DELETED .fossil-settings/binary-glob Index: .fossil-settings/binary-glob ================================================================== --- .fossil-settings/binary-glob +++ .fossil-settings/binary-glob @@ -1,5 +0,0 @@ -*.tiff *.png *.jpg *.JPG *.JPG.thumb -*.fossil *.sqlite *.ckout *.global -*.torrent -*.pdf -*/yencode.test.data */yencode.test.out DELETED .fossil-settings/crlf-glob Index: .fossil-settings/crlf-glob ================================================================== --- .fossil-settings/crlf-glob +++ .fossil-settings/crlf-glob @@ -1,3 +0,0 @@ -modules/pt/tests/data/ok/peg_serial-canonical/3_peg_itself -modules/fumagic/fumagic.testsupport -*.bat DELETED .fossil-settings/encoding-glob Index: .fossil-settings/encoding-glob ================================================================== --- .fossil-settings/encoding-glob +++ .fossil-settings/encoding-glob @@ -1,4 +0,0 @@ -modules/mime/mime.test -modules/base64/yencode.test.out -modules/fileutil/test-assets/pdf4tcl_01.pdf -modules/png/test-assets/xlfn0g04.png DELETED .fossil-settings/ignore-glob Index: .fossil-settings/ignore-glob ================================================================== --- .fossil-settings/ignore-glob +++ .fossil-settings/ignore-glob @@ -1,5 +0,0 @@ -M -MSG* -X.* -_work -modules/tcllibc Index: .github/CONTRIBUTING.md ================================================================== --- .github/CONTRIBUTING.md +++ .github/CONTRIBUTING.md @@ -1,17 +1,17 @@ -Hello. __Attention please__ +Hello. You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where Tcllib development takes place. +This is __not__ the location where development takes place. -We are __not tracking issues entered here__. With the exception of the +We are not tracking issues entered here. With the exception of the maintainer of the mirroring setup nobody will even see such issues. Please go to the -[official location of the sources](https://core.tcl-lang.org/tcllib) +[official location of the sources](https://core.tcl.tk/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) +[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) instead. Thank you for your consideration. Index: .github/ISSUE_TEMPLATE.md ================================================================== --- .github/ISSUE_TEMPLATE.md +++ .github/ISSUE_TEMPLATE.md @@ -1,17 +1,17 @@ -Hello. __Attention please__ +Hello. You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where Tcllib development takes place. +This is __not__ the location where development takes place. -We are __not tracking issues entered here__. With the exception of the +We are not tracking issues entered here. With the exception of the maintainer of the mirroring setup nobody will even see such issues. Please go to the -[official location of the sources](https://core.tcl-lang.org/tcllib) +[official location of the sources](https://core.tcl.tk/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) +[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) instead. Thank you for your consideration. Index: .github/PULL_REQUEST_TEMPLATE.md ================================================================== --- .github/PULL_REQUEST_TEMPLATE.md +++ .github/PULL_REQUEST_TEMPLATE.md @@ -1,17 +1,17 @@ -Hello. __Attention please__ +Hello. You are currently using the github __mirror__ of the Tcllib sources. -This is __not__ the location where Tcllib development takes place. +This is __not__ the location where development takes place. -We are __not tracking issues entered here__. With the exception of the +We are not tracking issues entered here. With the exception of the maintainer of the mirroring setup nobody will even see such issues. Please go to the -[official location of the sources](https://core.tcl-lang.org/tcllib) +[official location of the sources](https://core.tcl.tk/tcllib) and enter your ticket into the -[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) +[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) instead. Thank you for your consideration. Index: DESCRIPTION.txt ================================================================== --- DESCRIPTION.txt +++ DESCRIPTION.txt @@ -2,11 +2,11 @@ Title: Tcl Standard Library Description: This package is intended to be a collection of Tcl packages that provide utility functions useful to a large collection of Tcl programmers. Rights: BSD -Version: 1.20 +Version: 1.18 URL: http://core.tcl.tk/tcllib Architecture: tcl Contributor: Contributor: Aaron Faupell Contributor: Andreas Kupries @@ -23,11 +23,10 @@ Contributor: Elchonon Edelson Contributor: Emmanuel Frecon Contributor: Eric Melski Contributor: Gerald Lester Contributor: Gerhard Reithofer -Contributor: Harald Oehlmann Contributor: Jeff Hobbs Contributor: Joe English Contributor: Johannes-Heinrich Vogeler Contributor: KATO Kanryu Contributor: Kevin B, Kenny ADDED INSTALL.txt Index: INSTALL.txt ================================================================== --- INSTALL.txt +++ INSTALL.txt @@ -0,0 +1,77 @@ +How to install Tcllib +===================== + +Introduction +------------ + +The tcllib distribution, whether a snapshot directly from CVS, or +officially released, offers a single method for installing tcllib, +based on Tcl itself. + +This is based on the assumption that for tcllib to be of use Tcl has +to be present, and therefore can be used. + +This single method however can be used in a variety of ways. + +0 For an unwrapped (= directory) distribution or CVS snapshot + + a. either call the application 'installer.tcl' directly, + b or use + + % configure ; make install + + The latter is provided for people which are used to + this method and more comfortable with it. In end this + boils down into a call of 'installer.tcl' too. + +1. A starpack distribution (window-only) is a self-extracting + installer which internally uses the aforementioned installer. + +2. A starkit distribution is very much like a starpack, but + required an external interpreyter to run. This can be any tcl + interpreter which has all the packages to support starkits + (tclvfs, memchan, trf). + +3. A distribution in a tarball has to be unpacked first, then any + of the methods described in (0) can be used. + + +Usage of the installer +---------------------- + +The installer selects automatically either a gui based mode, or a +command line based mode. If the package Tk is present and can be +loaded, then the GUI mode is entered, else the system falls back to +the command line. + +Note that it is possible to specify options on the command line even +if the installer ultimatively selects a gui mode. In that case the +hardwired defaults and the options determine the data presented to the +user for editing. + +Command line help can be asked for by using the option -help when +running the installer (3) or the distribution itself in the case of +(1) or (2). + +The installer will select a number of defaults for the locations of +packages, examples, and documentation, and also the format of the +documentation. The user can overide these defaults in the GUI, or by +specifying additional options. + +The defaults depend on the platform detected (unix/windows) and the +executable used to run the installer. In the case of a starpack +distribution (1) this means that _no defaults_ are possible for the +various locations as the executable is part of the distribution and +has no knowledge of its environment. + +In all other cases the intepreter executable is outside of the +distribution, which means that its location can be used to determine +sensible defaults. + +Notes +----- + +The installer will overwrite an existing installation of tcllib 1.6 +without asking back after the initial confirmation is given. And if +the user chooses the same directory as for tcllib 1.4, or 1.3, etc. +then the installer will overwrite that too. ADDED README Index: README ================================================================== --- README +++ README @@ -0,0 +1,96 @@ +RCS: @(#) $Id: README,v 1.9 2007/08/30 17:24:13 andreas_kupries Exp $ + +Welcome to the Tcllib, the Tcl Standard Library. This package is +intended to be a collection of Tcl packages that provide utility +functions useful to a large collection of Tcl programmers. + +The home web site for this code is http://core.tcl.tk/tcllib/ . +At this web site, you will find mailing lists, web forums, databases +for bug reports and feature requests, the CVS repository (browsable on +the web, or read-only accessible via CVS ), and more. + +The structure of the tcllib source hierarchy is: + +tcllib + +- modules + +- + +- + +- ... + + +The install hierarchy is: + +.../lib/tcllib + +- + +- + +- ... + +There are some base requirements that a module must meet before it +will be added to tcllib: + +* the module must be a proper Tcl package +* the module must use a namespace for its commands and variables +* the name of the package must be the same as the name of the + namespace +* the module must reside in a subdirectory of the modules directory in + the source hierarchy, and that subdirectory must have the same name + as the package and namespace +* the module must be released under the BSD License, the terms of + which can be found in the toplevel tcllib source directory in the file + license.terms +* the module should have both documentation ([*]) and a test suite + (in the form of a group of *.test files in the module directory). + + [*] Possible forms: doctools, TMML/XML, nroff (man), or HTML. + The first format is the most preferred as it can be processed with + tools provided by tcllib itself (See module doctools). The first + two are preferred in general as they are semantic markup and thus + easier to convert into other formats. + +* the module must have either documentation or a test suite. It can + not have neither. +* the module should adhere to Tcl coding standards + +When adding a module to tcllib, be sure to add it to the files listed below. + +* installed_modules.tcl + + contains a table listing all modules to be installed, modules + excluded, and names the actions to be taken during installation + of each module. Add a line to this table naming your module and + its actions. + + Three actions have to be specified, for the package itself, its + documentation, and the examples demonstrating it. + + The _null action can be used everywhere and signals that there is + nothing to do. Although it is possible to use it for the package + action it does make no sense there, as that means that no package + code is installed. + + Other package actions are _tcl, _tci, and _text. The first causes + the installer to copy all .tcl files from the source directory for + the module into the appropriate module directory. _tci does all that + and also expects a tclIndex file to copy. _tex is like _tcl, however + it also copies all .tex files found in the source directory for the + module. + + There is currently only one true documentation action. This action + is _doc. It converts all documentation in doctools format into the + format chosen by the user for installation and copies the result + into the appropriate directory. + + There is currently one true action for examples, _exa. It copies all + files in the source directory for examples into the directory chosen + by the user as destination for examples. + +Each module source directory should have no subdirectories (other than +the CVS directory), and should contain the following files: + +* source code *.tcl +* package index pkgIndex.tcl +* tests *.test +* documentation *.man, *.n, *.xml + +If you do not follow this directory structure, the tcllib Makefile +will fail to locate the files from the new module. ADDED README.developer Index: README.developer ================================================================== --- README.developer +++ README.developer @@ -0,0 +1,396 @@ +RCS: @(#) $Id: README.developer,v 1.6 2009/06/02 22:49:55 andreas_kupries Exp $ + +Welcome to the tcllib, the Tcl Standard Library. +================================================ + +Introduction +------------ + +This README is intended to be a guide to the tools available to a + + Developer + +working on Tcllib to help him with his tasks, i.e. making the tasks easier +to perform. It is our hope that this will improve the quality of even +non-released revisions of Tcllib, and make the work of the release +manager easier as well. + +Audience +-------- + +The intended audience are, first and foremost, developers beginning to +work on Tcllib. To an experienced developer this document will be less +of a guide and more of a reference. Anybody else interested in working +on Tcllib is invited as well. + + +Directory hierarchy and file basics +------------------------------------ + +The main directories under the tcllib top directory are + + modules/ + examples/ +and apps/ + +Each directory FOO under modules/ represents one package, sometimes +more. In the case of the latter the packages are usually related in +some way. Examples are the base64, math, and struct modules, with +loose (base64) to strong (math) relations between the packages. + +Examples associated with a module FOO, if there are any, are placed +into the directory + + examples/FOO + +Any type of distributable application can be found under apps/, +together with their documentation, if any. Note that the apps/ +directory is currently not split into sub-directories. + +Regarding the files in Tcllib, the most common types found are + + .tcl Tcl code for a package. + + .man Documentation for a package, in doctools format. + + .test Test suite for a package, or part of. Based on tcltest. + + .bench Performance benchmarks for a package, or part of. + Based on modules/bench + + .pcx Syntax rules for TclDevKit's tclchecker. Using these + rules allows tclchecker to check the use of commands + of a Tcllib package X without having to scan the + implementation of X, i.e. its .tcl files. + + +Adding a new module +------------------- + +Assuming that FOO is the name of the new module, and T is the toplevel +directory of the Tcllib sources + +(1) Create the directory T/modules/FOO and put all the files of + the module into it. Note: + + * The file 'pkgIndex.tcl' is required. + + * Implementation files should have the extension '.tcl', + naturally. + + * If available, documentation should be in doctools format, + and the files should have the extension '.man' for SAK to + recognize them. + + * If available the testsuite(s) should use 'tcltest' and the + general format as used by the other modules in Tcllib + (declaration of minimally needed Tcl, tcltest, supporting + packages, etc.). The file(s) should have the extension + '.test' for SAK to recognize them. + + Note that an empty testsuite, or a testsuite which does not + perform any tests is less than useful and will not be + accepted. + + * If available the benchmark(s) should use 'bench' and the + general format as used by the other modules in Tcllib. The + file(s) should have the extension '.bench' for SAK to + recognize them. + + * Other files can be named and placed as the module sees fit. + +(2) If the new module has an example application A which is + polished enough for general use, put this application into the + file "T/apps/A.tcl", and its documentation into the file + "T/apps/A.man". While documentation for the application is + optional, it is preferred. + + For examples which are not full-fledged applications, a + skeleton, or not really polished for use, etc., create the + directory T/examples/FOO/ and put them there. + + A key difference is what happens to them on installation, and + what the target audience is. + + The examples are for developers using packages in Tcllib, + whereas the applications are also for users of Tcllib which do + not have an interest in developing for and with it. As such, + they are installed as regular commands, accessible through the + PATH, and example files are not installed. + +(3) To make Tcllib's installer aware of FOO, edit the file + + T/support/installation/modules.tcl + + Add a line 'Module FOO $impaction $docaction $exaction'. The + various actions describe to the installer how to install the + implementation files, the documentation, and the examples. + + Add a line 'Application A' for any application A which was + added to T/apps for FOO. + + The following actions are available: + + Implementation + + _tcl - Copy all .tcl files in T/modules/FOO into the installation. + _tcr - See above, does it for .tcl files in subdirectories as well. + _tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'. + _msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'. + _doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'. + _tex - _tcl + Copying of .tex files - special to module 'textutil'. + + The _null action, see below, is available in principle + too, but a module without implementation does not make + sense. + + Documentation + + _null - Module has no documentation, do nothing. + _man - Process the .man files in T/modules/FOO and + install the results (nroff and/or HTML) in the + proper location, as given to the installer. + + Examples + + _null - Module has no examples, do nothing + _exa - Copy the directory T/examples/FOO + (recursively) to the install location for + examples. + + +Testing modules +--------------- + +To run the testsuite of a module FOO in tcllib use the 'test run' +argument of sak.tcl, like so: + + % pwd + /the/tcllib/toplevel/directory + + % ./sak.tcl test run FOO +or % ./sak.tcl test run modules/FOO + +To run the testsuites of all modules either invoke 'test run' without a +module name, or use 'make test'. The latter assumes that configure was +run for Tcllib before, i.e.: + + % ./sak.tcl test run +or % ./sak.tcl test run + % make test + +In all of the above cases the result will be a combination of progress +display and testsuite log, showing for each module the tests that pass +or failed and how many of each in a summary at the end. + +To get a detailed log, it is necessary to invoke 'test run' with +additional options. + +First example: + % ./sak.tcl test run -l LOG FOO + +This shows the same short log on the terminal, and writes a detailed +log to the file LOG.log, and excerpts to other files (LOG.summary, +LOG.failures, etc.). + +Second example: + % ./sak.tcl test run -v FOO + % make test > LOG + +This writes the detailed log to stdout, or to the file LOG, instead of +the short log. In all cases, the detailed log contains a list of all +test cases executed, which failed, and how they failed (expected +versus actual results). + +Note: +The commands + % make test +and % make test > LOG + +are able to generate different output (short vs long log) because the +Makefile target contains code which detects that stdout has been +redirected to a file and acts accordingly. + +Non-developers should reports problems in Tcllib's bug tracker. +Information about its location and the relevant category can be found +in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module +and/or package. + +Module documentation +-------------------- + +The main format used for the documentation of packages in Tcllib is +'doctools', the support packages of which are part of Tcllib, see the +module 'doctools'. + +To convert this documentation to HTML or nroff manpages, or some other +format use the 'doc' argument of sak.tcl, like so: + + % pwd + /the/tcllib/toplevel/directory + + % ./sak.tcl doc html FOO +or % ./sak.tcl doc html modules/FOO + +The result of the conversion can be found in the newly-created 'doc' +directory in the current working directory. + +The set of formats the documentation can be converted into can be +queried via + + % ./sak.tcl help doc + + +To convert the documentation of all modules either invoke 'test run' +without a module name, or use 'make html-doc', etc.. The latter +assumes that configure was run for Tcllib before, i.e.: + + % ./sak.tcl doc html + % make html-doc + +Note the special format 'validate'. Using this format does not convert +the documentation to anything (and the sub-directory 'doc' will not be +created), it just checks that the documentation is syntactically +correct. I.e. + + % ./sak.tcldoc validate modules/FOO + % ./sak.tcldoc validate + + +Validating modules +------------------ + +Running the testsuite of a module, or checking the syntax of its +documentation (see the previous sections) are two forms of validation. + +The 'validate' command of sak.tcl provides a few more. The online +documentation of this command is available via + + % ./sak.tcl help validate + +The validated parts are man pages, testsuites, version information, +and syntax. The latter only if various static syntax checkers are +available on the PATH, like TclDevKit's tclchecker. + +Note that testsuite validation is not the execution of the testsuites, +only if a package has a testsuite or not. + +It is strongly recommended to validate a module before committing any +type of change made to it. + +It is recommended to validate all modules before committing any type +of change made to one of them. We have package inter-dependencies +between packages in Tcllib, thus changing one package may break +others, and just validating the changed package will not catch such +problems. + + +Writing Tests +------------- + +While a previous section talked about running the testsuite for a +module and the packages therein this has no meaning if the module in +question has no testsuites at all. + +This section gives a very basic overview on methodologies for writing +tests and testsuites. + +First there are "drudgery" tests. Written to check absolutely basic +assumptions which should never fail. + +Example: + + For a command FOO taking two arguments, three tests calling it + with zero, one, and three arguments. The basic checks that the + command fails if it has not enough arguments, or too many. + +After that come the tests checking things based on our knowledge of +the command, about its properties and assumptions. Some examples based +on the graph operations added during Google's Summer of Code 2009. + +** The BellmanFord command in struct::graph::ops takes a + _startnode_ as argument, and this node should be a node of the + graph. equals one test case checking the behavior when the + specified node is not a node a graph. + + This often gives rise to code in the implementation which + explicitly checks the assumption and throws a nice error. + Instead of letting the algorithm fails later in some weird + non-deterministic way. + + Such checks cannot be done always. The graph argument for + example is just a command in itself, and while we expect it to + exhibit a certain interface, i.e. set of sub-commands aka + methods, we cannot check that it has them, except by actually + trying to use them. That is done by the algorithm anyway, so + an explicit check is just overhead we can get by without. + +** IIRC one of the distinguishing characteristic of either + BellmanFord and/or Johnson is that they are able to handle + negative weights. Whereas Dijkstra requires positive weights. + + This induces (at least) three testcases ... Graph with all + positive weights, all negative, and a mix of positive and + negative weights. + + Thinking further does the algorithm handle the weight '0' as + well ? Another test case, or several, if we mix zero with + positive and negative weights. + +** The two algorithms we are currently thinking about are about + distances between nodes, and distance can be 'Inf'inity, + i.e. nodes may not be connected. This means that good test + cases are + + (1) Strongly connected graph + (2) Connected graph + (3) Disconnected graph. + + At the extremes of (1) and (3) we have the fully connected + graphs and graphs without edges, only nodes, i.e. completely + disconnected. + +** IIRC both of the algorithms take weighted arcs, and fill in a + default if arcs are left unweighted in the input graph. + + This also induces three test cases: + + (1) Graph will all arcs with explicit weights. + (2) Graph without weights at all. + (3) Graph with mixture of weighted and unweighted graphs. + + +What was described above via examples is called 'black-box' testing. +Test cases are designed and written based on our knowledge of the +properties of the algorithm and its inputs, without referencing a +particular implementation. + +Going further, a complement to 'black-box' testing is 'white-box'. For +this we know the implementation of the algorithm, we look at it and +design our tests cases so that they force the code through all +possible paths in the implementation. Wherever a decision is made we +have a test cases forcing a specific direction of the decision, for +all possible directions. + +In practice I often hope that the black-box tests I have made are +enough to cover all the paths, obviating the need for white-box tests. + +So, if you, dear reader, now believe that writing tests for an +algorithm takes at least as much time as coding the algorithm, and +often more time, then you are completely right. It does. Much more +time. See for example also http://sqlite.org/testing.html, a writeup +on how the Sqlite database engine is tested. + + + +An interesting connection is to documentation. In one direction, the +properties you are checking with black-box testing are properties +which should be documented in the algorithm man page. And conversely, +if you have documentation of properties of an algorithm then this is a +good reference to base black-box tests on. + +In practice test cases and documentation often get written together, +cross-influencing each other. And the actual writing of test cases is +a mix of black and white box, possibly influencing the implementation +while writing the tests. Like writing test for 'startnode not in input +graph' serving as reminder to put in a check for this into the code. Index: README.md ================================================================== --- README.md +++ README.md @@ -1,44 +1,17 @@ -# Attention - -:warning: -This repository is mirrored to [github](https://github.com/tcltk/tcllib). - -We are __not tracking issues at github__. With the exeception of the -maintainer of the mirroring setup nobody will even see issues created -at github. + +Hello. + +If you are reading this then you are very likely at the github +__mirror__ of the Tcllib sources. + +This means that the +[official location of the sources](https://core.tcl.tk/tcllib) +is somewhere else, just follow the link. + +This is also where our issue tracking is done. We are not tracking +issues at github. With the exeception of the maintainer of the +mirroring setup nobody will even see issues created at github. Please use the -[official ticket tracker](https://core.tcl-lang.org/tcllib/reportlist) +[official ticket tracker](https://core.tcl.tk/tcllib/reportlist) instead. - -# Welcome - -Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl packages -that provide utility functions useful to a large collection of Tcl -programmers. - -At our [home site](http://core.tcl-lang.org/tcllib) you will find the -official fossil repository used to manage our sources, together with -the bug tracker. This is also the main location for releases to -download from. - -We have a -[secondary download location](https://sourceforge.net/projects/tcllib/files) -where the Tcllib sources were hosted in the past. SourceForge is also -where our [mailing lists](https://sourceforge.net/p/tcllib/mailman) -are (still) hosted. - -Another location to find these sources at is the -[github mirror](https://github.com/tcltk/tcllib). - -Please note the :warning: at the top. - -# Guides To Tcllib - - * [Tcl Community - Kind Communication](embedded/www/tcllib/files/devdoc/tcl_community_communication.html) - * [License](embedded/www/tcllib/files/devdoc/tcllib_license.html) - * [How To Get The Sources](embedded/www/tcllib/files/devdoc/tcllib_sources.html) - * [How To Build And Install Tcllib](embedded/www/tcllib/files/devdoc/tcllib_installer.html) - * [The Developer's Guide](embedded/www/tcllib/files/devdoc/tcllib_devguide.html) - * [The Release Manager's Guide](embedded/www/tcllib/files/devdoc/tcllib_releasemgr.html) ADDED README.releasemgr Index: README.releasemgr ================================================================== --- README.releasemgr +++ README.releasemgr @@ -0,0 +1,65 @@ +RCS: @(#) $Id: README.releasemgr,v 1.2 2009/07/10 16:33:31 andreas_kupries Exp $ + +Welcome to the tcllib, the Tcl Standard Library. +================================================ + +Introduction +------------ + +This README is intended to be a guide to the tools available to a + + Release manager + +working on the creation of a release of Tcllib. + +Audience +-------- + +The intended audience is the release manager of Tcllib, his deputies, +and anybody else interested in the task. + +Basics +------ + +< Flesh this out > + + sak.tcl validate + sak.tcl test run + sak.tcl review + sak.tcl readme + sak.tcl localdoc + sak.tcl release (change to include rpmspec+gentip55+yml) + +< Tasks, and how to perform them > + + Making a release (candidate) branch. + Readying the release in the branch. + Make the release official, merging the branch back. + +Uploading and releasing files +-------------------------------------------- + +(1) Create a proper fossil event for the release, via + + http://core.tcl.tk/tcllib/eventedit + + See existing events (*) for a template + + (Ad *) http://core.tcl.tk/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 + +(2) Update the following web locations + + (a) Home page: http://core.tcl.tk/tcllib/home + (b) Downloads: http://core.tcl.tk/tcllib/wiki?name=Downloads + (c) Past Releases: http://core.tcl.tk/tcllib/wiki?name=Past+Releases + + Admin access to the fossil repository required + + (d) http://www.tcl.tk/home/release.txt + (e) http://www.tcl.tk/software/tcllib/*.tml + + ssh access to tcl.activestate.com + aka www.tcl.tk + required. + + (f) http://wiki.tcl.tk/1246 Index: apps/dtplite.man ================================================================== --- apps/dtplite.man +++ apps/dtplite.man @@ -441,7 +441,7 @@ of doctoc and docidx markup. [list_end] [vset CATEGORY doctools] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] Index: apps/nns.man ================================================================== --- apps/nns.man +++ apps/nns.man @@ -137,7 +137,7 @@ requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] Index: apps/nnsd.man ================================================================== --- apps/nnsd.man +++ apps/nnsd.man @@ -85,7 +85,7 @@ specifies the TCP port the server has to listen on for requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] Index: apps/nnslog.man ================================================================== --- apps/nnslog.man +++ apps/nnslog.man @@ -87,7 +87,7 @@ requests. [list_end] [vset CATEGORY nameserv] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] Index: apps/page.man ================================================================== --- apps/page.man +++ apps/page.man @@ -461,7 +461,7 @@ The contents of both environment variables and registry entries are interpreted as a list of paths, with the elements separated by either colon (Unix), or semicolon (Windows). [vset CATEGORY page] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] Index: apps/tcldocstrip.man ================================================================== --- apps/tcldocstrip.man +++ apps/tcldocstrip.man @@ -191,7 +191,7 @@ written after the actual content of a generated file. [list_end] [vset CATEGORY docstrip] -[include ../modules/common-text/feedback.inc] +[include ../modules/doctools2base/include/feedback.inc] [manpage_end] DELETED devdoc/README.developer Index: devdoc/README.developer ================================================================== --- devdoc/README.developer +++ devdoc/README.developer @@ -1,396 +0,0 @@ -RCS: @(#) $Id: README.developer,v 1.6 2009/06/02 22:49:55 andreas_kupries Exp $ - -Welcome to the tcllib, the Tcl Standard Library. -================================================ - -Introduction ------------- - -This README is intended to be a guide to the tools available to a - - Developer - -working on Tcllib to help him with his tasks, i.e. making the tasks easier -to perform. It is our hope that this will improve the quality of even -non-released revisions of Tcllib, and make the work of the release -manager easier as well. - -Audience --------- - -The intended audience are, first and foremost, developers beginning to -work on Tcllib. To an experienced developer this document will be less -of a guide and more of a reference. Anybody else interested in working -on Tcllib is invited as well. - - -Directory hierarchy and file basics ------------------------------------- - -The main directories under the tcllib top directory are - - modules/ - examples/ -and apps/ - -Each directory FOO under modules/ represents one package, sometimes -more. In the case of the latter the packages are usually related in -some way. Examples are the base64, math, and struct modules, with -loose (base64) to strong (math) relations between the packages. - -Examples associated with a module FOO, if there are any, are placed -into the directory - - examples/FOO - -Any type of distributable application can be found under apps/, -together with their documentation, if any. Note that the apps/ -directory is currently not split into sub-directories. - -Regarding the files in Tcllib, the most common types found are - - .tcl Tcl code for a package. - - .man Documentation for a package, in doctools format. - - .test Test suite for a package, or part of. Based on tcltest. - - .bench Performance benchmarks for a package, or part of. - Based on modules/bench - - .pcx Syntax rules for TclDevKit's tclchecker. Using these - rules allows tclchecker to check the use of commands - of a Tcllib package X without having to scan the - implementation of X, i.e. its .tcl files. - - -Adding a new module -------------------- - -Assuming that FOO is the name of the new module, and T is the toplevel -directory of the Tcllib sources - -(1) Create the directory T/modules/FOO and put all the files of - the module into it. Note: - - * The file 'pkgIndex.tcl' is required. - - * Implementation files should have the extension '.tcl', - naturally. - - * If available, documentation should be in doctools format, - and the files should have the extension '.man' for SAK to - recognize them. - - * If available the testsuite(s) should use 'tcltest' and the - general format as used by the other modules in Tcllib - (declaration of minimally needed Tcl, tcltest, supporting - packages, etc.). The file(s) should have the extension - '.test' for SAK to recognize them. - - Note that an empty testsuite, or a testsuite which does not - perform any tests is less than useful and will not be - accepted. - - * If available the benchmark(s) should use 'bench' and the - general format as used by the other modules in Tcllib. The - file(s) should have the extension '.bench' for SAK to - recognize them. - - * Other files can be named and placed as the module sees fit. - -(2) If the new module has an example application A which is - polished enough for general use, put this application into the - file "T/apps/A.tcl", and its documentation into the file - "T/apps/A.man". While documentation for the application is - optional, it is preferred. - - For examples which are not full-fledged applications, a - skeleton, or not really polished for use, etc., create the - directory T/examples/FOO/ and put them there. - - A key difference is what happens to them on installation, and - what the target audience is. - - The examples are for developers using packages in Tcllib, - whereas the applications are also for users of Tcllib which do - not have an interest in developing for and with it. As such, - they are installed as regular commands, accessible through the - PATH, and example files are not installed. - -(3) To make Tcllib's installer aware of FOO, edit the file - - T/support/installation/modules.tcl - - Add a line 'Module FOO $impaction $docaction $exaction'. The - various actions describe to the installer how to install the - implementation files, the documentation, and the examples. - - Add a line 'Application A' for any application A which was - added to T/apps for FOO. - - The following actions are available: - - Implementation - - _tcl - Copy all .tcl files in T/modules/FOO into the installation. - _tcr - See above, does it for .tcl files in subdirectories as well. - _tci - _tcl + Copying of a tclIndex - special to modules 'math', 'control'. - _msg - _tcl + Copying of subdir 'msgs' - special to modules 'dns', 'log'. - _doc - _tcl + Copying of subdir 'mpformats' - special to module 'doctools'. - _tex - _tcl + Copying of .tex files - special to module 'textutil'. - - The _null action, see below, is available in principle - too, but a module without implementation does not make - sense. - - Documentation - - _null - Module has no documentation, do nothing. - _man - Process the .man files in T/modules/FOO and - install the results (nroff and/or HTML) in the - proper location, as given to the installer. - - Examples - - _null - Module has no examples, do nothing - _exa - Copy the directory T/examples/FOO - (recursively) to the install location for - examples. - - -Testing modules ---------------- - -To run the testsuite of a module FOO in tcllib use the 'test run' -argument of sak.tcl, like so: - - % pwd - /the/tcllib/toplevel/directory - - % ./sak.tcl test run FOO -or % ./sak.tcl test run modules/FOO - -To run the testsuites of all modules either invoke 'test run' without a -module name, or use 'make test'. The latter assumes that configure was -run for Tcllib before, i.e.: - - % ./sak.tcl test run -or % ./sak.tcl test run - % make test - -In all of the above cases the result will be a combination of progress -display and testsuite log, showing for each module the tests that pass -or failed and how many of each in a summary at the end. - -To get a detailed log, it is necessary to invoke 'test run' with -additional options. - -First example: - % ./sak.tcl test run -l LOG FOO - -This shows the same short log on the terminal, and writes a detailed -log to the file LOG.log, and excerpts to other files (LOG.summary, -LOG.failures, etc.). - -Second example: - % ./sak.tcl test run -v FOO - % make test > LOG - -This writes the detailed log to stdout, or to the file LOG, instead of -the short log. In all cases, the detailed log contains a list of all -test cases executed, which failed, and how they failed (expected -versus actual results). - -Note: -The commands - % make test -and % make test > LOG - -are able to generate different output (short vs long log) because the -Makefile target contains code which detects that stdout has been -redirected to a file and acts accordingly. - -Non-developers should reports problems in Tcllib's bug tracker. -Information about its location and the relevant category can be found -in the section 'BUGS, IDEAS, FEEDBACK' of the manpage of the module -and/or package. - -Module documentation --------------------- - -The main format used for the documentation of packages in Tcllib is -'doctools', the support packages of which are part of Tcllib, see the -module 'doctools'. - -To convert this documentation to HTML or nroff manpages, or some other -format use the 'doc' argument of sak.tcl, like so: - - % pwd - /the/tcllib/toplevel/directory - - % ./sak.tcl doc html FOO -or % ./sak.tcl doc html modules/FOO - -The result of the conversion can be found in the newly-created 'doc' -directory in the current working directory. - -The set of formats the documentation can be converted into can be -queried via - - % ./sak.tcl help doc - - -To convert the documentation of all modules either invoke 'test run' -without a module name, or use 'make html-doc', etc.. The latter -assumes that configure was run for Tcllib before, i.e.: - - % ./sak.tcl doc html - % make html-doc - -Note the special format 'validate'. Using this format does not convert -the documentation to anything (and the sub-directory 'doc' will not be -created), it just checks that the documentation is syntactically -correct. I.e. - - % ./sak.tcldoc validate modules/FOO - % ./sak.tcldoc validate - - -Validating modules ------------------- - -Running the testsuite of a module, or checking the syntax of its -documentation (see the previous sections) are two forms of validation. - -The 'validate' command of sak.tcl provides a few more. The online -documentation of this command is available via - - % ./sak.tcl help validate - -The validated parts are man pages, testsuites, version information, -and syntax. The latter only if various static syntax checkers are -available on the PATH, like TclDevKit's tclchecker. - -Note that testsuite validation is not the execution of the testsuites, -only if a package has a testsuite or not. - -It is strongly recommended to validate a module before committing any -type of change made to it. - -It is recommended to validate all modules before committing any type -of change made to one of them. We have package inter-dependencies -between packages in Tcllib, thus changing one package may break -others, and just validating the changed package will not catch such -problems. - - -Writing Tests -------------- - -While a previous section talked about running the testsuite for a -module and the packages therein this has no meaning if the module in -question has no testsuites at all. - -This section gives a very basic overview on methodologies for writing -tests and testsuites. - -First there are "drudgery" tests. Written to check absolutely basic -assumptions which should never fail. - -Example: - - For a command FOO taking two arguments, three tests calling it - with zero, one, and three arguments. The basic checks that the - command fails if it has not enough arguments, or too many. - -After that come the tests checking things based on our knowledge of -the command, about its properties and assumptions. Some examples based -on the graph operations added during Google's Summer of Code 2009. - -** The BellmanFord command in struct::graph::ops takes a - _startnode_ as argument, and this node should be a node of the - graph. equals one test case checking the behavior when the - specified node is not a node a graph. - - This often gives rise to code in the implementation which - explicitly checks the assumption and throws a nice error. - Instead of letting the algorithm fails later in some weird - non-deterministic way. - - Such checks cannot be done always. The graph argument for - example is just a command in itself, and while we expect it to - exhibit a certain interface, i.e. set of sub-commands aka - methods, we cannot check that it has them, except by actually - trying to use them. That is done by the algorithm anyway, so - an explicit check is just overhead we can get by without. - -** IIRC one of the distinguishing characteristic of either - BellmanFord and/or Johnson is that they are able to handle - negative weights. Whereas Dijkstra requires positive weights. - - This induces (at least) three testcases ... Graph with all - positive weights, all negative, and a mix of positive and - negative weights. - - Thinking further does the algorithm handle the weight '0' as - well ? Another test case, or several, if we mix zero with - positive and negative weights. - -** The two algorithms we are currently thinking about are about - distances between nodes, and distance can be 'Inf'inity, - i.e. nodes may not be connected. This means that good test - cases are - - (1) Strongly connected graph - (2) Connected graph - (3) Disconnected graph. - - At the extremes of (1) and (3) we have the fully connected - graphs and graphs without edges, only nodes, i.e. completely - disconnected. - -** IIRC both of the algorithms take weighted arcs, and fill in a - default if arcs are left unweighted in the input graph. - - This also induces three test cases: - - (1) Graph will all arcs with explicit weights. - (2) Graph without weights at all. - (3) Graph with mixture of weighted and unweighted graphs. - - -What was described above via examples is called 'black-box' testing. -Test cases are designed and written based on our knowledge of the -properties of the algorithm and its inputs, without referencing a -particular implementation. - -Going further, a complement to 'black-box' testing is 'white-box'. For -this we know the implementation of the algorithm, we look at it and -design our tests cases so that they force the code through all -possible paths in the implementation. Wherever a decision is made we -have a test cases forcing a specific direction of the decision, for -all possible directions. - -In practice I often hope that the black-box tests I have made are -enough to cover all the paths, obviating the need for white-box tests. - -So, if you, dear reader, now believe that writing tests for an -algorithm takes at least as much time as coding the algorithm, and -often more time, then you are completely right. It does. Much more -time. See for example also http://sqlite.org/testing.html, a writeup -on how the Sqlite database engine is tested. - - - -An interesting connection is to documentation. In one direction, the -properties you are checking with black-box testing are properties -which should be documented in the algorithm man page. And conversely, -if you have documentation of properties of an algorithm then this is a -good reference to base black-box tests on. - -In practice test cases and documentation often get written together, -cross-influencing each other. And the actual writing of test cases is -a mix of black and white box, possibly influencing the implementation -while writing the tests. Like writing test for 'startnode not in input -graph' serving as reminder to put in a check for this into the code. ADDED devdoc/cvs.branches.fig Index: devdoc/cvs.branches.fig ================================================================== --- devdoc/cvs.branches.fig +++ devdoc/cvs.branches.fig @@ -0,0 +1,32 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 3000 2025 5400 2400 +4 0 12 50 0 0 14 0.0000 4 150 2385 3000 2175 Point releases are branched\001 +4 0 12 50 0 0 14 0.0000 4 150 1530 3000 2370 from RELEASES\001 +-6 +6 2400 750 5700 1200 +4 0 1 50 0 0 14 0.0000 4 195 3225 2400 900 Developer performs internal releases,\001 +4 0 1 50 0 0 14 0.0000 4 195 3285 2400 1095 merging from HEAD into RELEASES\001 +-6 +2 1 0 4 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 2 1 4.00 240.00 480.00 + 300 600 5700 600 +2 1 0 2 1 7 50 0 -1 0.000 0 0 -1 1 0 2 + 2 1 2.00 120.00 240.00 + 2100 600 2400 1800 +2 1 0 5 12 7 50 0 -1 0.000 0 0 -1 1 0 3 + 2 1 5.00 300.00 600.00 + 2700 1800 3000 3000 5700 3000 +2 1 0 4 17 7 50 0 -1 0.000 0 0 7 1 0 3 + 2 1 4.00 240.00 480.00 + 1200 600 1500 1800 5700 1800 +4 0 0 50 0 0 14 0.0000 4 195 2835 3150 1575 Staging for release : RELEASES\001 +4 0 0 50 0 0 14 0.0000 4 195 1905 3900 300 Development : HEAD\001 +4 0 0 50 0 0 14 0.0000 4 150 930 4800 2700 Tcllib 1.2.0\001 ADDED devdoc/devguide.html Index: devdoc/devguide.html ================================================================== --- devdoc/devguide.html +++ devdoc/devguide.html @@ -0,0 +1,50 @@ + + +

Guide for Tcllib developers. +

+
+ +

CVS Repository +

+
+ + +

+ +The CVS repository for Tcllib contains two main branches, the HEAD for +development, and RELEASES as the staging area for official +releases. At RELEASES the minor branches containing the various +official releases are anchored at. +

+ +

All the branches are of interest to the developers for + Tcllib. Ongoing development happens in HEAD, which can be + unstable or may not work at all. Whenever a developer considers + a piece of code, or module, he is responsible for as + sufficiently stable she has to perform an internal release which + merges this part from HEAD into RELEASES. Tools to help with + this will be provided. +

+ +

The branches for the official releases of tcllib are of interest to + a developer because it is expected that fixes for important bugs + not only go into the HEAD branch but also into the release + branches for the release they were found in and all releases + following that one. This is to allow the release manager to + create patch releases of existing releases distributing important + bugfixes as well. +

+ +

Version numbers for modules are handled as described below. This + way of handling them was chosen so that the modules in the + development branch always uses version numbers different from + the version numbers in the official releases made so far. +

+
    +
  • Whenever an internal release of a module FOO is done, the + developer performing this internal release has to increment + the version number of the module after the release was + executed. +
ADDED devdoc/installation.txt Index: devdoc/installation.txt ================================================================== --- devdoc/installation.txt +++ devdoc/installation.txt @@ -0,0 +1,85 @@ +Tcllib installation directory layout +==================================== + +This document describes the possible layouts for an installed tcllib, +discusses their pro and contra and makes a choice for Tcllib 1.4. A +roadmap of changes in the future is made available as appendix. + +[L1/D] Deep layout +------------------ + + This is the layout of Tcllib 1.3 (and versions before that). + + A single directory tcllib is created, and all + subdirectories of the 'modules' subdirectory in the + distribution is copied into it. This is restricted at large to + *.tcl files, with exception made for some modules with special + needs. + + Pro: + Contra: + Makes the handling of the various package indices, + well, not difficult, but uncomfortable. + + +[L2/Fa] Flat layout 1 +--------------------- + + A directory is created for each module of tcllib. + + Pro: + Handling of package indices is easier than for L1/D, a + toplevel index file with all its problems is not + required anymore. + + Contra: + Directories should be versioned to avoid conflicts + between multiple releases. modules have no + version. This can be faked for modules containing one + package, but not for the modules with more. + + +[L2/Fb] Flat layout 2 +--------------------- + + A directory is created for each package in tcllib. + + Pro + Handling of package indices is easy, one per package. + + Contra: + Modules containing more than one package are difficult + to handle. The system has to split them into the + individual packages. This rendered very difficult + because of shared package index files. + + This can be solved by moving tcllib (back) towards of + one package per module. When that goal is reached + L2/Fa and L2/Fb become the same, and the contra for + L2/Fa vanishes too as an exact version number can be + associated with each directory. + +Chosen layout for Tcllib 1.4 +---------------------------- + + L2/D + + Despite the problems with package indices the contras against + the flat structures are too strong at this point in + time. Automatic solutions are not really possible, or require + a very high effort. + +Roadmap +------- + Change the module directories of tcllib to contain exactly one + package per directory, with appropriate index (and meta data). + + This not only makes sense for easier handling of installation + and package indices, but also in the greater context of + wrapping code for deployment. + + +----------------------------------- +This document is in the public domain. + + Andreas Kupries DELETED devdoc/parts/b_critcl.inc Index: devdoc/parts/b_critcl.inc ================================================================== --- devdoc/parts/b_critcl.inc +++ devdoc/parts/b_critcl.inc @@ -1,39 +0,0 @@ - -While the majority of Tcllib consists of packages written in pure Tcl -a number of packages also have [term accelerators] associated with them. - -These are [syscmd critcl]-based C packages whose use will boost the -performance of the packages using them. - -These accelerators are optional, and they are not built by default. -If they are built according to the instructions below then they will -also be installed as well. - -[para] To build the accelerators the normally optional dependency on - [syscmd critcl] becomes required. - -[para] To build and install Tcllib with the accelerators in a - Unix-like environment invoke: - -[example { - ./configure - make critcl # Builds the shared library and package holding - # the accelerators, tcllibc - make install # Installs all packages, including the new tcllibc. -}] - -[para] The underlying tool is [file sak.tcl] in the toplevel directory -of Tcllib and the command [cmd {make critcl}] is just a wrapper around - -[example { - ./sak.tcl critcl -}] - -[para] Therefore in a Windows environment instead invoke - -[example { - ./sak.tcl critcl - ./installer.tcl -}] - -from within a DOS window, i.e. [syscmd cmd.exe]. DELETED devdoc/parts/b_tooling.inc Index: devdoc/parts/b_tooling.inc ================================================================== --- devdoc/parts/b_tooling.inc +++ devdoc/parts/b_tooling.inc @@ -1,109 +0,0 @@ - -The core of Tcllib's build system is the script [file installer.tcl] -found in the toplevel directory of a checkout or release. - -[para] The - [example { - configure ; make install - }] - setup available to - developers on Unix-like systems is just a wrapper around it. - - To go beyond the standard embodied in the wrapper it is - necessary to directly invoke this script. - -[para] On Windows system using it directly is the only way to invoke - it. - -[para] For basic help invoke it as - - [example { - ./installer.tcl -help - }] - - This will print a short list of all the available options to - the standard output channel. - -[para] The commands associated with the various [term install] targets - in the [term Makefile.in] for Unix can be used as additional - examples on how to use this tool as well. - -[para] The installer can operate in GUI and CLI modes. - - By default it chooses the mode automatically, based on if the - Tcl package [package Tk] can be used or not. - - The option [option -no-gui] can be used to force CLI mode. - -[para] Note that it is possible to specify options on the command line - even if the installer ultimatively selects GUI mode. In that - case the hardwired defaults and the options determine the data - presented to the user for editing. - -[para] The installer will select a number of defaults for the - locations of packages, examples, and documentation, and also - the format of the documentation. The user can overide these - defaults in the GUI, or by specifying additional options. - - The defaults depend on the platform detected (Unix/Windows) and - on the [syscmd tclsh] executable used to run the installer. - -[para][emph Options] - -[list_begin options] -[opt_def -help] - -Show the list of options explained here on the standard output channel -and exit. - -[opt_def +excluded] - -Include deprecated packages in the installation. - -[opt_def -no-gui] - -Force command line operation of the installer - -[opt_def -no-wait] - -In CLI mode the installer will by default ask the user to confirm that -the chosen configuration (destination paths, things to install) is -correct before performing any action. Using this option causes the -installer to skip this query and immediately jump to installation. - -[opt_def -app-path [arg path]] -[opt_def -example-path [arg path]] -[opt_def -html-path [arg path]] -[opt_def -nroff-path [arg path]] -[opt_def -pkg-path [arg path]] - -Declare the destination paths for the applications, examples, html -documentation, nroff manpages, and packages. The defaults are derived -from the location of the [syscmd tclsh] used to run the installer. - -[opt_def -dry-run] -[opt_def -simulate] - -Run the installer without modifying the destination directories. - -[opt_def -apps] -[opt_def -no-apps] -[opt_def -examples] -[opt_def -no-examples] -[opt_def -pkgs] -[opt_def -no-pkgs] -[opt_def -html] -[opt_def -no-html] -[opt_def -nroff] -[opt_def -no-nroff] - -(De)activate the installation of applications, examples, packages, -html documentation, and nroff manpages. - -[para] Applications, examples, and packages are installed by default. - -[para] On Windows the html documentation is installed by default. - -[para] On Unix the nroff manpages are installed by default. - -[list_end] DELETED devdoc/parts/b_unix.inc Index: devdoc/parts/b_unix.inc ================================================================== --- devdoc/parts/b_unix.inc +++ devdoc/parts/b_unix.inc @@ -1,22 +0,0 @@ - -For [term Unix]-like environments Tcllib comes with the standard set -of files to make - -[example { - ./configure - make install -}] - -a suitable way of installing it. - -This is a standard non-interactive install automatically figuring out -where to place everything, i.e. packages, applications, and the -manpages. - -[para] To get a graphical installer invoke - -[example { - ./installer.tcl -}] - -instead. DELETED devdoc/parts/b_windows.inc Index: devdoc/parts/b_windows.inc ================================================================== --- devdoc/parts/b_windows.inc +++ devdoc/parts/b_windows.inc @@ -1,18 +0,0 @@ - -In a Windows environment we have the [cmd installer.tcl] script to -perform installation. - -[para] If the desired [syscmd tclsh] is associated [file .tcl] files - then double-clicking / opening the [cmd installer.tcl] is - enough to invoke it in graphical mode. - - This assumes that [term Tk] is installed and available as well. - -[para] Without [term Tk] the only way to invoke the installer are to - open a DOS window, i.e. [syscmd cmd.exe], and then to invoke - -[example { - ./installer.tcl -}] - -inside it. DELETED devdoc/parts/d_bf_branchcmds.inc Index: devdoc/parts/d_bf_branchcmds.inc ================================================================== --- devdoc/parts/d_bf_branchcmds.inc +++ devdoc/parts/d_bf_branchcmds.inc @@ -1,29 +0,0 @@ - -In the hope of engendering good work practices now a few example -operations which will come up with branches, and their associated -fossil command (sequences). - -[list_begin definitions] - -[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] -[def [emph Awareness]] -[include d_op_aware.inc] - -[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] -[def [emph {Clean checkouts}]] -[include d_op_clean.inc] - -[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] -[def [emph {Starting a new branch}]] -[include d_op_branch_open.inc] - -[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] -[def [emph {Merging a branch into trunk}]] -[include d_op_branch_close.inc] - -[comment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] -[def [emph {Merging from trunk}]] -[include d_op_branch_import.inc] - -[list_end] - DELETED devdoc/parts/d_bf_branches.inc Index: devdoc/parts/d_bf_branches.inc ================================================================== --- devdoc/parts/d_bf_branches.inc +++ devdoc/parts/d_bf_branches.inc @@ -1,37 +0,0 @@ - -Given the constraints placed on the [term trunk] branch of the -repository it is (strongly) recommended to perform any development -going beyond trivial changes on a non-trunk branch. - -[para] Outside of the trunk developers are allowed to commit - intermediate broken states of their work. - - Only at the end of a development cycle, when the relevant - branch is considered ready for merging, will it be necessary to - perform full the set of validations ensuring that the merge to - come will create a good commit on trunk. - -[para] Note that while a review from a second developer is not a - required condition for merging a branch it is recommended to - seek out such an independent opinion as a means of - cross-checking the work. - -[para] It also recommended to give any new branch a name which aids in - determining additional details about it. Examples of good - things to stick into a branch name would be - -[list_begin itemized] -[item] Developer (nick)name -[item] Ticket hash/reference -[item] One or two keywords applicable to the work -[item] ... -[list_end] - -[para] Further, while most development branches are likely quite - short-lived, no prohibitions exist against making longer-lived - branches. - - Creators should however be mindful that the longer such a - branch exists without merges the more divergent they will tend - to be, with an associated increase in the effort which will - have to be spent on either merging from and merging to trunk. DELETED devdoc/parts/d_bf_dependencies.inc Index: devdoc/parts/d_bf_dependencies.inc ================================================================== --- devdoc/parts/d_bf_dependencies.inc +++ devdoc/parts/d_bf_dependencies.inc @@ -1,61 +0,0 @@ - -Regarding packages and dependencies between them Tcllib occupies a -middle position between two extremes: - -[list_begin enumerated] - -[enum] On one side a strongly interdependent set of packages, usually - by a single author, for a single project. Looking at my - (Andreas Kupries) own work examples of such are - [uri https://core.tcl.tk/akupries/marpa/index Marpa], - [uri https://core.tcl.tk/akupries/crimp/index CRIMP], - [uri https://core.tcl.tk/akupries/kinetcl/index Kinetcl], etc. - -[para] For every change the author of the project handles all the - modifications cascading from any incompatibilities it - introduced to the system. - -[enum] On the other side, the world of semi-independent projects by - many different authors where authors know what packages their - own creations depend on, yet usually do not know who else - depends on them. - -[para] The best thing an author making an (incompatible) change to - their project can do is to for one announce such changes in - some way, and for two use versioning to distinguish the code - before and after the change. - -[para] The world is then responsible for adapting, be it by updating - their own projects to the new version, or by sticking to the - old. - -[list_end] - -As mentioned already, Tcllib lives in the middle of that. - -[para] While we as maintainers cannot be aware of all users of - Tcllib's packages, and thus have to rely on the mechanisms - touched on in point 2 above for that, the dependencies between - the packages contained in Tcllib are a different matter. - -[para] As we are collectively responsible for the usability of Tcllib - in toto to the outside world, it behooves us to be individually - mindful even of Tcllib packages we are not directly - maintaining, when they depend on packages under our - maintainership. - - This may be as simple as coordinating with the maintainers of - the affected packages. - - It may also require us to choose how to adapt affected packages - which do not have maintainers, i.e. modify them to use our - changed package properly, or modify them to properly depend on - the unchanged version of our package. - -[para] Note that the above is not only a chore but an opportunity as - well. - - Additional insight can be had by forcing ourselves to look at - our package and the planned change(s) from an outside - perspective, to consider the ramifications of our actions on - others in general, and on dependent packages in particular. DELETED devdoc/parts/d_bf_trunk.inc Index: devdoc/parts/d_bf_trunk.inc ================================================================== --- devdoc/parts/d_bf_trunk.inc +++ devdoc/parts/d_bf_trunk.inc @@ -1,30 +0,0 @@ - -The management and use of branches is an important part of working -with a [term {Distributed Version Control System}] ([term DVCS]) like -[uri https://www.fossil-scm.org/ fossil]. - -[para] For Tcllib the main branch of the collection is - [term trunk]. In [term git] this branch would be called - [term master], and this is exactly the case in the - [uri https://github.com/tcltk/tcllib/ {github mirror}] of - Tcllib. - -[para] To properly support debugging [emph {each commit}] on this - branch [emph {has to pass the entire testsuite}] of the - collection. Using bisection to determine when an issue appeared - is an example of an action made easier by this constraint. - -[para] This is part of our collective responsibility for the usability - of Tcllib in toto to the outside world. - - As [term fossil] has no mechanism to enforce this condition - this is handled on the honor system for developers and maintainers. - -[para] To make the task easier Tcllib comes with a tool - ([file sak.tcl]) providing a number of commands in - support. These commands are explained in the following sections - of this guide. - -[para] While it is possible and allowed to commit directly to trunk - remember the above constraint regarding the testsuite, and the - coming notes about other possible issues with a commit. DELETED devdoc/parts/d_bf_versions.inc Index: devdoc/parts/d_bf_versions.inc ================================================================== --- devdoc/parts/d_bf_versions.inc +++ devdoc/parts/d_bf_versions.inc @@ -1,44 +0,0 @@ -In Tcllib all changes to a package have to come with an increment of -its version number. What part is incremented (patchlevel, minor, major -version) depends on the kind of change made. With multiple changes in -a commit the highest "wins". - -[para] When working in a development branch the version change can be - deferred until it is time to merge, and then has to cover all - the changes in the branch. - -[para] Below a list of the kinds of changes and their associated - version increments: - -[list_begin definitions] -[def [term {D - documentation}]] No increment -[def [term {T - testsuite}]] No increment -[def [term {B - bugfix}]] Patchlevel -[def [term {I - implementation tweak}]] Patchlevel -[def [term {P - performance tweak}]] Patchlevel -[def [term {E - backward-compatible extension}]] Minor -[def [term {API - incompatible change}]] Major -[list_end] - -[para] Note that a commit containing a version increment has to - mention the new version number in its commit message, as well - as the kind of change which caused it. - -[para] Note further that the version number of a package currently - exists in three places. An increment has to update all of them: - -[list_begin enumerated] -[enum] The package implementation. -[enum] The package index ([file pkgIndex.tcl]) -[enum] The package documentation. -[list_end] - -[para] The [file sak.tcl] command [cmd {validate version}] helps - finding discrepancies between the first two. - - All the other [cmd validate] methods are also of interest to - any developer. Invoke it with - - [example { sak.tcl help validate }] - - to see their documentation. DELETED devdoc/parts/d_branchflow.inc Index: devdoc/parts/d_branchflow.inc ================================================================== --- devdoc/parts/d_branchflow.inc +++ devdoc/parts/d_branchflow.inc @@ -1,19 +0,0 @@ -[comment {===================================================================}] -[subsection {Package Dependencies}] -[include d_bf_dependencies.inc] - -[comment {===================================================================}] -[subsection Trunk] -[include d_bf_trunk.inc] - -[comment {===================================================================}] -[subsection Branches] -[include d_bf_branches.inc] - -[comment {===================================================================}] -[subsection {Working with Branches}] -[include d_bf_branchcmds.inc] - -[comment {===================================================================}] -[subsection {Version numbers}] -[include d_bf_versions.inc] DELETED devdoc/parts/d_contrib.inc Index: devdoc/parts/d_contrib.inc ================================================================== --- devdoc/parts/d_contrib.inc +++ devdoc/parts/d_contrib.inc @@ -1,18 +0,0 @@ - -As a contributor to Tcllib you are committing yourself to: - -[list_begin enumerated] - -[enum] keep the guidelines written down in - [term {Tcl Community - Kind Communication}] in your mind. - The main point to take away from there is - [emph {to be kind to each other}]. - -[enum] Your contributions getting distributed under a BSD/MIT license. - For the details see [term {Tcllib - License}] - -[list_end] - -Contributions are made by entering tickets into our tracker, providing -patches, bundles or branches of code for inclusion, or posting to the -Tcllib related mailing lists. DELETED devdoc/parts/d_dirlayout.inc Index: devdoc/parts/d_dirlayout.inc ================================================================== --- devdoc/parts/d_dirlayout.inc +++ devdoc/parts/d_dirlayout.inc @@ -1,149 +0,0 @@ - -[subsection {Main Directories}] - -The main directories in the Tcllib toplevel directory and of interest -to a developer are: - -[list_begin definitions] - -[def [file modules]] - -Each child directory represents one or more packages. - -In the case of the latter the packages are usually related in some -way. Examples are [file base64], [file math], and [file struct], with -loose (base64) to strong (math) relations between the packages in the -directory. - -[def [file apps]] - -This directory contains all the installable applications, with their -documentation. Note that this directory is currently [emph not] split -into sub-directories. - -[def [file examples]] - -Each child directory [file foo] contains one or more example -application for the packages in [file modules/foo]. These examples are -generally not polished enough to be considered for installation. - -[list_end] - -[subsection {More Directories}] - -[list_begin definitions] - -[def [file config]] - -This directory contains files supporting the Unix build system, -i.e. [file configure] and [file Makefile.in]. - -[def [file devdoc]] - -This directories contains the doctools sources for the global -documentation, like this document and its sibling guides. - -[def [file embedded]] - -This directory contains the entire documentation formatted for -[term HTML] and styled to properly mix into the web site generated by -fossil for the repository. - -[para] This is the documentation accessible from the Tcllib home -directory, represented in the repository as [file embedded/index.md]. - -[def [file idoc]] - -This directory contains the entire documentation formatted for -[term nroff] and [term HTML], the latter without any styling. -This is the documentation which will be installed. - -[def [file support]] - -This directory contains the sources of internal packages and utilities -used in the implementation of the [file installer.tcl] and -[file sak.tcl] scripts/tools. - -[list_end] - -[subsection {Top Files}] - -[list_begin definitions] -[def [file aclocal.m4]] -[def [file configure]] -[def [file configure.in]] -[def [file Makefile.in]] - -These four files comprise the Unix build system layered on top of the -[file installer.tcl] script. - -[def [file installer.tcl]] - -The Tcl-based installation script/tool. - -[def [file project.shed]] - -Configuration file for [term {Sean Wood}]'s [syscmd PracTcl] -buildsystem. - -[def [file sak.tcl]] -This is the main tool for developers and release managers, the -[term {Swiss Army Knife}] of management operations on the collection. - -[def [file ChangeLog]] - -The log of changes to the global support, when the sources were held -in [term CVS]. Not relevant any longer with the switch to the -[term fossil] SCM. - -[def [file license.terms]] - -The license in plain ASCII. See also [term {Tcllib - License}] for the -nicely formatted form. The text is identical. - -[def [file README.md]] -[def [file .github/CONTRIBUTING.md]] -[def [file .github/ISSUE_TEMPLATE.md]] -[def [file .github/PULL_REQUEST_TEMPLATE.md]] - -These markdown-formatted documents are used and shown by the github -mirror of these sources, pointing people back to the official location -and issue trackers. - -[def [file DESCRIPTION.txt]] -[def [file STATUS]] -[def [file tcllib.spec]] -[def [file tcllib.tap]] -[def [file tcllib.yml]] - -???? - -[list_end] - -[subsection {File Types}] - -The most common file types, by file extension, are: - -[list_begin definitions] - -[def [file .tcl]] -Tcl code for a package, application, or example. - -[def [file .man]] -Doctools-formatted documentation, usually for a package. - -[def [file .test]] -Test suite for a package, or part of. -Based on [package tcltest]. - -[def [file .bench]] -Performance benchmarks for a package, or part of. -Based on [file modules/bench]. - -[def [file .pcx]] -Syntax rules for [term TclDevKit]'s [syscmd tclchecker]. Using these -rules allows the checker to validate the use of commands of a Tcllib -package [package foo] without having to scan the [file .tcl] files -implementing it. - -[list_end] DELETED devdoc/parts/d_documentation.inc Index: devdoc/parts/d_documentation.inc ================================================================== --- devdoc/parts/d_documentation.inc +++ devdoc/parts/d_documentation.inc @@ -1,76 +0,0 @@ - -The standard format used for documentation of packages and other -things in Tcllib is [term doctools]. - -Its supporting packages are a part of Tcllib, see the directories -[file modules/doctools] and [file modules/dtplite]. The latter is -an application package, with the actual application -[file apps/dtplite] a light wrapper around it. - -[para] Tcllib developers gain access to these through the [cmd doc] -method of the [file sak.tcl] tool, another (internal) wrapper around -the [file modules/dtplite] application package. - -[comment {===================================================================}] -[subsection {Generate documentation for a specific module}] - -Invoke either - -[example { ./sak.tcl doc html foo }] - -or - -[example { ./sak.tcl doc html modules/foo }] - -to generate HTML for the documentation found in the module [file foo]. - -Instead of [const html] any other supported format can be used here, -of course. - -[para] The generated formatted documentation will be placed into a -directory [file doc] in the current working directory. - -[comment {===================================================================}] -[subsection {Generate documentation for all modules}] - -Invoke the tool without a module name, i.e. - -[example { ./sak.tcl doc html }] - -to generate HTML for the documentation found in all modules. - -Instead of [const html] any other supported format can be used here, -of course. - -[para] The generated formatted documentation will be placed into a -directory [file doc] in the current working directory. - -[comment {===================================================================}] -[subsection {Available output formats, help}] - -Invoke the tool as - -[example { ./sak.tcl help doc }] - -to see the entire set of supported output formats which can be -generated. - -[comment {===================================================================}] -[subsection {Validation without output}] - -Note the special format [const validate]. - -[para] Using this value as the name of the format to generate forces -the tool to simply check that the documentation is syntactically -correct, without generating actual output. - -[para] Invoke it as either - -[example { ./sak.tcl doc validate (modules/)foo }] - -or - -[example { ./sak.tcl doc validate }] - -to either check the packages of a specific module or check all of -them. DELETED devdoc/parts/d_installation.inc Index: devdoc/parts/d_installation.inc ================================================================== --- devdoc/parts/d_installation.inc +++ devdoc/parts/d_installation.inc @@ -1,94 +0,0 @@ -A last thing to consider when adding a new package to the collection -is installation. - -[para] How to [emph use] the [file installer.tcl] script is documented -in [term {Tcllib - The Installer's Guide}]. - -[para] Here we document how to extend said installer so that it may -install new package(s) and/or application(s). - -[para] In most cases only a single file has to be modified, the -[file support/installation/modules.tcl] holding one command per module -and application to install. - -[para] The relevant commands are: - -[list_begin definitions] - -[call [cmd Module] [arg name] \ - [arg code-action] \ - [arg doc-action] \ - [arg example-action]] - -Install the packages of module [arg name], found in -[file modules/[arg name]]. - -[para] The [arg code-action] is responsible for installing the -packages and their index. The system currently provides - -[list_begin definitions] - -[def [cmd _tcl]] Copy all [file .tcl] files found in -[file modules/[arg name]] into the installation. - -[def [cmd _tcr]] As [cmd _tcl], copy the [file .tcl] files found in -the subdirectories of [file modules/[arg name]] as well. - -[def [cmd _tci]] As [cmd _tcl], and copy the [file tclIndex.tcl] file -as well. - -[def [cmd _msg]] As [cmd _tcl], and copy the subdirectory [file msgs] -as well. - -[def [cmd _doc]] As [cmd _tcl], and copy the subdirectory -[file mpformats] as well. - -[def [cmd _tex]] As [cmd _tcl], and copy [file .tex] files as well. - -[list_end] - -[para] The [arg doc-action] is responsible for installing the package -documentation. The system currently provides - -[list_begin definitions] -[def [cmd _null]] No documentation available, do nothing. - -[def [cmd _man]] Process the [file .man] files found in -[file modules/[arg name]] and install the results (nroff and/or HTML) -in the proper location, as given to the installer. - -[para] This is actually a fallback, normally the installer uses the -pre-made formatted documentation found under [file idoc]. - -[list_end] - -[para] The [arg example-action] is responsible for installing the -examples. The system currently provides - -[list_begin definitions] -[def [cmd _null]] No examples available, do nothing. - -[def [cmd _exa]] Copy the the directory [file examples/[arg name]] -recursively to the install location for examples. - -[list_end] - -[call [cmd Application] [arg name]] - -Install the application with [arg name], found in [file apps]. - - -[call [cmd Exclude] [arg name]] - -This command signals to the installer which of the listed modules to -[emph not] install. I.e. they name the deprecated modules of Tcllib. - -[list_end] - -[para] If, and only if the above actions are not suitable for the new -module then a second file has to be modified, -[file support/installation/actions.tcl]. - -[para] This file contains the implementations of the available -actions, and is the place where any custom action needed to handle the -special circumstances of module has to be added. DELETED devdoc/parts/d_maintain.inc Index: devdoc/parts/d_maintain.inc ================================================================== --- devdoc/parts/d_maintain.inc +++ devdoc/parts/d_maintain.inc @@ -1,71 +0,0 @@ - -When contributing one or more packages for full inclusion into Tcllib -you are committing yourself to - -[list_begin enumerated] - -[enum] Keep the guidelines written down in - [term {Tcl Community - Kind Communication}] - (as any contributor) in your mind. The main point to take away - from there is [emph {to be kind to each other}]. - -[enum] Your packages getting distributed under a BSD/MIT license. For - the details see [term {Tcllib - License}] - -[enum] Maintenance of the new packages for a period of two years under - the following rules, and responsibilities: - - [list_begin enumerated] - - [enum] A maintainer may step down after the mandatory period as - they see fit. - - [enum] A maintainer may step down before the end of the - mandatory period, under the condition that a replacement - maintainer is immediately available and has agreed to - serve the remainder of the period, plus their own - mandatory period (see below). - - [enum] When stepping down without a replacement maintainer - taking over the relevant packages have to be flagged as - [const unmaintained]. - - [enum] When a replacement mantainer is brought in for a package - it is (kept) marked as [const maintained] (again). - - [para] A replacement maintainer is bound by the same rules as - the original maintainer, except that the mandatory - period of maintenance is shortened to one year. - - [enum] For any [const unmaintained] package a contributor - interested in becoming its maintainer can become so by - flagging them as [const maintained] with their name and - contact information, committing themselves to the rules - of a replacement maintainer (see previous point). - - [enum] For any already [const maintained] package a contributor - interested in becoming a co-maintainer can become so - with the agreement of the existing maintainer(s), - committing themselves to the rules of a replacement - maintainer (see two points previous). - - [list_end] - - [para] The responsibilities as a maintainer include: - - [list_begin enumerated] - - [enum] Watching Tcllib's ticket tracker for bugs, bug fixes, - and feature requests related to the new packages. - - [enum] Reviewing the aforementioned tickets, rejecting or - applying them - - [enum] Coordination and discussion with ticket submitter during - the development and/or application of bug fixes. - - [list_end] - -[enum] Follow the [sectref {Branching and Workflow}] of this guide. - -[list_end] DELETED devdoc/parts/d_op_aware.inc Index: devdoc/parts/d_op_aware.inc ================================================================== --- devdoc/parts/d_op_aware.inc +++ devdoc/parts/d_op_aware.inc @@ -1,57 +0,0 @@ - -When developing we have to keep ourselves aware of the context of our -work. On what branch are we ? What files have we changed ? What new -files are not yet known to the repository ? What has happened remotely -since we used our checkout ? - -The answers to these questions become especially important when using -a long-lived checkout and coming back to it after some time away. - -[para] Commands to answer questions like the above are: - -[list_begin definitions] - -[def [cmd {fossil pull}]] - - Get all changes done on the remote since the last pull or sync - from it. This has to be done first, before any of the commands - below. - -[para] Even if the commit in our checkout refers to the branch we want - right now control operations committed to the remote may have - changed that from underneath us. - -[def [cmd {fossil info | grep tags}]] -[def [cmd {fossil branch list | grep '\*'}]] - - Two different ways of determining the branch our checkout is - on. - -[def [cmd {fossil timeline}]] - - What have we (and others) done recently ? - -[para] [emph Attention], this information is very likely outdated, the - more the longer we did not use this checkout. - - Run [cmd {fossil pull}] first to get latest information from - the remote repository of the project. - -[def [cmd {fossil timeline current}]] - - Place the commit our checkout is based on at the top of the - timeline. - -[def [cmd {fossil changes}]] - - Lists the files we have changed compared to the commit the - checkout is based on. - -[def [cmd {fossil extra}]] - - Lists the files we have in the checkout the repository does not - know about. This may be leftover chaff from our work, or - something we have forgotten to [cmd {fossil add}] to the - repository yet. - -[list_end] DELETED devdoc/parts/d_op_branch_close.inc Index: devdoc/parts/d_op_branch_close.inc ================================================================== --- devdoc/parts/d_op_branch_close.inc +++ devdoc/parts/d_op_branch_close.inc @@ -1,73 +0,0 @@ - -Be aware of where you are (see first definition). - -[para] Ensure that you have clean checkout (see second definition). - - In the full-blown sequence (zig-zag) it is [emph required], due - to the merging from trunk. In the shorter sequence it is only - desired. That said, keeping the checkout clean before - any major operations is a good habit to have, in my opinion. - -[para] The full-blown sequencing with checks all the way is to - -[list_begin enumerated] - -[enum] Validate the checkout, i.e. last commit on your branch. Run the - full test suite and other validations, fix all the issues which - have cropped up. - -[enum] Merge the latest state of the [term trunk] (see next definition). - -[enum] Validate the checkout again. The incoming trunk changes may - have broken something now. Do any required fixes. - -[enum] Now merge to the trunk using - -[example { - fossil update trunk - fossil merge --integrate YOUR_BRANCH -}] - -[enum] At this point the checkout should be in the same state as at - the end of point (3) above, because we resolved any issues with - the trunk already. Thus a simple - -[example { - fossil commit ... -}] - - should be sufficient now to commit the merge back and close the - branch (due to the [option --integrate] we used on the merge). - -[para] The more paranoid may validate the checkout a third time before - commiting. -[list_end] - -[para] I call this a [term {zig-zag merge}] because of how the arrows - look in the timeline, from trunk to feature branch for the - first merge, and then back for the final merge. - -[para] A less paranoid can do what I call a [term {simple merge}], - which moves step (2) after step (4) and skips step (3) - entirely. The resulting shorter sequence is - -[list_begin enumerated] -[enum] Validate -[enum] Merge to trunk -[enum] Validate again -[enum] Commit to trunk -[list_end] - -The last step after either zig-zag or plain merge is to - -[example { - fossil sync -}] - -This saves our work to the remote side, and further gives us any other -work done while we were doing our merge. It especially allows us to -check if we raced somebody else, resulting in a split trunk. - -[para] When that happens we should coordinate with the other developer - on who fixes the split, to ensure that we do not race each - other again. DELETED devdoc/parts/d_op_branch_import.inc Index: devdoc/parts/d_op_branch_import.inc ================================================================== --- devdoc/parts/d_op_branch_import.inc +++ devdoc/parts/d_op_branch_import.inc @@ -1,32 +0,0 @@ - -Be aware of where you are (see first definition). - -[para] Ensure that you have clean checkout (see second definition). - It is [emph required]. - -[para] In most situations you want to import the latest commit of - branch [term trunk] (or other origin). To get it use - -[example { - fossil pull -}] - -[para] With that done we can now import this commit into our current - branch with - -[example { - fossil merge trunk -}] - -[para] Even if [syscmd fossil] does not report any conflicts it is a - good idea to check that the operation has not broken the new - and/or changed functionality we are working on. - -[para] With the establishment of a good merge we then save the state - with - -[example { - fossil commit ... -}] - -before continuing development. DELETED devdoc/parts/d_op_branch_open.inc Index: devdoc/parts/d_op_branch_open.inc ================================================================== --- devdoc/parts/d_op_branch_open.inc +++ devdoc/parts/d_op_branch_open.inc @@ -1,59 +0,0 @@ - -Be aware of where you are (see first definition). - -[para] Ensure that you have clean checkout (see second definition). - It is [emph required]. - -[para] In most situations you want to be on branch [term trunk], and - you want to be on the latest commit for it. To get there use - -[example { - fossil pull - fossil update trunk -}] - -If some other branch is desired as the starting point for the coming -work replace [term trunk] in the commands above with the name of that -branch. - -[para] With the base line established we now have two ways of creating - the new branch, with differing (dis)advantages. - - The simpler way is to - -[example { - fossil branch new NAME_OF_NEW_BRANCH -}] - -and start developing. The advantage here is that you cannot forget to -create the branch. The disadvantages are that we have a branch commit -unchanged from where we branched from, and that we have to use -high-handed techniques like hiding or shunning to get rid of the -commit should we decide to abandon the work before the first actual -commit on the branch. - -[para] The other way of creating the branch is to start developing, -and then on the first commit use the option [option --branch] to tell -[syscmd fossil] that we are starting a branch now. I.e. run - -[example { - fossil commit --branch NAME_OF_NEW_BRANCH ... -}] - -where [term ...] are any other options used to supply the commit -message, files to commit, etc. - -[para] The (dis)advantages are now reversed. - -[para] We have no superflous commit, only what is actually - developed. The work is hidden until we commit to make our first - commit. - -[para] We may forget to use [option {--branch NAME_OF_NEW_BRANCH}] and - then have to correct that oversight via the fossil web - interface (I am currently unaware of ways of doing such from - the command line, although some magic incantantion of - [cmd {fossil tag create}] may work). - -[para] It helps to keep awareness, like checking before any commit - that we are on the desired branch. DELETED devdoc/parts/d_op_clean.inc Index: devdoc/parts/d_op_clean.inc ================================================================== --- devdoc/parts/d_op_clean.inc +++ devdoc/parts/d_op_clean.inc @@ -1,14 +0,0 @@ - -Be aware of where you are (see first definition). - -[para] For pretty much all the operation recipes below a clean - checkout is at least desired, often required. - To check that a checkout is clean invoke - -[example { - fossil changes - fossil extra -}] - -How to clean up when uncommitted changes of all sorts are found is -context-specific and outside of the scope of this guide. DELETED devdoc/parts/d_testing.inc Index: devdoc/parts/d_testing.inc ================================================================== --- devdoc/parts/d_testing.inc +++ devdoc/parts/d_testing.inc @@ -1,90 +0,0 @@ - -Testsuites in Tcllib are based on Tcl's standard test package -[package tcltest], plus utilities found in the directory -[file modules/devtools] - -[para] Tcllib developers invoke the suites through the -[cmd {test run}] method of the [file sak.tcl] tool, with other methods -of [cmd test] providing management operations, for example setting a -list of standard Tcl shells to use. - -[comment {===================================================================}] -[subsection {Invoke the testsuites of a specific module}] - -Invoke either - -[example { ./sak.tcl test run foo }] - -or - -[example { ./sak.tcl test run modules/foo }] - -to invoke the testsuites found in a specific module [file foo]. - -[comment {===================================================================}] -[subsection {Invoke the testsuites of all modules}] - -Invoke the tool without a module name, i.e. - -[example { ./sak.tcl test run }] - -to invoke the testsuites of all modules. - -[comment {===================================================================}] -[subsection {Detailed Test Logs}] - -In all the previous examples the test runner will write a combination -of progress display and testsuite log to the standard output, showing -for each module only the tests that passed or failed and how many of -each in a summary at the end. - -[para] To get a detailed log, it is necessary to invoke the test -runner with additional options. - -[para] For one: - -[example { - ./sak.tcl test run --log LOG foo -}] - -While this shows the same short log on the terminal as before, it also -writes a detailed log to the file [file LOG.log], and excerpts to -other files ([file LOG.summary], [file LOG.failures], etc.). - -[para] For two: - -[example { - ./sak.tcl test run -v foo -}] - -This writes the detailed log to the standard output, instead of the -short log. - -[para] Regardless of form, the detailed log contains a list of all test -cases executed, which failed, and how they failed (expected versus -actual results). - -[comment {===================================================================}] -[subsection {Shell Selection}] - -By default the test runner will use all the Tcl shells specified via -[cmd {test add}] to invoke the specified testsuites, if any. If no -such are specified it will fall back to the Tcl shell used to run the -tool itself. - -[para] Use option [option --shell] to explicitly specify the Tcl shell -to use, like - -[example { - ./sak.tcl test run --shell /path/to/tclsh ... -}] - -[comment {===================================================================}] -[subsection Help] - -Invoke the tool as - -[example { ./sak.tcl help test }] - -to see the detailed help for all methods of [cmd test], and the -associated options. DELETED devdoc/parts/d_testwrite.inc Index: devdoc/parts/d_testwrite.inc ================================================================== --- devdoc/parts/d_testwrite.inc +++ devdoc/parts/d_testwrite.inc @@ -1,119 +0,0 @@ - -While previous sections talked about running the testsuites for a -module and the packages therein, this has no meaning if the module in -question has no testsuites at all. - -[para] This section gives a very basic overview on possible -methodologies for writing tests and testsuites. - -[para] First there are "drudgery" tests. Written to check absolutely -basic assumptions which should never fail. - -[para] For example for a command FOO taking two arguments, three tests -calling it with zero, one, and three arguments. The basic checks that -the command fails if it has not enough arguments, or too many. - -[para] After that come the tests checking things based on our -knowledge of the command, about its properties and assumptions. Some -examples based on the graph operations added during Google's Summer of -Code 2009 are: - -[list_begin itemized] - -[item] The BellmanFord command in struct::graph::ops takes a - [arg startnode] as argument, and this node should be a node of - the graph. This equals one test case checking the behavior when the - specified node is not a node of the graph. - -[para] This often gives rise to code in the implementation which - explicitly checks the assumption and throws an understandable error, - instead of letting the algorithm fail later in some weird - non-deterministic way. - -[para] It is not always possible to do such checks. The graph argument - for example is just a command in itself, and while we expect - it to exhibit a certain interface, i.e. a set of sub-commands - aka methods, we cannot check that it has them, except by - actually trying to use them. That is done by the algorithm - anyway, so an explicit check is just overhead we can get by - without. - -[item] IIRC one of the distinguishing characteristic of either - BellmanFord and/or Johnson is that they are able to handle - negative weights. Whereas Dijkstra requires positive weights. - -[para] This induces (at least) three testcases ... Graph with all - positive weights, all negative, and a mix of positive and - negative weights. - - Thinking further does the algorithm handle the weight - [const 0] as well ? Another test case, or several, if we mix - zero with positive and negative weights. - -[item] The two algorithms we are currently thinking about are about - distances between nodes, and distance can be 'Inf'inity, - i.e. nodes may not be connected. This means that good test - cases are - - [list_begin enumerated] - [enum] Strongly connected graph - [enum] Connected graph - [enum] Disconnected graph. - [list_end] - - [para] At the extremes of strongly connected and disconnected - we have the fully connected graphs and graphs without edges, - only nodes, i.e. completely disconnected. - -[item] IIRC both of the algorithms take weighted arcs, and fill in a - default if arcs are left unweighted in the input graph. - - [para] This also induces three test cases: - - [list_begin enumerated] - [enum] Graph will all arcs with explicit weights. - [enum] Graph without weights at all. - [enum] Graph with mixture of weighted and unweighted graphs. - [list_end] -[list_end] - -[para] What was described above via examples is called -[term black-box] testing. Test cases are designed and written based on -the developer's knowledge of the properties of the algorithm and its -inputs, without referencing a particular implementation. - -[para] Going further, a complement to [term black-box] testing is -[term white-box]. For this we know the implementation of the -algorithm, we look at it and design our tests cases so that they force -the code through all possible paths in the implementation. Wherever a -decision is made we have a test case forcing a specific direction of -the decision, for all possible combinations and directions. It is easy -to get a combinatorial explosion in the number of needed test-cases. - -[para] In practice I often hope that the black-box tests I have made -are enough to cover all the paths, obviating the need for white-box -tests. - -[para] The above should be enough to make it clear that writing tests -for an algorithm takes at least as much time as coding the algorithm, -and often more time. Much more time. - -See for example also [uri http://sqlite.org/testing.html], a writeup -on how the Sqlite database engine is tested. Another article of -interest might be [uri https://www.researchgate.net/publication/298896236]. -While geared to a particular numerical algorithm it still shows that -even a simple-looking algorithm can lead to an incredible number of -test cases. - -[para] An interesting connection is to documentation. In one -direction, the properties checked with black-box testing are exactly -the properties which should be documented in the algorithm's man -page. And conversely, the documentation of the properties of an -algorithm makes a good reference to base the black-box tests on. - -[para] In practice test cases and documentation often get written -together, cross-influencing each other. And the actual writing of test -cases is a mix of black and white box, possibly influencing the -implementation while writing the tests. Like writing a test for a -condition like [term {startnode not in input graph}] serving as -reminder to put a check for this condition into the code. DELETED devdoc/parts/rm_distribute.inc Index: devdoc/parts/rm_distribute.inc ================================================================== --- devdoc/parts/rm_distribute.inc +++ devdoc/parts/rm_distribute.inc @@ -1,39 +0,0 @@ - -With the release made it has to be published and the world notified of -its existence. - -[list_begin enumerated] - -[enum] Create a proper fossil event for the release, via - [uri http://core.tcl-lang.org/tcllib/eventedit]. - -[para] An [uri http://core.tcl-lang.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817 {existing event}] should be used as template. - -[enum] Update a number of web locations: - -[list_begin enumerated] -[enum] [uri http://core.tcl-lang.org/tcllib/doc/trunk/embedded/index.md {Home page}] -[enum] [uri http://core.tcl-lang.org/tcllib/wiki?name=Downloads Downloads] -[enum] [uri http://core.tcl-lang.org/tcllib/wiki?name=Past+Releases {Past Releases}] -[enum] [uri http://www.tcl-lang.org/home/release.txt ] -[enum] [uri http://www.tcl-lang.org/software/tcllib/*.tml] -[enum] [uri http://wiki.tcl-lang.org/page/Tcllib] -[list_end] - -The first location maps to the file [file embedded/index.md] in the -repository itself, as such it can edited as part of the release -process. This is where reference to the new fossil event is added, as -the new current release. - -[para] The next two locations are in the fossil tcllib wiki and -require admin or wiki write permissions for -[uri http://core.tcl-lang.org/tcllib]. - -[para] The last two locations require ssh access to -[uri http://www.tcl-lang.org] and permission to edit -files in the web area. - - -[enum] ***TODO*** mailing lists and other places to send notes to. - -[list_end] DELETED devdoc/parts/rm_final.inc Index: devdoc/parts/rm_final.inc ================================================================== --- devdoc/parts/rm_final.inc +++ devdoc/parts/rm_final.inc @@ -1,1 +0,0 @@ -todo: finalize release, make candidate official DELETED devdoc/parts/rm_start.inc Index: devdoc/parts/rm_start.inc ================================================================== --- devdoc/parts/rm_start.inc +++ devdoc/parts/rm_start.inc @@ -1,1 +0,0 @@ -todo: open a candidate for release DELETED devdoc/parts/rm_tooling.inc Index: devdoc/parts/rm_tooling.inc ================================================================== --- devdoc/parts/rm_tooling.inc +++ devdoc/parts/rm_tooling.inc @@ -1,18 +0,0 @@ - -The [file sak.tcl] script in the toplevel directory of a Tcllib -checkout is the one tool used by the release manager to perform its -[sectref Tasks]. - -[para] The main commands to be used are - -[example { - sak.tcl validate - sak.tcl test run - sak.tcl review - sak.tcl readme - sak.tcl localdoc - sak.tcl release -}] - -More detail will be provided in the explanations of the various -[sectref Tasks]. DELETED devdoc/parts/rm_work.inc Index: devdoc/parts/rm_work.inc ================================================================== --- devdoc/parts/rm_work.inc +++ devdoc/parts/rm_work.inc @@ -1,7 +0,0 @@ -todo: test, validate and check that the candidate is worthy of release -fix testsuites, possibly fix packages, documentation -regenerate docs -coordinate with package maintainers wrt fixes - -big thing: going over the packages, classify changes since last -release to generate a nice readme. DELETED devdoc/parts/rq_critcl.inc Index: devdoc/parts/rq_critcl.inc ================================================================== --- devdoc/parts/rq_critcl.inc +++ devdoc/parts/rq_critcl.inc @@ -1,35 +0,0 @@ - -[subsection Critcl] - -The [syscmd critcl] tool is an [emph optional] dependency. - -[para] It is only required when trying to build the C-based -[term accelerators] for a number of packages, as explained in -[sectref {Critcl & Accelerators}] - -[para] Tcllib's build system looks for it in the [variable PATH], -using the name [syscmd critcl]. This is for Unix. - -On Windows on the other hand the search is more complex. First we look -for a proper application [syscmd critcl.exe]. When that is not found -we look for a combination of interpreter ([syscmd tclkitsh.exe], -[syscmd tclsh.exe]) and starkit ([syscmd critcl.kit], [syscmd critcl]) -instead. [emph Note] that the choice of starkit can be overriden via -the environment variable [variable CRITCL]. - -[para] Tcllib requires Critcl version 2 or higher. - -[para] The github repository providing releases of version 2 and -higher, and the associated sources, can be found at -[uri http://andreas-kupries.github.com/critcl]. - -[para] Any branch of the repository can be used (if not using the -prebuild starkit or starpack), although the use of the stable branch -[emph master] is recommended. - -[para] At the above url is also an explanation on how to build and -install Critcl, including a list of its dependencies. - -[para] Its instructions will not be repeated here. If there are -problems with these directions please file a ticket against the -[term Critcl] project, and not Tcllib. DELETED devdoc/parts/rq_tcl.inc Index: devdoc/parts/rq_tcl.inc ================================================================== --- devdoc/parts/rq_tcl.inc +++ devdoc/parts/rq_tcl.inc @@ -1,46 +0,0 @@ - -[subsection Tcl] - -As we are installing a number of Tcl packages and applications it -should be pretty much obvious that a working installation of Tcl -itself is needed, and I will not belabor the point. - -[para] Out of the many possibilities use whatever you are comfortable -with, as long as it provides at the very least Tcl 8.2, or higher. - -This may be a Tcl installation provided by your operating system -distribution, from a distribution-independent vendor, or built by -yourself. - -[para] [emph Note] that the packages in Tcllib have begun to require -8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use -such packages. Trying to use them will result in -[emph {package not found}] errors, as their package index files will -not register them in versions of the core unable to use them. - -[para] Myself, I used (and still use) -[uri http://www.activestate.com ActiveState's] -ActiveTcl 8.5 distribution during development, as I am most familiar -with it. - -[para] [emph {(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).}]. -I am currently working for SUSE Software Canada ULC, although not in -Tcl-related areas. - -[para] This distribution can be found at -[uri http://www.activestate.com/activetcl]. Retrieve the archive of -ActiveTcl 8.5 (or higher) for your platform and install it as directed -by ActiveState. - -[para] For those wishing to build and install Tcl on their own, the -relevant sources can be found at - -[list_begin definitions] -[def Tcl] [uri http://core.tcl-lang.org/tcl/] -[list_end] - -together with the necessary instructions on how to build it. - -[para] If there are problems with building, installing, or using Tcl, -please file a ticket against [term Tcl], or the vendor of your -distribution, and [emph not] [term Tcllib]. DELETED devdoc/parts/welcome.inc Index: devdoc/parts/welcome.inc ================================================================== --- devdoc/parts/welcome.inc +++ devdoc/parts/welcome.inc @@ -1,6 +0,0 @@ - -Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) [term Tcl] -packages that provide utility functions useful to a large collection -of Tcl programmers. - ADDED devdoc/releaseguide.html Index: devdoc/releaseguide.html ================================================================== --- devdoc/releaseguide.html +++ devdoc/releaseguide.html @@ -0,0 +1,72 @@ + + +

Guide to the creation of source releases for Tcllib +

+
+ +

Recap +

+
+ + +

+The CVS repository for Tcllib contains two main branches, + the HEAD for development, and RELEASES as the staging area for + official releases. +

+ +

Dependencies +

+ +

Creation of a new official release +

+ +

To create a new official release of Tcllib the release manager has + to perform the steps described below: +

+ + +
    +
  1. Retrieve the sources at the current head + from the CVS repository, using a command like +
    +	  CVSROOT=:pserver:anonymous@cvs.tcllib.sourceforge.net:/cvsroot/tcllib
+	  cvs -d${CVSROOT} co tcllib
+
    + Vary this command according to taste as long as the overall + meaning is not changed. Compression options and the like. + +
  2. Tag these sources with a new branch tag for the new release of + tcllib, like +
    +	  cvs -d${CVSROOT} rtag tcllib
+
    + +
  3. Commit the changes, then update the working directory. + +
  4. Use a tclsh to run the sak tool with the argument gendist, like +
    +    tclsh /path/to/tcllib/sak.tcl gendist
+
    + +
  5. This results in the creation of a tcllib-VERSION directory +in the current working directory, and of two archives, .zip, +and .tar.gz. A starkit will be created if sdx is present +in the PATH. If additionally a file named tclkit is present in +the current working directory a starpack will be created too, using +this tclkit as the runtime. + + +
  6. Now follow the instructions in the Sourceforge site documentation + for uploading the archives generated by the last + step to + ftp://upload.sourceforge.net/incoming, and + follow the procedures for creating packages and + releases at Sourceforge. +
+ +

At last notify the relevant persons in other communities like +Debian (See list of contacts) about the new release. +

DELETED devdoc/tcl_community_communication.man Index: devdoc/tcl_community_communication.man ================================================================== --- devdoc/tcl_community_communication.man +++ devdoc/tcl_community_communication.man @@ -1,178 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcl_community_communication n 1] -[titledesc {Tcl Community - Kind Communication}] -[description] - -The Tcl Community encourages contributions from anyone who wishes to -advance the development of: - -[list_begin itemized] -[item] The Tcl Language -[item] Tcl derived languages -[item] Tcl related libraries -[item] Tcl extensions -[item] External Projects that Integrate Tcl -[list_end] - -[para] We welcome those contributions from anyone. We are blind to -gender, race, religion, cultural background, cybernetic nature, and -any other demographic characteristics, as well as personal political -views. - -[para] A community lives and dies by communications. And occasionally -our communications are peppered with patterns that are harsh, -unfriendly, unwelcoming and/or otherwise unkind. As a volunteer -community, we need all of the help we can get. Therefore, we ask all -contributors to make a conscious effort, in Tcl Community discussions, -to communicate in ways that are welcoming. Ways that are -friendly. Ways that are, in a word: kind. - -[para] These guidelines suggest specific ways to accomplish that goal. - -[para] Please note: for the balance of this document any reference to -"People", "Persons", "anybody" or "somebody" can refer to any sentient -being, not merely corporeal members of the species Homo Sapien. - -[list_begin definitions] - -[def {We are a Sanctuary not a Clubhouse}] - -The Tcl Community is a collective of amateurs and professionals who -code, test, and use tools. Our community is open to all. There is no -velvet rope. There is no bouncer at the door. There are no secret -handshakes. Any sentient being who enters our midst is welcome. If -someone is ever asked to leave, it is only because they are being -disruptive to the functioning of the community. - -[def {We Merit Ideas, Not People}] - -A good idea can come from anyone, regardless of how little time they -have been with us. A bad idea can come from anyone, regardless of how -much time or how little time they have been with us. We judge a -concept by how it stands up to scrutiny of logic, implementation, and -regression testing. We don’t judge ideas based on who had the idea -first, who agrees with the idea, or who disagrees with it. - -[def {Treat Everyone with Respect}] - -Everyone is deserving of respect and courtesy at all times. - -[def {Refer to people by the names they use.}] - -If grammar requires you to state a gender for a person, honor their -preferences about their gender identity. If you are unsure as to the -gender of an individual, ask. If someone had to guess about your -gender and got it wrong, please correct them and do not take it -personally. - -[def {Do not take a harsh tone towards other participants.}] - -Do not make personal attacks against anyone (participant or not.) - -[para] Criticize statements and actions, never people. - -[def {Don’t Take Things Personally}] - -When in doubt, assume the best in people. A criticism of your -statements is not a personal attack on you. - -[def {Persons, not People}] - -Stereotypes are an unhelpful tool on many accounts. They are generally -oversimplified. They are usually flat out wrong. And even if "right" -they are of absolutely no utility in determining the capabilities, -motivations, or fitness of an individual. - -[para] Don’t use them in Tcl Community communications. - -[def {Mistakes Happen}] - -The human condition is a series of trials and errors. Progress is when -we get one more trial than error. Being wrong or making a mistake is -the default state of humanity. Accept the errors of your fellow -sentient beings, and be aware that you are also fallible. - -[def {Keep it Real}] - -Please respond to what people actually say. We are all amazing -individuals, but none among us are mind readers. If you find yourself -responding to what you imagine someone is thinking, odds are you are -going to be wrong. - -[para] If you must criticize someone, stick to things they have -actually done. Never criticize for something you speculate they have -done. Or imagine they have done. Or something someone who shares some -attribute with them has done in the past. - -[para] Keep discussions about any non-Tcl subjects to what can be -stated factually and without emotion or judgement. - -[def {When Trouble Arises, Don’t Escalate}] - -If you feel you are being personally attacked or offended, take the -high road. Punching back in a public forum will only makes things -worse. Address the matter in a private correspondence. Be -polite. Express your feelings, but note that you are expressing your -feelings. When writing, look for a way to calm matters down. And when -in doubt, sleep on your letter before pressing send. And when not in -doubt, sleep on it for another day after that. - -[para] If you are a spectator to a fight in progress, politely request -the two parties take the matter to a more private forum. - -[def {Always get the Last Word: I’m Sorry}] - -If an personal argument does arise, be the first to apologize. An -apology does not concede a logical point. It merely acknowledges that -at some point the discussion left either logic, community decency, or -both. Return to the topic when cooler heads can prevail. - -[def {Nobody is Keeping Score}] - -There is no prize for being right. There is no cost for being wrong. A -hard sell is not going to advance your idea along any more than a -logical argument. You aren’t running for office. This isn’t debate -club. If you find yourself continuing a discussion beyond where a -topic can be logically discussed, stop. - -[def {No Evangelizing}] - -The Tcl Community is not the place to promote your chosen operating -system, political outlook, religion, marketing scheme, or economic -model. Period. - -[para] (And if you do bring it up, be prepared to have your chosen -topic discussed logically. And odds are, not favorably.) - -[def {Respect the Community}] - -If the Community has come to a decision on a course of action, please -stop arguing. - -[para] If someone complains about how you are expressing your ideas, -listen. - -[para] If your words are hurting people, stop. There is no amount of -being "right" that makes up for someone leaving our midst because they -felt insulted, threatened, or ignored. - -[list_end] - -By following these guidelines, we will build our community, encourage -more contribution to our projects, and our discussions will be -friendlier and reach conclusions more easily. - -[para] Thank You. - -[section Signatories] -[list_begin itemized] -[item] Sean "the Hypnotoad" Woods -[item] Andreas Kupries -[list_end] - -[section Authors] -[list_begin definitions] -[def Primary] Sean "the Hypnotoad" Woods -[def {Light editing}] Andreas Kupries -[list_end] -[manpage_end] DELETED devdoc/tcllib_devguide.man Index: devdoc/tcllib_devguide.man ================================================================== --- devdoc/tcllib_devguide.man +++ devdoc/tcllib_devguide.man @@ -1,62 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcllib_devguide n 1] -[titledesc {Tcllib - The Developer's Guide}] -[description] -[include parts/welcome.inc] - -[para] - -This document is a guide for developers working on Tcllib, -i.e. maintainers fixing bugs, extending the collection's -functionality, etc. - -[para] - -Please read - -[list_begin enum] -[enum] [term {Tcllib - How To Get The Sources}] and -[enum] [term {Tcllib - The Installer's Guide}] -[list_end] - -first, if that was not done already. - -[para] Here we assume that the sources are already available in a -directory of your choice, and that you not only know how to build and -install them, but also have all the necessary requisites to actually -do so. The guide to the sources in particular also explains which -source code management system is used, where to find it, how to set it -up, etc. - -[comment {===================================================================}] -[section Commitments] -[subsection Contributor][include parts/d_contrib.inc] -[subsection Maintainer][include parts/d_maintain.inc] - -[comment {===================================================================}] -[section {Branching and Workflow}] -[include parts/d_branchflow.inc] - -[comment {===================================================================}] -[section {Structural Overview}] -[include parts/d_dirlayout.inc] - -[comment {===================================================================}] -[section {Testsuite Tooling}] -[include parts/d_testing.inc] - -[comment {===================================================================}] -[section {Documentation Tooling}] -[include parts/d_documentation.inc] - -[comment {===================================================================}] -[section {Notes On Writing A Testsuite}] -[include parts/d_testwrite.inc] - -[comment {===================================================================}] -[section {Installation Tooling}] -[include parts/d_installation.inc] - -[comment {===================================================================}] -[manpage_end] - DELETED devdoc/tcllib_installer.man Index: devdoc/tcllib_installer.man ================================================================== --- devdoc/tcllib_installer.man +++ devdoc/tcllib_installer.man @@ -1,90 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcllib_install_guide n 1] -[titledesc {Tcllib - The Installer's Guide}] -[description] -[include parts/welcome.inc] - -[para] - -The audience of this document is anyone wishing to build and install -the packages found in Tcllib, for either themselves, or others. - -[para] - -For developers intending to work on the packages themselves we -additionally provide - -[list_begin enum] -[enum] [term {Tcllib - The Developer's Guide}]. -[list_end] - -[para] - -Please read [term {Tcllib - How To Get The Sources}] first, if that -was not done already. Here we assume that the sources are already -available in a directory of your choice. - -[para] - -[comment {===================================================================}] -[section Requisites] - -Before Tcllib can be build and used a number of requisites must be installed. - -These are: - -[list_begin enumerated] -[enum] The scripting language Tcl. - For details see [sectref Tcl]. -[enum] Optionally, the [package critcl] package (C embedding) for [syscmd Tcl]. - For details see [sectref CriTcl]. -[list_end] - -This list assumes that the machine where Tcllib is to be installed is -essentially clean. Of course, if parts of the dependencies listed -below are already installed the associated steps can be skipped. It is -still recommended to read their sections though, to validate that the -dependencies they talk about are indeed installed. - -[include parts/rq_tcl.inc] -[include parts/rq_critcl.inc] - -[comment {= build instructions ==============================================}] -[section {Build & Installation Instructions}] - -As Tcllib is mainly a bundle of packages written in pure Tcl building -it is the same as installing it. The exceptions to this have their own -subsection, [sectref {Critcl & Accelerators}], later on. - -[para] Before that however comes the standard case, differentiated by - the platforms with material differences in the instruction, i.e. - [term Unix]-like, versus [term Windows]. - -[para] Regarding the latter it should also be noted that it is - possible set up an [term Unix]-like environment using projects - like [term MSYS], [term Cygwin], and others. In that case the - user has the choice of which instructions to follow. - -[para] Regardless of environment or platform, a suitable [term Tcl] - has to be installed, and its [syscmd tclsh] should be placed on - the [variable PATH] ([term Unix]) or associated with - [file .tcl] files ([term Windows]). - -[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] -[subsection {Installing on Unix}] -[include parts/b_unix.inc] - -[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] -[subsection {Installing on Windows}] -[include parts/b_windows.inc] - -[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] -[subsection {Critcl & Accelerators}] -[include parts/b_critcl.inc] - -[comment %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%] -[subsection Tooling] -[include parts/b_tooling.inc] - -[manpage_end] - DELETED devdoc/tcllib_license.man Index: devdoc/tcllib_license.man ================================================================== --- devdoc/tcllib_license.man +++ devdoc/tcllib_license.man @@ -1,61 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcllib_license n 1] -[titledesc {Tcllib - License}] -[description] -[include parts/welcome.inc] - -[para] The collection is under the BSD license. - -[section License] - -[para] - -This software is copyrighted by Ajuba Solutions and other parties. -The following terms apply to all files associated with the software -unless explicitly disclaimed in individual files. - -[para] - -The authors hereby grant permission to use, copy, modify, distribute, -and license this software and its documentation for any purpose, -provided that existing copyright notices are retained in all copies -and that this notice is included verbatim in any distributions. No -written agreement, license, or royalty fee is required for any of the -authorized uses. Modifications to this software may be copyrighted by -their authors and need not follow the licensing terms described here, -provided that the new terms are clearly indicated on the first page of -each file where they apply. - -[para] - -IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY -FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY -DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - -[para] - -THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND -NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND -THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE -MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. - -[para] - -GOVERNMENT USE: If you are acquiring this software on behalf of the -U.S. government, the Government shall have only "Restricted Rights" in -the software and related documentation as defined in the Federal -Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you -are acquiring the software on behalf of the Department of Defense, the -software shall be classified as "Commercial Computer Software" and the -Government shall have only "Restricted Rights" as defined in Clause -252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the -authors grant the U.S. Government and others acting in its behalf -permission to use and distribute the software in accordance with the -terms specified in this license. - -[manpage_end] - DELETED devdoc/tcllib_releasemgr.man Index: devdoc/tcllib_releasemgr.man ================================================================== --- devdoc/tcllib_releasemgr.man +++ devdoc/tcllib_releasemgr.man @@ -1,45 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcllib_releasemgr n 1] -[titledesc {Tcllib - The Release Manager's Guide}] -[description] -[include parts/welcome.inc] - -[para] - -The audience of this document is the release manager for Tcllib, their -deputies, and anybody else interested in the task of creating -an official release of Tcllib for distribution. - -[para] - -Please read [term {Tcllib - How To Get The Sources}] first, if that -was not done already. Here we assume that the sources are already -available in a directory of your choice. - -[para] - -[comment {===================================================================}] -[section Tools] -[include parts/rm_tooling.inc] - -[comment {===================================================================}] -[section Tasks] - -[comment {===================================================================}] -[subsection {Start a release candidate}] -[include parts/rm_start.inc] - -[comment {===================================================================}] -[subsection {Ready the candidate}] -[include parts/rm_work.inc] - -[comment {===================================================================}] -[subsection {Make it official}] -[include parts/rm_final.inc] - -[comment {===================================================================}] -[subsection {Distribute the release}] -[include parts/rm_distribute.inc] - -[manpage_end] - DELETED devdoc/tcllib_sources.man Index: devdoc/tcllib_sources.man ================================================================== --- devdoc/tcllib_sources.man +++ devdoc/tcllib_sources.man @@ -1,69 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[manpage_begin tcllib_sources n 1] -[titledesc {Tcllib - How To Get The Sources}] -[description] -[include parts/welcome.inc] - -[para] - -The audience of this document is anyone wishing to either have just a -look at Tcllib's source code, or build the packages, or to extend and -modify them. - -[para] For builders and developers we additionally provide - -[list_begin enum] -[enum] [term {Tcllib - The Installer's Guide}]. -[enum] [term {Tcllib - The Developer's Guide}]. -[list_end] - -respectively. - -[section {Source Location}] - -The official repository for Tcllib can be found at -[uri http://core.tcl-lang.org/tcllib] - -[section Retrieval] - -Assuming that you simply wish to look at the sources, or build a -specific revision, the easiest way of retrieving it is to: - -[list_begin enum] -[enum] Log into this site, as "anonymous", using the semi-random password in the captcha. -[enum] Go to the "Timeline". -[enum] Choose the revision you wish to have. -[enum] Follow its link to its detailed information page. -[enum] On that page, choose either the "ZIP" or "Tarball" link to get -a copy of this revision in the format of your choice. -[list_end] - -[section {Source Code Management}] - -For the curious (or a developer-to-be), the sources are managed by the -[uri http://www.fossil-scm.org {Fossil SCM}]. - -Binaries for popular platforms can be found directly at its -[uri http://www.fossil-scm.org/download.html {download page}]. - -[para] - -With that tool available the full history can be retrieved via: - -[example { - fossil clone \ - http://core.tcl-lang.org/tcllib \ - tcllib.fossil -}] - -followed by - -[example { - mkdir tcllib - cd tcllib - fossil open ../tcllib.fossil -}] - -to get a checkout of the head of the trunk. - -[manpage_end] ADDED embedded/index.html Index: embedded/index.html ================================================================== --- embedded/index.html +++ embedded/index.html @@ -0,0 +1,75 @@ +
+ +

Tcl Library Source Code

+ +
+
+ + +
+

+Table Of Contents +    + +Keyword Index +

+ +

Discussion & Contact

+
    +

    Tcllib has two mailing lists, +one for notifications, the other for general discussion. These are managed at SourceForge, +at the aforementioned link. A few direct links for various topics: + + + + + + + + + +
    tcllib-bugs: SubscribeArchiveSearch
    tcllib-devel:SubscribeArchiveSearch
    + +

+ + +

Feedback

+
    +

    Please go to and use our + +Local Trackers. They are for +

      +
    • Bugs,
      • +
    • Patches, and
      • +
    • Ideas & Feature Requests.
      • +

    +
+ +

Releases

+ + + +

Related Repositories

+ + + +

See also

+ DELETED embedded/index.md Index: embedded/index.md ================================================================== --- embedded/index.md +++ embedded/index.md @@ -1,68 +0,0 @@ -
- -

Tcl Library Source Code

- -
-Packages - [Table Of Contents](md/toc.md) -    -[Keyword Index](md/index.md) -
- -
-
- - -
-
- -## Guides to Tcllib - - * [Tcl Community - Kind Communication](md/tcllib/files/devdoc/tcl_community_communication.md) - * [License](md/tcllib/files/devdoc/tcllib_license.md) - * [How To Get The Sources](md/tcllib/files/devdoc/tcllib_sources.md) - * [How To Build And Install Tcllib](md/tcllib/files/devdoc/tcllib_installer.md) - * [The Developer's Guide](md/tcllib/files/devdoc/tcllib_devguide.md) - * [The Release Manager's Guide](md/tcllib/files/devdoc/tcllib_releasemgr.md) - -## Discussion & Contact - -Tcllib has two -[mailing lists](https://sourceforge.net/p/tcllib/mailman/). - -One for notifications (commits, ticket changes), the other for general -discussion. These are managed at SourceForge, at the aforementioned -link. A few direct links for various topics: - -|tcllib-bugs| : |[Subscribe](https://lists.sourceforge.net/lists/listinfo/tcllib-bugs) [Archive](https://sourceforge.net/p/tcllib/mailman/tcllib-bugs) [Search](https://sourceforge.net/p/tcllib/mailman/search/?mail_list=tcllib-bugs)| -|tcllib-devel| : |[Subscribe](https://lists.sourceforge.net/lists/listinfo/tcllib-devel) [Archive](https://sourceforge.net/p/tcllib/mailman/tcllib-devel) [Search](https://sourceforge.net/p/tcllib/mailman/search/?mail_list=tcllib-devel)| - -## Feedback - -Please go to and use our -[Local Trackers](../../../reportlist). -They are for - - * Bugs, - * Patches, and - * Ideas & Feature Requests. - -## Releases - - * [Current](../../../technote/cd3a11c3065120d491009e64a19f7676176045cd) __1.20 (Dec 1, 2019)__ - * [Past Releases](../../../wiki?name=Past+Releases) - * [Development Snapshots](../../../wiki?name=Development+Snapshots) - * [@ SourceForge](https://sourceforge.net/projects/tcllib/files/) - -## Related Repositories - - * [Tklib](../../../../tklib) - * [Tcl Apps](../../../../tclapps) - * [Tcl Bench](../../../../tclbench) - * [Multicolumn Listbox](../../../../mclistbox) - * [Widget](../../../../widget) - * [BWidget](../../../../bwidget) - - -## See also - - * [Landing page for this package at the Tcl Developer eXchange](http://www.tcl.tk/software/tcllib/) DELETED embedded/md/image/arch_core_container.png Index: embedded/md/image/arch_core_container.png ================================================================== --- embedded/md/image/arch_core_container.png +++ embedded/md/image/arch_core_container.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_eplugins.png Index: embedded/md/image/arch_core_eplugins.png ================================================================== --- embedded/md/image/arch_core_eplugins.png +++ embedded/md/image/arch_core_eplugins.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_export.png Index: embedded/md/image/arch_core_export.png ================================================================== --- embedded/md/image/arch_core_export.png +++ embedded/md/image/arch_core_export.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_import.png Index: embedded/md/image/arch_core_import.png ================================================================== --- embedded/md/image/arch_core_import.png +++ embedded/md/image/arch_core_import.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_iplugins.png Index: embedded/md/image/arch_core_iplugins.png ================================================================== --- embedded/md/image/arch_core_iplugins.png +++ embedded/md/image/arch_core_iplugins.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_support.png Index: embedded/md/image/arch_core_support.png ================================================================== --- embedded/md/image/arch_core_support.png +++ embedded/md/image/arch_core_support.png cannot compute difference between binary files DELETED embedded/md/image/arch_core_transform.png Index: embedded/md/image/arch_core_transform.png ================================================================== --- embedded/md/image/arch_core_transform.png +++ embedded/md/image/arch_core_transform.png cannot compute difference between binary files DELETED embedded/md/image/arch_user_app.png Index: embedded/md/image/arch_user_app.png ================================================================== --- embedded/md/image/arch_user_app.png +++ embedded/md/image/arch_user_app.png cannot compute difference between binary files DELETED embedded/md/image/arch_user_pkg.png Index: embedded/md/image/arch_user_pkg.png ================================================================== --- embedded/md/image/arch_user_pkg.png +++ embedded/md/image/arch_user_pkg.png cannot compute difference between binary files DELETED embedded/md/image/architecture.png Index: embedded/md/image/architecture.png ================================================================== --- embedded/md/image/architecture.png +++ embedded/md/image/architecture.png cannot compute difference between binary files DELETED embedded/md/image/expr_ast.png Index: embedded/md/image/expr_ast.png ================================================================== --- embedded/md/image/expr_ast.png +++ embedded/md/image/expr_ast.png cannot compute difference between binary files DELETED embedded/md/image/flow.png Index: embedded/md/image/flow.png ================================================================== --- embedded/md/image/flow.png +++ embedded/md/image/flow.png cannot compute difference between binary files DELETED embedded/md/image/gen_options.png Index: embedded/md/image/gen_options.png ================================================================== --- embedded/md/image/gen_options.png +++ embedded/md/image/gen_options.png cannot compute difference between binary files DELETED embedded/md/index.md Index: embedded/md/index.md ================================================================== --- embedded/md/index.md +++ embedded/md/index.md @@ -1,1034 +0,0 @@ - -[//000000001]: # (Index generated by tcllib/doctools/idx with format 'markdown') - -# Keyword Index - ----- - -[3](#c3) · [A](#cA) · [B](#cB) · [C](#cC) · [D](#cD) · [E](#cE) · [F](#cF) · [G](#cG) · [H](#cH) · [I](#cI) · [J](#cJ) · [K](#cK) · [L](#cL) · [M](#cM) · [N](#cN) · [O](#cO) · [P](#cP) · [Q](#cQ) · [R](#cR) · [S](#cS) · [T](#cT) · [U](#cU) · [V](#cV) · [W](#cW) · [X](#cX) · [Y](#cY) · [Z](#cZ) - ----- - -#### Keywords: 3 - -||| -|---|---| -|3DES|[des](tcllib/files/modules/des/des\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| - - -#### Keywords: A - -||| -|---|---| -|abstract syntax tree|[grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) · [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md)| -|acceptance|[grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md)| -|acceptor|[grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md)| -|active|[transfer::connect](tcllib/files/modules/transfer/connect\.md)| -|adaptors|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| -|adjacency list|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|adjacency matrix|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|adjacent|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|adjusting|[textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| -|adler32|[tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md)| -|aes|[aes](tcllib/files/modules/aes/aes\.md)| -|after|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|alias|[interp](tcllib/files/modules/interp/tcllib\_interp\.md)| -|amazon|[S3](tcllib/files/modules/amazon\-s3/S3\.md)| -|ambiguous|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)| -|American Express|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md)| -|AMEX|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md)| -|angle|[math::geometry](tcllib/files/modules/math/math\_geometry\.md) · [units](tcllib/files/modules/units/units\.md)| -|anonymous procedure|[lambda](tcllib/files/modules/lambda/lambda\.md)| -|ansi|[term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|appender|[logger::appender](tcllib/files/modules/log/loggerAppender\.md) · [logger::utils](tcllib/files/modules/log/loggerUtils\.md)| -|application|[nns](tcllib/files/apps/nns\.md) · [nnsd](tcllib/files/apps/nnsd\.md) · [nnslog](tcllib/files/apps/nnslog\.md)| -|approximation algorithm|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|arc|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|arcfour|[rc4](tcllib/files/modules/rc4/rc4\.md)| -|archive|[tar](tcllib/files/modules/tar/tar\.md)| -|argument integrity|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md)| -|argument processing|[cmdline](tcllib/files/modules/cmdline/cmdline\.md)| -|argument validation|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md)| -|arguments|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md)| -|argv|[cmdline](tcllib/files/modules/cmdline/cmdline\.md)| -|argv0|[cmdline](tcllib/files/modules/cmdline/cmdline\.md)| -|array|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|articulation point|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|ascii85|[ascii85](tcllib/files/modules/base64/ascii85\.md)| -|asn|[asn](tcllib/files/modules/asn/asn\.md)| -|assembler|[grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md)| -|assert|[control](tcllib/files/modules/control/control\.md)| -|assign|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|AST|[grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md)| -|asynchronous|[cache::async](tcllib/files/modules/cache/async\.md)| -|attribute control|[term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md)| -|augmenting network|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|augmenting path|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|authentication|[autoproxy](tcllib/files/modules/http/autoproxy\.md) · [SASL](tcllib/files/modules/sasl/sasl\.md) · [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) · [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) · [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md)| -|automatic|[nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md)| -|automatic documentation|[tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md)| -|automaton|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md)| -|aycock|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)| - - -#### Keywords: B - -||| -|---|---| -|bank|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md)| -|base32|[base32](tcllib/files/modules/base32/base32\.md) · [base32::core](tcllib/files/modules/base32/base32core\.md) · [base32::hex](tcllib/files/modules/base32/base32hex\.md)| -|base64|[base64](tcllib/files/modules/base64/base64\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md)| -|bash|[string::token::shell](tcllib/files/modules/string/token\_shell\.md)| -|bee|[bee](tcllib/files/modules/bee/bee\.md)| -|bench language|[bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) · [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) · [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md)| -|benchmark|[bench](tcllib/files/modules/bench/bench\.md) · [bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) · [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) · [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) · [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md)| -|ber|[asn](tcllib/files/modules/asn/asn\.md)| -|Bessel functions|[math::special](tcllib/files/modules/math/special\.md)| -|bfs|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|bibliography|[bibtex](tcllib/files/modules/bibtex/bibtex\.md)| -|bibtex|[bibtex](tcllib/files/modules/bibtex/bibtex\.md)| -|bignums|[math::bignum](tcllib/files/modules/math/bignum\.md)| -|bind|[uevent](tcllib/files/modules/uev/uevent\.md)| -|bipartite|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|BitTorrent|[bee](tcllib/files/modules/bee/bee\.md)| -|bittorrent|[bee](tcllib/files/modules/bee/bee\.md)| -|blanks|[textutil::repeat](tcllib/files/modules/textutil/repeat\.md)| -|block cipher|[aes](tcllib/files/modules/aes/aes\.md) · [blowfish](tcllib/files/modules/blowfish/blowfish\.md) · [des](tcllib/files/modules/des/des\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| -|blocking flow|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|blowfish|[blowfish](tcllib/files/modules/blowfish/blowfish\.md)| -|Book Number|[valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|breadth\-first|[struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|bridge|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|BWidget|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| - - -#### Keywords: C - -||| -|---|---| -|C|[doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md)| -|C\+\+|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md) · [stooop](tcllib/files/modules/stooop/stooop\.md) · [switched](tcllib/files/modules/stooop/switched\.md)| -|cache|[cache::async](tcllib/files/modules/cache/async\.md) · [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md)| -|caesar cipher|[tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md)| -|calculus|[math::calculus](tcllib/files/modules/math/calculus\.md)| -|callback|[cache::async](tcllib/files/modules/cache/async\.md) · [hook](tcllib/files/modules/hook/hook\.md) · [lambda](tcllib/files/modules/lambda/lambda\.md) · [oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md) · [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|callbacks|[tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md)| -|capitalize|[textutil::string](tcllib/files/modules/textutil/textutil\_string\.md)| -|card for credit|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md)| -|cardinality|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|cat|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)| -|catalog package|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|catalogue|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)| -|cell\-phone|[valtype::imei](tcllib/files/modules/valtype/imei\.md)| -|cer|[asn](tcllib/files/modules/asn/asn\.md)| -|CFG|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md)| -|CFL|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md)| -|CGI|[ncgi](tcllib/files/modules/ncgi/ncgi\.md)| -|cgraph|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md)| -|changelog|[doctools::changelog](tcllib/files/modules/doctools/changelog\.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs\.md)| -|channel|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) · [transfer::connect](tcllib/files/modules/transfer/connect\.md) · [transfer::copy](tcllib/files/modules/transfer/copyops\.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|channel transformation|[tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|character input|[term::receive](tcllib/files/modules/term/receive\.md) · [term::receive::bind](tcllib/files/modules/term/term\_bind\.md)| -|character output|[term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) · [term::send](tcllib/files/modules/term/term\_send\.md)| -|chat|[irc](tcllib/files/modules/irc/irc\.md) · [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) · [picoirc](tcllib/files/modules/irc/picoirc\.md)| -|checkbox|[html](tcllib/files/modules/html/html\.md) · [javascript](tcllib/files/modules/javascript/javascript\.md)| -|checkbutton|[html](tcllib/files/modules/html/html\.md)| -|Checking|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|checksum|[cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [sum](tcllib/files/modules/crc/sum\.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md)| -|chop|[textutil::string](tcllib/files/modules/textutil/textutil\_string\.md)| -|cipher|[pki](tcllib/files/modules/pki/pki\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md)| -|cksum|[cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [sum](tcllib/files/modules/crc/sum\.md)| -|class|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md) · [stooop](tcllib/files/modules/stooop/stooop\.md) · [switched](tcllib/files/modules/stooop/switched\.md)| -|class methods|[oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|class variables|[oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|cleanup|[defer](tcllib/files/modules/defer/defer\.md) · [try](tcllib/files/modules/try/tcllib\_try\.md)| -|client|[nameserv](tcllib/files/modules/nns/nns\_client\.md) · [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) · [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) · [nns](tcllib/files/apps/nns\.md) · [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) · [nnslog](tcllib/files/apps/nnslog\.md)| -|cloud|[S3](tcllib/files/modules/amazon\-s3/S3\.md)| -|cmdline processing|[cmdline](tcllib/files/modules/cmdline/cmdline\.md)| -|color control|[term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md)| -|columns|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|comm|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) · [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) · [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) · [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md)| -|command|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md)| -|command line processing|[cmdline](tcllib/files/modules/cmdline/cmdline\.md)| -|command prefix|[lambda](tcllib/files/modules/lambda/lambda\.md) · [oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|comment|[jpeg](tcllib/files/modules/jpeg/jpeg\.md) · [png](tcllib/files/modules/png/png\.md)| -|common|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|common prefix|[textutil::string](tcllib/files/modules/textutil/textutil\_string\.md)| -|communication|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md)| -|comparison|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|complete graph|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|complex numbers|[math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) · [math::fourier](tcllib/files/modules/math/fourier\.md)| -|compression|[tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) · [zipfile::encode](tcllib/files/modules/zip/encode\.md)| -|computations|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md)| -|concatenation channel|[tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md)| -|connected component|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|connected fifos|[tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md)| -|connection|[transfer::connect](tcllib/files/modules/transfer/connect\.md)| -|constants|[math::constants](tcllib/files/modules/math/constants\.md) · [units](tcllib/files/modules/units/units\.md)| -|CONTAINER|[pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md)| -|contents|[doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md)| -|context\-free grammar|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md)| -|context\-free languages|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|control|[control](tcllib/files/modules/control/control\.md) · [math::changepoint](tcllib/files/modules/math/changepoint\.md) · [term](tcllib/files/modules/term/term\.md) · [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) · [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) · [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) · [term::interact::menu](tcllib/files/modules/term/imenu\.md) · [term::interact::pager](tcllib/files/modules/term/ipager\.md) · [term::receive](tcllib/files/modules/term/receive\.md) · [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) · [term::send](tcllib/files/modules/term/term\_send\.md)| -|control structure|[generator](tcllib/files/modules/generator/generator\.md)| -|conversion|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [math::roman](tcllib/files/modules/math/roman\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) · [units](tcllib/files/modules/units/units\.md)| -|cooked|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|cookie|[ncgi](tcllib/files/modules/ncgi/ncgi\.md)| -|copy|[fileutil::multi](tcllib/files/modules/fileutil/multi\.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) · [transfer::copy](tcllib/files/modules/transfer/copyops\.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|coroutine|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) · [generator](tcllib/files/modules/generator/generator\.md)| -|Cost|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|counter|[tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md)| -|counting|[counter](tcllib/files/modules/counter/counter\.md)| -|CPARAM|[pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md)| -|crc|[cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [sum](tcllib/files/modules/crc/sum\.md)| -|crc16|[crc16](tcllib/files/modules/crc/crc16\.md)| -|crc32|[cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [sum](tcllib/files/modules/crc/sum\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md)| -|credit card|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md)| -|cron|[cron](tcllib/files/modules/cron/cron\.md)| -|cryptography|[blowfish](tcllib/files/modules/blowfish/blowfish\.md)| -|CSS|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md)| -|csv|[bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) · [csv](tcllib/files/modules/csv/csv\.md)| -|currying|[lambda](tcllib/files/modules/lambda/lambda\.md) · [oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|cut edge|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|cut vertex|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|CVS|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|cvs|[doctools::cvs](tcllib/files/modules/doctools/cvs\.md)| -|cvs log|[doctools::cvs](tcllib/files/modules/doctools/cvs\.md)| -|cyclic redundancy check|[cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [sum](tcllib/files/modules/crc/sum\.md)| - - -#### Keywords: D - -||| -|---|---| -|data analysis|[math::statistics](tcllib/files/modules/math/statistics\.md)| -|data destination|[transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md)| -|data entry form|[tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md)| -|data exchange|[huddle](tcllib/files/modules/yaml/huddle\.md) · [json](tcllib/files/modules/json/json\.md) · [json::write](tcllib/files/modules/json/json\_write\.md) · [yaml](tcllib/files/modules/yaml/yaml\.md)| -|data integrity|[aes](tcllib/files/modules/aes/aes\.md) · [cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [des](tcllib/files/modules/des/des\.md) · [pki](tcllib/files/modules/pki/pki\.md) · [rc4](tcllib/files/modules/rc4/rc4\.md) · [sum](tcllib/files/modules/crc/sum\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| -|data source|[transfer::data::source](tcllib/files/modules/transfer/dsource\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|data structures|[struct::record](tcllib/files/modules/struct/record\.md)| -|database|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|dataflow|[page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md)| -|\.ddt|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)| -|DE|[doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md)| -|debug|[debug](tcllib/files/modules/debug/debug\.md) · [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) · [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) · [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md)| -|decimal|[math::decimal](tcllib/files/modules/math/decimal\.md)| -|declare|[term::ansi::code](tcllib/files/modules/term/ansi\_code\.md)| -|decompression|[tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) · [zipfile::decode](tcllib/files/modules/zip/decode\.md) · [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md)| -|decryption|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md)| -|deferal|[uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|define|[term::ansi::code](tcllib/files/modules/term/ansi\_code\.md)| -|degree|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|degree constrained spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|degrees|[math::constants](tcllib/files/modules/math/constants\.md)| -|delegation|[deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) · [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md)| -|depth\-first|[struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|der|[asn](tcllib/files/modules/asn/asn\.md)| -|DES|[des](tcllib/files/modules/des/des\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| -|deserialization|[doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md)| -|/dev/null|[tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md)| -|/dev/random|[tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) · [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md)| -|/dev/zero|[tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md)| -|diameter|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|dict|[dicttool](tcllib/files/modules/dicttool/dicttool\.md)| -|diff|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|diff \-n format|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|diff \-ruN|[textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|diff, unified format|[textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|difference|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|differential|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|differential equations|[math::calculus](tcllib/files/modules/math/calculus\.md)| -|digital|[math::filters](tcllib/files/modules/math/filtergen\.md)| -|dijkstra|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|directory access|[ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md)| -|directory traversal|[fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md)| -|Discover|[valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md)| -|discrete items|[struct::pool](tcllib/files/modules/struct/pool\.md)| -|disjoint set|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|dispatcher|[term::receive::bind](tcllib/files/modules/term/term\_bind\.md)| -|distance|[math::geometry](tcllib/files/modules/math/math\_geometry\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md) · [units](tcllib/files/modules/units/units\.md)| -|DNS|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|do|[control](tcllib/files/modules/control/control\.md)| -|docidx|[doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) · [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) · [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md)| -|docidx commands|[docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md)| -|docidx language|[docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md)| -|docidx markup|[docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md)| -|docidx syntax|[docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md)| -|docstrip|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| -|doctoc|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md)| -|doctoc commands|[doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md)| -|doctoc language|[doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md)| -|doctoc markup|[doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md)| -|doctoc syntax|[doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md)| -|doctools|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) · [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) · [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) · [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) · [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md)| -|doctools commands|[doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md)| -|doctools language|[doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md)| -|doctools markup|[doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md)| -|doctools syntax|[doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md)| -|document|[doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)| -|documentation|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) · [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md)| -|DOM|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|dom|[xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md)| -|domain name service|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|\.dtx|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| - - -#### Keywords: E - -||| -|---|---| -|e|[math::constants](tcllib/files/modules/math/constants\.md)| -|EAN|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|EAN13|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|earley|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)| -|EBNF|[pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|eccentricity|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|edge|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|emacs|[doctools::changelog](tcllib/files/modules/doctools/changelog\.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs\.md)| -|email|[imap4](tcllib/files/modules/imap4/imap4\.md) · [mime](tcllib/files/modules/mime/mime\.md) · [pop3](tcllib/files/modules/pop3/pop3\.md) · [smtp](tcllib/files/modules/mime/smtp\.md)| -|emptiness|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|empty interpreter|[interp](tcllib/files/modules/interp/tcllib\_interp\.md)| -|EN|[doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md)| -|encoding|[ascii85](tcllib/files/modules/base64/ascii85\.md) · [base64](tcllib/files/modules/base64/base64\.md) · [uuencode](tcllib/files/modules/base64/uuencode\.md) · [yencode](tcllib/files/modules/base64/yencode\.md)| -|encryption|[aes](tcllib/files/modules/aes/aes\.md) · [blowfish](tcllib/files/modules/blowfish/blowfish\.md) · [des](tcllib/files/modules/des/des\.md) · [pki](tcllib/files/modules/pki/pki\.md) · [rc4](tcllib/files/modules/rc4/rc4\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| -|entry mask|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md)| -|equal|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|equality|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|equivalence class|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|error|[throw](tcllib/files/modules/try/tcllib\_throw\.md) · [try](tcllib/files/modules/try/tcllib\_try\.md)| -|error function|[math::special](tcllib/files/modules/math/special\.md)| -|European Article Number|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|event|[hook](tcllib/files/modules/hook/hook\.md) · [uevent](tcllib/files/modules/uev/uevent\.md) · [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|event management|[tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md)| -|events|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|examples|[bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md)| -|exception|[try](tcllib/files/modules/try/tcllib\_try\.md)| -|exchange format|[huddle](tcllib/files/modules/yaml/huddle\.md) · [json](tcllib/files/modules/json/json\.md) · [json::write](tcllib/files/modules/json/json\_write\.md)| -|exclusion|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|execution|[grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md)| -|exif|[jpeg](tcllib/files/modules/jpeg/jpeg\.md)| -|exit|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|export|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) · [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md)| -|expression|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|extended namespace|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| - - -#### Keywords: F - -||| -|---|---| -|faq|[docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md)| -|fetching information|[uri](tcllib/files/modules/uri/uri\.md)| -|FFT|[math::fourier](tcllib/files/modules/math/fourier\.md)| -|fifo|[tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md)| -|file|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md) · [uri](tcllib/files/modules/uri/uri\.md)| -|file recognition|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md)| -|file type|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md)| -|file utilities|[fileutil](tcllib/files/modules/fileutil/fileutil\.md) · [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) · [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md)| -|filesystem|[map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md)| -|filter|[generator](tcllib/files/modules/generator/generator\.md) · [struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|filtering|[math::filters](tcllib/files/modules/math/filtergen\.md)| -|final|[try](tcllib/files/modules/try/tcllib\_try\.md)| -|finance|[valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md)| -|find|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|finite|[struct::pool](tcllib/files/modules/struct/pool\.md)| -|finite automaton|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md)| -|FIPS 180\-1|[sha1](tcllib/files/modules/sha1/sha1\.md) · [sha256](tcllib/files/modules/sha1/sha256\.md)| -|first permutation|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|Fisher\-Yates|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|flatten|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|floating\-point|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md) · [math::fuzzy](tcllib/files/modules/math/fuzzy\.md)| -|flow|[control](tcllib/files/modules/control/control\.md)| -|flow network|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|folding|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|foldl|[generator](tcllib/files/modules/generator/generator\.md)| -|foldr|[generator](tcllib/files/modules/generator/generator\.md)| -|foreach|[generator](tcllib/files/modules/generator/generator\.md)| -|form|[html](tcllib/files/modules/html/html\.md) · [ncgi](tcllib/files/modules/ncgi/ncgi\.md)| -|format conversion|[pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md)| -|formatter|[doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)| -|formatting|[bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) · [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) · [textutil::tabify](tcllib/files/modules/textutil/tabify\.md)| -|formatting engine|[docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)| -|fossil|[textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|Fourier transform|[math::fourier](tcllib/files/modules/math/fourier\.md)| -|FR|[doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|frame|[term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md)| -|framework|[tool](tcllib/files/modules/tool/tool\.md)| -|ftp|[ftp](tcllib/files/modules/ftp/ftp\.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) · [ftpd](tcllib/files/modules/ftpd/ftpd\.md) · [uri](tcllib/files/modules/uri/uri\.md)| -|ftpd|[ftpd](tcllib/files/modules/ftpd/ftpd\.md)| -|ftpserver|[ftpd](tcllib/files/modules/ftpd/ftpd\.md)| -|full outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| - - -#### Keywords: G - -||| -|---|---| -|generate event|[uevent](tcllib/files/modules/uev/uevent\.md)| -|generate permutations|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|generation|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md)| -|generator|[generator](tcllib/files/modules/generator/generator\.md)| -|geocoding|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md)| -|geodesy|[map::slippy](tcllib/files/modules/map/map\_slippy\.md) · [mapproj](tcllib/files/modules/mapproj/mapproj\.md)| -|geography|[map::slippy](tcllib/files/modules/map/map\_slippy\.md)| -|get character|[term::receive](tcllib/files/modules/term/receive\.md)| -|gets|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|git|[textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|global|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|golang|[defer](tcllib/files/modules/defer/defer\.md)| -|gopher|[uri](tcllib/files/modules/uri/uri\.md)| -|gps|[gpx](tcllib/files/modules/gpx/gpx\.md) · [nmea](tcllib/files/modules/nmea/nmea\.md)| -|gpx|[gpx](tcllib/files/modules/gpx/gpx\.md)| -|grammar|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) · [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) · [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) · [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) · [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|graph|[grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) · [struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md) · [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::stack](tcllib/files/modules/struct/stack\.md)| -|graph walking|[page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md)| -|green threads|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|grep|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)| -|GUID|[uuid](tcllib/files/modules/uuid/uuid\.md)| - - -#### Keywords: H - -||| -|---|---| -|hashing|[md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) · [otp](tcllib/files/modules/otp/otp\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) · [sha1](tcllib/files/modules/sha1/sha1\.md) · [sha256](tcllib/files/modules/sha1/sha256\.md)| -|heartbeat|[debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md)| -|heuristic|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|hex|[base32::hex](tcllib/files/modules/base32/base32hex\.md)| -|hexadecimal|[tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md)| -|histogram|[counter](tcllib/files/modules/counter/counter\.md)| -|hook|[hook](tcllib/files/modules/hook/hook\.md) · [uevent](tcllib/files/modules/uev/uevent\.md)| -|horspool|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md)| -|HTML|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)| -|html|[html](tcllib/files/modules/html/html\.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) · [javascript](tcllib/files/modules/javascript/javascript\.md) · [ncgi](tcllib/files/modules/ncgi/ncgi\.md)| -|http|[autoproxy](tcllib/files/modules/http/autoproxy\.md) · [httpd](tcllib/files/modules/httpd/httpd\.md) · [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) · [uri](tcllib/files/modules/uri/uri\.md) · [websocket](tcllib/files/modules/websocket/websocket\.md)| -|httpd|[httpd](tcllib/files/modules/httpd/httpd\.md)| -|https|[uri](tcllib/files/modules/uri/uri\.md)| -|httpserver|[httpd](tcllib/files/modules/httpd/httpd\.md)| -|huddle|[huddle](tcllib/files/modules/yaml/huddle\.md) · [yaml](tcllib/files/modules/yaml/yaml\.md)| -|human readable|[bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md)| -|hyphenation|[textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| - - -#### Keywords: I - -||| -|---|---| -|i18n|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|IBAN|[valtype::iban](tcllib/files/modules/valtype/iban\.md)| -|ident|[ident](tcllib/files/modules/ident/ident\.md)| -|identification|[ident](tcllib/files/modules/ident/ident\.md)| -|identity|[tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md)| -|idle|[uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|image|[jpeg](tcllib/files/modules/jpeg/jpeg\.md) · [png](tcllib/files/modules/png/png\.md) · [tiff](tcllib/files/modules/tiff/tiff\.md)| -|imap|[imap4](tcllib/files/modules/imap4/imap4\.md)| -|IMEI|[valtype::imei](tcllib/files/modules/valtype/imei\.md)| -|import|[doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md)| -|in\-memory channel|[tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) · [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md)| -|in\-order|[struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|inclusion|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|Incr Tcl|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| -|indenting|[textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| -|independent set|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|index|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) · [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md)| -|index formatter|[docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md)| -|info|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|inner join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|input mode|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|integer|[math::roman](tcllib/files/modules/math/roman\.md)| -|integration|[math::calculus](tcllib/files/modules/math/calculus\.md)| -|inter\-thread communication|[tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md)| -|International Article Number|[valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|International Bank Account Number|[valtype::iban](tcllib/files/modules/valtype/iban\.md)| -|International Mobile Equipment Identity|[valtype::imei](tcllib/files/modules/valtype/imei\.md)| -|International Standard Book Number|[valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|internationalization|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|internet|[asn](tcllib/files/modules/asn/asn\.md) · [ftp](tcllib/files/modules/ftp/ftp\.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) · [imap4](tcllib/files/modules/imap4/imap4\.md) · [ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md) · [mime](tcllib/files/modules/mime/mime\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) · [smtp](tcllib/files/modules/mime/smtp\.md) · [websocket](tcllib/files/modules/websocket/websocket\.md)| -|internet address|[tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md)| -|interpolation|[math::interpolate](tcllib/files/modules/math/interpolate\.md)| -|interpreter|[deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) · [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) · [interp](tcllib/files/modules/interp/tcllib\_interp\.md) · [wip](tcllib/files/modules/wip/wip\.md)| -|intersection|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|interval|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md)| -|ip|[tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md)| -|ipc|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md)| -|ipv4|[tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md)| -|ipv6|[tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md)| -|irc|[irc](tcllib/files/modules/irc/irc\.md) · [picoirc](tcllib/files/modules/irc/picoirc\.md)| -|isA|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|ISBN|[valtype::isbn](tcllib/files/modules/valtype/isbn\.md)| -|isthmus|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|iterator|[generator](tcllib/files/modules/generator/generator\.md)| - - -#### Keywords: J - -||| -|---|---| -|javascript|[javascript](tcllib/files/modules/javascript/javascript\.md) · [json](tcllib/files/modules/json/json\.md) · [json::write](tcllib/files/modules/json/json\_write\.md)| -|jfif|[jpeg](tcllib/files/modules/jpeg/jpeg\.md)| -|join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|jpeg|[jpeg](tcllib/files/modules/jpeg/jpeg\.md)| -|JSON|[doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) · [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md)| -|json|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [huddle](tcllib/files/modules/yaml/huddle\.md) · [json](tcllib/files/modules/json/json\.md) · [json::write](tcllib/files/modules/json/json\_write\.md)| -|justification|[textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| - - -#### Keywords: K - -||| -|---|---| -|keyword index|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md)| -|keywords|[docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md)| -|knuth|[soundex](tcllib/files/modules/soundex/soundex\.md)| - - -#### Keywords: L - -||| -|---|---| -|l10n|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|lambda|[lambda](tcllib/files/modules/lambda/lambda\.md)| -|LaTeX|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| -|latex|[doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md)| -|latitute|[map::slippy](tcllib/files/modules/map/map\_slippy\.md)| -|ldap|[ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md) · [uri](tcllib/files/modules/uri/uri\.md)| -|ldap client|[ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md)| -|ldif|[ldapx](tcllib/files/modules/ldap/ldapx\.md)| -|least squares|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)| -|left outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|lemon|[page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md)| -|level graph|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|lexer|[doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md)| -|lexing|[string::token](tcllib/files/modules/string/token\.md) · [string::token::shell](tcllib/files/modules/string/token\_shell\.md)| -|limitsize|[tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md)| -|line|[math::geometry](tcllib/files/modules/math/math\_geometry\.md)| -|linear algebra|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)| -|linear equations|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)| -|linear program|[math::optimize](tcllib/files/modules/math/optimize\.md)| -|lines|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|list|[struct::list](tcllib/files/modules/struct/struct\_list\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md) · [wip](tcllib/files/modules/wip/wip\.md)| -|listener|[term::receive](tcllib/files/modules/term/receive\.md) · [term::receive::bind](tcllib/files/modules/term/term\_bind\.md)| -|literate programming|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| -|LL\(k\)|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|local searching|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|localization|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|location|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy](tcllib/files/modules/map/map\_slippy\.md) · [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md)| -|log|[debug](tcllib/files/modules/debug/debug\.md) · [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) · [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) · [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) · [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) · [log](tcllib/files/modules/log/log\.md) · [logger](tcllib/files/modules/log/logger\.md)| -|log level|[log](tcllib/files/modules/log/log\.md) · [logger](tcllib/files/modules/log/logger\.md)| -|logger|[logger](tcllib/files/modules/log/logger\.md) · [logger::appender](tcllib/files/modules/log/loggerAppender\.md) · [logger::utils](tcllib/files/modules/log/loggerUtils\.md)| -|longest common subsequence|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|longitude|[map::slippy](tcllib/files/modules/map/map\_slippy\.md)| -|loop|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|luhn|[valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md)| -|luhn\-5|[valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md)| - - -#### Keywords: M - -||| -|---|---| -|macros|[doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md)| -|mail|[imap4](tcllib/files/modules/imap4/imap4\.md) · [mime](tcllib/files/modules/mime/mime\.md) · [pop3](tcllib/files/modules/pop3/pop3\.md) · [smtp](tcllib/files/modules/mime/smtp\.md)| -|mailto|[uri](tcllib/files/modules/uri/uri\.md)| -|man\_macros|[doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md)| -|manpage|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)| -|map|[generator](tcllib/files/modules/generator/generator\.md) · [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy](tcllib/files/modules/map/map\_slippy\.md) · [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) · [mapproj](tcllib/files/modules/mapproj/mapproj\.md) · [struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|markdown|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md)| -|markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) · [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) · [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) · [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) · [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) · [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) · [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| -|MasterCard|[valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md)| -|matching|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|math|[math](tcllib/files/modules/math/math\.md) · [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) · [math::bignum](tcllib/files/modules/math/bignum\.md) · [math::calculus](tcllib/files/modules/math/calculus\.md) · [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) · [math::constants](tcllib/files/modules/math/constants\.md) · [math::decimal](tcllib/files/modules/math/decimal\.md) · [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) · [math::geometry](tcllib/files/modules/math/math\_geometry\.md) · [math::interpolate](tcllib/files/modules/math/interpolate\.md) · [math::linearalgebra](tcllib/files/modules/math/linalg\.md) · [math::optimize](tcllib/files/modules/math/optimize\.md) · [math::PCA](tcllib/files/modules/math/pca\.md) · [math::polynomials](tcllib/files/modules/math/polynomials\.md) · [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) · [math::special](tcllib/files/modules/math/special\.md) · [math::trig](tcllib/files/modules/math/trig\.md) · [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) · [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) · [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)| -|mathematics|[math::fourier](tcllib/files/modules/math/fourier\.md) · [math::probopt](tcllib/files/modules/math/probopt\.md) · [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) · [math::statistics](tcllib/files/modules/math/statistics\.md)| -|matrices|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)| -|matrix|[csv](tcllib/files/modules/csv/csv\.md) · [math::linearalgebra](tcllib/files/modules/math/linalg\.md) · [report](tcllib/files/modules/report/report\.md) · [struct::matrix](tcllib/files/modules/struct/matrix\.md) · [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::stack](tcllib/files/modules/struct/stack\.md)| -|max cut|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|maximum|[math::optimize](tcllib/files/modules/math/optimize\.md)| -|maximum flow|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|md4|[md4](tcllib/files/modules/md4/md4\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)| -|md5|[md5](tcllib/files/modules/md5/md5\.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md)| -|md5crypt|[md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md)| -|medicare|[valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md)| -|mega widget|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| -|membership|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|menu|[term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) · [term::interact::menu](tcllib/files/modules/term/imenu\.md)| -|merge|[tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) · [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|merge find|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|merging|[bench](tcllib/files/modules/bench/bench\.md)| -|message|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) · [log](tcllib/files/modules/log/log\.md)| -|message catalog|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|message level|[log](tcllib/files/modules/log/log\.md)| -|message package|[doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) · [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) · [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) · [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) · [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) · [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) · [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) · [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) · [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md)| -|message\-digest|[md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) · [otp](tcllib/files/modules/otp/otp\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) · [sha1](tcllib/files/modules/sha1/sha1\.md) · [sha256](tcllib/files/modules/sha1/sha256\.md)| -|metakit|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|method|[deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) · [interp](tcllib/files/modules/interp/tcllib\_interp\.md)| -|method reference|[oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|mime|[fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) · [mime](tcllib/files/modules/mime/mime\.md) · [smtp](tcllib/files/modules/mime/smtp\.md)| -|minimal spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|minimum|[math::optimize](tcllib/files/modules/math/optimize\.md)| -|minimum cost flow|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|minimum degree spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|minimum diameter spanning tree|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|mobile phone|[valtype::imei](tcllib/files/modules/valtype/imei\.md)| -|module|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)| -|montecarlo simulation|[simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md)| -|move|[fileutil::multi](tcllib/files/modules/fileutil/multi\.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md)| -|multi\-file|[fileutil::multi](tcllib/files/modules/fileutil/multi\.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md)| -|multiplexer|[multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md)| -|multiprecision|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md) · [math::bignum](tcllib/files/modules/math/bignum\.md)| -|my method|[oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| - - -#### Keywords: N - -||| -|---|---| -|name service|[nameserv](tcllib/files/modules/nns/nns\_client\.md) · [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) · [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) · [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) · [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) · [nns](tcllib/files/apps/nns\.md) · [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) · [nnsd](tcllib/files/apps/nnsd\.md) · [nnslog](tcllib/files/apps/nnslog\.md) · [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md)| -|namespace unknown|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|namespace utilities|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|narrative|[debug](tcllib/files/modules/debug/debug\.md) · [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) · [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) · [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md)| -|National Provider Identifier|[valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md)| -|neighbour|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|net|[ftp](tcllib/files/modules/ftp/ftp\.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) · [imap4](tcllib/files/modules/imap4/imap4\.md) · [mime](tcllib/files/modules/mime/mime\.md) · [smtp](tcllib/files/modules/mime/smtp\.md) · [websocket](tcllib/files/modules/websocket/websocket\.md)| -|nettool|[nettool](tcllib/files/modules/nettool/nettool\.md)| -|network|[pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md)| -|news|[nntp](tcllib/files/modules/nntp/nntp\.md) · [uri](tcllib/files/modules/uri/uri\.md)| -|next permutation|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|nmea|[nmea](tcllib/files/modules/nmea/nmea\.md)| -|nntp|[nntp](tcllib/files/modules/nntp/nntp\.md)| -|nntpclient|[nntp](tcllib/files/modules/nntp/nntp\.md)| -|no\-op|[control](tcllib/files/modules/control/control\.md)| -|node|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md) · [struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|nominatim|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md)| -|normalization|[bench](tcllib/files/modules/bench/bench\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) · [unicode](tcllib/files/modules/stringprep/unicode\.md)| -|NPI|[valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md)| -|nroff|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) · [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)| -|NTLM|[SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md)| -|NTP|[ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md)| -|null|[tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md)| -|number theory|[math::numtheory](tcllib/files/modules/math/numtheory\.md)| - - -#### Keywords: O - -||| -|---|---| -|oauth|[oauth](tcllib/files/modules/oauth/oauth\.md)| -|object|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md) · [stooop](tcllib/files/modules/stooop/stooop\.md) · [switched](tcllib/files/modules/stooop/switched\.md)| -|object oriented|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md) · [stooop](tcllib/files/modules/stooop/stooop\.md) · [switched](tcllib/files/modules/stooop/switched\.md)| -|observer|[hook](tcllib/files/modules/hook/hook\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md)| -|odie|[cron](tcllib/files/modules/cron/cron\.md) · [nettool](tcllib/files/modules/nettool/nettool\.md) · [processman](tcllib/files/modules/processman/processman\.md)| -|on\-idle|[uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md)| -|one time pad|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)| -|oo|[clay](tcllib/files/modules/clay/clay\.md)| -|optimisation|[math::probopt](tcllib/files/modules/math/probopt\.md)| -|optimization|[math::optimize](tcllib/files/modules/math/optimize\.md) · [simulation::annealing](tcllib/files/modules/simulation/annealing\.md)| -|ordered list|[struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md)| -|otp|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)| -|outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| - - -#### Keywords: P - -||| -|---|---| -|package|[csv](tcllib/files/modules/csv/csv\.md)| -|package indexing|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)| -|page|[page\_intro](tcllib/files/modules/page/page\_intro\.md) · [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) · [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) · [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md)| -|pager|[term::interact::pager](tcllib/files/modules/term/ipager\.md)| -|paragraph|[textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| -|PARAM|[pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md)| -|parameter entry form|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md)| -|parser|[doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) · [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) · [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) · [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) · [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md)| -|parser generator|[page](tcllib/files/apps/page\.md) · [page\_intro](tcllib/files/modules/page/page\_intro\.md) · [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) · [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) · [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md)| -|parsing|[bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bibtex](tcllib/files/modules/bibtex/bibtex\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) · [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) · [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) · [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) · [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) · [huddle](tcllib/files/modules/yaml/huddle\.md) · [string::token::shell](tcllib/files/modules/string/token\_shell\.md) · [yaml](tcllib/files/modules/yaml/yaml\.md)| -|parsing expression|[grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|parsing expression grammar|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|partial application|[lambda](tcllib/files/modules/lambda/lambda\.md)| -|partition|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|partitioned set|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md)| -|passive|[transfer::connect](tcllib/files/modules/transfer/connect\.md)| -|password|[otp](tcllib/files/modules/otp/otp\.md)| -|patch|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|patching|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|PCA|[math::PCA](tcllib/files/modules/math/pca\.md)| -|PEG|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) · [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|performance|[bench](tcllib/files/modules/bench/bench\.md) · [bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) · [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) · [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) · [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) · [profiler](tcllib/files/modules/profiler/profiler\.md)| -|permutation|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|persistence|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|phone|[valtype::imei](tcllib/files/modules/valtype/imei\.md)| -|pi|[math::constants](tcllib/files/modules/math/constants\.md)| -|plain text|[doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md)| -|plane geometry|[math::geometry](tcllib/files/modules/math/math\_geometry\.md)| -|plugin|[docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md)| -|plugin management|[pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md)| -|plugin search|[pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md)| -|png|[png](tcllib/files/modules/png/png\.md)| -|point|[math::geometry](tcllib/files/modules/math/math\_geometry\.md)| -|polynomial functions|[math::polynomials](tcllib/files/modules/math/polynomials\.md)| -|pool|[struct::pool](tcllib/files/modules/struct/pool\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md)| -|pop|[pop3](tcllib/files/modules/pop3/pop3\.md)| -|pop3|[pop3](tcllib/files/modules/pop3/pop3\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md)| -|post\-order|[struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|practcl|[practcl](tcllib/files/modules/practcl/practcl\.md)| -|pre\-order|[struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|prefix|[textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) · [textutil::trim](tcllib/files/modules/textutil/trim\.md)| -|prime|[math::numtheory](tcllib/files/modules/math/numtheory\.md)| -|prioqueue|[struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md)| -|priority queue|[struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md)| -|probabilistic calculations|[math::probopt](tcllib/files/modules/math/probopt\.md)| -|proc|[lambda](tcllib/files/modules/lambda/lambda\.md)| -|procedure|[deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) · [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md)| -|procedure documentation|[tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md)| -|processman|[processman](tcllib/files/modules/processman/processman\.md)| -|producer|[hook](tcllib/files/modules/hook/hook\.md)| -|profile|[profiler](tcllib/files/modules/profiler/profiler\.md)| -|projection|[mapproj](tcllib/files/modules/mapproj/mapproj\.md)| -|prospero|[uri](tcllib/files/modules/uri/uri\.md)| -|protocol|[asn](tcllib/files/modules/asn/asn\.md) · [ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md) · [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) · [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md)| -|proxy|[autoproxy](tcllib/files/modules/http/autoproxy\.md)| -|public key cipher|[pki](tcllib/files/modules/pki/pki\.md)| -|publisher|[hook](tcllib/files/modules/hook/hook\.md)| -|push down automaton|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| - - -#### Keywords: Q - -||| -|---|---| -|quasi\-random|[math::quasirandom](tcllib/files/modules/math/quasirandom\.md)| -|queue|[csv](tcllib/files/modules/csv/csv\.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) · [struct::stack](tcllib/files/modules/struct/stack\.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md)| -|quoting|[page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md)| - - -#### Keywords: R - -||| -|---|---| -|radians|[math::constants](tcllib/files/modules/math/constants\.md) · [units](tcllib/files/modules/units/units\.md)| -|radiobutton|[html](tcllib/files/modules/html/html\.md)| -|radius|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|random|[tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) · [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md)| -|random numbers|[simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)| -|rational functions|[math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md)| -|raw|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|rc4|[rc4](tcllib/files/modules/rc4/rc4\.md)| -|RCS|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|RCS patch|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|read|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|reading|[bench::in](tcllib/files/modules/bench/bench\_read\.md)| -|receiver|[term::receive](tcllib/files/modules/term/receive\.md) · [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md)| -|reconnect|[nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md)| -|record|[struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::record](tcllib/files/modules/struct/record\.md)| -|recursive descent|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|reduce|[generator](tcllib/files/modules/generator/generator\.md) · [struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|reference|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md)| -|reflected channel|[tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) · [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) · [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) · [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) · [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) · [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) · [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) · [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) · [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|regex|[string::token](tcllib/files/modules/string/token\.md)| -|regular expression|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) · [textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) · [textutil::trim](tcllib/files/modules/textutil/trim\.md)| -|regular grammar|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md)| -|regular languages|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md)| -|remote communication|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md)| -|remote execution|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md)| -|remove|[fileutil::multi](tcllib/files/modules/fileutil/multi\.md) · [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md)| -|repeating|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|repetition|[struct::list](tcllib/files/modules/struct/struct\_list\.md) · [textutil::repeat](tcllib/files/modules/textutil/repeat\.md)| -|report|[report](tcllib/files/modules/report/report\.md)| -|reshuffle|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|residual graph|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|resolver|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|resource management|[try](tcllib/files/modules/try/tcllib\_try\.md)| -|restore|[nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md)| -|return|[throw](tcllib/files/modules/try/tcllib\_throw\.md)| -|reverse|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|rfc 821|[mime](tcllib/files/modules/mime/mime\.md) · [smtp](tcllib/files/modules/mime/smtp\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|rfc 822|[mime](tcllib/files/modules/mime/mime\.md) · [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) · [smtp](tcllib/files/modules/mime/smtp\.md)| -|rfc 868|[ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md)| -|rfc 959|[ftp](tcllib/files/modules/ftp/ftp\.md) · [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) · [ftpd](tcllib/files/modules/ftpd/ftpd\.md)| -|rfc 977|[nntp](tcllib/files/modules/nntp/nntp\.md)| -|rfc 1034|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|rfc 1035|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|rfc 1036|[nntp](tcllib/files/modules/nntp/nntp\.md)| -|rfc 1320|[md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)| -|rfc 1321|[md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)| -|rfc 1413|[ident](tcllib/files/modules/ident/ident\.md)| -|rfc 1630|[uri](tcllib/files/modules/uri/uri\.md)| -|rfc 1886|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|rfc 1939|[pop3](tcllib/files/modules/pop3/pop3\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md)| -|rfc 2030|[ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md)| -|rfc 2045|[mime](tcllib/files/modules/mime/mime\.md)| -|rfc 2046|[mime](tcllib/files/modules/mime/mime\.md)| -|rfc 2049|[mime](tcllib/files/modules/mime/mime\.md)| -|rfc 2104|[md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) · [sha1](tcllib/files/modules/sha1/sha1\.md) · [sha256](tcllib/files/modules/sha1/sha256\.md)| -|rfc 2141|[uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md)| -|rfc 2251|[ldap](tcllib/files/modules/ldap/ldap\.md) · [ldapx](tcllib/files/modules/ldap/ldapx\.md)| -|rfc 2255|[uri](tcllib/files/modules/uri/uri\.md)| -|rfc 2289|[otp](tcllib/files/modules/otp/otp\.md)| -|rfc 2396|[uri](tcllib/files/modules/uri/uri\.md)| -|rfc 2554|[smtp](tcllib/files/modules/mime/smtp\.md)| -|RFC 2718|[oauth](tcllib/files/modules/oauth/oauth\.md)| -|rfc 2821|[smtp](tcllib/files/modules/mime/smtp\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|rfc 2849|[ldapx](tcllib/files/modules/ldap/ldapx\.md)| -|rfc 3207|[smtp](tcllib/files/modules/mime/smtp\.md)| -|rfc 3513|[tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md)| -|rfc 3986|[uri](tcllib/files/modules/uri/uri\.md)| -|rfc 4511|[ldap](tcllib/files/modules/ldap/ldap\.md)| -|RFC 5849|[oauth](tcllib/files/modules/oauth/oauth\.md)| -|rfc 6455|[websocket](tcllib/files/modules/websocket/websocket\.md)| -|rfc 7858|[dns](tcllib/files/modules/dns/tcllib\_dns\.md)| -|rfc3501|[imap4](tcllib/files/modules/imap4/imap4\.md)| -|rfc3548|[base32](tcllib/files/modules/base32/base32\.md) · [base32::hex](tcllib/files/modules/base32/base32hex\.md)| -|right outer join|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|RIPEMD|[ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md)| -|roman numeral|[math::roman](tcllib/files/modules/math/roman\.md)| -|roots|[math::calculus](tcllib/files/modules/math/calculus\.md)| -|rot|[tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md)| -|rot13|[tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md)| -|rounding|[math::fuzzy](tcllib/files/modules/math/fuzzy\.md)| -|rows|[term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md)| -|rpc|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md)| -|rsa|[pki](tcllib/files/modules/pki/pki\.md)| -|running|[grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md)| - - -#### Keywords: S - -||| -|---|---| -|s3|[S3](tcllib/files/modules/amazon\-s3/S3\.md)| -|SASL|[SASL](tcllib/files/modules/sasl/sasl\.md) · [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) · [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) · [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md)| -|scanl|[generator](tcllib/files/modules/generator/generator\.md)| -|SCCS|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|SCRAM|[SASL::SCRAM](tcllib/files/modules/sasl/scram\.md)| -|secure|[comm](tcllib/files/modules/comm/comm\.md) · [pop3](tcllib/files/modules/pop3/pop3\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [transfer::connect](tcllib/files/modules/transfer/connect\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|security|[aes](tcllib/files/modules/aes/aes\.md) · [blowfish](tcllib/files/modules/blowfish/blowfish\.md) · [cksum](tcllib/files/modules/crc/cksum\.md) · [crc16](tcllib/files/modules/crc/crc16\.md) · [crc32](tcllib/files/modules/crc/crc32\.md) · [des](tcllib/files/modules/des/des\.md) · [md4](tcllib/files/modules/md4/md4\.md) · [md5](tcllib/files/modules/md5/md5\.md) · [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) · [otp](tcllib/files/modules/otp/otp\.md) · [pki](tcllib/files/modules/pki/pki\.md) · [rc4](tcllib/files/modules/rc4/rc4\.md) · [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) · [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) · [sha1](tcllib/files/modules/sha1/sha1\.md) · [sha256](tcllib/files/modules/sha1/sha256\.md) · [sum](tcllib/files/modules/crc/sum\.md) · [tclDES](tcllib/files/modules/des/tcldes\.md) · [tclDESjr](tcllib/files/modules/des/tcldesjr\.md)| -|seed|[tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md)| -|selectionbox|[javascript](tcllib/files/modules/javascript/javascript\.md)| -|semantic markup|[docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) · [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) · [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) · [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) · [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) · [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) · [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) · [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) · [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) · [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) · [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) · [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) · [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) · [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) · [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) · [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md)| -|send|[comm](tcllib/files/modules/comm/comm\.md)| -|serialization|[bee](tcllib/files/modules/bee/bee\.md) · [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) · [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) · [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) · [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) · [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) · [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) · [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::tree](tcllib/files/modules/struct/struct\_tree\.md)| -|server|[map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) · [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) · [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) · [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) · [nnsd](tcllib/files/apps/nnsd\.md) · [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md)| -|service|[logger](tcllib/files/modules/log/logger\.md)| -|services|[ftpd](tcllib/files/modules/ftpd/ftpd\.md) · [httpd](tcllib/files/modules/httpd/httpd\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|set|[struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|sha1|[sha1](tcllib/files/modules/sha1/sha1\.md)| -|sha256|[sha256](tcllib/files/modules/sha1/sha256\.md)| -|shell|[string::token::shell](tcllib/files/modules/string/token\_shell\.md)| -|shortest path|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|shuffle|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|simulated annealing|[simulation::annealing](tcllib/files/modules/simulation/annealing\.md)| -|simulation|[simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)| -|singleton|[oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md)| -|size limit|[tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md)| -|skiplist|[struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::skiplist](tcllib/files/modules/struct/skiplist\.md)| -|slippy|[map::slippy](tcllib/files/modules/map/map\_slippy\.md) · [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md)| -|smtp|[mime](tcllib/files/modules/mime/mime\.md) · [smtp](tcllib/files/modules/mime/smtp\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|smtpd|[smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|Snit|[snit](tcllib/files/modules/snit/snit\.md)| -|snit|[deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) · [interp](tcllib/files/modules/interp/tcllib\_interp\.md)| -|SNTP|[ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md)| -|socket|[comm](tcllib/files/modules/comm/comm\.md) · [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| -|soundex|[soundex](tcllib/files/modules/soundex/soundex\.md)| -|source|[docstrip](tcllib/files/modules/docstrip/docstrip\.md) · [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) · [tcldocstrip](tcllib/files/apps/tcldocstrip\.md)| -|spacing|[tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md)| -|spatial interpolation|[math::interpolate](tcllib/files/modules/math/interpolate\.md)| -|special functions|[math::special](tcllib/files/modules/math/special\.md)| -|specification|[bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md)| -|speed|[profiler](tcllib/files/modules/profiler/profiler\.md)| -|split|[textutil::split](tcllib/files/modules/textutil/textutil\_split\.md)| -|squared graph|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|ssl|[comm](tcllib/files/modules/comm/comm\.md) · [imap4](tcllib/files/modules/imap4/imap4\.md) · [pop3](tcllib/files/modules/pop3/pop3\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [transfer::connect](tcllib/files/modules/transfer/connect\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|stack|[struct::queue](tcllib/files/modules/struct/queue\.md)| -|standard io|[tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md)| -|state|[grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|state \(de\)serialization|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|statistical distribution|[simulation::random](tcllib/files/modules/simulation/simulation\_random\.md)| -|statistics|[counter](tcllib/files/modules/counter/counter\.md) · [math](tcllib/files/modules/math/math\.md) · [math::changepoint](tcllib/files/modules/math/changepoint\.md) · [math::PCA](tcllib/files/modules/math/pca\.md) · [math::statistics](tcllib/files/modules/math/statistics\.md)| -|stdin|[tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md)| -|stdout|[tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md)| -|stochastic modelling|[simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md)| -|stream cipher|[rc4](tcllib/files/modules/rc4/rc4\.md)| -|stream copy|[tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md)| -|string|[string::token](tcllib/files/modules/string/token\.md) · [string::token::shell](tcllib/files/modules/string/token\_shell\.md) · [textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) · [textutil::expander](tcllib/files/modules/textutil/expander\.md) · [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) · [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) · [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) · [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) · [textutil::trim](tcllib/files/modules/textutil/trim\.md)| -|stringprep|[stringprep](tcllib/files/modules/stringprep/stringprep\.md) · [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) · [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md)| -|strongly connected component|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|struct|[struct::pool](tcllib/files/modules/struct/pool\.md) · [struct::record](tcllib/files/modules/struct/record\.md)| -|structure|[control](tcllib/files/modules/control/control\.md)| -|structured queries|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|style|[doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md)| -|subcommand|[tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) · [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md)| -|subgraph|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|subject|[hook](tcllib/files/modules/hook/hook\.md)| -|submitbutton|[javascript](tcllib/files/modules/javascript/javascript\.md)| -|subscriber|[hook](tcllib/files/modules/hook/hook\.md)| -|subsequence|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|subst|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md)| -|sum|[sum](tcllib/files/modules/crc/sum\.md)| -|swapping|[struct::list](tcllib/files/modules/struct/struct\_list\.md)| -|symmetric difference|[struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|synchronous|[cache::async](tcllib/files/modules/cache/async\.md)| -|syntax tree|[grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md)| - - -#### Keywords: T - -||| -|---|---| -|table|[doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [html](tcllib/files/modules/html/html\.md) · [report](tcllib/files/modules/report/report\.md)| -|table of contents|[doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md)| -|tabstops|[textutil::tabify](tcllib/files/modules/textutil/tabify\.md)| -|tallying|[counter](tcllib/files/modules/counter/counter\.md)| -|tape archive|[tar](tcllib/files/modules/tar/tar\.md)| -|tar|[tar](tcllib/files/modules/tar/tar\.md)| -|tcl|[math::bigfloat](tcllib/files/modules/math/bigfloat\.md) · [math::bignum](tcllib/files/modules/math/bignum\.md) · [math::decimal](tcllib/files/modules/math/decimal\.md) · [math::PCA](tcllib/files/modules/math/pca\.md)| -|Tcl module|[docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md)| -|Tcl syntax|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md)| -|tcler's wiki|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md)| -|tcllib|[csv](tcllib/files/modules/csv/csv\.md)| -|TclOO|[clay](tcllib/files/modules/clay/clay\.md) · [httpd](tcllib/files/modules/httpd/httpd\.md) · [oo::util](tcllib/files/modules/tool/meta\.md) · [oo::util](tcllib/files/modules/ooutil/ooutil\.md) · [oometa](tcllib/files/modules/oometa/oometa\.md) · [tool](tcllib/files/modules/tool/tool\.md) · [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md)| -|TCLPARAM|[pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md)| -|TDPL|[grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|temp file|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)| -|template processing|[textutil::expander](tcllib/files/modules/textutil/expander\.md)| -|terminal|[term](tcllib/files/modules/term/term\.md) · [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) · [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) · [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) · [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) · [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) · [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) · [term::interact::menu](tcllib/files/modules/term/imenu\.md) · [term::interact::pager](tcllib/files/modules/term/ipager\.md) · [term::receive](tcllib/files/modules/term/receive\.md) · [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) · [term::send](tcllib/files/modules/term/term\_send\.md)| -|test|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)| -|Testing|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|testing|[bench](tcllib/files/modules/bench/bench\.md) · [bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) · [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) · [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) · [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md)| -|TeX|[textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| -|text|[bench::in](tcllib/files/modules/bench/bench\_read\.md) · [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md)| -|text comparison|[soundex](tcllib/files/modules/soundex/soundex\.md)| -|text conversion|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|text differences|[rcs](tcllib/files/modules/rcs/rcs\.md)| -|text display|[term::interact::menu](tcllib/files/modules/term/imenu\.md) · [term::interact::pager](tcllib/files/modules/term/ipager\.md)| -|text expansion|[textutil::expander](tcllib/files/modules/textutil/expander\.md)| -|text likeness|[soundex](tcllib/files/modules/soundex/soundex\.md)| -|text processing|[bibtex](tcllib/files/modules/bibtex/bibtex\.md) · [huddle](tcllib/files/modules/yaml/huddle\.md) · [page](tcllib/files/apps/page\.md) · [page\_intro](tcllib/files/modules/page/page\_intro\.md) · [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) · [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) · [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) · [yaml](tcllib/files/modules/yaml/yaml\.md)| -|text widget|[tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md)| -|threads|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|throw|[throw](tcllib/files/modules/try/tcllib\_throw\.md)| -|thumbnail|[jpeg](tcllib/files/modules/jpeg/jpeg\.md)| -|tie|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|tif|[tiff](tcllib/files/modules/tiff/tiff\.md)| -|tiff|[tiff](tcllib/files/modules/tiff/tiff\.md)| -|tile|[map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md)| -|time|[ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md)| -|timestamp|[png](tcllib/files/modules/png/png\.md)| -|timestamps|[debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md)| -|tip 219|[tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) · [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) · [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) · [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) · [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) · [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) · [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) · [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) · [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md)| -|tip 230|[tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|tip 234|[tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|tip 317|[tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md)| -|Tk|[tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md)| -|tls|[comm](tcllib/files/modules/comm/comm\.md) · [imap4](tcllib/files/modules/imap4/imap4\.md) · [pop3](tcllib/files/modules/pop3/pop3\.md) · [pop3d](tcllib/files/modules/pop3d/pop3d\.md) · [smtp](tcllib/files/modules/mime/smtp\.md) · [transfer::connect](tcllib/files/modules/transfer/connect\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|TMML|[doctools](tcllib/files/modules/doctools/doctools\.md) · [doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) · [dtplite](tcllib/files/apps/dtplite\.md) · [mpexpand](tcllib/files/modules/doctools/mpexpand\.md)| -|toc|[doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) · [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) · [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) · [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) · [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) · [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) · [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) · [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md)| -|toc formatter|[doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md)| -|tokenization|[string::token](tcllib/files/modules/string/token\.md) · [string::token::shell](tcllib/files/modules/string/token\_shell\.md)| -|TOOL|[oometa](tcllib/files/modules/oometa/oometa\.md) · [tool](tcllib/files/modules/tool/tool\.md) · [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md)| -|top\-down parsing languages|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|torrent|[bee](tcllib/files/modules/bee/bee\.md)| -|touch|[fileutil](tcllib/files/modules/fileutil/fileutil\.md)| -|TPDL|[grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md)| -|trace|[debug](tcllib/files/modules/debug/debug\.md) · [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) · [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) · [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md)| -|transducer|[grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) · [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) · [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) · [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) · [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) · [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt](tcllib/files/apps/pt\.md) · [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) · [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) · [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) · [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md) · [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) · [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) · [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) · [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) · [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) · [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) · [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) · [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) · [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) · [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) · [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) · [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) · [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) · [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) · [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) · [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) · [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) · [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) · [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) · [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) · [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) · [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) · [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) · [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) · [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) · [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) · [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) · [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) · [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) · [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) · [pt::util](tcllib/files/modules/pt/pt\_util\.md) · [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) · [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) · [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) · [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) · [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) · [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md)| -|transfer|[transfer::connect](tcllib/files/modules/transfer/connect\.md) · [transfer::copy](tcllib/files/modules/transfer/copyops\.md) · [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) · [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) · [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) · [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) · [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|transformation|[page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|transmitter|[transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md)| -|travelling salesman|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|traversal|[fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md)| -|tree|[grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) · [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) · [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) · [struct::queue](tcllib/files/modules/struct/queue\.md) · [struct::stack](tcllib/files/modules/struct/stack\.md) · [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) · [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) · [treeql](tcllib/files/modules/treeql/treeql\.md)| -|tree query language|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|tree walking|[page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) · [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) · [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md)| -|TreeQL|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|trigonometry|[math::trig](tcllib/files/modules/math/trig\.md)| -|trimming|[textutil](tcllib/files/modules/textutil/textutil\.md) · [textutil::trim](tcllib/files/modules/textutil/trim\.md)| -|twitter|[oauth](tcllib/files/modules/oauth/oauth\.md)| -|type|[fileutil](tcllib/files/modules/fileutil/fileutil\.md) · [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) · [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) · [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) · [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) · [snit](tcllib/files/modules/snit/snit\.md)| -|Type checking|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| - - -#### Keywords: U - -||| -|---|---| -|uevent|[hook](tcllib/files/modules/hook/hook\.md)| -|unbind|[uevent](tcllib/files/modules/uev/uevent\.md)| -|uncapitalize|[textutil::string](tcllib/files/modules/textutil/textutil\_string\.md)| -|undenting|[textutil::adjust](tcllib/files/modules/textutil/adjust\.md)| -|unicode|[stringprep](tcllib/files/modules/stringprep/stringprep\.md) · [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) · [unicode](tcllib/files/modules/stringprep/unicode\.md) · [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md)| -|unified format diff|[textutil::patch](tcllib/files/modules/textutil/patch\.md)| -|union|[struct::disjointset](tcllib/files/modules/struct/disjointset\.md) · [struct::set](tcllib/files/modules/struct/struct\_set\.md)| -|unit|[units](tcllib/files/modules/units/units\.md)| -|unknown hooking|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|untie|[tie](tcllib/files/modules/tie/tie\_std\.md) · [tie](tcllib/files/modules/tie/tie\.md)| -|update|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md)| -|uri|[uri](tcllib/files/modules/uri/uri\.md) · [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md)| -|url|[doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) · [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) · [uri](tcllib/files/modules/uri/uri\.md) · [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md)| -|urn|[uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md)| -|US\-NPI|[valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md)| -|utilities|[namespacex](tcllib/files/modules/namespacex/namespacex\.md)| -|uuencode|[uuencode](tcllib/files/modules/base64/uuencode\.md)| -|UUID|[uuid](tcllib/files/modules/uuid/uuid\.md)| - - -#### Keywords: V - -||| -|---|---| -|Validation|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|Value checking|[valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) · [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) · [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) · [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) · [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) · [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) · [valtype::iban](tcllib/files/modules/valtype/iban\.md) · [valtype::imei](tcllib/files/modules/valtype/imei\.md) · [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) · [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) · [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) · [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) · [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|vectors|[math::linearalgebra](tcllib/files/modules/math/linalg\.md)| -|verhoeff|[valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md)| -|vertex|[struct::graph](tcllib/files/modules/struct/graph\.md) · [struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|vertex cover|[struct::graph::op](tcllib/files/modules/struct/graphops\.md)| -|virtual channel|[tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) · [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) · [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) · [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) · [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) · [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) · [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) · [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) · [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) · [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) · [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) · [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) · [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) · [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) · [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) · [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) · [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) · [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) · [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) · [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) · [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) · [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) · [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) · [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) · [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) · [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) · [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) · [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) · [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|virtual machine|[grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) · [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) · [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) · [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) · [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) · [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) · [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) · [pt::param](tcllib/files/modules/pt/pt\_param\.md)| -|VISA|[valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md)| -|vwait|[coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) · [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) · [smtpd](tcllib/files/modules/smtpd/smtpd\.md)| - - -#### Keywords: W - -||| -|---|---| -|wais|[uri](tcllib/files/modules/uri/uri\.md)| -|widget|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| -|widget adaptors|[snit](tcllib/files/modules/snit/snit\.md) · [snitfaq](tcllib/files/modules/snit/snitfaq\.md)| -|wiki|[doctools::idx](tcllib/files/modules/doctools/docidx\.md) · [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) · [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) · [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) · [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) · [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) · [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) · [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md)| -|word|[doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) · [wip](tcllib/files/modules/wip/wip\.md)| -|WWW|[httpd](tcllib/files/modules/httpd/httpd\.md)| -|www|[uri](tcllib/files/modules/uri/uri\.md)| - - -#### Keywords: X - -||| -|---|---| -|x\.208|[asn](tcllib/files/modules/asn/asn\.md)| -|x\.209|[asn](tcllib/files/modules/asn/asn\.md)| -|x\.500|[ldap](tcllib/files/modules/ldap/ldap\.md)| -|XGoogleToken|[SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md)| -|xml|[xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md)| -|xor|[tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md)| -|XPath|[treeql](tcllib/files/modules/treeql/treeql\.md)| -|XSLT|[treeql](tcllib/files/modules/treeql/treeql\.md)| - - -#### Keywords: Y - -||| -|---|---| -|yaml|[huddle](tcllib/files/modules/yaml/huddle\.md) · [yaml](tcllib/files/modules/yaml/yaml\.md)| -|ydecode|[yencode](tcllib/files/modules/base64/yencode\.md)| -|yEnc|[yencode](tcllib/files/modules/base64/yencode\.md)| -|yencode|[yencode](tcllib/files/modules/base64/yencode\.md)| - - -#### Keywords: Z - -||| -|---|---| -|zero|[tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) · [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md)| -|zip|[zipfile::decode](tcllib/files/modules/zip/decode\.md) · [zipfile::encode](tcllib/files/modules/zip/encode\.md) · [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md)| -|zlib|[tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md)| -|zoom|[map::slippy](tcllib/files/modules/map/map\_slippy\.md) · [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) · [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md)| DELETED embedded/md/tcllib/files/apps/dtplite.md Index: embedded/md/tcllib/files/apps/dtplite.md ================================================================== --- embedded/md/tcllib/files/apps/dtplite.md +++ embedded/md/tcllib/files/apps/dtplite.md @@ -1,408 +0,0 @@ - -[//000000001]: # (dtplite \- Documentation toolbox) -[//000000002]: # (Generated from file 'dtplite\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2013 Andreas Kupries ) -[//000000004]: # (dtplite\(n\) 1\.0\.5 tcllib "Documentation toolbox") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -dtplite \- Lightweight DocTools Markup Processor - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [FORMATS](#subsection4) - - - [DIRECTORY STRUCTURES](#subsection5) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__dtplite__ __\-o__ *output* ?options? *format* *inputfile*](#1) -[__dtplite__ __validate__ *inputfile*](#2) -[__dtplite__ __\-o__ *output* ?options? *format* *inputdirectory*](#3) -[__dtplite__ __\-merge__ __\-o__ *output* ?options? *format* *inputdirectory*](#4) - -# DESCRIPTION - -The application described by this document, __dtplite__, is the successor to -the extremely simple __[mpexpand](\.\./modules/doctools/mpexpand\.md)__\. -Influenced in its functionality by the __dtp__ doctools processor it is much -more powerful than __[mpexpand](\.\./modules/doctools/mpexpand\.md)__, yet -still as easy to use; definitely easier than __dtp__ with its myriad of -subcommands and options\. - -__dtplite__ is based upon the package -__[doctools](\.\./modules/doctools/doctools\.md)__, like the other two -processors\. - -## USE CASES - -__dtplite__ was written with the following three use cases in mind\. - - 1. Validation of a single document, i\.e\. checking that it was written in valid - doctools format\. This mode can also be used to get a preliminary version of - the formatted output for a single document, for display in a browser, - nroff, etc\., allowing proofreading of the formatting\. - - 1. Generation of the formatted documentation for a single package, i\.e\. all - the manpages, plus a table of contents and an index of keywords\. - - 1. An extension of the previous mode of operation, a method for the easy - generation of one documentation tree for several packages, and especially - of a unified table of contents and keyword index\. - -Beyond the above we also want to make use of the customization features provided -by the HTML formatter\. It is not the only format the application should be able -to generate, but we anticipiate it to be the most commonly used, and it is one -of the few which do provide customization hooks\. - -We allow the caller to specify a header string, footer string, a stylesheet, and -data for a bar of navigation links at the top of the generated document\. While -all can be set as long as the formatting engine provides an appropriate engine -parameter \(See section [OPTIONS](#subsection3)\) the last two have internal -processing which make them specific to HTML\. - -## COMMAND LINE - - - __dtplite__ __\-o__ *output* ?options? *format* *inputfile* - - This is the form for use case \[1\]\. The *options* will be explained later, - in section [OPTIONS](#subsection3)\. - - * path *output* \(in\) - - This argument specifies where to write the generated document\. It can be - the path to a file or directory, or __\-__\. The last value causes the - application to write the generated documented to __stdout__\. - - If the *output* does not exist then \[file dirname $output\] has to - exist and must be a writable directory\. The generated document will be - written to a file in that directory, and the name of that file will be - derived from the *inputfile*, the *format*, and the value given to - option __\-ext__ \(if present\)\. - - * \(path|handle\) *format* \(in\) - - This argument specifies the formatting engine to use when processing the - input, and thus the format of the generated document\. See section - [FORMATS](#subsection4) for the possibilities recognized by the - application\. - - * path *inputfile* \(in\) - - This argument specifies the path to the file to process\. It has to - exist, must be readable, and written in - *[doctools](\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __dtplite__ __validate__ *inputfile* - - This is a simpler form for use case \[1\]\. The "validate" format generates no - output at all, only syntax checks are performed\. As such the specification - of an output file or other options is not necessary and left out\. - - - __dtplite__ __\-o__ *output* ?options? *format* *inputdirectory* - - This is the form for use case \[2\]\. It differs from the form for use case \[1\] - by having the input documents specified through a directory instead of a - file\. The other arguments are identical, except for *output*, which now - has to be the path to an existing and writable directory\. - - The input documents are all files in *inputdirectory* or any of its - subdirectories which were recognized by __fileutil::fileType__ as - containing text in *[doctools](\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __dtplite__ __\-merge__ __\-o__ *output* ?options? *format* *inputdirectory* - - This is the form for use case \[3\]\. The only difference to the form for use - case \[2\] is the additional option __\-merge__\. - - Each such call will merge the generated documents coming from processing the - input documents under *inputdirectory* or any of its subdirectories to the - files under *output*\. In this manner it is possible to incrementally build - the unified documentation for any number of packages\. Note that it is - necessary to run through all the packages twice to get fully correct - cross\-references \(for formats supporting them\)\. - -## OPTIONS - -This section describes all the options available to the user of the application, -with the exception of the options __\-o__ and __\-merge__\. These two were -described already, in section [COMMAND LINE](#subsection2)\. - - - __\-exclude__ string - - This option specifies an exclude \(glob\) pattern\. Any files identified as - manpages to process which match the exclude pattern are ignored\. The option - can be provided multiple times, each usage adding an additional pattern to - the list of exclusions\. - - - __\-ext__ string - - If the name of an output file has to be derived from the name of an input - file it will use the name of the *format* as the extension by default\. - This option here will override this however, forcing it to use *string* as - the file extension\. This option is ignored if the name of the output file is - fully specified through option __\-o__\. - - When used multiple times only the last definition is relevant\. - - - __\-header__ file - - This option can be used if and only if the selected *format* provides an - engine parameter named "header"\. It takes the contents of the specified file - and assign them to that parameter, for whatever use by the engine\. The HTML - engine will insert the text just after the tag ____\. If navigation - buttons are present \(see option __\-nav__ below\), then the HTML generated - for them is appended to the header data originating here before the final - assignment to the parameter\. - - When used multiple times only the last definition is relevant\. - - - __\-footer__ file - - Like __\-header__, except that: Any navigation buttons are ignored, the - corresponding required engine parameter is named "footer", and the data is - inserted just before the tag ____\. - - When used multiple times only the last definition is relevant\. - - - __\-style__ file - - This option can be used if and only if the selected *format* provides an - engine parameter named "meta"\. When specified it will generate a piece of - HTML code declaring the *file* as the stylesheet for the generated - document and assign that to the parameter\. The HTML engine will insert this - inot the document, just after the tag ____\. - - When processing an input directory the stylesheet file is copied into the - output directory and the generated HTML will refer to the copy, to make the - result more self\-contained\. When processing an input file we have no - location to copy the stylesheet to and so just reference it as specified\. - - When used multiple times only the last definition is relevant\. - - - __\-toc__ path - - This option specifies a doctoc file to use for the table of contents instead - of generating our own\. - - When used multiple times only the last definition is relevant\. - - - __\-pre\+toc__ label path|text - - - __\-post\+toc__ label path|text - - This option specifies additional doctoc files \(or texts\) to use in the - navigation bar\. - - Positioning and handling of multiple uses is like for options - __\-prenav__ and __\-postnav__, see below\. - - - __\-nav__ label url - - - __\-prenav__ label url - - Use this option to specify a navigation button with *label* to display and - the *url* to link to\. This option can be used if and only if the selected - *format* provides an engine parameter named "header"\. The HTML generated - for this is appended to whatever data we got from option __\-header__ - before it is inserted into the generated documents\. - - When used multiple times all definitions are collected and a navigation bar - is created, with the first definition shown at the left edge and the last - definition to the right\. - - The url can be relative\. In that case it is assumed to be relative to the - main files \(TOC and Keyword index\), and will be transformed for all others - to still link properly\. - - - __\-postnav__ label url - - Use this option to specify a navigation button with *label* to display and - the *url* to link to\. This option can be used if and only if the selected - *format* provides an engine parameter named "header"\. The HTML generated - for this is appended to whatever data we got from option __\-header__ - before it is inserted into the generated documents\. - - When used multiple times all definitions are collected and a navigation bar - is created, with the last definition shown at the right edge and the first - definition to the left\. - - The url can be relative\. In that case it is assumed to be relative to the - main files \(TOC and Keyword index\), and will be transformed for all others - to still link properly\. - -## FORMATS - -At first the *format* argument will be treated as a path to a tcl file -containing the code for the requested formatting engine\. The argument will be -treated as the name of one of the predefined formats listed below if and only if -the path does not exist\. - -*Note a limitation*: If treating the format as path to the tcl script -implementing the engine was sucessful, then this script has to implement not -only the engine API for doctools, i\.e\. *doctools\_api*, but for *doctoc\_api* -and *docidx\_api* as well\. Otherwise the generation of a table of contents and -of a keyword index will fail\. - -List of predefined formats, i\.e\. as provided by the package -__[doctools](\.\./modules/doctools/doctools\.md)__: - - - __nroff__ - - The processor generates \*roff output, the standard format for unix manpages\. - - - __html__ - - The processor generates HTML output, for usage in and display by web - browsers\. This engine is currently the only one providing the various engine - parameters required for the additional customaization of the output\. - - - __tmml__ - - The processor generates TMML output, the Tcl Manpage Markup Language, a - derivative of XML\. - - - __latex__ - - The processor generates LaTeX output\. - - - __wiki__ - - The processor generates Wiki markup as understood by __wikit__\. - - - __list__ - - The processor extracts the information provided by __manpage\_begin__\. - This format is used internally to extract the meta data from which both - table of contents and keyword index are derived from\. - - - __null__ - - The processor does not generate any output\. This is equivalent to - __validate__\. - -## DIRECTORY STRUCTURES - -In this section we describe the directory structures generated by the -application under *output* when processing all documents in an -*inputdirectory*\. In other words, this is only relevant to the use cases \[2\] -and \[3\]\. - - - \[2\] - - The following directory structure is created when processing a single set of - input documents\. The file extension used is for output in HTML, but that is - not relevant to the structure and was just used to have proper file names\. - - output/ - toc.html - index.html - files/ - path/to/FOO.html - - The last line in the example shows the document generated for a file FOO - located at - - inputdirectory/path/to/FOO - - - \[3\] - - When merging many packages into a unified set of documents the generated - directory structure is a bit deeper: - - output - .toc - .idx - .tocdoc - .idxdoc - .xrf - toc.html - index.html - FOO1/ - ... - FOO2/ - toc.html - files/ - path/to/BAR.html - - Each of the directories FOO1, \.\.\. contains the documents generated for the - package FOO1, \.\.\. and follows the structure shown for use case \[2\]\. The only - exception is that there is no per\-package index\. - - The files "\.toc", "\.idx", and "\.xrf" contain the internal status of the - whole output and will be read and updated by the next invokation\. Their - contents will not be documented\. Remove these files when all packages wanted - for the output have been processed, i\.e\. when the output is complete\. - - The files "\.tocdoc", and "\.idxdoc", are intermediate files in doctoc and - docidx markup, respectively, containing the main table of contents and - keyword index for the set of documents before their conversion to the chosen - output format\. They are left in place, i\.e\. not deleted, to serve as - demonstrations of doctoc and docidx markup\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx introduction](\.\./modules/doctools/docidx\_intro\.md), [doctoc -introduction](\.\./modules/doctools/doctoc\_intro\.md), [doctools -introduction](\.\./modules/doctools/doctools\_intro\.md) - -# KEYWORDS - -[HTML](\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./index\.md\#conversion), -[docidx](\.\./\.\./\.\./index\.md\#docidx), [doctoc](\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./index\.md\#doctools), -[manpage](\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./index\.md\#markup), [nroff](\.\./\.\./\.\./index\.md\#nroff) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2004\-2013 Andreas Kupries DELETED embedded/md/tcllib/files/apps/nns.md Index: embedded/md/tcllib/files/apps/nns.md ================================================================== --- embedded/md/tcllib/files/apps/nns.md +++ embedded/md/tcllib/files/apps/nns.md @@ -1,169 +0,0 @@ - -[//000000001]: # (nns \- Name service facility) -[//000000002]: # (Generated from file 'nns\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nns\(n\) 1\.1 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nns \- Name service facility, Commandline Client Application - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__nns__ __bind__ ?__\-host__ *host*? ?__\-port__ *port*? *name* *data*](#1) -[__nns__ __search__ ?__\-host__ *host*? ?__\-port__ *port*? ?__\-continuous__? ?*pattern*?](#2) -[__nns__ __ident__ ?__\-host__ *host*? ?__\-port__ *port*?](#3) -[__nns__ __who__](#4) - -# DESCRIPTION - -Please read *[Name service facility, -introduction](\.\./modules/nns/nns\_intro\.md)* first\. - -The application described by this document, __nns__, is a simple command -line client for the nano name service facility provided by the Tcllib packages -__[nameserv](\.\./modules/nns/nns\_client\.md)__, and -__[nameserv::server](\.\./modules/nns/nns\_server\.md)__\. Beyond that the -application's sources also serve as an example of how to use the client package -__[nameserv](\.\./modules/nns/nns\_client\.md)__\. All abilities of a client -are covered, from configuration to registration of names to searching\. - -This name service facility has nothing to do with the Internet's *Domain Name -System*, otherwise known as *[DNS](\.\./\.\./\.\./index\.md\#dns)*\. If the reader -is looking for a package dealing with that please see either of the packages -__[dns](\.\./modules/dns/tcllib\_dns\.md)__ and __resolv__, both found -in Tcllib too\. - -## USE CASES - -__nns__ was written with the following two main use cases in mind\. - - 1. Registration of a name/data pair in the name service\. - - 1. Searching the name service for entries matching a glob pattern\. - -Beyond the above we also want to be able to identify the client, and get -information about the name service\. - -## COMMAND LINE - - - __nns__ __bind__ ?__\-host__ *host*? ?__\-port__ *port*? *name* *data* - - This form registers the *name*/*data* pair in the specified name - service\. In this form the command will *not* exit to keep the registration - alive\. The user has to kill it explicitly, either by sending a signal, or - through the job\-control facilities of the shell in use\. It will especially - survive the loss of the connection to the name service and reestablish the - *name*/*data* pair when the connection is restored\. - - The options to specify the name service will be explained later, in section - [OPTIONS](#subsection3)\. - - - __nns__ __search__ ?__\-host__ *host*? ?__\-port__ *port*? ?__\-continuous__? ?*pattern*? - - This form searches the specified name service for entries matching the - glob\-*pattern* and prints them to stdout, with each entry on its own line\. - If no pattern is specified it defaults to __\*__, matching everything\. - - The options to specify the name service will be explained later, in section - [OPTIONS](#subsection3)\. - - If the option __\-continuous__ is specified the client will not exit - after performing the search, but start to continuously monitor the service - for changes to the set of matching entries, appropriately updating the - display as changes arrive\. In that form it will especially also survive the - loss of the connection to the name service and reestablish the search when - the connection is restored\. - - - __nns__ __ident__ ?__\-host__ *host*? ?__\-port__ *port*? - - This form asks the specified name service for the version and features of - the name service protocol it supports and prints the results to stdout\. - - The options to specify the name service will be explained later, in section - [OPTIONS](#subsection3)\. - - - __nns__ __who__ - - This form prints name, version, and protocol version of the application to - stdout\. - -## OPTIONS - -This section describes all the options available to the user of the application - - - __\-host__ name|ipaddress - - If this option is not specified it defaults to __localhost__\. It - specifies the name or ip\-address of the host the name service to talk to is - running on\. - - - __\-port__ number - - If this option is not specified it defaults to __38573__\. It specifies - the TCP port the name service to talk to is listening on for requests\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv\(n\)](\.\./modules/nns/nns\_client\.md), -[nameserv::common\(n\)](\.\./modules/nns/nns\_common\.md) - -# KEYWORDS - -[application](\.\./\.\./\.\./index\.md\#application), -[client](\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./index\.md\#name\_service) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/apps/nnsd.md Index: embedded/md/tcllib/files/apps/nnsd.md ================================================================== --- embedded/md/tcllib/files/apps/nnsd.md +++ embedded/md/tcllib/files/apps/nnsd.md @@ -1,130 +0,0 @@ - -[//000000001]: # (nnsd \- Name service facility) -[//000000002]: # (Generated from file 'nnsd\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nnsd\(n\) 1\.0\.1 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nnsd \- Name service facility, Commandline Server Application - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__nnsd__ ?__\-localonly__ *flag*? ?__\-port__ *port*?](#1) - -# DESCRIPTION - -Please read *[Name service facility, -introduction](\.\./modules/nns/nns\_intro\.md)* first\. - -The application described by this document, __[nns](nns\.md)__, is a -simple command line server for the nano name service facility provided by the -Tcllib packages __[nameserv](\.\./modules/nns/nns\_client\.md)__, and -__[nameserv::server](\.\./modules/nns/nns\_server\.md)__\. Beyond that the -application's sources also serve as an example of how to use the server package -__[nameserv::server](\.\./modules/nns/nns\_server\.md)__\. - -This name service facility has nothing to do with the Internet's *Domain Name -System*, otherwise known as *[DNS](\.\./\.\./\.\./index\.md\#dns)*\. If the reader -is looking for a package dealing with that please see either of the packages -__[dns](\.\./modules/dns/tcllib\_dns\.md)__ and __resolv__, both found -in Tcllib too\. - -## USE CASES - -__nnsd__ was written with the following main use case in mind\. - - 1. Run a nano name service on some host\. - -## COMMAND LINE - - - __nnsd__ ?__\-localonly__ *flag*? ?__\-port__ *port*? - - The command configures a server per the specified options and starts it\. The - command will not exit on its own, as it keeps the name service database - wholly in memory\. The user has to kill it explicitly, either by sending a a - signal, or through the job\-control facilities of the shell in use\. - - The options to configure the name service are explained in section - [OPTIONS](#subsection3)\. - -## OPTIONS - -This section describes all the options available to the user of the application - - - __\-localonly__ bool - - If this option is not specified it defaults to __true__, i\.e\. acceptance - of only local connections\. The server will accept remote connections, i\.e\. - connections from other hosts, if and only if this option is configured to - __false__\. - - - __\-port__ number - - If this option is not specified it defaults to __38573__\. It specifies - the TCP port the server has to listen on for requests\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv::common\(n\)](\.\./modules/nns/nns\_common\.md), -[nameserv::server\(n\)](\.\./modules/nns/nns\_server\.md) - -# KEYWORDS - -[application](\.\./\.\./\.\./index\.md\#application), [name -service](\.\./\.\./\.\./index\.md\#name\_service), -[server](\.\./\.\./\.\./index\.md\#server) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/apps/nnslog.md Index: embedded/md/tcllib/files/apps/nnslog.md ================================================================== --- embedded/md/tcllib/files/apps/nnslog.md +++ embedded/md/tcllib/files/apps/nnslog.md @@ -1,134 +0,0 @@ - -[//000000001]: # (nnslog \- Name service facility) -[//000000002]: # (Generated from file 'nnslog\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Andreas Kupries ) -[//000000004]: # (nnslog\(n\) 1\.0 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nnslog \- Name service facility, Commandline Logging Client Application - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__nnslog__ ?__\-host__ *host*? ?__\-port__ *port*?](#1) - -# DESCRIPTION - -Please read *[Name service facility, -introduction](\.\./modules/nns/nns\_intro\.md)* first\. - -The application described by this document, __nnslog__, is a simple command -line client for the nano name service facility provided by the Tcllib packages -__[nameserv](\.\./modules/nns/nns\_client\.md)__, and -__[nameserv::server](\.\./modules/nns/nns\_server\.md)__\. - -It essentially implements "__[nns](nns\.md)__ search \-continuous \*", but -uses a different output formatting\. Instead of continuously showing the current -contents of the server in the terminal it simply logs all received add/remove -events to __stdout__\. - -This name service facility has nothing to do with the Internet's *Domain Name -System*, otherwise known as *[DNS](\.\./\.\./\.\./index\.md\#dns)*\. If the reader -is looking for a package dealing with that please see either of the packages -__[dns](\.\./modules/dns/tcllib\_dns\.md)__ and __resolv__, both found -in Tcllib too\. - -## USE CASES - -__nnslog__ was written with the following main use case in mind\. - - 1. Monitoring the name service for all changes and logging them in a text - terminal\. - -## COMMAND LINE - - - __nnslog__ ?__\-host__ *host*? ?__\-port__ *port*? - - The command connects to the specified name service, sets up a search for all - changes and then prints all received events to stdout, with each events on - its own line\. The command will not exit until it is explicitly terminated by - the user\. It will especially survive the loss of the connection to the name - service and reestablish the search and log when the connection is restored\. - - The options to specify the name service will be explained later, in section - [OPTIONS](#subsection3)\. - -## OPTIONS - -This section describes all the options available to the user of the application - - - __\-host__ name|ipaddress - - If this option is not specified it defaults to __localhost__\. It - specifies the name or ip\-address of the host the name service to talk to is - running on\. - - - __\-port__ number - - If this option is not specified it defaults to __38573__\. It specifies - the TCP port the name service to talk to is listening on for requests\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv\(n\)](\.\./modules/nns/nns\_client\.md), -[nameserv::common\(n\)](\.\./modules/nns/nns\_common\.md) - -# KEYWORDS - -[application](\.\./\.\./\.\./index\.md\#application), -[client](\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./index\.md\#name\_service) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2008 Andreas Kupries DELETED embedded/md/tcllib/files/apps/page.md Index: embedded/md/tcllib/files/apps/page.md ================================================================== --- embedded/md/tcllib/files/apps/page.md +++ embedded/md/tcllib/files/apps/page.md @@ -1,474 +0,0 @@ - -[//000000001]: # (page \- Development Tools) -[//000000002]: # (Generated from file 'page\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries ) -[//000000004]: # (page\(n\) 1\.0 tcllib "Development Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page \- Parser Generator - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMAND LINE](#subsection1) - - - [OPERATION](#subsection2) - - - [OPTIONS](#subsection3) - - - [PLUGINS](#subsection4) - - - [PLUGIN LOCATIONS](#subsection5) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__page__ ?*options*\.\.\.? ?*input* ?*output*??](#1) - -# DESCRIPTION - -The application described by this document, __page__, is actually not just a -parser generator, as the name implies, but a generic tool for the execution of -arbitrary transformations on texts\. - -Its genericity comes through the use of *plugins* for reading, transforming, -and writing data, and the predefined set of plugins provided by Tcllib is for -the generation of memoizing recursive descent parsers \(aka *packrat parsers*\) -from grammar specifications \(*Parsing Expression Grammars*\)\. - -__page__ is written on top of the package __page::pluginmgr__, wrapping -its functionality into a command line based application\. All the other -__page::\*__ packages are plugin and/or supporting packages for the -generation of parsers\. The parsers themselves are based on the packages -__[grammar::peg](\.\./modules/grammar\_peg/peg\.md)__, -__[grammar::peg::interp](\.\./modules/grammar\_peg/peg\_interp\.md)__, and -__grammar::mengine__\. - -## COMMAND LINE - - - __page__ ?*options*\.\.\.? ?*input* ?*output*?? - - This is general form for calling __page__\. The application will read the - contents of the file *input*, process them under the control of the - specified *options*, and then write the result to the file *output*\. - - If *input* is the string __\-__ the data to process will be read from - __stdin__ instead of a file\. Analogously the result will be written to - __stdout__ instead of a file if *output* is the string __\-__\. A - missing output or input specification causes the application to assume - __\-__\. - - The detailed specifications of the recognized *options* are provided in - section [OPTIONS](#subsection3)\. - - * path *input* \(in\) - - This argument specifies the path to the file to be processed by the - application, or __\-__\. The last value causes the application to read - the text from __stdin__\. Otherwise it has to exist, and be readable\. - If the argument is missing __\-__ is assumed\. - - * path *output* \(in\) - - This argument specifies where to write the generated text\. It can be the - path to a file, or __\-__\. The last value causes the application to - write the generated documented to __stdout__\. - - If the file *output* does not exist then \[file dirname $output\] has to - exist and must be a writable directory, as the application will create - the fileto write to\. - - If the argument is missing __\-__ is assumed\. - -## OPERATION - -\.\.\. reading \.\.\. transforming \.\.\. writing \- plugins \- pipeline \.\.\. - -## OPTIONS - -This section describes all the options available to the user of the application\. -Options are always processed in order\. I\.e\. of both __\-\-help__ and -__\-\-version__ are specified the option encountered first has precedence\. - -Unknown options specified before any of the options __\-rd__, __\-wr__, or -__\-tr__ will cause processing to abort with an error\. Unknown options coming -in between these options, or after the last of them are assumed to always take a -single argument and are associated with the last plugin option coming before -them\. They will be checked after all the relevant plugins, and thus the options -they understand, are known\. I\.e\. such unknown options cause error if and only if -the plugin option they are associated with does not understand them, and was not -superceded by a plugin option coming after\. - -Default options are used if and only if the command line did not contain any -options at all\. They will set the application up as a PEG\-based parser -generator\. The exact list of options is - - -c peg - -And now the recognized options and their arguments, if they have any: - - - __\-\-help__ - - - __\-h__ - - - __\-?__ - - When one of these options is found on the command line all arguments coming - before or after are ignored\. The application will print a short description - of the recognized options and exit\. - - - __\-\-version__ - - - __\-V__ - - When one of these options is found on the command line all arguments coming - before or after are ignored\. The application will print its own revision and - exit\. - - - __\-P__ - - This option signals the application to activate visual feedback while - reading the input\. - - - __\-T__ - - This option signals the application to collect statistics while reading the - input and to print them after reading has completed, before processing - started\. - - - __\-D__ - - This option signals the application to activate logging in the Safe base, - for the debugging of problems with plugins\. - - - __\-r__ parser - - - __\-rd__ parser - - - __\-\-reader__ parser - - These options specify the plugin the application has to use for reading the - *input*\. If the options are used multiple times the last one will be used\. - - - __\-w__ generator - - - __\-wr__ generator - - - __\-\-writer__ generator - - These options specify the plugin the application has to use for generating - and writing the final *output*\. If the options are used multiple times the - last one will be used\. - - - __\-t__ process - - - __\-tr__ process - - - __\-\-transform__ process - - These options specify a plugin to run on the input\. In contrast to readers - and writers each use will *not* supersede previous uses, but add each - chosen plugin to a list of transformations, either at the front, or the end, - per the last seen use of either option __\-p__ or __\-a__\. The initial - default is to append the new transformations\. - - - __\-a__ - - - __\-\-append__ - - These options signal the application that all following transformations - should be added at the end of the list of transformations\. - - - __\-p__ - - - __\-\-prepend__ - - These options signal the application that all following transformations - should be added at the beginning of the list of transformations\. - - - __\-\-reset__ - - This option signals the application to clear the list of transformations\. - This is necessary to wipe out the default transformations used\. - - - __\-c__ file - - - __\-\-configuration__ file - - This option causes the application to load a configuration file and/or - plugin\. This is a plugin which in essence provides a pre\-defined set of - commandline options\. They are processed exactly as if they have been - specified in place of the option and its arguments\. This means that unknown - options found at the beginning of the configuration file are associated with - the last plugin, even if that plugin was specified before the configuration - file itself\. Conversely, unknown options coming after the configuration file - can be associated with a plugin specified in the file\. - - If the argument is a file which cannot be loaded as a plugin the application - will assume that its contents are a list of options and their arguments, - separated by space, tabs, and newlines\. Options and argumentes containing - spaces can be quoted via double\-quotes \("\) and quotes \('\)\. The quote - character can be specified within in a quoted string by doubling it\. - Newlines in a quoted string are accepted as is\. - -## PLUGINS - -__page__ makes use of four different types of plugins, namely: readers, -writers, transformations, and configurations\. Here we provide only a basic -introduction on how to use them from __page__\. The exact APIs provided to -and expected from the plugins can be found in the documentation for -__page::pluginmgr__, for those who wish to write their own plugins\. - -Plugins are specified as arguments to the options __\-r__, __\-w__, -__\-t__, __\-c__, and their equivalent longer forms\. See the section -[OPTIONS](#subsection3) for reference\. - -Each such argument will be first treated as the name of a file and this file is -loaded as the plugin\. If however there is no file with that name, then it will -be translated into the name of a package, and this package is then loaded\. For -each type of plugins the package management searches not only the regular paths, -but a set application\- and type\-specific paths as well\. Please see the section -[PLUGIN LOCATIONS](#subsection5) for a listing of all paths and their -sources\. - - - __\-c__ *name* - - Configurations\. The name of the package for the plugin *name* is - "page::config::*name*"\. - - We have one predefined plugin: - - * *peg* - - It sets the application up as a parser generator accepting parsing - expression grammars and writing a packrat parser in Tcl\. The actual - arguments it specifies are: - - --reset - --append - --reader peg - --transform reach - --transform use - --writer me - - - __\-r__ *name* - - Readers\. The name of the package for the plugin *name* is - "page::reader::*name*"\. - - We have five predefined plugins: - - * *peg* - - Interprets the input as a parsing expression grammar - \(*[PEG](\.\./\.\./\.\./index\.md\#peg)*\) and generates a tree - representation for it\. Both the syntax of PEGs and the structure of the - tree representation are explained in their own manpages\. - - * *hb* - - Interprets the input as Tcl code as generated by the writer plugin - *hb* and generates its tree representation\. - - * *ser* - - Interprets the input as the serialization of a PEG, as generated by the - writer plugin *ser*, using the package - __[grammar::peg](\.\./modules/grammar\_peg/peg\.md)__\. - - * *lemon* - - Interprets the input as a grammar specification as understood by Richard - Hipp's *[LEMON](\.\./\.\./\.\./index\.md\#lemon)* parser generator and - generates a tree representation for it\. Both the input syntax and the - structure of the tree representation are explained in their own - manpages\. - - * *treeser* - - Interprets the input as the serialization of a - __[struct::tree](\.\./modules/struct/struct\_tree\.md)__\. It is - validated as such, but nothing else\. It is *not* assumed to be the - tree representation of a grammar\. - - - __\-w__ *name* - - Writers\. The name of the package for the plugin *name* is - "page::writer::*name*"\. - - We have eight predefined plugins: - - * *identity* - - Simply writes the incoming data as it is, without making any changes\. - This is good for inspecting the raw result of a reader or - transformation\. - - * *null* - - Generates nothing, and ignores the incoming data structure\. - - * *tree* - - Assumes that the incoming data structure is a - __[struct::tree](\.\./modules/struct/struct\_tree\.md)__ and - generates an indented textual representation of all nodes, their - parental relationships, and their attribute information\. - - * *peg* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar and writes - it out as a PEG\. The result is nicely formatted and partially simplified - \(strings as sequences of characters\)\. A pretty printer in essence, but - can also be used to obtain a canonical representation of the input - grammar\. - - * *tpc* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar and writes - out Tcl code defining a package which defines a - __[grammar::peg](\.\./modules/grammar\_peg/peg\.md)__ object - containing the grammar when it is loaded into an interpreter\. - - * *hb* - - This is like the writer plugin *tpc*, but it writes only the - statements which define stat expression and grammar rules\. The code - making the result a package is left out\. - - * *ser* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar, transforms - it internally into a - __[grammar::peg](\.\./modules/grammar\_peg/peg\.md)__ object and - writes out its serialization\. - - * *me* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar and writes - out Tcl code defining a package which implements a memoizing recursive - descent parser based on the match engine \(ME\) provided by the package - __grammar::mengine__\. - - - __\-t__ *name* - - Transformers\. The name of the package for the plugin *name* is - "page::transform::*name*"\. - - We have two predefined plugins: - - * *reach* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar\. It - determines which nonterminal symbols and rules are reachable from - start\-symbol/expression\. All nonterminal symbols which were not reached - are removed\. - - * *use* - - Assumes that the incoming data structure is a tree representation of a - *[PEG](\.\./\.\./\.\./index\.md\#peg)* or other other grammar\. It - determines which nonterminal symbols and rules are able to generate a - *finite* sequences of terminal symbols \(in the sense for a Context - Free Grammar\)\. All nonterminal symbols which were not deemed useful in - this sense are removed\. - -## PLUGIN LOCATIONS - -The application\-specific paths searched by __page__ either are, or come -from: - - 1. The directory "~/\.page/plugin" - - 1. The environment variable *PAGE\_PLUGINS* - - 1. The registry entry *HKEY\_LOCAL\_MACHINE\\SOFTWARE\\PAGE\\PLUGINS* - - 1. The registry entry *HKEY\_CURRENT\_USER\\SOFTWARE\\PAGE\\PLUGINS* - -The type\-specific paths searched by __page__ either are, or come from: - - 1. The directory "~/\.page/plugin/" - - 1. The environment variable *PAGE\_\_PLUGINS* - - 1. The registry entry *HKEY\_LOCAL\_MACHINE\\SOFTWARE\\PAGE\\\\PLUGINS* - - 1. The registry entry *HKEY\_CURRENT\_USER\\SOFTWARE\\PAGE\\\\PLUGINS* - -Where the placeholder ** is always one of the values below, properly -capitalized\. - - 1. reader - - 1. writer - - 1. transform - - 1. config - -The registry entries are specific to the Windows\(tm\) platform, all other -platforms will ignore them\. - -The contents of both environment variables and registry entries are interpreted -as a list of paths, with the elements separated by either colon \(Unix\), or -semicolon \(Windows\)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -page::pluginmgr - -# KEYWORDS - -[parser generator](\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./index\.md\#text\_processing) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2005 Andreas Kupries DELETED embedded/md/tcllib/files/apps/pt.md Index: embedded/md/tcllib/files/apps/pt.md ================================================================== --- embedded/md/tcllib/files/apps/pt.md +++ embedded/md/tcllib/files/apps/pt.md @@ -1,799 +0,0 @@ - -[//000000001]: # (pt \- Parser Tools) -[//000000002]: # (Generated from file 'pt\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt \- Parser Tools Application - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Command Line](#section2) - - - [PEG Specification Language](#section3) - - - [JSON Grammar Exchange](#section4) - - - [C Parser Embedded In Tcl](#section5) - - - [C Parser](#section6) - - - [Snit Parser](#section7) - - - [TclOO Parser](#section8) - - - [Grammar Container](#section9) - - - [Example](#section10) - - - [Internals](#section11) - - - [Bugs, Ideas, Feedback](#section12) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -[__pt__ __generate__ *resultformat* ?*options\.\.\.*? *resultfile* *inputformat* *inputfile*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](\.\./modules/pt/pt\_introduction\.md)*\. This document is the entrypoint -to the whole system the current package is a part of\. - -This document describes __pt__, the main application of the module, a -*[parser generator](\.\./\.\./\.\./index\.md\#parser\_generator)*\. Its intended -audience are people who wish to create a parser for some language of theirs\. -Should you wish to modify the application instead, please see the section about -the application's [Internals](#section11) for the basic references\. - -It resides in the User Application Layer of Parser Tools\. - -![](\.\./\.\./\.\./image/arch\_user\_app\.png) - -# Command Line - - - __pt__ __generate__ *resultformat* ?*options\.\.\.*? *resultfile* *inputformat* *inputfile* - - This sub\-command of the application reads the parsing expression grammar - stored in the *inputfile* in the format *inputformat*, converts it to - the *resultformat* under the direction of the \(format\-specific\) set of - options specified by the user and stores the result in the *resultfile*\. - - The *inputfile* has to exist, while the *resultfile* may be created, - overwriting any pre\-existing content of the file\. Any missing directory in - the path to the *resultfile* will be created as well\. - - The exact form of the result for, and the set of options supported by the - known result\-formats, are explained in the upcoming sections of this - document, with the list below providing an index mapping between format name - and its associated section\. In alphabetical order: - - * __c__ - - A *resultformat*\. See section [C Parser](#section6)\. - - * __container__ - - A *resultformat*\. See section [Grammar Container](#section9)\. - - * __critcl__ - - A *resultformat*\. See section [C Parser Embedded In - Tcl](#section5)\. - - * __json__ - - A *input*\- and *resultformat*\. See section [JSON Grammar - Exchange](#section4)\. - - * __oo__ - - A *resultformat*\. See section [TclOO Parser](#section8)\. - - * __peg__ - - A *input*\- and *resultformat*\. See section [PEG Specification - Language](#section3)\. - - * __snit__ - - A *resultformat*\. See section [Snit Parser](#section7)\. - -Of the seven possible results four are parsers outright \(__c__, -__critcl__, __oo__, and __snit__\), one \(__container__\) provides -code which can be used in conjunction with a generic parser \(also known as a -grammar interpreter\), and the last two \(__json__ and __peg__\) are doing -double\-duty as input formats, allowing the transformation of grammars for -exchange, reformatting, and the like\. - -The created parsers fall into three categories: - -![](\.\./\.\./\.\./image/gen\_options\.png) - - - __Specialized parsers implemented in C__ - - The fastest parsers are created when using the result formats __c__ and - __critcl__\. The first returns the raw C code for the parser, while the - latter wraps it into a Tcl package using *CriTcl*\. - - This makes the latter much easier to use than the former\. On the other hand, - the former can be adapted to the users' requirements through a multitude of - options, allowing for things like usage of the parser outside of a Tcl - environment, something the __critcl__ format doesn't support\. As such - the __c__ format is meant for more advanced users, or users with special - needs\. - - A disadvantage of all the parsers in this section is the need to run them - through a C compiler to make them actually executable\. This is not something - everyone has the necessary tools for\. The parsers in the next section are - for people under such restrictions\. - - - __Specialized parsers implemented in Tcl__ - - As the parsers in this section are implemented in Tcl they are quite a bit - slower than anything from the previous section\. On the other hand this - allows them to be used in pure\-Tcl environments, or in environments which - allow only a limited set of binary packages\. In the latter case it will be - advantageous to lobby for the inclusion of the C\-based runtime support - \(notes below\) into the environment to reduce the impact of Tcl's on the - speed of these parsers\. - - The relevant formats are __snit__ and __oo__\. Both place their - result into a Tcl package containing a __snit::type__, or TclOO - __[class](\.\./\.\./\.\./index\.md\#class)__ respectively\. - - Of the supporting runtime, which is the package - __[pt::rde](\.\./modules/pt/pt\_rdengine\.md)__, the user has to know - nothing but that it does exist and that the parsers are dependent on it\. - Knowledge of the API exported by the runtime for the parsers' consumption is - *not* required by the parsers' users\. - - - __Interpreted parsing implemented in Tcl__ - - The last category, grammar interpretation\. This means that an interpreter - for parsing expression grammars takes the description of the grammar to - parse input for, and uses it guide the parsing process\. This is the slowest - of the available options, as the interpreter has to continually run through - the configured grammar, whereas the specialized parsers of the previous - sections have the relevant knowledge about the grammar baked into them\. - - The only places where using interpretation make sense is where the grammar - for some input may be changed interactively by the user, as the - interpretation allows for quick turnaround after each change, whereas the - previous methods require the generation of a whole new parser, which is not - as fast\. On the other hand, wherever the grammar to use is fixed, the - previous methods are much more advantageous as the time to generate the - parser is minuscule compared to the time the parser code is in use\. - - The relevant result format is __container__\. It \(quickly\) generates - grammar descriptions \(instead of a full parser\) which match the API expected - by ParserTools' grammar interpreter\. The latter is provided by the package - __[pt::peg::interp](\.\./modules/pt/pt\_peg\_interp\.md)__\. - -All the parsers generated by __critcl__, __snit__, and __oo__, and -the grammar interpreter share a common API for access to the actual parsing -functionality, making them all plug\-compatible\. It is described in the -*[Parser API](\.\./modules/pt/pt\_parser\_api\.md)* specification document\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -For either an introduction to or the formal specification of the language, -please go and read the *[PEG Language -Tutorial](\.\./modules/pt/pt\_peg\_language\.md)*\. - -When used as a result\-format this format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-template__ string - - The value of this option is a string into which to put the generated text - and the values of the other options\. The various locations for user\-data are - expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __PEG__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@code@__ - - To be replaced with the generated text\. - -# JSON Grammar Exchange - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -For the formal specification of the JSON grammar exchange format, please go and -read *[The JSON Grammar Exchange -Format](\.\./modules/pt/pt\_json\_language\.md)*\. - -When used as a result\-format this format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-indented__ boolean - - If this option is set the system will break the generated JSON across lines - and indent it according to its inner structure, with each key of a - dictionary on a separate line\. - - If the option is not set \(the default\), the whole JSON object will be - written on a single line, with minimum spacing between all elements\. - - - __\-aligned__ boolean - - If this option is set the system will ensure that the values for the keys in - a dictionary are vertically aligned with each other, for a nice table - effect\. To make this work this also implies that __\-indented__ is set\. - - If the option is not set \(the default\), the output is formatted as per the - value of __indented__, without trying to align the values for dictionary - keys\. - -# C Parser Embedded In Tcl - -The __critcl__ format is executable code, a parser for the grammar\. It is a -Tcl package with the actual parser implementation written in C and embedded in -Tcl via the __critcl__ package\. - -This result\-format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-class__ string - - The value of this option is the name of the class to generate, without - leading colons\. The default value is __CLASS__\. - - For a simple value __X__ without colons, like CLASS, the parser command - will be __X__::__X__\. Whereas for a namespaced value __X::Y__ - the parser command will be __X::Y__\. - - - __\-package__ string - - The value of this option is the name of the package to generate\. The default - value is __PACKAGE__\. - - - __\-version__ string - - The value of this option is the version of the package to generate\. The - default value is __1__\. - -# C Parser - -The __c__ format is executable code, a parser for the grammar\. The parser -implementation is written in C and can be tweaked to the users' needs through a -multitude of options\. - -The __critcl__ format, for example, is implemented as a canned configuration -of these options on top of the generator for __c__\. - -This result\-format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-template__ string - - The value of this option is a string into which to put the generated text - and the other configuration settings\. The various locations for user\-data - are expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __C/PARAM__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@code@__ - - To be replaced with the generated Tcl code\. - - The following options are special, in that they will occur within the - generated code, and are replaced there as well\. - - * __@statedecl@__ - - To be replaced with the value of the option __state\-decl__\. - - * __@stateref@__ - - To be replaced with the value of the option __state\-ref__\. - - * __@strings@__ - - To be replaced with the value of the option __string\-varname__\. - - * __@self@__ - - To be replaced with the value of the option __self\-command__\. - - * __@def@__ - - To be replaced with the value of the option __fun\-qualifier__\. - - * __@ns@__ - - To be replaced with the value of the option __namespace__\. - - * __@main@__ - - To be replaced with the value of the option __main__\. - - * __@prelude@__ - - To be replaced with the value of the option __prelude__\. - - - __\-state\-decl__ string - - A C string representing the argument declaration to use in the generated - parsing functions to refer to the parsing state\. In essence type and - argument name\. The default value is the string __RDE\_PARAM p__\. - - - __\-state\-ref__ string - - A C string representing the argument named used in the generated parsing - functions to refer to the parsing state\. The default value is the string - __p__\. - - - __\-self\-command__ string - - A C string representing the reference needed to call the generated parser - function \(methods \.\.\.\) from another parser fonction, per the chosen - framework \(template\)\. The default value is the empty string\. - - - __\-fun\-qualifier__ string - - A C string containing the attributes to give to the generated functions - \(methods \.\.\.\), per the chosen framework \(template\)\. The default value is - __static__\. - - - __\-namespace__ string - - The name of the C namespace the parser functions \(methods, \.\.\.\) shall reside - in, or a general prefix to add to the function names\. The default value is - the empty string\. - - - __\-main__ string - - The name of the main function \(method, \.\.\.\) to be called by the chosen - framework \(template\) to start parsing input\. The default value is - __\_\_main__\. - - - __\-string\-varname__ string - - The name of the variable used for the table of strings used by the generated - parser, i\.e\. error messages, symbol names, etc\. The default value is - __p\_string__\. - - - __\-prelude__ string - - A snippet of code to be inserted at the head of each generated parsing - function\. The default value is the empty string\. - - - __\-indent__ integer - - The number of characters to indent each line of the generated code by\. The - default value is __0__\. - - - __\-comments__ boolean - - A flag controlling the generation of code comments containing the original - parsing expression a parsing function is for\. The default value is - __on__\. - -# Snit Parser - -The __snit__ format is executable code, a parser for the grammar\. It is a -Tcl package holding a __snit::type__, i\.e\. a class, whose instances are -parsers for the input grammar\. - -This result\-format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-class__ string - - The value of this option is the name of the class to generate, without - leading colons\. Note, it serves double\-duty as the name of the package to - generate too, if option __\-package__ is not specified, see below\. The - default value is __CLASS__, applying if neither option __\-class__ - nor __\-package__ were specified\. - - - __\-package__ string - - The value of this option is the name of the package to generate, without - leading colons\. Note, it serves double\-duty as the name of the class to - generate too, if option __\-class__ is not specified, see above\. The - default value is __PACKAGE__, applying if neither option - __\-package__ nor __\-class__ were specified\. - - - __\-version__ string - - The value of this option is the version of the package to generate\. The - default value is __1__\. - -# TclOO Parser - -The __oo__ format is executable code, a parser for the grammar\. It is a Tcl -package holding a __[TclOO](\.\./\.\./\.\./index\.md\#tcloo)__ class, whose -instances are parsers for the input grammar\. - -This result\-format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-class__ string - - The value of this option is the name of the class to generate, without - leading colons\. Note, it serves double\-duty as the name of the package to - generate too, if option __\-package__ is not specified, see below\. The - default value is __CLASS__, applying if neither option __\-class__ - nor __\-package__ were specified\. - - - __\-package__ string - - The value of this option is the name of the package to generate, without - leading colons\. Note, it serves double\-duty as the name of the class to - generate too, if option __\-class__ is not specified, see above\. The - default value is __PACKAGE__, applying if neither option - __\-package__ nor __\-class__ were specified\. - - - __\-version__ string - - The value of this option is the version of the package to generate\. The - default value is __1__\. - -# Grammar Container - -The __container__ format is another form of describing parsing expression -grammars\. While data in this format is executable it does not constitute a -parser for the grammar\. It always has to be used in conjunction with the package -__[pt::peg::interp](\.\./modules/pt/pt\_peg\_interp\.md)__, a grammar -interpreter\. - -The format represents grammars by a __snit::type__, i\.e\. class, whose -instances are API\-compatible to the instances of the -__[pt::peg::container](\.\./modules/pt/pt\_peg\_container\.md)__ package, and -which are preloaded with the grammar in question\. - -This result\-format supports the following options: - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-mode__ __bulk__|__incremental__ - - The value of this option controls which methods of - __[pt::peg::container](\.\./modules/pt/pt\_peg\_container\.md)__ - instances are used to specify the grammar, i\.e\. preload it into the - container\. There are two legal values, as listed below\. The default is - __bulk__\. - - * __bulk__ - - In this mode the methods __start__, __add__, __modes__, and - __rules__ are used to specify the grammar in a bulk manner, i\.e\. as - a set of nonterminal symbols, and two dictionaries mapping from the - symbols to their semantic modes and parsing expressions\. - - This mode is the default\. - - * __incremental__ - - In this mode the methods __start__, __add__, __mode__, and - __rule__ are used to specify the grammar piecemal, with each - nonterminal having its own block of defining commands\. - - - __\-template__ string - - The value of this option is a string into which to put the generated code - and the other configuration settings\. The various locations for user\-data - are expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __CONTAINER__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@mode@__ - - To be replaced with the value of the option __\-mode__\. - - * __@code@__ - - To be replaced with the generated code\. - -# Example - -In this section we are working a complete example, starting with a PEG grammar -and ending with running the parser generated from it over some input, following -the outline shown in the figure below: - -![](\.\./\.\./\.\./image/flow\.png) Our grammar, assumed to the stored in the file -"calculator\.peg" is - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -From this we create a snit\-based parser via - - pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg - -which leaves us with the parser package and class written to the file -"calculator\.tcl"\. Assuming that this package is then properly installed in a -place where Tcl can find it we can now use this class via a script like - - package require calculator - - lassign $argv input - set channel [open $input r] - - set parser [calculator] - set ast [$parser parse $channel] - $parser destroy - close $channel - - ... now process the returned abstract syntax tree ... - -where the abstract syntax tree stored in the variable will look like - - set ast {Expression 0 4 - {Factor 0 4 - {Term 0 2 - {Number 0 2 - {Digit 0 0} - {Digit 1 1} - {Digit 2 2} - } - } - {AddOp 3 3} - {Term 4 4 - {Number 4 4 - {Digit 4 4} - } - } - } - } - -assuming that the input file and channel contained the text - - 120+5 - -A more graphical representation of the tree would be - -![](\.\./\.\./\.\./image/expr\_ast\.png) Regardless, at this point it is the user's -responsibility to work with the tree to reach whatever goal she desires\. I\.e\. -analyze it, transform it, etc\. The package -__[pt::ast](\.\./modules/pt/pt\_astree\.md)__ should be of help here, -providing commands to walk such ASTs structures in various ways\. - -One important thing to note is that the parsers used here return a data -structure representing the structure of the input per the grammar underlying the -parser\. There are *no* callbacks during the parsing process, i\.e\. no *parsing -actions*, as most other parsers will have\. - -Going back to the last snippet of code, the execution of the parser for some -input, note how the parser instance follows the specified *[Parser -API](\.\./modules/pt/pt\_parser\_api\.md)*\. - -# Internals - -This section is intended for users of the application which wish to modify or -extend it\. Users only interested in the generation of parsers can ignore it\. - -The main functionality of the application is encapsulated in the package -__[pt::pgen](\.\./modules/pt/pt\_pgen\.md)__\. Please read it for more -information\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/apps/tcldocstrip.md Index: embedded/md/tcllib/files/apps/tcldocstrip.md ================================================================== --- embedded/md/tcllib/files/apps/tcldocstrip.md +++ embedded/md/tcllib/files/apps/tcldocstrip.md @@ -1,221 +0,0 @@ - -[//000000001]: # (tcldocstrip \- Textprocessing toolbox) -[//000000002]: # (Generated from file 'tcldocstrip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries ) -[//000000004]: # (tcldocstrip\(n\) 1\.0 tcllib "Textprocessing toolbox") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcldocstrip \- Tcl\-based Docstrip Processor - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__tcldocstrip__ *output* ?options? *input* ?*guards*?](#1) -[__tcldocstrip__ ?options? *output* \(?options? *input* *guards*\)\.\.\.](#2) -[__tcldocstrip__ __\-guards__ *input*](#3) - -# DESCRIPTION - -The application described by this document, __tcldocstrip__, is a relative -of __[docstrip](\.\./modules/docstrip/docstrip\.md)__, a simple literate -programming tool for LaTeX\. - -__tcldocstrip__ is based upon the package -__[docstrip](\.\./modules/docstrip/docstrip\.md)__\. - -## USE CASES - -__tcldocstrip__ was written with the following three use cases in mind\. - - 1. Conversion of a single input file according to the listed guards into the - stripped output\. This handles the most simple case of a set of guards - specifying a single document found in a single input file\. - - 1. Stitching, or the assembly of an output from several sets of guards, in a - specific order, and possibly from different files\. This is the second - common case\. One document spread over several inputs, and/or spread over - different guard sets\. - - 1. Extraction and listing of all the unique guard expressions and guards used - within a document to help a person which did not author the document in - question in familiarizing itself with it\. - -## COMMAND LINE - - - __tcldocstrip__ *output* ?options? *input* ?*guards*? - - This is the form for use case \[1\]\. It converts the *input* file according - to the specified *guards* and options\. The result is written to the named - *output* file\. Usage of the string __\-__ as the name of the output - signals that the result should be written to __stdout__\. The guards are - document\-specific and have to be known to the caller\. The *options* will - be explained later, in section [OPTIONS](#subsection3)\. - - * path *output* \(in\) - - This argument specifies where to write the generated document\. It can be - the path to a file or directory, or __\-__\. The last value causes the - application to write the generated documented to __stdout__\. - - If the *output* does not exist then \[file dirname $output\] has to - exist and must be a writable directory\. - - * path *inputfile* \(in\) - - This argument specifies the path to the file to process\. It has to - exist, must be readable, and written in - *[docstrip](\.\./\.\./\.\./index\.md\#docstrip)* format\. - - - __tcldocstrip__ ?options? *output* \(?options? *input* *guards*\)\.\.\. - - This is the form for use case \[2\]\. It differs from the form for use case \[1\] - by the possibility of having options before the output file, which apply in - general, and specifying more than one inputfile, each with its own set of - input specific options and guards\. - - It extracts data from the various *input* files, according to the - specified *options* and *guards*, and writes the result to the given - *output*, in the order of their specification on the command line\. Options - specified before the output are global settings, whereas the options - specified before each input are valid only just for this input file\. - Unspecified values are taken from the global settings, or defaults\. As for - form \[1\] using the string __\-__ as output causes the application to - write to stdout\. Using the string __\.__ for an input file signals that - the last input file should be used again\. This enables the assembly of the - output from one input file using multiple and different sets of guards, - without having to specify the full name of the file every time\. - - - __tcldocstrip__ __\-guards__ *input* - - This is the form for use case \[3\]\. It determines the guards, and unique - guard expressions used within the provided *input* document\. The found - strings are written to stdout, one string per line\. - -## OPTIONS - -This section describes all the options available to the user of the application, -with the exception of the option __\-guards__\. This option was described -already, in section [COMMAND LINE](#subsection2)\. - - - __\-metaprefix__ string - - This option is inherited from the command __docstrip::extract__ provided - by the package __[docstrip](\.\./modules/docstrip/docstrip\.md)__\. - - It specifies the string by which the '%%' prefix of a metacomment line will - be replaced\. Defaults to '%%'\. For Tcl code this would typically be '\#'\. - - - __\-onerror__ mode - - This option is inherited from the command __docstrip::extract__ provided - by the package __[docstrip](\.\./modules/docstrip/docstrip\.md)__\. - - It controls what will be done when a format error in the *text* being - processed is detected\. The settings are: - - * __ignore__ - - Just ignore the error; continue as if nothing happened\. - - * __puts__ - - Write an error message to __stderr__, then continue processing\. - - * __throw__ - - Throw an error\. __::errorCode__ is set to a list whose first element - is __DOCSTRIP__, second element is the type of error, and third - element is the line number where the error is detected\. This is the - default\. - - - __\-trimlines__ bool - - This option is inherited from the command __docstrip::extract__ provided - by the package __[docstrip](\.\./modules/docstrip/docstrip\.md)__\. - - Controls whether *spaces* at the end of a line should be trimmed away - before the line is processed\. Defaults to __true__\. - - - __\-preamble__ text - - - __\-postamble__ text - - - __\-nopreamble__ - - - __\-nopostamble__ - - The \-no\*amble options deactivate file pre\- and postambles altogether, - whereas the \-\*amble options specify the *user* part of the file pre\- and - postambles\. This part can be empty, in that case only the standard parts are - shown\. This is the default\. - - Preambles, when active, are written before the actual content of a generated - file\. In the same manner postambles are, when active, written after the - actual content of a generated file\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *docstrip* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docstrip](\.\./modules/docstrip/docstrip\.md) - -# KEYWORDS - -[\.dtx](\.\./\.\./\.\./index\.md\#\_dtx), [LaTeX](\.\./\.\./\.\./index\.md\#latex), -[conversion](\.\./\.\./\.\./index\.md\#conversion), -[docstrip](\.\./\.\./\.\./index\.md\#docstrip), -[documentation](\.\./\.\./\.\./index\.md\#documentation), [literate -programming](\.\./\.\./\.\./index\.md\#literate\_programming), -[markup](\.\./\.\./\.\./index\.md\#markup), [source](\.\./\.\./\.\./index\.md\#source) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2005 Andreas Kupries DELETED embedded/md/tcllib/files/devdoc/tcl_community_communication.md Index: embedded/md/tcllib/files/devdoc/tcl_community_communication.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcl_community_communication.md +++ embedded/md/tcllib/files/devdoc/tcl_community_communication.md @@ -1,196 +0,0 @@ - -[//000000001]: # (tcl\_community\_communication \- ) -[//000000002]: # (Generated from file 'tcl\_community\_communication\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcl\_community\_communication\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl\_community\_communication \- Tcl Community \- Kind Communication - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Signatories](#section2) - - - [Authors](#section3) - -# DESCRIPTION - -The Tcl Community encourages contributions from anyone who wishes to advance the -development of: - - - The Tcl Language - - - Tcl derived languages - - - Tcl related libraries - - - Tcl extensions - - - External Projects that Integrate Tcl - -We welcome those contributions from anyone\. We are blind to gender, race, -religion, cultural background, cybernetic nature, and any other demographic -characteristics, as well as personal political views\. - -A community lives and dies by communications\. And occasionally our -communications are peppered with patterns that are harsh, unfriendly, -unwelcoming and/or otherwise unkind\. As a volunteer community, we need all of -the help we can get\. Therefore, we ask all contributors to make a conscious -effort, in Tcl Community discussions, to communicate in ways that are welcoming\. -Ways that are friendly\. Ways that are, in a word: kind\. - -These guidelines suggest specific ways to accomplish that goal\. - -Please note: for the balance of this document any reference to "People", -"Persons", "anybody" or "somebody" can refer to any sentient being, not merely -corporeal members of the species Homo Sapien\. - - - We are a Sanctuary not a Clubhouse - - The Tcl Community is a collective of amateurs and professionals who code, - test, and use tools\. Our community is open to all\. There is no velvet rope\. - There is no bouncer at the door\. There are no secret handshakes\. Any - sentient being who enters our midst is welcome\. If someone is ever asked to - leave, it is only because they are being disruptive to the functioning of - the community\. - - - We Merit Ideas, Not People - - A good idea can come from anyone, regardless of how little time they have - been with us\. A bad idea can come from anyone, regardless of how much time - or how little time they have been with us\. We judge a concept by how it - stands up to scrutiny of logic, implementation, and regression testing\. We - don’t judge ideas based on who had the idea first, who agrees with the idea, - or who disagrees with it\. - - - Treat Everyone with Respect - - Everyone is deserving of respect and courtesy at all times\. - - - Refer to people by the names they use\. - - If grammar requires you to state a gender for a person, honor their - preferences about their gender identity\. If you are unsure as to the gender - of an individual, ask\. If someone had to guess about your gender and got it - wrong, please correct them and do not take it personally\. - - - Do not take a harsh tone towards other participants\. - - Do not make personal attacks against anyone \(participant or not\.\) - - Criticize statements and actions, never people\. - - - Don’t Take Things Personally - - When in doubt, assume the best in people\. A criticism of your statements is - not a personal attack on you\. - - - Persons, not People - - Stereotypes are an unhelpful tool on many accounts\. They are generally - oversimplified\. They are usually flat out wrong\. And even if "right" they - are of absolutely no utility in determining the capabilities, motivations, - or fitness of an individual\. - - Don’t use them in Tcl Community communications\. - - - Mistakes Happen - - The human condition is a series of trials and errors\. Progress is when we - get one more trial than error\. Being wrong or making a mistake is the - default state of humanity\. Accept the errors of your fellow sentient beings, - and be aware that you are also fallible\. - - - Keep it Real - - Please respond to what people actually say\. We are all amazing individuals, - but none among us are mind readers\. If you find yourself responding to what - you imagine someone is thinking, odds are you are going to be wrong\. - - If you must criticize someone, stick to things they have actually done\. - Never criticize for something you speculate they have done\. Or imagine they - have done\. Or something someone who shares some attribute with them has done - in the past\. - - Keep discussions about any non\-Tcl subjects to what can be stated factually - and without emotion or judgement\. - - - When Trouble Arises, Don’t Escalate - - If you feel you are being personally attacked or offended, take the high - road\. Punching back in a public forum will only makes things worse\. Address - the matter in a private correspondence\. Be polite\. Express your feelings, - but note that you are expressing your feelings\. When writing, look for a way - to calm matters down\. And when in doubt, sleep on your letter before - pressing send\. And when not in doubt, sleep on it for another day after - that\. - - If you are a spectator to a fight in progress, politely request the two - parties take the matter to a more private forum\. - - - Always get the Last Word: I’m Sorry - - If an personal argument does arise, be the first to apologize\. An apology - does not concede a logical point\. It merely acknowledges that at some point - the discussion left either logic, community decency, or both\. Return to the - topic when cooler heads can prevail\. - - - Nobody is Keeping Score - - There is no prize for being right\. There is no cost for being wrong\. A hard - sell is not going to advance your idea along any more than a logical - argument\. You aren’t running for office\. This isn’t debate club\. If you find - yourself continuing a discussion beyond where a topic can be logically - discussed, stop\. - - - No Evangelizing - - The Tcl Community is not the place to promote your chosen operating system, - political outlook, religion, marketing scheme, or economic model\. Period\. - - \(And if you do bring it up, be prepared to have your chosen topic discussed - logically\. And odds are, not favorably\.\) - - - Respect the Community - - If the Community has come to a decision on a course of action, please stop - arguing\. - - If someone complains about how you are expressing your ideas, listen\. - - If your words are hurting people, stop\. There is no amount of being "right" - that makes up for someone leaving our midst because they felt insulted, - threatened, or ignored\. - -By following these guidelines, we will build our community, encourage more -contribution to our projects, and our discussions will be friendlier and reach -conclusions more easily\. - -Thank You\. - -# Signatories - - - Sean "the Hypnotoad" Woods - - - Andreas Kupries - -# Authors - - - Primary - - Sean "the Hypnotoad" Woods - - - Light editing - - Andreas Kupries DELETED embedded/md/tcllib/files/devdoc/tcllib_devguide.md Index: embedded/md/tcllib/files/devdoc/tcllib_devguide.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcllib_devguide.md +++ embedded/md/tcllib/files/devdoc/tcllib_devguide.md @@ -1,1046 +0,0 @@ - -[//000000001]: # (tcllib\_devguide \- ) -[//000000002]: # (Generated from file 'tcllib\_devguide\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcllib\_devguide\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_devguide \- Tcllib \- The Developer's Guide - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commitments](#section2) - - - [Contributor](#subsection1) - - - [Maintainer](#subsection2) - - - [Branching and Workflow](#section3) - - - [Package Dependencies](#subsection3) - - - [Trunk](#subsection4) - - - [Branches](#subsection5) - - - [Working with Branches](#subsection6) - - - [Version numbers](#subsection7) - - - [Structural Overview](#section4) - - - [Main Directories](#subsection8) - - - [More Directories](#subsection9) - - - [Top Files](#subsection10) - - - [File Types](#subsection11) - - - [Testsuite Tooling](#section5) - - - [Invoke the testsuites of a specific module](#subsection12) - - - [Invoke the testsuites of all modules](#subsection13) - - - [Detailed Test Logs](#subsection14) - - - [Shell Selection](#subsection15) - - - [Help](#subsection16) - - - [Documentation Tooling](#section6) - - - [Generate documentation for a specific module](#subsection17) - - - [Generate documentation for all modules](#subsection18) - - - [Available output formats, help](#subsection19) - - - [Validation without output](#subsection20) - - - [Notes On Writing A Testsuite](#section7) - - - [Installation Tooling](#section8) - -# SYNOPSIS - -[__[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action*](#1) -[__[Application](\.\./\.\./\.\./index\.md\#application)__ *name*](#2) -[__Exclude__ *name*](#3) - -# DESCRIPTION - -Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package -itself\. It is a collection of \(semi\-independent\) -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions -useful to a large collection of Tcl programmers\. - -This document is a guide for developers working on Tcllib, i\.e\. maintainers -fixing bugs, extending the collection's functionality, etc\. - -Please read - - 1. *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* and - - 1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)* - -first, if that was not done already\. - -Here we assume that the sources are already available in a directory of your -choice, and that you not only know how to build and install them, but also have -all the necessary requisites to actually do so\. The guide to the sources in -particular also explains which source code management system is used, where to -find it, how to set it up, etc\. - -# Commitments - -## Contributor - -As a contributor to Tcllib you are committing yourself to: - - 1. keep the guidelines written down in *[Tcl Community \- Kind - Communication](tcl\_community\_communication\.md)* in your mind\. The main - point to take away from there is *to be kind to each other*\. - - 1. Your contributions getting distributed under a BSD/MIT license\. For the - details see *[Tcllib \- License](tcllib\_license\.md)* - -Contributions are made by entering tickets into our tracker, providing patches, -bundles or branches of code for inclusion, or posting to the Tcllib related -mailing lists\. - -## Maintainer - -When contributing one or more packages for full inclusion into Tcllib you are -committing yourself to - - 1. Keep the guidelines written down in *[Tcl Community \- Kind - Communication](tcl\_community\_communication\.md)* \(as any contributor\) in - your mind\. The main point to take away from there is *to be kind to each - other*\. - - 1. Your packages getting distributed under a BSD/MIT license\. For the details - see *[Tcllib \- License](tcllib\_license\.md)* - - 1. Maintenance of the new packages for a period of two years under the - following rules, and responsibilities: - - 1) A maintainer may step down after the mandatory period as they see fit\. - - 1) A maintainer may step down before the end of the mandatory period, - under the condition that a replacement maintainer is immediately - available and has agreed to serve the remainder of the period, plus - their own mandatory period \(see below\)\. - - 1) When stepping down without a replacement maintainer taking over the - relevant packages have to be flagged as __unmaintained__\. - - 1) When a replacement mantainer is brought in for a package it is \(kept\) - marked as __maintained__ \(again\)\. - - A replacement maintainer is bound by the same rules as the original - maintainer, except that the mandatory period of maintenance is - shortened to one year\. - - 1) For any __unmaintained__ package a contributor interested in - becoming its maintainer can become so by flagging them as - __maintained__ with their name and contact information, committing - themselves to the rules of a replacement maintainer \(see previous - point\)\. - - 1) For any already __maintained__ package a contributor interested in - becoming a co\-maintainer can become so with the agreement of the - existing maintainer\(s\), committing themselves to the rules of a - replacement maintainer \(see two points previous\)\. - - The responsibilities as a maintainer include: - - 1) Watching Tcllib's ticket tracker for bugs, bug fixes, and feature - requests related to the new packages\. - - 1) Reviewing the aforementioned tickets, rejecting or applying them - - 1) Coordination and discussion with ticket submitter during the - development and/or application of bug fixes\. - - 1. Follow the [Branching and Workflow](#section3) of this guide\. - -# Branching and Workflow - -## Package Dependencies - -Regarding packages and dependencies between them Tcllib occupies a middle -position between two extremes: - - 1. On one side a strongly interdependent set of packages, usually by a single - author, for a single project\. Looking at my \(Andreas Kupries\) own work - examples of such are [Marpa](https://core\.tcl\.tk/akupries/marpa/index), - [CRIMP](https://core\.tcl\.tk/akupries/crimp/index), - [Kinetcl](https://core\.tcl\.tk/akupries/kinetcl/index), etc\. - - For every change the author of the project handles all the modifications - cascading from any incompatibilities it introduced to the system\. - - 1. On the other side, the world of semi\-independent projects by many different - authors where authors know what packages their own creations depend on, yet - usually do not know who else depends on them\. - - The best thing an author making an \(incompatible\) change to their project - can do is to for one announce such changes in some way, and for two use - versioning to distinguish the code before and after the change\. - - The world is then responsible for adapting, be it by updating their own - projects to the new version, or by sticking to the old\. - -As mentioned already, Tcllib lives in the middle of that\. - -While we as maintainers cannot be aware of all users of Tcllib's packages, and -thus have to rely on the mechanisms touched on in point 2 above for that, the -dependencies between the packages contained in Tcllib are a different matter\. - -As we are collectively responsible for the usability of Tcllib in toto to the -outside world, it behooves us to be individually mindful even of Tcllib packages -we are not directly maintaining, when they depend on packages under our -maintainership\. This may be as simple as coordinating with the maintainers of -the affected packages\. It may also require us to choose how to adapt affected -packages which do not have maintainers, i\.e\. modify them to use our changed -package properly, or modify them to properly depend on the unchanged version of -our package\. - -Note that the above is not only a chore but an opportunity as well\. Additional -insight can be had by forcing ourselves to look at our package and the planned -change\(s\) from an outside perspective, to consider the ramifications of our -actions on others in general, and on dependent packages in particular\. - -## Trunk - -The management and use of branches is an important part of working with a -*Distributed Version Control System* \(*DVCS*\) like -[fossil](https://www\.fossil\-scm\.org/)\. - -For Tcllib the main branch of the collection is *trunk*\. In -*[git](\.\./\.\./\.\./index\.md\#git)* this branch would be called *master*, and -this is exactly the case in the [github -mirror](https://github\.com/tcltk/tcllib/) of Tcllib\. - -To properly support debugging *each commit* on this branch *has to pass the -entire testsuite* of the collection\. Using bisection to determine when an issue -appeared is an example of an action made easier by this constraint\. - -This is part of our collective responsibility for the usability of Tcllib in -toto to the outside world\. As *[fossil](\.\./\.\./\.\./index\.md\#fossil)* has no -mechanism to enforce this condition this is handled on the honor system for -developers and maintainers\. - -To make the task easier Tcllib comes with a tool \("sak\.tcl"\) providing a number -of commands in support\. These commands are explained in the following sections -of this guide\. - -While it is possible and allowed to commit directly to trunk remember the above -constraint regarding the testsuite, and the coming notes about other possible -issues with a commit\. - -## Branches - -Given the constraints placed on the *trunk* branch of the repository it is -\(strongly\) recommended to perform any development going beyond trivial changes -on a non\-trunk branch\. - -Outside of the trunk developers are allowed to commit intermediate broken states -of their work\. Only at the end of a development cycle, when the relevant branch -is considered ready for merging, will it be necessary to perform full the set of -validations ensuring that the merge to come will create a good commit on trunk\. - -Note that while a review from a second developer is not a required condition for -merging a branch it is recommended to seek out such an independent opinion as a -means of cross\-checking the work\. - -It also recommended to give any new branch a name which aids in determining -additional details about it\. Examples of good things to stick into a branch name -would be - - - Developer \(nick\)name - - - Ticket hash/reference - - - One or two keywords applicable to the work - - - \.\.\. - -Further, while most development branches are likely quite short\-lived, no -prohibitions exist against making longer\-lived branches\. Creators should however -be mindful that the longer such a branch exists without merges the more -divergent they will tend to be, with an associated increase in the effort which -will have to be spent on either merging from and merging to trunk\. - -## Working with Branches - -In the hope of engendering good work practices now a few example operations -which will come up with branches, and their associated fossil command -\(sequences\)\. - - - *Awareness* - - When developing we have to keep ourselves aware of the context of our work\. - On what branch are we ? What files have we changed ? What new files are not - yet known to the repository ? What has happened remotely since we used our - checkout ? The answers to these questions become especially important when - using a long\-lived checkout and coming back to it after some time away\. - - Commands to answer questions like the above are: - - * __fossil pull__ - - Get all changes done on the remote since the last pull or sync from it\. - This has to be done first, before any of the commands below\. - - Even if the commit in our checkout refers to the branch we want right - now control operations committed to the remote may have changed that - from underneath us\. - - * __fossil info | grep tags__ - - * __fossil branch list | grep '\\\*'__ - - Two different ways of determining the branch our checkout is on\. - - * __fossil timeline__ - - What have we \(and others\) done recently ? - - *Attention*, this information is very likely outdated, the more the - longer we did not use this checkout\. Run __fossil pull__ first to - get latest information from the remote repository of the project\. - - * __fossil timeline current__ - - Place the commit our checkout is based on at the top of the timeline\. - - * __fossil changes__ - - Lists the files we have changed compared to the commit the checkout is - based on\. - - * __fossil extra__ - - Lists the files we have in the checkout the repository does not know - about\. This may be leftover chaff from our work, or something we have - forgotten to __fossil add__ to the repository yet\. - - - *Clean checkouts* - - Be aware of where you are \(see first definition\)\. - - For pretty much all the operation recipes below a clean checkout is at least - desired, often required\. To check that a checkout is clean invoke - - fossil changes - fossil extra - - How to clean up when uncommitted changes of all sorts are found is - context\-specific and outside of the scope of this guide\. - - - *Starting a new branch* - - Be aware of where you are \(see first definition\)\. - - Ensure that you have clean checkout \(see second definition\)\. It is - *required*\. - - In most situations you want to be on branch *trunk*, and you want to be on - the latest commit for it\. To get there use - - fossil pull - fossil update trunk - - If some other branch is desired as the starting point for the coming work - replace *trunk* in the commands above with the name of that branch\. - - With the base line established we now have two ways of creating the new - branch, with differing \(dis\)advantages\. The simpler way is to - - fossil branch new NAME_OF_NEW_BRANCH - - and start developing\. The advantage here is that you cannot forget to create - the branch\. The disadvantages are that we have a branch commit unchanged - from where we branched from, and that we have to use high\-handed techniques - like hiding or shunning to get rid of the commit should we decide to abandon - the work before the first actual commit on the branch\. - - The other way of creating the branch is to start developing, and then on the - first commit use the option __\-\-branch__ to tell - __[fossil](\.\./\.\./\.\./index\.md\#fossil)__ that we are starting a branch - now\. I\.e\. run - - fossil commit --branch NAME_OF_NEW_BRANCH ... - - where *\.\.\.* are any other options used to supply the commit message, files - to commit, etc\. - - The \(dis\)advantages are now reversed\. - - We have no superflous commit, only what is actually developed\. The work is - hidden until we commit to make our first commit\. - - We may forget to use __\-\-branch NAME\_OF\_NEW\_BRANCH__ and then have to - correct that oversight via the fossil web interface \(I am currently unaware - of ways of doing such from the command line, although some magic - incantantion of __fossil tag create__ may work\)\. - - It helps to keep awareness, like checking before any commit that we are on - the desired branch\. - - - *Merging a branch into trunk* - - Be aware of where you are \(see first definition\)\. - - Ensure that you have clean checkout \(see second definition\)\. In the - full\-blown sequence \(zig\-zag\) it is *required*, due to the merging from - trunk\. In the shorter sequence it is only desired\. That said, keeping the - checkout clean before any major operations is a good habit to have, in my - opinion\. - - The full\-blown sequencing with checks all the way is to - - 1. Validate the checkout, i\.e\. last commit on your branch\. Run the full - test suite and other validations, fix all the issues which have cropped - up\. - - 1. Merge the latest state of the *trunk* \(see next definition\)\. - - 1. Validate the checkout again\. The incoming trunk changes may have broken - something now\. Do any required fixes\. - - 1. Now merge to the trunk using - - fossil update trunk - fossil merge --integrate YOUR_BRANCH - - 1. At this point the checkout should be in the same state as at the end of - point \(3\) above, because we resolved any issues with the trunk already\. - Thus a simple - - fossil commit ... - - should be sufficient now to commit the merge back and close the branch - \(due to the __\-\-integrate__ we used on the merge\)\. - - The more paranoid may validate the checkout a third time before - commiting\. - - I call this a *zig\-zag merge* because of how the arrows look in the - timeline, from trunk to feature branch for the first merge, and then back - for the final merge\. - - A less paranoid can do what I call a *simple merge*, which moves step \(2\) - after step \(4\) and skips step \(3\) entirely\. The resulting shorter sequence - is - - 1. Validate - - 1. Merge to trunk - - 1. Validate again - - 1. Commit to trunk - - The last step after either zig\-zag or plain merge is to - - fossil sync - - This saves our work to the remote side, and further gives us any other work - done while we were doing our merge\. It especially allows us to check if we - raced somebody else, resulting in a split trunk\. - - When that happens we should coordinate with the other developer on who fixes - the split, to ensure that we do not race each other again\. - - - *Merging from trunk* - - Be aware of where you are \(see first definition\)\. - - Ensure that you have clean checkout \(see second definition\)\. It is - *required*\. - - In most situations you want to import the latest commit of branch *trunk* - \(or other origin\)\. To get it use - - fossil pull - - With that done we can now import this commit into our current branch with - - fossil merge trunk - - Even if __[fossil](\.\./\.\./\.\./index\.md\#fossil)__ does not report any - conflicts it is a good idea to check that the operation has not broken the - new and/or changed functionality we are working on\. - - With the establishment of a good merge we then save the state with - - fossil commit ... - - before continuing development\. - -## Version numbers - -In Tcllib all changes to a package have to come with an increment of its version -number\. What part is incremented \(patchlevel, minor, major version\) depends on -the kind of change made\. With multiple changes in a commit the highest "wins"\. - -When working in a development branch the version change can be deferred until it -is time to merge, and then has to cover all the changes in the branch\. - -Below a list of the kinds of changes and their associated version increments: - - - *D \- documentation* - - No increment - - - *T \- testsuite* - - No increment - - - *B \- bugfix* - - Patchlevel - - - *I \- implementation tweak* - - Patchlevel - - - *P \- performance tweak* - - Patchlevel - - - *E \- backward\-compatible extension* - - Minor - - - *API \- incompatible change* - - Major - -Note that a commit containing a version increment has to mention the new version -number in its commit message, as well as the kind of change which caused it\. - -Note further that the version number of a package currently exists in three -places\. An increment has to update all of them: - - 1. The package implementation\. - - 1. The package index \("pkgIndex\.tcl"\) - - 1. The package documentation\. - -The "sak\.tcl" command __validate version__ helps finding discrepancies -between the first two\. All the other __validate__ methods are also of -interest to any developer\. Invoke it with - - sak.tcl help validate - -to see their documentation\. - -# Structural Overview - -## Main Directories - -The main directories in the Tcllib toplevel directory and of interest to a -developer are: - - - "modules" - - Each child directory represents one or more packages\. In the case of the - latter the packages are usually related in some way\. Examples are "base64", - "math", and "struct", with loose \(base64\) to strong \(math\) relations between - the packages in the directory\. - - - "apps" - - This directory contains all the installable applications, with their - documentation\. Note that this directory is currently *not* split into - sub\-directories\. - - - "examples" - - Each child directory "foo" contains one or more example application for the - packages in "modules/foo"\. These examples are generally not polished enough - to be considered for installation\. - -## More Directories - - - "config" - - This directory contains files supporting the Unix build system, i\.e\. - "configure" and "Makefile\.in"\. - - - "devdoc" - - This directories contains the doctools sources for the global documentation, - like this document and its sibling guides\. - - - "embedded" - - This directory contains the entire documentation formatted for - *[HTML](\.\./\.\./\.\./index\.md\#html)* and styled to properly mix into the - web site generated by fossil for the repository\. - - This is the documentation accessible from the Tcllib home directory, - represented in the repository as "embedded/index\.md"\. - - - "idoc" - - This directory contains the entire documentation formatted for - *[nroff](\.\./\.\./\.\./index\.md\#nroff)* and - *[HTML](\.\./\.\./\.\./index\.md\#html)*, the latter without any styling\. This - is the documentation which will be installed\. - - - "support" - - This directory contains the sources of internal packages and utilities used - in the implementation of the "installer\.tcl" and "sak\.tcl" scripts/tools\. - -## Top Files - - - "aclocal\.m4" - - - "configure" - - - "configure\.in" - - - "Makefile\.in" - - These four files comprise the Unix build system layered on top of the - "installer\.tcl" script\. - - - "installer\.tcl" - - The Tcl\-based installation script/tool\. - - - "project\.shed" - - Configuration file for *Sean Wood*'s - __[PracTcl](\.\./modules/practcl/practcl\.md)__ buildsystem\. - - - "sak\.tcl" - - This is the main tool for developers and release managers, the *Swiss Army - Knife* of management operations on the collection\. - - - "ChangeLog" - - The log of changes to the global support, when the sources were held in - *[CVS](\.\./\.\./\.\./index\.md\#cvs)*\. Not relevant any longer with the - switch to the *[fossil](\.\./\.\./\.\./index\.md\#fossil)* SCM\. - - - "license\.terms" - - The license in plain ASCII\. See also *[Tcllib \- - License](tcllib\_license\.md)* for the nicely formatted form\. The text is - identical\. - - - "README\.md" - - - "\.github/CONTRIBUTING\.md" - - - "\.github/ISSUE\_TEMPLATE\.md" - - - "\.github/PULL\_REQUEST\_TEMPLATE\.md" - - These markdown\-formatted documents are used and shown by the github mirror - of these sources, pointing people back to the official location and issue - trackers\. - - - "DESCRIPTION\.txt" - - - "STATUS" - - - "tcllib\.spec" - - - "tcllib\.tap" - - - "tcllib\.yml" - - ???? - -## File Types - -The most common file types, by file extension, are: - - - "\.tcl" - - Tcl code for a package, application, or example\. - - - "\.man" - - Doctools\-formatted documentation, usually for a package\. - - - "\.test" - - Test suite for a package, or part of\. Based on __tcltest__\. - - - "\.bench" - - Performance benchmarks for a package, or part of\. Based on "modules/bench"\. - - - "\.pcx" - - Syntax rules for *TclDevKit*'s __tclchecker__\. Using these rules - allows the checker to validate the use of commands of a Tcllib package - __foo__ without having to scan the "\.tcl" files implementing it\. - -# Testsuite Tooling - -Testsuites in Tcllib are based on Tcl's standard test package __tcltest__, -plus utilities found in the directory "modules/devtools" - -Tcllib developers invoke the suites through the __test run__ method of the -"sak\.tcl" tool, with other methods of __[test](\.\./\.\./\.\./index\.md\#test)__ -providing management operations, for example setting a list of standard Tcl -shells to use\. - -## Invoke the testsuites of a specific module - -Invoke either - - ./sak.tcl test run foo - -or - - ./sak.tcl test run modules/foo - -to invoke the testsuites found in a specific module "foo"\. - -## Invoke the testsuites of all modules - -Invoke the tool without a module name, i\.e\. - - ./sak.tcl test run - -to invoke the testsuites of all modules\. - -## Detailed Test Logs - -In all the previous examples the test runner will write a combination of -progress display and testsuite log to the standard output, showing for each -module only the tests that passed or failed and how many of each in a summary at -the end\. - -To get a detailed log, it is necessary to invoke the test runner with additional -options\. - -For one: - - ./sak.tcl test run --log LOG foo - -While this shows the same short log on the terminal as before, it also writes a -detailed log to the file "LOG\.log", and excerpts to other files \("LOG\.summary", -"LOG\.failures", etc\.\)\. - -For two: - - ./sak.tcl test run -v foo - -This writes the detailed log to the standard output, instead of the short log\. - -Regardless of form, the detailed log contains a list of all test cases executed, -which failed, and how they failed \(expected versus actual results\)\. - -## Shell Selection - -By default the test runner will use all the Tcl shells specified via __test -add__ to invoke the specified testsuites, if any\. If no such are specified it -will fall back to the Tcl shell used to run the tool itself\. - -Use option __\-\-shell__ to explicitly specify the Tcl shell to use, like - - ./sak.tcl test run --shell /path/to/tclsh ... - -## Help - -Invoke the tool as - - ./sak.tcl help test - -to see the detailed help for all methods of -__[test](\.\./\.\./\.\./index\.md\#test)__, and the associated options\. - -# Documentation Tooling - -The standard format used for documentation of packages and other things in -Tcllib is *[doctools](\.\./\.\./\.\./index\.md\#doctools)*\. Its supporting -packages are a part of Tcllib, see the directories "modules/doctools" and -"modules/dtplite"\. The latter is an application package, with the actual -application "apps/dtplite" a light wrapper around it\. - -Tcllib developers gain access to these through the __doc__ method of the -"sak\.tcl" tool, another \(internal\) wrapper around the "modules/dtplite" -application package\. - -## Generate documentation for a specific module - -Invoke either - - ./sak.tcl doc html foo - -or - - ./sak.tcl doc html modules/foo - -to generate HTML for the documentation found in the module "foo"\. Instead of -__html__ any other supported format can be used here, of course\. - -The generated formatted documentation will be placed into a directory "doc" in -the current working directory\. - -## Generate documentation for all modules - -Invoke the tool without a module name, i\.e\. - - ./sak.tcl doc html - -to generate HTML for the documentation found in all modules\. Instead of -__html__ any other supported format can be used here, of course\. - -The generated formatted documentation will be placed into a directory "doc" in -the current working directory\. - -## Available output formats, help - -Invoke the tool as - - ./sak.tcl help doc - -to see the entire set of supported output formats which can be generated\. - -## Validation without output - -Note the special format __validate__\. - -Using this value as the name of the format to generate forces the tool to simply -check that the documentation is syntactically correct, without generating actual -output\. - -Invoke it as either - - ./sak.tcl doc validate (modules/)foo - -or - - ./sak.tcl doc validate - -to either check the packages of a specific module or check all of them\. - -# Notes On Writing A Testsuite - -While previous sections talked about running the testsuites for a module and the -packages therein, this has no meaning if the module in question has no -testsuites at all\. - -This section gives a very basic overview on possible methodologies for writing -tests and testsuites\. - -First there are "drudgery" tests\. Written to check absolutely basic assumptions -which should never fail\. - -For example for a command FOO taking two arguments, three tests calling it with -zero, one, and three arguments\. The basic checks that the command fails if it -has not enough arguments, or too many\. - -After that come the tests checking things based on our knowledge of the command, -about its properties and assumptions\. Some examples based on the graph -operations added during Google's Summer of Code 2009 are: - - - The BellmanFord command in struct::graph::ops takes a *startnode* as - argument, and this node should be a node of the graph\. This equals one test - case checking the behavior when the specified node is not a node of the - graph\. - - This often gives rise to code in the implementation which explicitly checks - the assumption and throws an understandable error, instead of letting the - algorithm fail later in some weird non\-deterministic way\. - - It is not always possible to do such checks\. The graph argument for example - is just a command in itself, and while we expect it to exhibit a certain - interface, i\.e\. a set of sub\-commands aka methods, we cannot check that it - has them, except by actually trying to use them\. That is done by the - algorithm anyway, so an explicit check is just overhead we can get by - without\. - - - IIRC one of the distinguishing characteristic of either BellmanFord and/or - Johnson is that they are able to handle negative weights\. Whereas Dijkstra - requires positive weights\. - - This induces \(at least\) three testcases \.\.\. Graph with all positive weights, - all negative, and a mix of positive and negative weights\. Thinking further - does the algorithm handle the weight __0__ as well ? Another test case, - or several, if we mix zero with positive and negative weights\. - - - The two algorithms we are currently thinking about are about distances - between nodes, and distance can be 'Inf'inity, i\.e\. nodes may not be - connected\. This means that good test cases are - - 1. Strongly connected graph - - 1. Connected graph - - 1. Disconnected graph\. - - At the extremes of strongly connected and disconnected we have the fully - connected graphs and graphs without edges, only nodes, i\.e\. completely - disconnected\. - - - IIRC both of the algorithms take weighted arcs, and fill in a default if - arcs are left unweighted in the input graph\. - - This also induces three test cases: - - 1. Graph will all arcs with explicit weights\. - - 1. Graph without weights at all\. - - 1. Graph with mixture of weighted and unweighted graphs\. - -What was described above via examples is called *black\-box* testing\. Test -cases are designed and written based on the developer's knowledge of the -properties of the algorithm and its inputs, without referencing a particular -implementation\. - -Going further, a complement to *black\-box* testing is *white\-box*\. For this -we know the implementation of the algorithm, we look at it and design our tests -cases so that they force the code through all possible paths in the -implementation\. Wherever a decision is made we have a test case forcing a -specific direction of the decision, for all possible combinations and -directions\. It is easy to get a combinatorial explosion in the number of needed -test\-cases\. - -In practice I often hope that the black\-box tests I have made are enough to -cover all the paths, obviating the need for white\-box tests\. - -The above should be enough to make it clear that writing tests for an algorithm -takes at least as much time as coding the algorithm, and often more time\. Much -more time\. See for example also -[http://sqlite\.org/testing\.html](http://sqlite\.org/testing\.html), a writeup -on how the Sqlite database engine is tested\. Another article of interest might -be -[https://www\.researchgate\.net/publication/298896236](https://www\.researchgate\.net/publication/298896236)\. -While geared to a particular numerical algorithm it still shows that even a -simple\-looking algorithm can lead to an incredible number of test cases\. - -An interesting connection is to documentation\. In one direction, the properties -checked with black\-box testing are exactly the properties which should be -documented in the algorithm's man page\. And conversely, the documentation of the -properties of an algorithm makes a good reference to base the black\-box tests -on\. - -In practice test cases and documentation often get written together, -cross\-influencing each other\. And the actual writing of test cases is a mix of -black and white box, possibly influencing the implementation while writing the -tests\. Like writing a test for a condition like *startnode not in input graph* -serving as reminder to put a check for this condition into the code\. - -# Installation Tooling - -A last thing to consider when adding a new package to the collection is -installation\. - -How to *use* the "installer\.tcl" script is documented in *[Tcllib \- The -Installer's Guide](tcllib\_installer\.md)*\. - -Here we document how to extend said installer so that it may install new -package\(s\) and/or application\(s\)\. - -In most cases only a single file has to be modified, the -"support/installation/modules\.tcl" holding one command per module and -application to install\. - -The relevant commands are: - - - __[Module](\.\./\.\./\.\./index\.md\#module)__ *name* *code\-action* *doc\-action* *example\-action* - - Install the packages of module *name*, found in "modules/*name*"\. - - The *code\-action* is responsible for installing the packages and their - index\. The system currently provides - - * __\_tcl__ - - Copy all "\.tcl" files found in "modules/*name*" into the installation\. - - * __\_tcr__ - - As __\_tcl__, copy the "\.tcl" files found in the subdirectories of - "modules/*name*" as well\. - - * __\_tci__ - - As __\_tcl__, and copy the "tclIndex\.tcl" file as well\. - - * __\_msg__ - - As __\_tcl__, and copy the subdirectory "msgs" as well\. - - * __\_doc__ - - As __\_tcl__, and copy the subdirectory "mpformats" as well\. - - * __\_tex__ - - As __\_tcl__, and copy "\.tex" files as well\. - - The *doc\-action* is responsible for installing the package documentation\. - The system currently provides - - * __\_null__ - - No documentation available, do nothing\. - - * __\_man__ - - Process the "\.man" files found in "modules/*name*" and install the - results \(nroff and/or HTML\) in the proper location, as given to the - installer\. - - This is actually a fallback, normally the installer uses the pre\-made - formatted documentation found under "idoc"\. - - The *example\-action* is responsible for installing the examples\. The - system currently provides - - * __\_null__ - - No examples available, do nothing\. - - * __\_exa__ - - Copy the the directory "examples/*name*" recursively to the install - location for examples\. - - - __[Application](\.\./\.\./\.\./index\.md\#application)__ *name* - - Install the application with *name*, found in "apps"\. - - - __Exclude__ *name* - - This command signals to the installer which of the listed modules to *not* - install\. I\.e\. they name the deprecated modules of Tcllib\. - -If, and only if the above actions are not suitable for the new module then a -second file has to be modified, "support/installation/actions\.tcl"\. - -This file contains the implementations of the available actions, and is the -place where any custom action needed to handle the special circumstances of -module has to be added\. DELETED embedded/md/tcllib/files/devdoc/tcllib_installer.md Index: embedded/md/tcllib/files/devdoc/tcllib_installer.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcllib_installer.md +++ embedded/md/tcllib/files/devdoc/tcllib_installer.md @@ -1,340 +0,0 @@ - -[//000000001]: # (tcllib\_install\_guide \- ) -[//000000002]: # (Generated from file 'tcllib\_installer\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcllib\_install\_guide\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_install\_guide \- Tcllib \- The Installer's Guide - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Requisites](#section2) - - - [Tcl](#subsection1) - - - [Critcl](#subsection2) - - - [Build & Installation Instructions](#section3) - - - [Installing on Unix](#subsection3) - - - [Installing on Windows](#subsection4) - - - [Critcl & Accelerators](#subsection5) - - - [Tooling](#subsection6) - -# DESCRIPTION - -Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package -itself\. It is a collection of \(semi\-independent\) -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions -useful to a large collection of Tcl programmers\. - -The audience of this document is anyone wishing to build and install the -packages found in Tcllib, for either themselves, or others\. - -For developers intending to work on the packages themselves we additionally -provide - - 1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\. - -Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first, -if that was not done already\. Here we assume that the sources are already -available in a directory of your choice\. - -# Requisites - -Before Tcllib can be build and used a number of requisites must be installed\. -These are: - - 1. The scripting language Tcl\. For details see [Tcl](#subsection1)\. - - 1. Optionally, the __critcl__ package \(C embedding\) for - __[Tcl](\.\./\.\./\.\./index\.md\#tcl)__\. For details see __CriTcl__\. - -This list assumes that the machine where Tcllib is to be installed is -essentially clean\. Of course, if parts of the dependencies listed below are -already installed the associated steps can be skipped\. It is still recommended -to read their sections though, to validate that the dependencies they talk about -are indeed installed\. - -## Tcl - -As we are installing a number of Tcl packages and applications it should be -pretty much obvious that a working installation of Tcl itself is needed, and I -will not belabor the point\. - -Out of the many possibilities use whatever you are comfortable with, as long as -it provides at the very least Tcl 8\.2, or higher\. This may be a Tcl installation -provided by your operating system distribution, from a distribution\-independent -vendor, or built by yourself\. - -*Note* that the packages in Tcllib have begun to require 8\.4, 8\.5, and even -8\.6\. Older versions of Tcl will not be able to use such packages\. Trying to use -them will result in *package not found* errors, as their package index files -will not register them in versions of the core unable to use them\. - -Myself, I used \(and still use\) [ActiveState's](http://www\.activestate\.com) -ActiveTcl 8\.5 distribution during development, as I am most familiar with it\. - -*\(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, -maintaining ActiveTcl and TclDevKit for them\)\.*\. I am currently working for -SUSE Software Canada ULC, although not in Tcl\-related areas\. - -This distribution can be found at -[http://www\.activestate\.com/activetcl](http://www\.activestate\.com/activetcl)\. -Retrieve the archive of ActiveTcl 8\.5 \(or higher\) for your platform and install -it as directed by ActiveState\. - -For those wishing to build and install Tcl on their own, the relevant sources -can be found at - - - Tcl - - [http://core\.tcl\-lang\.org/tcl/](http://core\.tcl\-lang\.org/tcl/) - -together with the necessary instructions on how to build it\. - -If there are problems with building, installing, or using Tcl, please file a -ticket against *[Tcl](\.\./\.\./\.\./index\.md\#tcl)*, or the vendor of your -distribution, and *not* *[Tcllib](\.\./\.\./\.\./index\.md\#tcllib)*\. - -## Critcl - -The __critcl__ tool is an *optional* dependency\. - -It is only required when trying to build the C\-based *accelerators* for a -number of packages, as explained in [Critcl & Accelerators](#subsection5) - -Tcllib's build system looks for it in the , using the name __critcl__\. This -is for Unix\. On Windows on the other hand the search is more complex\. First we -look for a proper application __critcl\.exe__\. When that is not found we look -for a combination of interpreter \(__tclkitsh\.exe__, __tclsh\.exe__\) and -starkit \(__critcl\.kit__, __critcl__\) instead\. *Note* that the choice -of starkit can be overriden via the environment variable \. - -Tcllib requires Critcl version 2 or higher\. - -The github repository providing releases of version 2 and higher, and the -associated sources, can be found at -[http://andreas\-kupries\.github\.com/critcl](http://andreas\-kupries\.github\.com/critcl)\. - -Any branch of the repository can be used \(if not using the prebuild starkit or -starpack\), although the use of the stable branch *master* is recommended\. - -At the above url is also an explanation on how to build and install Critcl, -including a list of its dependencies\. - -Its instructions will not be repeated here\. If there are problems with these -directions please file a ticket against the *Critcl* project, and not Tcllib\. - -# Build & Installation Instructions - -As Tcllib is mainly a bundle of packages written in pure Tcl building it is the -same as installing it\. The exceptions to this have their own subsection, -[Critcl & Accelerators](#subsection5), later on\. - -Before that however comes the standard case, differentiated by the platforms -with material differences in the instruction, i\.e\. *Unix*\-like, versus -*Windows*\. - -Regarding the latter it should also be noted that it is possible set up an -*Unix*\-like environment using projects like *MSYS*, *Cygwin*, and others\. -In that case the user has the choice of which instructions to follow\. - -Regardless of environment or platform, a suitable -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* has to be installed, and its __tclsh__ -should be placed on the \(*Unix*\) or associated with "\.tcl" files -\(*Windows*\)\. - -## Installing on Unix - -For *Unix*\-like environments Tcllib comes with the standard set of files to -make - - ./configure - make install - -a suitable way of installing it\. This is a standard non\-interactive install -automatically figuring out where to place everything, i\.e\. packages, -applications, and the manpages\. - -To get a graphical installer invoke - - ./installer.tcl - -instead\. - -## Installing on Windows - -In a Windows environment we have the __installer\.tcl__ script to perform -installation\. - -If the desired __tclsh__ is associated "\.tcl" files then double\-clicking / -opening the __installer\.tcl__ is enough to invoke it in graphical mode\. This -assumes that *[Tk](\.\./\.\./\.\./index\.md\#tk)* is installed and available as -well\. - -Without *[Tk](\.\./\.\./\.\./index\.md\#tk)* the only way to invoke the installer -are to open a DOS window, i\.e\. __cmd\.exe__, and then to invoke - - ./installer.tcl - -inside it\. - -## Critcl & Accelerators - -While the majority of Tcllib consists of packages written in pure Tcl a number -of packages also have *accelerators* associated with them\. These are -__critcl__\-based C packages whose use will boost the performance of the -packages using them\. These accelerators are optional, and they are not built by -default\. If they are built according to the instructions below then they will -also be installed as well\. - -To build the accelerators the normally optional dependency on __critcl__ -becomes required\. - -To build and install Tcllib with the accelerators in a Unix\-like environment -invoke: - - ./configure - make critcl # Builds the shared library and package holding - # the accelerators, tcllibc - make install # Installs all packages, including the new tcllibc. - -The underlying tool is "sak\.tcl" in the toplevel directory of Tcllib and the -command __make critcl__ is just a wrapper around - - ./sak.tcl critcl - -Therefore in a Windows environment instead invoke - - ./sak.tcl critcl - ./installer.tcl - -from within a DOS window, i\.e\. __cmd\.exe__\. - -## Tooling - -The core of Tcllib's build system is the script "installer\.tcl" found in the -toplevel directory of a checkout or release\. - -The - - configure ; make install - -setup available to developers on Unix\-like systems is just a wrapper around it\. -To go beyond the standard embodied in the wrapper it is necessary to directly -invoke this script\. - -On Windows system using it directly is the only way to invoke it\. - -For basic help invoke it as - - ./installer.tcl -help - -This will print a short list of all the available options to the standard output -channel\. - -The commands associated with the various *install* targets in the -*Makefile\.in* for Unix can be used as additional examples on how to use this -tool as well\. - -The installer can operate in GUI and CLI modes\. By default it chooses the mode -automatically, based on if the Tcl package -__[Tk](\.\./\.\./\.\./index\.md\#tk)__ can be used or not\. The option -__\-no\-gui__ can be used to force CLI mode\. - -Note that it is possible to specify options on the command line even if the -installer ultimatively selects GUI mode\. In that case the hardwired defaults and -the options determine the data presented to the user for editing\. - -The installer will select a number of defaults for the locations of packages, -examples, and documentation, and also the format of the documentation\. The user -can overide these defaults in the GUI, or by specifying additional options\. The -defaults depend on the platform detected \(Unix/Windows\) and on the __tclsh__ -executable used to run the installer\. - -*Options* - - - __\-help__ - - Show the list of options explained here on the standard output channel and - exit\. - - - __\+excluded__ - - Include deprecated packages in the installation\. - - - __\-no\-gui__ - - Force command line operation of the installer - - - __\-no\-wait__ - - In CLI mode the installer will by default ask the user to confirm that the - chosen configuration \(destination paths, things to install\) is correct - before performing any action\. Using this option causes the installer to skip - this query and immediately jump to installation\. - - - __\-app\-path__ *path* - - - __\-example\-path__ *path* - - - __\-html\-path__ *path* - - - __\-nroff\-path__ *path* - - - __\-pkg\-path__ *path* - - Declare the destination paths for the applications, examples, html - documentation, nroff manpages, and packages\. The defaults are derived from - the location of the __tclsh__ used to run the installer\. - - - __\-dry\-run__ - - - __\-simulate__ - - Run the installer without modifying the destination directories\. - - - __\-apps__ - - - __\-no\-apps__ - - - __\-examples__ - - - __\-no\-examples__ - - - __\-pkgs__ - - - __\-no\-pkgs__ - - - __\-html__ - - - __\-no\-html__ - - - __\-nroff__ - - - __\-no\-nroff__ - - \(De\)activate the installation of applications, examples, packages, html - documentation, and nroff manpages\. - - Applications, examples, and packages are installed by default\. - - On Windows the html documentation is installed by default\. - - On Unix the nroff manpages are installed by default\. DELETED embedded/md/tcllib/files/devdoc/tcllib_license.md Index: embedded/md/tcllib/files/devdoc/tcllib_license.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcllib_license.md +++ embedded/md/tcllib/files/devdoc/tcllib_license.md @@ -1,69 +0,0 @@ - -[//000000001]: # (tcllib\_license \- ) -[//000000002]: # (Generated from file 'tcllib\_license\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcllib\_license\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_license \- Tcllib \- License - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [License](#section2) - -# DESCRIPTION - -Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package -itself\. It is a collection of \(semi\-independent\) -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions -useful to a large collection of Tcl programmers\. - -The collection is under the BSD license\. - -# License - -This software is copyrighted by Ajuba Solutions and other parties\. The following -terms apply to all files associated with the software unless explicitly -disclaimed in individual files\. - -The authors hereby grant permission to use, copy, modify, distribute, and -license this software and its documentation for any purpose, provided that -existing copyright notices are retained in all copies and that this notice is -included verbatim in any distributions\. No written agreement, license, or -royalty fee is required for any of the authorized uses\. Modifications to this -software may be copyrighted by their authors and need not follow the licensing -terms described here, provided that the new terms are clearly indicated on the -first page of each file where they apply\. - -IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, -INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE -OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE -AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\. - -THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, -BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A -PARTICULAR PURPOSE, AND NON\-INFRINGEMENT\. THIS SOFTWARE IS PROVIDED ON AN "AS -IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE -MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\. - -GOVERNMENT USE: If you are acquiring this software on behalf of the U\.S\. -government, the Government shall have only "Restricted Rights" in the software -and related documentation as defined in the Federal Acquisition Regulations -\(FARs\) in Clause 52\.227\.19 \(c\) \(2\)\. If you are acquiring the software on behalf -of the Department of Defense, the software shall be classified as "Commercial -Computer Software" and the Government shall have only "Restricted Rights" as -defined in Clause 252\.227\-7013 \(c\) \(1\) of DFARs\. Notwithstanding the foregoing, -the authors grant the U\.S\. Government and others acting in its behalf permission -to use and distribute the software in accordance with the terms specified in -this license\. DELETED embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md Index: embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md +++ embedded/md/tcllib/files/devdoc/tcllib_releasemgr.md @@ -1,124 +0,0 @@ - -[//000000001]: # (tcllib\_releasemgr \- ) -[//000000002]: # (Generated from file 'tcllib\_releasemgr\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcllib\_releasemgr\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_releasemgr \- Tcllib \- The Release Manager's Guide - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Tools](#section2) - - - [Tasks](#section3) - - - [Start a release candidate](#subsection1) - - - [Ready the candidate](#subsection2) - - - [Make it official](#subsection3) - - - [Distribute the release](#subsection4) - -# DESCRIPTION - -Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package -itself\. It is a collection of \(semi\-independent\) -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions -useful to a large collection of Tcl programmers\. - -The audience of this document is the release manager for Tcllib, their deputies, -and anybody else interested in the task of creating an official release of -Tcllib for distribution\. - -Please read *[Tcllib \- How To Get The Sources](tcllib\_sources\.md)* first, -if that was not done already\. Here we assume that the sources are already -available in a directory of your choice\. - -# Tools - -The "sak\.tcl" script in the toplevel directory of a Tcllib checkout is the one -tool used by the release manager to perform its [Tasks](#section3)\. - -The main commands to be used are - - sak.tcl validate - sak.tcl test run - sak.tcl review - sak.tcl readme - sak.tcl localdoc - sak.tcl release - -More detail will be provided in the explanations of the various -[Tasks](#section3)\. - -# Tasks - -## Start a release candidate - -todo: open a candidate for release - -## Ready the candidate - -todo: test, validate and check that the candidate is worthy of release fix -testsuites, possibly fix packages, documentation regenerate docs coordinate with -package maintainers wrt fixes big thing: going over the packages, classify -changes since last release to generate a nice readme\. - -## Make it official - -todo: finalize release, make candidate official - -## Distribute the release - -With the release made it has to be published and the world notified of its -existence\. - - 1. Create a proper fossil event for the release, via - [http://core\.tcl\-lang\.org/tcllib/eventedit](http://core\.tcl\-lang\.org/tcllib/eventedit)\. - - An [existing - event](http://core\.tcl\-lang\.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817) - should be used as template\. - - 1. Update a number of web locations: - - 1) [Home - page](http://core\.tcl\-lang\.org/tcllib/doc/trunk/embedded/index\.md) - - 1) [Downloads](http://core\.tcl\-lang\.org/tcllib/wiki?name=Downloads) - - 1) [Past - Releases](http://core\.tcl\-lang\.org/tcllib/wiki?name=Past\+Releases) - - 1) [http://www\.tcl\-lang\.org/home/release\.txt](http://www\.tcl\-lang\.org/home/release\.txt) - - 1) [http://www\.tcl\-lang\.org/software/tcllib/\*\.tml](http://www\.tcl\-lang\.org/software/tcllib/\*\.tml) - - 1) [http://wiki\.tcl\-lang\.org/page/Tcllib](http://wiki\.tcl\-lang\.org/page/Tcllib) - - The first location maps to the file "embedded/index\.md" in the repository - itself, as such it can edited as part of the release process\. This is where - reference to the new fossil event is added, as the new current release\. - - The next two locations are in the fossil tcllib wiki and require admin or - wiki write permissions for - [http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib)\. - - The last two locations require ssh access to - [http://www\.tcl\-lang\.org](http://www\.tcl\-lang\.org) and permission to - edit files in the web area\. - - 1. \*\*\*TODO\*\*\* mailing lists and other places to send notes to\. DELETED embedded/md/tcllib/files/devdoc/tcllib_sources.md Index: embedded/md/tcllib/files/devdoc/tcllib_sources.md ================================================================== --- embedded/md/tcllib/files/devdoc/tcllib_sources.md +++ embedded/md/tcllib/files/devdoc/tcllib_sources.md @@ -1,85 +0,0 @@ - -[//000000001]: # (tcllib\_sources \- ) -[//000000002]: # (Generated from file 'tcllib\_sources\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tcllib\_sources\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_sources \- Tcllib \- How To Get The Sources - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Source Location](#section2) - - - [Retrieval](#section3) - - - [Source Code Management](#section4) - -# DESCRIPTION - -Welcome to Tcllib, the Tcl Standard Library\. Note that Tcllib is not a package -itself\. It is a collection of \(semi\-independent\) -*[Tcl](\.\./\.\./\.\./index\.md\#tcl)* packages that provide utility functions -useful to a large collection of Tcl programmers\. - -The audience of this document is anyone wishing to either have just a look at -Tcllib's source code, or build the packages, or to extend and modify them\. - -For builders and developers we additionally provide - - 1. *[Tcllib \- The Installer's Guide](tcllib\_installer\.md)*\. - - 1. *[Tcllib \- The Developer's Guide](tcllib\_devguide\.md)*\. - -respectively\. - -# Source Location - -The official repository for Tcllib can be found at -[http://core\.tcl\-lang\.org/tcllib](http://core\.tcl\-lang\.org/tcllib) - -# Retrieval - -Assuming that you simply wish to look at the sources, or build a specific -revision, the easiest way of retrieving it is to: - - 1. Log into this site, as "anonymous", using the semi\-random password in the - captcha\. - - 1. Go to the "Timeline"\. - - 1. Choose the revision you wish to have\. - - 1. Follow its link to its detailed information page\. - - 1. On that page, choose either the "ZIP" or "Tarball" link to get a copy of - this revision in the format of your choice\. - -# Source Code Management - -For the curious \(or a developer\-to\-be\), the sources are managed by the [Fossil -SCM](http://www\.fossil\-scm\.org)\. Binaries for popular platforms can be found -directly at its [download page](http://www\.fossil\-scm\.org/download\.html)\. - -With that tool available the full history can be retrieved via: - - fossil clone http://core.tcl-lang.org/tcllib tcllib.fossil - -followed by - - mkdir tcllib - cd tcllib - fossil open ../tcllib.fossil - -to get a checkout of the head of the trunk\. DELETED embedded/md/tcllib/files/modules/aes/aes.md Index: embedded/md/tcllib/files/modules/aes/aes.md ================================================================== --- embedded/md/tcllib/files/modules/aes/aes.md +++ embedded/md/tcllib/files/modules/aes/aes.md @@ -1,201 +0,0 @@ - -[//000000001]: # (aes \- Advanced Encryption Standard \(AES\)) -[//000000002]: # (Generated from file 'aes\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts ) -[//000000004]: # (Copyright © 2012\-2014, Andreas Kupries ) -[//000000005]: # (aes\(n\) 1\.2\.1 tcllib "Advanced Encryption Standard \(AES\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -aes \- Implementation of the AES block cipher - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [MODES OF OPERATION](#section4) - - - [EXAMPLES](#section5) - - - [REFERENCES](#section6) - - - [AUTHORS](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require aes ?1\.2\.1? - -[__::aes::aes__ ?*\-mode \[ecb|cbc\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-hex*? ?*\-out channel*? ?*\-chunksize size*? \[ *\-in channel* | ?__\-\-__? *data* \]](#1) -[__::aes::Init__ *mode* *keydata* *iv*](#2) -[__::aes::Encrypt__ *Key* *data*](#3) -[__::aes::Decrypt__ *Key* *data*](#4) -[__::aes::Reset__ *Key* *iv*](#5) -[__::aes::Final__ *Key*](#6) - -# DESCRIPTION - -This is an implementation in Tcl of the Advanced Encryption Standard \(AES\) as -published by the U\.S\. National Institute of Standards and Technology \[1\]\. AES is -a 128\-bit block cipher with a variable key size of 128, 192 or 256 bits\. This -implementation supports ECB and CBC modes\. - -# COMMANDS - - - __::aes::aes__ ?*\-mode \[ecb|cbc\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-hex*? ?*\-out channel*? ?*\-chunksize size*? \[ *\-in channel* | ?__\-\-__? *data* \] - - Perform the __aes__ algorithm on either the data provided by the - argument or on the data read from the *\-in* channel\. If an *\-out* - channel is given then the result will be written to this channel\. - - The *\-key* option must be given\. This parameter takes a binary string of - either 16, 24 or 32 bytes in length and is used to generate the key - schedule\. - - The *\-mode* and *\-dir* options are optional and default to cbc mode and - encrypt respectively\. The initialization vector *\-iv* takes a 16 byte - binary argument which defaults to all zeros\. See [MODES OF - OPERATION](#section4) for more about available modes and their uses\. - - AES is a 128\-bit block cipher\. This means that the data must be provided in - units that are a multiple of 16 bytes\. - -# PROGRAMMING INTERFACE - -Internal state is maintained in an opaque structure that is returned from the -__Init__ function\. In ECB mode the state is not affected by the input but -for CBC mode some input dependent state is maintained and may be reset by -calling the __Reset__ function with a new initialization vector value\. - - - __::aes::Init__ *mode* *keydata* *iv* - - Construct a new AES key schedule using the specified key data and the given - initialization vector\. The initialization vector is not used with ECB mode - but is important for CBC mode\. See [MODES OF OPERATION](#section4) for - details about cipher modes\. - - - __::aes::Encrypt__ *Key* *data* - - Use a prepared key acquired by calling __Init__ to encrypt the provided - data\. The data argument should be a binary array that is a multiple of the - AES block size of 16 bytes\. The result is a binary array the same size as - the input of encrypted data\. - - - __::aes::Decrypt__ *Key* *data* - - Decipher data using the key\. Note that the same key may be used to encrypt - and decrypt data provided that the initialization vector is reset - appropriately for CBC mode\. - - - __::aes::Reset__ *Key* *iv* - - Reset the initialization vector\. This permits the programmer to re\-use a key - and avoid the cost of re\-generating the key schedule where the same key data - is being used multiple times\. - - - __::aes::Final__ *Key* - - This should be called to clean up resources associated with *Key*\. Once - this function has been called the key may not be used again\. - -# MODES OF OPERATION - - - Electronic Code Book \(ECB\) - - ECB is the basic mode of all block ciphers\. Each block is encrypted - independently and so identical plain text will produce identical output when - encrypted with the same key\. Any encryption errors will only affect a single - block however this is vulnerable to known plaintext attacks\. - - - Cipher Block Chaining \(CBC\) - - CBC mode uses the output of the last block encryption to affect the current - block\. An initialization vector of the same size as the cipher block size is - used to handle the first block\. The initialization vector should be chosen - randomly and transmitted as the first block of the output\. Errors in - encryption affect the current block and the next block after which the - cipher will correct itself\. CBC is the most commonly used mode in software - encryption\. This is the default mode of operation for this module\. - -# EXAMPLES - - % set nil_block [string repeat \\0 16] - % aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block - 66e94bd4ef8a2c3b884cfa59ca342b2e - - set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv] - append ciphertext [aes::Encrypt $Key $plaintext] - append ciphertext [aes::Encrypt $Key $additional_plaintext] - aes::Final $Key - -# REFERENCES - - 1. "Advanced Encryption Standard", Federal Information Processing Standards - Publication 197, 2001 - \([http://csrc\.nist\.gov/publications/fips/fips197/fips\-197\.pdf](http://csrc\.nist\.gov/publications/fips/fips197/fips\-197\.pdf)\) - -# AUTHORS - -Thorsten Schloermann, Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *aes* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[blowfish\(n\)](\.\./blowfish/blowfish\.md), [des\(n\)](\.\./des/des\.md), -[md5\(n\)](\.\./md5/md5\.md), [sha1\(n\)](\.\./sha1/sha1\.md) - -# KEYWORDS - -[aes](\.\./\.\./\.\./\.\./index\.md\#aes), [block -cipher](\.\./\.\./\.\./\.\./index\.md\#block\_cipher), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2005, Pat Thoyts -Copyright © 2012\-2014, Andreas Kupries DELETED embedded/md/tcllib/files/modules/amazon-s3/S3.md Index: embedded/md/tcllib/files/modules/amazon-s3/S3.md ================================================================== --- embedded/md/tcllib/files/modules/amazon-s3/S3.md +++ embedded/md/tcllib/files/modules/amazon-s3/S3.md @@ -1,1514 +0,0 @@ - -[//000000001]: # (S3 \- Amazon S3 Web Service Utilities) -[//000000002]: # (Generated from file 'S3\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (2006,2008 Darren New\. All Rights Reserved\. See LICENSE\.TXT for terms\.) -[//000000004]: # (S3\(n\) 1\.0\.3 tcllib "Amazon S3 Web Service Utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -S3 \- Amazon S3 Web Service Interface - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [ERROR REPORTING](#section2) - - - [COMMANDS](#section3) - - - [LOW LEVEL COMMANDS](#section4) - - - [HIGH LEVEL COMMANDS](#section5) - - - [LIMITATIONS](#section6) - - - [USAGE SUGGESTIONS](#section7) - - - [FUTURE DEVELOPMENTS](#section8) - - - [TLS Security Considerations](#section9) - - - [Bugs, Ideas, Feedback](#section10) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require S3 ?1\.0\.3? -package require sha1 1\.0 -package require md5 2\.0 -package require base64 2\.3 -package require xsxp 1\.0 - -[__S3::Configure__ ?__\-reset__ *boolean*? ?__\-retries__ *integer*? ?__\-accesskeyid__ *idstring*? ?__\-secretaccesskey__ *idstring*? ?__\-service\-access\-point__ *FQDN*? ?__\-use\-tls__ *boolean*? ?__\-default\-compare__ *always|never|exists|missing|newer|date|checksum|different*? ?__\-default\-separator__ *string*? ?__\-default\-acl__ *private|public\-read|public\-read\-write|authenticated\-read|keep|calc*? ?__\-default\-bucket__ *bucketname*?](#1) -[__S3::SuggestBucket__ ?*name*?](#2) -[__S3::REST__ *dict*](#3) -[__S3::ListAllMyBuckets__ ?__\-blocking__ *boolean*? ?__\-parse\-xml__ *xmlstring*? ?__\-result\-type__ *REST|xml|pxml|dict|names|owner*?](#4) -[__S3::PutBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*? ?__\-acl__ *\{\}|private|public\-read|public\-read\-write|authenticated\-read*?](#5) -[__S3::DeleteBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*?](#6) -[__S3::GetBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*? ?__\-parse\-xml__ *xmlstring*? ?__\-max\-count__ *integer*? ?__\-prefix__ *prefixstring*? ?__\-delimiter__ *delimiterstring*? ?__\-result\-type__ *REST|xml|pxml|names|dict*?](#7) -[__S3::Put__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-file__ *filename*? ?__\-content__ *contentstring*? ?__\-acl__ *private|public\-read|public\-read\-write|authenticated\-read|calc|keep*? ?__\-content\-type__ *contenttypestring*? ?__\-x\-amz\-meta\-\*__ *metadatatext*? ?__\-compare__ *comparemode*?](#8) -[__S3::Get__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-compare__ *comparemode*? ?__\-file__ *filename*? ?__\-content__ *contentvarname*? ?__\-timestamp__ *aws|now*? ?__\-headers__ *headervarname*?](#9) -[__S3::Head__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-dict__ *dictvarname*? ?__\-headers__ *headersvarname*? ?__\-status__ *statusvarname*?](#10) -[__S3::GetAcl__ ?__\-blocking__ *boolean*? ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-result\-type__ *REST|xml|pxml*?](#11) -[__S3::PutAcl__ ?__\-blocking__ *boolean*? ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-acl__ *new\-acl*?](#12) -[__S3::Delete__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-status__ *statusvar*?](#13) -[__S3::Push__ ?__\-bucket__ *bucketname*? __\-directory__ *directoryname* ?__\-prefix__ *prefixstring*? ?__\-compare__ *comparemode*? ?__\-x\-amz\-meta\-\*__ *metastring*? ?__\-acl__ *aclcode*? ?__\-delete__ *boolean*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*?](#14) -[__S3::Pull__ ?__\-bucket__ *bucketname*? __\-directory__ *directoryname* ?__\-prefix__ *prefixstring*? ?__\-blocking__ *boolean*? ?__\-compare__ *comparemode*? ?__\-delete__ *boolean*? ?__\-timestamp__ *aws|now*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*?](#15) -[__S3::Toss__ ?__\-bucket__ *bucketname*? __\-prefix__ *prefixstring* ?__\-blocking__ *boolean*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*?](#16) - -# DESCRIPTION - -This package provides access to Amazon's Simple Storage Solution web service\. - -As a quick summary, Amazon Simple Storage Solution provides a for\-fee web -service allowing the storage of arbitrary data as "resources" within "buckets" -online\. See [http://www\.amazonaws\.com/](http://www\.amazonaws\.com/) for -details on that system\. Access to the service is via HTTP \(SOAP or REST\)\. Much -of this documentation will not make sense if you're not familiar with the terms -and functionality of the Amazon S3 service\. - -This package provides services for reading and writing the data items via the -REST interface\. It also provides some higher\-level operations\. Other packages in -the same distribution provide for even more functionality\. - -Copyright 2006 Darren New\. All Rights Reserved\. NO WARRANTIES OF ANY TYPE ARE -PROVIDED\. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS\. This software is -licensed under essentially the same terms as Tcl\. See LICENSE\.txt for the terms\. - -# ERROR REPORTING - -The error reporting from this package makes use of $errorCode to provide more -details on what happened than simply throwing an error\. Any error caught by the -S3 package \(and we try to catch them all\) will return with an $errorCode being a -list having at least three elements\. In all cases, the first element will be -"S3"\. The second element will take on one of six values, with that element -defining the value of the third and subsequent elements\. S3::REST does not throw -an error, but rather returns a dictionary with the keys "error", "errorInfo", -and "errorCode" set\. This allows for reliable background use\. The possible -second elements are these: - - - usage - - The usage of the package is incorrect\. For example, a command has been - invoked which requires the library to be configured before the library has - been configured, or an invalid combination of options has been specified\. - The third element of $errorCode supplies the name of the parameter that was - wrong\. The fourth usually provides the arguments that were actually supplied - to the throwing proc, unless the usage error isn't confined to a single - proc\. - - - local - - Something happened on the local system which threw an error\. For example, a - request to upload or download a file was made and the file permissions - denied that sort of access\. The third element of $errorCode is the original - $errorCode\. - - - socket - - Something happened with the socket\. It closed prematurely, or some other - condition of failure\-to\-communicate\-with\-Amazon was detected\. The third - element of $errorCode is the original $errorCode, or sometimes the message - from fcopy, or \.\.\.? - - - remote - - The Amazon web service returned an error code outside the 2xx range in the - HTTP header\. In other words, everything went as documented, except this - particular case was documented not to work\. The third element is the - dictionary returned from __::S3::REST__\. Note that S3::REST itself never - throws this error, but just returns the dictionary\. Most of the higher\-level - commands throw for convenience, unless an argument indicates they should - not\. If something is documented as "not throwing an S3 remote error", it - means a status return is set rather than throwing an error if Amazon returns - a non\-2XX HTTP result code\. - - - notyet - - The user obeyed the documentation, but the author has not yet gotten around - to implementing this feature\. \(Right now, only TLS support and sophisticated - permissions fall into this category, as well as the S3::Acl command\.\) - - - xml - - The service has returned invalid XML, or XML whose schema is unexpected\. For - the high\-level commands that accept service XML as input for parsing, this - may also be thrown\. - -# COMMANDS - -This package provides several separate levels of complexity\. - - - The lowest level simply takes arguments to be sent to the service, sends - them, retrieves the result, and provides it to the caller\. *Note:* This - layer allows both synchronous and event\-driven processing\. It depends on the - MD5 and SHA1 and base64 packages from Tcllib \(available at - [http://core\.tcl\.tk/tcllib/](http://core\.tcl\.tk/tcllib/)\)\. Note that - __S3::Configure__ is required for __S3::REST__ to work due to the - authentication portion, so we put that in the "lowest level\." - - - The next layer parses the results of calls, allowing for functionality such - as uploading only changed files, synchronizing directories, and so on\. This - layer depends on the __TclXML__ package as well as the included - __[xsxp](xsxp\.md)__ package\. These packages are package required - when these more\-sophisticated routines are called, so nothing breaks if they - are not correctly installed\. - - - Also included is a separate program that uses the library\. It provides code - to parse $argv0 and $argv from the command line, allowing invocation as a - tclkit, etc\. \(Not yet implmented\.\) - - - Another separate program provides a GUI interface allowing drag\-and\-drop and - other such functionality\. \(Not yet implemented\.\) - - - Also built on this package is the OddJob program\. It is a separate program - designed to allow distribution of computational work units over Amazon's - Elastic Compute Cloud web service\. - -The goal is to have at least the bottom\-most layers implemented in pure Tcl -using only that which comes from widely\-available sources, such as Tcllib\. - -# LOW LEVEL COMMANDS - -These commands do not require any packages not listed above\. They talk directly -to the service, or they are utility or configuration routines\. Note that the -"xsxp" package was written to support this package, so it should be available -wherever you got this package\. - - - __S3::Configure__ ?__\-reset__ *boolean*? ?__\-retries__ *integer*? ?__\-accesskeyid__ *idstring*? ?__\-secretaccesskey__ *idstring*? ?__\-service\-access\-point__ *FQDN*? ?__\-use\-tls__ *boolean*? ?__\-default\-compare__ *always|never|exists|missing|newer|date|checksum|different*? ?__\-default\-separator__ *string*? ?__\-default\-acl__ *private|public\-read|public\-read\-write|authenticated\-read|keep|calc*? ?__\-default\-bucket__ *bucketname*? - - There is one command for configuration, and that is __S3::Configure__\. - If called with no arguments, it returns a dictionary of key/value pairs - listing all current settings\. If called with one argument, it returns the - value of that single argument\. If called with two or more arguments, it must - be called with pairs of arguments, and it applies the changes in order\. - There is only one set of configuration information per interpreter\. - - The following options are accepted: - - * __\-reset__ *boolean* - - By default, false\. If true, any previous changes and any changes on the - same call before the reset option will be returned to default values\. - - * __\-retries__ *integer* - - Default value is 3\. If Amazon returns a 500 error, a retry after an - exponential backoff delay will be tried this many times before finally - throwing the 500 error\. This applies to each call to __S3::REST__ - from the higher\-level commands, but not to __S3::REST__ itself\. That - is, __S3::REST__ will always return httpstatus 500 if that's what it - receives\. Functions like __S3::Put__ will retry the PUT call, and - will also retry the GET and HEAD calls used to do content comparison\. - Changing this to 0 will prevent retries and their associated delays\. In - addition, socket errors \(i\.e\., errors whose errorCode starts with "S3 - socket"\) will be similarly retried after backoffs\. - - * __\-accesskeyid__ *idstring* - - * __\-secretaccesskey__ *idstring* - - Each defaults to an empty string\. These must be set before any calls are - made\. This is your S3 ID\. Once you sign up for an account, go to - [http://www\.amazonaws\.com/](http://www\.amazonaws\.com/), sign in, go - to the "Your Web Services Account" button, pick "AWS Access - Identifiers", and your access key ID and secret access keys will be - available\. All __S3::REST__ calls are authenticated\. Blame Amazon - for the poor choice of names\. - - * __\-service\-access\-point__ *FQDN* - - Defaults to "s3\.amazonaws\.com"\. This is the fully\-qualified domain name - of the server to contact for __S3::REST__ calls\. You should probably - never need to touch this, unless someone else implements a compatible - service, or you wish to test something by pointing the library at your - own service\. - - * __\-slop\-seconds__ *integer* - - When comparing dates between Amazon and the local machine, two dates - within this many seconds of each other are considered the same\. Useful - for clock drift correction, processing overhead time, and so on\. - - * __\-use\-tls__ *boolean* - - Defaults to false\. This is not yet implemented\. If true, - __S3::REST__ will negotiate a TLS connection to Amazon\. If false, - unencrypted connections are used\. - - * __\-bucket\-prefix__ *string* - - Defaults to "TclS3"\. This string is used by - __S3::SuggestBucketName__ if that command is passed an empty string - as an argument\. It is used to distinguish different applications using - the Amazon service\. Your application should always set this to keep from - interfering with the buckets of other users of Amazon S3 or with other - buckets of the same user\. - - * __\-default\-compare__ *always|never|exists|missing|newer|date|checksum|different* - - Defaults to "always\." If no \-compare is specified on __S3::Put__, - __S3::Get__, or __S3::Delete__, this comparison is used\. See - those commands for a description of the meaning\. - - * __\-default\-separator__ *string* - - Defaults to "/"\. This is currently unused\. It might make sense to use - this for __S3::Push__ and __S3::Pull__, but allowing resources - to have slashes in their names that aren't marking directories would be - problematic\. Hence, this currently does nothing\. - - * __\-default\-acl__ *private|public\-read|public\-read\-write|authenticated\-read|keep|calc* - - Defaults to an empty string\. If no \-acl argument is provided to - __S3::Put__ or __S3::Push__, this string is used \(given as the - x\-amz\-acl header if not keep or calc\)\. If this is also empty, no - x\-amz\-acl header is generated\. This is *not* used by __S3::REST__\. - - * __\-default\-bucket__ *bucketname* - - If no bucket is given to __S3::GetBucket__, __S3::PutBucket__, - __S3::Get__, __S3::Put__, __S3::Head__, __S3::Acl__, - __S3::Delete__, __S3::Push__, __S3::Pull__, or - __S3::Toss__, and if this configuration variable is not an empty - string \(and not simply "/"\), then this value will be used for the - bucket\. This is useful if one program does a large amount of resource - manipulation within a single bucket\. - - - __S3::SuggestBucket__ ?*name*? - - The __S3::SuggestBucket__ command accepts an optional string as a prefix - and returns a valid bucket containing the *name* argument and the Access - Key ID\. This makes the name unique to the owner and to the application - \(assuming the application picks a good *name* argument\)\. If no name is - provided, the name from __S3::Configure__ *\-bucket\-prefix* is used\. If - that too is empty \(which is not the default\), an error is thrown\. - - - __S3::REST__ *dict* - - The __S3::REST__ command takes as an argument a dictionary and returns a - dictionary\. The return dictionary has the same keys as the input dictionary, - and includes additional keys as the result\. The presence or absence of keys - in the input dictionary can control the behavior of the routine\. It never - throws an error directly, but includes keys "error", "errorInfo", and - "errorCode" if necessary\. Some keys are required, some optional\. The routine - can run either in blocking or non\-blocking mode, based on the presense of - __resultvar__ in the input dictionary\. This requires the - *\-accesskeyid* and *\-secretaccesskey* to be configured via - __S3::Configure__ before being called\. - - The possible input keys are these: - - * __verb__ *GET|PUT|DELETE|HEAD* - - This required item indicates the verb to be used\. - - * __resource__ *string* - - This required item indicates the resource to be accessed\. A leading / is - added if not there already\. It will be URL\-encoded for you if necessary\. - Do not supply a resource name that is already URL\-encoded\. - - * ?__rtype__ *torrent|acl*? - - This indicates a torrent or acl resource is being manipulated\. Do not - include this in the __resource__ key, or the "?" separator will get - URL\-encoded\. - - * ?__parameters__ *dict*? - - This optional dictionary provides parameters added to the URL for the - transaction\. The keys must be in the correct case \(which is confusing in - the Amazon documentation\) and the values must be valid\. This can be an - empty dictionary or omitted entirely if no parameters are desired\. No - other error checking on parameters is performed\. - - * ?__headers__ *dict*? - - This optional dictionary provides headers to be added to the HTTP - request\. The keys must be in *lower case* for the authentication to - work\. The values must not contain embedded newlines or carriage returns\. - This is primarily useful for adding x\-amz\-\* headers\. Since - authentication is calculated by __S3::REST__, do not add that header - here\. Since content\-type gets its own key, also do not add that header - here\. - - * ?__inbody__ *contentstring*? - - This optional item, if provided, gives the content that will be sent\. It - is sent with a tranfer encoding of binary, and only the low bytes are - used, so use \[encoding convertto utf\-8\] if the string is a utf\-8 string\. - This is written all in one blast, so if you are using non\-blocking mode - and the __inbody__ is especially large, you may wind up blocking on - the write socket\. - - * ?__infile__ *filename*? - - This optional item, if provided, and if __inbody__ is not provided, - names the file from which the body of the HTTP message will be - constructed\. The file is opened for reading and sent progressively by - \[fcopy\], so it should not block in non\-blocking mode even if the file is - very large\. The file is transfered in binary mode, so the bytes on your - disk will match the bytes in your resource\. Due to HTTP restrictions, it - must be possible to use \[file size\] on this file to determine the size - at the start of the transaction\. - - * ?__S3chan__ *channel*? - - This optional item, if provided, indicates the already\-open socket over - which the transaction should be conducted\. If not provided, a connection - is made to the service access point specified via __S3::Configure__, - which is normally s3\.amazonaws\.com\. If this is provided, the channel is - not closed at the end of the transaction\. - - * ?__outchan__ *channel*? - - This optional item, if provided, indicates the already\-open channel to - which the body returned from S3 should be written\. That is, to retrieve - a large resource, open a file, set the translation mode, and pass the - channel as the value of the key outchan\. Output will be written to the - channel in pieces so memory does not fill up unnecessarily\. The channel - is not closed at the end of the transaction\. - - * ?__resultvar__ *varname*? - - This optional item, if provided, indicates that __S3::REST__ should - run in non\-blocking mode\. The *varname* should be fully qualified with - respect to namespaces and cannot be local to a proc\. If provided, the - result of the __S3::REST__ call is assigned to this variable once - everything has completed; use trace or vwait to know when this has - happened\. If this key is not provided, the result is simply returned - from the call to __S3::REST__ and no calls to the eventloop are - invoked from within this call\. - - * ?__throwsocket__ *throw|return*? - - This optional item, if provided, indicates that __S3::REST__ should - throw an error if throwmode is throw and a socket error is encountered\. - It indicates that __S3::REST__ should return the error code in the - returned dictionary if a socket error is encountered and this is set to - return\. If __throwsocket__ is set to *return* or if the call is - not blocking, then a socket error \(i\.e\., an error whose error code - starts with "S3 socket" will be returned in the dictionary as - __error__, __errorInfo__, and __errorCode__\. If a foreground - call is made \(i\.e\., __resultvar__ is not provided\), and this option - is not provided or is set to *throw*, then - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ will be invoked instead\. - - Once the call to __S3::REST__ completes, a new dict is returned, either - in the *resultvar* or as the result of execution\. This dict is a copy of - the original dict with the results added as new keys\. The possible new keys - are these: - - * __error__ *errorstring* - - * __errorInfo__ *errorstring* - - * __errorCode__ *errorstring* - - If an error is caught, these three keys will be set in the result\. Note - that __S3::REST__ does *not* consider a non\-2XX HTTP return code - as an error\. The __errorCode__ value will be formatted according to - the [ERROR REPORTING](#section2) description\. If these are present, - other keys described here might not be\. - - * __httpstatus__ *threedigits* - - The three\-digit code from the HTTP transaction\. 2XX for good, 5XX for - server error, etc\. - - * __httpmessage__ *text* - - The textual result after the status code\. "OK" or "Forbidden" or etc\. - - * __outbody__ *contentstring* - - If *outchan* was not specified, this key will hold a reference to the - \(unencoded\) contents of the body returned\. If Amazon returned an error - \(a la the httpstatus not a 2XX value\), the error message will be in - __outbody__ or written to __outchan__ as appropriate\. - - * __outheaders__ *dict* - - This contains a dictionary of headers returned by Amazon\. The keys are - always lower case\. It's mainly useful for finding the x\-amz\-meta\-\* - headers, if any, although things like last\-modified and content\-type are - also useful\. The keys of this dictionary are always lower case\. Both - keys and values are trimmed of extraneous whitespace\. - -# HIGH LEVEL COMMANDS - -The routines in this section all make use of one or more calls to -__S3::REST__ to do their work, then parse and manage the data in a -convenient way\. All these commands throw errors as described in [ERROR -REPORTING](#section2) unless otherwise noted\. - -In all these commands, all arguments are presented as name/value pairs, in any -order\. All the argument names start with a hyphen\. - -There are a few options that are common to many of the commands, and those -common options are documented here\. - - - __\-blocking__ *boolean* - - If provided and specified as false, then any calls to __S3:REST__ will - be non\-blocking, and internally these routines will call \[vwait\] to get the - results\. In other words, these routines will return the same value, but - they'll have event loops running while waiting for Amazon\. - - - __\-parse\-xml__ *xmlstring* - - If provided, the routine skips actually communicating with Amazon, and - instead behaves as if the XML string provided was returned as the body of - the call\. Since several of these routines allow the return of data in - various formats, this argument can be used to parse existing XML to extract - the bits of information that are needed\. It's also helpful for testing\. - - - __\-bucket__ *bucketname* - - Almost every high\-level command needs to know what bucket the resources are - in\. This option specifies that\. \(Only the command to list available buckets - does not require this parameter\.\) This does not need to be URL\-encoded, even - if it contains special or non\-ASCII characters\. May or may not contain - leading or trailing spaces \- commands normalize the bucket\. If this is not - supplied, the value is taken from __S3::Configure \-default\-bucket__ if - that string isn't empty\. Note that spaces and slashes are always trimmed - from both ends and the rest must leave a valid bucket\. - - - __\-resource__ *resourcename* - - This specifies the resource of interest within the bucket\. It may or may not - start with a slash \- both cases are handled\. This does not need to be - URL\-encoded, even if it contains special or non\-ASCII characters\. - - - __\-compare__ *always|never|exists|missing|newer|date|checksum|different* - - When commands copy resources to files or files to resources, the caller may - specify that the copy should be skipped if the contents are the same\. This - argument specifies the conditions under which the files should be copied\. If - it is not passed, the result of __S3::Configure \-default\-compare__ is - used, which in turn defaults to "always\." The meanings of the various values - are these: - - * *always* - - Always copy the data\. This is the default\. - - * *never* - - Never copy the data\. This is essentially a no\-op, except in - __S3::Push__ and __S3::Pull__ where the \-delete flag might make - a difference\. - - * *exists* - - Copy the data only if the destination already exists\. - - * *missing* - - Copy the data only if the destination does not already exist\. - - * *newer* - - Copy the data if the destination is missing, or if the date on the - source is newer than the date on the destination by at least - __S3::Configure \-slop\-seconds__ seconds\. If the source is Amazon, - the date is taken from the Last\-Modified header\. If the source is local, - it is taken as the mtime of the file\. If the source data is specified in - a string rather than a file, it is taken as right now, via \[clock - seconds\]\. - - * *date* - - Like *newer*, except copy if the date is newer *or* older\. - - * *checksum* - - Calculate the MD5 checksum on the local file or string, ask Amazon for - the eTag of the resource, and copy the data if they're different\. Copy - the data also if the destination is missing\. Note that this can be slow - with large local files unless the C version of the MD5 support is - available\. - - * *different* - - Copy the data if the destination does not exist\. If the destination - exists and an actual file name was specified \(rather than a content - string\), and the date on the file differs from the date on the resource, - copy the data\. If the data is provided as a content string, the "date" - is treated as "right now", so it will likely always differ unless - slop\-seconds is large\. If the dates are the same, the MD5 checksums are - compared, and the data is copied if the checksums differ\. - - Note that "newer" and "date" don't care about the contents, and "checksum" - doesn't care about the dates, but "different" checks both\. - - - __S3::ListAllMyBuckets__ ?__\-blocking__ *boolean*? ?__\-parse\-xml__ *xmlstring*? ?__\-result\-type__ *REST|xml|pxml|dict|names|owner*? - - This routine performs a GET on the Amazon S3 service, which is defined to - return a list of buckets owned by the account identified by the - authorization header\. \(Blame Amazon for the dumb names\.\) - - * __\-blocking__ *boolean* - - See above for standard definition\. - - * __\-parse\-xml__ *xmlstring* - - See above for standard definition\. - - * __\-result\-type__ *REST* - - The dictionary returned by __S3::REST__ is the return value of - __S3::ListAllMyBuckets__\. In this case, a non\-2XX httpstatus will - not throw an error\. You may not combine this with *\-parse\-xml*\. - - * __\-result\-type__ *xml* - - The raw XML of the body is returned as the result \(with no encoding - applied\)\. - - * __\-result\-type__ *pxml* - - The XML of the body as parsed by __xsxp::parse__ is returned\. - - * __\-result\-type__ *dict* - - A dictionary of interesting portions of the XML is returned\. The - dictionary contains the following keys: - - + Owner/ID - - The Amazon AWS ID \(in hex\) of the owner of the bucket\. - - + Owner/DisplayName - - The Amazon AWS ID's Display Name\. - - + Bucket/Name - - A list of names, one for each bucket\. - - + Bucket/CreationDate - - A list of dates, one for each bucket, in the same order as - Bucket/Name, in ISO format \(as returned by Amazon\)\. - - * __\-result\-type__ *names* - - A list of bucket names is returned with all other information stripped - out\. This is the default result type for this command\. - - * __\-result\-type__ *owner* - - A list containing two elements is returned\. The first element is the - owner's ID, and the second is the owner's display name\. - - - __S3::PutBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*? ?__\-acl__ *\{\}|private|public\-read|public\-read\-write|authenticated\-read*? - - This command creates a bucket if it does not already exist\. Bucket names are - globally unique, so you may get a "Forbidden" error from Amazon even if you - cannot see the bucket in __S3::ListAllMyBuckets__\. See - __S3::SuggestBucket__ for ways to minimize this risk\. The x\-amz\-acl - header comes from the __\-acl__ option, or from __S3::Configure - \-default\-acl__ if not specified\. - - - __S3::DeleteBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*? - - This command deletes a bucket if it is empty and you have such permission\. - Note that Amazon's list of buckets is a global resource, requiring far\-flung - synchronization\. If you delete a bucket, it may be quite a few minutes \(or - hours\) before you can recreate it, yielding "Conflict" errors until then\. - - - __S3::GetBucket__ ?__\-bucket__ *bucketname*? ?__\-blocking__ *boolean*? ?__\-parse\-xml__ *xmlstring*? ?__\-max\-count__ *integer*? ?__\-prefix__ *prefixstring*? ?__\-delimiter__ *delimiterstring*? ?__\-result\-type__ *REST|xml|pxml|names|dict*? - - This lists the contents of a bucket\. That is, it returns a directory listing - of resources within a bucket, rather than transfering any user data\. - - * __\-bucket__ *bucketname* - - The standard bucket argument\. - - * __\-blocking__ *boolean* - - The standard blocking argument\. - - * __\-parse\-xml__ *xmlstring* - - The standard parse\-xml argument\. - - * __\-max\-count__ *integer* - - If supplied, this is the most number of records to be returned\. If not - supplied, the code will iterate until all records have been found\. Not - compatible with \-parse\-xml\. Note that if this is supplied, only one call - to __S3::REST__ will be made\. Otherwise, enough calls will be made - to exhaust the listing, buffering results in memory, so take care if you - may have huge buckets\. - - * __\-prefix__ *prefixstring* - - If present, restricts listing to resources with a particular prefix\. One - leading / is stripped if present\. - - * __\-delimiter__ *delimiterstring* - - If present, specifies a delimiter for the listing\. The presence of this - will summarize multiple resources into one entry, as if S3 supported - directories\. See the Amazon documentation for details\. - - * __\-result\-type__ *REST|xml|pxml|names|dict* - - This indicates the format of the return result of the command\. - - + REST - - If *\-max\-count* is specified, the dictionary returned from - __S3::REST__ is returned\. If *\-max\-count* is not specified, a - list of all the dictionaries returned from the one or more calls to - __S3::REST__ is returned\. - - + xml - - If *\-max\-count* is specified, the body returned from - __S3::REST__ is returned\. If *\-max\-count* is not specified, a - list of all the bodies returned from the one or more calls to - __S3::REST__ is returned\. - - + pxml - - If *\-max\-count* is specified, the body returned from - __S3::REST__ is passed throught __xsxp::parse__ and then - returned\. If *\-max\-count* is not specified, a list of all the - bodies returned from the one or more calls to __S3::REST__ are - each passed through __xsxp::parse__ and then returned\. - - + names - - Returns a list of all names found in either the Contents/Key fields - or the CommonPrefixes/Prefix fields\. If no *\-delimiter* is - specified and no *\-max\-count* is specified, this returns a list of - all resources with the specified *\-prefix*\. - - + dict - - Returns a dictionary\. \(Returns only one dictionary even if - *\-max\-count* wasn't specified\.\) The keys of the dictionary are as - follows: - - - Name - - The name of the bucket \(from the final call to - __S3::REST__\)\. - - - Prefix - - From the final call to __S3::REST__\. - - - Marker - - From the final call to __S3::REST__\. - - - MaxKeys - - From the final call to __S3::REST__\. - - - IsTruncated - - From the final call to __S3::REST__, so always false if - *\-max\-count* is not specified\. - - - NextMarker - - Always provided if IsTruncated is true, and calculated of Amazon - does not provide it\. May be empty if IsTruncated is false\. - - - Key - - A list of names of resources in the bucket matching the - *\-prefix* and *\-delimiter* restrictions\. - - - LastModified - - A list of times of resources in the bucket, in the same order as - Key, in the format returned by Amazon\. \(I\.e\., it is not parsed - into a seconds\-from\-epoch\.\) - - - ETag - - A list of entity tags \(a\.k\.a\. MD5 checksums\) in the same order - as Key\. - - - Size - - A list of sizes in bytes of the resources, in the same order as - Key\. - - - Owner/ID - - A list of owners of the resources in the bucket, in the same - order as Key\. - - - Owner/DisplayName - - A list of owners of the resources in the bucket, in the same - order as Key\. These are the display names\. - - - CommonPrefixes/Prefix - - A list of prefixes common to multiple entities\. This is present - only if *\-delimiter* was supplied\. - - - __S3::Put__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-file__ *filename*? ?__\-content__ *contentstring*? ?__\-acl__ *private|public\-read|public\-read\-write|authenticated\-read|calc|keep*? ?__\-content\-type__ *contenttypestring*? ?__\-x\-amz\-meta\-\*__ *metadatatext*? ?__\-compare__ *comparemode*? - - This command sends data to a resource on Amazon's servers for storage, using - the HTTP PUT command\. It returns 0 if the __\-compare__ mode prevented - the transfer, 1 if the transfer worked, or throws an error if the transfer - was attempted but failed\. Server 5XX errors and S3 socket errors are retried - according to __S3:Configure \-retries__ settings before throwing an - error; other errors throw immediately\. - - * __\-bucket__ - - This specifies the bucket into which the resource will be written\. - Leading and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-blocking__ - - The standard blocking flag\. - - * __\-file__ - - If this is specified, the *filename* must exist, must be readable, and - must not be a special or directory file\. \[file size\] must apply to it - and must not change for the lifetime of the call\. The default - content\-type is calculated based on the name and/or contents of the - file\. Specifying this is an error if __\-content__ is also specified, - but at least one of __\-file__ or __\-content__ must be specified\. - \(The file is allowed to not exist or not be readable if __\-compare__ - *never* is specified\.\) - - * __\-content__ - - If this is specified, the *contentstring* is sent as the body of the - resource\. The content\-type defaults to "application/octet\-string"\. Only - the low bytes are sent, so non\-ASCII should use the appropriate encoding - \(such as \[encoding convertto utf\-8\]\) before passing it to this routine, - if necessary\. Specifying this is an error if __\-file__ is also - specified, but at least one of __\-file__ or __\-content__ must be - specified\. - - * __\-acl__ - - This defaults to __S3::Configure \-default\-acl__ if not specified\. It - sets the x\-amz\-acl header on the PUT operation\. If the value provided is - *calc*, the x\-amz\-acl header is calculated based on the I/O - permissions of the file to be uploaded; it is an error to specify - *calc* and __\-content__\. If the value provided is *keep*, the - acl of the resource is read before the PUT \(or the default is used if - the resource does not exist\), then set back to what it was after the PUT - \(if it existed\)\. An error will occur if the resource is successfully - written but the kept ACL cannot be then applied\. This should never - happen\. *Note:* *calc* is not currently fully implemented\. - - * __\-x\-amz\-meta\-\*__ - - If any header starts with "\-x\-amz\-meta\-", its contents are added to the - PUT command to be stored as metadata with the resource\. Again, no - encoding is performed, and the metadata should not contain characters - like newlines, carriage returns, and so on\. It is best to stick with - simple ASCII strings, or to fix the library in several places\. - - * __\-content\-type__ - - This overrides the content\-type calculated by __\-file__ or sets the - content\-type for __\-content__\. - - * __\-compare__ - - This is the standard compare mode argument\. __S3::Put__ returns 1 if - the data was copied or 0 if the data was skipped due to the comparison - mode so indicating it should be skipped\. - - - __S3::Get__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-compare__ *comparemode*? ?__\-file__ *filename*? ?__\-content__ *contentvarname*? ?__\-timestamp__ *aws|now*? ?__\-headers__ *headervarname*? - - This command retrieves data from a resource on Amazon's S3 servers, using - the HTTP GET command\. It returns 0 if the __\-compare__ mode prevented - the transfer, 1 if the transfer worked, or throws an error if the transfer - was attempted but failed\. Server 5XX errors and S3 socket errors are are - retried according to __S3:Configure__ settings before throwing an error; - other errors throw immediately\. Note that this is always authenticated as - the user configured in via __S3::Configure \-accesskeyid__\. Use the - Tcllib http for unauthenticated GETs\. - - * __\-bucket__ - - This specifies the bucket from which the resource will be read\. Leading - and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-blocking__ - - The standard blocking flag\. - - * __\-file__ - - If this is specified, the body of the resource will be read into this - file, incrementally without pulling it entirely into memory first\. The - parent directory must already exist\. If the file already exists, it must - be writable\. If an error is thrown part\-way through the process and the - file already existed, it may be clobbered\. If an error is thrown - part\-way through the process and the file did not already exist, any - partial bits will be deleted\. Specifying this is an error if - __\-content__ is also specified, but at least one of __\-file__ or - __\-content__ must be specified\. - - * __\-timestamp__ - - This is only valid in conjunction with __\-file__\. It may be - specified as *now* or *aws*\. The default is *now*\. If *now*, the - file's modification date is left up to the system\. If *aws*, the - file's mtime is set to match the Last\-Modified header on the resource, - synchronizing the two appropriately for __\-compare__ *date* or - __\-compare__ *newer*\. - - * __\-content__ - - If this is specified, the *contentvarname* is a variable in the - caller's scope \(not necessarily global\) that receives the value of the - body of the resource\. No encoding is done, so if the resource \(for - example\) represents a UTF\-8 byte sequence, use \[encoding convertfrom - utf\-8\] to get a valid UTF\-8 string\. If this is specified, the - __\-compare__ is ignored unless it is *never*, in which case no - assignment to *contentvarname* is performed\. Specifying this is an - error if __\-file__ is also specified, but at least one of - __\-file__ or __\-content__ must be specified\. - - * __\-compare__ - - This is the standard compare mode argument\. __S3::Get__ returns 1 if - the data was copied or 0 if the data was skipped due to the comparison - mode so indicating it should be skipped\. - - * __\-headers__ - - If this is specified, the headers resulting from the fetch are stored in - the provided variable, as a dictionary\. This will include content\-type - and x\-amz\-meta\-\* headers, as well as the usual HTTP headers, the - x\-amz\-id debugging headers, and so on\. If no file is fetched \(due to - __\-compare__ or other errors\), no assignment to this variable is - performed\. - - - __S3::Head__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-dict__ *dictvarname*? ?__\-headers__ *headersvarname*? ?__\-status__ *statusvarname*? - - This command requests HEAD from the resource\. It returns whether a 2XX code - was returned as a result of the request, never throwing an S3 remote error\. - That is, if this returns 1, the resource exists and is accessible\. If this - returns 0, something went wrong, and the __\-status__ result can be - consulted for details\. - - * __\-bucket__ - - This specifies the bucket from which the resource will be read\. Leading - and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-blocking__ - - The standard blocking flag\. - - * __\-dict__ - - If specified, the resulting dictionary from the __S3::REST__ call is - assigned to the indicated \(not necessarily global\) variable in the - caller's scope\. - - * __\-headers__ - - If specified, the dictionary of headers from the result are assigned to - the indicated \(not necessarily global\) variable in the caller's scope\. - - * __\-status__ - - If specified, the indicated \(not necessarily global\) variable in the - caller's scope is assigned a 2\-element list\. The first element is the - 3\-digit HTTP status code, while the second element is the HTTP message - \(such as "OK" or "Forbidden"\)\. - - - __S3::GetAcl__ ?__\-blocking__ *boolean*? ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-result\-type__ *REST|xml|pxml*? - - This command gets the ACL of the indicated resource or throws an error if it - is unavailable\. - - * __\-blocking__ *boolean* - - See above for standard definition\. - - * __\-bucket__ - - This specifies the bucket from which the resource will be read\. Leading - and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-parse\-xml__ *xml* - - The XML from a previous GetACL can be passed in to be parsed into - dictionary form\. In this case, \-result\-type must be pxml or dict\. - - * __\-result\-type__ *REST* - - The dictionary returned by __S3::REST__ is the return value of - __S3::GetAcl__\. In this case, a non\-2XX httpstatus will not throw an - error\. - - * __\-result\-type__ *xml* - - The raw XML of the body is returned as the result \(with no encoding - applied\)\. - - * __\-result\-type__ *pxml* - - The XML of the body as parsed by __xsxp::parse__ is returned\. - - * __\-result\-type__ *dict* - - This fetches the ACL, parses it, and returns a dictionary of two - elements\. - - The first element has the key "owner" whose value is the canonical ID of - the owner of the resource\. - - The second element has the key "acl" whose value is a dictionary\. Each - key in the dictionary is one of Amazon's permissions, namely "READ", - "WRITE", "READ\_ACP", "WRITE\_ACP", or "FULL\_CONTROL"\. Each value of each - key is a list of canonical IDs or group URLs that have that permission\. - Elements are not in the list in any particular order, and not all keys - are necessarily present\. Display names are not returned, as they are not - especially useful; use pxml to obtain them if necessary\. - - - __S3::PutAcl__ ?__\-blocking__ *boolean*? ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-acl__ *new\-acl*? - - This sets the ACL on the indicated resource\. It returns the XML written to - the ACL, or throws an error if anything went wrong\. - - * __\-blocking__ *boolean* - - See above for standard definition\. - - * __\-bucket__ - - This specifies the bucket from which the resource will be read\. Leading - and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-owner__ - - If this is provided, it is assumed to match the owner of the resource\. - Otherwise, a GET may need to be issued against the resource to find the - owner\. If you already have the owner \(such as from a call to - __S3::GetAcl__, you can pass the value of the "owner" key as the - value of this option, and it will be used in the construction of the - XML\. - - * __\-acl__ - - If this option is specified, it provides the ACL the caller wishes to - write to the resource\. If this is not supplied or is empty, the value is - taken from __S3::Configure \-default\-acl__\. The ACL is written with a - PUT to the ?acl resource\. - - If the value passed to this option starts with "<", it is taken to be a - body to be PUT to the ACL resource\. - - If the value matches one of the standard Amazon x\-amz\-acl headers \(i\.e\., - a canned access policy\), that header is translated to XML and then - applied\. The canned access policies are private, public\-read, - public\-read\-write, and authenticated\-read \(in lower case\)\. - - Otherwise, the value is assumed to be a dictionary formatted as the - "acl" sub\-entry within the dict returns by __S3::GetAcl \-result\-type - dict__\. The proper XML is generated and applied to the resource\. Note - that a value containing "//" is assumed to be a group, a value - containing "@" is assumed to be an AmazonCustomerByEmail, and otherwise - the value is assumed to be a canonical Amazon ID\. - - Note that you cannot change the owner, so calling GetAcl on a resource - owned by one user and applying it via PutAcl on a resource owned by - another user may not do exactly what you expect\. - - - __S3::Delete__ ?__\-bucket__ *bucketname*? __\-resource__ *resourcename* ?__\-blocking__ *boolean*? ?__\-status__ *statusvar*? - - This command deletes the specified resource from the specified bucket\. It - returns 1 if the resource was deleted successfully, 0 otherwise\. It returns - 0 rather than throwing an S3 remote error\. - - * __\-bucket__ - - This specifies the bucket from which the resource will be deleted\. - Leading and/or trailing slashes are removed for you, as are spaces\. - - * __\-resource__ - - This is the full name of the resource within the bucket\. A single - leading slash is removed, but not a trailing slash\. Spaces are not - trimmed\. - - * __\-blocking__ - - The standard blocking flag\. - - * __\-status__ - - If specified, the indicated \(not necessarily global\) variable in the - caller's scope is set to a two\-element list\. The first element is the - 3\-digit HTTP status code\. The second element is the HTTP message \(such - as "OK" or "Forbidden"\)\. Note that Amazon's DELETE result is 204 on - success, that being the code indicating no content in the returned body\. - - - __S3::Push__ ?__\-bucket__ *bucketname*? __\-directory__ *directoryname* ?__\-prefix__ *prefixstring*? ?__\-compare__ *comparemode*? ?__\-x\-amz\-meta\-\*__ *metastring*? ?__\-acl__ *aclcode*? ?__\-delete__ *boolean*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*? - - This synchronises a local directory with a remote bucket by pushing the - differences using __S3::Put__\. Note that if something has changed in the - bucket but not locally, those changes could be lost\. Thus, this is not a - general two\-way synchronization primitive\. \(See __S3::Sync__ for that\.\) - Note too that resource names are case sensitive, so changing the case of a - file on a Windows machine may lead to otherwise\-unnecessary transfers\. Note - that only regular files are considered, so devices, pipes, symlinks, and - directories are not copied\. - - * __\-bucket__ - - This names the bucket into which data will be pushed\. - - * __\-directory__ - - This names the local directory from which files will be taken\. It must - exist, be readable via \[glob\] and so on\. If only some of the files - therein are readable, __S3::Push__ will PUT those files that are - readable and return in its results the list of files that could not be - opened\. - - * __\-prefix__ - - This names the prefix that will be added to all resources\. That is, it - is the remote equivalent of __\-directory__\. If it is not specified, - the root of the bucket will be treated as the remote directory\. An - example may clarify\. - - S3::Push -bucket test -directory /tmp/xyz -prefix hello/world - - In this example, /tmp/xyz/pdq\.html will be stored as - http://s3\.amazonaws\.com/test/hello/world/pdq\.html in Amazon's servers\. - Also, /tmp/xyz/abc/def/Hello will be stored as - http://s3\.amazonaws\.com/test/hello/world/abc/def/Hello in Amazon's - servers\. Without the __\-prefix__ option, /tmp/xyz/pdq\.html would be - stored as http://s3\.amazonaws\.com/test/pdq\.html\. - - * __\-blocking__ - - This is the standard blocking option\. - - * __\-compare__ - - If present, this is passed to each invocation of __S3::Put__\. - Naturally, __S3::Configure \-default\-compare__ is used if this is not - specified\. - - * __\-x\-amz\-meta\-\*__ - - If present, this is passed to each invocation of __S3::Put__\. All - copied files will have the same metadata\. - - * __\-acl__ - - If present, this is passed to each invocation of __S3::Put__\. - - * __\-delete__ - - This defaults to false\. If true, resources in the destination that are - not in the source directory are deleted with __S3::Delete__\. Since - only regular files are considered, the existance of a symlink, pipe, - device, or directory in the local source will *not* prevent the - deletion of a remote resource with a corresponding name\. - - * __\-error__ - - This controls the behavior of __S3::Push__ in the event that - __S3::Put__ throws an error\. Note that errors encountered on the - local file system or in reading the list of resources in the remote - bucket always throw errors\. This option allows control over "partial" - errors, when some files were copied and some were not\. - __S3::Delete__ is always finished up, with errors simply recorded in - the return result\. - - + throw - - The error is rethrown with the same errorCode\. - - + break - - Processing stops without throwing an error, the error is recorded in - the return value, and the command returns with a normal return\. The - calls to __S3::Delete__ are not started\. - - + continue - - This is the default\. Processing continues without throwing, - recording the error in the return result, and resuming with the next - file in the local directory to be copied\. - - * __\-progress__ - - If this is specified and the indicated script prefix is not empty, the - indicated script prefix will be invoked several times in the caller's - context with additional arguments at various points in the processing\. - This allows progress reporting without backgrounding\. The provided - prefix will be invoked with additional arguments, with the first - additional argument indicating what part of the process is being - reported on\. The prefix is initially invoked with *args* as the first - additional argument and a dictionary representing the normalized - arguments to the __S3::Push__ call as the second additional - argument\. Then the prefix is invoked with *local* as the first - additional argument and a list of suffixes of the files to be considered - as the second argument\. Then the prefix is invoked with *remote* as - the first additional argument and a list of suffixes existing in the - remote bucket as the second additional argument\. Then, for each file in - the local list, the prefix will be invoked with *start* as the first - additional argument and the common suffix as the second additional - argument\. When __S3::Put__ returns for that file, the prefix will be - invoked with *copy* as the first additional argument, the common - suffix as the second additional argument, and a third argument that will - be "copied" \(if __S3::Put__ sent the resource\), "skipped" \(if - __S3::Put__ decided not to based on __\-compare__\), or the - errorCode that __S3::Put__ threw due to unexpected errors \(in which - case the third argument is a list that starts with "S3"\)\. When all files - have been transfered, the prefix may be invoked zero or more times with - *delete* as the first additional argument and the suffix of the - resource being deleted as the second additional argument, with a third - argument being either an empty string \(if the delete worked\) or the - errorCode from __S3::Delete__ if it failed\. Finally, the prefix will - be invoked with *finished* as the first additional argument and the - return value as the second additional argument\. - - The return result from this command is a dictionary\. They keys are the - suffixes \(i\.e\., the common portion of the path after the __\-directory__ - and __\-prefix__\), while the values are either "copied", "skipped" \(if - __\-compare__ indicated not to copy the file\), or the errorCode thrown by - __S3::Put__, as appropriate\. If __\-delete__ was true, there may also - be entries for suffixes with the value "deleted" or "notdeleted", indicating - whether the attempted __S3::Delete__ worked or not, respectively\. There - is one additional pair in the return result, whose key is the empty string - and whose value is a nested dictionary\. The keys of this nested dictionary - include "filescopied" \(the number of files successfully copied\), - "bytescopied" \(the number of data bytes in the files copied, excluding - headers, metadata, etc\), "compareskipped" \(the number of files not copied - due to __\-compare__ mode\), "errorskipped" \(the number of files not - copied due to thrown errors\), "filesdeleted" \(the number of resources - deleted due to not having corresponding files locally, or 0 if - __\-delete__ is false\), and "filesnotdeleted" \(the number of resources - whose deletion was attempted but failed\)\. - - Note that this is currently implemented somewhat inefficiently\. It fetches - the bucket listing \(including timestamps and eTags\), then calls - __S3::Put__, which uses HEAD to find the timestamps and eTags again\. - Correcting this with no API change is planned for a future upgrade\. - - - __S3::Pull__ ?__\-bucket__ *bucketname*? __\-directory__ *directoryname* ?__\-prefix__ *prefixstring*? ?__\-blocking__ *boolean*? ?__\-compare__ *comparemode*? ?__\-delete__ *boolean*? ?__\-timestamp__ *aws|now*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*? - - This synchronises a remote bucket with a local directory by pulling the - differences using __S3::Get__ If something has been changed locally but - not in the bucket, those difference may be lost\. This is not a general - two\-way synchronization mechanism\. \(See __S3::Sync__ for that\.\) This - creates directories if needed; new directories are created with default - permissions\. Note that resource names are case sensitive, so changing the - case of a file on a Windows machine may lead to otherwise\-unnecessary - transfers\. Also, try not to store data in resources that end with a slash, - or which are prefixes of resources that otherwise would start with a slash; - i\.e\., don't use this if you store data in resources whose names have to be - directories locally\. - - Note that this is currently implemented somewhat inefficiently\. It fetches - the bucket listing \(including timestamps and eTags\), then calls - __S3::Get__, which uses HEAD to find the timestamps and eTags again\. - Correcting this with no API change is planned for a future upgrade\. - - * __\-bucket__ - - This names the bucket from which data will be pulled\. - - * __\-directory__ - - This names the local directory into which files will be written It must - exist, be readable via \[glob\], writable for file creation, and so on\. If - only some of the files therein are writable, __S3::Pull__ will GET - those files that are writable and return in its results the list of - files that could not be opened\. - - * __\-prefix__ - - The prefix of resources that will be considered for retrieval\. See - __S3::Push__ for more details, examples, etc\. \(Of course, - __S3::Pull__ reads rather than writes, but the prefix is treated - similarly\.\) - - * __\-blocking__ - - This is the standard blocking option\. - - * __\-compare__ - - This is passed to each invocation of __S3::Get__ if provided\. - Naturally, __S3::Configure \-default\-compare__ is used if this is not - provided\. - - * __\-timestamp__ - - This is passed to each invocation of __S3::Get__ if provided\. - - * __\-delete__ - - If this is specified and true, files that exist in the - __\-directory__ that are not in the __\-prefix__ will be deleted - after all resources have been copied\. In addition, empty directories - \(other than the top\-level __\-directory__\) will be deleted, as Amazon - S3 has no concept of an empty directory\. - - * __\-error__ - - See __S3::Push__ for a description of this option\. - - * __\-progress__ - - See __S3::Push__ for a description of this option\. It differs - slightly in that local directories may be included with a trailing slash - to indicate they are directories\. - - The return value from this command is a dictionary\. It is identical in form - and meaning to the description of the return result of __S3::Push__\. It - differs only in that directories may be included, with a trailing slash in - their name, if they are empty and get deleted\. - - - __S3::Toss__ ?__\-bucket__ *bucketname*? __\-prefix__ *prefixstring* ?__\-blocking__ *boolean*? ?__\-error__ *throw|break|continue*? ?__\-progress__ *scriptprefix*? - - This deletes some or all resources within a bucket\. It would be considered a - "recursive delete" had Amazon implemented actual directories\. - - * __\-bucket__ - - The bucket from which resources will be deleted\. - - * ____\-blocking____ - - The standard blocking option\. - - * ____\-prefix____ - - The prefix for resources to be deleted\. Any resource that starts with - this string will be deleted\. This is required\. To delete everything in - the bucket, pass an empty string for the prefix\. - - * ____\-error____ - - If this is "throw", __S3::Toss__ rethrows any errors it encounters\. - If this is "break", __S3::Toss__ returns with a normal return after - the first error, recording that error in the return result\. If this is - "continue", which is the default, __S3::Toss__ continues on and - lists all errors in the return result\. - - * ____\-progress____ - - If this is specified and not an empty string, the script prefix will be - invoked several times in the context of the caller with additional - arguments appended\. Initially, it will be invoked with the first - additional argument being *args* and the second being the processed - list of arguments to __S3::Toss__\. Then it is invoked with - *remote* as the first additional argument and the list of suffixes in - the bucket to be deleted as the second additional argument\. Then it is - invoked with the first additional argument being *delete* and the - second additional argument being the suffix deleted and the third - additional argument being "deleted" or "notdeleted" depending on whether - __S3::Delete__ threw an error\. Finally, the script prefix is invoked - with a first additional argument of "finished" and a second additional - argument of the return value\. - - The return value is a dictionary\. The keys are the suffixes of files that - __S3::Toss__ attempted to delete, and whose values are either the string - "deleted" or "notdeleted"\. There is also one additional pair, whose key is - the empty string and whose value is an embedded dictionary\. The keys of this - embedded dictionary include "filesdeleted" and "filesnotdeleted", each of - which has integer values\. - -# LIMITATIONS - - - The pure\-Tcl MD5 checking is slow\. If you are processing files in the - megabyte range, consider ensuring binary support is available\. - - - The commands __S3::Pull__ and __S3::Push__ fetch a directory listing - which includes timestamps and MD5 hashes, then invoke __S3::Get__ and - __S3::Put__\. If a complex __\-compare__ mode is specified, - __S3::Get__ and __S3::Put__ will invoke a HEAD operation for each - file to fetch timestamps and MD5 hashes of each resource again\. It is - expected that a future release of this package will solve this without any - API changes\. - - - The commands __S3::Pull__ and __S3::Push__ fetch a directory listing - without using __\-max\-count__\. The entire directory is pulled into memory - at once\. For very large buckets, this could be a performance problem\. The - author, at this time, does not plan to change this behavior\. Welcome to Open - Source\. - - - __S3::Sync__ is neither designed nor implemented yet\. The intention - would be to keep changes synchronised, so changes could be made to both the - bucket and the local directory and be merged by __S3::Sync__\. - - - Nor is __\-compare__ *calc* fully implemented\. This is primarily due to - Windows not providing a convenient method for distinguishing between local - files that are "public\-read" or "public\-read\-write"\. Assistance figuring out - TWAPI for this would be appreciated\. The U\*\*X semantics are difficult to map - directly as well\. See the source for details\. Note that there are not tests - for calc, since it isn't done yet\. - - - The HTTP processing is implemented within the library, rather than using a - "real" HTTP package\. Hence, multi\-line headers are not \(yet\) handled - correctly\. Do not include carriage returns or linefeeds in x\-amz\-meta\-\* - headers, content\-type values, and so on\. The author does not at this time - expect to improve this\. - - - Internally, __S3::Push__ and __S3::Pull__ and __S3::Toss__ are - all very similar and should be refactored\. - - - The idea of using __\-compare__ *never* __\-delete__ *true* to - delete files that have been deleted from one place but not the other yet not - copying changed files is untested\. - -# USAGE SUGGESTIONS - -To fetch a "directory" out of a bucket, make changes, and store it back: - - file mkdir ./tempfiles - S3::Pull -bucket sample -prefix of/interest -directory ./tempfiles \ - -timestamp aws - do_my_process ./tempfiles other arguments - S3::Push -bucket sample -prefix of/interest -directory ./tempfiles \ - -compare newer -delete true - -To delete files locally that were deleted off of S3 but not otherwise update -files: - - S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \ - -compare never -delete true - -# FUTURE DEVELOPMENTS - -The author intends to work on several additional projects related to this -package, in addition to finishing the unfinished features\. - -First, a command\-line program allowing browsing of buckets and transfer of files -from shell scripts and command prompts is useful\. - -Second, a GUI\-based program allowing visual manipulation of bucket and resource -trees not unlike Windows Explorer would be useful\. - -Third, a command\-line \(and perhaps a GUI\-based\) program called "OddJob" that -will use S3 to synchronize computation amongst multiple servers running OddJob\. -An S3 bucket will be set up with a number of scripts to run, and the OddJob -program can be invoked on multiple machines to run scripts on all the machines, -each moving on to the next unstarted task as it finishes each\. This is still -being designed, and it is intended primarily to be run on Amazon's Elastic -Compute Cloud\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *amazon\-s3* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[amazon](\.\./\.\./\.\./\.\./index\.md\#amazon), -[cloud](\.\./\.\./\.\./\.\./index\.md\#cloud), [s3](\.\./\.\./\.\./\.\./index\.md\#s3) - -# CATEGORY - -Networking - -# COPYRIGHT - -2006,2008 Darren New\. All Rights Reserved\. See LICENSE\.TXT for terms\. DELETED embedded/md/tcllib/files/modules/amazon-s3/xsxp.md Index: embedded/md/tcllib/files/modules/amazon-s3/xsxp.md ================================================================== --- embedded/md/tcllib/files/modules/amazon-s3/xsxp.md +++ embedded/md/tcllib/files/modules/amazon-s3/xsxp.md @@ -1,194 +0,0 @@ - -[//000000001]: # (xsxp \- Amazon S3 Web Service Utilities) -[//000000002]: # (Generated from file 'xsxp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (2006 Darren New\. All Rights Reserved\.) -[//000000004]: # (xsxp\(n\) 1\.0 tcllib "Amazon S3 Web Service Utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -xsxp \- eXtremely Simple Xml Parser - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require xsxp 1 -package require xml - -[__xsxp::parse__ *xml*](#1) -[__xsxp::fetch__ *pxml* *path* ?*part*?](#2) -[__xsxp::fetchall__ *pxml\_list* *path* ?*part*?](#3) -[__xsxp::only__ *pxml* *tagname*](#4) -[__xsxp::prettyprint__ *pxml* ?*chan*?](#5) - -# DESCRIPTION - -This package provides a simple interface to parse XML into a pure\-value list\. It -also provides accessor routines to pull out specific subtags, not unlike DOM -access\. This package was written for and is used by Darren New's Amazon S3 -access package\. - -This is pretty lame, but I needed something like this for S3, and at the time, -TclDOM would not work with the new 8\.5 Tcl due to version number problems\. - -In addition, this is a pure\-value implementation\. There is no garbage to clean -up in the event of a thrown error, for example\. This simplifies the code for -sufficiently small XML documents, which is what Amazon's S3 guarantees\. - -Copyright 2006 Darren New\. All Rights Reserved\. NO WARRANTIES OF ANY TYPE ARE -PROVIDED\. COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS\. This software is -licensed under essentially the same terms as Tcl\. See LICENSE\.txt for the terms\. - -# COMMANDS - -The package implements five rather simple procedures\. One parses, one is for -debugging, and the rest pull various parts of the parsed document out for -processing\. - - - __xsxp::parse__ *xml* - - This parses an XML document \(using the standard xml tcllib module in a SAX - sort of way\) and builds a data structure which it returns if the parsing - succeeded\. The return value is referred to herein as a "pxml", or "parsed - xml"\. The list consists of two or more elements: - - * The first element is the name of the tag\. - - * The second element is an array\-get formatted list of key/value pairs\. - The keys are attribute names and the values are attribute values\. This - is an empty list if there are no attributes on the tag\. - - * The third through end elements are the children of the node, if any\. - Each child is, recursively, a pxml\. - - * Note that if the zero'th element, i\.e\. the tag name, is "%PCDATA", then - the attributes will be empty and the third element will be the text of - the element\. In addition, if an element's contents consists only of - PCDATA, it will have only one child, and all the PCDATA will be - concatenated\. In other words, this parser works poorly for XML with - elements that contain both child tags and PCDATA\. Since Amazon S3 does - not do this \(and for that matter most uses of XML where XML is a poor - choice don't do this\), this is probably not a serious limitation\. - - - __xsxp::fetch__ *pxml* *path* ?*part*? - - *pxml* is a parsed XML, as returned from xsxp::parse\. *path* is a list - of element tag names\. Each element is the name of a child to look up, - optionally followed by a hash \("\#"\) and a string of digits\. An empty list or - an initial empty element selects *pxml*\. If no hash sign is present, the - behavior is as if "\#0" had been appended to that element\. \(In addition to a - list, slashes can separate subparts where convenient\.\) - - An element of *path* scans the children at the indicated level for the - n'th instance of a child whose tag matches the part of the element before - the hash sign\. If an element is simply "\#" followed by digits, that indexed - child is selected, regardless of the tags in the children\. Hence, an element - of "\#3" will always select the fourth child of the node under consideration\. - - *part* defaults to "%ALL"\. It can be one of the following case\-sensitive - terms: - - * %ALL - - returns the entire selected element\. - - * %TAGNAME - - returns lindex 0 of the selected element\. - - * %ATTRIBUTES - - returns index 1 of the selected element\. - - * %CHILDREN - - returns lrange 2 through end of the selected element, resulting in a - list of elements being returned\. - - * %PCDATA - - returns a concatenation of all the bodies of direct children of this - node whose tag is %PCDATA\. It throws an error if no such children are - found\. That is, part=%PCDATA means return the textual content found in - that node but not its children nodes\. - - * %PCDATA? - - is like %PCDATA, but returns an empty string if no PCDATA is found\. - - For example, to fetch the first bold text from the fifth paragraph of the - body of your HTML file, - - xsxp::fetch $pxml {body p#4 b} %PCDATA - - - __xsxp::fetchall__ *pxml\_list* *path* ?*part*? - - This iterates over each PXML in *pxml\_list* \(which must be a list of - pxmls\) selecting the indicated path from it, building a new list with the - selected data, and returning that new list\. - - For example, *pxml\_list* might be the %CHILDREN of a particular element, - and the *path* and *part* might select from each child a sub\-element in - which we're interested\. - - - __xsxp::only__ *pxml* *tagname* - - This iterates over the direct children of *pxml* and selects only those - with *tagname* as their tag\. Returns a list of matching elements\. - - - __xsxp::prettyprint__ *pxml* ?*chan*? - - This outputs to *chan* \(default stdout\) a pretty\-printed version of - *pxml*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *amazon\-s3* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[dom](\.\./\.\./\.\./\.\./index\.md\#dom), [parser](\.\./\.\./\.\./\.\./index\.md\#parser), -[xml](\.\./\.\./\.\./\.\./index\.md\#xml) - -# CATEGORY - -Text processing - -# COPYRIGHT - -2006 Darren New\. All Rights Reserved\. DELETED embedded/md/tcllib/files/modules/asn/asn.md Index: embedded/md/tcllib/files/modules/asn/asn.md ================================================================== --- embedded/md/tcllib/files/modules/asn/asn.md +++ embedded/md/tcllib/files/modules/asn/asn.md @@ -1,517 +0,0 @@ - -[//000000001]: # (asn \- ASN\.1 processing) -[//000000002]: # (Generated from file 'asn\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries ) -[//000000004]: # (Copyright © 2004 Jochen Loewer ) -[//000000005]: # (Copyright © 2004\-2011 Michael Schlenker ) -[//000000006]: # (asn\(n\) 0\.8 tcllib "ASN\.1 processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -asn \- ASN\.1 BER encoder/decoder - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [ENCODER](#subsection1) - - - [DECODER](#subsection2) - - - [HANDLING TAGS](#subsection3) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require asn ?0\.8\.4? - -[__::asn::asnSequence__ *evalue*\.\.\.](#1) -[__::asn::asnSequenceFromList__ *elist*](#2) -[__::asn::asnSet__ *evalue*\.\.\.](#3) -[__::asn::asnSetFromList__ *elist*](#4) -[__::asn::asnApplicationConstr__ *appNumber* *evalue*\.\.\.](#5) -[__::asn::asnApplication__ *appNumber* *data*](#6) -[__::asn::asnChoice__ *appNumber* *evalue*\.\.\.](#7) -[__::asn::asnChoiceConstr__ *appNumber* *evalue*\.\.\.](#8) -[__::asn::asnInteger__ *number*](#9) -[__::asn::asnEnumeration__ *number*](#10) -[__::asn::asnBoolean__ *bool*](#11) -[__::asn::asnContext__ *context* *data*](#12) -[__::asn::asnContextConstr__ *context* *evalue*\.\.\.](#13) -[__::asn::asnObjectIdentifier__ *idlist*](#14) -[__::asn::asnUTCTime__ *utcstring*](#15) -[__::asn::asnNull__](#16) -[__::asn::asnBitString__ *string*](#17) -[__::asn::asnOctetString__ *string*](#18) -[__::asn::asnNumericString__ *string*](#19) -[__::asn::asnPrintableString__ *string*](#20) -[__::asn::asnIA5String__ *string*](#21) -[__::asn::asnBMPString__ *string*](#22) -[__::asn::asnUTF8String__ *string*](#23) -[__::asn::asnString__ *string*](#24) -[__::asn::defaultStringType__ ?*type*?](#25) -[__::asn::asnPeekByte__ *data\_var* *byte\_var*](#26) -[__::asn::asnGetLength__ *data\_var* *length\_var*](#27) -[__::asn::asnGetResponse__ *chan* *data\_var*](#28) -[__::asn::asnGetInteger__ *data\_var* *int\_var*](#29) -[__::asn::asnGetEnumeration__ *data\_var* *enum\_var*](#30) -[__::asn::asnGetOctetString__ *data\_var* *string\_var*](#31) -[__::asn::asnGetString__ *data\_var* *string\_var* ?*type\_var*?](#32) -[__::asn::asnGetNumericString__ *data\_var* *string\_var*](#33) -[__::asn::asnGetPrintableString__ *data\_var* *string\_var*](#34) -[__::asn::asnGetIA5String__ *data\_var* *string\_var*](#35) -[__::asn::asnGetBMPString__ *data\_var* *string\_var*](#36) -[__::asn::asnGetUTF8String__ *data\_var* *string\_var*](#37) -[__::asn::asnGetUTCTime__ *data\_var* *utc\_var*](#38) -[__::asn::asnGetBitString__ *data\_var* *bits\_var*](#39) -[__::asn::asnGetObjectIdentifier__ *data\_var* *oid\_var*](#40) -[__::asn::asnGetBoolean__ *data\_var* *bool\_var*](#41) -[__::asn::asnGetNull__ *data\_var*](#42) -[__::asn::asnGetSequence__ *data\_var* *sequence\_var*](#43) -[__::asn::asnGetSet__ *data\_var* *set\_var*](#44) -[__::asn::asnGetApplication__ *data\_var* *appNumber\_var* ?*content\_var*? ?*encodingType\_var*?](#45) -[__::asn::asnGetContext__ *data\_var* *contextNumber\_var* ?*content\_var*? ?*encodingType\_var*?](#46) -[__::asn::asnPeekTag__ *data\_var* *tag\_var* *tagtype\_var* *constr\_var*](#47) -[__::asn::asnTag__ *tagnumber* ?*class*? ?*tagstyle*?](#48) -[__::asn::asnRetag__ *data\_var* *newTag*](#49) - -# DESCRIPTION - -The __asn__ package provides *partial* de\- and encoder commands for BER -encoded ASN\.1 data\. It can also be used for decoding DER, which is a restricted -subset of BER\. - -ASN\.1 is a standard *Abstract Syntax Notation*, and BER are its *Basic -Encoding Rules*\. - -See -[http://asn1\.elibel\.tm\.fr/en/standards/index\.htm](http://asn1\.elibel\.tm\.fr/en/standards/index\.htm) -for more information about the standard\. - -Also see -[http://luca\.ntop\.org/Teaching/Appunti/asn1\.html](http://luca\.ntop\.org/Teaching/Appunti/asn1\.html) -for *A Layman's Guide to a Subset of ASN\.1, BER, and DER*, an RSA Laboratories -Technical Note by Burton S\. Kaliski Jr\. \(Revised November 1, 1993\)\. A text -version of this note is part of the module sources and should be read by any -implementor\. - -# PUBLIC API - -## ENCODER - - - __::asn::asnSequence__ *evalue*\.\.\. - - Takes zero or more encoded values, packs them into an ASN sequence and - returns its encoded binary form\. - - - __::asn::asnSequenceFromList__ *elist* - - Takes a list of encoded values, packs them into an ASN sequence and returns - its encoded binary form\. - - - __::asn::asnSet__ *evalue*\.\.\. - - Takes zero or more encoded values, packs them into an ASN set and returns - its encoded binary form\. - - - __::asn::asnSetFromList__ *elist* - - Takes a list of encoded values, packs them into an ASN set and returns its - encoded binary form\. - - - __::asn::asnApplicationConstr__ *appNumber* *evalue*\.\.\. - - Takes zero or more encoded values, packs them into an ASN application - construct and returns its encoded binary form\. - - - __::asn::asnApplication__ *appNumber* *data* - - Takes a single encoded value *data*, packs it into an ASN application - construct and returns its encoded binary form\. - - - __::asn::asnChoice__ *appNumber* *evalue*\.\.\. - - Takes zero or more encoded values, packs them into an ASN choice construct - and returns its encoded binary form\. - - - __::asn::asnChoiceConstr__ *appNumber* *evalue*\.\.\. - - Takes zero or more encoded values, packs them into an ASN choice construct - and returns its encoded binary form\. - - - __::asn::asnInteger__ *number* - - Returns the encoded form of the specified integer *number*\. - - - __::asn::asnEnumeration__ *number* - - Returns the encoded form of the specified enumeration id *number*\. - - - __::asn::asnBoolean__ *bool* - - Returns the encoded form of the specified boolean value *bool*\. - - - __::asn::asnContext__ *context* *data* - - Takes an encoded value and packs it into a constructed value with - application tag, the *context* number\. - - - __::asn::asnContextConstr__ *context* *evalue*\.\.\. - - Takes zero or more encoded values and packs them into a constructed value - with application tag, the *context* number\. - - - __::asn::asnObjectIdentifier__ *idlist* - - Takes a list of at least 2 integers describing an object identifier \(OID\) - value, and returns the encoded value\. - - - __::asn::asnUTCTime__ *utcstring* - - Returns the encoded form of the specified UTC time string\. - - - __::asn::asnNull__ - - Returns the NULL encoding\. - - - __::asn::asnBitString__ *string* - - Returns the encoded form of the specified *string*\. - - - __::asn::asnOctetString__ *string* - - Returns the encoded form of the specified *string*\. - - - __::asn::asnNumericString__ *string* - - Returns the *string* encoded as ASN\.1 NumericString\. Raises an error if - the *string* contains characters other than decimal numbers and space\. - - - __::asn::asnPrintableString__ *string* - - Returns the *string* encoding as ASN\.1 PrintableString\. Raises an error if - the *string* contains characters which are not allowed by the Printable - String datatype\. The allowed characters are A\-Z, a\-z, 0\-9, space, - apostrophe, colon, parentheses, plus, minus, comma, period, forward slash, - question mark, and the equals sign\. - - - __::asn::asnIA5String__ *string* - - Returns the *string* encoded as ASN\.1 IA5String\. Raises an error if the - *string* contains any characters outside of the US\-ASCII range\. - - - __::asn::asnBMPString__ *string* - - Returns the *string* encoded as ASN\.1 Basic Multilingual Plane string - \(Which is essentialy big\-endian UCS2\)\. - - - __::asn::asnUTF8String__ *string* - - Returns the *string* encoded as UTF8 String\. Note that some legacy - applications such as Windows CryptoAPI do not like UTF8 strings\. Use - BMPStrings if you are not sure\. - - - __::asn::asnString__ *string* - - Returns an encoded form of *string*, choosing the most restricted ASN\.1 - string type possible\. If the string contains non\-ASCII characters, then - there is more than one string type which can be used\. See - __::asn::defaultStringType__\. - - - __::asn::defaultStringType__ ?*type*? - - Selects the string type to use for the encoding of non\-ASCII strings\. - Returns current default when called without argument\. If the argument - *type* is supplied, it should be either __UTF8__ or __BMP__ to - choose UTF8String or BMPString respectively\. - -## DECODER - -General notes: - - 1. Nearly all decoder commands take two arguments\. These arguments are - variable names, except for __::asn::asnGetResponse__\. The first - variable contains the encoded ASN value to decode at the beginning, and - more, and the second variable is where the value is stored to\. The - remainder of the input after the decoded value is stored back into the - datavariable\. - - 1. After extraction the data variable is always modified first, before by - writing the extracted value to its variable\. This means that if both - arguments refer to the same variable, it will always contain the extracted - value after the call, and not the remainder of the input\. - - - __::asn::asnPeekByte__ *data\_var* *byte\_var* - - Retrieve the first byte of the data, without modifing *data\_var*\. This can - be used to check for implicit tags\. - - - __::asn::asnGetLength__ *data\_var* *length\_var* - - Decode the length information for a block of BER data\. The tag has already - to be removed from the data\. - - - __::asn::asnGetResponse__ *chan* *data\_var* - - Reads an encoded ASN *sequence* from the channel *chan* and stores it - into the variable named by *data\_var*\. - - - __::asn::asnGetInteger__ *data\_var* *int\_var* - - Assumes that an encoded integer value is at the front of the data stored in - the variable named *data\_var*, extracts and stores it into the variable - named by *int\_var*\. Additionally removes all bytes associated with the - value from the data for further processing by the following decoder - commands\. - - - __::asn::asnGetEnumeration__ *data\_var* *enum\_var* - - Assumes that an enumeration id is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *enum\_var*\. Additionally removes all bytes associated with the value from - the data for further processing by the following decoder commands\. - - - __::asn::asnGetOctetString__ *data\_var* *string\_var* - - Assumes that a string is at the front of the data stored in the variable - named *data\_var*, and stores it into the variable named by *string\_var*\. - Additionally removes all bytes associated with the value from the data for - further processing by the following decoder commands\. - - - __::asn::asnGetString__ *data\_var* *string\_var* ?*type\_var*? - - Decodes a user\-readable string\. This is a convenience function which is able - to automatically distinguish all supported ASN\.1 string types and convert - the input value appropriately\. See __::asn::asnGetPrintableString__, - __::asnGetIA5String__, etc\. below for the type\-specific conversion - commands\. - - If the optional third argument *type\_var* is supplied, then the type of - the incoming string is stored in the variable named by it\. - - The function throws the error "Invalid command name - asnGetSome__UnsupportedString__" if the unsupported string type - __Unsupported__ is encountered\. You can create the appropriate function - "asn::asnGetSome__UnsupportedString__" in your application if - neccessary\. - - - __::asn::asnGetNumericString__ *data\_var* *string\_var* - - Assumes that a numeric string value is at the front of the data stored in - the variable named *data\_var*, and stores it into the variable named by - *string\_var*\. Additionally removes all bytes associated with the value - from the data for further processing by the following decoder commands\. - - - __::asn::asnGetPrintableString__ *data\_var* *string\_var* - - Assumes that a printable string value is at the front of the data stored in - the variable named *data\_var*, and stores it into the variable named by - *string\_var*\. Additionally removes all bytes associated with the value - from the data for further processing by the following decoder commands\. - - - __::asn::asnGetIA5String__ *data\_var* *string\_var* - - Assumes that a IA5 \(ASCII\) string value is at the front of the data stored - in the variable named *data\_var*, and stores it into the variable named by - *string\_var*\. Additionally removes all bytes associated with the value - from the data for further processing by the following decoder commands\. - - - __::asn::asnGetBMPString__ *data\_var* *string\_var* - - Assumes that a BMP \(two\-byte unicode\) string value is at the front of the - data stored in the variable named *data\_var*, and stores it into the - variable named by *string\_var*, converting it into a proper Tcl string\. - Additionally removes all bytes associated with the value from the data for - further processing by the following decoder commands\. - - - __::asn::asnGetUTF8String__ *data\_var* *string\_var* - - Assumes that a UTF8 string value is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *string\_var*, converting it into a proper Tcl string\. Additionally removes - all bytes associated with the value from the data for further processing by - the following decoder commands\. - - - __::asn::asnGetUTCTime__ *data\_var* *utc\_var* - - Assumes that a UTC time value is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *utc\_var*\. The UTC time value is stored as a string, which has to be - decoded with the usual clock scan commands\. Additionally removes all bytes - associated with the value from the data for further processing by the - following decoder commands\. - - - __::asn::asnGetBitString__ *data\_var* *bits\_var* - - Assumes that a bit string value is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *bits\_var* as a string containing only 0 and 1\. Additionally removes all - bytes associated with the value from the data for further processing by the - following decoder commands\. - - - __::asn::asnGetObjectIdentifier__ *data\_var* *oid\_var* - - Assumes that a object identifier \(OID\) value is at the front of the data - stored in the variable named *data\_var*, and stores it into the variable - named by *oid\_var* as a list of integers\. Additionally removes all bytes - associated with the value from the data for further processing by the - following decoder commands\. - - - __::asn::asnGetBoolean__ *data\_var* *bool\_var* - - Assumes that a boolean value is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *bool\_var*\. Additionally removes all bytes associated with the value from - the data for further processing by the following decoder commands\. - - - __::asn::asnGetNull__ *data\_var* - - Assumes that a NULL value is at the front of the data stored in the variable - named *data\_var* and removes the bytes used to encode it from the data\. - - - __::asn::asnGetSequence__ *data\_var* *sequence\_var* - - Assumes that an ASN sequence is at the front of the data stored in the - variable named *data\_var*, and stores it into the variable named by - *sequence\_var*\. Additionally removes all bytes associated with the value - from the data for further processing by the following decoder commands\. - - The data in *sequence\_var* is encoded binary and has to be further decoded - according to the definition of the sequence, using the decoder commands - here\. - - - __::asn::asnGetSet__ *data\_var* *set\_var* - - Assumes that an ASN set is at the front of the data stored in the variable - named *data\_var*, and stores it into the variable named by *set\_var*\. - Additionally removes all bytes associated with the value from the data for - further processing by the following decoder commands\. - - The data in *set\_var* is encoded binary and has to be further decoded - according to the definition of the set, using the decoder commands here\. - - - __::asn::asnGetApplication__ *data\_var* *appNumber\_var* ?*content\_var*? ?*encodingType\_var*? - - Assumes that an ASN application construct is at the front of the data stored - in the variable named *data\_var*, and stores its id into the variable - named by *appNumber\_var*\. Additionally removes all bytes associated with - the value from the data for further processing by the following decoder - commands\. If a *content\_var* is specified, then the command places all - data associated with it into the named variable, in the binary form which - can be processed using the decoder commands of this package\. If a - *encodingType\_var* is specified, then that var is set to 1 if the encoding - is constructed and 0 if it is primitive\. - - Otherwise it is the responsibility of the caller to decode the remainder of - the application construct based on the id retrieved by this command, using - the decoder commands of this package\. - - - __::asn::asnGetContext__ *data\_var* *contextNumber\_var* ?*content\_var*? ?*encodingType\_var*? - - Assumes that an ASN context tag construct is at the front of the data stored - in the variable named *data\_var*, and stores its id into the variable - named by *contextNumber\_var*\. Additionally removes all bytes associated - with the value from the data for further processing by the following decoder - commands\. If a *content\_var* is specified, then the command places all - data associated with it into the named variable, in the binary form which - can be processed using the decoder commands of this package\. If a - *encodingType\_var* is specified, then that var is set to 1 if the encoding - is constructed and 0 if it is primitive\. - - Otherwise it is the responsibility of the caller to decode the remainder of - the construct based on the id retrieved by this command, using the decoder - commands of this package\. - -## HANDLING TAGS - -Working with ASN\.1 you often need to decode tagged values, which use a tag thats -different from the universal tag for a type\. In those cases you have to replace -the tag with the universal tag used for the type, to decode the value\. To decode -a tagged value use the __::asn::asnRetag__ to change the tag to the -appropriate type to use one of the decoders for primitive values\. To help with -this the module contains three functions: - - - __::asn::asnPeekTag__ *data\_var* *tag\_var* *tagtype\_var* *constr\_var* - - The __::asn::asnPeekTag__ command can be used to take a peek at the data - and decode the tag value, without removing it from the data\. The *tag\_var* - gets set to the tag number, while the *tagtype\_var* gets set to the class - of the tag\. \(Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE\)\. The - *constr\_var* is set to 1 if the tag is for a constructed value, and to 0 - for not constructed\. It returns the length of the tag\. - - - __::asn::asnTag__ *tagnumber* ?*class*? ?*tagstyle*? - - The __::asn::asnTag__ can be used to create a tag value\. The - *tagnumber* gives the number of the tag, while the *class* gives one of - the classes \(UNIVERSAL,CONTEXT,APPLICATION or PRIVATE\)\. The class may be - abbreviated to just the first letter \(U,C,A,P\), default is UNIVERSAL\. The - *tagstyle* is either C for Constructed encoding, or P for primitve - encoding\. It defaults to P\. You can also use 1 instead of C and 0 instead of - P for direct use of the values returned by __::asn::asnPeekTag__\. - - - __::asn::asnRetag__ *data\_var* *newTag* - - Replaces the tag in front of the data in *data\_var* with *newTag*\. The - new Tag can be created using the __::asn::asnTag__ command\. - -# EXAMPLES - -Examples for the usage of this package can be found in the implementation of -package __[ldap](\.\./ldap/ldap\.md)__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *asn* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[asn](\.\./\.\./\.\./\.\./index\.md\#asn), [ber](\.\./\.\./\.\./\.\./index\.md\#ber), -[cer](\.\./\.\./\.\./\.\./index\.md\#cer), [der](\.\./\.\./\.\./\.\./index\.md\#der), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), -[x\.208](\.\./\.\./\.\./\.\./index\.md\#x\_208), [x\.209](\.\./\.\./\.\./\.\./index\.md\#x\_209) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2004 Andreas Kupries -Copyright © 2004 Jochen Loewer -Copyright © 2004\-2011 Michael Schlenker DELETED embedded/md/tcllib/files/modules/base32/base32.md Index: embedded/md/tcllib/files/modules/base32/base32.md ================================================================== --- embedded/md/tcllib/files/modules/base32/base32.md +++ embedded/md/tcllib/files/modules/base32/base32.md @@ -1,125 +0,0 @@ - -[//000000001]: # (base32 \- Base32 encoding) -[//000000002]: # (Generated from file 'base32\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Public domain) -[//000000004]: # (base32\(n\) 0\.1 tcllib "Base32 encoding") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -base32 \- base32 standard encoding - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Code map](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require base32::core ?0\.1? -package require base32 ?0\.1? - -[__::base32::encode__ *string*](#1) -[__::base32::decode__ *estring*](#2) - -# DESCRIPTION - -This package provides commands for encoding and decoding of strings into and out -of the standard base32 encoding as specified in RFC 3548\. - -# API - - - __::base32::encode__ *string* - - This command encodes the given *string* in base32 and returns the encoded - string as its result\. The result may be padded with the character __=__ - to signal a partial encoding at the end of the input string\. - - - __::base32::decode__ *estring* - - This commands takes the *estring* and decodes it under the assumption that - it is a valid base32 encoded string\. The result of the decoding is returned - as the result of the command\. - - Note that while the encoder will generate only uppercase characters this - decoder accepts input in lowercase as well\. - - The command will always throw an error whenever encountering conditions - which signal some type of bogus input, namely if - - 1. the input contains characters which are not valid output of a base32 - encoder, - - 1. the length of the input is not a multiple of eight, - - 1. padding appears not at the end of input, but in the middle, - - 1. the padding has not of length six, four, three, or one characters, - -# Code map - -The code map used to convert 5\-bit sequences is shown below, with the numeric id -of the bit sequences to the left and the character used to encode it to the -right\. It should be noted that the characters "0" and "1" are not used by the -encoding\. This is done as these characters can be easily confused with "O", "o" -and "l" \(L\)\. - - 0 A 9 J 18 S 27 3 - 1 B 10 K 19 T 28 4 - 2 C 11 L 20 U 29 5 - 3 D 12 M 21 V 30 6 - 4 E 13 N 22 W 31 7 - 5 F 14 O 23 X - 6 G 15 P 24 Y - 7 H 16 Q 25 Z - 8 I 17 R 26 2 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base32* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[base32](\.\./\.\./\.\./\.\./index\.md\#base32), -[rfc3548](\.\./\.\./\.\./\.\./index\.md\#rfc3548) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Public domain DELETED embedded/md/tcllib/files/modules/base32/base32core.md Index: embedded/md/tcllib/files/modules/base32/base32core.md ================================================================== --- embedded/md/tcllib/files/modules/base32/base32core.md +++ embedded/md/tcllib/files/modules/base32/base32core.md @@ -1,109 +0,0 @@ - -[//000000001]: # (base32::core \- Base32 encoding) -[//000000002]: # (Generated from file 'base32core\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Public domain) -[//000000004]: # (base32::core\(n\) 0\.1 tcllib "Base32 encoding") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -base32::core \- Expanding basic base32 maps - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require base32::core ?0\.1? - -[__::base32::core::define__ *map* *forwvar* *backwvar* *ivar*](#1) -[__::base32::core::valid__ *string* *pattern* *mvar*](#2) - -# DESCRIPTION - -This package provides generic commands for the construction of full base32 -mappings from a basic mapping listing just the codes and associated characters\. -The full mappings, regular and inverse, created here map to and from bit -sequences, and also handle the partial mappings at the end of a string\. - -This is in essence an internal package to be used by implementors of a base32 -en\- and decoder\. A regular user has no need of this package at all\. - -# API - - - __::base32::core::define__ *map* *forwvar* *backwvar* *ivar* - - This command computes full forward and backward \(inverse\) mappings from the - basic *map* and stores them in the variables named by *forwvar* and - *backwvar* resp\. It also constructs a regexp pattern for the detection of - invalid characters in supposedly base32 encoded input and stores it in the - variable named by *ivar*\. - - - __::base32::core::valid__ *string* *pattern* *mvar* - - This command checks if the input *string* is a valid base32 encoded - string, based on the *pattern* of invalid characters as generated by - __::base32::core::define__, and some other general rules\. - - The result of the command is a boolean flag\. Its value is __True__ for a - valid *string*, and __False__ otherwise\. In the latter case an error - message describing the problem with the input is stored into the variable - named by *mvar*\. The variable is not touched if the input was found to be - valid\. - - The rules checked by the command, beyond rejection of bad characters, are: - - 1. The length of the input is not a multiple of eight, - - 1. The padding appears not at the end of input, but in the middle, - - 1. The padding has not of length six, four, three, or one characters, - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base32* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[base32](\.\./\.\./\.\./\.\./index\.md\#base32) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Public domain DELETED embedded/md/tcllib/files/modules/base32/base32hex.md Index: embedded/md/tcllib/files/modules/base32/base32hex.md ================================================================== --- embedded/md/tcllib/files/modules/base32/base32hex.md +++ embedded/md/tcllib/files/modules/base32/base32hex.md @@ -1,125 +0,0 @@ - -[//000000001]: # (base32::hex \- Base32 encoding) -[//000000002]: # (Generated from file 'base32hex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Public domain) -[//000000004]: # (base32::hex\(n\) 0\.1 tcllib "Base32 encoding") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -base32::hex \- base32 extended hex encoding - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Code map](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require base32::core ?0\.1? -package require base32::hex ?0\.1? - -[__::base32::hex::encode__ *string*](#1) -[__::base32::hex::decode__ *estring*](#2) - -# DESCRIPTION - -This package provides commands for encoding and decoding of strings into and out -of the extended hex base32 encoding as specified in the RFC 3548bis draft\. - -# API - - - __::base32::hex::encode__ *string* - - This command encodes the given *string* in extended hex base32 and returns - the encoded string as its result\. The result may be padded with the - character __=__ to signal a partial encoding at the end of the input - string\. - - - __::base32::hex::decode__ *estring* - - This commands takes the *estring* and decodes it under the assumption that - it is a valid extended hex base32 encoded string\. The result of the decoding - is returned as the result of the command\. - - Note that while the encoder will generate only uppercase characters this - decoder accepts input in lowercase as well\. - - The command will always throw an error whenever encountering conditions - which signal some type of bogus input, namely if - - 1. the input contains characters which are not valid output of a extended - hex base32 encoder, - - 1. the length of the input is not a multiple of eight, - - 1. padding appears not at the end of input, but in the middle, - - 1. the padding has not of length six, four, three, or one characters, - -# Code map - -The code map used to convert 5\-bit sequences is shown below, with the numeric id -of the bit sequences to the left and the character used to encode it to the -right\. The important feature of the extended hex mapping is that the first 16 -codes map to the digits and hex characters\. - - 0 0 9 9 18 I 27 R - 1 1 10 A 19 J 28 S - 2 2 11 B 20 K 29 T - 3 3 12 C 21 L 30 U - 4 4 13 D 22 M 31 V - 5 5 14 E 23 N - 6 6 15 F 24 O - 7 7 16 G 25 P - 8 8 17 H 26 Q - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base32* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[base32](\.\./\.\./\.\./\.\./index\.md\#base32), [hex](\.\./\.\./\.\./\.\./index\.md\#hex), -[rfc3548](\.\./\.\./\.\./\.\./index\.md\#rfc3548) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Public domain DELETED embedded/md/tcllib/files/modules/base64/ascii85.md Index: embedded/md/tcllib/files/modules/base64/ascii85.md ================================================================== --- embedded/md/tcllib/files/modules/base64/ascii85.md +++ embedded/md/tcllib/files/modules/base64/ascii85.md @@ -1,117 +0,0 @@ - -[//000000001]: # (ascii85 \- Text encoding & decoding binary data) -[//000000002]: # (Generated from file 'ascii85\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010, Emiliano Gavilán) -[//000000004]: # (ascii85\(n\) 1\.0 tcllib "Text encoding & decoding binary data") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ascii85 \- ascii85\-encode/decode binary data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [References](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require ascii85 ?1\.0? - -[__::ascii85::encode__ ?__\-maxlen__ *maxlen*? ?__\-wrapchar__ *wrapchar*? *string*](#1) -[__::ascii85::decode__ *string*](#2) - -# DESCRIPTION - -This package provides procedures to encode binary data into ascii85 and back\. - - - __::ascii85::encode__ ?__\-maxlen__ *maxlen*? ?__\-wrapchar__ *wrapchar*? *string* - - Ascii85 encodes the given binary *string* and returns the encoded result\. - Inserts the character *wrapchar* every *maxlen* characters of output\. - *wrapchar* defaults to newline\. *maxlen* defaults to __76__\. - - *Note well*: If your string is not simple ascii you should fix the string - encoding before doing ascii85 encoding\. See the examples\. - - The command will throw an error for negative values of *maxlen*, or if - *maxlen* is not an integer number\. - - - __::ascii85::decode__ *string* - - Ascii85 decodes the given *string* and returns the binary data\. The - decoder ignores whitespace in the string, as well as tabs and newlines\. - -# EXAMPLES - - % ascii85::encode "Hello, world" - 87cURD_*#TDfTZ) - - % ascii85::encode [string repeat xyz 24] - G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G - ^4U[H$X^\H?a^] - % ascii85::encode -wrapchar "" [string repeat xyz 24] - G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^] - - # NOTE: ascii85 encodes BINARY strings. - % set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"] - % set encoded [ascii85::encode $chemical] - 6fN]R8E,5Pidu\UiduhZidua - % set caffeine [encoding convertfrom utf-8 [ascii85::decode $encoded]] - -# References - - 1. [http://en\.wikipedia\.org/wiki/Ascii85](http://en\.wikipedia\.org/wiki/Ascii85) - - 1. Postscript Language Reference Manual, 3rd Edition, page 131\. - [http://www\.adobe\.com/devnet/postscript/pdfs/PLRM\.pdf](http://www\.adobe\.com/devnet/postscript/pdfs/PLRM\.pdf) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base64* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ascii85](\.\./\.\./\.\./\.\./index\.md\#ascii85), -[encoding](\.\./\.\./\.\./\.\./index\.md\#encoding) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2010, Emiliano Gavilán DELETED embedded/md/tcllib/files/modules/base64/base64.md Index: embedded/md/tcllib/files/modules/base64/base64.md ================================================================== --- embedded/md/tcllib/files/modules/base64/base64.md +++ embedded/md/tcllib/files/modules/base64/base64.md @@ -1,113 +0,0 @@ - -[//000000001]: # (base64 \- Text encoding & decoding binary data) -[//000000002]: # (Generated from file 'base64\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2000, Eric Melski) -[//000000004]: # (Copyright © 2001, Miguel Sofer) -[//000000005]: # (base64\(n\) 2\.4\.2 tcllib "Text encoding & decoding binary data") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -base64 \- base64\-encode/decode binary data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8 -package require base64 ?2\.4\.2? - -[__::base64::encode__ ?__\-maxlen__ *maxlen*? ?__\-wrapchar__ *wrapchar*? *string*](#1) -[__::base64::decode__ *string*](#2) - -# DESCRIPTION - -This package provides procedures to encode binary data into base64 and back\. - - - __::base64::encode__ ?__\-maxlen__ *maxlen*? ?__\-wrapchar__ *wrapchar*? *string* - - Base64 encodes the given binary *string* and returns the encoded result\. - Inserts the character *wrapchar* every *maxlen* characters of output\. - *wrapchar* defaults to newline\. *maxlen* defaults to __76__\. - - *Note* that if *maxlen* is set to __0__, the output will not be - wrapped at all\. - - *Note well*: If your string is not simple ascii you should fix the string - encoding before doing base64 encoding\. See the examples\. - - The command will throw an error for negative values of *maxlen*, or if - *maxlen* is not an integer number\. - - - __::base64::decode__ *string* - - Base64 decodes the given *string* and returns the binary data\. The decoder - ignores whitespace in the string\. - -# EXAMPLES - - % base64::encode "Hello, world" - SGVsbG8sIHdvcmxk - - % base64::encode [string repeat xyz 20] - eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6 - eHl6eHl6eHl6 - % base64::encode -wrapchar "" [string repeat xyz 20] - eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6 - - # NOTE: base64 encodes BINARY strings. - % set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"] - % set encoded [base64::encode $chemical] - Q+KCiEjigoHigoBO4oKET+KCgg== - % set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]] - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base64* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[base64](\.\./\.\./\.\./\.\./index\.md\#base64), -[encoding](\.\./\.\./\.\./\.\./index\.md\#encoding) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2000, Eric Melski -Copyright © 2001, Miguel Sofer DELETED embedded/md/tcllib/files/modules/base64/uuencode.md Index: embedded/md/tcllib/files/modules/base64/uuencode.md ================================================================== --- embedded/md/tcllib/files/modules/base64/uuencode.md +++ embedded/md/tcllib/files/modules/base64/uuencode.md @@ -1,138 +0,0 @@ - -[//000000001]: # (uuencode \- Text encoding & decoding binary data) -[//000000002]: # (Generated from file 'uuencode\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts) -[//000000004]: # (uuencode\(n\) 1\.1\.4 tcllib "Text encoding & decoding binary data") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uuencode \- UU\-encode/decode binary data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OPTIONS](#section2) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8 -package require uuencode ?1\.1\.4? - -[__::uuencode::encode__ *string*](#1) -[__::uuencode::decode__ *string*](#2) -[__::uuencode::uuencode__ ?__\-name__ *string*? ?__\-mode__ *octal*? \(__\-file__ *filename* | ?__\-\-__? *string*\)](#3) -[__::uuencode::uudecode__ \(__\-file__ *filename* | ?__\-\-__? *string*\)](#4) - -# DESCRIPTION - -This package provides a Tcl\-only implementation of the __uuencode\(1\)__ and -__uudecode\(1\)__ commands\. This encoding packs binary data into printable -ASCII characters\. - - - __::uuencode::encode__ *string* - - returns the uuencoded data\. This will encode all the data passed in even if - this is longer than the uuencode maximum line length\. If the number of input - bytes is not a multiple of 3 then additional 0 bytes are added to pad the - string\. - - - __::uuencode::decode__ *string* - - Decodes the given encoded data\. This will return any padding characters as - well and it is the callers responsibility to deal with handling the actual - length of the encoded data\. \(see uuencode\)\. - - - __::uuencode::uuencode__ ?__\-name__ *string*? ?__\-mode__ *octal*? \(__\-file__ *filename* | ?__\-\-__? *string*\) - - - __::uuencode::uudecode__ \(__\-file__ *filename* | ?__\-\-__? *string*\) - - UUDecode a file or block of data\. A file may contain more than one embedded - file so the result is a list where each element is a three element list of - filename, mode value and data\. - -# OPTIONS - - - \-filename name - - Cause the uuencode or uudecode commands to read their data from the named - file rather that taking a string parameter\. - - - \-name string - - The uuencoded data header line contains the suggested file name to be used - when unpacking the data\. Use this option to change this from the default of - "data\.dat"\. - - - \-mode octal - - The uuencoded data header line contains a suggested permissions bit pattern - expressed as an octal string\. To change the default of 0644 you can set this - option\. For instance, 0755 would be suitable for an executable\. See - __chmod\(1\)__\. - -# EXAMPLES - - % set d [uuencode::encode "Hello World!"] - 2&5L;&\\@5V]R;&0A - - % uuencode::uudecode $d - Hello World! - - % set d [uuencode::uuencode -name hello.txt "Hello World"] - begin 644 hello.txt - +2&5L;&\@5V]R;&0` - ` - end - - % uuencode::uudecode $d - {hello.txt 644 {Hello World}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base64* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[encoding](\.\./\.\./\.\./\.\./index\.md\#encoding), -[uuencode](\.\./\.\./\.\./\.\./index\.md\#uuencode) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/base64/yencode.md Index: embedded/md/tcllib/files/modules/base64/yencode.md ================================================================== --- embedded/md/tcllib/files/modules/base64/yencode.md +++ embedded/md/tcllib/files/modules/base64/yencode.md @@ -1,139 +0,0 @@ - -[//000000001]: # (yencode \- Text encoding & decoding binary data) -[//000000002]: # (Generated from file 'yencode\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts) -[//000000004]: # (yencode\(n\) 1\.1\.2 tcllib "Text encoding & decoding binary data") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -yencode \- Y\-encode/decode binary data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OPTIONS](#section2) - - - [References](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require yencode ?1\.1\.2? - -[__::yencode::encode__ *string*](#1) -[__::yencode::decode__ *string*](#2) -[__::yencode::yencode__ ?__\-name__ *string*? ?__\-line__ *integer*? ?__\-crc32__ *boolean*? \(__\-file__ *filename* | ?__\-\-__? *string*\)](#3) -[__::yencode::ydecode__ \(__\-file__ *filename* | ?__\-\-__? *string*\)](#4) - -# DESCRIPTION - -This package provides a Tcl\-only implementation of the yEnc file encoding\. This -is a recently introduced method of encoding binary files for transmission -through Usenet\. This encoding packs binary data into a format that requires an -8\-bit clean transmission layer but that escapes characters special to the -*[NNTP](\.\./\.\./\.\./\.\./index\.md\#nntp)* posting protocols\. See -[http://www\.yenc\.org/](http://www\.yenc\.org/) for details concerning the -algorithm\. - - - __::yencode::encode__ *string* - - returns the yEnc encoded data\. - - - __::yencode::decode__ *string* - - Decodes the given yEnc encoded data\. - - - __::yencode::yencode__ ?__\-name__ *string*? ?__\-line__ *integer*? ?__\-crc32__ *boolean*? \(__\-file__ *filename* | ?__\-\-__? *string*\) - - Encode a file or block of data\. - - - __::yencode::ydecode__ \(__\-file__ *filename* | ?__\-\-__? *string*\) - - Decode a file or block of data\. A file may contain more than one embedded - file so the result is a list where each element is a three element list of - filename, file size and data\. - -# OPTIONS - - - \-filename name - - Cause the yencode or ydecode commands to read their data from the named file - rather that taking a string parameter\. - - - \-name string - - The encoded data header line contains the suggested file name to be used - when unpacking the data\. Use this option to change this from the default of - "data\.dat"\. - - - \-line integer - - The yencoded data header line contains records the line length used during - the encoding\. Use this option to select a line length other that the default - of 128\. Note that NNTP imposes a 1000 character line length limit and some - gateways may have trouble with more than 255 characters per line\. - - - \-crc32 boolean - - The yEnc specification recommends the inclusion of a cyclic redundancy check - value in the footer\. Use this option to change the default from *true* to - *false*\. - - % set d [yencode::yencode -file testfile.txt] - =ybegin line=128 size=584 name=testfile.txt - -o- data not shown -o- - =yend size=584 crc32=ded29f4f - -# References - - 1. [http://www\.yenc\.org/yenc\-draft\.1\.3\.txt](http://www\.yenc\.org/yenc\-draft\.1\.3\.txt) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *base64* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[encoding](\.\./\.\./\.\./\.\./index\.md\#encoding), -[yEnc](\.\./\.\./\.\./\.\./index\.md\#yenc), -[ydecode](\.\./\.\./\.\./\.\./index\.md\#ydecode), -[yencode](\.\./\.\./\.\./\.\./index\.md\#yencode) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/bee/bee.md Index: embedded/md/tcllib/files/modules/bee/bee.md ================================================================== --- embedded/md/tcllib/files/modules/bee/bee.md +++ embedded/md/tcllib/files/modules/bee/bee.md @@ -1,344 +0,0 @@ - -[//000000001]: # (bee \- BitTorrent) -[//000000002]: # (Generated from file 'bee\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries ) -[//000000004]: # (bee\(n\) 0\.1 tcllib "BitTorrent") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bee \- BitTorrent Serialization Format Encoder/Decoder - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [ENCODER](#subsection1) - - - [DECODER](#subsection2) - - - [FORMAT DEFINITION](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require bee ?0\.1? - -[__::bee::encodeString__ *string*](#1) -[__::bee::encodeNumber__ *integer*](#2) -[__::bee::encodeListArgs__ *value*\.\.\.](#3) -[__::bee::encodeList__ *list*](#4) -[__::bee::encodeDictArgs__ *key* *value*\.\.\.](#5) -[__::bee::encodeDict__ *dict*](#6) -[__::bee::decode__ *string* ?*endvar*? ?*start*?](#7) -[__::bee::decodeIndices__ *string* ?*endvar*? ?*start*?](#8) -[__::bee::decodeChannel__ *chan* __\-command__ *cmdprefix* ?__\-exact__? ?__\-prefix__ *data*?](#9) -[__cmdprefix__ __eof__ *token*](#10) -[__cmdprefix__ __error__ *token* *message*](#11) -[__cmdprefix__ __value__ *token* *value*](#12) -[__::bee::decodeCancel__ *token*](#13) -[__::bee::decodePush__ *token* *string*](#14) - -# DESCRIPTION - -The __bee__ package provides de\- and encoder commands for data in bencoding -\(speak 'bee'\), the serialization format for data and messages used by the -BitTorrent protocol\. - -# PUBLIC API - -## ENCODER - -The package provides one encoder command for each of the basic forms, and two -commands per container, one taking a proper tcl data structure to encode in the -container, the other taking the same information as several arguments\. - - - __::bee::encodeString__ *string* - - Returns the bee\-encoding of the *string*\. - - - __::bee::encodeNumber__ *integer* - - Returns the bee\-encoding of the *integer* number\. - - - __::bee::encodeListArgs__ *value*\.\.\. - - Takes zero or more bee\-encoded values and returns the bee\-encoding of their - list\. - - - __::bee::encodeList__ *list* - - Takes a list of bee\-encoded values and returns the bee\-encoding of the list\. - - - __::bee::encodeDictArgs__ *key* *value*\.\.\. - - Takes zero or more pairs of keys and values and returns the bee\-encoding of - the dictionary they form\. The values are expected to be already bee\-encoded, - but the keys must not be\. Their encoding will be done by the command itself\. - - - __::bee::encodeDict__ *dict* - - Takes a dictionary list of string keys and bee\-encoded values and returns - the bee\-encoding of the list\. Note that the keys in the input must not be - bee\-encoded already\. This will be done by the command itself\. - -## DECODER - -The package provides two main decoder commands, one for decoding a string -expected to contain a complete data structure, the other for the incremental -decoding of bee\-values arriving on a channel\. The latter command is asynchronous -and provides the completed decoded values to the user through a command -callback\. - - - __::bee::decode__ *string* ?*endvar*? ?*start*? - - Takes the bee\-encoding in the string and returns one decoded value\. In the - case of this being a container all contained values are decoded recursively - as well and the result is a properly nested tcl list and/or dictionary\. - - If the optional *endvar* is set then it is the name of a variable to store - the index of the first character *after* the decoded value into\. In other - words, if the string contains more than one value then *endvar* can be - used to obtain the position of the bee\-value after the bee\-value currently - decoded\. together with *start*, see below, it is possible to iterate over - the string to extract all contained values\. - - The optional *start* index defaults to __0__, i\.e\. the beginning of - the string\. It is the index of the first character of the bee\-encoded value - to extract\. - - - __::bee::decodeIndices__ *string* ?*endvar*? ?*start*? - - Takes the same arguments as __::bee::decode__ and returns the same - information in *endvar*\. The result however is different\. Instead of the - tcl value contained in the *string* it returns a list describing the value - with respect to type and location \(indices for the first and last character - of the bee\-value\)\. In case of a container the structure also contains the - same information for all the embedded values\. - - Formally the results for the various types of bee\-values are: - - * string - - A list containing three elements: - - + The constant string __string__, denoting the type of the value\. - - + An integer number greater than or equal to zero\. This is the index - of the first character of the bee\-value in the input *string*\. - - + An integer number greater than or equal to zero\. This is the index - of the last character of the bee\-value in the input *string*\. - - *Note* that this information is present in the results for all four - types of bee\-values, with only the first element changing according to - the type of the value\. - - * integer - - The result is like for strings, except that the type element contains - the constant string __integer__\. - - * list - - The result is like before, with two exceptions: One, the type element - contains the constant string __list__\. And two, the result actually - contains four elements\. The last element is new, and contains the index - data as described here for all elements of the bee\-list\. - - * dictionary - - The result is like for strings, except that the type element contains - the constant string __dict__\. A fourth element is present as well, - with a slightly different structure than for lists\. The element is a - dictionary mapping from the strings keys of the bee\-dictionary to a list - containing two elements\. The first of them is the index information for - the key, and the second element is the index information for the value - the key maps to\. This structure is the only which contains not only - index data, but actual values from the bee\-string\. While the index - information of the keys is unique enough, i\.e\. serviceable as keys, they - are not easy to navigate when trying to find particular element\. Using - the actual keys makes this much easier\. - - - __::bee::decodeChannel__ *chan* __\-command__ *cmdprefix* ?__\-exact__? ?__\-prefix__ *data*? - - The command creates a decoder for a series of bee\-values arriving on the - channel *chan* and returns its handle\. This handle can be used to remove - the decoder again\. Setting up another bee decoder on *chan* while a bee - decoder is still active will fail with an error message\. - - * __\-command__ - - The command prefix *cmdprefix* specified by the *required* option - __\-command__ is used to report extracted values and exceptional - situations \(error, and EOF on the channel\)\. The callback will be - executed at the global level of the interpreter, with two or three - arguments\. The exact call signatures are - - + __cmdprefix__ __eof__ *token* - - The decoder has reached eof on the channel *chan*\. No further - invocations of the callback will be made after this\. The channel has - already been closed at the time of the call, and the *token* is - not valid anymore as well\. - - + __cmdprefix__ __error__ *token* *message* - - The decoder encountered an error, which is not eof\. For example a - malformed bee\-value\. The *message* provides details about the - error\. The decoder token is in the same state as for eof, i\.e\. - invalid\. The channel however is kept open\. - - + __cmdprefix__ __value__ *token* *value* - - The decoder received and successfully decoded a bee\-value\. The - format of the equivalent tcl *value* is the same as returned by - __::bee::decode__\. The channel is still open and the decoder - token is valid\. This means that the callback is able to remove the - decoder\. - - * __\-exact__ - - By default the decoder assumes that the remainder of the data in the - channel consists only of bee\-values, and reads as much as possible per - event, without regard for boundaries between bee\-values\. This means that - if the the input contains non\-bee data after a series of bee\-value the - beginning of that data may be lost because it was already read by the - decoder, but not processed\. - - The __\-exact__ was made for this situation\. When specified the - decoder will take care to not read any characters behind the currently - processed bee\-value, so that any non\-bee data is kept in the channel for - further processing after removal of the decoder\. - - * __\-prefix__ - - If this option is specified its value is assumed to be the beginning of - the bee\-value and used to initialize the internal decoder buffer\. This - feature is required if the creator of the decoder used data from the - channel to determine if it should create the decoder or not\. Without the - option this data would be lost to the decoding\. - - - __::bee::decodeCancel__ *token* - - This command cancels the decoder set up by __::bee::decodeChannel__ and - represented by the handle *token*\. - - - __::bee::decodePush__ *token* *string* - - This command appends the *string* to the internal decoder buffer\. It is - the runtime equivalent of the option __\-prefix__ of - __::bee::decodeChannel__\. Use it to push data back into the decoder when - the __value__ callback used data from the channel to determine if it - should decode another bee\-value or not\. - -# FORMAT DEFINITION - -Data in the bee serialization format is constructed from two basic forms, and -two container forms\. The basic forms are strings and integer numbers, and the -containers are lists and dictionaries\. - - - String *S* - - A string *S* of length *L* is encoded by the string - "*L*__:__*S*", where the length is written out in textual form\. - - - Integer *N* - - An integer number *N* is encoded by the string "__i__*N*__e__"\. - - - List *v1* \.\.\. *vn* - - A list of the values *v1* to *vn* is encoded by the string - "__l__*BV1*\.\.\.*BVn*__e__" where "BV__i__" is the - bee\-encoding of the value "v__i__"\. - - - Dict *k1* \-> *v1* \.\.\. - - A dictionary mapping the string key *k*__i__ to the value - *v*__i__, for __i__ in __1__ \.\.\. __n__ is encoded by the - string "__d__*BK*__i__*BV*__i__\.\.\.__e__" for i in - __1__ \.\.\. __n__, where "BK__i__" is the bee\-encoding of the key - string "k__i__"\. and "BV__i__" is the bee\-encoding of the value - "v__i__"\. - - *Note*: The bee\-encoding does not retain the order of the keys in the - input, but stores in a sorted order\. The sorting is done for the "raw - strings"\. - -Note that the type of each encoded item can be determined immediately from the -first character of its representation: - - - i - - Integer\. - - - l - - List\. - - - d - - Dictionary\. - - - \[0\-9\] - - String\. - -By wrapping an integer number into __i__\.\.\.__e__ the format makes sure -that they are different from strings, which all begin with a digit\. - -# EXAMPLES - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bee* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[BitTorrent](\.\./\.\./\.\./\.\./index\.md\#bittorrent), -[bee](\.\./\.\./\.\./\.\./index\.md\#bee), -[bittorrent](\.\./\.\./\.\./\.\./index\.md\#bittorrent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[torrent](\.\./\.\./\.\./\.\./index\.md\#torrent) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2004 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench.md Index: embedded/md/tcllib/files/modules/bench/bench.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench.md +++ embedded/md/tcllib/files/modules/bench/bench.md @@ -1,308 +0,0 @@ - -[//000000001]: # (bench \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (bench\(n\) 0\.4 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench \- bench \- Processing benchmark suites - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [Benchmark execution](#subsection1) - - - [Result manipulation](#subsection2) - - - [Result format](#subsection3) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require bench ?0\.4? - -[__::bench::locate__ *pattern* *paths*](#1) -[__::bench::run__ ?*option value*\.\.\.? *interp\_list* *file*\.\.\.](#2) -[__::bench::versions__ *interp\_list*](#3) -[__::bench::del__ *bench\_result* *column*](#4) -[__::bench::edit__ *bench\_result* *column* *newvalue*](#5) -[__::bench::merge__ *bench\_result*\.\.\.](#6) -[__::bench::norm__ *bench\_result* *column*](#7) -[__::bench::out::raw__ *bench\_result*](#8) - -# DESCRIPTION - -This package provides commands for the execution of benchmarks written in the -bench language, and for the processing of results generated by such execution\. - -A reader interested in the bench language itself should start with the *[bench -language introduction](bench\_lang\_intro\.md)* and proceed from there to the -formal *[bench language specification](bench\_lang\_spec\.md)*\. - -# PUBLIC API - -## Benchmark execution - - - __::bench::locate__ *pattern* *paths* - - This command locates Tcl interpreters and returns a list containing their - paths\. It searches them in the list of *paths* specified by the caller, - using the glob *pattern*\. - - The command resolves soft links to find the actual executables matching the - pattern\. Note that only interpreters which are marked as executable and are - actually executable on the current platform are put into the result\. - - - __::bench::run__ ?*option value*\.\.\.? *interp\_list* *file*\.\.\. - - This command executes the benchmarks declared in the set of files, once per - Tcl interpreter specified via the *interp\_list*, and per the configuration - specified by the options, and then returns the accumulated timing results\. - The format of this result is described in section [Result - format](#subsection3)\. - - It is assumed that the contents of the files are written in the bench - language\. - - The available options are - - * __\-errors__ *flag* - - The argument is a boolean value\. If set errors in benchmarks are - propagated to the command, aborting benchmark execution\. Otherwise they - are recorded in the timing result via a special result code\. The default - is to propagate and abort\. - - * __\-threads__ *n* - - The argument is a non\-negative integer value declaring the number of - threads to use while executing the benchmarks\. The default value is - __0__, to not use threads\. - - * __\-match__ *pattern* - - The argument is a glob pattern\. Only benchmarks whose description - matches the pattern are executed\. The default is the empty string, to - execute all patterns\. - - * __\-rmatch__ *pattern* - - The argument is a regular expression pattern\. Only benchmarks whose - description matches the pattern are executed\. The default is the empty - string, to execute all patterns\. - - * __\-iters__ *n* - - The argument is positive integer number, the maximal number of - iterations for any benchmark\. The default is __1000__\. Individual - benchmarks can override this\. - - * __\-pkgdir__ *path* - - The argument is a path to an existing, readable directory\. Multiple - paths can be specified, simply use the option multiple times, each time - with one of the paths to use\. - - If no paths were specified the system will behave as before\. If one or - more paths are specified, say __N__, each of the specified - interpreters will be invoked __N__ times, with one of the specified - paths\. The chosen path is put into the interpreters' __auto\_path__, - thus allowing it to find specific versions of a package\. - - In this way the use of __\-pkgdir__ allows the user to benchmark - several different versions of a package, against one or more - interpreters\. - - *Note:* The empty string is allowed as a path and causes the system to - run the specified interpreters with an unmodified __auto\_path__\. In - case the package in question is available there as well\. - - - __::bench::versions__ *interp\_list* - - This command takes a list of Tcl interpreters, identified by their path, and - returns a dictionary mapping from the interpreters to their versions\. - Interpreters which are not actually executable, or fail when interrogated, - are not put into the result\. I\.e the result may contain less interpreters - than there in the input list\. - - The command uses builtin command __info patchlevel__ to determine the - version of each interpreter\. - -## Result manipulation - - - __::bench::del__ *bench\_result* *column* - - This command removes a column, i\.e\. all benchmark results for a specific Tcl - interpreter, from the specified benchmark result and returns the modified - result\. - - The benchmark results are in the format described in section [Result - format](#subsection3)\. - - The column is identified by an integer number\. - - - __::bench::edit__ *bench\_result* *column* *newvalue* - - This command renames a column in the specified benchmark result and returns - the modified result\. This means that the path of the Tcl interpreter in the - identified column is changed to an arbitrary string\. - - The benchmark results are in the format described in section [Result - format](#subsection3)\. - - The column is identified by an integer number\. - - - __::bench::merge__ *bench\_result*\.\.\. - - This commands takes one or more benchmark results, merges them into one big - result, and returns that as its result\. - - All benchmark results are in the format described in section [Result - format](#subsection3)\. - - - __::bench::norm__ *bench\_result* *column* - - This command normalizes the timing results in the specified benchmark result - and returns the modified result\. This means that the cell values are not - times anymore, but factors showing how much faster or slower the execution - was relative to the baseline\. - - The baseline against which the command normalizes are the timing results in - the chosen column\. This means that after the normalization the values in - this column are all __1__, as these benchmarks are neither faster nor - slower than the baseline\. - - A factor less than __1__ indicates a benchmark which was faster than the - baseline, whereas a factor greater than __1__ indicates a slower - execution\. - - The benchmark results are in the format described in section [Result - format](#subsection3)\. - - The column is identified by an integer number\. - - - __::bench::out::raw__ *bench\_result* - - This command formats the specified benchmark result for output to a file, - socket, etc\. This specific command does no formatting at all, it passes the - input through unchanged\. - - For other formatting styles see the packages - __[bench::out::text](bench\_wtext\.md)__ and - __[bench::out::csv](bench\_wcsv\.md)__ which provide commands to - format benchmark results for human consumption, or as CSV data importable by - spread sheets, respectively\. - - Complementary, to read benchmark results from files, sockets etc\. look for - the package __[bench::in](bench\_read\.md)__ and the commands provided - by it\. - -## Result format - -After the execution of a set of benchmarks the raw result returned by this -package is a Tcl dictionary containing all the relevant information\. The -dictionary is a compact representation, i\.e\. serialization, of a 2\-dimensional -table which has Tcl interpreters as columns and benchmarks as rows\. The cells of -the table contain the timing results\. The Tcl interpreters / columns are -identified by their paths\. The benchmarks / rows are identified by their -description\. - -The possible keys are all valid Tcl lists of two or three elements and have one -of the following forms: - - - \{interp \*\} - - The set of keys matching this glob pattern capture the information about all - the Tcl interpreters used to run the benchmarks\. The second element of the - key is the path to the interpreter\. - - The associated value is the version of the Tcl interpreter\. - - - \{desc \*\} - - The set of keys matching this glob pattern capture the information about all - the benchmarks found in the executed benchmark suite\. The second element of - the key is the description of the benchmark, which has to be unique\. - - The associated value is irrelevant, and set to the empty string\. - - - \{usec \* \*\} - - The set of keys matching this glob pattern capture the performance - information, i\.e\. timing results\. The second element of the key is the - description of the benchmark, the third element the path of the Tcl - interpreter which was used to run it\. - - The associated value is either one of several special result codes, or the - time it took to execute the benchmark, in microseconds\. The possible special - result codes are - - * ERR - - Benchmark could not be executed, failed with a Tcl error\. - - * BAD\_RES - - The benchmark could be executed, however the result from its body did - not match the declared expectations\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench\_intro](bench\_intro\.md), [bench\_lang\_intro](bench\_lang\_intro\.md), -[bench\_lang\_spec](bench\_lang\_spec\.md), bench\_read, bench\_wcsv, bench\_wtext - -# KEYWORDS - -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[merging](\.\./\.\./\.\./\.\./index\.md\#merging), -[normalization](\.\./\.\./\.\./\.\./index\.md\#normalization), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_intro.md Index: embedded/md/tcllib/files/modules/bench/bench_intro.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_intro.md +++ embedded/md/tcllib/files/modules/bench/bench_intro.md @@ -1,106 +0,0 @@ - -[//000000001]: # (bench\_intro \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench\_intro\(n\) 1\.0 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench\_intro \- bench introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [HISTORICAL NOTES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -The *[bench](bench\.md)* \(short for *benchmark tools*\), is a set of -related, yet different, entities which are working together for the easy -creation and execution of performance test suites, also known as benchmarks\. -These are - - 1. A tcl based language for the declaration of test cases\. A test case is - represented by a tcl command declaring the various parts needed to execute - it, like setup, cleanup, the commands to test, etc\. - - 1. A package providing the ability to execute test cases written in that - language\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the benchmarking process\. - - 1. A *writer* of benchmarks has to understand the bench language itself\. A - beginner to bench should read the more informally written *[bench - language introduction](bench\_lang\_intro\.md)* first\. Having digested - this the formal *[bench language specification](bench\_lang\_spec\.md)* - should become understandable\. A writer experienced with bench may only need - this last document from time to time, to refresh her memory\. - - 1. A *user* of benchmark suites written in the *[bench](bench\.md)* - language has to know which tools are available for use\. At the bottom level - sits the package __[bench](bench\.md)__, providing the basic - facilities to read and execute files containing benchmarks written in the - bench language, and to manipulate benchmark results\. - -# HISTORICAL NOTES - -This module and package have been derived from Jeff Hobbs' __tclbench__ -application for the benchmarking of the Tcl core and its ancestor -"runbench\.tcl"\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench](bench\.md), bench\_lang\_faq, -[bench\_lang\_intro](bench\_lang\_intro\.md), -[bench\_lang\_spec](bench\_lang\_spec\.md) - -# KEYWORDS - -[bench language](\.\./\.\./\.\./\.\./index\.md\#bench\_language), -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_lang_intro.md Index: embedded/md/tcllib/files/modules/bench/bench_lang_intro.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_lang_intro.md +++ embedded/md/tcllib/files/modules/bench/bench_lang_intro.md @@ -1,183 +0,0 @@ - -[//000000001]: # (bench\_lang\_intro \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\_lang\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench\_lang\_intro\(n\) 1\.0 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench\_lang\_intro \- bench language introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#subsection1) - - - [Basics](#subsection2) - - - [Pre\- and postprocessing](#subsection3) - - - [Advanced pre\- and postprocessing](#subsection4) - - - [FURTHER READING](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document is an informal introduction to version 1 of the bench language -based on a multitude of examples\. After reading this a benchmark writer should -be ready to understand the formal *[bench language -specification](bench\_lang\_spec\.md)*\. - -## Fundamentals - -In the broadest terms possible the *[bench -language](\.\./\.\./\.\./\.\./index\.md\#bench\_language)* is essentially Tcl, plus a -number of commands to support the declaration of benchmarks\. A document written -in this language is a Tcl script and has the same syntax\. - -## Basics - -One of the most simplest benchmarks which can be written in bench is - - bench -desc LABEL -body { - set a b - } - -This code declares a benchmark named __LABEL__ which measures the time it -takes to assign a value to a variable\. The Tcl code doing this assignment is the -__\-body__ of the benchmark\. - -## Pre\- and postprocessing - -Our next example demonstrates how to declare *initialization* and -*[cleanup](\.\./\.\./\.\./\.\./index\.md\#cleanup)* code, i\.e\. code computing -information for the use of the __\-body__, and for releasing such resources -after the measurement is done\. They are the __\-pre__\- and the -__\-post__\-body, respectively\. - -In our example, directly drawn from the benchmark suite of Tcllib's -__[aes](\.\./aes/aes\.md)__ package, the concrete initialization code -constructs the key schedule used by the encryption command whose speed we -measure, and the cleanup code releases any resources bound to that schedule\. - -> bench \-desc "AES\-$\{len\} ECB encryption core" __\-pre__ \{ ->     set key \[aes::Init ecb $k $i\] -> \} \-body \{ ->     aes::Encrypt $key $p -> \} __\-post__ \{ ->     aes::Final $key -> \} - -## Advanced pre\- and postprocessing - -Our last example again deals with initialization and cleanup code\. To see the -difference to the regular initialization and cleanup discussed in the last -section it is necessary to know a bit more about how bench actually measures the -speed of the the __\-body__\. - -Instead of running the __\-body__ just once the system actually executes the -__\-body__ several hundred times and then returns the average of the found -execution times\. This is done to remove environmental effects like machine load -from the result as much as possible, with outliers canceling each other out in -the average\. - -The drawback of doing things this way is that when we measure operations which -are not idempotent we will most likely not measure the time for the operation we -want, but of the state\(s\) the system is in after the first iteration, a mixture -of things we have no interest in\. - -Should we wish, for example, to measure the time it takes to include an element -into a set, with the element not yet in the set, and the set having specific -properties like being a shared Tcl\_Obj, then the first iteration will measure -the time for this\. *However* all subsequent iterations will measure the time -to include an element which is already in the set, and the Tcl\_Obj holding the -set will not be shared anymore either\. In the end the timings taken for the -several hundred iterations of this state will overwhelm the time taken from the -first iteration, the only one which actually measured what we wanted\. - -The advanced initialization and cleanup codes, __\-ipre__\- and the -__\-ipost__\-body respectively, are present to solve this very problem\. While -the regular initialization and cleanup codes are executed before and after the -whole series of iterations the advanced codes are executed before and after each -iteration of the body, without being measured themselves\. This allows them to -bring the system into the exact state the body wishes to measure\. - -Our example, directly drawn from the benchmark suite of Tcllib's -__[struct::set](\.\./struct/struct\_set\.md)__ package, is for exactly the -example we used above to demonstrate the necessity for the advanced -initialization and cleanup\. Its concrete initialization code constructs a -variable refering to a set with specific properties \(The set has a string -representation, which is shared\) affecting the speed of the inclusion command, -and the cleanup code releases the temporary variables created by this -initialization\. - -> bench \-desc "set include, missing x$times $n" __\-ipre__ \{ ->     set A $sx\($times,$n\) ->     set B $A -> \} \-body \{ ->     struct::set include A x -> \} __\-ipost__ \{ ->     unset A B -> \} - -# FURTHER READING - -Now that this document has been digested the reader, assumed to be a *writer* -of benchmarks, he should be fortified enough to be able to understand the formal -*bench language specfication*\. It will also serve as the detailed -specification and cheat sheet for all available commands and their syntax\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench\_intro](bench\_intro\.md), [bench\_lang\_spec](bench\_lang\_spec\.md) - -# KEYWORDS - -[bench language](\.\./\.\./\.\./\.\./index\.md\#bench\_language), -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[examples](\.\./\.\./\.\./\.\./index\.md\#examples), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_lang_spec.md Index: embedded/md/tcllib/files/modules/bench/bench_lang_spec.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_lang_spec.md +++ embedded/md/tcllib/files/modules/bench/bench_lang_spec.md @@ -1,175 +0,0 @@ - -[//000000001]: # (bench\_lang\_spec \- Documentation tools) -[//000000002]: # (Generated from file 'bench\_lang\_spec\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench\_lang\_spec\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench\_lang\_spec \- bench language specification - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__bench\_rm__ *path*\.\.\.](#1) -[__bench\_tmpfile__](#2) -[__[bench](bench\.md)__ *options*\.\.\.](#3) - -# DESCRIPTION - -This document specifies both names and syntax of all the commands which together -are the bench language, version 1\. As this document is intended to be a -reference the commands are listed in alphabetical order, and the descriptions -are relatively short\. A beginner should read the more informally written -*[bench language introduction](bench\_lang\_intro\.md)* first\. - -# Commands - - - __bench\_rm__ *path*\.\.\. - - This command silently removes the files specified as its arguments and then - returns the empty string as its result\. The command is *trusted*, there is - no checking if the specified files are outside of whatever restricted area - the benchmarks are run in\. - - - __bench\_tmpfile__ - - This command returns the path to a bench specific unique temporary file\. The - uniqueness means that multiple calls will return different paths\. While the - path may exist from previous runs, the command itself does *not* create - aynthing\. - - The base location of the temporary files is platform dependent: - - * Unix, and indeterminate platform - - "/tmp" - - * Windows - - __$TEMP__ - - * Anything else - - The current working directory\. - - - __[bench](bench\.md)__ *options*\.\.\. - - This command declares a single benchmark\. Its result is the empty string\. - All parts of the benchmark are declared via options, and their values\. The - options can occur in any order\. The accepted options are: - - * __\-body__ script - - The argument of this option declares the body of the benchmark, the Tcl - script whose performance we wish to measure\. This option, and - __\-desc__, are the two required parts of each benchmark\. - - * __\-desc__ msg - - The argument of this option declares the name of the benchmark\. It has - to be unique, or timing data from different benchmarks will be mixed - together\. - - *Beware\!* This requirement is not checked when benchmarks are - executed, and the system will silently produce bogus data\. This option, - and __\-body__, are the two required parts of each benchmark\. - - * __\-ipost__ script - - The argument of this option declares a script which is run immediately - *after* each iteration of the body\. Its responsibility is to release - resources created by the body, or __\-ipre__\-bodym which we do not - wish to live into the next iteration\. - - * __\-ipre__ script - - The argument of this option declares a script which is run immediately - *before* each iteration of the body\. Its responsibility is to create - the state of the system expected by the body so that we measure the - right thing\. - - * __\-iterations__ num - - The argument of this option declares the maximum number of times to run - the __\-body__ of the benchmark\. During execution this and the global - maximum number of iterations are compared and the smaller of the two - values is used\. - - This option should be used only for benchmarks which are expected or - known to take a long time per run\. I\.e\. reduce the number of times they - are run to keep the overall time for the execution of the whole - benchmark within manageable limits\. - - * __\-post__ script - - The argument of this option declares a script which is run *after* all - iterations of the body have been run\. Its responsibility is to release - resources created by the body, or __\-pre__\-body\. - - * __\-pre__ script - - The argument of this option declares a script which is run *before* - any of the iterations of the body are run\. Its responsibility is to - create whatever resources are needed by the body to run without failing\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench\_intro](bench\_intro\.md), [bench\_lang\_intro](bench\_lang\_intro\.md) - -# KEYWORDS - -[bench language](\.\./\.\./\.\./\.\./index\.md\#bench\_language), -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[specification](\.\./\.\./\.\./\.\./index\.md\#specification), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_read.md Index: embedded/md/tcllib/files/modules/bench/bench_read.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_read.md +++ embedded/md/tcllib/files/modules/bench/bench_read.md @@ -1,119 +0,0 @@ - -[//000000001]: # (bench::in \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\_read\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench::in\(n\) 0\.1 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench::in \- bench::in \- Reading benchmark results - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require csv -package require bench::in ?0\.1? - -[__::bench::in::read__ *file*](#1) - -# DESCRIPTION - -This package provides a command for reading benchmark results from files, -sockets, etc\. - -A reader interested in the creation, processing or writing of such results -should go and read *[bench \- Processing benchmark suites](bench\.md)* -instead\. - -If the bench language itself is the actual interest please start with the -*[bench language introduction](bench\_lang\_intro\.md)* and then proceed from -there to the formal *[bench language specification](bench\_lang\_spec\.md)*\. - -# PUBLIC API - - - __::bench::in::read__ *file* - - This command reads a benchmark result from the specified *file* and - returns it as its result\. The command understands the three formats created - by the commands - - * __bench::out::raw__ - - Provided by package __[bench](bench\.md)__\. - - * __[bench::out::csv](bench\_wcsv\.md)__ - - Provided by package __[bench::out::csv](bench\_wcsv\.md)__\. - - * __[bench::out::text](bench\_wtext\.md)__ - - Provided by package __[bench::out::text](bench\_wtext\.md)__\. - - and automatically detects which format is used by the input file\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench](bench\.md), [bench::out::csv](bench\_wcsv\.md), -[bench::out::text](bench\_wtext\.md), [bench\_intro](bench\_intro\.md) - -# KEYWORDS - -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[csv](\.\./\.\./\.\./\.\./index\.md\#csv), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), [human -readable](\.\./\.\./\.\./\.\./index\.md\#human\_readable), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[reading](\.\./\.\./\.\./\.\./index\.md\#reading), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing), -[text](\.\./\.\./\.\./\.\./index\.md\#text) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_wcsv.md Index: embedded/md/tcllib/files/modules/bench/bench_wcsv.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_wcsv.md +++ embedded/md/tcllib/files/modules/bench/bench_wcsv.md @@ -1,103 +0,0 @@ - -[//000000001]: # (bench::out::csv \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\_wcsv\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench::out::csv\(n\) 0\.1\.2 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench::out::csv \- bench::out::csv \- Formatting benchmark results as CSV - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require bench::out::csv ?0\.1\.2? - -[__::bench::out::csv__ *bench\_result*](#1) - -# DESCRIPTION - -This package provides commands for fomatting of benchmark results into a CSV -table importable by spread sheets\. - -A reader interested in the generation or processing of such results should go -and read *[bench \- Processing benchmark suites](bench\.md)* instead\. - -If the bench language itself is the actual interest please start with the -*[bench language introduction](bench\_lang\_intro\.md)* and then proceed from -there to the formal *[bench language specification](bench\_lang\_spec\.md)*\. - -# PUBLIC API - - - __::bench::out::csv__ *bench\_result* - - This command formats the specified benchmark result for output to a file, - socket, etc\. This specific command generates CSV data importable by spread - sheets\. - - For other formatting styles see the packages __[bench](bench\.md)__ - and __[bench::out::text](bench\_wtext\.md)__ which provide commands to - format benchmark results in raw form, or for human consumption, - respectively\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench](bench\.md), [bench::out::text](bench\_wtext\.md) - -# KEYWORDS - -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[csv](\.\./\.\./\.\./\.\./index\.md\#csv), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bench/bench_wtext.md Index: embedded/md/tcllib/files/modules/bench/bench_wtext.md ================================================================== --- embedded/md/tcllib/files/modules/bench/bench_wtext.md +++ embedded/md/tcllib/files/modules/bench/bench_wtext.md @@ -1,104 +0,0 @@ - -[//000000001]: # (bench::out::text \- Benchmarking/Performance tools) -[//000000002]: # (Generated from file 'bench\_wtext\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (bench::out::text\(n\) 0\.1\.2 tcllib "Benchmarking/Performance tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bench::out::text \- bench::out::text \- Formatting benchmark results as human -readable text - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require bench::out::text ?0\.1\.2? - -[__::bench::out::text__ *bench\_result*](#1) - -# DESCRIPTION - -This package provides commands for fomatting of benchmark results into human -readable text\. - -A reader interested in the generation or processing of such results should go -and read *[bench \- Processing benchmark suites](bench\.md)* instead\. - -If the bench language itself is the actual interest please start with the -*[bench language introduction](bench\_lang\_intro\.md)* and then proceed from -there to the formal *[bench language specification](bench\_lang\_spec\.md)*\. - -# PUBLIC API - - - __::bench::out::text__ *bench\_result* - - This command formats the specified benchmark result for output to a file, - socket, etc\. This specific command generates human readable text\. - - For other formatting styles see the packages __[bench](bench\.md)__ - and __[bench::out::csv](bench\_wcsv\.md)__ which provide commands to - format benchmark results in raw form, or as importable CSV data, - respectively\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bench* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[bench](bench\.md), [bench::out::csv](bench\_wcsv\.md) - -# KEYWORDS - -[benchmark](\.\./\.\./\.\./\.\./index\.md\#benchmark), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), [human -readable](\.\./\.\./\.\./\.\./index\.md\#human\_readable), -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[testing](\.\./\.\./\.\./\.\./index\.md\#testing), -[text](\.\./\.\./\.\./\.\./index\.md\#text) - -# CATEGORY - -Benchmark tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/bibtex/bibtex.md Index: embedded/md/tcllib/files/modules/bibtex/bibtex.md ================================================================== --- embedded/md/tcllib/files/modules/bibtex/bibtex.md +++ embedded/md/tcllib/files/modules/bibtex/bibtex.md @@ -1,198 +0,0 @@ - -[//000000001]: # (bibtex \- bibtex) -[//000000002]: # (Generated from file 'bibtex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 for documentation, Andreas Kupries ) -[//000000004]: # (bibtex\(n\) 0\.7 tcllib "bibtex") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -bibtex \- Parse bibtex files - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require bibtex ?0\.7? - -[__::bibtex::parse__ ?*options*? ?*text*?](#1) -[__::bibtex::parse__ *text*](#2) -[__::bibtex::parse__ ?__\-command__ *cmd*? __\-channel__ *chan*](#3) -[__::bibtex::parse__ ?__\-recordcommand__ *recordcmd*? ?__\-preamblecommand__ *preamblecmd*? ?__\-stringcommand__ *stringcmd*? ?__\-commentcommand__ *commentcmd*? ?__\-progresscommand__ *progresscmd*? ?__\-casesensitivestrings__ *bool*? \(*text* | __\-channel__ *chan*\)](#4) -[__::bibtex::wait__ *token*](#5) -[__::bibtex::destroy__ *token*](#6) -[__::bibtex::addStrings__ *token* *stringdict*](#7) - -# DESCRIPTION - -This package provides commands for the parsing of bibliographies in BibTeX -format\. - - - __::bibtex::parse__ ?*options*? ?*text*? - - This is the general form of the command for parsing a bibliography\. - Depending on the options used to invoke it it will either return a token for - the parser, or the parsed entries of the input bibliography\. Instead of - performing an immediate parse returning a predefined format the command can - also enter an event\-based parsing style where all relevant entries in the - input are reported through callback commands, in the style of SAX\. - - - __::bibtex::parse__ *text* - - In this form the command will assume that the specified *text* is a - bibliography in BibTeX format, parse it, and then return a list containing - one element per record found in the bibliography\. Note that comments, string - definitions, preambles, etc\. will not show up in the result\. Each element - will be a list containing record type, bibliography key and record data, in - this order\. The record data will be a dictionary, its keys the keys of the - record, with the associated values\. - - - __::bibtex::parse__ ?__\-command__ *cmd*? __\-channel__ *chan* - - In this form the command will reads the bibliography from the specified Tcl - channel *chan* and then returns the same data structure as described - above\. - - If however the option __\-command__ is specified the result will be a - handle for the parser instead and all processing will be incremental and - happen in the background\. When the input has been exhausted the callback - *cmd* will be invoked with the result of the parse\. The exact definition - for the callback is - - * __cmd__ *token* *parseresult* - - The parse result will have the structure explained above, for the - simpler forms of the parser\. - - *Note* that the parser will *not* close the channel after it has - exhausted it\. This is still the responsibility of the user of the parser\. - - - __::bibtex::parse__ ?__\-recordcommand__ *recordcmd*? ?__\-preamblecommand__ *preamblecmd*? ?__\-stringcommand__ *stringcmd*? ?__\-commentcommand__ *commentcmd*? ?__\-progresscommand__ *progresscmd*? ?__\-casesensitivestrings__ *bool*? \(*text* | __\-channel__ *chan*\) - - This is the most low\-level form for the parser\. The returned result will be - a handle for the parser\. During processing it will invoke the invoke the - specified callback commands for each type of data found in the bibliography\. - - The processing will be incremental and happen in the background if, and only - if a Tcl channel *chan* is specified\. For a *text* the processing will - happen immediately and all callbacks will be invoked before the command - itself returns\. - - The callbacks, i\.e\. *\*cmd*, are all command prefixes and will be invoked - with additional arguments appended to them\. The meaning of the arguments - depends on the callback and is explained below\. The first argument will - however always be the handle of the parser invoking the callback\. - - * __\-casesensitivestrings__ - - This option takes a boolean value\. When set string macro processing - becomes case\-sensitive\. The default is case\-insensitive string macro - processing\. - - * __recordcmd__ *token* *type* *key* *recorddict* - - This callback is invoked whenever the parser detects a bibliography - record in the input\. Its arguments are the record type, the bibliography - key for the record, and a dictionary containing the keys and values - describing the record\. Any string macros known to the parser have - already been expanded\. - - * __preamblecmd__ *token* *preambletext* - - This callback is invoked whenever the parser detects an @preamble block - in the input\. The only additional argument is the text found in the - preamble block\. By default such entries are ignored\. - - * __stringcmd__ *token* *stringdict* - - This callback is invoked whenever the parser detects an @string\-based - macro definition in the input\. The argument is a dictionary with the - macro names as keys and their replacement strings as values\. By default - such definitions are added to the parser state for use in future - bibliography records\. - - * __commentcmd__ *token* *commenttext* - - This callback is invoked whenever the parser detects a comment in the - input\. The only additional argument is the comment text\. By default such - entries are ignored\. - - * __progresscmd__ *token* *percent* - - This callback is invoked during processing to tell the user about the - progress which has been made\. Its argument is the percentage of data - processed, as integer number between __0__ and __100__\. In the - case of incremental processing the perecentage will always be __\-1__ - as the total number of entries is not known beforehand\. - - - __::bibtex::wait__ *token* - - This command waits for the parser represented by the *token* to complete - and then returns\. The returned result is the empty string\. - - - __::bibtex::destroy__ *token* - - This command cleans up all internal state associated with the parser - represented by the handle *token*, effectively destroying it\. This command - can be called from within the parser callbacks to terminate processing\. - - - __::bibtex::addStrings__ *token* *stringdict* - - This command adds the macro definitions stored in the dictionary - *stringdict* to the parser represented by the handle *token*\. - - The dictionary keys are the macro names and the values their replacement - strings\. This command has the correct signature for use as a - __\-stringcommand__ callback in an invokation of the command - __::bibtex::parse__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *bibtex* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[bibliography](\.\./\.\./\.\./\.\./index\.md\#bibliography), -[bibtex](\.\./\.\./\.\./\.\./index\.md\#bibtex), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2005 for documentation, Andreas Kupries DELETED embedded/md/tcllib/files/modules/blowfish/blowfish.md Index: embedded/md/tcllib/files/modules/blowfish/blowfish.md ================================================================== --- embedded/md/tcllib/files/modules/blowfish/blowfish.md +++ embedded/md/tcllib/files/modules/blowfish/blowfish.md @@ -1,198 +0,0 @@ - -[//000000001]: # (blowfish \- Blowfish Block Cipher) -[//000000002]: # (Generated from file 'blowfish\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003, Pat Thoyts ) -[//000000004]: # (blowfish\(n\) 1\.0\.5 tcllib "Blowfish Block Cipher") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -blowfish \- Implementation of the Blowfish block cipher - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [MODES OF OPERATION](#section4) - - - [EXAMPLES](#section5) - - - [REFERENCES](#section6) - - - [AUTHORS](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require blowfish ?1\.0\.5? - -[__::blowfish::blowfish__ ?*\-mode \[ecb|cbc\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-out channel*? ?*\-chunksize size*? ?*\-pad padchar*? \[ *\-in channel* | ?*\-\-*? *data* \]](#1) -[__::blowfish::Init__ *mode* *keydata* *iv*](#2) -[__::blowfish::Encrypt__ *Key* *data*](#3) -[__::blowfish::Decrypt__ *Key* *data*](#4) -[__::blowfish::Reset__ *Key* *iv*](#5) -[__::blowfish::Final__ *Key*](#6) - -# DESCRIPTION - -This package is an implementation in Tcl of the Blowfish algorithm developed by -Bruce Schneier \[1\]\. Blowfish is a 64\-bit block cipher designed to operate -quickly on 32 bit architectures and accepting a variable key length\. This -implementation supports ECB and CBC mode blowfish encryption\. - -# COMMANDS - - - __::blowfish::blowfish__ ?*\-mode \[ecb|cbc\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-out channel*? ?*\-chunksize size*? ?*\-pad padchar*? \[ *\-in channel* | ?*\-\-*? *data* \] - - Perform the __blowfish__ algorithm on either the data provided by the - argument or on the data read from the *\-in* channel\. If an *\-out* - channel is given then the result will be written to this channel\. - - The *\-key* option must be given\. This parameter takes a binary string of - variable length and is used to generate the __blowfish__ key schedule\. - You should be aware that creating a key schedule is quite an expensive - operation in blowfish so it is worth reusing the key where possible\. See - __Reset__\. - - The *\-mode* and *\-dir* options are optional and default to cbc mode and - encrypt respectively\. The initialization vector *\-iv* takes an 8 byte - binary argument which defaults to 8 zeros\. See [MODES OF - OPERATION](#section4) for more about available modes and their uses\. - - Blowfish is a 64\-bit block cipher\. This means that the data must be provided - in units that are a multiple of 8 bytes\. The __blowfish__ command will - by default add nul characters to pad the input data to a multiple of 8 bytes - if necessary\. The programming api commands will never add padding and - instead will raise an error if the input is not a multiple of the block - size\. The *\-pad* option can be used to change the padding character or to - disable padding if the empty string is provided as the argument\. - -# PROGRAMMING INTERFACE - - - __::blowfish::Init__ *mode* *keydata* *iv* - - Construct a new blowfish key schedule using the specified key data and the - given initialization vector\. The initialization vector is not used with ECB - mode but is important for CBC mode\. See [MODES OF OPERATION](#section4) - for details about cipher modes\. - - - __::blowfish::Encrypt__ *Key* *data* - - Use a prepared key acquired by calling __Init__ to encrypt the provided - data\. The data argument should be a binary array that is a multiple of the - block size of 8 bytes\. The result is a binary array the same size as the - input of encrypted data\. - - - __::blowfish::Decrypt__ *Key* *data* - - Decipher data using the key\. Note that the same key may be used to encrypt - and decrypt data provided that the initialization vector is reset - appropriately for CBC mode\. - - - __::blowfish::Reset__ *Key* *iv* - - Reset the initialization vector\. This permits the programmer to re\-use a key - and avoid the cost of re\-generating the key schedule where the same key data - is being used multiple times\. - - - __::blowfish::Final__ *Key* - - This should be called to clean up resources associated with *Key*\. Once - this function has been called the key may not be used again\. - -# MODES OF OPERATION - - - Electronic Code Book \(ECB\) - - ECB is the basic mode of all block ciphers\. Each block is encrypted - independently and so identical plain text will produce identical output when - encrypted with the same key\. Any encryption errors will only affect a single - block however this is vulnerable to known plaintext attacks\. - - - Cipher Block Chaining \(CBC\) - - CBC mode uses the output of the last block encryption to affect the current - block\. An initialization vector of the same size as the cipher block size is - used to handle the first block\. The initialization vector should be chosen - randomly and transmitted as the first block of the output\. Errors in - encryption affect the current block and the next block after which the - cipher will correct itself\. CBC is the most commonly used mode in software - encryption\. - -# EXAMPLES - - % blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!" - d0d8f27e7a374b9e2dbd9938dd04195a - - set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv] - append ciphertext [blowfish::Encrypt $Key $plaintext] - append ciphertext [blowfish::Encrypt $Key $additional_plaintext] - blowfish::Final $Key - -# REFERENCES - - 1. Schneier, B\. "Applied Cryptography, 2nd edition", 1996, ISBN 0\-471\-11709\-9, - pub\. John Wiley & Sons\. - -# AUTHORS - -Frank Pilhofer, Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *blowfish* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -3des, [des](\.\./des/des\.md), [rc4](\.\./rc4/rc4\.md) - -# KEYWORDS - -[block cipher](\.\./\.\./\.\./\.\./index\.md\#block\_cipher), -[blowfish](\.\./\.\./\.\./\.\./index\.md\#blowfish), -[cryptography](\.\./\.\./\.\./\.\./index\.md\#cryptography), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2003, Pat Thoyts DELETED embedded/md/tcllib/files/modules/cache/async.md Index: embedded/md/tcllib/files/modules/cache/async.md ================================================================== --- embedded/md/tcllib/files/modules/cache/async.md +++ embedded/md/tcllib/files/modules/cache/async.md @@ -1,167 +0,0 @@ - -[//000000001]: # (cache::async \- In\-memory caches) -[//000000002]: # (Generated from file 'async\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Andreas Kupries ) -[//000000004]: # (cache::async\(n\) 0\.3\.1 tcllib "In\-memory caches") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -cache::async \- Asynchronous in\-memory cache - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require cache::async ?0\.3\.1? - -[__::cache::async__ *objectName* *commandprefix* ?*options*\.\.\.?](#1) -[*objectName* __get__ *key* *donecmdprefix*](#2) -[*objectName* __set__ *key* *value*](#3) -[*objectName* __unset__ *key*](#4) -[*objectName* __exists__ *key*](#5) -[*objectName* __clear__ ?*key*?](#6) - -# DESCRIPTION - -This package provides objects which cache data in memory, and operate -asynchronously with regard to request and responses\. The objects are agnostic -with regard to cache keys and values, and unknown methods are delegated to the -provider of cached data\. These two properties make it easy to use caches as a -facade for any data provider\. - -# API - -The package exports a class, __cache::async__, as specified below\. - - - __::cache::async__ *objectName* *commandprefix* ?*options*\.\.\.? - - The command creates a new *[cache](\.\./\.\./\.\./\.\./index\.md\#cache)* object - with an associated global Tcl command whose name is *objectName*\. This - command may be used to invoke various operations on the object\. - - The *commandprefix* is the action to perform when an user asks for data in - the cache and the cache doesn't yet know about the key\. When run the - commandprefix is given three additional arguments, the string __get__, - the key requested, and the cache object itself, in the form of its object - command, in this order\. The execution of the action is done in an - idle\-handler, decoupling it from the original request\. - - The only supported option is - - * __\-full\-async\-results__ - - This option defines the behaviour of the cache for when requested keys - are known to the cache at the time of __get__ request\. By default - such requeste are responded to asynchronously as well\. Setting this - option to __false__ forces the cache to respond to them - synchronuously, although still through the specified callback\. - -The object commands created by the class commands above have the form: - - - *objectName* __get__ *key* *donecmdprefix* - - This method requests the data for the *key* from the cache\. If the data is - not yet known the command prefix specified during construction of the cache - object is used to ask for this information\. - - Whenever the information is/becomes available the *donecmdprefix* will be - run to transfer the result to the caller\. This command prefix is invoked - with either 2 or 3 arguments, i\.e\. - - 1. The string __set__, the *key*, and the value\. - - 1. The string __unset__, and the *key*\. - - These two possibilities are used to either signal the value for the *key*, - or that the *key* has no value defined for it\. The latter is distinct from - the cache not knowing about the *key*\. - - For a cache object configured to be fully asynchronous \(default\) the - *donecmdprefix* is always run in an idle\-handler, decoupling it from the - request\. Otherwise the callback will be invoked synchronously when the - *key* is known to the cache at the time of the invokation\. - - Another important part of the cache's behaviour, as it is asynchronous it is - possible that multiple __get__ requests are issued for the same *key* - before it can respond\. In that case the cache will issue only one data - request to the provider, for the first of these, and suspend the others, and - then notify all of them when the data becomes available\. - - - *objectName* __set__ *key* *value* - - - *objectName* __unset__ *key* - - These two methods are provided to allow users of the cache to make keys - known to the cache, as either having a *value*, or as undefined\. - - It is expected that the data provider \(see *commandprefix* of the - constructor\) uses them in response to data requests for unknown keys\. - - Note how this matches the cache's own API towards its caller, calling the - *donecmd* of __get__\-requests issued to itself with either "set key - value" or "unset key", versus issuing __get__\-requests to its own - provider with itself in the place of the *donecmd*, expecting to be called - with either "set key value" or "unset key"\. - - This also means that these methods invoke the *donecmd* of all - __get__\-requests waiting for information about the modified *key*\. - - - *objectName* __exists__ *key* - - This method queries the cache for knowledge about the *key* and returns a - boolean value\. The result is __true__ if the key is known, and - __false__ otherwise\. - - - *objectName* __clear__ ?*key*? - - This method resets the state of either the specified *key* or of all keys - known to the cache, making it unkown\. This forces future - __get__\-requests to reload the information from the provider\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *cache* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[asynchronous](\.\./\.\./\.\./\.\./index\.md\#asynchronous), -[cache](\.\./\.\./\.\./\.\./index\.md\#cache), -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), -[synchronous](\.\./\.\./\.\./\.\./index\.md\#synchronous) - -# COPYRIGHT - -Copyright © 2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/clay/clay.md Index: embedded/md/tcllib/files/modules/clay/clay.md ================================================================== --- embedded/md/tcllib/files/modules/clay/clay.md +++ embedded/md/tcllib/files/modules/clay/clay.md @@ -1,807 +0,0 @@ - -[//000000001]: # (clay \- Clay Framework) -[//000000002]: # (Generated from file 'clay\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2018 Sean Woods ) -[//000000004]: # (clay\(n\) 0\.8\.6 tcllib "Clay Framework") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -clay \- A minimalist framework for large scale OO Projects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Structured Data](#subsection1) - - - [Clay Dialect](#subsection2) - - - [Method Delegation](#subsection3) - - - [Commands](#section2) - - - [Classes](#section3) - - - [Class clay::class](#subsection4) - - - [Class clay::object](#subsection5) - - - [AUTHORS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require uuid -package require oo::dialect - -[proc __clay::PROC__ *name* *arglist* *body* ?*ninja* ____?](#1) -[proc __clay::\_ancestors__ *resultvar* *class*](#2) -[proc __clay::ancestors__ ?*args*?](#3) -[proc __clay::args\_to\_dict__ ?*args*?](#4) -[proc __clay::args\_to\_options__ ?*args*?](#5) -[proc __clay::dynamic\_arguments__ *ensemble* *method* *arglist* ?*args*?](#6) -[proc __clay::dynamic\_wrongargs\_message__ *arglist*](#7) -[proc __clay::is\_dict__ *d*](#8) -[proc __clay::is\_null__ *value*](#9) -[proc __clay::leaf__ ?*args*?](#10) -[proc __clay::K__ *a* *b*](#11) -[proc __clay::noop__ ?*args*?](#12) -[proc __clay::cleanup__](#13) -[proc __clay::object\_create__ *objname* ?*class* ____?](#14) -[proc __clay::object\_rename__ *object* *newname*](#15) -[proc __clay::object\_destroy__ ?*args*?](#16) -[proc __clay::path__ ?*args*?](#17) -[proc __clay::putb__ ?*map*? *text*](#18) -[proc __clay::script\_path__](#19) -[proc __clay::NSNormalize__ *qualname*](#20) -[proc __clay::uuid\_generate__ ?*args*?](#21) -[proc __clay::uuid::generate\_tcl\_machinfo__](#22) -[proc __clay::uuid::tostring__ *uuid*](#23) -[proc __clay::uuid::fromstring__ *uuid*](#24) -[proc __clay::uuid::equal__ *left* *right*](#25) -[proc __clay::uuid__ *cmd* ?*args*?](#26) -[proc __clay::tree::sanitize__ *dict*](#27) -[proc __clay::tree::\_sanitizeb__ *path* *varname* *dict*](#28) -[proc __clay::tree::storage__ *rawpath*](#29) -[proc __clay::tree::dictset__ *varname* ?*args*?](#30) -[proc __clay::tree::dictmerge__ *varname* ?*args*?](#31) -[proc __clay::tree::merge__ ?*args*?](#32) -[proc __dictargs::proc__ *name* *argspec* *body*](#33) -[proc __dictargs::method__ *name* *argspec* *body*](#34) -[proc __clay::dialect::Push__ *class*](#35) -[proc __clay::dialect::Peek__](#36) -[proc __clay::dialect::Pop__](#37) -[proc __clay::dialect::create__ *name* ?*parent* ____?](#38) -[proc __clay::dialect::NSNormalize__ *namespace* *qualname*](#39) -[proc __clay::dialect::DefineThunk__ *target* ?*args*?](#40) -[proc __clay::dialect::Canonical__ *namespace* *NSpace* *class*](#41) -[proc __clay::dialect::Define__ *namespace* *class* ?*args*?](#42) -[proc __clay::dialect::Aliases__ *namespace* ?*args*?](#43) -[proc __clay::dialect::SuperClass__ *namespace* ?*args*?](#44) -[proc __clay::dynamic\_methods__ *class*](#45) -[proc __clay::dynamic\_methods\_class__ *thisclass*](#46) -[proc __clay::define::Array__ *name* ?*values* ____?](#47) -[proc __clay::define::Delegate__ *name* *info*](#48) -[proc __clay::define::constructor__ *arglist* *rawbody*](#49) -[proc __clay::define::Class\_Method__ *name* *arglist* *body*](#50) -[proc __clay::define::class\_method__ *name* *arglist* *body*](#51) -[proc __clay::define::clay__ ?*args*?](#52) -[proc __clay::define::destructor__ *rawbody*](#53) -[proc __clay::define::Dict__ *name* ?*values* ____?](#54) -[proc __clay::define::Option__ *name* ?*args*?](#55) -[proc __clay::define::Method__ *name* *argstyle* *argspec* *body*](#56) -[proc __clay::define::Option\_Class__ *name* ?*args*?](#57) -[proc __clay::define::Variable__ *name* ?*default* ____?](#58) -[proc __clay::ensemble\_methodbody__ *ensemble* *einfo*](#59) -[proc __clay::define::Ensemble__ *rawmethod* ?*args*?](#60) -[proc __clay::event::cancel__ *self* ?*task* __\*__?](#61) -[proc __clay::event::generate__ *self* *event* ?*args*?](#62) -[proc __clay::event::nextid__](#63) -[proc __clay::event::Notification\_list__ *self* *event* ?*stackvar* ____?](#64) -[proc __clay::event::notify__ *rcpt* *sender* *event* *eventinfo*](#65) -[proc __clay::event::process__ *self* *handle* *script*](#66) -[proc __clay::event::schedule__ *self* *handle* *interval* *script*](#67) -[proc __clay::event::subscribe__ *self* *who* *event*](#68) -[proc __clay::event::unsubscribe__ *self* ?*args*?](#69) -[proc __clay::singleton__ *name* *script*](#70) -[method __clay ancestors__](#71) -[method __clay dump__](#72) -[method __clay find__ *path* ?__path\.\.\.__?](#73) -[method __clay get__ *path* ?__path\.\.\.__?](#74) -[method __clay GET__ *path* ?__path\.\.\.__?](#75) -[method __clay merge__ *dict* ?__dict\.\.\.__?](#76) -[method __clay replace__ *dictionary*](#77) -[method __clay search__ *path* ?__path\.\.\.__?](#78) -[method __clay set__ *path* ?__path\.\.\.__? *value*](#79) -[method __clay ancestors__](#80) -[method __clay cache__ *path* *value*](#81) -[method __clay cget__ *field*](#82) -[method __clay delegate__ ?*stub*? ?*object*?](#83) -[method __clay dump__](#84) -[method __clay ensemble\_map__](#85) -[method __clay eval__ *script*](#86) -[method __clay evolve__](#87) -[method __clay exists__ *path* ?__path\.\.\.__?](#88) -[method __clay flush__](#89) -[method __clay forward__ *method* *object*](#90) -[method __clay get__ *path* ?__path\.\.\.__?](#91) -[method __clay leaf__ *path* ?__path\.\.\.__?](#92) -[method __clay merge__ *dict* ?__dict\.\.\.__?](#93) -[method __clay mixin__ *class* ?__class\.\.\.__?](#94) -[method __clay mixinmap__ ?*stub*? ?*classes*?](#95) -[method __clay provenance__ *path* ?__path\.\.\.__?](#96) -[method __clay replace__ *dictionary*](#97) -[method __clay search__ *path* *valuevar* *isleafvar*](#98) -[method __clay source__ *filename*](#99) -[method __clay set__ *path* ?__path\.\.\.__? *value*](#100) -[method __InitializePublic__](#101) - -# DESCRIPTION - -Clay introduces a method ensemble to both __oo::class__ and -__oo::object__ called clay\. This ensemble handles all of the high level -interactions within the framework\. Clay stores structured data\. Clan manages -method delegation\. Clay has facilities to manage the complex interactions that -come about with mixins\. - -The central concept is that inside of every object and class \(which are actually -objects too\) is a dict called clay\. What is stored in that dict is left to the -imagination\. But because this dict is exposed via a public method, we can share -structured data between object, classes, and mixins\. - -## Structured Data - -Clay uses a standardized set of method interactions and introspection that TclOO -already provides to perform on\-the\-fly searches\. On\-the\-fly searches mean that -the data is never stale, and we avoid many of the sorts of collisions that would -arise when objects start mixing in other classes during operation\. - -The __clay__ methods for both classes and objects have a get and a set -method\. For objects, get will search through the local clay dict\. If the -requested leaf is not found, or the query is for a branch, the system will then -begin to poll the clay methods of all of the class that implements the object, -all of that classes’ ancestors, as well as all of the classes that have been -mixed into this object, and all of their ancestors\. - -Intended branches on a tree end with a directory slash \(/\)\. Intended leaves are -left unadorned\. This is a guide for the tool that builds the search results to -know what parts of a dict are intended to be branches and which are intended to -be leaves\. For simple cases, branch marking can be ignored: - - ::oo::class create ::foo { } - ::foo clay set property/ color blue - ::foo clay set property/ shape round - - set A [::foo new] - $A clay get property/ - {color blue shape round} - - $A clay set property/ shape square - $A clay get property/ - {color blue shape square} - -But when you start storing blocks of text, guessing what field is a dict and -what isn’t gets messy: - - ::foo clay set description {A generic thing of designated color and shape} - - $A clay get description - {A generic thing of designated color and shape} - - Without a convention for discerning branches for leaves what should have been a value can be accidentally parsed as a dictionary, and merged with all of the other values that were never intended to be merge. Here is an example of it all going wrong: - ::oo::class create ::foo { } - # Add description as a leaf - ::foo clay set description {A generic thing of designated color and shape} - # Add description as a branch - ::foo clay set description/ {A generic thing of designated color and shape} - - ::oo::class create ::bar { - superclass foo - } - # Add description as a leaf - ::bar clay set description {A drinking establishment of designated color and shape and size} - # Add description as a branch - ::bar clay set description/ {A drinking establishment of designated color and shape and size} - - set B [::bar new] - # As a leaf we get the value verbatim from he nearest ancestor - $B clay get description - {A drinking establishment of designated color and shape and size} - # As a branch we get a recursive merge - $B clay get description/ - {A drinking establishment of designated color and size thing of} - -## Clay Dialect - -Clay is built using the oo::dialect module from Tcllib\. oo::dialect allows you -to either add keywords directly to clay, or to create your own metaclass and -keyword set using Clay as a foundation\. For details on the keywords and what -they do, consult the functions in the ::clay::define namespace\. - -## Method Delegation - -Method Delegation It is sometimes useful to have an external object that can be -invoked as if it were a method of the object\. Clay provides a delegate ensemble -method to perform that delegation, as well as introspect which methods are -delegated in that manner\. All delegated methods are marked with html\-like tag -markings \(< >\) around them\. - - ::clay::define counter { - Variable counter 0 - method incr {{howmuch 1}} { - my variable counter - incr counter $howmuch - } - method value {} { - my variable counter - return $counter - } - method reset {} { - my variable counter - set counter 0 - } - } - ::clay::define example { - variable buffer - constructor {} { - # Build a counter object - set obj [namespace current]::counter - ::counter create $obj - # Delegate the counter - my delegate $obj - } - method line {text} { - my incr - append buffer $text - } - } - - set A [example new] - $A line {Who’s line is it anyway?} - $A value - 1 - -# Commands - - - proc __clay::PROC__ *name* *arglist* *body* ?*ninja* ____? - - Because many features in this package may be added as commands to future tcl - cores, or be provided in binary form by packages, I need a declaritive way - of saying *Create this command if there isn't one already*\. The *ninja* - argument is a script to execute if the command is created by this mechanism\. - - - proc __clay::\_ancestors__ *resultvar* *class* - - - proc __clay::ancestors__ ?*args*? - - - proc __clay::args\_to\_dict__ ?*args*? - - - proc __clay::args\_to\_options__ ?*args*? - - - proc __clay::dynamic\_arguments__ *ensemble* *method* *arglist* ?*args*? - - - proc __clay::dynamic\_wrongargs\_message__ *arglist* - - - proc __clay::is\_dict__ *d* - - - proc __clay::is\_null__ *value* - - - proc __clay::leaf__ ?*args*? - - - proc __clay::K__ *a* *b* - - - proc __clay::noop__ ?*args*? - - Perform a noop\. Useful in prototyping for commenting out blocks of code - without actually having to comment them out\. It also makes a handy default - for method delegation if a delegate has not been assigned yet\. - - - proc __clay::cleanup__ - - Process the queue of objects to be destroyed - - - proc __clay::object\_create__ *objname* ?*class* ____? - - - proc __clay::object\_rename__ *object* *newname* - - - proc __clay::object\_destroy__ ?*args*? - - Mark an objects for destruction on the next cleanup - - - proc __clay::path__ ?*args*? - - - proc __clay::putb__ ?*map*? *text* - - Append a line of text to a variable\. Optionally apply a string mapping\. - - - proc __clay::script\_path__ - - - proc __clay::NSNormalize__ *qualname* - - - proc __clay::uuid\_generate__ ?*args*? - - - proc __clay::uuid::generate\_tcl\_machinfo__ - - - proc __clay::uuid::tostring__ *uuid* - - - proc __clay::uuid::fromstring__ *uuid* - - Convert a string representation of a uuid into its binary format\. - - - proc __clay::uuid::equal__ *left* *right* - - Compare two uuids for equality\. - - - proc __clay::uuid__ *cmd* ?*args*? - - uuid generate \-> string rep of a new uuid uuid equal uuid1 uuid2 - - - proc __clay::tree::sanitize__ *dict* - - Output a dictionary removing any \. entries added by - __clay::tree::merge__ - - - proc __clay::tree::\_sanitizeb__ *path* *varname* *dict* - - Helper function for ::clay::tree::sanitize Formats the string representation - for a dictionary element within a human readable stream of lines, and - determines if it needs to call itself with further indentation to express a - sub\-branch - - - proc __clay::tree::storage__ *rawpath* - - Return the path as a storage path for clay::tree with all branch terminators - removed\. This command will also break arguments up if they contain /\. - - Example: - - > clay::tree::storage {foo bar baz bang} - foo bar baz bang - > clay::tree::storage {foo bar baz bang/} - foo bar baz bang - > clay::tree::storage {foo bar baz bang:} - foo bar baz bang: - > clay::tree::storage {foo/bar/baz bang:} - foo bar baz bang: - > clay::tree::storage {foo/bar/baz/bang} - foo bar baz bang - - - proc __clay::tree::dictset__ *varname* ?*args*? - - Set an element with a recursive dictionary, marking all branches on the way - down to the final element\. If the value does not exists in the nested - dictionary it is added as a leaf\. If the value already exists as a branch - the value given is merged if the value is a valid dict\. If the incoming - value is not a valid dict, the value overrides the value stored, and the - value is treated as a leaf from then on\. - - Example: - - > set r {} - > ::clay::tree::dictset r option color default Green - . {} option {. {} color {. {} default Green}} - > ::clay::tree::dictset r option {Something not dictlike} - . {} option {Something not dictlike} - # Note that if the value is not a dict, and you try to force it to be - # an error with be thrown on the merge - > ::clay::tree::dictset r option color default Blue - missing value to go with key - - - proc __clay::tree::dictmerge__ *varname* ?*args*? - - A recursive form of dict merge, intended for modifying variables in place\. - - Example: - - > set mydict {sub/ {sub/ {description {a block of text}}}} - > ::clay::tree::dictmerge mydict {sub/ {sub/ {field {another block of text}}}}] - > clay::tree::print $mydict - sub/ { - sub/ { - description {a block of text} - field {another block of text} - } - } - - - proc __clay::tree::merge__ ?*args*? - - A recursive form of dict merge - - A routine to recursively dig through dicts and merge adapted from - http://stevehavelka\.com/tcl\-dict\-operation\-nested\-merge/ - - Example: - - > set mydict {sub/ {sub/ {description {a block of text}}}} - > set odict [clay::tree::merge $mydict {sub/ {sub/ {field {another block of text}}}}] - > clay::tree::print $odict - sub/ { - sub/ { - description {a block of text} - field {another block of text} - } - } - - - proc __dictargs::proc__ *name* *argspec* *body* - - Named Procedures as new command - - - proc __dictargs::method__ *name* *argspec* *body* - - - proc __clay::dialect::Push__ *class* - - - proc __clay::dialect::Peek__ - - - proc __clay::dialect::Pop__ - - - proc __clay::dialect::create__ *name* ?*parent* ____? - - This proc will generate a namespace, a "mother of all classes", and a - rudimentary set of policies for this dialect\. - - - proc __clay::dialect::NSNormalize__ *namespace* *qualname* - - Support commands; not intended to be called directly\. - - - proc __clay::dialect::DefineThunk__ *target* ?*args*? - - - proc __clay::dialect::Canonical__ *namespace* *NSpace* *class* - - - proc __clay::dialect::Define__ *namespace* *class* ?*args*? - - Implementation of the languages' define command - - - proc __clay::dialect::Aliases__ *namespace* ?*args*? - - - proc __clay::dialect::SuperClass__ *namespace* ?*args*? - - - proc __clay::dynamic\_methods__ *class* - - - proc __clay::dynamic\_methods\_class__ *thisclass* - - - proc __clay::define::Array__ *name* ?*values* ____? - - New OO Keywords for clay - - - proc __clay::define::Delegate__ *name* *info* - - An annotation that objects of this class interact with delegated methods\. - The annotation is intended to be a dictionary, and the only reserved key is - *description*, a human readable description\. - - - proc __clay::define::constructor__ *arglist* *rawbody* - - - proc __clay::define::Class\_Method__ *name* *arglist* *body* - - Specify the a method for the class object itself, instead of for objects of - the class - - - proc __clay::define::class\_method__ *name* *arglist* *body* - - And alias to the new Class\_Method keyword - - - proc __clay::define::clay__ ?*args*? - - - proc __clay::define::destructor__ *rawbody* - - - proc __clay::define::Dict__ *name* ?*values* ____? - - - proc __clay::define::Option__ *name* ?*args*? - - Define an option for the class - - - proc __clay::define::Method__ *name* *argstyle* *argspec* *body* - - - proc __clay::define::Option\_Class__ *name* ?*args*? - - Define a class of options All field / value pairs will be be inherited by an - option that specify *name* as it class field\. - - - proc __clay::define::Variable__ *name* ?*default* ____? - - This keyword can also be expressed: - - property variable NAME {default DEFAULT} - - Variables registered in the variable property are also initialized \(if - missing\) when the object changes class via the *morph* method\. - - - proc __clay::ensemble\_methodbody__ *ensemble* *einfo* - - Produce the body of an ensemble's public dispatch method ensemble is the - name of the the ensemble\. einfo is a dictionary of methods for the ensemble, - and each value is a script to execute on dispatch - - Example: - - ::clay::ensemble_methodbody foo { - bar {tailcall my Foo_bar {*}$args} - baz {tailcall my Foo_baz {*}$args} - clock {return [clock seconds]} - default {puts "You gave me $method"} - } - - - proc __clay::define::Ensemble__ *rawmethod* ?*args*? - - - proc __clay::event::cancel__ *self* ?*task* __\*__? - - Cancel a scheduled event - - - proc __clay::event::generate__ *self* *event* ?*args*? - - Generate an event Adds a subscription mechanism for objects to see who has - recieved this event and prevent spamming or infinite recursion - - - proc __clay::event::nextid__ - - - proc __clay::event::Notification\_list__ *self* *event* ?*stackvar* ____? - - Called recursively to produce a list of who recieves notifications - - - proc __clay::event::notify__ *rcpt* *sender* *event* *eventinfo* - - Final delivery to intended recipient object - - - proc __clay::event::process__ *self* *handle* *script* - - Evaluate an event script in the global namespace - - - proc __clay::event::schedule__ *self* *handle* *interval* *script* - - Schedule an event to occur later - - - proc __clay::event::subscribe__ *self* *who* *event* - - Subscribe an object to an event pattern - - - proc __clay::event::unsubscribe__ *self* ?*args*? - - Unsubscribe an object from an event pattern - - - proc __clay::singleton__ *name* *script* - - An object which is intended to be it's own class\. - -# Classes - -## Class clay::class - -__Methods__ - - - method __clay ancestors__ - - Return this class and all ancestors in search order\. - - - method __clay dump__ - - Return a complete dump of this object's clay data, but only this object's - clay data\. - - - method __clay find__ *path* ?__path\.\.\.__? - - Pull a chunk of data from the clay system\. If the last element of *path* - is a branch, returns a recursive merge of all data from this object and it's - constituent classes of the data in that branch\. If the last element is a - leaf, search this object for a matching leaf, or search all constituent - classes for a matching leaf and return the first value found\. If no value is - found, returns an empty string\. If a branch is returned the topmost \. entry - is omitted\. - - - method __clay get__ *path* ?__path\.\.\.__? - - Pull a chunk of data from the class's clay system\. If no value is found, - returns an empty string\. If a branch is returned the topmost \. entry is - omitted\. - - - method __clay GET__ *path* ?__path\.\.\.__? - - Pull a chunk of data from the class's clay system\. If no value is found, - returns an empty string\. - - - method __clay merge__ *dict* ?__dict\.\.\.__? - - Recursively merge the dictionaries given into the object's local clay - storage\. - - - method __clay replace__ *dictionary* - - Replace the contents of the internal clay storage with the dictionary given\. - - - method __clay search__ *path* ?__path\.\.\.__? - - Return the first matching value for the path in either this class's clay - data or one of its ancestors - - - method __clay set__ *path* ?__path\.\.\.__? *value* - - Merge the conents of __value__ with the object's clay storage at - __path__\. - -## Class clay::object - -clay::object This class is inherited by all classes that have options\. - -__Methods__ - - - method __clay ancestors__ - - Return the class this object belongs to, all classes mixed into this object, - and all ancestors of those classes in search order\. - - - method __clay cache__ *path* *value* - - Store VALUE in such a way that request in SEARCH for PATH will always return - it until the cache is flushed - - - method __clay cget__ *field* - - Pull a value from either the object's clay structure or one of its - constituent classes that matches the field name\. The order of search us: - - 1\. The as a value in local dict variable config - - 2\. The as a value in local dict variable clay - - 3\. As a leaf in any ancestor as a root of the clay tree - - 4\. As a leaf in any ancestor as __const__ *field* - - 5\. As a leaf in any ancestor as __option__ *field* __default__ - - - method __clay delegate__ ?*stub*? ?*object*? - - Introspect or control method delegation\. With no arguments, the method will - return a key/value list of stubs and objects\. With just the *stub* - argument, the method will return the object \(if any\) attached to the stub\. - With a *stub* and an *object* this command will forward all calls to the - method *stub* to the *object*\. - - - method __clay dump__ - - Return a complete dump of this object's clay data, as well as the data from - all constituent classes recursively blended in\. - - - method __clay ensemble\_map__ - - Return a dictionary describing the method ensembles to be assembled for this - object - - - method __clay eval__ *script* - - Evaluated a script in the namespace of this object - - - method __clay evolve__ - - Trigger the __InitializePublic__ private method - - - method __clay exists__ *path* ?__path\.\.\.__? - - Returns 1 if *path* exists in either the object's clay data\. Values - greater than one indicate the element exists in one of the object's - constituent classes\. A value of zero indicates the path could not be found\. - - - method __clay flush__ - - Wipe any caches built by the clay implementation - - - method __clay forward__ *method* *object* - - A convenience wrapper for - - oo::objdefine [self] forward {*}$args - - - method __clay get__ *path* ?__path\.\.\.__? - - Pull a chunk of data from the clay system\. If the last element of *path* - is a branch \(ends in a slash /\), returns a recursive merge of all data from - this object and it's constituent classes of the data in that branch\. If the - last element is a leaf, search this object for a matching leaf, or search - all constituent classes for a matching leaf and return the first value - found\. If no value is found, returns an empty string\. - - - method __clay leaf__ *path* ?__path\.\.\.__? - - A modified get which is tailored to pull only leaf elements - - - method __clay merge__ *dict* ?__dict\.\.\.__? - - Recursively merge the dictionaries given into the object's local clay - storage\. - - - method __clay mixin__ *class* ?__class\.\.\.__? - - Perform \[oo::objdefine \[self\] mixin\] on this object, with a few additional - rules: Prior to the call, for any class was previously mixed in, but not in - the new result, execute the script registered to mixin/ unmap\-script \(if - given\.\) For all new classes, that were not present prior to this call, after - the native TclOO mixin is invoked, execute the script registered to mixin/ - map\-script \(if given\.\) Fall all classes that are now present and “mixed inâ€, - execute the script registered to mixin/ react\-script \(if given\.\) - - - method __clay mixinmap__ ?*stub*? ?*classes*? - - With no arguments returns the map of stubs and classes mixed into the - current object\. When only stub is given, returns the classes mixed in on - that stub\. When stub and classlist given, replace the classes currently on - that stub with the given classes and invoke clay mixin on the new matrix of - mixed in classes\. - - - method __clay provenance__ *path* ?__path\.\.\.__? - - Return either __self__ if that path exists in the current object, or - return the first class \(if any\) along the clay search path which contains - that element\. - - - method __clay replace__ *dictionary* - - Replace the contents of the internal clay storage with the dictionary given\. - - - method __clay search__ *path* *valuevar* *isleafvar* - - Return true, and set valuevar to the value and isleafar to true for false if - PATH was found in the cache\. - - - method __clay source__ *filename* - - Source the given filename within the object's namespace - - - method __clay set__ *path* ?__path\.\.\.__? *value* - - Merge the conents of __value__ with the object's clay storage at - __path__\. - - - method __InitializePublic__ - - Instantiate variables\. Called on object creation and during clay mixin\. - -# AUTHORS - -Sean Woods - -[mailto:](mailto:) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *oo* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), [oo](\.\./\.\./\.\./\.\./index\.md\#oo) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2018 Sean Woods DELETED embedded/md/tcllib/files/modules/clock/iso8601.md Index: embedded/md/tcllib/files/modules/clock/iso8601.md ================================================================== --- embedded/md/tcllib/files/modules/clock/iso8601.md +++ embedded/md/tcllib/files/modules/clock/iso8601.md @@ -1,142 +0,0 @@ - -[//000000001]: # (clock\_iso8601 \- Date/Time Utilities) -[//000000002]: # (Generated from file 'iso8601\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (clock\_iso8601\(n\) 0\.1 tcllib "Date/Time Utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -clock\_iso8601 \- Parsing ISO 8601 dates/times - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Date formats](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require clock::iso8601 ?0\.1? - -[__::clock::iso8601 parse\_date__ *date* *options\.\.\.*](#1) -[__::clock::iso8601 parse\_time__ *time* *options\.\.\.*](#2) - -# DESCRIPTION - -This package provides functionality to parse dates and times in ISO 8601 format\. - - - __::clock::iso8601 parse\_date__ *date* *options\.\.\.* - - This command parses an ISO8601 date string in an unknown variant and returns - the given date/time in seconds since epoch\. - - The acceptable options are __\-base__, __\-gmt__, __\-locale__, and - __\-timezone__ of the builtin command __clock scan__\. - - - __::clock::iso8601 parse\_time__ *time* *options\.\.\.* - - This command parses a full ISO8601 timestamp string \(date and time\) in an - unknown variant and returns the given time in seconds since epoch\. - - The acceptable options are __\-base__, __\-gmt__, __\-locale__, and - __\-timezone__ of the builtin command __clock scan__\. - -# Date formats - -The commands accept the following 23 date formats: - - (year)-(month)-(day) - (year)(month)(day) - (year)-(day in year) - (year)(day in year) - (year in century)-(month)-(day) - (year)-(month) Day defaults to the 1st of the month - (year in century)(month)(day) - (year in century)-(day in year) - (year in century)(day in year) - --(month)-(day) Year defaults to the current year - --(month)(day) Year defaults to the current year - --(day in year) Year defaults to the current year - ---(day) Year defaults to the current year, month to current month - (fiscal year)-W(week)-(wday) - (fiscal year)W(week)-(wday) - (fiscal year in century)-W(week)-(wday) - (fiscal year in century)W(week)(wday) - (fiscal year)-W(week) Weekday defaults to monday - (fiscal year)W(week) Weekday defaults to monday - -W(week)-(wday) Year defaults to current fiscal year - -W(week)(wday) Year defaults to current fiscal year - (wday) Year defaults to current fiscal year, week to current week - (year) Month defaults to january, day to 1st of the month - -The possible parts/fields in the above, and their meanings, are: - - - year - - Year with century, 4 digits - - - month - - Month in year, 2 digits - - - day - - Day in month, 2 digits\. - - - year in century - - Year without century, 2 digits - - - day in year - - Day in year, 3 digits - - - fiscal year - - ISO 8601 fiscal year with century, 4 digits - - - fiscal year in century - - ISO 8601 fiscal year without century, 2 digits - - - week - - ISO 8601 week number - - - wday - - Week day, 1 digit, Monday \(1\) to Sunday \(7,0\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *clock::iso8601* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/clock/rfc2822.md Index: embedded/md/tcllib/files/modules/clock/rfc2822.md ================================================================== --- embedded/md/tcllib/files/modules/clock/rfc2822.md +++ embedded/md/tcllib/files/modules/clock/rfc2822.md @@ -1,63 +0,0 @@ - -[//000000001]: # (clock\_rfc2822 \- Date/Time Utilities) -[//000000002]: # (Generated from file 'rfc2822\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (clock\_rfc2822\(n\) 0\.1 tcllib "Date/Time Utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -clock\_rfc2822 \- Parsing RFC 2822 dates/times - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require clock::rfc2822 ?0\.1? - -[__::clock::rfc2822 parse\_date__ *date*](#1) - -# DESCRIPTION - -This package provides functionality to parse dates in RFC 2822 format\. - - - __::clock::rfc2822 parse\_date__ *date* - - This command parses an RFC2822 date string and returns the given date in - seconds since epoch\. An error is thrown if the command is unable to parse - the date\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *clock::rfc2822* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/cmdline/cmdline.md Index: embedded/md/tcllib/files/modules/cmdline/cmdline.md ================================================================== --- embedded/md/tcllib/files/modules/cmdline/cmdline.md +++ embedded/md/tcllib/files/modules/cmdline/cmdline.md @@ -1,238 +0,0 @@ - -[//000000001]: # (cmdline \- Command line and option processing) -[//000000002]: # (Generated from file 'cmdline\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (cmdline\(n\) 1\.5 tcllib "Command line and option processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -cmdline \- Procedures to process command lines and options\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [::argv handling](#section2) - - - [API](#section3) - - - [Error Codes](#subsection1) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require cmdline ?1\.3\.3? - -[__::cmdline::getopt__ *argvVar* *optstring* *optVar* *valVar*](#1) -[__::cmdline::getKnownOpt__ *argvVar* *optstring* *optVar* *valVar*](#2) -[__::cmdline::getoptions__ *arglistVar* *optlist* ?*usage*?](#3) -[__::cmdline::getKnownOptions__ *arglistVar* *optlist* ?*usage*?](#4) -[__::cmdline::usage__ *optlist* ?*usage*?](#5) -[__::cmdline::getfiles__ *patterns* *quiet*](#6) -[__::cmdline::getArgv0__](#7) - -# DESCRIPTION - -This package provides commands to parse command lines and options\. - -# ::argv handling - -One of the most common variables this package will be used with is -__::argv__, which holds the command line of the current application\. This -variable has a companion __::argc__ which is initialized to the number of -elements in __::argv__ at the beginning of the application\. - -The commands in this package will *not* modify the __::argc__ companion -when called with __::argv__\. Keeping the value consistent, if such is -desired or required, is the responsibility of the caller\. - -# API - - - __::cmdline::getopt__ *argvVar* *optstring* *optVar* *valVar* - - This command works in a fashion like the standard C based __getopt__ - function\. Given an option string and a pointer to an array of args this - command will process the first argument and return info on how to proceed\. - The command returns 1 if an option was found, 0 if no more options were - found, and \-1 if an error occurred\. - - *argvVar* contains the name of the list of arguments to process\. If - options are found the list is modified and the processed arguments are - removed from the start of the list\. - - *optstring* contains a list of command options that the application will - accept\. If the option ends in "\.arg" the command will use the next argument - as an argument to the option, or extract it from the current argument, if it - is of the form "option=value"\. Otherwise the option is a boolean that is set - to 1 if present\. - - *optVar* refers to the variable the command will store the found option - into \(without the leading '\-' and without the \.arg extension\)\. - - *valVar* refers to the variable to store either the value for the - specified option into upon success or an error message in the case of - failure\. The stored value comes from the command line for \.arg options, - otherwise the value is 1\. - - - __::cmdline::getKnownOpt__ *argvVar* *optstring* *optVar* *valVar* - - Like __::cmdline::getopt__, but ignores any unknown options in the - input\. - - - __::cmdline::getoptions__ *arglistVar* *optlist* ?*usage*? - - Processes the set of command line options found in the list variable named - by *arglistVar* and fills in defaults for those not specified\. This also - generates an error message that lists the allowed flags if an incorrect flag - is specified\. The optional *usage*\-argument contains a string to include - in front of the generated message\. If not present it defaults to "options:"\. - - *argvVar* contains the name of the list of arguments to process\. If - options are found the list is modified and the processed arguments are - removed from the start of the list\. - - *optlist* contains a list of lists where each element specifies an option - in the form: *flag* *default* *comment*\. - - If *flag* ends in "\.arg" then the value is taken from the command line\. - Otherwise it is a boolean and appears in the result if present on the - command line\. If *flag* ends in "\.secret", it will not be displayed in the - usage\. - - The options __\-?__, __\-help__, and __\-\-__ are implicitly - understood\. The first two abort option processing by throwing an error and - force the generation of the usage message, whereas the the last aborts - option processing without an error, leaving all arguments coming after for - regular processing, even if starting with a dash\. - - The result of the command is a dictionary mapping all options to their - values, be they user\-specified or defaults\. - - - __::cmdline::getKnownOptions__ *arglistVar* *optlist* ?*usage*? - - Like __::cmdline::getoptions__, but ignores any unknown options in the - input\. - - - __::cmdline::usage__ *optlist* ?*usage*? - - Generates and returns an error message that lists the allowed flags\. - *optlist* is defined as for __::cmdline::getoptions__\. The optional - *usage*\-argument contains a string to include in front of the generated - message\. If not present it defaults to "options:"\. - - - __::cmdline::getfiles__ *patterns* *quiet* - - Given a list of file *patterns* this command computes the set of valid - files\. On windows, file globbing is performed on each argument\. On Unix, - only file existence is tested\. If a file argument produces no valid files, a - warning is optionally generated \(set *quiet* to true\)\. - - This code also uses the full path for each file\. If not given it prepends - the current working directory to the filename\. This ensures that these files - will never conflict with files in a wrapped zip file\. The last sentence - refers to the pro\-tools\. - - - __::cmdline::getArgv0__ - - This command returns the "sanitized" version of *argv0*\. It will strip off - the leading path and removes the extension "\.bin"\. The latter is used by the - pro\-apps because they must be wrapped by a shell script\. - -## Error Codes - -Starting with version 1\.5 all errors thrown by the package have a proper -__::errorCode__ for use with Tcl's __[try](\.\./try/tcllib\_try\.md)__ -command\. This code always has the word __CMDLINE__ as its first element\. - -# EXAMPLES - - package require Tcl 8.5 - package require try ;# Tcllib. - package require cmdline 1.5 ;# First version with proper error-codes. - - # Notes: - # - Tcl 8.6+ has 'try' as a builtin command and therefore does not - # need the 'try' package. - # - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'. - # This then requires a dedicated test (if) on the contents of - # ::errorCode to separate the CMDLINE USAGE signal from actual errors. - - set options { - {a "set the atime only"} - {m "set the mtime only"} - {c "do not create non-existent files"} - {r.arg "" "use time from ref_file"} - {t.arg -1 "use specified time"} - } - set usage ": MyCommandName \[options] filename ...\noptions:" - - try { - array set params [::cmdline::getoptions argv $options $usage] - - # Note: argv is modified now. The recognized options are - # removed from it, leaving the non-option arguments behind. - } trap {CMDLINE USAGE} {msg o} { - # Trap the usage signal, print the message, and exit the application. - # Note: Other errors are not caught and passed through to higher levels! - puts $msg - exit 1 - } - - if { $params(a) } { set set_atime "true" } - set has_t [expr {$params(t) != -1}] - set has_r [expr {[string length $params(r)] > 0}] - if {$has_t && $has_r} { - return -code error "Cannot specify both -r and -t" - } elseif {$has_t} { - ... - } - -This example, taken \(and slightly modified\) from the package -__[fileutil](\.\./fileutil/fileutil\.md)__, shows how to use cmdline\. -First, a list of options is created, then the 'args' list is passed to cmdline -for processing\. Subsequently, different options are checked to see if they have -been passed to the script, and what their value is\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *cmdline* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[argument processing](\.\./\.\./\.\./\.\./index\.md\#argument\_processing), -[argv](\.\./\.\./\.\./\.\./index\.md\#argv), [argv0](\.\./\.\./\.\./\.\./index\.md\#argv0), -[cmdline processing](\.\./\.\./\.\./\.\./index\.md\#cmdline\_processing), [command -line processing](\.\./\.\./\.\./\.\./index\.md\#command\_line\_processing) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/comm/comm.md Index: embedded/md/tcllib/files/modules/comm/comm.md ================================================================== --- embedded/md/tcllib/files/modules/comm/comm.md +++ embedded/md/tcllib/files/modules/comm/comm.md @@ -1,1109 +0,0 @@ - -[//000000001]: # (comm \- Remote communication) -[//000000002]: # (Generated from file 'comm\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 1995\-1998 The Open Group\. All Rights Reserved\.) -[//000000004]: # (Copyright © 2003\-2004 ActiveState Corporation\.) -[//000000005]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000006]: # (comm\(n\) 4\.6\.3 tcllib "Remote communication") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -comm \- A remote communication facility for Tcl \(8\.3 and later\) - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#subsection1) - - - [Eval Semantics](#subsection2) - - - [Multiple Channels](#subsection3) - - - [Channel Configuration](#subsection4) - - - [Id/port Assignments](#subsection5) - - - [Execution Environment](#subsection6) - - - [Remote Interpreters](#subsection7) - - - [Closing Connections](#subsection8) - - - [Callbacks](#subsection9) - - - [Unsupported](#subsection10) - - - [Security](#subsection11) - - - [Blocking Semantics](#subsection12) - - - [Asynchronous Result Generation](#subsection13) - - - [Compatibility](#subsection14) - - - [TLS Security Considerations](#section2) - - - [Author](#section3) - - - [License](#section4) - - - [Bugs](#section5) - - - [On Using Old Versions Of Tcl](#section6) - - - [Related Work](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require comm ?4\.6\.3? - -[__::comm::comm send__ ?\-async? ?\-command *callback*? *id* *cmd* ?*arg arg \.\.\.*?](#1) -[__::comm::comm self__](#2) -[__::comm::comm interps__](#3) -[__::comm::comm connect__ ?*id*?](#4) -[__::comm::comm new__ *chan* ?*name value \.\.\.*?](#5) -[__::comm::comm channels__](#6) -[__::comm::comm config__](#7) -[__::comm::comm config__ *name*](#8) -[__::comm::comm config__ ?*name* *value* *\.\.\.*?](#9) -[__::comm::comm shutdown__ *id*](#10) -[__::comm::comm abort__](#11) -[__::comm::comm destroy__](#12) -[__::comm::comm hook__ *event* ?__\+__? ?*script*?](#13) -[__::comm::comm remoteid__](#14) -[__::comm::comm\_send__](#15) -[__::comm::comm return\_async__](#16) -[__$future__ __return__ ?__\-code__ *code*? ?*value*?](#17) -[__$future__ __configure__ ?__\-command__ ?*cmdprefix*??](#18) -[__$future__ __cget__ __\-command__](#19) - -# DESCRIPTION - -The __comm__ command provides an inter\-interpreter remote execution facility -much like Tk's __send\(n\)__, except that it uses sockets rather than the X -server for the communication path\. As a result, __comm__ works with multiple -interpreters, works on Windows and Macintosh systems, and provides control over -the remote execution path\. - -These commands work just like __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ and -__winfo interps__ : - - ::comm::comm send ?-async? id cmd ?arg arg ...? - ::comm::comm interps - -This is all that is really needed to know in order to use __comm__ - -## Commands - -The package initializes __::comm::comm__ as the default *chan*\. - -__comm__ names communication endpoints with an *id* unique to each -machine\. Before sending commands, the *id* of another interpreter is needed\. -Unlike Tk's send, __comm__ doesn't implicitly know the *id*'s of all the -interpreters on the system\. The following four methods make up the basic -__comm__ interface\. - - - __::comm::comm send__ ?\-async? ?\-command *callback*? *id* *cmd* ?*arg arg \.\.\.*? - - This invokes the given command in the interpreter named by *id*\. The - command waits for the result and remote errors are returned unless the - __\-async__ or __\-command__ option is given\. If __\-async__ is - given, send returns immediately and there is no further notification of - result\. If __\-command__ is used, *callback* specifies a command to - invoke when the result is received\. These options are mutually exclusive\. - The callback will receive arguments in the form *\-option value*, suitable - for __array set__\. The options are: *\-id*, the comm id of the - interpreter that received the command; *\-serial*, a unique serial for each - command sent to a particular comm interpreter; *\-chan*, the comm channel - name; *\-code*, the result code of the command; *\-errorcode*, the - errorcode, if any, of the command; *\-errorinfo*, the errorinfo, if any, of - the command; and *\-result*, the return value of the command\. If connection - is lost before a reply is received, the callback will be invoked with a - connection lost message with \-code equal to \-1\. When __\-command__ is - used, the command returns the unique serial for the command\. - - - __::comm::comm self__ - - Returns the *id* for this channel\. - - - __::comm::comm interps__ - - Returns a list of all the remote *id*'s to which this channel is - connected\. __comm__ learns a new remote *id* when a command is first - issued it, or when a remote *id* first issues a command to this comm - channel\. __::comm::comm ids__ is an alias for this method\. - - - __::comm::comm connect__ ?*id*? - - Whereas __::comm::comm send__ will automatically connect to the given - *id*, this forces a connection to a remote *id* without sending a - command\. After this, the remote *id* will appear in __::comm::comm - interps__\. - -## Eval Semantics - -The evaluation semantics of __::comm::comm send__ are intended to match Tk's -__[send](\.\./\.\./\.\./\.\./index\.md\#send)__ *exactly*\. This means that -__comm__ evaluates arguments on the remote side\. - -If you find that __::comm::comm send__ doesn't work for a particular -command, try the same thing with Tk's send and see if the result is different\. -If there is a problem, please report it\. For instance, there was had one report -that this command produced an error\. Note that the equivalent -__[send](\.\./\.\./\.\./\.\./index\.md\#send)__ command also produces the same -error\. - - % ::comm::comm send id llength {a b c} - wrong # args: should be "llength list" - % send name llength {a b c} - wrong # args: should be "llength list" - -The __eval__ hook \(described below\) can be used to change from -__[send](\.\./\.\./\.\./\.\./index\.md\#send)__'s double eval semantics to single -eval semantics\. - -## Multiple Channels - -More than one __comm__ channel \(or *listener*\) can be created in each Tcl -interpreter\. This allows flexibility to create full and restricted channels\. For -instance, *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* scripts are specific to the -channel they are defined against\. - - - __::comm::comm new__ *chan* ?*name value \.\.\.*? - - This creates a new channel and Tcl command with the given channel name\. This - new command controls the new channel and takes all the same arguments as - __::comm::comm__\. Any remaining arguments are passed to the - __config__ method\. The fully qualified channel name is returned\. - - - __::comm::comm channels__ - - This lists all the channels allocated in this Tcl interpreter\. - -The default configuration parameters for a new channel are: - - "-port 0 -local 1 -listen 0 -silent 0" - -The default channel __::comm::comm__ is created with: - - "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0" - -## Channel Configuration - -The __config__ method acts similar to __fconfigure__ in that it sets or -queries configuration variables associated with a channel\. - - - __::comm::comm config__ - - - __::comm::comm config__ *name* - - - __::comm::comm config__ ?*name* *value* *\.\.\.*? - - When given no arguments, __config__ returns a list of all variables and - their value With one argument, __config__ returns the value of just that - argument\. With an even number of arguments, the given variables are set to - the given values\. - -These configuration variables can be changed \(descriptions of them are elsewhere -in this manual page\): - - - __\-listen__ ?*0|1*? - - - __\-local__ ?*0|1*? - - - __\-port__ ?*port*? - - - __\-silent__ ?*0|1*? - - - __\-socketcmd__ ?*commandname*? - - - __\-interp__ ?*interpreter*? - - - __\-events__ ?*eventlist*? - -These configuration variables are read only: - - - __\-chan__ *chan* - - - __\-serial__ *n* - - - __\-socket__ sock*In* - -When __config__ changes the parameters of an existing channel \(with the -exception of __\-interp__ and __\-events__\), it closes and reopens the -listening socket\. An automatically assigned channel *id* will change when this -happens\. Recycling the socket is done by invoking __::comm::comm abort__, -which causes all active sends to terminate\. - -## Id/port Assignments - -__comm__ uses a TCP port for endpoint *id*\. The __interps__ \(or -__ids__\) method merely lists all the TCP ports to which the channel is -connected\. By default, each channel's *id* is randomly assigned by the -operating system \(but usually starts at a low value around 1024 and increases -each time a new socket is opened\)\. This behavior is accomplished by giving the -__\-port__ config option a value of 0\. Alternately, a specific TCP port -number may be provided for a given channel\. As a special case, comm contains -code to allocate a a high\-numbered TCP port \(>10000\) by using __\-port \{\}__\. -Note that a channel won't be created and initialized unless the specific port -can be allocated\. - -As a special case, if the channel is configured with __\-listen 0__, then it -will not create a listening socket and will use an id of __0__ for itself\. -Such a channel is only good for outgoing connections \(although once a connection -is established, it can carry send traffic in both directions\)\. As another -special case, if the channel is configured with __\-silent 0__, then the -listening side will ignore connection attempts where the protocol negotiation -phase failed, instead of throwing an error\. - -## Execution Environment - -A communication channel in its default configuration will use the current -interpreter for the execution of all received scripts, and of the event scripts -associated with the various hooks\. - -This insecure setup can be changed by the user via the two options -__\-interp__, and __\-events__\. - -When __\-interp__ is set all received scripts are executed in the slave -interpreter specified as the value of the option\. This interpreter is expected -to exist before configuration\. I\.e\. it is the responsibility of the user to -create it\. However afterward the communication channel takes ownership of this -interpreter, and will destroy it when the communication channel is destroyed\. -Note that reconfiguration of the communication channel to either a different -interpreter or the empty string will release the ownership *without* -destroying the previously configured interpreter\. The empty string has a special -meaning, it restores the default behaviour of executing received scripts in the -current interpreter\. - -*Also of note* is that replies and callbacks \(a special form of reply\) are -*not* considered as received scripts\. They are trusted, part of the internal -machinery of comm, and therefore always executed in the current interpreter\. - -Even if an interpreter has been configured as the execution environment for -received scripts the event scripts associated with the various hooks will by -default still be executed in the current interpreter\. To change this use the -option __\-events__ to declare a list of the events whose scripts should be -executed in the declared interpreter as well\. The contents of this option are -ignored if the communication channel is configured to execute received scripts -in the current interpreter\. - -## Remote Interpreters - -By default, each channel is restricted to accepting connections from the local -system\. This can be overridden by using the __\-local 0__ configuration -option For such channels, the *id* parameter takes the form *\{ id host \}*\. - -*WARNING*: The *host* must always be specified in the same form \(e\.g\., as -either a fully qualified domain name, plain hostname or an IP address\)\. - -## Closing Connections - -These methods give control over closing connections: - - - __::comm::comm shutdown__ *id* - - This closes the connection to *id*, aborting all outstanding commands in - progress\. Note that nothing prevents the connection from being immediately - reopened by another incoming or outgoing command\. - - - __::comm::comm abort__ - - This invokes shutdown on all open connections in this comm channel\. - - - __::comm::comm destroy__ - - This aborts all connections and then destroys the this comm channel itself, - including closing the listening socket\. Special code allows the default - __::comm::comm__ channel to be closed such that the __::comm::comm__ - command it is not destroyed\. Doing so closes the listening socket, - preventing both incoming and outgoing commands on the channel\. This sequence - reinitializes the default channel: - - "::comm::comm destroy; ::comm::comm new ::comm::comm" - -When a remote connection is lost \(because the remote exited or called -__shutdown__\), __comm__ can invoke an application callback\. This can be -used to cleanup or restart an ancillary process, for instance\. See the *lost* -callback below\. - -## Callbacks - -This is a mechanism for setting hooks for particular events: - - - __::comm::comm hook__ *event* ?__\+__? ?*script*? - - This uses a syntax similar to Tk's - __[bind](\.\./\.\./\.\./\.\./index\.md\#bind)__ command\. Prefixing *script* - with a __\+__ causes the new script to be appended\. Without this, a new - *script* replaces any existing script\. When invoked without a script, no - change is made\. In all cases, the new hook script is returned by the - command\. - - When an *event* occurs, the *script* associated with it is evaluated - with the listed variables in scope and available\. The return code \(*not* - the return value\) of the script is commonly used decide how to further - process after the hook\. - - Common variables include: - - * __chan__ - - the name of the comm channel \(and command\) - - * __id__ - - the id of the remote in question - - * __fid__ - - the file id for the socket of the connection - -These are the defined *events*: - - - __connecting__ - - Variables: __chan__, __id__ - - This hook is invoked before making a connection to the remote named in - *id*\. An error return \(via - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__\) will abort the connection - attempt with the error\. Example: - - % ::comm::comm hook connecting { - if {[string match {*[02468]} $id]} { - error "Can't connect to even ids" - } - } - % ::comm::comm send 10000 puts ok - Connect to remote failed: Can't connect to even ids - % - - - __connected__ - - Variables: __chan__, __fid__, __id__, __host__, and - __port__\. - - This hook is invoked immediately after making a remote connection to *id*, - allowing arbitrary authentication over the socket named by *fid*\. An error - return \(via __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ \) will close the - connection with the error\. *host* and *port* are merely extracted from - the *id*; changing any of these will have no effect on the connection, - however\. It is also possible to substitute and replace *fid*\. - - - __incoming__ - - Variables: __chan__, __fid__, __addr__, and __remport__\. - - Hook invoked when receiving an incoming connection, allowing arbitrary - authentication over socket named by *fid*\. An error return \(via - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__\) will close the connection - with the error\. Note that the peer is named by *remport* and *addr* but - that the remote *id* is still unknown\. Example: - - ::comm::comm hook incoming { - if {[string match 127.0.0.1 $addr]} { - error "I don't talk to myself" - } - } - - - __eval__ - - Variables: __chan__, __id__, __cmd__, and __buffer__\. - - This hook is invoked after collecting a complete script from a remote but - *before* evaluating it\. This allows complete control over the processing - of incoming commands\. *cmd* contains either __send__ or __async__\. - *buffer* holds the script to evaluate\. At the time the hook is called, - *$chan remoteid* is identical in value to *id*\. - - By changing *buffer*, the hook can change the script to be evaluated\. The - hook can short circuit evaluation and cause a value to be immediately - returned by using __[return](\.\./\.\./\.\./\.\./index\.md\#return)__ - *result* \(or, from within a procedure, __return \-code return__ - *result*\)\. An error return \(via - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__\) will return an error - result, as is if the script caused the error\. Any other return will evaluate - the script in *buffer* as normal\. For compatibility with 3\.2, - __break__ and __return \-code break__ *result* is supported, acting - similarly to __return \{\}__ and __return \-code return__ *result*\. - - Examples: - - 1. augmenting a command - - % ::comm::comm send [::comm::comm self] pid - 5013 - % ::comm::comm hook eval {puts "going to execute $buffer"} - % ::comm::comm send [::comm::comm self] pid - going to execute pid - 5013 - - 1. short circuiting a command - - % ::comm::comm hook eval {puts "would have executed $buffer"; return 0} - % ::comm::comm send [::comm::comm self] pid - would have executed pid - 0 - - 1. Replacing double eval semantics - - % ::comm::comm send [::comm::comm self] llength {a b c} - wrong # args: should be "llength list" - % ::comm::comm hook eval {return [uplevel #0 $buffer]} - return [uplevel #0 $buffer] - % ::comm::comm send [::comm::comm self] llength {a b c} - 3 - - 1. Using a slave interpreter - - % interp create foo - % ::comm::comm hook eval {return [foo eval $buffer]} - % ::comm::comm send [::comm::comm self] set myvar 123 - 123 - % set myvar - can't read "myvar": no such variable - % foo eval set myvar - 123 - - 1. Using a slave interpreter \(double eval\) - - % ::comm::comm hook eval {return [eval foo eval $buffer]} - - 1. Subverting the script to execute - - % ::comm::comm hook eval { - switch -- $buffer { - a {return A-OK} - b {return B-OK} - default {error "$buffer is a no-no"} - } - } - % ::comm::comm send [::comm::comm self] pid - pid is a no-no - % ::comm::comm send [::comm::comm self] a - A-OK - - - __reply__ - - Variables: __chan__, __id__, __buffer__, __ret__, and - __return\(\)__\. - - This hook is invoked after collecting a complete reply script from a remote - but *before* evaluating it\. This allows complete control over the - processing of replies to sent commands\. The reply *buffer* is in one of - the following forms - - * return result - - * return \-code code result - - * return \-code code \-errorinfo info \-errorcode ecode msg - - For safety reasons, this is decomposed\. The return result is in *ret*, and - the return switches are in the return array: - - * *return\(\-code\)* - - * *return\(\-errorinfo\)* - - * *return\(\-errorcode\)* - - Any of these may be the empty string\. Modifying these four variables can - change the return value, whereas modifying *buffer* has no effect\. - - - __callback__ - - Variables: __chan__, __id__, __buffer__, __ret__, and - __return\(\)__\. - - Similar to *reply*, but used for callbacks\. - - - __lost__ - - Variables: __chan__, __id__, and __reason__\. - - This hook is invoked when the connection to __id__ is lost\. Return value - \(or thrown error\) is ignored\. *reason* is an explanatory string indicating - why the connection was lost\. Example: - - ::comm::comm hook lost { - global myvar - if {$myvar(id) == $id} { - myfunc - return - } - } - -## Unsupported - -These interfaces may change or go away in subsequence releases\. - - - __::comm::comm remoteid__ - - Returns the *id* of the sender of the last remote command executed on this - channel\. If used by a proc being invoked remotely, it must be called before - any events are processed\. Otherwise, another command may get invoked and - change the value\. - - - __::comm::comm\_send__ - - Invoking this procedure will substitute the Tk - __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ and __winfo interps__ - commands with these equivalents that use __::comm::comm__\. - - proc send {args} { - eval ::comm::comm send $args - } - rename winfo tk_winfo - proc winfo {cmd args} { - if {![string match in* $cmd]} { - return [eval [list tk_winfo $cmd] $args] - } - return [::comm::comm interps] - } - -## Security - -Starting with version 4\.6 of the package an option __\-socketcmd__ is -supported, allowing the user of a comm channel to specify which command to use -when opening a socket\. Anything which is API\-compatible with the builtin -__::socket__ \(the default\) can be used\. - -The envisioned main use is the specification of the __tls::socket__ command, -see package __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the -communication\. - - # Load and initialize tls - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create secured comm channel - ::comm::comm new SECURE -socketcmd tls::socket -listen 1 - ... - -The sections [Execution Environment](#subsection6) and -[Callbacks](#subsection9) are also relevant to the security of the system, -providing means to restrict the execution to a specific environment, perform -additional authentication, and the like\. - -## Blocking Semantics - -There is one outstanding difference between __comm__ and -__[send](\.\./\.\./\.\./\.\./index\.md\#send)__\. When blocking in a synchronous -remote command, __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ uses an internal C -hook \(Tk\_RestrictEvents\) to the event loop to look ahead for send\-related events -and only process those without processing any other events\. In contrast, -__comm__ uses the __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ command as -a semaphore to indicate the return message has arrived\. The difference is that a -synchronous __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ will block the -application and prevent all events \(including window related ones\) from being -processed, while a synchronous __::comm::comm send__ will block the -application but still allow other events to get processed\. In particular, -__after idle__ handlers will fire immediately when comm blocks\. - -What can be done about this? First, note that this behavior will come from any -code using __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ to block and wait for -an event to occur\. At the cost of multiple channel support, __comm__ could -be changed to do blocking I/O on the socket, giving send\-like blocking -semantics\. However, multiple channel support is a very useful feature of comm -that it is deemed too important to lose\. The remaining approaches involve a new -loadable module written in C \(which is somewhat against the philosophy of -__comm__\) One way would be to create a modified version of the -__[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ command that allow the event -flags passed to Tcl\_DoOneEvent to be specified\. For __comm__, just the -TCL\_FILE\_EVENTS would be processed\. Another way would be to implement a -mechanism like Tk\_RestrictEvents, but apply it to the Tcl event loop \(since -__comm__ doesn't require Tk\)\. One of these approaches will be available in a -future __comm__ release as an optional component\. - -## Asynchronous Result Generation - -By default the result returned by a remotely invoked command is the result sent -back to the invoker\. This means that the result is generated synchronously, and -the server handling the call is blocked for the duration of the command\. - -While this is tolerable as long as only short\-running commands are invoked on -the server long\-running commands, like database queries make this a problem\. One -command can prevent the processing requests of all other clients for an -arbitrary period of time\. - -Before version 4\.5 of comm the only solution was to rewrite the server command -to use the Tcl builtin command __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__, -or one of its relatives like __tkwait__, to open a new event loop which -processes requests while the long\-running operation is executed\. This however -has its own perils, as this makes it possible to both overflow the Tcl stack -with a large number of event loop, and to have a newer requests block the return -of older ones, as the eventloop have to be unwound in the order of their -creation\. - -The proper solution is to have the invoked command indicate to __comm__ that -it cannot or will not deliver an immediate, synchronous result, but will do so -later\. At that point the framework can put sending the actual result on hold and -continue processing requests using the main event loop\. No blocking, no nesting -of event loops\. At some future date the long running operation delivers the -result to comm, via the future object, which is then forwarded to the invoker as -usual\. - -The necessary support for this solution has been added to comm since version -4\.5, in the form of the new method __return\_async__\. - - - __::comm::comm return\_async__ - - This command is used by a remotely invoked script to notify the comm channel - which invoked it that the result to send back to the invoker is not - generated synchronously\. If this command is not called the default/standard - behaviour of comm is to send the synchronously generated result of the - script itself to the invoker\. - - The result of __return\_async__ is an object\. This object, called a - *future* is where the result of the script has to be delivered to when it - becomes ready\. When that happens it will take all the necessary actions to - deliver the result to the invoker of the script, and then destroy itself\. - Should comm have lost the connection to the invoker while the result is - being computed the future will not try to deliver the result it got, but - just destroy itself\. The future can be configured with a command to call - when the invoker is lost\. This enables the user to implement an early abort - of the long\-running operation, should this be supported by it\. - - An example: - - # Procedure invoked by remote clients to run database operations. - proc select {sql} { - # Signal the async generation of the result - - set future [::comm::comm return_async] - - # Generate an async db operation and tell it where to deliver the result. - - set query [db query -command [list $future return] $sql] - - # Tell the database system which query to cancel if the connection - # goes away while it is running. - - $future configure -command [list db cancel $query] - - # Note: The above will work without problem only if the async - # query will nover run its completion callback immediately, but - # only from the eventloop. Because otherwise the future we wish to - # configure may already be gone. If that is possible use 'catch' - # to prevent the error from propagating. - return - } - - The API of a future object is: - - * __$future__ __return__ ?__\-code__ *code*? ?*value*? - - Use this method to tell the future that long\-running operation has - completed\. Arguments are an optional return value \(defaults to the empty - string\), and the Tcl return code \(defaults to OK\)\. - - The future will deliver this information to invoker, if the connection - was not lost in the meantime, and then destroy itself\. If the connection - was lost it will do nothing but destroy itself\. - - * __$future__ __configure__ ?__\-command__ ?*cmdprefix*?? - - * __$future__ __cget__ __\-command__ - - These methods allow the user to retrieve and set a command to be called - if the connection the future belongs to has been lost\. - -## Compatibility - -__comm__ exports itself as a package\. The package version number is in the -form *major \. minor*, where the major version will only change when a -non\-compatible change happens to the API or protocol\. Minor bug fixes and -changes will only affect the minor version\. To load __comm__ this command is -usually used: - - package require comm 3 - -Note that requiring no version \(or a specific version\) can also be done\. - -The revision history of __comm__ includes these releases: - - - 4\.6\.3 - - Fixed ticket \[ced0d60fc9\]\. Added proper detection of eof on a socket, - properly closing it\. - - - 4\.6\.2 - - Fixed bugs 2972571 and 3066872, the first a misdetection of quoted brace - after double backslash, the other a blocking gets making for an obvious - \(hinsight\) DoS attack on comm channels\. - - - 4\.6\.1 - - Changed the implementation of __comm::commCollect__ to emulate lindex's - pre\-Tcl 8 behaviour, i\.e\. it was given the ability to parse out the first - word of a list, even if the whole buffer is not a well\-formed list\. Without - this change the first word could only be extracted if the whole buffer was a - well\-formed list \(ever since Tcl 8\), and in a ver\-high\-load situation, i\.e\. - a server sending lots and/or large commands very fast, this may never - happen, eventually crashing the receiver when it runs out of memory\. With - the change the receiver is always able to process the first word when it - becomes well\-formed, regardless of the structure of the remainder of the - buffer\. - - - 4\.6 - - Added the option __\-socketcmd__ enabling users to override how a socket - is opened\. The envisioned main use is the specification of the - __tls::socket__ command, see package - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\. - - - 4\.5\.7 - - Changed handling of ports already in use to provide a proper error message\. - - - 4\.5\.6 - - Bugfix in the replacement for - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__, made robust against of - variable names containing spaces\. - - - 4\.5\.5 - - Bugfix in the handling of hooks, typo in variable name\. - - - 4\.5\.4 - - Bugfix in the handling of the result received by the __send__ method\. - Replaced an *after idle unset result* with an immediate __unset__, - with the information saved to a local variable\. - - The __after idle__ can spill into a forked child process if there is no - event loop between its setup and the fork\. This may bork the child if the - next event loop is the __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ of - __comm__'s __send__ a few lines above the __after idle__, and - the child used the same serial number for its next request\. In that case the - parent's __after idle unset__ will delete the very array element the - child is waiting for, unlocking the - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__, causing it to access a now - missing array element, instead of the expected result\. - - - 4\.5\.3 - - Bugfixes in the wrappers for the builtin - __[update](\.\./\.\./\.\./\.\./index\.md\#update)__ and - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ commands\. - - - 4\.5\.2 - - Bugfix in the wrapper for the builtin - __[update](\.\./\.\./\.\./\.\./index\.md\#update)__ command\. - - - 4\.5\.1 - - Bugfixes in the handling of \-interp for regular scripts\. The handling of the - buffer was wrong for scripts which are a single statement as list\. Fixed - missing argument to new command __commSendReply__, introduced by version - 4\.5\. Affected debugging\. - - - 4\.5 - - New server\-side feature\. The command invoked on the server can now switch - comm from the standard synchronous return of its result to an asynchronous - \(defered\) return\. Due to the use of snit to implement the *future* objects - used by this feature from this version on comm requires at least Tcl 8\.3 to - run\. Please read the section [Asynchronous Result - Generation](#subsection13) for more details\. - - - 4\.4\.1 - - Bugfix in the execution of hooks\. - - - 4\.4 - - Bugfixes in the handling of \-interp for regular and hook scripts\. Bugfixes - in channel cleanup\. - - - 4\.3\.1 - - Introduced \-interp and \-events to enable easy use of a slave interp for - execution of received scripts, and of event scripts\. - - - 4\.3 - - Bugfixes, and introduces \-silent to allow the user to force the - server/listening side to silently ignore connection attempts where the - protocol negotiation failed\. - - - 4\.2 - - Bugfixes, and most important, switched to utf\-8 as default encoding for full - i18n without any problems\. - - - 4\.1 - - Rewrite of internal code to remove old pseudo\-object model\. Addition of send - \-command asynchronous callback option\. - - - 4\.0 - - Per request by John LoVerso\. Improved handling of error for async invoked - commands\. - - - 3\.7 - - Moved into tcllib and placed in a proper namespace\. - - - 3\.6 - - A bug in the looking up of the remoteid for a executed command could be - triggered when the connection was closed while several asynchronous sends - were queued to be executed\. - - - 3\.5 - - Internal change to how reply messages from a - __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ are handled\. Reply messages - are now decoded into the *value* to pass to - __[return](\.\./\.\./\.\./\.\./index\.md\#return)__; a new return statement is - then cons'd up to with this value\. Previously, the return code was passed in - from the remote as a command to evaluate\. Since the wire protocol has not - changed, this is still the case\. Instead, the reply handling code decodes - the __reply__ message\. - - - 3\.4 - - Added more source commentary, as well as documenting config variables in - this man page\. Fixed bug were loss of connection would give error about a - variable named __pending__ rather than the message about the lost - connection\. __comm ids__ is now an alias for __comm interps__ - \(previously, it an alias for __comm chans__\)\. Since the method - invocation change of 3\.0, break and other exceptional conditions were not - being returned correctly from __comm send__\. This has been fixed by - removing the extra level of indirection into the internal procedure - __commSend__\. Also added propagation of the *errorCode* variable\. This - means that these commands return exactly as they would with - __[send](\.\./\.\./\.\./\.\./index\.md\#send)__: - - comm send id break - catch {comm send id break} - comm send id expr 1 / 0 - - Added a new hook for reply messages\. Reworked method invocation to avoid the - use of comm:\* procedures; this also cut the invocation time down by 40%\. - Documented __comm config__ \(as this manual page still listed the defunct - __comm init__\!\) - - - 3\.3 - - Some minor bugs were corrected and the documentation was cleaned up\. Added - some examples for hooks\. The return semantics of the __eval__ hook were - changed\. - - - 3\.2 - - A new wire protocol, version 3, was added\. This is backwards compatible with - version 2 but adds an exchange of supported protocol versions to allow - protocol negotiation in the future\. Several bugs with the hook - implementation were fixed\. A new section of the man page on blocking - semantics was added\. - - - 3\.1 - - All the documented hooks were implemented\. __commLostHook__ was removed\. - A bug in __comm new__ was fixed\. - - - 3\.0 - - This is a new version of __comm__ with several major changes\. There is a - new way of creating the methods available under the __comm__ command\. - The __comm init__ method has been retired and is replaced by __comm - configure__ which allows access to many of the well\-defined internal - variables\. This also generalizes the options available to __comm new__\. - Finally, there is now a protocol version exchanged when a connection is - established\. This will allow for future on\-wire protocol changes\. Currently, - the protocol version is set to 2\. - - - 2\.3 - - __comm ids__ was renamed to __comm channels__\. General support for - __comm hook__ was fully implemented, but only the *lost* hook exists, - and it was changed to follow the general hook API\. __commLostHook__ was - unsupported \(replaced by __comm hook lost__\) and __commLost__ was - removed\. - - - 2\.2 - - The *died* hook was renamed *lost*, to be accessed by - __commLostHook__ and an early implementation of __comm lost hook__\. - As such, __commDied__ is now __commLost__\. - - - 2\.1 - - Unsupported method __comm remoteid__ was added\. - - - 2\.0 - - __comm__ has been rewritten from scratch \(but is fully compatible with - Comm 1\.0, without the requirement to use obTcl\)\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Author - -John LoVerso, John@LoVerso\.Southborough\.MA\.US - -*http://www\.opengroup\.org/~loverso/tcl\-tk/\#comm* - -# License - -Please see the file *comm\.LICENSE* that accompanied this source, or -[http://www\.opengroup\.org/www/dist\_client/caubweb/COPYRIGHT\.free\.html](http://www\.opengroup\.org/www/dist\_client/caubweb/COPYRIGHT\.free\.html)\. - -This license for __comm__, new as of version 3\.2, allows it to be used for -free, without any licensing fee or royalty\. - -# Bugs - - - If there is a failure initializing a channel created with __::comm::comm - new__, then the channel should be destroyed\. Currently, it is left in an - inconsistent state\. - - - There should be a way to force a channel to quiesce when changing the - configuration\. - -The following items can be implemented with the existing hooks and are listed -here as a reminder to provide a sample hook in a future version\. - - - Allow easier use of a slave interp for actual command execution \(especially - when operating in "not local" mode\)\. - - - Add host list \(xhost\-like\) or "magic cookie" \(xauth\-like\) authentication to - initial handshake\. - -The following are outstanding todo items\. - - - Add an interp discovery and name\->port mapping\. This is likely to be in a - separate, optional nameserver\. \(See also the related work, below\.\) - - - Fix the *\{id host\}* form so as not to be dependent upon canonical - hostnames\. This requires fixes to Tcl to resolve hostnames\! - -This man page is bigger than the source file\. - -# On Using Old Versions Of Tcl - -Tcl7\.5 under Windows contains a bug that causes the interpreter to hang when EOF -is reached on non\-blocking sockets\. This can be triggered with a command such as -this: - - "comm send $other exit" - -Always make sure the channel is quiescent before closing/exiting or use at least -Tcl7\.6 under Windows\. - -Tcl7\.6 on the Mac contains several bugs\. It is recommended you use at least -Tcl7\.6p2\. - -Tcl8\.0 on UNIX contains a socket bug that can crash Tcl\. It is recommended you -use Tcl8\.0p1 \(or Tcl7\.6p2\)\. - -# Related Work - -Tcl\-DP provides an RPC\-based remote execution interface, but is a compiled Tcl -extension\. See -[http://www\.cs\.cornell\.edu/Info/Projects/zeno/Projects/Tcl\-DP\.html](http://www\.cs\.cornell\.edu/Info/Projects/zeno/Projects/Tcl\-DP\.html)\. - -Michael Doyle has code that implements the Tcl\-DP RPC -interface using standard Tcl sockets, much like __comm__\. The DpTcl package -is available at -[http://chiselapp\.com/user/gwlester/repository/DpTcl](http://chiselapp\.com/user/gwlester/repository/DpTcl)\. - -Andreas Kupries uses __comm__ and -has built a simple nameserver as part of his Pool library\. See -[http://www\.purl\.org/net/akupries/soft/pool/index\.htm](http://www\.purl\.org/net/akupries/soft/pool/index\.htm)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *comm* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -send\(n\) - -# KEYWORDS - -[comm](\.\./\.\./\.\./\.\./index\.md\#comm), -[communication](\.\./\.\./\.\./\.\./index\.md\#communication), -[ipc](\.\./\.\./\.\./\.\./index\.md\#ipc), -[message](\.\./\.\./\.\./\.\./index\.md\#message), [remote -communication](\.\./\.\./\.\./\.\./index\.md\#remote\_communication), [remote -execution](\.\./\.\./\.\./\.\./index\.md\#remote\_execution), -[rpc](\.\./\.\./\.\./\.\./index\.md\#rpc), [secure](\.\./\.\./\.\./\.\./index\.md\#secure), -[send](\.\./\.\./\.\./\.\./index\.md\#send), -[socket](\.\./\.\./\.\./\.\./index\.md\#socket), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 1995\-1998 The Open Group\. All Rights Reserved\. -Copyright © 2003\-2004 ActiveState Corporation\. -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/comm/comm_wire.md Index: embedded/md/tcllib/files/modules/comm/comm_wire.md ================================================================== --- embedded/md/tcllib/files/modules/comm/comm_wire.md +++ embedded/md/tcllib/files/modules/comm/comm_wire.md @@ -1,216 +0,0 @@ - -[//000000001]: # (comm\_wire \- Remote communication) -[//000000002]: # (Generated from file 'comm\_wire\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Docs\. Andreas Kupries ) -[//000000004]: # (comm\_wire\(n\) 3 tcllib "Remote communication") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -comm\_wire \- The comm wire protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Wire Protocol Version 3](#section2) - - - [Basic Layer](#subsection1) - - - [Basic Message Layer](#subsection2) - - - [Negotiation Messages \- Initial Handshake](#subsection3) - - - [Script/Command Messages](#subsection4) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require comm - -# DESCRIPTION - -The __[comm](comm\.md)__ command provides an inter\-interpreter remote -execution facility much like Tk's __send\(n\)__, except that it uses sockets -rather than the X server for the communication path\. As a result, -__[comm](comm\.md)__ works with multiple interpreters, works on Windows -and Macintosh systems, and provides control over the remote execution path\. - -This document contains a specification of the various versions of the wire -protocol used by comm internally for the communication between its endpoints\. It -has no relevance to users of __[comm](comm\.md)__, only to developers who -wish to modify the package, write a compatible facility in a different language, -or some other facility based on the same protocol\. - -# Wire Protocol Version 3 - -## Basic Layer - -The basic encoding for *all* data is UTF\-8\. Because of this binary data, -including the NULL character, can be sent over the wire as is, without the need -for armoring it\. - -## Basic Message Layer - -On top of the [Basic Layer](#subsection1) we have a *message oriented* -exchange of data\. The totality of all characters written to the channel is a Tcl -list, with each element a separate -*[message](\.\./\.\./\.\./\.\./index\.md\#message)*, each itself a list\. The -messages in the overall list are separated by EOL\. Note that EOL characters can -occur within the list as well\. They can be distinguished from the -message\-separating EOL by the fact that the data from the beginning up to their -location is not a valid Tcl list\. - -EOL is signaled through the linefeed character, i\.e __LF__, or, hex -__0x0a__\. This is following the unix convention for line\-endings\. - -As a list each message is composed of *words*\. Their meaning depends on when -the message was sent in the overall exchange\. This is described in the upcoming -sections\. - -## Negotiation Messages \- Initial Handshake - -The command protocol is defined like this: - - - The first message send by a client to a server, when opening the connection, - contains two words\. The first word is a list as well, and contains the - versions of the wire protocol the client is willing to accept, with the most - preferred version first\. The second word is the TCP port the client is - listening on for connections to itself\. The value __0__ is used here to - signal that the client will not listen for connections, i\.e\. that it is - purely for sending commands, and not receiving them\. - - - The first message sent by the server to the client, in response to the - message above contains only one word\. This word is a list, containing the - string __vers__ as its first element, and the version of the wire - protocol the server has selected from the offered versions as the second\. - -## Script/Command Messages - -All messages coming after the [initial handshake](#subsection3) consist of -three words\. These are an instruction, a transaction id, and the payload\. The -valid instructions are shown below\. The transaction ids are used by the client -to match any incoming replies to the command messages it sent\. This means that a -server has to copy the transaction id from a command message to the reply it -sends for that message\. - - - __send__ - - - __async__ - - - __command__ - - The payload is the Tcl script to execute on the server\. It is actually a - list containing the script fragments\. These fragment are - __concat__enated together by the server to form the full script to - execute on the server side\. This emulates the Tcl "eval" semantics\. In most - cases it is best to have only one word in the list, a list containing the - exact command\. - - Examples: - - (a) {send 1 {{array get tcl_platform}}} - (b) {send 1 {array get tcl_platform}} - (c) {send 1 {array {get tcl_platform}}} - - are all valid representations of the same command. They are - generated via - - (a') send {array get tcl_platform} - (b') send array get tcl_platform - (c') send array {get tcl_platform} - - respectively - - Note that \(a\), generated by \(a'\), is the usual form, if only single commands - are sent by the client\. For example constructed using - __[list](\.\./\.\./\.\./\.\./index\.md\#list)__, if the command contains - variable arguments\. Like - - send [list array get $the_variable] - - These three instructions all invoke the script on the server side\. Their - difference is in the treatment of result values, and thus determines if a - reply is expected\. - - * __send__ - - A reply is expected\. The sender is waiting for the result\. - - * __async__ - - No reply is expected, the sender has no interest in the result and is - not waiting for any\. - - * __command__ - - A reply is expected, but the sender is not waiting for it\. It has - arranged to get a process\-internal notification when the result arrives\. - - - __reply__ - - Like the previous three command, however the tcl script in the payload is - highly restricted\. It has to be a syntactically valid Tcl - __[return](\.\./\.\./\.\./\.\./index\.md\#return)__ command\. This contains - result code, value, error code, and error info\. - - Examples: - - {reply 1 {return -code 0 {}}} - {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *comm* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[comm](comm\.md) - -# KEYWORDS - -[comm](\.\./\.\./\.\./\.\./index\.md\#comm), -[communication](\.\./\.\./\.\./\.\./index\.md\#communication), -[ipc](\.\./\.\./\.\./\.\./index\.md\#ipc), -[message](\.\./\.\./\.\./\.\./index\.md\#message), [remote -communication](\.\./\.\./\.\./\.\./index\.md\#remote\_communication), [remote -execution](\.\./\.\./\.\./\.\./index\.md\#remote\_execution), -[rpc](\.\./\.\./\.\./\.\./index\.md\#rpc), [socket](\.\./\.\./\.\./\.\./index\.md\#socket) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2005 Docs\. Andreas Kupries DELETED embedded/md/tcllib/files/modules/control/control.md Index: embedded/md/tcllib/files/modules/control/control.md ================================================================== --- embedded/md/tcllib/files/modules/control/control.md +++ embedded/md/tcllib/files/modules/control/control.md @@ -1,190 +0,0 @@ - -[//000000001]: # (control \- Tcl Control Flow Commands) -[//000000002]: # (Generated from file 'control\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (control\(n\) 0\.1\.3 tcllib "Tcl Control Flow Commands") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -control \- Procedures for control flow structures\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [LIMITATIONS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require control ?0\.1\.3? - -[__control::control__ *command* *option* ?*arg arg \.\.\.*?](#1) -[__control::assert__ *expr* ?*arg arg \.\.\.*?](#2) -[__control::do__ *body* ?*option test*?](#3) -[__control::no\-op__ ?*arg arg \.\.\.*?](#4) - -# DESCRIPTION - -The __control__ package provides a variety of commands that provide -additional flow of control structures beyond the built\-in ones provided by Tcl\. -These are commands that in many programming languages might be considered -*keywords*, or a part of the language itself\. In Tcl, control flow structures -are just commands like everything else\. - -# COMMANDS - - - __control::control__ *command* *option* ?*arg arg \.\.\.*? - - The __control__ command is used as a configuration command for - customizing the other public commands of the control package\. The - *command* argument names the command to be customized\. The set of valid - *option* and subsequent arguments are determined by the command being - customized, and are documented with the command\. - - - __control::assert__ *expr* ?*arg arg \.\.\.*? - - When disabled, the __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ command - behaves exactly like the __[no\-op](\.\./\.\./\.\./\.\./index\.md\#no\_op)__ - command\. - - When enabled, the __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ command - evaluates *expr* as an expression \(in the same way that __expr__ - evaluates its argument\)\. If evaluation reveals that *expr* is not a valid - boolean expression \(according to \[__string is boolean \-strict__\]\), an - error is raised\. If *expr* evaluates to a true boolean value \(as - recognized by __if__\), then - __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ returns an empty string\. - Otherwise, the remaining arguments to - __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ are used to construct a - message string\. If there are no arguments, the message string is "assertion - failed: $expr"\. If there are arguments, they are joined by - __[join](\.\./\.\./\.\./\.\./index\.md\#join)__ to form the message string\. - The message string is then appended as an argument to a callback command, - and the completed callback command is evaluated in the global namespace\. - - The __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ command can be - customized by the __control__ command in two ways: - - \[__control::control assert enabled__ ?*boolean*?\] queries or sets - whether __control::assert__ is enabled\. When called without a - *boolean* argument, a boolean value is returned indicating whether the - __control::assert__ command is enabled\. When called with a valid boolean - value as the *boolean* argument, the __control::assert__ command is - enabled or disabled to match the argument, and an empty string is returned\. - - \[__control::control assert callback__ ?*command*?\] queries or sets the - callback command that will be called by an enabled - __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ on assertion failure\. When - called without a *command* argument, the current callback command is - returned\. When called with a *command* argument, that argument becomes the - new assertion failure callback command\. Note that an assertion failure - callback command is always defined, even when - __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ is disabled\. The default - callback command is \[__return \-code error__\]\. - - Note that __control::assert__ has been written so that in combination - with \[__namespace import__\], it is possible to use enabled - __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ commands in some - namespaces and disabled __[assert](\.\./\.\./\.\./\.\./index\.md\#assert)__ - commands in other namespaces at the same time\. This capability is useful so - that debugging efforts can be independently controlled module by module\. - - % package require control - % control::control assert enabled 1 - % namespace eval one namespace import ::control::assert - % control::control assert enabled 0 - % namespace eval two namespace import ::control::assert - % one::assert {1 == 0} - assertion failed: 1 == 0 - % two::assert {1 == 0} - - - __control::do__ *body* ?*option test*? - - The __[do](\.\./\.\./\.\./\.\./index\.md\#do)__ command evaluates the script - *body* repeatedly *until* the expression *test* becomes true or as - long as \(*while*\) *test* is true, depending on the value of *option* - being __until__ or __while__\. If *option* and *test* are omitted - the body is evaluated exactly once\. After normal completion, - __[do](\.\./\.\./\.\./\.\./index\.md\#do)__ returns an empty string\. - Exceptional return codes \(__break__, __continue__, - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__, etc\.\) during the evaluation - of *body* are handled in the same way the __while__ command handles - them, except as noted in [LIMITATIONS](#section3), below\. - - - __control::no\-op__ ?*arg arg \.\.\.*? - - The __[no\-op](\.\./\.\./\.\./\.\./index\.md\#no\_op)__ command takes any number - of arguments and does nothing\. It returns an empty string\. - -# LIMITATIONS - -Several of the commands provided by the __control__ package accept arguments -that are scripts to be evaluated\. Due to fundamental limitations of Tcl's -__catch__ and __[return](\.\./\.\./\.\./\.\./index\.md\#return)__ commands, it -is not possible for these commands to properly evaluate the command \[__return -\-code $code__\] within one of those script arguments for any value of *$code* -other than *ok*\. In this way, the commands of the __control__ package are -limited as compared to Tcl's built\-in control flow commands \(such as __if__, -__while__, etc\.\) and those control flow commands that can be provided by -packages coded in C\. An example of this difference: - - % package require control - % proc a {} {while 1 {return -code error a}} - % proc b {} {control::do {return -code error b} while 1} - % catch a - 1 - % catch b - 0 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *control* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -break, continue, expr, if, [join](\.\./\.\./\.\./\.\./index\.md\#join), namespace, -[return](\.\./\.\./\.\./\.\./index\.md\#return), -[string](\.\./\.\./\.\./\.\./index\.md\#string), while - -# KEYWORDS - -[assert](\.\./\.\./\.\./\.\./index\.md\#assert), -[control](\.\./\.\./\.\./\.\./index\.md\#control), [do](\.\./\.\./\.\./\.\./index\.md\#do), -[flow](\.\./\.\./\.\./\.\./index\.md\#flow), [no\-op](\.\./\.\./\.\./\.\./index\.md\#no\_op), -[structure](\.\./\.\./\.\./\.\./index\.md\#structure) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/coroutine/coro_auto.md Index: embedded/md/tcllib/files/modules/coroutine/coro_auto.md ================================================================== --- embedded/md/tcllib/files/modules/coroutine/coro_auto.md +++ embedded/md/tcllib/files/modules/coroutine/coro_auto.md @@ -1,99 +0,0 @@ - -[//000000001]: # (coroutine::auto \- Coroutine utilities) -[//000000002]: # (Generated from file 'coro\_auto\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010\-2014 Andreas Kupries ) -[//000000004]: # (coroutine::auto\(n\) 1\.1\.3 tcllib "Coroutine utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -coroutine::auto \- Automatic event and IO coroutine awareness - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require coroutine::auto 1\.1\.3 -package require coroutine 1\.1 - -# DESCRIPTION - -The __coroutine::auto__ package provides no commands or other directly -visible functionality\. Built on top of the package -__[coroutine](tcllib\_coroutine\.md)__, it intercepts various builtin -commands of the Tcl core to make any code using them coroutine\-oblivious, i\.e\. -able to run inside and outside of a coroutine without changes\. - -The commands so affected by this package are - - - __[after](\.\./\.\./\.\./\.\./index\.md\#after)__ - - - __[exit](\.\./\.\./\.\./\.\./index\.md\#exit)__ - - - __[gets](\.\./\.\./\.\./\.\./index\.md\#gets)__ - - - __[global](\.\./\.\./\.\./\.\./index\.md\#global)__ - - - __[read](\.\./\.\./\.\./\.\./index\.md\#read)__ - - - __[update](\.\./\.\./\.\./\.\./index\.md\#update)__ - - - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__ - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *coroutine* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[after](\.\./\.\./\.\./\.\./index\.md\#after), -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[coroutine](\.\./\.\./\.\./\.\./index\.md\#coroutine), -[events](\.\./\.\./\.\./\.\./index\.md\#events), -[exit](\.\./\.\./\.\./\.\./index\.md\#exit), [gets](\.\./\.\./\.\./\.\./index\.md\#gets), -[global](\.\./\.\./\.\./\.\./index\.md\#global), [green -threads](\.\./\.\./\.\./\.\./index\.md\#green\_threads), -[read](\.\./\.\./\.\./\.\./index\.md\#read), -[threads](\.\./\.\./\.\./\.\./index\.md\#threads), -[update](\.\./\.\./\.\./\.\./index\.md\#update), -[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait) - -# CATEGORY - -Coroutine - -# COPYRIGHT - -Copyright © 2010\-2014 Andreas Kupries DELETED embedded/md/tcllib/files/modules/coroutine/tcllib_coroutine.md Index: embedded/md/tcllib/files/modules/coroutine/tcllib_coroutine.md ================================================================== --- embedded/md/tcllib/files/modules/coroutine/tcllib_coroutine.md +++ embedded/md/tcllib/files/modules/coroutine/tcllib_coroutine.md @@ -1,168 +0,0 @@ - -[//000000001]: # (coroutine \- Coroutine utilities) -[//000000002]: # (Generated from file 'tcllib\_coroutine\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010\-2015 Andreas Kupries ) -[//000000004]: # (coroutine\(n\) 1\.2 tcllib "Coroutine utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -coroutine \- Coroutine based event and IO handling - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require coroutine 1\.2 - -[__coroutine::util after__ *delay*](#1) -[__coroutine::util await__ *varname*\.\.\.](#2) -[__coroutine::util create__ *arg*\.\.\.](#3) -[__coroutine::util exit__ ?*status*?](#4) -[__coroutine::util gets__ *chan* ?*varname*?](#5) -[__coroutine::util gets\_safety__ *chan* *limit* *varname*](#6) -[__coroutine::util global__ *varname*\.\.\.](#7) -[__coroutine::util read__ __\-nonewline__ *chan* ?*n*?](#8) -[__coroutine::util update__ ?__idletasks__?](#9) -[__coroutine::util vwait__ *varname*](#10) - -# DESCRIPTION - -The __coroutine__ package provides coroutine\-aware implementations of -various event\- and channel related commands\. It can be in multiple modes: - - 1. Call the commands through their ensemble, in code which is explicitly - written for use within coroutines\. - - 1. Import the commands into a namespace, either directly, or through - __namespace path__\. This allows the use from within code which is not - coroutine\-aware per se and restricted to specific namespaces\. - -A more agressive form of making code coroutine\-oblivious than point 2 above is -available through the package __[coroutine::auto](coro\_auto\.md)__, which -intercepts the relevant builtin commands and changes their implementation -dependending on the context they are run in, i\.e\. inside or outside of a -coroutine\. - -# API - -All the commands listed below are synchronous with respect to the coroutine -invoking them, i\.e\. this coroutine blocks until the result is available\. The -overall eventloop is not blocked however\. - - - __coroutine::util after__ *delay* - - This command delays the coroutine invoking it by *delay* milliseconds\. - - - __coroutine::util await__ *varname*\.\.\. - - This command is an extension form of the __coroutine::util vwait__ - command \(see below\) which waits on a write to one of many named namespace - variables\. - - - __coroutine::util create__ *arg*\.\.\. - - This command creates a new coroutine with an automatically assigned name and - causes it to run the code specified by the arguments\. - - - __coroutine::util exit__ ?*status*? - - This command exits the current coroutine, causing it to return *status*\. - If no status was specified the default *0* is returned\. - - - __coroutine::util gets__ *chan* ?*varname*? - - This command reads a line from the channel *chan* and returns it either as - its result, or, if a *varname* was specified, writes it to the named - variable and returns the number of characters read\. - - - __coroutine::util gets\_safety__ *chan* *limit* *varname* - - This command reads a line from the channel *chan* up to size *limit* and - stores the result in *varname*\. Of *limit* is reached before the set - first newline, an error is thrown\. The command returns the number of - characters read\. - - - __coroutine::util global__ *varname*\.\.\. - - This command imports the named global variables of the coroutine into the - current scope\. From the technical point of view these variables reside in - level __\#1__ of the Tcl stack\. I\.e\. these are not the regular global - variable in to the global namespace, and each coroutine can have their own - set, independent of all others\. - - - __coroutine::util read__ __\-nonewline__ *chan* ?*n*? - - This command reads *n* characters from the channel *chan* and returns - them as its result\. If *n* is not specified the command will read the - channel until EOF is reached\. - - - __coroutine::util update__ ?__idletasks__? - - This command causes the coroutine invoking it to run pending events or idle - handlers before proceeding\. - - - __coroutine::util vwait__ *varname* - - This command causes the coroutine calling it to wait for a write to the - named namespace variable *varname*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *coroutine* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[after](\.\./\.\./\.\./\.\./index\.md\#after), -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[coroutine](\.\./\.\./\.\./\.\./index\.md\#coroutine), -[events](\.\./\.\./\.\./\.\./index\.md\#events), -[exit](\.\./\.\./\.\./\.\./index\.md\#exit), [gets](\.\./\.\./\.\./\.\./index\.md\#gets), -[global](\.\./\.\./\.\./\.\./index\.md\#global), [green -threads](\.\./\.\./\.\./\.\./index\.md\#green\_threads), -[read](\.\./\.\./\.\./\.\./index\.md\#read), -[threads](\.\./\.\./\.\./\.\./index\.md\#threads), -[update](\.\./\.\./\.\./\.\./index\.md\#update), -[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait) - -# CATEGORY - -Coroutine - -# COPYRIGHT - -Copyright © 2010\-2015 Andreas Kupries DELETED embedded/md/tcllib/files/modules/counter/counter.md Index: embedded/md/tcllib/files/modules/counter/counter.md ================================================================== --- embedded/md/tcllib/files/modules/counter/counter.md +++ embedded/md/tcllib/files/modules/counter/counter.md @@ -1,281 +0,0 @@ - -[//000000001]: # (counter \- Counters and Histograms) -[//000000002]: # (Generated from file 'counter\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (counter\(n\) 2\.0\.4 tcllib "Counters and Histograms") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -counter \- Procedures for counters and histograms - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8 -package require counter ?2\.0\.4? - -[__::counter::init__ *tag args*](#1) -[__::counter::count__ *tag* ?*delta*? ?*instance*?](#2) -[__::counter::start__ *tag instance*](#3) -[__::counter::stop__ *tag instance*](#4) -[__::counter::get__ *tag args*](#5) -[__::counter::exists__ *tag*](#6) -[__::counter::names__](#7) -[__::counter::histHtmlDisplay__ *tag args*](#8) -[__::counter::reset__ *tag args*](#9) - -# DESCRIPTION - -The __counter__ package provides a counter facility and can compute -statistics and histograms over the collected data\. - - - __::counter::init__ *tag args* - - This defines a counter with the name *tag*\. The *args* determines the - characteristics of the counter\. The *args* are - - * __\-group__ *name* - - Keep a grouped counter where the name of the histogram bucket is passed - into __::counter::count__\. - - * __\-hist__ *bucketsize* - - Accumulate the counter into histogram buckets of size *bucketsize*\. - For example, if the samples are millisecond time values and - *bucketsize* is 10, then each histogram bucket represents time values - of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec, and so on\. - - * __\-hist2x__ *bucketsize* - - Accumulate the statistic into histogram buckets\. The size of the first - bucket is *bucketsize*, each other bucket holds values 2 times the - size of the previous bucket\. For example, if *bucketsize* is 10, then - each histogram bucket represents time values of 0 to 10 msec, 10 to 20 - msec, 20 to 40 msec, 40 to 80 msec, and so on\. - - * __\-hist10x__ *bucketsize* - - Accumulate the statistic into histogram buckets\. The size of the first - bucket is *bucketsize*, each other bucket holds values 10 times the - size of the previous bucket\. For example, if *bucketsize* is 10, then - each histogram bucket represents time values of 0 to 10 msec, 10 to 100 - msec, 100 to 1000 msec, and so on\. - - * __\-lastn__ *N* - - Save the last *N* values of the counter to maintain a "running - average" over the last *N* values\. - - * __\-timehist__ *secsPerMinute* - - Keep a time\-based histogram\. The counter is summed into a histogram - bucket based on the current time\. There are 60 per\-minute buckets that - have a size determined by *secsPerMinute*, which is normally 60, but - for testing purposes can be less\. Every "hour" \(i\.e\., 60 "minutes"\) the - contents of the per\-minute buckets are summed into the next hourly - bucket\. Every 24 "hours" the contents of the per\-hour buckets are summed - into the next daily bucket\. The counter package keeps all time\-based - histograms in sync, so the first *secsPerMinute* value seen by the - package is used for all subsequent time\-based histograms\. - - - __::counter::count__ *tag* ?*delta*? ?*instance*? - - Increment the counter identified by *tag*\. The default increment is 1, - although you can increment by any value, integer or real, by specifying - *delta*\. You must declare each counter with __::counter::init__ to - define the characteristics of counter before you start to use it\. If the - counter type is __\-group__, then the counter identified by *instance* - is incremented\. - - - __::counter::start__ *tag instance* - - Record the starting time of an interval\. The *tag* is the name of the - counter defined as a __\-hist__ value\-based histogram\. The *instance* - is used to distinguish this interval from any other intervals that might be - overlapping this one\. - - - __::counter::stop__ *tag instance* - - Record the ending time of an interval\. The delta time since the - corresponding __::counter::start__ call for *instance* is recorded in - the histogram identified by *tag*\. - - - __::counter::get__ *tag args* - - Return statistics about a counter identified by *tag*\. The *args* - determine what value to return: - - * __\-total__ - - Return the total value of the counter\. This is the default if *args* - is not specified\. - - * __\-totalVar__ - - Return the name of the total variable\. Useful for specifying with - \-textvariable in a Tk widget\. - - * __\-N__ - - Return the number of samples accumulated into the counter\. - - * __\-avg__ - - Return the average of samples accumulated into the counter\. - - * __\-avgn__ - - Return the average over the last *N* samples taken\. The *N* value is - set in the __::counter::init__ call\. - - * __\-hist__ *bucket* - - If *bucket* is specified, then the value in that bucket of the - histogram is returned\. Otherwise the complete histogram is returned in - array get format sorted by bucket\. - - * __\-histVar__ - - Return the name of the histogram array variable\. - - * __\-histHour__ - - Return the complete hourly histogram in array get format sorted by - bucket\. - - * __\-histHourVar__ - - Return the name of the hourly histogram array variable\. - - * __\-histDay__ - - Return the complete daily histogram in array get format sorted by - bucket\. - - * __\-histDayVar__ - - Return the name of the daily histogram array variable\. - - * __\-resetDate__ - - Return the clock seconds value recorded when the counter was last reset\. - - * __\-all__ - - Return an array get of the array used to store the counter\. This - includes the total, the number of samples \(N\), and any type\-specific - information\. This does not include the histogram array\. - - - __::counter::exists__ *tag* - - Returns 1 if the counter is defined\. - - - __::counter::names__ - - Returns a list of all counters defined\. - - - __::counter::histHtmlDisplay__ *tag args* - - Generate HTML to display a histogram for a counter\. The *args* control the - format of the display\. They are: - - * __\-title__ *string* - - Label to display above bar chart - - * __\-unit__ *unit* - - Specify __minutes__, __hours__, or __days__ for the - time\-base histograms\. For value\-based histograms, the *unit* is used - in the title\. - - * __\-images__ *url* - - URL of /images directory\. - - * __\-gif__ *filename* - - Image for normal histogram bars\. The *filename* is relative to the - __\-images__ directory\. - - * __\-ongif__ *filename* - - Image for the active histogram bar\. The *filename* is relative to the - __\-images__ directory\. - - * __\-max__ *N* - - Maximum number of value\-based buckets to display\. - - * __\-height__ *N* - - Pixel height of the highest bar\. - - * __\-width__ *N* - - Pixel width of each bar\. - - * __\-skip__ *N* - - Buckets to skip when labeling value\-based histograms\. - - * __\-format__ *string* - - Format used to display labels of buckets\. - - * __\-text__ *boolean* - - If 1, a text version of the histogram is dumped, otherwise a graphical - one is generated\. - - - __::counter::reset__ *tag args* - - Resets the counter with the name *tag* to an initial state\. The *args* - determine the new characteristics of the counter\. They have the same meaning - as described for __::counter::init__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *counter* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[counting](\.\./\.\./\.\./\.\./index\.md\#counting), -[histogram](\.\./\.\./\.\./\.\./index\.md\#histogram), -[statistics](\.\./\.\./\.\./\.\./index\.md\#statistics), -[tallying](\.\./\.\./\.\./\.\./index\.md\#tallying) - -# CATEGORY - -Data structures DELETED embedded/md/tcllib/files/modules/crc/cksum.md Index: embedded/md/tcllib/files/modules/crc/cksum.md ================================================================== --- embedded/md/tcllib/files/modules/crc/cksum.md +++ embedded/md/tcllib/files/modules/crc/cksum.md @@ -1,171 +0,0 @@ - -[//000000001]: # (cksum \- Cyclic Redundancy Checks) -[//000000002]: # (Generated from file 'cksum\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts) -[//000000004]: # (cksum\(n\) 1\.1\.4 tcllib "Cyclic Redundancy Checks") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -cksum \- Calculate a cksum\(1\) compatible checksum - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [OPTIONS](#section3) - - - [PROGRAMMING INTERFACE](#section4) - - - [EXAMPLES](#section5) - - - [AUTHORS](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require cksum ?1\.1\.4? - -[__::crc::cksum__ ?*\-format format*? ?*\-chunksize size*? \[ *\-channel chan* | *\-filename file* | *string* \]](#1) -[__::crc::CksumInit__](#2) -[__::crc::CksumUpdate__ *token* *data*](#3) -[__::crc::CksumFinal__ *token*](#4) - -# DESCRIPTION - -This package provides a Tcl implementation of the cksum\(1\) algorithm based upon -information provided at in the GNU implementation of this program as part of the -GNU Textutils 2\.0 package\. - -# COMMANDS - - - __::crc::cksum__ ?*\-format format*? ?*\-chunksize size*? \[ *\-channel chan* | *\-filename file* | *string* \] - - The command takes string data or a channel or file name and returns a - checksum value calculated using the __cksum\(1\)__ algorithm\. The result - is formatted using the *format*\(n\) specifier provided or as an unsigned - integer \(%u\) by default\. - -# OPTIONS - - - \-channel *name* - - Return a checksum for the data read from a channel\. The command will read - data from the channel until the __eof__ is true\. If you need to be able - to process events during this calculation see the [PROGRAMMING - INTERFACE](#section4) section - - - \-filename *name* - - This is a convenience option that opens the specified file, sets the - encoding to binary and then acts as if the *\-channel* option had been - used\. The file is closed on completion\. - - - \-format *string* - - Return the checksum using an alternative format template\. - -# PROGRAMMING INTERFACE - -The cksum package implements the checksum using a context variable to which -additional data can be added at any time\. This is expecially useful in an event -based environment such as a Tk application or a web server package\. Data to be -checksummed may be handled incrementally during a __fileevent__ handler in -discrete chunks\. This can improve the interactive nature of a GUI application -and can help to avoid excessive memory consumption\. - - - __::crc::CksumInit__ - - Begins a new cksum context\. Returns a token ID that must be used for the - remaining functions\. An optional seed may be specified if required\. - - - __::crc::CksumUpdate__ *token* *data* - - Add data to the checksum identified by token\. Calling *CksumUpdate $token - "abcd"* is equivalent to calling *CksumUpdate $token "ab"* followed by - *CksumUpdate $token "cb"*\. See [EXAMPLES](#section5)\. - - - __::crc::CksumFinal__ *token* - - Returns the checksum value and releases any resources held by this token\. - Once this command completes the token will be invalid\. The result is a 32 - bit integer value\. - -# EXAMPLES - - % crc::cksum "Hello, World!" - 2609532967 - - % crc::cksum -format 0x%X "Hello, World!" - 0x9B8A5027 - - % crc::cksum -file cksum.tcl - 1828321145 - - % set tok [crc::CksumInit] - % crc::CksumUpdate $tok "Hello, " - % crc::CksumUpdate $tok "World!" - % crc::CksumFinal $tok - 2609532967 - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *crc* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[crc32\(n\)](crc32\.md), [sum\(n\)](sum\.md) - -# KEYWORDS - -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), -[cksum](\.\./\.\./\.\./\.\./index\.md\#cksum), [crc](\.\./\.\./\.\./\.\./index\.md\#crc), -[crc32](\.\./\.\./\.\./\.\./index\.md\#crc32), [cyclic redundancy -check](\.\./\.\./\.\./\.\./index\.md\#cyclic\_redundancy\_check), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/crc/crc16.md Index: embedded/md/tcllib/files/modules/crc/crc16.md ================================================================== --- embedded/md/tcllib/files/modules/crc/crc16.md +++ embedded/md/tcllib/files/modules/crc/crc16.md @@ -1,184 +0,0 @@ - -[//000000001]: # (crc16 \- Cyclic Redundancy Checks) -[//000000002]: # (Generated from file 'crc16\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, 2017, Pat Thoyts) -[//000000004]: # (crc16\(n\) 1\.1\.4 tcllib "Cyclic Redundancy Checks") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -crc16 \- Perform a 16bit Cyclic Redundancy Check - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [OPTIONS](#section3) - - - [EXAMPLES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require crc16 ?1\.1\.4? - -[__::crc::crc16__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message*](#1) -[__::crc::crc16__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file*](#2) -[__::crc::crc\-ccitt__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message*](#3) -[__::crc::crc\-ccitt__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file*](#4) -[__::crc::xmodem__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message*](#5) -[__::crc::xmodem__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file*](#6) - -# DESCRIPTION - -This package provides a Tcl\-only implementation of the CRC algorithms based upon -information provided at http://www\.microconsultants\.com/tips/crc/crc\.txt There -are a number of permutations available for calculating CRC checksums and this -package can handle all of them\. Defaults are set up for the most common cases\. - -# COMMANDS - - - __::crc::crc16__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message* - - - __::crc::crc16__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file* - - - __::crc::crc\-ccitt__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message* - - - __::crc::crc\-ccitt__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file* - - - __::crc::xmodem__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? __\-\-__ *message* - - - __::crc::xmodem__ ?\-format *format*? ?\-seed *value*? ?\-implementation *procname*? \-filename *file* - - The command takes either string data or a file name and returns a checksum - value calculated using the CRC algorithm\. The command used sets up the CRC - polynomial, initial value and bit ordering for the desired standard checksum - calculation\. The result is formatted using the *format*\(n\) specifier - provided or as an unsigned integer \(%u\) by default\. - - A number of common polynomials are in use with the CRC algorithm and the - most commonly used of these are included in this package\. For convenience - each of these has a command alias in the crc namespace\. - - It is possible to implement the CRC\-32 checksum using this crc16 package as - the implementation is sufficiently generic to extend to 32 bit checksums\. As - an example this has been done already \- however this is not the fastest - method to implement this algorithm in Tcl and a separate - __[crc32](crc32\.md)__ package is available\. - -# OPTIONS - - - \-filename *name* - - Return a checksum for the file contents instead of for parameter data\. - - - \-format *string* - - Return the checksum using an alternative format template\. - - - \-seed *value* - - Select an alternative seed value for the CRC calculation\. The default is 0 - for the CRC16 calculation and 0xFFFF for the CCITT version\. This can be - useful for calculating the CRC for data structures without first converting - the whole structure into a string\. The CRC of the previous member can be - used as the seed for calculating the CRC of the next member\. It is also used - for accumulating a checksum from fragments of a large message \(or file\) - - - \-implementation *procname* - - This hook is provided to allow users to provide their own implementation - \(perhaps a C compiled extension\)\. The procedure specfied is called with two - parameters\. The first is the data to be checksummed and the second is the - seed value\. An integer is expected as the result\. - - The package provides some implementations of standard CRC polynomials for - the XMODEM, CCITT and the usual CRC\-16 checksum\. For convenience, additional - commands have been provided that make use of these implementations\. - - - \-\- - - Terminate option processing\. Please note that using the option termination - flag is important when processing data from parameters\. If the binary data - looks like one of the options given above then the data will be read as an - option if this marker is not included\. Always use the *\-\-* option - termination flag before giving the data argument\. - -# EXAMPLES - - % crc::crc16 -- "Hello, World!" - 64077 - - % crc::crc-ccitt -- "Hello, World!" - 26586 - - % crc::crc16 -format 0x%X -- "Hello, World!" - 0xFA4D - - % crc::crc16 -file crc16.tcl - 51675 - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *crc* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[cksum\(n\)](cksum\.md), [crc32\(n\)](crc32\.md), [sum\(n\)](sum\.md) - -# KEYWORDS - -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), -[cksum](\.\./\.\./\.\./\.\./index\.md\#cksum), [crc](\.\./\.\./\.\./\.\./index\.md\#crc), -[crc16](\.\./\.\./\.\./\.\./index\.md\#crc16), -[crc32](\.\./\.\./\.\./\.\./index\.md\#crc32), [cyclic redundancy -check](\.\./\.\./\.\./\.\./index\.md\#cyclic\_redundancy\_check), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2002, 2017, Pat Thoyts DELETED embedded/md/tcllib/files/modules/crc/crc32.md Index: embedded/md/tcllib/files/modules/crc/crc32.md ================================================================== --- embedded/md/tcllib/files/modules/crc/crc32.md +++ embedded/md/tcllib/files/modules/crc/crc32.md @@ -1,185 +0,0 @@ - -[//000000001]: # (crc32 \- Cyclic Redundancy Checks) -[//000000002]: # (Generated from file 'crc32\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts) -[//000000004]: # (crc32\(n\) 1\.3\.3 tcllib "Cyclic Redundancy Checks") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -crc32 \- Perform a 32bit Cyclic Redundancy Check - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [OPTIONS](#section3) - - - [PROGRAMMING INTERFACE](#section4) - - - [EXAMPLES](#section5) - - - [AUTHORS](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require crc32 ?1\.3\.3? - -[__::crc::crc32__ ?\-format *format*? ?\-seed *value*? \[ *\-channel chan* | *\-filename file* | *message* \]](#1) -[__::crc::Crc32Init__ ?*seed*?](#2) -[__::crc::Crc32Update__ *token* *data*](#3) -[__::crc::Crc32Final__ *token*](#4) - -# DESCRIPTION - -This package provides a Tcl implementation of the CRC\-32 algorithm based upon -information provided at http://www\.naaccr\.org/standard/crc32/document\.html If -either the __critcl__ package or the __Trf__ package are available then -a compiled version may be used internally to accelerate the checksum -calculation\. - -# COMMANDS - - - __::crc::crc32__ ?\-format *format*? ?\-seed *value*? \[ *\-channel chan* | *\-filename file* | *message* \] - - The command takes either string data or a channel or file name and returns a - checksum value calculated using the CRC\-32 algorithm\. The result is - formatted using the *format*\(n\) specifier provided\. The default is to - return the value as an unsigned integer \(format %u\)\. - -# OPTIONS - - - \-channel *name* - - Return a checksum for the data read from a channel\. The command will read - data from the channel until the __eof__ is true\. If you need to be able - to process events during this calculation see the [PROGRAMMING - INTERFACE](#section4) section - - - \-filename *name* - - This is a convenience option that opens the specified file, sets the - encoding to binary and then acts as if the *\-channel* option had been - used\. The file is closed on completion\. - - - \-format *string* - - Return the checksum using an alternative format template\. - - - \-seed *value* - - Select an alternative seed value for the CRC calculation\. The default is - 0xffffffff\. This can be useful for calculating the CRC for data structures - without first converting the whole structure into a string\. The CRC of the - previous member can be used as the seed for calculating the CRC of the next - member\. Note that the crc32 algorithm includes a final XOR step\. If - incremental processing is desired then this must be undone before using the - output of the algorithm as the seed for further processing\. A simpler - alternative is to use the [PROGRAMMING INTERFACE](#section4) which is - intended for this mode of operation\. - -# PROGRAMMING INTERFACE - -The CRC\-32 package implements the checksum using a context variable to which -additional data can be added at any time\. This is expecially useful in an event -based environment such as a Tk application or a web server package\. Data to be -checksummed may be handled incrementally during a __fileevent__ handler in -discrete chunks\. This can improve the interactive nature of a GUI application -and can help to avoid excessive memory consumption\. - - - __::crc::Crc32Init__ ?*seed*? - - Begins a new CRC32 context\. Returns a token ID that must be used for the - remaining functions\. An optional seed may be specified if required\. - - - __::crc::Crc32Update__ *token* *data* - - Add data to the checksum identified by token\. Calling *Crc32Update $token - "abcd"* is equivalent to calling *Crc32Update $token "ab"* followed by - *Crc32Update $token "cb"*\. See [EXAMPLES](#section5)\. - - - __::crc::Crc32Final__ *token* - - Returns the checksum value and releases any resources held by this token\. - Once this command completes the token will be invalid\. The result is a 32 - bit integer value\. - -# EXAMPLES - - % crc::crc32 "Hello, World!" - 3964322768 - - % crc::crc32 -format 0x%X "Hello, World!" - 0xEC4AC3D0 - - % crc::crc32 -file crc32.tcl - 483919716 - - % set tok [crc::Crc32Init] - % crc::Crc32Update $tok "Hello, " - % crc::Crc32Update $tok "World!" - % crc::Crc32Final $tok - 3964322768 - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *crc* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[cksum\(n\)](cksum\.md), [crc16\(n\)](crc16\.md), [sum\(n\)](sum\.md) - -# KEYWORDS - -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), -[cksum](\.\./\.\./\.\./\.\./index\.md\#cksum), [crc](\.\./\.\./\.\./\.\./index\.md\#crc), -[crc32](\.\./\.\./\.\./\.\./index\.md\#crc32), [cyclic redundancy -check](\.\./\.\./\.\./\.\./index\.md\#cyclic\_redundancy\_check), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/crc/sum.md Index: embedded/md/tcllib/files/modules/crc/sum.md ================================================================== --- embedded/md/tcllib/files/modules/crc/sum.md +++ embedded/md/tcllib/files/modules/crc/sum.md @@ -1,149 +0,0 @@ - -[//000000001]: # (sum \- Cyclic Redundancy Checks) -[//000000002]: # (Generated from file 'sum\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts ) -[//000000004]: # (sum\(n\) 1\.1\.2 tcllib "Cyclic Redundancy Checks") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -sum \- Calculate a sum\(1\) compatible checksum - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [OPTIONS](#section3) - - - [EXAMPLES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require sum ?1\.1\.2? - -[__::crc::sum__ ?*\-bsd* | *\-sysv*? ?*\-format fmt*? ?*\-chunksize size*? \[ *\-filename file* | *\-channel chan* | *string* \]](#1) - -# DESCRIPTION - -This package provides a Tcl\-only implementation of the sum\(1\) command which -calculates a 16 bit checksum value from the input data\. The BSD sum algorithm is -used by default but the SysV algorithm is also available\. - -# COMMANDS - - - __::crc::sum__ ?*\-bsd* | *\-sysv*? ?*\-format fmt*? ?*\-chunksize size*? \[ *\-filename file* | *\-channel chan* | *string* \] - - The command takes string data or a file name or a channel and returns a - checksum value calculated using the __sum\(1\)__ algorithm\. The result is - formatted using the *format*\(n\) specifier provided or as an unsigned - integer \(%u\) by default\. - -# OPTIONS - - - \-sysv - - The SysV algorithm is fairly naive\. The byte values are summed and any - overflow is discarded\. The lowest 16 bits are returned as the checksum\. - Input with the same content but different ordering will give the same - result\. - - - \-bsd - - This algorithm is similar to the SysV version but includes a bit rotation - step which provides a dependency on the order of the data values\. - - - \-filename *name* - - Return a checksum for the file contents instead of for parameter data\. - - - \-channel *chan* - - Return a checksum for the contents of the specified channel\. The channel - must be open for reading and should be configured for binary translation\. - The channel will no be closed on completion\. - - - \-chunksize *size* - - Set the block size used when reading data from either files or channels\. - This value defaults to 4096\. - - - \-format *string* - - Return the checksum using an alternative format template\. - -# EXAMPLES - - % crc::sum "Hello, World!" - 37287 - - % crc::sum -format 0x%X "Hello, World!" - 0x91A7 - - % crc::sum -file sum.tcl - 13392 - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *crc* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[cksum\(n\)](cksum\.md), [crc32\(n\)](crc32\.md), sum\(1\) - -# KEYWORDS - -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), -[cksum](\.\./\.\./\.\./\.\./index\.md\#cksum), [crc](\.\./\.\./\.\./\.\./index\.md\#crc), -[crc32](\.\./\.\./\.\./\.\./index\.md\#crc32), [cyclic redundancy -check](\.\./\.\./\.\./\.\./index\.md\#cyclic\_redundancy\_check), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[security](\.\./\.\./\.\./\.\./index\.md\#security), -[sum](\.\./\.\./\.\./\.\./index\.md\#sum) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/cron/cron.md Index: embedded/md/tcllib/files/modules/cron/cron.md ================================================================== --- embedded/md/tcllib/files/modules/cron/cron.md +++ embedded/md/tcllib/files/modules/cron/cron.md @@ -1,256 +0,0 @@ - -[//000000001]: # (cron \- cron) -[//000000002]: # (Generated from file 'cron\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2016\-2018 Sean Woods ) -[//000000004]: # (cron\(n\) 2\.1 tcllib "cron") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -cron \- Tool for automating the period callback of commands - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require cron ?2\.1? - -[__::cron::at__ *?processname?* *timecode* *command*](#1) -[__::cron::cancel__ *processname*](#2) -[__::cron::every__ *processname* *frequency* *command*](#3) -[__::cron::in__ *?processname?* *timecode* *command*](#4) -[__::cron::object\_coroutine__ *object* *coroutine* *?info?*](#5) -[__::cron::sleep__ *milliseconds*](#6) -[__::cron::task delete__ *process*](#7) -[__::cron::task exists__ *process*](#8) -[__::cron::task info__ *process*](#9) -[__::cron::task set__ *process* *field* *value* *?field\.\.\.?* *?value\.\.\.?*](#10) -[__::cron::wake__ *?who?*](#11) -[__::cron::clock\_step__ *milliseconds*](#12) -[__::cron::clock\_delay__ *milliseconds*](#13) -[__::cron::clock\_sleep__ *seconds* *?offset?*](#14) -[__::cron::clock\_set__ *newtime*](#15) - -# DESCRIPTION - -The __cron__ package provides a Pure\-tcl set of tools to allow programs to -schedule tasks to occur at regular intervals\. Rather than force each task to -issue it's own call to the event loop, the cron system mimics the cron utility -in Unix: on task periodically checks to see if something is to be done, and -issues all commands for a given time step at once\. - -Changes in version 2\.0 - -While cron was originally designed to handle time scales > 1 second, the latest -version's internal understand time granularity down to the millisecond, making -it easier to integrate with other timed events\. Version 2\.0 also understands how -to properly integrate coroutines and objects\. It also adds a facility for an -external \(or script driven\) clock\. Note that vwait style events won't work very -well with an external clock\. - -# Commands - - - __::cron::at__ *?processname?* *timecode* *command* - - This command registers a *command* to be called at the time specified by - *timecode*\. If *timecode* is expressed as an integer, the timecode is - assumed to be in unixtime\. All other inputs will be interpreted by __clock - scan__ and converted to unix time\. This task can be modified by subsequent - calls to this package's commands by referencing *processname*\. If - *processname* exists, it will be replaced\. If *processname* is not - given, one is generated and returned by the command\. - - ::cron::at start_coffee {Tomorrow at 9:00am} {remote::exec::coffeepot power on} - ::cron::at shutdown_coffee {Tomorrow at 12:00pm} {remote::exec::coffeepot power off} - - - __::cron::cancel__ *processname* - - This command unregisters the process *processname* and cancels any pending - commands\. Note: processname can be a process created by either - __::cron::at__ or __::cron::every__\. - - ::cron::cancel check_mail - - - __::cron::every__ *processname* *frequency* *command* - - This command registers a *command* to be called at the interval of - *frequency*\. *frequency* is given in seconds\. This task can be modified - by subsequent calls to this package's commands by referencing - *processname*\. If *processname* exists, it will be replaced\. - - ::cron::every check_mail 900 ::imap_client::check_mail - ::cron::every backup_db 3600 {::backup_procedure ::mydb} - - - __::cron::in__ *?processname?* *timecode* *command* - - This command registers a *command* to be called after a delay of time - specified by *timecode*\. *timecode* is expressed as an seconds\. This - task can be modified by subsequent calls to this package's commands by - referencing *processname*\. If *processname* exists, it will be replaced\. - If *processname* is not given, one is generated and returned by the - command\. - - - __::cron::object\_coroutine__ *object* *coroutine* *?info?* - - This command registers a *coroutine*, associated with *object* to be - called given the parameters of *info*\. If now parameters are given, the - coroutine is assumed to be an idle task which will self\-terminate\. *info* - can be given in any form compadible with __::cron::task set__ - - - __::cron::sleep__ *milliseconds* - - When run within a coroutine, this command will register the coroutine for a - callback at the appointed time, and immediately yield\. - - If the ::cron::time variable is > 0 this command will advance the internal - time, 100ms at a time\. - - In all other cases this command will generate a fictious variable, generate - an after call, and vwait the variable: - - set eventid [incr ::cron::eventcount] - set var ::cron::event_#$eventid - set $var 0 - ::after $ms "set $var 1" - ::vwait $var - ::unset $var - - Usage: - - ::cron::sleep 250 - - - __::cron::task delete__ *process* - - Delete the process specified the *process* - - - __::cron::task exists__ *process* - - Returns true if *process* is registered with cron\. - - - __::cron::task info__ *process* - - Returns a dict describing *process*\. See __::cron::task set__ for a - description of the options\. - - - __::cron::task set__ *process* *field* *value* *?field\.\.\.?* *?value\.\.\.?* - - If *process* does not exist, it is created\. Options Include: - - * __[command](\.\./\.\./\.\./\.\./index\.md\#command)__ - - If __[coroutine](\.\./coroutine/tcllib\_coroutine\.md)__ is black, a - global command which implements this process\. If - __[coroutine](\.\./coroutine/tcllib\_coroutine\.md)__ is not black, - the command to invoke to create or recreate the coroutine\. - - * __[coroutine](\.\./coroutine/tcllib\_coroutine\.md)__ - - The name of the coroutine \(if any\) which implements this process\. - - * __frequency__ - - If \-1, this process is terminated after the next event\. If 0 this - process should be called during every idle event\. If positive, this - process should generate events periodically\. The frequency is an integer - number of milliseconds between events\. - - * __[object](\.\./\.\./\.\./\.\./index\.md\#object)__ - - The object associated with this process or coroutine\. - - * __scheduled__ - - If non\-zero, the absolute time from the epoch \(in milliseconds\) that - this process will trigger an event\. If zero, and the __frequency__ - is also zero, this process is called every idle loop\. - - * __[running](\.\./\.\./\.\./\.\./index\.md\#running)__ - - A boolean flag\. If true it indicates the process never returned or - yielded during the event loop, and will not be called again until it - does so\. - - - __::cron::wake__ *?who?* - - Wake up cron, and arrange for its event loop to be run during the next Idle - cycle\. - - ::cron::wake {I just did something important} - -Several utility commands are provided that are used internally within cron and -for testing cron, but may or may not be useful in the general cases\. - - - __::cron::clock\_step__ *milliseconds* - - Return a clock time absolute to the epoch which falls on the next border - between one second and the next for the value of *milliseconds* - - - __::cron::clock\_delay__ *milliseconds* - - Return a clock time absolute to the epoch which falls on the next border - between one second and the next *milliseconds* in the future\. - - - __::cron::clock\_sleep__ *seconds* *?offset?* - - Return a clock time absolute to the epoch which falls exactly *seconds* in - the future\. If offset is given it may be positive or negative, and will - shift the final time to before or after the second would flip\. - - - __::cron::clock\_set__ *newtime* - - Sets the internal clock for cron\. This command will advance the time in - 100ms increment, triggering events, until the internal time catches up with - *newtime*\. - - *newtime* is expressed in absolute milliseconds since the beginning of the - epoch\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *odie* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[cron](\.\./\.\./\.\./\.\./index\.md\#cron), [odie](\.\./\.\./\.\./\.\./index\.md\#odie) - -# CATEGORY - -System - -# COPYRIGHT - -Copyright © 2016\-2018 Sean Woods DELETED embedded/md/tcllib/files/modules/csv/csv.md Index: embedded/md/tcllib/files/modules/csv/csv.md ================================================================== --- embedded/md/tcllib/files/modules/csv/csv.md +++ embedded/md/tcllib/files/modules/csv/csv.md @@ -1,273 +0,0 @@ - -[//000000001]: # (csv \- CSV processing) -[//000000002]: # (Generated from file 'csv\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2015 Andreas Kupries ) -[//000000004]: # (csv\(n\) 0\.8\.1 tcllib "CSV processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -csv \- Procedures to handle CSV data\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [FORMAT](#section3) - - - [EXAMPLE](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require csv ?0\.8\.1? - -[__::csv::iscomplete__ *data*](#1) -[__::csv::join__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?](#2) -[__::csv::joinlist__ *values* ?*sepChar*? ?*delChar*? ?*delMode*?](#3) -[__::csv::joinmatrix__ *matrix* ?*sepChar*? ?*delChar*? ?*delMode*?](#4) -[__::csv::read2matrix__ ?__\-alternate__? *chan m* \{*sepChar* ,\} \{*expand* none\}](#5) -[__::csv::read2queue__ ?__\-alternate__? *chan q* \{*sepChar* ,\}](#6) -[__::csv::report__ *cmd matrix* ?*chan*?](#7) -[__::csv::split__ ?__\-alternate__? *line* ?*sepChar*? ?*delChar*?](#8) -[__::csv::split2matrix__ ?__\-alternate__? *m line* \{*sepChar* ,\} \{*expand* none\}](#9) -[__::csv::split2queue__ ?__\-alternate__? *q line* \{*sepChar* ,\}](#10) -[__::csv::writematrix__ *m chan* ?*sepChar*? ?*delChar*?](#11) -[__::csv::writequeue__ *q chan* ?*sepChar*? ?*delChar*?](#12) - -# DESCRIPTION - -The __csv__ package provides commands to manipulate information in CSV -[FORMAT](#section3) \(CSV = Comma Separated Values\)\. - -# COMMANDS - -The following commands are available: - - - __::csv::iscomplete__ *data* - - A predicate checking if the argument *data* is a complete csv record\. The - result is a boolean flag indicating the completeness of the data\. The result - is true if the data is complete\. - - - __::csv::join__ *values* ?*sepChar*? ?*delChar*? ?*delMode*? - - Takes a list of values and returns a string in CSV format containing these - values\. The separator character can be defined by the caller, but this is - optional\. The default is ","\. The quoting aka delimiting character can be - defined by the caller, but this is optional\. The default is '"'\. By default - the quoting mode *delMode* is "auto", surrounding values with *delChar* - only when needed\. When set to "always" however, values are always surrounded - by the *delChar* instead\. - - - __::csv::joinlist__ *values* ?*sepChar*? ?*delChar*? ?*delMode*? - - Takes a list of lists of values and returns a string in CSV format - containing these values\. The separator character can be defined by the - caller, but this is optional\. The default is ","\. The quoting character can - be defined by the caller, but this is optional\. The default is '"'\. By - default the quoting mode *delMode* is "auto", surrounding values with - *delChar* only when needed\. When set to "always" however, values are - always surrounded by the *delChar* instead\. Each element of the outer list - is considered a record, these are separated by newlines in the result\. The - elements of each record are formatted as usual \(via __::csv::join__\)\. - - - __::csv::joinmatrix__ *matrix* ?*sepChar*? ?*delChar*? ?*delMode*? - - Takes a *matrix* object following the API specified for the struct::matrix - package and returns a string in CSV format containing these values\. The - separator character can be defined by the caller, but this is optional\. The - default is ","\. The quoting character can be defined by the caller, but this - is optional\. The default is '"'\. By default the quoting mode *delMode* is - "auto", surrounding values with *delChar* only when needed\. When set to - "always" however, values are always surrounded by the *delChar* instead\. - Each row of the matrix is considered a record, these are separated by - newlines in the result\. The elements of each record are formatted as usual - \(via __::csv::join__\)\. - - - __::csv::read2matrix__ ?__\-alternate__? *chan m* \{*sepChar* ,\} \{*expand* none\} - - A wrapper around __::csv::split2matrix__ \(see below\) reading - CSV\-formatted lines from the specified channel \(until EOF\) and adding them - to the given matrix\. For an explanation of the *expand* argument see - __::csv::split2matrix__\. - - - __::csv::read2queue__ ?__\-alternate__? *chan q* \{*sepChar* ,\} - - A wrapper around __::csv::split2queue__ \(see below\) reading - CSV\-formatted lines from the specified channel \(until EOF\) and adding them - to the given queue\. - - - __::csv::report__ *cmd matrix* ?*chan*? - - A report command which can be used by the matrix methods __format - 2string__ and __format 2chan__\. For the latter this command delegates - the work to __::csv::writematrix__\. *cmd* is expected to be either - __printmatrix__ or __printmatrix2channel__\. The channel argument, - *chan*, has to be present for the latter and must not be present for the - first\. - - - __::csv::split__ ?__\-alternate__? *line* ?*sepChar*? ?*delChar*? - - converts a *line* in CSV format into a list of the values contained in the - line\. The character used to separate the values from each other can be - defined by the caller, via *sepChar*, but this is optional\. The default is - ","\. The quoting character can be defined by the caller, but this is - optional\. The default is '"'\. - - If the option __\-alternate__ is specified a slightly different syntax is - used to parse the input\. This syntax is explained below, in the section - [FORMAT](#section3)\. - - - __::csv::split2matrix__ ?__\-alternate__? *m line* \{*sepChar* ,\} \{*expand* none\} - - The same as __::csv::split__, but appends the resulting list as a new - row to the matrix *m*, using the method __add row__\. The expansion - mode specified via *expand* determines how the command handles a matrix - with less columns than contained in *line*\. The allowed modes are: - - * __none__ - - This is the default mode\. In this mode it is the responsibility of the - caller to ensure that the matrix has enough columns to contain the full - line\. If there are not enough columns the list of values is silently - truncated at the end to fit\. - - * __empty__ - - In this mode the command expands an empty matrix to hold all columns of - the specified line, but goes no further\. The overall effect is that the - first of a series of lines determines the number of columns in the - matrix and all following lines are truncated to that size, as if mode - __none__ was set\. - - * __auto__ - - In this mode the command expands the matrix as needed to hold all - columns contained in *line*\. The overall effect is that after adding a - series of lines the matrix will have enough columns to hold all columns - of the longest line encountered so far\. - - - __::csv::split2queue__ ?__\-alternate__? *q line* \{*sepChar* ,\} - - The same as __::csv::split__, but appending the resulting list as a - single item to the queue *q*, using the method __put__\. - - - __::csv::writematrix__ *m chan* ?*sepChar*? ?*delChar*? - - A wrapper around __::csv::join__ taking all rows in the matrix *m* and - writing them CSV formatted into the channel *chan*\. - - - __::csv::writequeue__ *q chan* ?*sepChar*? ?*delChar*? - - A wrapper around __::csv::join__ taking all items in the queue *q* - \(assumes that they are lists\) and writing them CSV formatted into the - channel *chan*\. - -# FORMAT - -The format of regular CSV files is specified as - - 1. Each record of a csv file \(comma\-separated values, as exported e\.g\. by - Excel\) is a set of ASCII values separated by ","\. For other languages it - may be ";" however, although this is not important for this case as the - functions provided here allow any separator character\. - - 1. If and only if a value contains itself the separator ",", then it \(the - value\) has to be put between ""\. If the value does not contain the - separator character then quoting is optional\. - - 1. If a value contains the character ", that character is represented by ""\. - - 1. The output string "" represents the value "\. In other words, it is assumed - that it was created through rule 3, and only this rule, i\.e\. that the value - was not quoted\. - -An alternate format definition mainly used by MS products specifies that the -output string "" is a representation of the empty string\. In other words, it is -assumed that the output was generated out of the empty string by quoting it -\(i\.e\. rule 2\), and not through rule 3\. This is the only difference between the -regular and the alternate format\. - -The alternate format is activated through specification of the option -__\-alternate__ to the various split commands\. - -# EXAMPLE - -Using the regular format the record - - 123,"123,521.2","Mary says ""Hello, I am Mary""","" - -is parsed into the items - - a) 123 - b) 123,521.2 - c) Mary says "Hello, I am Mary" - d) " - -Using the alternate format the result is - - a) 123 - b) 123,521.2 - c) Mary says "Hello, I am Mary" - d) (the empty string) - -instead\. As can be seen only item \(d\) is different, now the empty string instead -of a "\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *csv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[queue](\.\./\.\./\.\./\.\./index\.md\#queue) - -# KEYWORDS - -[csv](\.\./\.\./\.\./\.\./index\.md\#csv), [matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[package](\.\./\.\./\.\./\.\./index\.md\#package), -[queue](\.\./\.\./\.\./\.\./index\.md\#queue), -[tcllib](\.\./\.\./\.\./\.\./index\.md\#tcllib) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2002\-2015 Andreas Kupries DELETED embedded/md/tcllib/files/modules/debug/debug.md Index: embedded/md/tcllib/files/modules/debug/debug.md ================================================================== --- embedded/md/tcllib/files/modules/debug/debug.md +++ embedded/md/tcllib/files/modules/debug/debug.md @@ -1,286 +0,0 @@ - -[//000000001]: # (debug \- debug narrative) -[//000000002]: # (Generated from file 'debug\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 200?, Colin McCormack, Wub Server Utilities) -[//000000004]: # (Copyright © 2012\-2014, Andreas Kupries ) -[//000000005]: # (debug\(n\) 1\.0\.6 tcllib "debug narrative") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -debug \- debug narrative \- core - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require debug ?1\.0\.6? - -[__debug\.____tag__ *message* ?*level*?](#1) -[__debug__ __2array__](#2) -[__debug__ __define__ *tag*](#3) -[__debug__ __header__ *text*](#4) -[__debug__ __level__ *tag* ?*level*? ?*fd*?](#5) -[__debug__ __names__](#6) -[__debug__ __off__ *tag*](#7) -[__debug__ __on__ *tag*](#8) -[__debug__ __parray__ *arrayvarname*](#9) -[__debug__ __pdict__ *dict*](#10) -[__debug__ __hexl__ *data* ?*prefix*?](#11) -[__debug__ __nl__](#12) -[__debug__ __tab__](#13) -[__debug__ __prefix__ *tag* ?*text*?](#14) -[__debug__ __setting__ \(*tag* *level*\) \.\.\. ?*fd*?](#15) -[__debug__ __suffix__ *tag* ?*text*?](#16) -[__debug__ __trailer__ *text*](#17) - -# DESCRIPTION - -Debugging areas of interest are represented by 'tags' which have independently -settable levels of interest \(an integer, higher is more detailed\)\. - -# API - - - __debug\.____tag__ *message* ?*level*? - - For each known tag the package creates a command with this signature the - user can then use to provide the debug narrative of the tag\. The narrative - *message* is provided as a Tcl script whose value is - __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ed in the caller's scope if - and only if the current level of interest for the *tag* matches or exceeds - the call's *level* of detail\. This is useful, as one can place arbitrarily - complex narrative in code without unnecessarily evaluating it\. - - See methods __level__ and __setting__ for querying and manipulating - the current level of detail for tags\. - - The actually printed text consists of not only the *message*, but also - global and tag\-specific prefix and suffix, should they exist, with each line - in the message having the specified headers and trailers\. - - All these parts are __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ableTcl - scripts, which are substituted once per message before assembly\. - - - __debug__ __2array__ - - This method returns a dictionary mapping the names of all debug tags - currently known to the package to their state and log level\. The latter are - encoded in a single numeric value, where a negative number indicates an - inactive tag at the level given by the absolute value, and a positive number - is an active tag at that level\. - - See also method __settings__ below\. - - - __debug__ __define__ *tag* - - This method registers the named *tag* with the package\. If the tag was not - known before it is placed in an inactive state\. The state of an already - known tag is left untouched\. - - The result of the method is the empty string\. - - - __debug__ __header__ *text* - - This method defines a global - __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__able Tcl script which - provides a text printed before each line of output\. - - Note how this is tag\-independent\. - - Further note that the header substitution happens only once per actual - printed message, i\.e\. all lines of the same message will have the same - actual heading text\. - - The result of the method is the specified text\. - - - __debug__ __level__ *tag* ?*level*? ?*fd*? - - This method sets the detail\-*level* for the *tag*, and the channel - *fd* to write the tags narration into\. The level is an integer value >= 0 - defaulting to __1__\. The channel defaults to __stderr__\. - - The result of the method is the new detail\-level for the tag\. - - - __debug__ __names__ - - This method returns a list containing the names of all debug tags currently - known to the package\. - - - __debug__ __off__ *tag* - - This method registers the named *tag* with the package and sets it - inactive\. - - The result of the method is the empty string\. - - - __debug__ __on__ *tag* - - This method registers the named *tag* with the package, as active\. - - The result of the method is the empty string\. - - - __debug__ __parray__ *arrayvarname* - - This is a convenience method formatting the named array like the builtin - command __parray__, except it returns the resulting string instead of - writing it directly to __stdout__\. - - This makes it suitable for use in debug messages\. - - - __debug__ __pdict__ *dict* - - This is a convenience method formatting the dictionary similarly to how the - builtin command __parray__ does for array, and returns the resulting - string\. - - This makes it suitable for use in debug messages\. - - - __debug__ __hexl__ *data* ?*prefix*? - - This is a convenience method formatting arbitrary data into a hex\-dump and - returns the resulting string\. - - This makes it suitable for use in debug messages\. - - Each line of the dump is prefixed with *prefix*\. This prefix defaults to - the empty string\. - - - __debug__ __nl__ - - This is a convenience method to insert a linefeed character \(ASCII 0x0a\) - into a debug message\. - - - __debug__ __tab__ - - This is a convenience method to insert a TAB character \(ASCII 0x09\) into a - debug message\. - - - __debug__ __prefix__ *tag* ?*text*? - - This method is similar to the method __header__ above, in that it - defines __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__able Tcl script which - provides more text for debug messages\. - - In contrast to __header__ the generated text is added to the user's - message before it is split into lines, making it a per\-message extension\. - - Furthermore the script is tag\-dependent\. - - In exception to that, a script for tag __::__ is applied to all - messages\. - - If both global and tag\-dependent prefix exist, both are applied, with the - global prefix coming before the tag\-dependent prefix\. - - Note that the prefix substitution happens only once per actual printed - message\. - - The result of the method is the empty string\. - - If the *tag* was not known at the time of the call it is registered, and - set inactive\. - - - __debug__ __setting__ \(*tag* *level*\) \.\.\. ?*fd*? - - This method is a multi\-tag variant of method __level__ above, with the - functionality of methods __on__, and __off__ also folded in\. - - Each named *tag* is set to the detail\-*level* following it, with a - negative level deactivating the tag, and a positive level activating it\. - - If the last argument is not followed by a level it is not treated as tag - name, but as the channel all the named tags should print their messages to\. - - The result of the method is the empty string\. - - - __debug__ __suffix__ *tag* ?*text*? - - This method is similar to the method __trailer__ below, in that it - defines __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__able Tcl script which - provides more text for debug messages\. - - In contrast to __trailer__ the generated text is added to the user's - message before it is split into lines, making it a per\-message extension\. - - Furthermore the script is tag\-dependent\. - - In exception to that, a script for tag __::__ is applied to all - messages\. - - If both global and tag\-dependent suffix exist, both are applied, with the - global suffix coming after the tag\-dependent suffix\. - - Note that the suffix substitution happens only once per actual printed - message\. - - The result of the method is the empty string\. - - If the *tag* was not known at the time of the call it is registered, and - set inactive\. - - - __debug__ __trailer__ *text* - - This method defines a global - __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__able Tcl script which - provides a text printed after each line of output \(before the EOL however\)\. - - Note how this is tag\-independent\. - - Further note that the trailer substitution happens only once per actual - printed message, i\.e\. all lines of the same message will have the same - actual trailing text\. - - The result of the method is the specified text\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *debug* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[debug](\.\./\.\./\.\./\.\./index\.md\#debug), [log](\.\./\.\./\.\./\.\./index\.md\#log), -[narrative](\.\./\.\./\.\./\.\./index\.md\#narrative), -[trace](\.\./\.\./\.\./\.\./index\.md\#trace) - -# CATEGORY - -debugging, tracing, and logging - -# COPYRIGHT - -Copyright © 200?, Colin McCormack, Wub Server Utilities -Copyright © 2012\-2014, Andreas Kupries DELETED embedded/md/tcllib/files/modules/debug/debug_caller.md Index: embedded/md/tcllib/files/modules/debug/debug_caller.md ================================================================== --- embedded/md/tcllib/files/modules/debug/debug_caller.md +++ embedded/md/tcllib/files/modules/debug/debug_caller.md @@ -1,92 +0,0 @@ - -[//000000001]: # (debug::caller \- debug narrative) -[//000000002]: # (Generated from file 'debug\_caller\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2012\-2015, Andreas Kupries ) -[//000000004]: # (debug::caller\(n\) 1\.1 tcllib "debug narrative") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -debug::caller \- debug narrative \- caller - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require debug::caller ?1\.1? - -[__[debug](debug\.md)__ __caller__ ?*args*\.\.\.?](#1) - -# DESCRIPTION - -# API - - - __[debug](debug\.md)__ __caller__ ?*args*\.\.\.? - - This method is useful in a tag\-specific prefix to automatically provide - caller information for all uses of the tag\. Or in a message, when only - specific places need such detail\. - - Beyond that it recognizing the various internal forms of method calls - generated by the __[snit](\.\./snit/snit\.md)__ OO system and rewrites - these to their original form, for better readability\. Similarly for - __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__\. - - If *args* are specified then they are treated as the integer indices of - command arguments to *not* show in the output\. The referenced arguments - are replaced by __\*__ instead\. The main anticipiated use case for this - is the exclusion of arguments expected to contain large Tcl values, i\.e\. - long lists, large dictionaries, etc\. to prevent them from overwhelming the - narrative\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *debug* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[debug](\.\./\.\./\.\./\.\./index\.md\#debug), [log](\.\./\.\./\.\./\.\./index\.md\#log), -[narrative](\.\./\.\./\.\./\.\./index\.md\#narrative), -[trace](\.\./\.\./\.\./\.\./index\.md\#trace) - -# CATEGORY - -debugging, tracing, and logging - -# COPYRIGHT - -Copyright © 2012\-2015, Andreas Kupries DELETED embedded/md/tcllib/files/modules/debug/debug_heartbeat.md Index: embedded/md/tcllib/files/modules/debug/debug_heartbeat.md ================================================================== --- embedded/md/tcllib/files/modules/debug/debug_heartbeat.md +++ embedded/md/tcllib/files/modules/debug/debug_heartbeat.md @@ -1,93 +0,0 @@ - -[//000000001]: # (debug::heartbeat \- debug narrative) -[//000000002]: # (Generated from file 'debug\_heartbeat\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 200?, Colin McCormack, Wub Server Utilities) -[//000000004]: # (Copyright © 2012, Andreas Kupries ) -[//000000005]: # (debug::heartbeat\(n\) 1\.0\.1 tcllib "debug narrative") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -debug::heartbeat \- debug narrative \- heartbeat - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require debug::heartbeat ?1\.0\.1? -package require debug ?1? - -[__[debug](debug\.md)__ __heartbeat__ ?*delta*?](#1) - -# DESCRIPTION - -# API - - - __[debug](debug\.md)__ __heartbeat__ ?*delta*? - - This method activates or disables a heartbeat with which to monitor the - event loop of an event\-based Tcl application\. - - It reserves the debug tag __heartbeat__ for its operation and writes a - message every *delta* milliseconds\. - - A *delta*\-value <= 0 disables the heartbeat\. - - The message produced by the heartbeat contains a sequence counter and the - time in milliseconds since the last beat, thus providing insight into timing - variationsn and deviations from the nominal *delta*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *debug* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[debug](\.\./\.\./\.\./\.\./index\.md\#debug), -[heartbeat](\.\./\.\./\.\./\.\./index\.md\#heartbeat), -[log](\.\./\.\./\.\./\.\./index\.md\#log), -[narrative](\.\./\.\./\.\./\.\./index\.md\#narrative), -[trace](\.\./\.\./\.\./\.\./index\.md\#trace) - -# CATEGORY - -debugging, tracing, and logging - -# COPYRIGHT - -Copyright © 200?, Colin McCormack, Wub Server Utilities -Copyright © 2012, Andreas Kupries DELETED embedded/md/tcllib/files/modules/debug/debug_timestamp.md Index: embedded/md/tcllib/files/modules/debug/debug_timestamp.md ================================================================== --- embedded/md/tcllib/files/modules/debug/debug_timestamp.md +++ embedded/md/tcllib/files/modules/debug/debug_timestamp.md @@ -1,85 +0,0 @@ - -[//000000001]: # (debug::timestamp \- debug narrative) -[//000000002]: # (Generated from file 'debug\_timestamp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 200?, Colin McCormack, Wub Server Utilities) -[//000000004]: # (Copyright © 2012, Andreas Kupries ) -[//000000005]: # (debug::timestamp\(n\) 1 tcllib "debug narrative") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -debug::timestamp \- debug narrative \- timestamping - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require debug::timestamp ?1? -package require debug ?1? - -[__[debug](debug\.md)__ __timestamp__](#1) - -# DESCRIPTION - -# API - - - __[debug](debug\.md)__ __timestamp__ - - This method returns millisecond timing information since a baseline or last - call, making it useful in a tag\-specific prefix to automatically provide - caller information for all uses of the tag\. Or in a message, when only - specific places need such detail\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *debug* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[debug](\.\./\.\./\.\./\.\./index\.md\#debug), [log](\.\./\.\./\.\./\.\./index\.md\#log), -[narrative](\.\./\.\./\.\./\.\./index\.md\#narrative), -[timestamps](\.\./\.\./\.\./\.\./index\.md\#timestamps), -[trace](\.\./\.\./\.\./\.\./index\.md\#trace) - -# CATEGORY - -debugging, tracing, and logging - -# COPYRIGHT - -Copyright © 200?, Colin McCormack, Wub Server Utilities -Copyright © 2012, Andreas Kupries DELETED embedded/md/tcllib/files/modules/defer/defer.md Index: embedded/md/tcllib/files/modules/defer/defer.md ================================================================== --- embedded/md/tcllib/files/modules/defer/defer.md +++ embedded/md/tcllib/files/modules/defer/defer.md @@ -1,133 +0,0 @@ - -[//000000001]: # (defer \- Defered execution ala Go) -[//000000002]: # (Generated from file 'defer\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2017, Roy Keene) -[//000000004]: # (defer\(n\) 1 tcllib "Defered execution ala Go") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -defer \- Defered execution - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require defer ?1? - -[__::defer::defer__ ?*command*? ?*arg1*? ?*arg2*? ?*argN\.\.\.*?](#1) -[__::defer::with__ *variableList* *script*](#2) -[__::defer::autowith__ *script*](#3) -[__::defer::cancel__ ?*id\.\.\.*?](#4) - -# DESCRIPTION - -The __defer__ commands allow a developer to schedule actions to happen as -part of the current variable scope terminating\. This is most useful for dealing -with cleanup activities\. Since the defered actions always execute, and always -execute in the reverse order from which the defer statements themselves execute, -the programmer can schedule the cleanup of a resource \(for example, a channel\) -as soon as that resource is acquired\. Then, later if the procedure or lambda -ends, either due to an error, or an explicit return, the cleanup of that -resource will always occur\. - -# COMMANDS - - - __::defer::defer__ ?*command*? ?*arg1*? ?*arg2*? ?*argN\.\.\.*? - - Defers execution of some code until the current variable scope ends\. Each - argument is concatencated together to form the script to execute at deferal - time\. Multiple defer statements may be used, they are executed in the order - of last\-in, first\-out\. The return value is an identifier which can be used - later with __defer::cancel__ - - - __::defer::with__ *variableList* *script* - - Defers execution of a script while copying the current value of some - variables, whose names specified in *variableList*, into the script\. The - script acts like a lambda but executes at the same level as the - __defer::with__ call\. The return value is the same as - __::defer::defer__ - - - __::defer::autowith__ *script* - - The same as __::defer::with__ but uses all local variables in the - variable list\. - - - __::defer::cancel__ ?*id\.\.\.*? - - Cancels the execution of a defered action\. The *id* argument is the - identifier returned by __::defer::defer__, __::defer::with__, or - __::defer::autowith__\. Any number of arguments may be supplied, and all - of the IDs supplied will be cancelled\. - -# EXAMPLES - - package require defer 1 - apply {{} { - set fd [open /dev/null] - defer::defer close $fd - }} - -# REFERENCES - -# AUTHORS - -Roy Keene - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *defer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[cleanup](\.\./\.\./\.\./\.\./index\.md\#cleanup), -[golang](\.\./\.\./\.\./\.\./index\.md\#golang) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2017, Roy Keene DELETED embedded/md/tcllib/files/modules/des/des.md Index: embedded/md/tcllib/files/modules/des/des.md ================================================================== --- embedded/md/tcllib/files/modules/des/des.md +++ embedded/md/tcllib/files/modules/des/des.md @@ -1,233 +0,0 @@ - -[//000000001]: # (des \- Data Encryption Standard \(DES\)) -[//000000002]: # (Generated from file 'des\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts ) -[//000000004]: # (des\(n\) 1\.1 tcllib "Data Encryption Standard \(DES\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -des \- Implementation of the DES and triple\-DES ciphers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [MODES OF OPERATION](#section4) - - - [EXAMPLES](#section5) - - - [REFERENCES](#section6) - - - [AUTHORS](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require des 1\.1 - -[__::DES::des__ ?*\-mode \[ecb|cbc|cfb|ofb\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-hex*? ?*\-weak*? ?*\-out channel*? ?*\-chunksize size*? \[ *\-in channel* | *data* \]](#1) -[__::DES::Init__ *mode* *keydata* *iv* ?*weak*?](#2) -[__::DES::Encrypt__ *Key* *data*](#3) -[__::DES::Decrypt__ *Key* *data*](#4) -[__::DES::Reset__ *Key* *iv*](#5) -[__::DES::Final__ *Key*](#6) - -# DESCRIPTION - -This is an implementation in Tcl of the Data Encryption Standard \(DES\) as -published by the U\.S\. National Institute of Standards and Technology \(NIST\) \[1\]\. -This implementation also supports triple DES \(3DES\) extension to DES\. DES is a -64\-bit block cipher that uses a 56\-bit key\. 3DES uses a 168\-bit key\. DES has now -officially been superceeded by AES but is in common use in many protocols\. - -The tcllib implementation of DES and 3DES uses an implementation by Mac Cody and -is available as a separate download from \[2\]\. For anyone concerned about the -details of exporting this code please see the TclDES web pages\. The tcllib -specific code is a wrapper to the TclDES API that presents same API for the DES -cipher as for other ciphers in the library\. - -# COMMANDS - - - __::DES::des__ ?*\-mode \[ecb|cbc|cfb|ofb\]*? ?*\-dir \[encrypt|decrypt\]*? *\-key keydata* ?*\-iv vector*? ?*\-hex*? ?*\-weak*? ?*\-out channel*? ?*\-chunksize size*? \[ *\-in channel* | *data* \] - - Perform the __[DES](\.\./\.\./\.\./\.\./index\.md\#des)__ algorithm on either - the data provided by the argument or on the data read from the *\-in* - channel\. If an *\-out* channel is given then the result will be written to - this channel\. - - The *\-key* option must be given\. This parameter takes a binary string of 8 - bytes in length and is used to generate the key schedule\. In DES only 56 - bits of key data are used\. The highest bit from each byte is discarded\. - - The *\-mode* and *\-dir* options are optional and default to cbc mode and - encrypt respectively\. The initialization vector *\-iv* takes an 8 byte - binary argument\. This defaults to all zeros\. See [MODES OF - OPERATION](#section4) for more about *\-mode* and the use of the - initialization vector\. - - DES is a 64\-bit block cipher\. This means that the data must be provided in - units that are a multiple of 8 bytes\. - -# PROGRAMMING INTERFACE - -Internal state is maintained in an opaque structure that is returned from the -__Init__ function\. In ECB mode the state is not affected by the input but -for other modes some input dependent state is maintained and may be reset by -calling the __Reset__ function with a new initialization vector value\. - - - __::DES::Init__ *mode* *keydata* *iv* ?*weak*? - - Construct a new DES key schedule using the specified key data and the given - initialization vector\. The initialization vector is not used with ECB mode - but is important for other usage modes\. See [MODES OF - OPERATION](#section4)\. - - There are a small number of keys that are known to be weak when used with - DES\. By default if such a key is passed in then an error will be raised\. If - there is a need to accept such keys then the *weak* parameter can be set - true to avoid the error being thrown\. - - - __::DES::Encrypt__ *Key* *data* - - Use a prepared key acquired by calling __Init__ to encrypt the provided - data\. The data argument should be a binary array that is a multiple of the - DES block size of 8 bytes\. The result is a binary array the same size as the - input of encrypted data\. - - - __::DES::Decrypt__ *Key* *data* - - Decipher data using the key\. Note that the same key may be used to encrypt - and decrypt data provided that the initialization vector is reset - appropriately for CBC mode\. - - - __::DES::Reset__ *Key* *iv* - - Reset the initialization vector\. This permits the programmer to re\-use a key - and avoid the cost of re\-generating the key schedule where the same key data - is being used multiple times\. - - - __::DES::Final__ *Key* - - This should be called to clean up resources associated with *Key*\. Once - this function has been called the key may not be used again\. - -# MODES OF OPERATION - - - Electronic Code Book \(ECB\) - - ECB is the basic mode of all block ciphers\. Each block is encrypted - independently and so identical plain text will produce identical output when - encrypted with the same key\. Any encryption errors will only affect a single - block however this is vulnerable to known plaintext attacks\. - - - Cipher Block Chaining \(CBC\) - - CBC mode uses the output of the last block encryption to affect the current - block\. An initialization vector of the same size as the cipher block size is - used to handle the first block\. The initialization vector should be chosen - randomly and transmitted as the first block of the output\. Errors in - encryption affect the current block and the next block after which the - cipher will correct itself\. CBC is the most commonly used mode in software - encryption\. - - - Cipher Feedback \(CFB\) - - CFB mode can be used to convert block ciphers into stream ciphers\. In CFB - mode the initialization vector is encrypted and the output is then xor'd - with the plaintext stream\. The result is then used as the initialization - vector for the next round\. Errors will affect the current block and the next - block\. - - - Output Feedback \(OFB\) - - OFB is similar to CFB except that the output of the cipher is fed back into - the next round and not the xor'd plain text\. This means that errors only - affect a single block but the cipher is more vulnerable to attack\. - -# EXAMPLES - - % set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext] - % set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext] - - set iv [string repeat \\0 8] - set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv] - set ciphertext [DES::Encrypt $Key "somedata"] - append ciphertext [DES::Encrypt $Key "moredata"] - DES::Reset $Key $iv - set plaintext [DES::Decrypt $Key $ciphertext] - DES::Final $Key - -# REFERENCES - - 1. "Data Encryption Standard", Federal Information Processing Standards - Publication 46\-3, 1999, - \([http://csrc\.nist\.gov/publications/fips/fips46\-3/fips46\-3\.pdf](http://csrc\.nist\.gov/publications/fips/fips46\-3/fips46\-3\.pdf)\) - - 1. "TclDES: munitions\-grade Tcl scripting" - [http://tcldes\.sourceforge\.net/](http://tcldes\.sourceforge\.net/) - -# AUTHORS - -Jochen C Loewer, Mac Cody, Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *des* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[aes\(n\)](\.\./aes/aes\.md), [blowfish\(n\)](\.\./blowfish/blowfish\.md), -[md5\(n\)](\.\./md5/md5\.md), [rc4\(n\)](\.\./rc4/rc4\.md), -[sha1\(n\)](\.\./sha1/sha1\.md) - -# KEYWORDS - -[3DES](\.\./\.\./\.\./\.\./index\.md\#3des), [DES](\.\./\.\./\.\./\.\./index\.md\#des), -[block cipher](\.\./\.\./\.\./\.\./index\.md\#block\_cipher), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2005, Pat Thoyts DELETED embedded/md/tcllib/files/modules/des/tcldes.md Index: embedded/md/tcllib/files/modules/des/tcldes.md ================================================================== --- embedded/md/tcllib/files/modules/des/tcldes.md +++ embedded/md/tcllib/files/modules/des/tcldes.md @@ -1,80 +0,0 @@ - -[//000000001]: # (tclDES \- Data Encryption Standard \(DES\)) -[//000000002]: # (Generated from file 'tcldes\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts ) -[//000000004]: # (tclDES\(n\) 1\.1 tcllib "Data Encryption Standard \(DES\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tclDES \- Implementation of the DES and triple\-DES ciphers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require tclDES 1\.1 - -# DESCRIPTION - -The __tclDES__ package is a helper package for __[des](des\.md)__\. - -Please see the documentation of __[des](des\.md)__ for details\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *des* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[des\(n\)](des\.md) - -# KEYWORDS - -[3DES](\.\./\.\./\.\./\.\./index\.md\#3des), [DES](\.\./\.\./\.\./\.\./index\.md\#des), -[block cipher](\.\./\.\./\.\./\.\./index\.md\#block\_cipher), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2005, Pat Thoyts DELETED embedded/md/tcllib/files/modules/des/tcldesjr.md Index: embedded/md/tcllib/files/modules/des/tcldesjr.md ================================================================== --- embedded/md/tcllib/files/modules/des/tcldesjr.md +++ embedded/md/tcllib/files/modules/des/tcldesjr.md @@ -1,80 +0,0 @@ - -[//000000001]: # (tclDESjr \- Data Encryption Standard \(DES\)) -[//000000002]: # (Generated from file 'tcldesjr\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts ) -[//000000004]: # (tclDESjr\(n\) 1\.1 tcllib "Data Encryption Standard \(DES\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tclDESjr \- Implementation of the DES and triple\-DES ciphers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require tclDESjr 1\.1 - -# DESCRIPTION - -The __tclDESjr__ package is a helper package for __[des](des\.md)__\. - -Please see the documentation of __[des](des\.md)__ for details\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *des* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[des\(n\)](des\.md) - -# KEYWORDS - -[3DES](\.\./\.\./\.\./\.\./index\.md\#3des), [DES](\.\./\.\./\.\./\.\./index\.md\#des), -[block cipher](\.\./\.\./\.\./\.\./index\.md\#block\_cipher), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2005, Pat Thoyts DELETED embedded/md/tcllib/files/modules/dicttool/dicttool.md Index: embedded/md/tcllib/files/modules/dicttool/dicttool.md ================================================================== --- embedded/md/tcllib/files/modules/dicttool/dicttool.md +++ embedded/md/tcllib/files/modules/dicttool/dicttool.md @@ -1,133 +0,0 @@ - -[//000000001]: # (dicttool \- Extensions to the standard "dict" command) -[//000000002]: # (Generated from file 'dicttool\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2017 Sean Woods ) -[//000000004]: # (dicttool\(n\) 1\.0 tcllib "Extensions to the standard "dict" command") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -dicttool \- Dictionary Tools - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require dicttool ?1\.0? - -[__ladd__ *varname* *args*](#1) -[__ldelete__ *varname* *args*](#2) -[__dict getnull__ *args*](#3) -[__dict print__ *dict*](#4) -[__dict is\_dict__ *value*](#5) -[__rmerge__ *args*](#6) - -# DESCRIPTION - -The __dicttool__ package enhances the standard *dict* command with several -new commands\. In addition, the package also defines several "creature comfort" -list commands as well\. Each command checks to see if a command already exists of -the same name before adding itself, just in case any of these slip into the -core\. - - - __ladd__ *varname* *args* - - This command will add a new instance of each element in *args* to - *varname*, but only if that element is not already present\. - - - __ldelete__ *varname* *args* - - This command will delete all instances of each element in *args* from - *varname*\. - - - __dict getnull__ *args* - - Operates like __dict get__, however if the key *args* does not exist, - it returns an empty list instead of throwing an error\. - - - __dict print__ *dict* - - This command will produce a string representation of *dict*, with each - nested branch on a newline, and indented with two spaces for every level\. - - - __dict is\_dict__ *value* - - This command will return true if *value* can be interpreted as a dict\. The - command operates in such a way as to not force an existing dict - representation to shimmer into another internal rep\. - - - __rmerge__ *args* - - Return a dict which is the product of a recursive merge of all of the - arguments\. Unlike __dict merge__, this command descends into all of the - levels of a dict\. Dict keys which end in a : indicate a leaf, which will be - interpreted as a literal value, and not descended into further\. - - set items [dict merge { - option {color {default: green}} - } { - option {fruit {default: mango}} - } { - option {color {default: blue} fruit {widget: select values: {mango apple cherry grape}}} - }] - puts [dict print $items] - - Prints the following result: - - option { - color { - default: blue - } - fruit { - widget: select - values: {mango apple cherry grape} - } - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *dict* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[dict](\.\./\.\./\.\./\.\./index\.md\#dict) - -# CATEGORY - -Utilities - -# COPYRIGHT - -Copyright © 2017 Sean Woods DELETED embedded/md/tcllib/files/modules/dns/tcllib_dns.md Index: embedded/md/tcllib/files/modules/dns/tcllib_dns.md ================================================================== --- embedded/md/tcllib/files/modules/dns/tcllib_dns.md +++ embedded/md/tcllib/files/modules/dns/tcllib_dns.md @@ -1,356 +0,0 @@ - -[//000000001]: # (dns \- Domain Name Service) -[//000000002]: # (Generated from file 'tcllib\_dns\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts) -[//000000004]: # (dns\(n\) 1\.5\.0 tcllib "Domain Name Service") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -dns \- Tcl Domain Name Service Client - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require dns ?1\.5\.0? - -[__::dns::resolve__ *query* ?*options*?](#1) -[__::dns::configure__ ?*options*?](#2) -[__::dns::name__ *token*](#3) -[__::dns::address__ *token*](#4) -[__::dns::cname__ *token*](#5) -[__::dns::result__ *token*](#6) -[__::dns::status__ *token*](#7) -[__::dns::error__ *token*](#8) -[__::dns::reset__ *token*](#9) -[__::dns::wait__ *token*](#10) -[__::dns::cleanup__ *token*](#11) -[__::dns::nameservers__](#12) - -# DESCRIPTION - -The dns package provides a Tcl only Domain Name Service client\. You should refer -to \(1\) and \(2\) for information about the DNS protocol or read resolver\(3\) to -find out how the C library resolves domain names\. The intention of this package -is to insulate Tcl scripts from problems with using the system library resolver -for slow name servers\. It may or may not be of practical use\. Internet name -resolution is a complex business and DNS is only one part of the resolver\. You -may find you are supposed to be using hosts files, NIS or WINS to name a few -other systems\. This package is not a substitute for the C library resolver \- it -does however implement name resolution over DNS\. The package also extends the -package __[uri](\.\./uri/uri\.md)__ to support DNS URIs \(4\) of the form -[dns:what\.host\.com](dns:what\.host\.com) or -[dns://my\.nameserver/what\.host\.com](dns://my\.nameserver/what\.host\.com)\. The -__dns::resolve__ command can handle DNS URIs or simple domain names as a -query\. - -*Note:* The package defaults to using DNS over TCP connections\. If you wish to -use UDP you will need to have the __tcludp__ package installed and have a -version that correctly handles binary data \(> 1\.0\.4\)\. This is available at -[http://tcludp\.sourceforge\.net/](http://tcludp\.sourceforge\.net/)\. If the -__udp__ package is present then UDP will be used by default\. - -*Note:* The package supports DNS over TLS \(RFC 7858\) for enhanced privacy of -DNS queries\. Using this feature requires the TLS package\. - -# COMMANDS - - - __::dns::resolve__ *query* ?*options*? - - Resolve a domain name using the *[DNS](\.\./\.\./\.\./\.\./index\.md\#dns)* - protocol\. *query* is the domain name to be lookup up\. This should be - either a fully qualified domain name or a DNS URI\. - - * __\-nameserver__ *hostname* or __\-server__ *hostname* - - Specify an alternative name server for this request\. - - * __\-protocol__ *tcp|udp* - - Specify the network protocol to use for this request\. Can be one of - *tcp* or *udp*\. - - * __\-port__ *portnum* - - Specify an alternative port\. - - * __\-search__ *domainlist* - - * __\-timeout__ *milliseconds* - - Override the default timeout\. - - * __\-type__ *TYPE* - - Specify the type of DNS record you are interested in\. Valid values are - A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, MINFO, MX, - TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and \*\. See RFC1035 for details - about the return values\. See - [http://spf\.pobox\.com/](http://spf\.pobox\.com/) about SPF\. See \(3\) - about AAAA records and RFC2782 for details of SRV records\. - - * __\-class__ *CLASS* - - Specify the class of domain name\. This is usually IN but may be one of - IN for internet domain names, CS, CH, HS or \* for any class\. - - * __\-recurse__ *boolean* - - Set to *false* if you do not want the name server to recursively act - upon your request\. Normally set to *true*\. - - * __\-command__ *procname* - - Set a procedure to be called upon request completion\. The procedure will - be passed the token as its only argument\. - - * __\-usetls__ *boolean* - - Set the *true* to use DNS over TLS\. This will force the use of TCP and - change the default port to 853\. Certificate validation is required so a - source of trusted certificate authority certificates must be provided - using *\-cafile* or *\-cadir*\. - - * __\-cafile__ *filepath* - - Specify a file containing a collection of trusted certificate authority - certficates\. See the __update\-ca\-certificates__ command manual page - for details or the __\-CAfile__ option help from __openssl__\. - - * __\-cadir__ *dirpath* - - Specify a directory containing trusted certificate authority - certificates\. This must be provided if __\-cafile__ is not specified - for certificate validation to work when __\-usetls__ is enabled\. See - the __openssl__ documentation for the required structure of this - directory\. - - - __::dns::configure__ ?*options*? - - The __::dns::configure__ command is used to setup the dns package\. The - server to query, the protocol and domain search path are all set via this - command\. If no arguments are provided then a list of all the current - settings is returned\. If only one argument then it must the the name of an - option and the value for that option is returned\. - - * __\-nameserver__ *hostname* - - Set the default name server to be used by all queries\. The default is - *localhost*\. - - * __\-protocol__ *tcp|udp* - - Set the default network protocol to be used\. Default is *tcp*\. - - * __\-port__ *portnum* - - Set the default port to use on the name server\. The default is 53\. - - * __\-search__ *domainlist* - - Set the domain search list\. This is currently not used\. - - * __\-timeout__ *milliseconds* - - Set the default timeout value for DNS lookups\. Default is 30 seconds\. - - * __\-loglevel__ *level* - - Set the log level used for emitting diagnostic messages from this - package\. The default is *warn*\. See the - __[log](\.\./log/log\.md)__ package for details of the available - levels\. - - * __\-cafile__ *filepath* - - Set the default file path to be used for the __\-cafile__ option to - __dns::resolve__\. - - * __\-cadir__ *dirpath* - - Set the default directory path to be used for the __\-cadir__ option - to __dns::resolve__\. - - - __::dns::name__ *token* - - Returns a list of all domain names returned as an answer to your query\. - - - __::dns::address__ *token* - - Returns a list of the address records that match your query\. - - - __::dns::cname__ *token* - - Returns a list of canonical names \(usually just one\) matching your query\. - - - __::dns::result__ *token* - - Returns a list of all the decoded answer records provided for your query\. - This permits you to extract the result for more unusual query types\. - - - __::dns::status__ *token* - - Returns the status flag\. For a successfully completed query this will be - *ok*\. May be *error* or *timeout* or *eof*\. See also - __::dns::error__ - - - __::dns::error__ *token* - - Returns the error message provided for requests whose status is *error*\. - If there is no error message then an empty string is returned\. - - - __::dns::reset__ *token* - - Reset or cancel a DNS query\. - - - __::dns::wait__ *token* - - Wait for a DNS query to complete and return the status upon completion\. - - - __::dns::cleanup__ *token* - - Remove all state variables associated with the request\. - - - __::dns::nameservers__ - - Attempts to return a list of the nameservers currently configured for the - users system\. On a unix machine this parses the /etc/resolv\.conf file for - nameservers \(if it exists\) and on Windows systems we examine certain parts - of the registry\. If no nameserver can be found then the loopback address - \(127\.0\.0\.1\) is used as a default\. - -# EXAMPLES - - % set tok [dns::resolve www.tcl.tk] - ::dns::1 - % dns::status $tok - ok - % dns::address $tok - 199.175.6.239 - % dns::name $tok - www.tcl.tk - % dns::cleanup $tok - -Using DNS URIs as queries: - - % set tok [dns::resolve "dns:tcl.tk;type=MX"] - % set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"] - -Reverse address lookup: - - % set tok [dns::resolve 127.0.0.1] - ::dns::1 - % dns::name $tok - localhost - % dns::cleanup $tok - -Using DNS over TLS \(RFC 7858\): - - % set tok [dns::resolve www.tcl.tk -nameserver dns-tls.bitwiseshift.net -usetls 1 -cafile /etc/ssl/certs/ca-certificates.crt] - ::dns::12 - % dns::wait $tok - ok - % dns::address $tok - 104.25.119.118 104.25.120.118 - -# REFERENCES - - 1. Mockapetris, P\., "Domain Names \- Concepts and Facilities", RFC 1034, - November 1987\. - \([http://www\.ietf\.org/rfc/rfc1034\.txt](http://www\.ietf\.org/rfc/rfc1034\.txt)\) - - 1. Mockapetris, P\., "Domain Names \- Implementation and Specification", RFC - 1035, November 1087\. - \([http://www\.ietf\.org/rfc/rfc1035\.txt](http://www\.ietf\.org/rfc/rfc1035\.txt)\) - - 1. Thompson, S\. and Huitema, C\., "DNS Extensions to support IP version 6", RFC - 1886, December 1995\. - \([http://www\.ietf\.org/rfc/rfc1886\.txt](http://www\.ietf\.org/rfc/rfc1886\.txt)\) - - 1. Josefsson, S\., "Domain Name System Uniform Resource Identifiers", - Internet\-Draft, October 2003, - \([http://www\.ietf\.org/internet\-drafts/draft\-josefsson\-dns\-url\-09\.txt](http://www\.ietf\.org/internet\-drafts/draft\-josefsson\-dns\-url\-09\.txt)\) - - 1. Gulbrandsen, A\., Vixie, P\. and Esibov, L\., "A DNS RR for specifying the - location of services \(DNS SRV\)", RFC 2782, February 2000, - \([http://www\.ietf\.org/rfc/rfc2782\.txt](http://www\.ietf\.org/rfc/rfc2782\.txt)\) - - 1. Ohta, M\. "Incremental Zone Transfer in DNS", RFC 1995, August 1996, - \([http://www\.ietf\.org/rfc/rfc1995\.txt](http://www\.ietf\.org/rfc/rfc1995\.txt)\) - - 1. Hu, Z\., etc al\. "Specification for DNS over Transport Layer Security - \(TLS\)", RFC 7858, May 2016, - \([http://www\.ietf\.org/rfc/rfc7858\.txt](http://www\.ietf\.org/rfc/rfc7858\.txt)\) - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *dns* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -resolver\(5\) - -# KEYWORDS - -[DNS](\.\./\.\./\.\./\.\./index\.md\#dns), [domain name -service](\.\./\.\./\.\./\.\./index\.md\#domain\_name\_service), -[resolver](\.\./\.\./\.\./\.\./index\.md\#resolver), [rfc -1034](\.\./\.\./\.\./\.\./index\.md\#rfc\_1034), [rfc -1035](\.\./\.\./\.\./\.\./index\.md\#rfc\_1035), [rfc -1886](\.\./\.\./\.\./\.\./index\.md\#rfc\_1886), [rfc -7858](\.\./\.\./\.\./\.\./index\.md\#rfc\_7858) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/dns/tcllib_ip.md Index: embedded/md/tcllib/files/modules/dns/tcllib_ip.md ================================================================== --- embedded/md/tcllib/files/modules/dns/tcllib_ip.md +++ embedded/md/tcllib/files/modules/dns/tcllib_ip.md @@ -1,424 +0,0 @@ - -[//000000001]: # (tcllib\_ip \- Domain Name Service) -[//000000002]: # (Generated from file 'tcllib\_ip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Pat Thoyts) -[//000000004]: # (Copyright © 2005 Aamer Akhter ) -[//000000005]: # (tcllib\_ip\(n\) 1\.4 tcllib "Domain Name Service") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcllib\_ip \- IPv4 and IPv6 address manipulation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require ip ?1\.4? - -[__::ip::version__ *address*](#1) -[__::ip::is__ *class* *address*](#2) -[__::ip::equal__ *address* *address*](#3) -[__::ip::normalize__ *address*](#4) -[__::ip::contract__ *address*](#5) -[__::ip::distance__ *ipaddr1* *ipaddr2*](#6) -[__::ip::nextIp__ *ipaddr* ?*offset*?](#7) -[__::ip::prefix__ *address*](#8) -[__::ip::type__ *address*](#9) -[__::ip::mask__ *address*](#10) -[__::ip::prefixToNative__ *prefix*](#11) -[__::ip::nativeToPrefix__ *nativeList*|*native* ?__\-ipv4__?](#12) -[__::ip::intToString__ *number* ?__\-ipv4__?](#13) -[__::ip::toInteger__ *ipaddr*](#14) -[__::ip::toHex__ *ipaddr*](#15) -[__::ip::maskToInt__ *ipmask*](#16) -[__::ip::broadcastAddress__ *prefix* ?__\-ipv4__?](#17) -[__::ip::maskToLength__ *dottedMask*|*integerMask*|*hexMask* ?__\-ipv4__?](#18) -[__::ip::lengthToMask__ *maskLength* ?__\-ipv4__?](#19) -[__::ip::nextNet__ *ipaddr* *ipmask* ?*count*? ?__\-ipv4__?](#20) -[__::ip::isOverlap__ *prefix* *prefix*\.\.\.](#21) -[__::ip::isOverlapNative__ ?__\-all__? ?__\-inline__? ?__\-ipv4__? *hexipaddr* *hexipmask* *hexiplist*](#22) -[__::ip::ipToLayer2Multicast__ *ipaddr*](#23) -[__::ip::ipHostFromPrefix__ *prefix* ?__\-exclude__ *prefixExcludeList*?](#24) -[__::ip::reduceToAggregates__ *prefixlist*](#25) -[__::ip::longestPrefixMatch__ *ipaddr* *prefixlist* ?__\-ipv4__?](#26) -[__::ip::collapse__ *prefixlist*](#27) -[__::ip::subtract__ *prefixlist*](#28) - -# DESCRIPTION - -This package provides a set of commands to help in parsing, displaying and -comparing internet addresses\. The package can handle both IPv4 \(1\) and IPv6 \(2\) -address types\. - -# COMMANDS - - - __::ip::version__ *address* - - Returns the protocol version of the address \(__4__ or __6__\), or - __\-1__ if the address is neither IPv4 or IPv6\. - - - __::ip::is__ *class* *address* - - Returns true if the address is a member of the given protocol class\. The - class parameter may be either __ipv4__ or __ipv6__ This is - effectively a boolean equivalent of the __version__ command\. The - *class* argument may be shortened to __4__ or __6__\. - - - __::ip::equal__ *address* *address* - - Compare two address specifications for equivalence\. The arguments are - normalized and the address prefix determined \(if a mask is supplied\)\. The - normalized addresses are then compared bit\-by\-bit and the procedure returns - true if they match\. - - - __::ip::normalize__ *address* - - Convert an IPv4 or IPv6 address into a fully expanded version\. There are - various shorthand ways to write internet addresses, missing out redundant - parts or digits\. This procedure is the opposite of __contract__\. - - - __::ip::contract__ *address* - - Convert a __normalize__d internet address into a more compact form - suitable for displaying to users\. - - - __::ip::distance__ *ipaddr1* *ipaddr2* - - This command computes the \(integer\) distance from IPv4 address *ipaddr1* - to IPv4 address *ipaddr2*, i\.e\. "ipaddr2 \- ipaddr1" - - % ::ip::distance 1.1.1.1 1.1.1.5 - 4 - - - __::ip::nextIp__ *ipaddr* ?*offset*? - - This command adds the integer *offset* to the IPv4 address *ipaddr* and - returns the new IPv4 address\. - - % ::ip::distance 1.1.1.1 4 - 1.1.1.5 - - - __::ip::prefix__ *address* - - Returns the address prefix generated by masking the address part with the - mask if provided\. If there is no mask then it is equivalent to calling - __normalize__ - - - __::ip::type__ *address* - - - __::ip::mask__ *address* - - If the address supplied includes a mask then this is returned otherwise - returns an empty string\. - - - __::ip::prefixToNative__ *prefix* - - This command converts the string *prefix* from dotted form - \(/ format\) to native \(hex\) form\. Returns a list containing two - elements, ipaddress and mask, in this order, in hexadecimal notation\. - - % ip::prefixToNative 1.1.1.0/24 - 0x01010100 0xffffff00 - - - __::ip::nativeToPrefix__ *nativeList*|*native* ?__\-ipv4__? - - This command converts from native \(hex\) form to dotted form\. It is the - complement of __::ip::prefixToNative__\. - - * list *nativeList* \(in\) - - List of several ip addresses in native form\. The native form is a list - as returned by __::ip::prefixToNative__\. - - * list *native* \(in\) - - A list as returned by __::ip::prefixToNative__\. - - The command returns a list of addresses in dotted form if it was called with - a list of addresses\. Otherwise a single address in dotted form is returned\. - - % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4 - 1.1.1.0/24 - - - __::ip::intToString__ *number* ?__\-ipv4__? - - This command converts from an ip address specified as integer number to - dotted form\. - - ip::intToString 4294967295 - 255.255.255.255 - - - __::ip::toInteger__ *ipaddr* - - This command converts a dotted form ip into an integer number\. - - % ::ip::toInteger 1.1.1.0 - 16843008 - - - __::ip::toHex__ *ipaddr* - - This command converts dotted form ip into a hexadecimal number\. - - % ::ip::toHex 1.1.1.0 - 0x01010100 - - - __::ip::maskToInt__ *ipmask* - - This command convert an ipmask in either dotted \(255\.255\.255\.0\) form or mask - length form \(24\) into an integer number\. - - ::ip::maskToInt 24 - 4294967040 - - - __::ip::broadcastAddress__ *prefix* ?__\-ipv4__? - - This commands returns a broadcast address in dotted form for the given route - *prefix*, either in the form "addr/mask", or in native form\. The result is - in dotted form\. - - ::ip::broadcastAddress 1.1.1.0/24 - 1.1.1.255 - - ::ip::broadcastAddress {0x01010100 0xffffff00} - 0x010101ff - - - __::ip::maskToLength__ *dottedMask*|*integerMask*|*hexMask* ?__\-ipv4__? - - This command converts the dotted or integer form of an ipmask to the mask - length form\. - - ::ip::maskToLength 0xffffff00 -ipv4 - 24 - - % ::ip::maskToLength 255.255.255.0 - 24 - - - __::ip::lengthToMask__ *maskLength* ?__\-ipv4__? - - This command converts an ipmask in mask length form to its dotted form\. - - ::ip::lengthToMask 24 - 255.255.255.0 - - - __::ip::nextNet__ *ipaddr* *ipmask* ?*count*? ?__\-ipv4__? - - This command returns an ipaddress in the same position in the *count* next - network\. The default value for *count* is __1__\. - - The address can be specified as either integer number or in dotted form\. The - mask can be specified as either integer number, dotted form, or mask length - form\. - - The result is in hex form\. - - - __::ip::isOverlap__ *prefix* *prefix*\.\.\. - - This command checks if the given ip prefixes overlap\. All arguments are in - dotted "addr/mask" form\. All arguments after the first prefix are compared - against the first prefix\. The result is a boolean value\. It is true if an - overlap was found for any of the prefixes\. - - % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 - 0 - - ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32 - 1 - - - __::ip::isOverlapNative__ ?__\-all__? ?__\-inline__? ?__\-ipv4__? *hexipaddr* *hexipmask* *hexiplist* - - This command is similar to __::ip::isOverlap__, however the arguments - are in the native form, and the form of the result is under greater control - of the caller\. If the option __\-all__ is specified it checks all - addresses for overlap, not only until the first one is found\. If the option - __\-inline__ is specified the command returns the overlapping prefix - instead of index values\. - - The result of the command is, depending on the specified options, - - * no options - - The index of the first overlap found, or 0 if there is none\. - - * \-all - - A list containing the indices of all overlaps found, or an empty list if - there are none\. - - * \-inline - - The first overlapping prefix, or an empoty string if there is none\. - - * \-all \-inline - - A list containing the prefixes of all overlaps found, or an empty list - if there are none\. - - % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}} - 0 - - % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}} - 2 - - - __::ip::ipToLayer2Multicast__ *ipaddr* - - This command an converts ipv4 address in dotted form into a layer 2 - multicast address, also in dotted form\. - - % ::ip::ipToLayer2Multicast 224.0.0.2 - 01.00.5e.00.00.02 - - - __::ip::ipHostFromPrefix__ *prefix* ?__\-exclude__ *prefixExcludeList*? - - This command returns a host address from a prefix in the form - "ipaddr/masklen", also making sure that the result is not an address found - in the *prefixExcludeList*\. The result is an ip address in dotted form\. - - %::ip::ipHostFromPrefix 1.1.1.5/24 - 1.1.1.1 - - %::ip::ipHostFromPrefix 1.1.1.1/32 - 1.1.1.1 - - - __::ip::reduceToAggregates__ *prefixlist* - - This command finds nets that overlap and filters out the more specific nets\. - The prefixes are in either addr/mask form or in native format\. The result is - a list containing the non\-overlapping ip prefixes from the input\. - - % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8 2.1.1.0/24 1.1.1.1/32 } - 1.0.0.0/8 2.1.1.0/24 - - - __::ip::longestPrefixMatch__ *ipaddr* *prefixlist* ?__\-ipv4__? - - This command finds longest prefix match from set of prefixes, given a - specific host address\. The prefixes in the list are in either native or - dotted form, whereas the host address is in either ipprefix format, dotted - form, or integer form\. The result is the prefix which is the most specific - match to the host address\. - - % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8 2.1.1.0/24 1.1.1.0/28 } - 1.1.1.0/28 - - - __::ip::collapse__ *prefixlist* - - This commands takes a list of prefixes and returns a list prefixes with the - largest possible subnet masks covering the input, in this manner collapsing - adjacent prefixes into larger ranges\. - - This is different from __::ip::reduceToAggregates__ in that the latter - only removes specific nets from a list when they are covered by other - elements of the input whereas this command actively merges nets into larger - ranges when they are adjacent to each other\. - - % ::ip::collapse {1.2.2.0/24 1.2.3.0/24} - 1.2.2.0/23 - - - __::ip::subtract__ *prefixlist* - - This command takes a list of prefixes, some of which are prefixed by a dash\. - These latter *negative* prefixes are used to punch holes into the ranges - described by the other, *positive*, prefixes\. I\.e\. the negative prefixes - are subtracted frrom the positive ones, resulting in a larger list of - describes describing the covered ranges only as positives\. - -# EXAMPLES - - % ip::version ::1 - 6 - % ip::version 127.0.0.1 - 4 - - % ip::normalize 127/8 - 127.0.0.0/8 - % ip::contract 192.168.0.0 - 192.168 - % - % ip::normalize fec0::1 - fec0:0000:0000:0000:0000:0000:0000:0001 - % ip::contract fec0:0000:0000:0000:0000:0000:0000:0001 - fec0::1 - - % ip::equal 192.168.0.4/16 192.168.0.0/16 - 1 - % ip::equal fec0::1/10 fec0::fe01/10 - 1 - -# REFERENCES - - 1. Postel, J\. "Internet Protocol\." RFC 791, September 1981, - \([http://www\.ietf\.org/rfc/rfc791\.txt](http://www\.ietf\.org/rfc/rfc791\.txt)\) - - 1. Hinden, R\. and Deering, S\., "Internet Protocol Version 6 \(IPv6\) Addressing - Architecture", RFC 3513, April 2003 - \([http://www\.ietf\.org/rfc/rfc3513\.txt](http://www\.ietf\.org/rfc/rfc3513\.txt)\) - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *dns* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -inet\(3\), ip\(7\), ipv6\(7\) - -# KEYWORDS - -[internet address](\.\./\.\./\.\./\.\./index\.md\#internet\_address), -[ip](\.\./\.\./\.\./\.\./index\.md\#ip), [ipv4](\.\./\.\./\.\./\.\./index\.md\#ipv4), -[ipv6](\.\./\.\./\.\./\.\./index\.md\#ipv6), [rfc -3513](\.\./\.\./\.\./\.\./index\.md\#rfc\_3513) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2004, Pat Thoyts -Copyright © 2005 Aamer Akhter DELETED embedded/md/tcllib/files/modules/docstrip/docstrip.md Index: embedded/md/tcllib/files/modules/docstrip/docstrip.md ================================================================== --- embedded/md/tcllib/files/modules/docstrip/docstrip.md +++ embedded/md/tcllib/files/modules/docstrip/docstrip.md @@ -1,449 +0,0 @@ - -[//000000001]: # (docstrip \- Literate programming tool) -[//000000002]: # (Generated from file 'docstrip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003–2010 Lars Hellström ) -[//000000004]: # (docstrip\(n\) 1\.2 tcllib "Literate programming tool") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docstrip \- Docstrip style source code extraction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [File format](#section2) - - - [Commands](#section3) - - - [Document structure](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require docstrip ?1\.2? - -[__docstrip::extract__ *text* *terminals* ?*option* *value* \.\.\.?](#1) -[__docstrip::sourcefrom__ *filename* *terminals* ?*option* *value* \.\.\.?](#2) - -# DESCRIPTION - -__Docstrip__ is a tool created to support a brand of Literate Programming\. -It is most common in the \(La\)TeX community, where it is being used for pretty -much everything from the LaTeX core and up, but there is nothing about -__docstrip__ which prevents using it for other types of software\. - -In short, the basic principle of literate programming is that program source -should primarily be written and structured to suit the developers \(and advanced -users who want to peek "under the hood"\), not to suit the whims of a compiler or -corresponding source code consumer\. This means literate sources often need some -kind of "translation" to an illiterate form that dumb software can understand\. -The __docstrip__ Tcl package handles this translation\. - -Even for those who do not whole\-hartedly subscribe to the philosophy behind -literate programming, __docstrip__ can bring greater clarity to in -particular: - - - programs employing non\-obvious mathematics - - - projects where separate pieces of code, perhaps in different languages, need - to be closely coordinated\. - -The first is by providing access to much more powerful typographical features -for source code comments than are possible in plain text\. The second is because -all the separate pieces of code can be kept next to each other in the same -source file\. - -The way it works is that the programmer edits directly only one or several -"master" source code files, from which __docstrip__ generates the more -traditional "source" files compilers or the like would expect\. The master -sources typically contain a large amount of documentation of the code, sometimes -even in places where the code consumers would not allow any comments\. The -etymology of "docstrip" is that this *doc*umentation was *strip*ped away -\(although "code extraction" might be a better description, as it has always been -a matter of copying selected pieces of the master source rather than deleting -text from it\)\. The __docstrip__ Tcl package contains a reimplementation of -the basic extraction functionality from the __docstrip__ program, and thus -makes it possible for a Tcl interpreter to read and interpret the master source -files directly\. - -Readers who are not previously familiar with __docstrip__ but want to know -more about it may consult the following sources\. - - 1. *The tclldoc package and class*, - [http://ctan\.org/tex\-archive/macros/latex/contrib/tclldoc/](http://ctan\.org/tex\-archive/macros/latex/contrib/tclldoc/)\. - - 1. *The DocStrip utility*, - [http://ctan\.org/tex\-archive/macros/latex/base/docstrip\.dtx](http://ctan\.org/tex\-archive/macros/latex/base/docstrip\.dtx)\. - - 1. *The doc and shortvrb Packages*, - [http://ctan\.org/tex\-archive/macros/latex/base/doc\.dtx](http://ctan\.org/tex\-archive/macros/latex/base/doc\.dtx)\. - - 1. Chapter 14 of *The LaTeX Companion* \(second edition\), Addison\-Wesley, - 2004; ISBN 0\-201\-36299\-6\. - -# File format - -The basic unit __docstrip__ operates on are the *lines* of a master source -file\. Extraction consists of selecting some of these lines to be copied from -input text to output text\. The basic distinction is that between *code lines* -\(which are copied and do not begin with a percent character\) and *comment -lines* \(which begin with a percent character and are not copied\)\. - - docstrip::extract [join { - {% comment} - {% more comment !"#$%&/(} - {some command} - { % blah $blah "Not a comment."} - {% abc; this is comment} - {# def; this is code} - {ghi} - {% jkl} - } \n] {} - -returns the same sequence of lines as - - join { - {some command} - { % blah $blah "Not a comment."} - {# def; this is code} - {ghi} "" - } \n - -It does not matter to __docstrip__ what format is used for the documentation -in the comment lines, but in order to do better than plain text comments, one -typically uses some markup language\. Most commonly LaTeX is used, as that is a -very established standard and also provides the best support for mathematical -formulae, but the __docstrip::util__ package also gives some support for -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)*\-like markup\. - -Besides the basic code and comment lines, there are also *guard lines*, which -begin with the two characters '%<', and *meta\-comment lines*, which begin with -the two characters '%%'\. Within guard lines there is furthermore the distinction -between *verbatim guard lines*, which begin with '%<<', and ordinary guard -lines, where the '%<' is not followed by another '<'\. The last category is by -far the most common\. - -Ordinary guard lines conditions extraction of the code line\(s\) they guard by the -value of a boolean expression; the guarded block of code lines will only be -included if the expression evaluates to true\. The syntax of an ordinary guard -line is one of - - '%' '<' STARSLASH EXPRESSION '>' - '%' '<' PLUSMINUS EXPRESSION '>' CODE - -where - - STARSLASH ::= '*' | '/' - PLUSMINUS ::= | '+' | '-' - EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION - | SECONDARY '|' EXPRESSION - SECONDARY ::= PRIMARY | PRIMARY '&' SECONDARY - PRIMARY ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')' - CODE ::= { any character except end-of-line } - -Comma and vertical bar both denote 'or'\. Ampersand denotes 'and'\. Exclamation -mark denotes 'not'\. A TERMINAL can be any nonempty string of characters not -containing '>', '&', '|', comma, '\(', or '\)', although the __docstrip__ -manual is a bit restrictive and only guarantees proper operation for strings of -letters \(although even the LaTeX core sources make heavy use also of digits in -TERMINALs\)\. The second argument of __docstrip::extract__ is the list of -those TERMINALs that should count as having the value 'true'; all other -TERMINALs count as being 'false' when guard expressions are evaluated\. - -In the case of a '%<\**EXPRESSION*>' guard, the lines guarded are all lines up -to the next '%' guard with the same *EXPRESSION* \(compared as -strings\)\. The blocks of code delimited by such '\*' and '/' guard lines must be -properly nested\. - - set text [join { - {begin} - {%<*foo>} - {1} - {%<*bar>} - {2} - {%} - {%<*!bar>} - {3} - {%} - {4} - {%} - {5} - {%<*bar>} - {6} - {%} - {end} - } \n] - set res [docstrip::extract $text foo] - append res [docstrip::extract $text {foo bar}] - append res [docstrip::extract $text bar] - -sets $res to the result of - - join { - {begin} - {1} - {3} - {4} - {5} - {end} - {begin} - {1} - {2} - {4} - {5} - {6} - {end} - {begin} - {5} - {6} - {end} "" - } \n - -In guard lines without a '\*', '/', '\+', or '\-' modifier after the '%<', the -guard applies only to the CODE following the '>' on that single line\. A '\+' -modifier is equivalent to no modifier\. A '\-' modifier is like the case with no -modifier, but the expression is implicitly negated, i\.e\., the CODE of a '%<\-' -guard line is only included if the expression evaluates to false\. - -Metacomment lines are "comment lines which should not be stripped away", but be -extracted like code lines; these are sometimes used for copyright notices and -similar material\. The '%%' prefix is however not kept, but substituted by the -current __\-metaprefix__, which is customarily set to some "comment until end -of line" character \(or character sequence\) of the language of the code being -extracted\. - - set text [join { - {begin} - {% foo} - {%<+foo>plusfoo} - {%<-foo>minusfoo} - {middle} - {%% some metacomment} - {%<*foo>} - {%%another metacomment} - {%} - {end} - } \n] - set res [docstrip::extract $text foo -metaprefix {# }] - append res [docstrip::extract $text bar -metaprefix {#}] - -sets $res to the result of - - join { - {begin} - { foo} - {plusfoo} - {middle} - {# some metacomment} - {# another metacomment} - {end} - {begin} - {minusfoo} - {middle} - {# some metacomment} - {end} "" - } \n - -Verbatim guards can be used to force code line interpretation of a block of -lines even if some of them happen to look like any other type of lines to -docstrip\. A verbatim guard has the form '%<<*END\-TAG*' and the verbatim block -is terminated by the first line that is exactly '%*END\-TAG*'\. - - set text [join { - {begin} - {%<*myblock>} - {some stupid()} - { #computer} - {%<} - {%QQQ-98765} - { using*strange@programming} - {%} - {end} - } \n] - set res [docstrip::extract $text myblock -metaprefix {# }] - append res [docstrip::extract $text {}] - -sets $res to the result of - - join { - {begin} - {some stupid()} - { #computer} - {% These three lines are copied verbatim (including percents} - {%% even if -metaprefix is something different than %%).} - {%} - { using*strange@programming} - {end} - {begin} - {end} "" - } \n - -The processing of verbatim guards takes place also inside blocks of lines which -due to some outer block guard will not be copied\. - -The final piece of __docstrip__ syntax is that extraction stops at a line -that is exactly "\\endinput"; this is often used to avoid copying random -whitespace at the end of a file\. In the unlikely case that one wants such a code -line, one can protect it with a verbatim guard\. - -# Commands - -The package defines two commands\. - - - __docstrip::extract__ *text* *terminals* ?*option* *value* \.\.\.? - - The __extract__ command docstrips the *text* and returns the extracted - lines of code, as a string with each line terminated with a newline\. The - *terminals* is the list of those guard expression terminals which should - evaluate to true\. The available options are: - - * __\-annotate__ *lines* - - Requests the specified number of lines of annotation to follow each - extracted line in the result\. Defaults to 0\. Annotation lines are mostly - useful when the extracted lines are to undergo some further - transformation\. A first annotation line is a list of three elements: - line type, prefix removed in extraction, and prefix inserted in - extraction\. The line type is one of: 'V' \(verbatim\), 'M' \(metacomment\), - '\+' \(\+ or no modifier guard line\), '\-' \(\- modifier guard line\), '\.' - \(normal line\)\. A second annotation line is the source line number\. A - third annotation line is the current stack of block guards\. Requesting - more than three lines of annotation is currently not supported\. - - * __\-metaprefix__ *string* - - The string by which the '%%' prefix of a metacomment line will be - replaced\. Defaults to '%%'\. For Tcl code this would typically be '\#'\. - - * __\-onerror__ *keyword* - - Controls what will be done when a format error in the *text* being - processed is detected\. The settings are: - - + __ignore__ - - Just ignore the error; continue as if nothing happened\. - - + __puts__ - - Write an error message to __stderr__, then continue processing\. - - + __throw__ - - Throw an error\. The __\-errorcode__ is set to a list whose first - element is __DOCSTRIP__, second element is the type of error, - and third element is the line number where the error is detected\. - This is the default\. - - * __\-trimlines__ *boolean* - - Controls whether *spaces* at the end of a line should be trimmed away - before the line is processed\. Defaults to true\. - - It should be remarked that the *terminals* are often called "options" in - the context of the __docstrip__ program, since these specify which - optional code fragments should be included\. - - - __docstrip::sourcefrom__ *filename* *terminals* ?*option* *value* \.\.\.? - - The __sourcefrom__ command is a docstripping emulation of - __[source](\.\./\.\./\.\./\.\./index\.md\#source)__\. It opens the file - *filename*, reads it, closes it, docstrips the contents as specified by - the *terminals*, and evaluates the result in the local context of the - caller, during which time the __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ - __script__ value will be the *filename*\. The options are passed on to - __fconfigure__ to configure the file before its contents are read\. The - __\-metaprefix__ is set to '\#', all other __extract__ options have - their default values\. - -# Document structure - -The file format \(as described above\) determines whether a master source code -file can be processed correctly by __docstrip__, but the usefulness of the -format is to no little part also dependent on that the code and comment lines -together constitute a well\-formed document\. - -For a document format that does not require any non\-Tcl software, see the -__ddt2man__ command in the __docstrip::util__ package\. It is suggested -that files employing that document format are given the suffix "\.ddt", to -distinguish them from the more traditional LaTeX\-based "\.dtx" files\. - -Master source files with "\.dtx" extension are usually set up so that they can be -typeset directly by __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ without any -support from other files\. This is achieved by beginning the file with the lines - ->    % \\iffalse ->    %<\*driver> ->    \\documentclass\{tclldoc\} ->    \\begin\{document\} ->    \\DocInput\{*filename\.dtx*\} ->    \\end\{document\} ->    % ->    % \\fi - -or some variation thereof\. The trick is that the file gets read twice\. With -normal LaTeX reading rules, the first two lines are comments and therefore -ignored\. The third line is the document preamble, the fourth line begins the -document body, and the sixth line ends the document, so LaTeX stops there — -non\-comments below that point in the file are never subjected to the normal -LaTeX reading rules\. Before that, however, the \\DocInput command on the fifth -line is processed, and that does two things: it changes the interpretation of -'%' from "comment" to "ignored", and it inputs the file specified in the -argument \(which is normally the name of the file the command is in\)\. It is this -second time that the file is being read that the comments and code in it are -typeset\. - -The function of the \\iffalse \.\.\. \\fi is to skip lines two to seven on this -second time through; this is similar to the "if 0 \{ \.\.\. \}" idiom for block -comments in Tcl code, and it is needed here because \(amongst other things\) the -\\documentclass command may only be executed once\. The function of the -guards is to prevent this short piece of LaTeX code from being extracted by -__docstrip__\. The total effect is that the file can function both as a LaTeX -document and as a __docstrip__ master source code file\. - -It is not necessary to use the tclldoc document class, but that does provide a -number of features that are convenient for "\.dtx" files containing Tcl code\. -More information on this matter can be found in the references above\. - -# SEE ALSO - -[docstrip\_util](docstrip\_util\.md) - -# KEYWORDS - -[\.dtx](\.\./\.\./\.\./\.\./index\.md\#\_dtx), [LaTeX](\.\./\.\./\.\./\.\./index\.md\#latex), -[docstrip](\.\./\.\./\.\./\.\./index\.md\#docstrip), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), [literate -programming](\.\./\.\./\.\./\.\./index\.md\#literate\_programming), -[source](\.\./\.\./\.\./\.\./index\.md\#source) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003–2010 Lars Hellström DELETED embedded/md/tcllib/files/modules/docstrip/docstrip_util.md Index: embedded/md/tcllib/files/modules/docstrip/docstrip_util.md ================================================================== --- embedded/md/tcllib/files/modules/docstrip/docstrip_util.md +++ embedded/md/tcllib/files/modules/docstrip/docstrip_util.md @@ -1,672 +0,0 @@ - -[//000000001]: # (docstrip\_util \- Literate programming tool) -[//000000002]: # (Generated from file 'docstrip\_util\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003–2010 Lars Hellström ) -[//000000004]: # (docstrip\_util\(n\) 1\.3\.1 tcllib "Literate programming tool") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docstrip\_util \- Docstrip\-related utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Package indexing commands](#section2) - - - [Source processing commands](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require docstrip ?1\.2? -package require docstrip::util ?1\.3\.1? - -[__pkgProvide__ *name* *version* *terminals*](#1) -[__pkgIndex__ ?*terminal* \.\.\.?](#2) -[__fileoptions__ ?*option* *value* \.\.\.?](#3) -[__docstrip::util::index\_from\_catalogue__ *dir* *pattern* ?*option* *value* \.\.\.?](#4) -[__docstrip::util::modules\_from\_catalogue__ *target* *source* ?*option* *value* \.\.\.?](#5) -[__docstrip::util::classical\_preamble__ *metaprefix* *message* *target* ?*source* *terminals* \.\.\.?](#6) -[__docstrip::util::classical\_postamble__ *metaprefix* *message* *target* ?*source* *terminals* \.\.\.?](#7) -[__docstrip::util::packages\_provided__ *text* ?*setup\-script*?](#8) -[__docstrip::util::ddt2man__ *text*](#9) -[__docstrip::util::guards__ *subcmd* *text*](#10) -[__docstrip::util::patch__ *source\-var* *terminals* *fromtext* *diff* ?*option* *value* \.\.\.?](#11) -[__docstrip::util::thefile__ *filename* ?*option* *value* \.\.\.?](#12) -[__docstrip::util::import\_unidiff__ *diff\-text* ?*warning\-var*?](#13) - -# DESCRIPTION - -The __docstrip::util__ package is meant for collecting various utility -procedures that are mainly useful at installation or development time\. It is -separate from the base package to avoid overhead when the latter is used to -__[source](\.\./\.\./\.\./\.\./index\.md\#source)__ code\. - -# Package indexing commands - -Like raw "\.tcl" files, code lines in docstrip source files can be searched for -package declarations and corresponding indices constructed\. A complication is -however that one cannot tell from the code blocks themselves which will fit -together to make a working package; normally that information would be found in -an accompanying "\.ins" file, but parsing one of those is not an easy task\. -Therefore __docstrip::util__ introduces an alternative encoding of such -information, in the form of a declarative Tcl script: the -*[catalogue](\.\./\.\./\.\./\.\./index\.md\#catalogue)* \(of the contents in a source -file\)\. - -The special commands which are available inside a catalogue are: - - - __pkgProvide__ *name* *version* *terminals* - - Declares that the code for a package with name *name* and version - *version* is made up from those modules in the source file which are - selected by the *terminals* list of guard expression terminals\. This code - should preferably not contain a - __[package](\.\./\.\./\.\./\.\./index\.md\#package)__ __provide__ command - for the package, as one will be provided by the package loading mechanisms\. - - - __pkgIndex__ ?*terminal* \.\.\.? - - Declares that the code for a package is made up from those modules in the - source file which are selected by the listed guard expression *terminal*s\. - The name and version of this package is determined from - __[package](\.\./\.\./\.\./\.\./index\.md\#package)__ __provide__ - command\(s\) found in that code \(hence there must be such a command in there\)\. - - - __fileoptions__ ?*option* *value* \.\.\.? - - Declares the __fconfigure__ options that should be in force when reading - the source; this can usually be ignored for pure ASCII files, but if the - file needs to be interpreted according to some other __\-encoding__ then - this is how to specify it\. The command should normally appear first in the - catalogue, as it takes effect only for commands following it\. - -Other Tcl commands are supported too — a catalogue is parsed by being evaluated -in a safe interpreter — but they are rarely needed\. To allow for future -extensions, unknown commands in the catalogue are silently ignored\. - -To simplify distribution of catalogues together with their source files, the -catalogue is stored *in the source file itself* as a module selected by the -terminal '__docstrip\.tcl::catalogue__'\. This supports both the style of -collecting all catalogue lines in one place and the style of putting each -catalogue line in close proximity of the code that it declares\. - -Putting catalogue entries next to the code they declare may look as follows - - % First there's the catalogue entry - % \begin{tcl} - %pkgProvide foo::bar 1.0 {foobar load} - % \end{tcl} - % second a metacomment used to include a copyright message - % \begin{macrocode} - %<*foobar> - %% This file is placed in the public domain. - % \end{macrocode} - % third the package implementation - % \begin{tcl} - namespace eval foo::bar { - # ... some clever piece of Tcl code elided ... - % \end{tcl} - % which at some point may have variant code to make use of a - % |load|able extension - % \begin{tcl} - %<*load> - load [file rootname [info script]][info sharedlibextension] - % - %<*!load> - # ... even more clever scripted counterpart of the extension - # also elided ... - % - } - % - % \end{tcl} - % and that's it! - -The corresponding set\-up with __pkgIndex__ would be - - % First there's the catalogue entry - % \begin{tcl} - %pkgIndex foobar load - % \end{tcl} - % second a metacomment used to include a copyright message - % \begin{tcl} - %<*foobar> - %% This file is placed in the public domain. - % \end{tcl} - % third the package implementation - % \begin{tcl} - package provide foo::bar 1.0 - namespace eval foo::bar { - # ... some clever piece of Tcl code elided ... - % \end{tcl} - % which at some point may have variant code to make use of a - % |load|able extension - % \begin{tcl} - %<*load> - load [file rootname [info script]][info sharedlibextension] - % - %<*!load> - # ... even more clever scripted counterpart of the extension - # also elided ... - % - } - % - % \end{tcl} - % and that's it! - - - __docstrip::util::index\_from\_catalogue__ *dir* *pattern* ?*option* *value* \.\.\.? - - This command is a sibling of the standard __pkg\_mkIndex__ command, in - that it adds package entries to "pkgIndex\.tcl" files\. The difference is that - it indexes __[docstrip](docstrip\.md)__\-style source files rather - than raw "\.tcl" or loadable library files\. Only packages listed in the - catalogue of a file are considered\. - - The *dir* argument is the directory in which to look for files \(and whose - "pkgIndex\.tcl" file should be amended\)\. The *pattern* argument is a - __glob__ pattern of files to look into; a typical value would be - __\*\.dtx__ or __\*\.\{dtx,ddt\}__\. Remaining arguments are option\-value - pairs, where the supported options are: - - * __\-recursein__ *dirpattern* - - If this option is given, then the __index\_from\_catalogue__ operation - will be repeated in each subdirectory whose name matches the - *dirpattern*\. __\-recursein__ __\*__ will cause the entire - subtree rooted at *dir* to be indexed\. - - * __\-sourceconf__ *dictionary* - - Specify __fileoptions__ to use when reading the catalogues of files - \(and also for reading the packages if the catalogue does not contain a - __fileoptions__ command\)\. Defaults to being empty\. Primarily useful - if your system encoding is very different from that of the source file - \(e\.g\., one is a two\-byte encoding and the other is a one\-byte encoding\)\. - __ascii__ and __utf\-8__ are not very different in that sense\. - - * __\-options__ *terminals* - - The *terminals* is a list of terminals in addition to - __docstrip\.tcl::catalogue__ that should be held as true when - extracting the catalogue\. Defaults to being empty\. This makes it - possible to make use of "variant sections" in the catalogue itself, e\.g\. - gaurd some entries with an extra "experimental" and thus prevent them - from appearing in the index unless that is generated with "experimental" - among the __\-options__\. - - * __\-report__ *boolean* - - If the *boolean* is true then the return value will be a textual, - probably multiline, report on what was done\. Defaults to false, in which - case there is no particular return value\. - - * __\-reportcmd__ *commandPrefix* - - Every item in the report is handed as an extra argument to the command - prefix\. Since __index\_from\_catalogue__ would typically be used at a - rather high level in installation scripts and the like, the - *commandPrefix* defaults to "__puts__ __stdout__"\. Use - __[list](\.\./\.\./\.\./\.\./index\.md\#list)__ to effectively disable - this feature\. The return values from the prefix are ignored\. - - The __package ifneeded__ scripts that are generated contain one - __package require docstrip__ command and one - __docstrip::sourcefrom__ command\. If the catalogue entry was of the - __pkgProvide__ kind then the __package ifneeded__ script also - contains the __package provide__ command\. - - Note that __index\_from\_catalogue__ never removes anything from an - existing "pkgIndex\.tcl" file\. Hence you may need to delete it \(or have - __pkg\_mkIndex__ recreate it from scratch\) before running - __index\_from\_catalogue__ to update some piece of information, such as a - package version number\. - - - __docstrip::util::modules\_from\_catalogue__ *target* *source* ?*option* *value* \.\.\.? - - This command is an alternative to __index\_from\_catalogue__ which creates - Tcl Module \("\.tm"\) files rather than "pkgIndex\.tcl" entries\. Since this - action is more similar to what __[docstrip](docstrip\.md)__ - classically does, it has features for putting pre\- and postambles on the - generated files\. - - The *source* argument is the name of the source file to generate "\.tm" - files from\. The *target* argument is the directory which should count as a - module path, i\.e\., this is what the relative paths derived from package - names are joined to\. The supported options are: - - * __\-preamble__ *message* - - A message to put in the preamble \(initial block of comments\) of - generated files\. Defaults to a space\. May be several lines, which are - then separated by newlines\. Traditionally used for copyright notices or - the like, but metacomment lines provide an alternative to that\. - - * __\-postamble__ *message* - - Like __\-preamble__, but the message is put at the end of the file - instead of the beginning\. Defaults to being empty\. - - * __\-sourceconf__ *dictionary* - - Specify __fileoptions__ to use when reading the catalogue of the - *source* \(and also for reading the packages if the catalogue does not - contain a __fileoptions__ command\)\. Defaults to being empty\. - Primarily useful if your system encoding is very different from that of - the source file \(e\.g\., one is a two\-byte encoding and the other is a - one\-byte encoding\)\. __ascii__ and __utf\-8__ are not very - different in that sense\. - - * __\-options__ *terminals* - - The *terminals* is a list of terminals in addition to - __docstrip\.tcl::catalogue__ that should be held as true when - extracting the catalogue\. Defaults to being empty\. This makes it - possible to make use of "variant sections" in the catalogue itself, e\.g\. - gaurd some entries with an extra "experimental" guard and thus prevent - them from contributing packages unless those are generated with - "experimental" among the __\-options__\. - - * __\-formatpreamble__ *commandPrefix* - - Command prefix used to actually format the preamble\. Takes four - additional arguments *message*, *targetFilename*, - *sourceFilename*, and *terminalList* and returns a fully formatted - preamble\. Defaults to using __classical\_preamble__ with a - *metaprefix* of '\#\#'\. - - * __\-formatpostamble__ *commandPrefix* - - Command prefix used to actually format the postamble\. Takes four - additional arguments *message*, *targetFilename*, - *sourceFilename*, and *terminalList* and returns a fully formatted - postamble\. Defaults to using __classical\_postamble__ with a - *metaprefix* of '\#\#'\. - - * __\-report__ *boolean* - - If the *boolean* is true \(which is the default\) then the return value - will be a textual, probably multiline, report on what was done\. If it is - false then there is no particular return value\. - - * __\-reportcmd__ *commandPrefix* - - Every item in the report is handed as an extra argument to this command - prefix\. Defaults to __[list](\.\./\.\./\.\./\.\./index\.md\#list)__, which - effectively disables this feature\. The return values from the prefix are - ignored\. Use for example "__puts__ __stdout__" to get report - items written immediately to the terminal\. - - An existing file of the same name as one to be created will be overwritten\. - - - __docstrip::util::classical\_preamble__ *metaprefix* *message* *target* ?*source* *terminals* \.\.\.? - - This command returns a preamble in the classical - __[docstrip](docstrip\.md)__ style - - ## - ## This is `TARGET', - ## generated by the docstrip::util package. - ## - ## The original source files were: - ## - ## SOURCE (with options: `foo,bar') - ## - ## Some message line 1 - ## line2 - ## line3 - - if called as - - docstrip::util::classical_preamble {##}\ - "\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar} - - The command supports preambles for files generated from multiple sources, - even though __modules\_from\_catalogue__ at present does not need that\. - - - __docstrip::util::classical\_postamble__ *metaprefix* *message* *target* ?*source* *terminals* \.\.\.? - - This command returns a postamble in the classical - __[docstrip](docstrip\.md)__ style - - ## Some message line 1 - ## line2 - ## line3 - ## - ## End of file `TARGET'. - - if called as - - docstrip::util::classical_postamble {##}\ - "Some message line 1\nline2\nline3" TARGET SOURCE {foo bar} - - In other words, the *source* and *terminals* arguments are ignored, but - supported for symmetry with __classical\_preamble__\. - - - __docstrip::util::packages\_provided__ *text* ?*setup\-script*? - - This command returns a list where every even index element is the name of a - package __provide__d by *text* when that is evaluated as a Tcl script, - and the following odd index element is the corresponding version\. It is used - to do package indexing of extracted pieces of code, in the manner of - __pkg\_mkIndex__\. - - One difference to __pkg\_mkIndex__ is that the *text* gets evaluated in - a safe interpreter\. __package require__ commands are silently ignored, - as are unknown commands \(which includes - __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ and __load__\)\. Other - errors cause processing of the *text* to stop, in which case only those - package declarations that had been encountered before the error will be - included in the return value\. - - The *setup\-script* argument can be used to customise the evaluation - environment, if the code in *text* has some very special needs\. The - *setup\-script* is evaluated in the local context of the - __packages\_provided__ procedure just before the *text* is processed\. - At that time, the name of the slave command for the safe interpreter that - will do this processing is kept in the local variable __c__\. To for - example copy the contents of the __::env__ array to the safe - interpreter, one might use a *setup\-script* of - - $c eval [list array set env [array get ::env]] - -# Source processing commands - -Unlike the previous group of commands, which would use __docstrip::extract__ -to extract some code lines and then process those further, the following -commands operate on text consisting of all types of lines\. - - - __docstrip::util::ddt2man__ *text* - - The __ddt2man__ command reformats *text* from the general - __[docstrip](docstrip\.md)__ format to - __[doctools](\.\./doctools/doctools\.md)__ "\.man" format \(Tcl Markup - Language for Manpages\)\. The different line types are treated as follows: - - * comment and metacomment lines - - The '%' and '%%' prefixes are removed, the rest of the text is kept as - it is\. - - * empty lines - - These are kept as they are\. \(Effectively this means that they will count - as comment lines after a comment line and as code lines after a code - line\.\) - - * code lines - - __example\_begin__ and __example\_end__ commands are placed at the - beginning and end of every block of consecutive code lines\. Brackets in - a code line are converted to __lb__ and __rb__ commands\. - - * verbatim guards - - These are processed as usual, so they do not show up in the result but - every line in a verbatim block is treated as a code line\. - - * other guards - - These are treated as code lines, except that the actual guard is - __emph__asised\. - - At the time of writing, no project has employed - __[doctools](\.\./doctools/doctools\.md)__ markup in master source - files, so experience of what works well is not available\. A source file - could however look as follows - - % [manpage_begin gcd n 1.0] - % [keywords divisor] - % [keywords math] - % [moddesc {Greatest Common Divisor}] - % [require gcd [opt 1.0]] - % [description] - % - % [list_begin definitions] - % [call [cmd gcd] [arg a] [arg b]] - % The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which - % must be integers and returns their greatest common divisor. - proc gcd {a b} { - % The first step is to take the absolute values of the arguments. - % This relieves us of having to worry about how signs will be treated - % by the remainder operation. - set a [expr {abs($a)}] - set b [expr {abs($b)}] - % The next line does all of Euclid's algorithm! We can make do - % without a temporary variable, since $a is substituted before the - % [lb]set a $b[rb] and thus continues to hold a reference to the - % "old" value of [var a]. - while {$b>0} { set b [expr { $a % [set a $b] }] } - % In Tcl 8.3 we might want to use [cmd set] instead of [cmd return] - % to get the slight advantage of byte-compilation. - % set a - % return $a - } - % [list_end] - % - % [manpage_end] - - If the above text is fed through __docstrip::util::ddt2man__ then the - result will be a syntactically correct - __[doctools](\.\./doctools/doctools\.md)__ manpage, even though its - purpose is a bit different\. - - It is suggested that master source code files with - __[doctools](\.\./doctools/doctools\.md)__ markup are given the suffix - "\.ddt", hence the "ddt" in __ddt2man__\. - - - __docstrip::util::guards__ *subcmd* *text* - - The __guards__ command returns information \(mostly of a statistical - nature\) about the ordinary docstrip guards that occur in the *text*\. The - *subcmd* selects what is returned\. - - * __counts__ - - List the guard expression terminals with counts\. The format of the - return value is a dictionary which maps the terminal name to the number - of occurencies of it in the file\. - - * __exprcount__ - - List the guard expressions with counts\. The format of the return value - is a dictionary which maps the expression to the number of occurencies - of it in the file\. - - * __exprerr__ - - List the syntactically incorrect guard expressions \(e\.g\. parentheses do - not match, or a terminal is missing\)\. The return value is a list, with - the elements in no particular order\. - - * __expressions__ - - List the guard expressions\. The return value is a list, with the - elements in no particular order\. - - * __exprmods__ - - List the guard expressions with modifiers\. The format of the return - value is a dictionary where each index is a guard expression and each - entry is a string with one character for every guard line that has this - expression\. The characters in the entry specify what modifier was used - in that line: \+, \-, \*, /, or \(for guard without modifier:\) space\. This - is the most primitive form of the information gathered by - __guards__\. - - * __names__ - - List the guard expression terminals\. The return value is a list, with - the elements in no particular order\. - - * __rotten__ - - List the malformed guard lines \(this does not include lines where only - the expression is malformed, though\)\. The format of the return value is - a dictionary which maps line numbers to their contents\. - - - __docstrip::util::patch__ *source\-var* *terminals* *fromtext* *diff* ?*option* *value* \.\.\.? - - This command tries to apply a __[diff](\.\./\.\./\.\./\.\./index\.md\#diff)__ - file \(for example a contributed patch\) that was computed for a generated - file to the __[docstrip](docstrip\.md)__ source\. This can be useful - if someone has edited a generated file, thus mistaking it for being the - source\. This command makes no presumptions which are specific for the case - that the generated file is a Tcl script\. - - __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ requires that the source - file to patch is kept as a list of lines in a variable, and the name of that - variable in the calling context is what goes into the *source\-var* - argument\. The *terminals* is the list of terminals used to extract the - file that has been patched\. The *diff* is the actual diff to apply \(in a - format as explained below\) and the *fromtext* is the contents of the file - which served as "from" when the diff was computed\. Options can be used to - further control the process\. - - The process works by "lifting" the hunks in the *diff* from generated to - source file, and then applying them to the elements of the *source\-var*\. - In order to do this lifting, it is necessary to determine how lines in the - *fromtext* correspond to elements of the *source\-var*, and that is where - the *terminals* come in; the source is first __extract__ed under the - given *terminals*, and the result of that is then matched against the - *fromtext*\. This produces a map which translates line numbers stated in - the *diff* to element numbers in *source\-var*, which is what is needed - to lift the hunks\. - - The reason that both the *terminals* and the *fromtext* must be given is - twofold\. First, it is very difficult to keep track of how many lines of - preamble are supplied some other way than by copying lines from source - files\. Second, a generated file might contain material from several source - files\. Both make it impossible to predict what line number an extracted file - would have in the generated file, so instead the algorithm for computing the - line number map looks for a block of lines in the *fromtext* which matches - what can be extracted from the source\. This matching is affected by the - following options: - - * __\-matching__ *mode* - - How equal must two lines be in order to match? The supported *mode*s - are: - - + __exact__ - - Lines must be equal as strings\. This is the default\. - - + __anyspace__ - - All sequences of whitespace characters are converted to single - spaces before comparing\. - - + __nonspace__ - - Only non\-whitespace characters are considered when comparing\. - - + __none__ - - Any two lines are considered to be equal\. - - * __\-metaprefix__ *string* - - The __\-metaprefix__ value to use when extracting\. Defaults to "%%", - but for Tcl code it is more likely that "\#" or "\#\#" had been used for - the generated file\. - - * __\-trimlines__ *boolean* - - The __\-trimlines__ value to use when extracting\. Defaults to true\. - - The return value is in the form of a unified diff, containing only those - hunks which were not applied or were only partially applied; a comment in - the header of each hunk specifies which case is at hand\. It is normally - necessary to manually review both the return value from - __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ and the patched text itself, - as this command cannot adjust comment lines to match new content\. - - An example use would look like - - set sourceL [split [docstrip::util::thefile from.dtx] \n] - set terminals {foo bar baz} - set fromtext [docstrip::util::thefile from.tcl] - set difftext [exec diff --unified from.tcl to.tcl] - set leftover [docstrip::util::patch sourceL $terminals $fromtext\ - [docstrip::util::import_unidiff $difftext] -metaprefix {#}] - set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F - return $leftover - - Here, "from\.dtx" was used as source for "from\.tcl", which someone modified - into "to\.tcl"\. We're trying to construct a "to\.dtx" which can be used as - source for "to\.tcl"\. - - - __docstrip::util::thefile__ *filename* ?*option* *value* \.\.\.? - - The __thefile__ command opens the file *filename*, reads it to end, - closes it, and returns the contents \(dropping a final newline if there is - one\)\. The option\-value pairs are passed on to __fconfigure__ to - configure the open file channel before anything is read from it\. - - - __docstrip::util::import\_unidiff__ *diff\-text* ?*warning\-var*? - - This command parses a unified \(__[diff](\.\./\.\./\.\./\.\./index\.md\#diff)__ - flags __\-U__ and __\-\-unified__\) format diff into the list\-of\-hunks - format expected by __docstrip::util::patch__\. The *diff\-text* argument - is the text to parse and the *warning\-var* is, if specified, the name in - the calling context of a variable to which any warnings about parsing - problems will be __append__ed\. - - The return value is a list of *hunks*\. Each hunk is a list of five - elements "*start1* *end1* *start2* *end2* *lines*"\. *start1* and - *end1* are line numbers in the "from" file of the first and last - respectively lines of the hunk\. *start2* and *end2* are the - corresponding line numbers in the "to" file\. Line numbers start at 1\. The - *lines* is a list with two elements for each line in the hunk; the first - specifies the type of a line and the second is the actual line contents\. The - type is __\-__ for lines only in the "from" file, __\+__ for lines - that are only in the "to" file, and __0__ for lines that are in both\. - -# SEE ALSO - -[docstrip](docstrip\.md), [doctools](\.\./doctools/doctools\.md), -doctools\_fmt - -# KEYWORDS - -[\.ddt](\.\./\.\./\.\./\.\./index\.md\#\_ddt), [\.dtx](\.\./\.\./\.\./\.\./index\.md\#\_dtx), -[LaTeX](\.\./\.\./\.\./\.\./index\.md\#latex), [Tcl -module](\.\./\.\./\.\./\.\./index\.md\#tcl\_module), -[catalogue](\.\./\.\./\.\./\.\./index\.md\#catalogue), -[diff](\.\./\.\./\.\./\.\./index\.md\#diff), -[docstrip](\.\./\.\./\.\./\.\./index\.md\#docstrip), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), [literate -programming](\.\./\.\./\.\./\.\./index\.md\#literate\_programming), -[module](\.\./\.\./\.\./\.\./index\.md\#module), [package -indexing](\.\./\.\./\.\./\.\./index\.md\#package\_indexing), -[patch](\.\./\.\./\.\./\.\./index\.md\#patch), -[source](\.\./\.\./\.\./\.\./index\.md\#source) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003–2010 Lars Hellström DELETED embedded/md/tcllib/files/modules/doctools/changelog.md Index: embedded/md/tcllib/files/modules/doctools/changelog.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/changelog.md +++ embedded/md/tcllib/files/modules/doctools/changelog.md @@ -1,136 +0,0 @@ - -[//000000001]: # (doctools::changelog \- Documentation tools) -[//000000002]: # (Generated from file 'changelog\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2013 Andreas Kupries ) -[//000000004]: # (doctools::changelog\(n\) 1\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::changelog \- Processing text in Emacs ChangeLog format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil -package require doctools::changelog ?1\.1? - -[__::doctools::changelog::scan__ *text*](#1) -[__::doctools::changelog::flatten__ *entries*](#2) -[__::doctools::changelog::toDoctools__ *title* *module* *version* *entries*](#3) -[__::doctools::changelog::merge__ *entries*\.\.\.](#4) - -# DESCRIPTION - -This package provides Tcl commands for the processing and reformatting of text -in the "ChangeLog" format generated by -__[emacs](\.\./\.\./\.\./\.\./index\.md\#emacs)__\. - -# API - - - __::doctools::changelog::scan__ *text* - - The command takes the *text* and parses it under the assumption that it - contains a ChangeLog as generated by - __[emacs](\.\./\.\./\.\./\.\./index\.md\#emacs)__\. It returns a data structure - describing the contents of this ChangeLog\. - - This data structure is a list where each element describes one entry in the - ChangeLog\. Each element/entry is then a list of three elements describing - the date of the entry, its author, and the comments made, in this order\. The - last item in each element/entry, the comments, is a list of sections\. Each - section is described by a list containing two elements, a list of file - names, and a string containing the true comment associated with the files of - the section\. - - { - { - date - author - { - { - {file ...} - commenttext - } - ... - } - } - {...} - } - - - __::doctools::changelog::flatten__ *entries* - - This command converts a list of entries as generated by __change::scan__ - above into a simpler list of plain text blocks each containing all the - information of a single entry\. - - - __::doctools::changelog::toDoctools__ *title* *module* *version* *entries* - - This command converts the pre\-parsed ChangeLog *entries* as generated by - the command __::doctools::changelog::scan__ into a document in - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format and returns it as - the result of the command\. - - The other three arguments supply the information for the header of that - document which is not available from the changelog itself\. - - - __::doctools::changelog::merge__ *entries*\.\.\. - - Each argument of the command is assumed to be a pre\-parsed Changelog as - generated by the command __::doctools::changelog::scan__\. This command - merges all of them into a single structure, and collapses multiple entries - for the same date and author into a single entry\. The new structure is - returned as the result of the command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[changelog](\.\./\.\./\.\./\.\./index\.md\#changelog), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[emacs](\.\./\.\./\.\./\.\./index\.md\#emacs) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003\-2013 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/cvs.md Index: embedded/md/tcllib/files/modules/doctools/cvs.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/cvs.md +++ embedded/md/tcllib/files/modules/doctools/cvs.md @@ -1,143 +0,0 @@ - -[//000000001]: # (doctools::cvs \- Documentation tools) -[//000000002]: # (Generated from file 'cvs\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2008 Andreas Kupries ) -[//000000004]: # (doctools::cvs\(n\) 1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::cvs \- Processing text in 'cvs log' format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil -package require doctools::cvs ?1? - -[__::doctools::cvs::scanLog__ *text* *evar* *cvar* *fvar*](#1) -[__::doctools::cvs::toChangeLog__ *evar* *cvar* *fvar*](#2) - -# DESCRIPTION - -This package provides Tcl commands for the processing and reformatting text in -the format generated by the __[cvs log](\.\./\.\./\.\./\.\./index\.md\#cvs\_log)__ -command\. - -The commands __::doctools::cvs::scanLog__ and -__::doctools::cvs::toChangeLog__ are derived from code found on the -[Tcl'ers Wiki](http://wiki\.tcl\.tk)\. See the references at the end of the -page\. - -# API - - - __::doctools::cvs::scanLog__ *text* *evar* *cvar* *fvar* - - The command takes the *text* and parses it under the assumption that it - contains a CVS log as generated by __[cvs - log](\.\./\.\./\.\./\.\./index\.md\#cvs\_log)__\. The resulting information is - stored in the variables whose names were specified via *evar*, *cvar*, - and *fvar*\. - - Already existing information in the referenced variables is preserved, - allowing the caller to merge data from multiple logs into one database\. - - * varname *evar* \(in\) - - Has to refer to a scalar variable\. After the call this variable will - contain a list of all the entries found in the log file\. An entry is - identified through the combination of date and author, and can be split - over multiple physical entries, one per touched file\. - - It should be noted that the entries are listed in the same order as they - were found in the *text*\. This is not necessarily sorted by date or - author\. - - Each item in the list is a list containing two elements, the date of the - entry, and its author, in this order\. The date is formatted as - __year__/__month__/__day__\. - - * varname *cvar* \(in\) - - Has to refer to an array variable\. Keys are strings containing the date - and author of log entries, in this order, separated by a comma\. - - The values are lists of comments made for the entry\. - - * varname *fvar* \(in\) - - Has to refer to an array variable\. Keys are strings containing date, - author of a log entry, and a comment for that entry, in this order, - separated by commas\. - - The values are lists of the files the entry is touching\. - - - __::doctools::cvs::toChangeLog__ *evar* *cvar* *fvar* - - The three arguments for this command are the same as the last three - arguments of the command __::doctools::cvs::scanLog__\. This command - however expects them to be filled with information about one or more logs\. - It takes this information and converts it into a text in the format of a - ChangeLog as accepted and generated by - __[emacs](\.\./\.\./\.\./\.\./index\.md\#emacs)__\. The constructed text is - returned as the result of the command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -\[uri, http://wiki\.tcl\.tk/log2changelog - -# KEYWORDS - -[changelog](\.\./\.\./\.\./\.\./index\.md\#changelog), -[cvs](\.\./\.\./\.\./\.\./index\.md\#cvs), [cvs -log](\.\./\.\./\.\./\.\./index\.md\#cvs\_log), [emacs](\.\./\.\./\.\./\.\./index\.md\#emacs), -[log](\.\./\.\./\.\./\.\./index\.md\#log) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx.md Index: embedded/md/tcllib/files/modules/doctools/docidx.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx.md +++ embedded/md/tcllib/files/modules/doctools/docidx.md @@ -1,410 +0,0 @@ - -[//000000001]: # (doctools::idx \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2019 Andreas Kupries ) -[//000000004]: # (doctools::idx\(n\) 1\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::idx \- docidx \- Processing indices - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [PACKAGE COMMANDS](#subsection1) - - - [OBJECT COMMAND](#subsection2) - - - [OBJECT METHODS](#subsection3) - - - [OBJECT CONFIGURATION](#subsection4) - - - [FORMAT MAPPING](#subsection5) - - - [PREDEFINED ENGINES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require doctools::idx ?1\.1? - -[__::doctools::idx::new__ *objectName* ?__\-option__ *value* \.\.\.?](#1) -[__::doctools::idx::help__](#2) -[__::doctools::idx::search__ *path*](#3) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#4) -[*objectName* __configure__](#5) -[*objectName* __configure__ *option*](#6) -[*objectName* __configure__ __\-option__ *value*\.\.\.](#7) -[*objectName* __cget__ __\-option__](#8) -[*objectName* __destroy__](#9) -[*objectName* __format__ *text*](#10) -[*objectName* __map__ *symbolic* *actual*](#11) -[*objectName* __parameters__](#12) -[*objectName* __search__ *path*](#13) -[*objectName* __setparam__ *name* *value*](#14) -[*objectName* __warnings__](#15) - -# DESCRIPTION - -This package provides a class for the creation of objects able to process and -convert text written in the *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup -language into any output format X for which a *[formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* is available\. - -A reader interested in the markup language itself should start with the -*[docidx language introduction](docidx\_lang\_intro\.md)* and proceed from -there to the formal specifications, i\.e\. the *[docidx language -syntax](docidx\_lang\_syntax\.md)* and the *[docidx language command -reference](docidx\_lang\_cmdref\.md)*\. - -If on the other hand the reader wishes to write her own formatting engine for -some format, i\.e\. is a *plugin writer* then reading and understanding the -*[docidx plugin API reference](docidx\_plugin\_apiref\.md)* is an absolute -necessity, as that document specifies the interaction between this package and -its plugins, i\.e\. the formatting engines, in detail\. - -# PUBLIC API - -## PACKAGE COMMANDS - - - __::doctools::idx::new__ *objectName* ?__\-option__ *value* \.\.\.? - - This command creates a new docidx object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [OBJECT COMMAND](#subsection2) and [OBJECT - METHODS](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - - The options and their values coming after the name of the object are used to - set the initial configuration of the object\. - - - __::doctools::idx::help__ - - This is a convenience command for applications wishing to provide their user - with a short description of the available formatting commands and their - meanings\. It returns a string containing a standard help text\. - - - __::doctools::idx::search__ *path* - - Whenever an object created by this the package has to map the name of a - format to the file containing the code for its formatting engine it will - search for the file in a number of directories stored in a list\. See section - [FORMAT MAPPING](#subsection5) for more explanations\. - - This list not only contains three default directories which are declared by - the package itself, but is also extensible user of the package\. This command - is the means to do so\. When given a *path* to an existing and readable - directory it will prepend that directory to the list of directories to - search\. This means that the *path* added last is later searched through - first\. - - An error will be thrown if the *path* either does not exist, is not a - directory, or is not readable\. - -## OBJECT COMMAND - -All commands created by __::doctools::idx::new__ have the following general -form and may be used to invoke various operations on their docidx converter -object\. - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [OBJECT METHODS](#subsection3) for - the detailed specifications\. - -## OBJECT METHODS - - - *objectName* __configure__ - - The method returns a list of all known options and their current values when - called without any arguments\. - - - *objectName* __configure__ *option* - - The method behaves like the method __cget__ when called with a single - argument and returns the value of the option specified by said argument\. - - - *objectName* __configure__ __\-option__ *value*\.\.\. - - The method reconfigures the specified __option__s of the object, setting - them to the associated *value*s, when called with an even number of - arguments, at least two\. - - The legal options are described in the section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __cget__ __\-option__ - - This method expects a legal configuration option as argument and will return - the current value of that option for the object the method was invoked for\. - - The legal configuration options are described in section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __format__ *text* - - This method runs the *text* through the configured formatting engine and - returns the generated string as its result\. An error will be thrown if no - __\-format__ was configured for the object\. - - The method assumes that the *text* is in - *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* format as specified in the - companion document *docidx\_fmt*\. Errors will be thrown otherwise\. - - - *objectName* __map__ *symbolic* *actual* - - This methods add one entry to the per\-object mapping from *symbolic* - filenames to the *actual* uris\. The object just stores this mapping and - makes it available to the configured formatting engine through the command - __dt\_fmap__\. This command is described in more detail in the *[docidx - plugin API reference](docidx\_plugin\_apiref\.md)* which specifies the - interaction between the objects created by this package and index formatting - engines\. - - - *objectName* __parameters__ - - This method returns a list containing the names of all engine parameters - provided by the configured formatting engine\. It will return an empty list - if the object is not yet configured for a specific format\. - - - *objectName* __search__ *path* - - This method extends the per\-object list of paths searched for index - formatting engines\. See also the command __::doctools::idx::search__ on - how to extend the per\-package list of paths\. Note that the path entered last - will be searched first\. For more details see section [FORMAT - MAPPING](#subsection5)\. - - - *objectName* __setparam__ *name* *value* - - This method sets the *name*d engine parameter to the specified *value*\. - It will throw an error if the object is either not yet configured for a - specific format, or if the formatting engine for the configured format does - not provide a parameter with the given *name*\. The list of parameters - provided by the configured formatting engine can be retrieved through the - method __parameters__\. - - - *objectName* __warnings__ - - This method returns a list containing all the warnings which were generated - by the configured formatting engine during the last invocation of the method - __format__\. - -## OBJECT CONFIGURATION - -All docidx objects understand the following configuration options: - - - __\-file__ *file* - - The argument of this option is stored in the object and made available to - the configured formatting engine through the command __dt\_file__\. This - command is described in more detail in the companion document *docidx\_api* - which specifies the API between the object and formatting engines\. - - The default value of this option is the empty string\. - - The configured formatting engine should interpret the value as the name of - the file containing the document which is currently processed\. - - - __\-format__ *text* - - The argument of this option specifies the format to generate and by - implication the formatting engine to use when converting text via the method - __format__\. Its default value is the empty string\. The method - __format__ cannot be used if this option is not set to a valid value at - least once\. - - The package will immediately try to map the given name to a file containing - the code for a formatting engine generating that format\. An error will be - thrown if this mapping fails\. In that case a previously configured format is - left untouched\. - - The section [FORMAT MAPPING](#subsection5) explains in detail how the - package and object will look for engine implementations\. - -## FORMAT MAPPING - -The package and object will perform the following algorithm when trying to map a -format name *foo* to a file containing an implementation of a formatting -engine for *foo*: - - 1. If *foo* is the name of an existing file then this file is directly taken - as the implementation\. - - 1. If not, the list of per\-object search paths is searched\. For each directory - in the list the package checks if that directory contains a file - "idx\.*foo*"\. If yes, then that file is taken as the implementation\. - - Note that this list of paths is initially empty and can be extended through - the object method __search__\. - - 1. If not, the list of package paths is searched\. For each directory in the - list the package checks if that directory contains a file "idx\.*foo*"\. If - yes, then that file is taken as the implementation\. - - This list of paths can be extended through the command - __::doctools::idx::search__\. It contains initially one path, the - subdirectory "mpformats" of the directory the package itself is located in\. - In other words, if the package implementation "docidx\.tcl" is installed in - the directory "/usr/local/lib/tcllib/doctools" then it will by default - search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format - implementations\. - - 1. The mapping fails\. - -# PREDEFINED ENGINES - -The package provides predefined formatting engines for the following formats\. -Some of the formatting engines support engine parameters\. These will be -explicitly highlighted\. - - - html - - This engine generates HTML markup, for processing by web browsers and the - like\. This engine supports three parameters: - - * footer - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just before the - ____ tag, closing the body of the generated HTML\. - - This can be used to insert boilerplate footer markup into the generated - document\. - - * header - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just after the - ____ tag, starting the body of the generated HTML\. - - This can be used to insert boilerplate header markup into the generated - document\. - - * meta - - The value for this parameter has to be valid selfcontained HTML markup - for the header section of a HTML document\. The default value is the - empty string\. The value is inserted into the generated output just after - the ____ tag, starting the header section of the generated - HTML\. - - This can be used to insert boilerplate meta data markup into the - generated document, like references to a stylesheet, standard meta - keywords, etc\. - - - latex - - This engine generates output suitable for the - __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ text processor coming out of - the TeX world\. - - - list - - This engine retrieves version, section and title of the manpage from the - document\. As such it can be used to generate a directory listing for a set - of manpages\. - - - markdown - - This engine generates *[Markdown](\.\./\.\./\.\./\.\./index\.md\#markdown)* - markup\. - - - nroff - - This engine generates nroff output, for processing by - __[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff)__, or __groff__\. The - result will be standard man pages as they are known in the unix world\. - - - null - - This engine generates no outout at all\. This can be used if one just wants - to validate some input\. - - - tmml - - This engine generates TMML markup as specified by Joe English\. The Tcl - Manpage Markup Language is a derivate of XML\. - - - wiki - - This engine generates Wiki markup as understood by Jean Claude Wippler's - __wikit__ application\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md), -[docidx\_plugin\_apiref](docidx\_plugin\_apiref\.md) - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [keyword -index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[latex](\.\./\.\./\.\./\.\./index\.md\#latex), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markdown](\.\./\.\./\.\./\.\./index\.md\#markdown), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), [wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003\-2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_intro.md Index: embedded/md/tcllib/files/modules/doctools/docidx_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_intro.md +++ embedded/md/tcllib/files/modules/doctools/docidx_intro.md @@ -1,137 +0,0 @@ - -[//000000001]: # (docidx\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (docidx\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_intro \- docidx introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [RELATED FORMATS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* \(short for *documentation tables -of contents*\) stands for a set of related, yet different, entities which are -working together for the easy creation and transformation of keyword\-based -indices for documentation\. These are - - 1. A tcl based language for the semantic markup of a keyword index\. Markup is - represented by Tcl commands\. - - 1. A package providing the ability to read and transform texts written in that - markup language\. It is important to note that the actual transformation of - the input text is delegated to plugins\. - - 1. An API describing the interface between the package above and a plugin\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the documentation process\. - - 1. A *writer* of documentation has to understand the markup language itself\. - A beginner to docidx should read the more informally written *[docidx - language introduction](docidx\_lang\_intro\.md)* first\. Having digested - this the formal *[docidx language syntax](docidx\_lang\_syntax\.md)* - specification should become understandable\. A writer experienced with - docidx may only need the *[docidx language command - reference](docidx\_lang\_cmdref\.md)* from time to time to refresh her - memory\. - - While a document is written the __dtp__ application can be used to - validate it, and after completion it also performs the conversion into the - chosen system of visual markup, be it \*roff, HTML, plain text, wiki, etc\. - The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ application makes - internal use of docidx when handling directories of documentation, - automatically generating a proper keyword index for them\. - - 1. A *processor* of documentation written in the - *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup language has to know - which tools are available for use\. - - The main tool is the aforementioned __dtp__ application provided by - Tcllib\. The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ does not - expose docidx to the user\. At the bottom level, common to both - applications, however sits the package __doctoools::idx__, providing - the basic facilities to read and process files containing text in the - docidx format\. - - 1. At last, but not least, *plugin writers* have to understand the - interaction between the - __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ package and - its plugins, as described in the *[docidx plugin API - reference](docidx\_plugin\_apiref\.md)*\. - -# RELATED FORMATS - -docidx does not stand alone, it has two companion formats\. These are called -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* and -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)*, and they are for the markup -of *tables of contents*, and general documentation, respectively\. They are -described in their own sets of documents, starting at the *[doctoc -introduction](doctoc\_intro\.md)* and the *[doctools -introduction](doctools\_intro\.md)*, respectively\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_faq](docidx\_lang\_faq\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md), -[docidx\_plugin\_apiref](docidx\_plugin\_apiref\.md), -[doctoc\_intro](doctoc\_intro\.md), -[doctools::idx](\.\./doctools2idx/idx\_container\.md), -[doctools\_intro](doctools\_intro\.md) - -# KEYWORDS - -[index](\.\./\.\./\.\./\.\./index\.md\#index), [keyword -index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_lang_cmdref.md Index: embedded/md/tcllib/files/modules/doctools/docidx_lang_cmdref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_lang_cmdref.md +++ embedded/md/tcllib/files/modules/doctools/docidx_lang_cmdref.md @@ -1,168 +0,0 @@ - -[//000000001]: # (docidx\_lang\_cmdref \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_lang\_cmdref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (docidx\_lang\_cmdref\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_lang\_cmdref \- docidx language command reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext*](#1) -[__include__ *filename*](#2) -[__index\_begin__ *text* *title*](#3) -[__index\_end__](#4) -[__key__ *text*](#5) -[__lb__](#6) -[__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ *file* *text*](#7) -[__rb__](#8) -[__[url](\.\./\.\./\.\./\.\./index\.md\#url)__ *url* *label*](#9) -[__vset__ *varname* *value*](#10) -[__vset__ *varname*](#11) - -# DESCRIPTION - -This document specifies both names and syntax of all the commands which together -are the docidx markup language, version 1\. As this document is intended to be a -reference the commands are listed in alphabetical order, and the descriptions -are relatively short\. A beginner should read the much more informally written -*[docidx language introduction](docidx\_lang\_intro\.md)* first\. - -# Commands - - - __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext* - - Index markup\. The argument text is marked up as a comment standing outside - of the actual text of the document\. Main use is in free\-form text\. - - - __include__ *filename* - - Templating\. The contents of the named file are interpreted as text written - in the docidx markup and processed in the place of the include command\. The - markup in the file has to be self\-contained\. It is not possible for a markup - command to cross the file boundaries\. - - - __index\_begin__ *text* *title* - - Document structure\. The command to start an index\. The arguments are a label - for the whole group of documents the index refers to \(*text*\) and the - overall title text for the index \(*title*\), without markup\. - - The label often is the name of the package \(or extension\) the documents - belong to\. - - - __index\_end__ - - Document structure\. Command to end an index\. Anything in the document coming - after this command is in error\. - - - __key__ *text* - - Index structure\. This command adds the keyword *text* to the index\. - - - __lb__ - - Text\. The command is replaced with a left bracket\. Use in free\-form text\. - Required to avoid interpretation of a left bracket as the start of a markup - command\. Its usage is restricted to the arguments of other markup commands\. - - - __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ *file* *text* - - Index structure\. This command adds an element to the index which refers to a - document\. The document is specified through the symbolic name *file*\. The - *text* argument is used to label the reference\. - - Symbolic names are used to preserve the convertibility of this format to any - output format\. The actual name of the file will be inserted by the chosen - formatting engine when converting the input\. This will be based on a mapping - from symbolic to actual names given to the engine\. - - - __rb__ - - Text\. The command is replaced with a right bracket\. Use in free\-form text\. - Required to avoid interpretation of a right bracket as the end of a markup - command\. Its usage is restricted to the arguments of other commands\. - - - __[url](\.\./\.\./\.\./\.\./index\.md\#url)__ *url* *label* - - Index structure\. This is the second command to add an element to the index\. - To refer to a document it is not using a symbolic name however, but a - \(possibly format\-specific\) url describing the exact location of the document - indexed here\. - - - __vset__ *varname* *value* - - Templating\. In this form the command sets the named document variable to the - specified *value*\. It does not generate output\. I\.e\. the command is - replaced by the empty string\. - - - __vset__ *varname* - - Templating\. In this form the command is replaced by the value of the named - document variable - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), [docidx\_lang\_faq](docidx\_lang\_faq\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md) - -# KEYWORDS - -[docidx commands](\.\./\.\./\.\./\.\./index\.md\#docidx\_commands), [docidx -language](\.\./\.\./\.\./\.\./index\.md\#docidx\_language), [docidx -markup](\.\./\.\./\.\./\.\./index\.md\#docidx\_markup), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_lang_faq.md Index: embedded/md/tcllib/files/modules/doctools/docidx_lang_faq.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_lang_faq.md +++ embedded/md/tcllib/files/modules/doctools/docidx_lang_faq.md @@ -1,112 +0,0 @@ - -[//000000001]: # (docidx\_lang\_faq \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_lang\_faq\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (docidx\_lang\_faq\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_lang\_faq \- docidx language faq - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [What is this document?](#subsection1) - - - [EXAMPLES](#section3) - - - [Where do I find docidx examples?](#subsection2) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -# OVERVIEW - -## What is this document? - -This document is currently mainly a placeholder, to be filled with commonly -asked questions about the docidx markup language and companions, and their -answers\. - -Please report any questions \(and, if possible, answers\) we should consider for -this document as explained in the section [Bugs, Ideas, -Feedback](#section4) below\. - -# EXAMPLES - -## Where do I find docidx examples? - -We have no direct examples of documents written using docidx markup\. However the -doctools processor __[dtplite](\.\./\.\./apps/dtplite\.md)__ does generate a -table of contents when processing a set of documents written in doctools markup\. -The intermediate file for it uses docidx markup and is not deleted when -generation completes\. Such files can therefore serve as examples\. - -__[dtplite](\.\./\.\./apps/dtplite\.md)__ is distributed as part of Tcllib, -so to get it you need one of - - 1. A snapshot of Tcllib\. How to retrieve such a snapshot and the tools - required for this are described at [Development - Snapshots](/wiki?name=Development\+Snapshots) - - 1. A Tcllib release archive\. They are available at the [home](/home) page\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md) - -# KEYWORDS - -[docidx commands](\.\./\.\./\.\./\.\./index\.md\#docidx\_commands), [docidx -language](\.\./\.\./\.\./\.\./index\.md\#docidx\_language), [docidx -markup](\.\./\.\./\.\./\.\./index\.md\#docidx\_markup), [docidx -syntax](\.\./\.\./\.\./\.\./index\.md\#docidx\_syntax), -[examples](\.\./\.\./\.\./\.\./index\.md\#examples), -[faq](\.\./\.\./\.\./\.\./index\.md\#faq), [markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[semantic markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md Index: embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md +++ embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md @@ -1,228 +0,0 @@ - -[//000000001]: # (docidx\_lang\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_lang\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2009 Andreas Kupries ) -[//000000004]: # (docidx\_lang\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_lang\_intro \- docidx language introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#subsection1) - - - [Basic structure](#subsection2) - - - [Advanced structure](#subsection3) - - - [Escapes](#subsection4) - - - [FURTHER READING](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document is an informal introduction to version 1 of the docidx markup -language based on a multitude of examples\. After reading this a writer should be -ready to understand the two parts of the formal specification, i\.e\. the -*[docidx language syntax](docidx\_lang\_syntax\.md)* specification and the -*[docidx language command reference](docidx\_lang\_cmdref\.md)*\. - -## Fundamentals - -While the *docidx markup language* is quite similar to the *doctools markup -language*, in the broadest terms possible, there is one key difference\. An -index consists essentially only of markup commands, with no plain text -interspersed between them, except for whitespace\. - -Each markup command is a Tcl command surrounded by a matching pair of __\[__ -and __\]__\. Inside of these delimiters the usual rules for a Tcl command -apply with regard to word quotation, nested commands, continuation lines, etc\. -I\.e\. - - ... [key {markup language}] ... - - ... [manpage thefile \ - {file description}] ... - -## Basic structure - -The most simple document which can be written in docidx is - - [index_begin GROUPTITLE TITLE] - [index_end] - -Not very useful, but valid\. This also shows us that all docidx documents consist -of only one part where we will list all keys and their references\. - -A more useful index will contain at least keywords, or short 'keys', i\.e\. the -phrases which were indexed\. So: - -> \[index\_begin GROUPTITLE TITLE\] -> \[__key markup__\] -> \[__key \{semantic markup\}\]__\] -> \[__key \{docidx markup\}__\] -> \[__key \{docidx language\}__\] -> \[__key \{docidx commands\}__\] -> \[index\_end\] - -In the above example the command __key__ is used to declare the keyword -phrases we wish to be part of the index\. - -However a truly useful index does not only list the keyword phrases, but will -also contain references to documents associated with the keywords\. Here is a -made\-up index for all the manpages in the module -*[base64](\.\./\.\./\.\./\.\./index\.md\#base64)*: - -> \[index\_begin tcllib/base64 \{De\- & Encoding\}\] -> \[key base64\] -> \[__manpage base64__\] -> \[key encoding\] -> \[__manpage base64__\] -> \[__manpage uuencode__\] -> \[__manpage yencode__\] -> \[key uuencode\] -> \[__manpage uuencode__\] -> \[key yEnc\] -> \[__manpage yencode__\] -> \[key ydecode\] -> \[__manpage yencode__\] -> \[key yencode\] -> \[__manpage yencode__\] -> \[index\_end\] - -In the above example the command -__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ is used to insert references -to documents, using symbolic file names, with each command belonging to the last -__key__ command coming before it\. - -The other command to insert references is -__[url](\.\./\.\./\.\./\.\./index\.md\#url)__\. In contrast to -__[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ it uses explicit \(possibly -format\-specific\) urls to describe the location of the referenced document\. As -such this command is intended for the creation of references to external -documents which could not be handled in any other way\. - -## Advanced structure - -In all previous examples we fudged a bit regarding the markup actually allowed -to be used before the __index\_begin__ command opening the document\. - -Instead of only whitespace the two templating commands __include__ and -__vset__ are also allowed, to enable the writer to either set and/or import -configuration settings relevant to the table of contents\. I\.e\. it is possible to -write - -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \[index\_begin GROUPTITLE TITLE\] -> \.\.\. -> \[index\_end\] - -Even more important, these two commands are allowed anywhere where a markup -command is allowed, without regard for any other structure\. - -> \[index\_begin GROUPTITLE TITLE\] -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \.\.\. -> \[index\_end\] - -The only restriction __include__ has to obey is that the contents of the -included file must be valid at the place of the inclusion\. I\.e\. a file included -before __index\_begin__ may contain only the templating commands __vset__ -and __include__, a file included after a key may contain only manape or url -references, and other keys, etc\. - -## Escapes - -Beyond the 6 commands shown so far we have two more available\. However their -function is not the marking up of index structure, but the insertion of -characters, namely __\[__ and __\]__\. These commands, __lb__ and -__rb__ respectively, are required because our use of \[ and \] to bracket -markup commands makes it impossible to directly use \[ and \] within the text\. - -Our example of their use are the sources of the last sentence in the previous -paragraph, with some highlighting added\. - ->   \.\.\. ->   These commands, \[cmd lb\] and \[cmd lb\] respectively, are required ->   because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it ->   impossible to directly use \[__lb__\] and \[__rb__\] within the text\. ->   \.\.\. - -# FURTHER READING - -Now that this document has been digested the reader, assumed to be a *writer* -of documentation should be fortified enough to be able to understand the formal -*[docidx language syntax](docidx\_lang\_syntax\.md)* specification as well\. -From here on out the *[docidx language command -reference](docidx\_lang\_cmdref\.md)* will also serve as the detailed -specification and cheat sheet for all available commands and their syntax\. - -To be able to validate a document while writing it, it is also recommended to -familiarize oneself with Tclapps' ultra\-configurable __dtp__\. - -On the other hand, docidx is perfectly suited for the automatic generation from -doctools documents, and this is the route Tcllib's easy and simple -__[dtplite](\.\./\.\./apps/dtplite\.md)__ goes, creating an index for a set -of documents behind the scenes, without the writer having to do so on their own\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md) - -# KEYWORDS - -[docidx commands](\.\./\.\./\.\./\.\./index\.md\#docidx\_commands), [docidx -language](\.\./\.\./\.\./\.\./index\.md\#docidx\_language), [docidx -markup](\.\./\.\./\.\./\.\./index\.md\#docidx\_markup), [docidx -syntax](\.\./\.\./\.\./\.\./index\.md\#docidx\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_lang_syntax.md Index: embedded/md/tcllib/files/modules/doctools/docidx_lang_syntax.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_lang_syntax.md +++ embedded/md/tcllib/files/modules/doctools/docidx_lang_syntax.md @@ -1,152 +0,0 @@ - -[//000000001]: # (docidx\_lang\_syntax \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_lang\_syntax\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2009 Andreas Kupries ) -[//000000004]: # (docidx\_lang\_syntax\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_lang\_syntax \- docidx language syntax - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#section2) - - - [Lexical definitions](#section3) - - - [Syntax](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document contains the formal specification of the syntax of the docidx -markup language, version 1 in Backus\-Naur\-Form\. This document is intended to be -a reference, complementing the *[docidx language command -reference](docidx\_lang\_cmdref\.md)*\. A beginner should read the much more -informally written *[docidx language introduction](docidx\_lang\_intro\.md)* -first before trying to understand either this document or the command reference\. - -# Fundamentals - -In the broadest terms possible the *docidx markup language* is like SGML and -similar languages\. A document written in this language consists primarily of -markup commands, with text embedded into it at some places\. - -Each markup command is a just Tcl command surrounded by a matching pair of -__\[__ and __\]__\. Which commands are available, and their arguments, i\.e\. -syntax is specified in the *[docidx language command -reference](docidx\_lang\_cmdref\.md)*\. - -In this document we specify first the lexeme, and then the syntax, i\.e\. how we -can mix text and markup commands with each other\. - -# Lexical definitions - -In the syntax rules listed in the next section - - 1. stands for all text except markup commands\. - - 1. Any XXX stands for the markup command \[xxx\] including its arguments\. Each - markup command is a Tcl command surrounded by a matching pair of __\[__ - and __\]__\. Inside of these delimiters the usual rules for a Tcl command - apply with regard to word quotation, nested commands, continuation lines, - etc\. - - 1. stands for all text consisting only of spaces, newlines, tabulators - and the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ markup command\. - -# Syntax - -The rules listed here specify only the syntax of docidx documents\. The lexical -level of the language was covered in the previous section\. - -Regarding the syntax of the \(E\)BNF itself - - 1. The construct \{ X \} stands for zero or more occurrences of X\. - - 1. The construct \[ X \] stands for zero or one occurrence of X\. - -The syntax: - - index = defs - INDEX_BEGIN - [ contents ] - INDEX_END - { } - - defs = { INCLUDE | VSET | } - contents = keyword { keyword } - - keyword = defs KEY ref { ref } - ref = MANPAGE | URL | defs - -At last a rule we were unable to capture in the EBNF syntax, as it is about the -arguments of the markup commands, something which is not modeled here\. - - 1. The arguments of all markup commands have to be plain text, and/or text - markup commands, i\.e\. one of - - 1) __lb__, - - 1) __rb__, or - - 1) __vset__ \(1\-argument form\)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_faq](docidx\_lang\_faq\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md) - -# KEYWORDS - -[docidx commands](\.\./\.\./\.\./\.\./index\.md\#docidx\_commands), [docidx -language](\.\./\.\./\.\./\.\./index\.md\#docidx\_language), [docidx -markup](\.\./\.\./\.\./\.\./index\.md\#docidx\_markup), [docidx -syntax](\.\./\.\./\.\./\.\./index\.md\#docidx\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/docidx_plugin_apiref.md Index: embedded/md/tcllib/files/modules/doctools/docidx_plugin_apiref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/docidx_plugin_apiref.md +++ embedded/md/tcllib/files/modules/doctools/docidx_plugin_apiref.md @@ -1,420 +0,0 @@ - -[//000000001]: # (docidx\_plugin\_apiref \- Documentation tools) -[//000000002]: # (Generated from file 'docidx\_plugin\_apiref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (docidx\_plugin\_apiref\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -docidx\_plugin\_apiref \- docidx plugin API reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [FRONTEND COMMANDS](#section3) - - - [PLUGIN COMMANDS](#section4) - - - [Management commands](#subsection1) - - - [Formatting commands](#subsection2) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__dt\_fmap__ *symfname*](#1) -[__dt\_format__](#2) -[__dt\_read__ *file*](#3) -[__dt\_source__ *file*](#4) -[__ex\_cappend__ *text*](#5) -[__ex\_cget__ *varname*](#6) -[__ex\_cis__ *cname*](#7) -[__ex\_cname__](#8) -[__ex\_cpop__ *cname*](#9) -[__ex\_cpush__ *cname*](#10) -[__ex\_cset__ *varname* *value*](#11) -[__ex\_lb__ ?*newbracket*?](#12) -[__ex\_rb__ ?*newbracket*?](#13) -[__idx\_initialize__](#14) -[__idx\_listvariables__](#15) -[__idx\_numpasses__](#16) -[__idx\_postprocess__ *text*](#17) -[__idx\_setup__ *n*](#18) -[__idx\_shutdown__](#19) -[__idx\_varset__ *varname* *text*](#20) -[__fmt\_plain\_text__ *text*](#21) - -# DESCRIPTION - -This document is intended for *plugin writers*, i\.e\. developers wishing to -write an index *[formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* for some output format X\. - -It specifies the interaction between the -__[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ package and its -plugins, i\.e\. the interface any index formatting engine has to comply with\. - -This document deals with version 1 of the interface\. - -A reader who is on the other hand more interested in the markup language itself -should start with the *[docidx language -introduction](docidx\_lang\_intro\.md)* and proceed from there to the formal -specifications, i\.e\. the *[docidx language syntax](docidx\_lang\_syntax\.md)* -and the *[docidx language command reference](docidx\_lang\_cmdref\.md)*\. - -# OVERVIEW - -The API for an index formatting engine consists of two major sections\. - -On the one side we have a set of commands through which the plugin is able to -query the frontend\. These commands are provided by the frontend and linked into -the plugin interpreter\. Please see section [FRONTEND COMMANDS](#section3) -for their detailed specification\. - -And on the other side the plugin has to provide its own set of commands which -will then be called by the frontend in a specific sequence while processing -input\. They, again, fall into two categories, management and formatting\. Please -see section [PLUGIN COMMANDS](#section4) and its subsections for their -detailed specification\. - -# FRONTEND COMMANDS - -This section specifies the set of commands through which a plugin, also known as -an index formatting engine, is able to query the frontend\. These commands are -provided by the frontend and linked into the plugin interpreter\. - -I\.e\. an index formatting engine can assume that all of the following commands -are present when any of its own commands \(as specified in section [PLUGIN -COMMANDS](#section4)\) are executed\. - -Beyond that it can also assume that it has full access to its own safe -interpreter and thus is not able to damage the other parts of the processor, nor -can it damage the filesystem\. It is however able to either kill or hang the -whole process, by exiting, or running an infinite loop\. - -Coming back to the imported commands, all the commands with prefix *dt\_* -provide limited access to specific parts of the frontend, whereas the commands -with prefix *ex\_* provide access to the state of the -__[textutil::expander](\.\./textutil/expander\.md)__ object which does the -main parsing of the input within the frontend\. These commands should not be -except under very special circumstances\. - - - __dt\_fmap__ *symfname* - - Query command\. It returns the actual pathname to use in the output in place - of the symbolic filename *symfname*\. It will return the unchanged input if - no mapping was established for *symfname*\. - - The required mappings are established with the method __map__ of a - frontend, as explained in section __OBJECT METHODS__ of the - documentation for the package - __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__\. - - - __dt\_format__ - - Query command\. It returns the name of the format associated with the index - formatting engine\. - - - __dt\_read__ *file* - - Controlled filesystem access\. Returns contents of *file* for whatever use - desired by the plugin\. Only files which are either in the same directory as - the file containing the engine, or below it, can be loaded\. Trying to load a - file outside of this directory causes an error\. - - - __dt\_source__ *file* - - Controlled filesystem access\. This command allows the index formatting - engine to load additional Tcl code it may need\. Only files which are either - in the same directory as the file containing the engine, or below it, can be - loaded\. Trying to load a file outside of this directory causes an error\. - - - __ex\_cappend__ *text* - - Appends a string to the output in the current context\. This command should - rarely be used by macros or application code\. - - - __ex\_cget__ *varname* - - Retrieves the value of variable *varname*, defined in the current context\. - - - __ex\_cis__ *cname* - - Determines whether or not the name of the current context is *cname*\. - - - __ex\_cname__ - - Returns the name of the current context\. - - - __ex\_cpop__ *cname* - - Pops a context from the context stack, returning all accumulated output in - that context\. The context must be named *cname*, or an error results\. - - - __ex\_cpush__ *cname* - - Pushes a context named *cname* onto the context stack\. The context must be - popped by __cpop__ before expansion ends or an error results\. - - - __ex\_cset__ *varname* *value* - - Sets variable *varname* to *value* in the current context\. - - - __ex\_lb__ ?*newbracket*? - - Returns the current value of the left macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - - - __ex\_rb__ ?*newbracket*? - - Returns the current value of the right macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - -# PLUGIN COMMANDS - -The plugin has to provide its own set of commands which will then be called by -the frontend in a specific sequence while processing input\. They fall into two -categories, management and formatting\. Their expected names, signatures, and -responsibilities are specified in the following two subsections\. - -## Management commands - -The management commands a plugin has to provide are used by the frontend to - - 1. initialize and shutdown the plugin - - 1. determine the number of passes it has to make over the input - - 1. initialize and shutdown each pass - - 1. query and initialize engine parameters - -After the plugin has been loaded and the frontend commands are established the -commands will be called in the following sequence: - - idx_numpasses -> n - idx_listvariables -> vars - - idx_varset var1 value1 - idx_varset var2 value2 - ... - idx_varset varK valueK - idx_initialize - idx_setup 1 - ... - idx_setup 2 - ... - ... - idx_setup n - ... - idx_postprocess - idx_shutdown - ... - -I\.e\. first the number of passes and the set of available engine parameters is -established, followed by calls setting the parameters\. That second part is -optional\. - -After that the plugin is initialized, the specified number of passes executed, -the final result run through a global post processing step and at last the -plugin is shutdown again\. This can be followed by more conversions, restarting -the sequence at __idx\_varset__\. - -In each of the passes, i\.e\. after the calls of __idx\_setup__ the frontend -will process the input and call the formatting commands as markup is -encountered\. This means that the sequence of formatting commands is determined -by the grammar of the docidx markup language, as specified in the *[docidx -language syntax](docidx\_lang\_syntax\.md)* specification\. - -A different way of looking at the sequence is: - - - First some basic parameters are determined\. - - - Then everything starting at the first __idx\_varset__ to - __idx\_shutdown__ forms a *run*, the formatting of a single input\. Each - run can be followed by more\. - - - Embedded within each run we have one or more *passes*, each starting with - __idx\_setup__ and going until either the next __idx\_setup__ or - __idx\_postprocess__ is reached\. - - If more than one pass is required to perform the formatting only the output - of the last pass is relevant\. The output of all the previous, preparatory - passes is ignored\. - -The commands, their names, signatures, and responsibilities are, in detail: - - - __idx\_initialize__ - - *Initialization/Shutdown*\. This command is called at the beginning of - every conversion run, as the first command of that run\. Note that a run is - not a pass, but may consist of multiple passes\. It has to initialize the - general state of the plugin, beyond the initialization done during the load\. - No return value is expected, and any returned value is ignored\. - - - __idx\_listvariables__ - - *Initialization/Shutdown* and *Engine parameters*\. Second command is - called after the plugin code has been loaded, i\.e\. immediately after - __idx\_numpasses__\. It has to return a list containing the names of the - parameters the frontend can set to configure the engine\. This list can be - empty\. - - - __idx\_numpasses__ - - *Initialization/Shutdown* and *Pass management*\. First command called - after the plugin code has been loaded\. No other command of the engine will - be called before it\. It has to return the number of passes this engine - requires to fully process the input document\. This value has to be an - integer number greater or equal to one\. - - - __idx\_postprocess__ *text* - - *Initialization/Shutdown*\. This command is called immediately after the - last pass in a run\. Its argument is the result of the conversion generated - by that pass\. It is provided to allow the engine to perform any global - modifications of the generated document\. If no post\-processing is required - for a specific format the command has to just return the argument\. - - Expected to return a value, the final result of formatting the input\. - - - __idx\_setup__ *n* - - *Initialization/Shutdown* and *Pass management*\. This command is called - at the beginning of each pass over the input in a run\. Its argument is the - number of the pass which has begun\. Passes are counted from __1__ - upward\. The command has to set up the internal state of the plugin for this - particular pass\. No return value is expected, and any returned value is - ignored\. - - - __idx\_shutdown__ - - *Initialization/Shutdown*\. This command is called at the end of every - conversion run\. It is the last command called in a run\. It has to clean up - of all the run\-specific state in the plugin\. After the call the engine has - to be in a state which allows the initiation of another run without fear - that information from the last run is leaked into this new run\. No return - value is expected, and any returned value is ignored\. - - - __idx\_varset__ *varname* *text* - - *Engine parameters*\. This command is called by the frontend to set an - engine parameter to a particular value\. The parameter to change is specified - by *varname*, the value to set in *text*\. - - The command has to throw an error if an unknown *varname* is used\. Only - the names returned by __idx\_listvariables__ have to be considered as - known\. - - The values of all engine parameters have to persist between passes and runs\. - -## Formatting commands - -The formatting commands have to implement the formatting for the output format, -for all the markup commands of the docidx markup language, except __lb__, -__rb__, __vset__, __include__, and -__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__\. These exceptions are -processed by the frontend and are never seen by the plugin\. In return a command -for the formatting of plain text has to be provided, something which has no -markup in the input at all\. - -This means, that each of the five markup commands specified in the *[docidx -language command reference](docidx\_lang\_cmdref\.md)* and outside of the set -of exceptions listed above has an equivalent formatting command which takes the -same arguments as the markup command and whose name is the name of markup -command with the prefix *fmt\_* added to it\. - -All commands are expected to format their input in some way per the semantics -specified in the command reference and to return whatever part of this that they -deem necessary as their result, which will be added to the output\. - -To avoid essentially duplicating the command reference we do not list any of the -command here and simply refer the reader to the *[docidx language command -reference](docidx\_lang\_cmdref\.md)* for their signature and description\. The -sole exception is the plain text formatter, which has no equivalent markup -command\. - -The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the docidx markup -language, as specified in the *[docidx language -syntax](docidx\_lang\_syntax\.md)* specification\. - - - __fmt\_plain\_text__ *text* - - *No associated markup command*\. - - Called by the frontend for any plain text encountered in the input\. It has - to perform any and all special processing required for plain text\. - - The formatted text is expected as the result of the command, and added to - the output\. If no special processing is required it has to simply return its - argument without change\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), -[docidx\_lang\_cmdref](docidx\_lang\_cmdref\.md), -[docidx\_lang\_faq](docidx\_lang\_faq\.md), -[docidx\_lang\_intro](docidx\_lang\_intro\.md), -[docidx\_lang\_syntax](docidx\_lang\_syntax\.md), -[doctools::idx](\.\./doctools2idx/idx\_container\.md) - -# KEYWORDS - -[formatting engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [index -formatter](\.\./\.\./\.\./\.\./index\.md\#index\_formatter), -[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc.md Index: embedded/md/tcllib/files/modules/doctools/doctoc.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc.md +++ embedded/md/tcllib/files/modules/doctools/doctoc.md @@ -1,410 +0,0 @@ - -[//000000001]: # (doctools::toc \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2019 Andreas Kupries ) -[//000000004]: # (doctools::toc\(n\) 1\.2 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::toc \- doctoc \- Processing tables of contents - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [PACKAGE COMMANDS](#subsection1) - - - [OBJECT COMMAND](#subsection2) - - - [OBJECT METHODS](#subsection3) - - - [OBJECT CONFIGURATION](#subsection4) - - - [FORMAT MAPPING](#subsection5) - - - [PREDEFINED ENGINES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require doctools::toc ?1\.2? - -[__::doctools::toc::new__ *objectName* ?__\-option__ *value* \.\.\.?](#1) -[__::doctools::toc::help__](#2) -[__::doctools::toc::search__ *path*](#3) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#4) -[*objectName* __configure__](#5) -[*objectName* __configure__ *option*](#6) -[*objectName* __configure__ __\-option__ *value*\.\.\.](#7) -[*objectName* __cget__ __\-option__](#8) -[*objectName* __destroy__](#9) -[*objectName* __format__ *text*](#10) -[*objectName* __map__ *symbolic* *actual*](#11) -[*objectName* __parameters__](#12) -[*objectName* __search__ *path*](#13) -[*objectName* __setparam__ *name* *value*](#14) -[*objectName* __warnings__](#15) - -# DESCRIPTION - -This package provides a class for the creation of objects able to process and -convert text written in the *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup -language into any output format X for which a *[formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* is available\. - -A reader interested in the markup language itself should start with the -*[doctoc language introduction](doctoc\_lang\_intro\.md)* and proceed from -there to the formal specifications, i\.e\. the *[doctoc language -syntax](doctoc\_lang\_syntax\.md)* and the *[doctoc language command -reference](doctoc\_lang\_cmdref\.md)*\. - -If on the other hand the reader wishes to write her own formatting engine for -some format, i\.e\. is a *plugin writer* then reading and understanding the -*[doctoc plugin API reference](doctoc\_plugin\_apiref\.md)* is an absolute -necessity, as that document specifies the interaction between this package and -its plugins, i\.e\. the formatting engines, in detail\. - -# PUBLIC API - -## PACKAGE COMMANDS - - - __::doctools::toc::new__ *objectName* ?__\-option__ *value* \.\.\.? - - This command creates a new doctoc object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [OBJECT COMMAND](#subsection2) and [OBJECT - METHODS](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - - The options and their values coming after the name of the object are used to - set the initial configuration of the object\. - - - __::doctools::toc::help__ - - This is a convenience command for applications wishing to provide their user - with a short description of the available formatting commands and their - meanings\. It returns a string containing a standard help text\. - - - __::doctools::toc::search__ *path* - - Whenever an object created by this the package has to map the name of a - format to the file containing the code for its formatting engine it will - search for the file in a number of directories stored in a list\. See section - [FORMAT MAPPING](#subsection5) for more explanations\. - - This list not only contains three default directories which are declared by - the package itself, but is also extensible user of the package\. This command - is the means to do so\. When given a *path* to an existing and readable - directory it will prepend that directory to the list of directories to - search\. This means that the *path* added last is later searched through - first\. - - An error will be thrown if the *path* either does not exist, is not a - directory, or is not readable\. - -## OBJECT COMMAND - -All commands created by __::doctools::toc::new__ have the following general -form and may be used to invoke various operations on their doctoc converter -object\. - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [OBJECT METHODS](#subsection3) for - the detailed specifications\. - -## OBJECT METHODS - - - *objectName* __configure__ - - The method returns a list of all known options and their current values when - called without any arguments\. - - - *objectName* __configure__ *option* - - The method behaves like the method __cget__ when called with a single - argument and returns the value of the option specified by said argument\. - - - *objectName* __configure__ __\-option__ *value*\.\.\. - - The method reconfigures the specified __option__s of the object, setting - them to the associated *value*s, when called with an even number of - arguments, at least two\. - - The legal options are described in the section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __cget__ __\-option__ - - This method expects a legal configuration option as argument and will return - the current value of that option for the object the method was invoked for\. - - The legal configuration options are described in section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __format__ *text* - - This method runs the *text* through the configured formatting engine and - returns the generated string as its result\. An error will be thrown if no - __\-format__ was configured for the object\. - - The method assumes that the *text* is in - *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* format as specified in the - companion document *doctoc\_fmt*\. Errors will be thrown otherwise\. - - - *objectName* __map__ *symbolic* *actual* - - This methods add one entry to the per\-object mapping from *symbolic* - filenames to the *actual* uris\. The object just stores this mapping and - makes it available to the configured formatting engine through the command - __dt\_fmap__\. This command is described in more detail in the *[doctoc - plugin API reference](doctoc\_plugin\_apiref\.md)* which specifies the - interaction between the objects created by this package and toc formatting - engines\. - - - *objectName* __parameters__ - - This method returns a list containing the names of all engine parameters - provided by the configured formatting engine\. It will return an empty list - if the object is not yet configured for a specific format\. - - - *objectName* __search__ *path* - - This method extends the per\-object list of paths searched for toc formatting - engines\. See also the command __::doctools::toc::search__ on how to - extend the per\-package list of paths\. Note that the path entered last will - be searched first\. For more details see section [FORMAT - MAPPING](#subsection5)\. - - - *objectName* __setparam__ *name* *value* - - This method sets the *name*d engine parameter to the specified *value*\. - It will throw an error if the object is either not yet configured for a - specific format, or if the formatting engine for the configured format does - not provide a parameter with the given *name*\. The list of parameters - provided by the configured formatting engine can be retrieved through the - method __parameters__\. - - - *objectName* __warnings__ - - This method returns a list containing all the warnings which were generated - by the configured formatting engine during the last invocation of the method - __format__\. - -## OBJECT CONFIGURATION - -All doctoc objects understand the following configuration options: - - - __\-file__ *file* - - The argument of this option is stored in the object and made available to - the configured formatting engine through the command __dt\_file__\. This - command is described in more detail in the companion document *doctoc\_api* - which specifies the API between the object and formatting engines\. - - The default value of this option is the empty string\. - - The configured formatting engine should interpret the value as the name of - the file containing the document which is currently processed\. - - - __\-format__ *text* - - The argument of this option specifies the format to generate and by - implication the formatting engine to use when converting text via the method - __format__\. Its default value is the empty string\. The method - __format__ cannot be used if this option is not set to a valid value at - least once\. - - The package will immediately try to map the given name to a file containing - the code for a formatting engine generating that format\. An error will be - thrown if this mapping fails\. In that case a previously configured format is - left untouched\. - - The section [FORMAT MAPPING](#subsection5) explains in detail how the - package and object will look for engine implementations\. - -## FORMAT MAPPING - -The package and object will perform the following algorithm when trying to map a -format name *foo* to a file containing an implementation of a formatting -engine for *foo*: - - 1. If *foo* is the name of an existing file then this file is directly taken - as the implementation\. - - 1. If not, the list of per\-object search paths is searched\. For each directory - in the list the package checks if that directory contains a file - "toc\.*foo*"\. If yes, then that file is taken as the implementation\. - - Note that this list of paths is initially empty and can be extended through - the object method __search__\. - - 1. If not, the list of package paths is searched\. For each directory in the - list the package checks if that directory contains a file "toc\.*foo*"\. If - yes, then that file is taken as the implementation\. - - This list of paths can be extended through the command - __::doctools::toc::search__\. It contains initially one path, the - subdirectory "mpformats" of the directory the package itself is located in\. - In other words, if the package implementation "doctoc\.tcl" is installed in - the directory "/usr/local/lib/tcllib/doctools" then it will by default - search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format - implementations\. - - 1. The mapping fails\. - -# PREDEFINED ENGINES - -The package provides predefined formatting engines for the following formats\. -Some of the formatting engines support engine parameters\. These will be -explicitly highlighted\. - - - html - - This engine generates HTML markup, for processing by web browsers and the - like\. This engine supports three parameters: - - * footer - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just before the - ____ tag, closing the body of the generated HTML\. - - This can be used to insert boilerplate footer markup into the generated - document\. - - * header - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just after the - ____ tag, starting the body of the generated HTML\. - - This can be used to insert boilerplate header markup into the generated - document\. - - * meta - - The value for this parameter has to be valid selfcontained HTML markup - for the header section of a HTML document\. The default value is the - empty string\. The value is inserted into the generated output just after - the ____ tag, starting the header section of the generated - HTML\. - - This can be used to insert boilerplate meta data markup into the - generated document, like references to a stylesheet, standard meta - keywords, etc\. - - - latex - - This engine generates output suitable for the - __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ text processor coming out of - the TeX world\. - - - list - - This engine retrieves version, section and title of the manpage from the - document\. As such it can be used to generate a directory listing for a set - of manpages\. - - - markdown - - This engine generates *[Markdown](\.\./\.\./\.\./\.\./index\.md\#markdown)* - markup\. - - - nroff - - This engine generates nroff output, for processing by - __[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff)__, or __groff__\. The - result will be standard man pages as they are known in the unix world\. - - - null - - This engine generates no outout at all\. This can be used if one just wants - to validate some input\. - - - tmml - - This engine generates TMML markup as specified by Joe English\. The Tcl - Manpage Markup Language is a derivate of XML\. - - - wiki - - This engine generates Wiki markup as understood by Jean Claude Wippler's - __wikit__ application\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_intro](doctoc\_intro\.md), -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md), -[doctoc\_plugin\_apiref](doctoc\_plugin\_apiref\.md) - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[latex](\.\./\.\./\.\./\.\./index\.md\#latex), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markdown](\.\./\.\./\.\./\.\./index\.md\#markdown), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc), [wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003\-2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_intro.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_intro.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_intro.md @@ -1,135 +0,0 @@ - -[//000000001]: # (doctoc\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctoc\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_intro \- doctoc introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [RELATED FORMATS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* \(short for *documentation tables -of contents*\) stands for a set of related, yet different, entities which are -working together for the easy creation and transformation of tables of contents -for documentation\. These are - - 1. A tcl based language for the semantic markup of a table of contents\. Markup - is represented by Tcl commands\. - - 1. A package providing the ability to read and transform texts written in that - markup language\. It is important to note that the actual transformation of - the input text is delegated to plugins\. - - 1. An API describing the interface between the package above and a plugin\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the documentation process\. - - 1. A *writer* of documentation has to understand the markup language itself\. - A beginner to doctoc should read the more informally written *[doctoc - language introduction](doctoc\_lang\_intro\.md)* first\. Having digested - this the formal *[doctoc language syntax](doctoc\_lang\_syntax\.md)* - specification should become understandable\. A writer experienced with - doctoc may only need the *[doctoc language command - reference](doctoc\_lang\_cmdref\.md)* from time to time to refresh her - memory\. - - While a document is written the __dtp__ application can be used to - validate it, and after completion it also performs the conversion into the - chosen system of visual markup, be it \*roff, HTML, plain text, wiki, etc\. - The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ application makes - internal use of doctoc when handling directories of documentation, - automatically generating a proper table of contents for them\. - - 1. A *processor* of documentation written in the - *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup language has to know - which tools are available for use\. - - The main tool is the aforementioned __dtp__ application provided by - Tcllib\. The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ does not - expose doctoc to the user\. At the bottom level, common to both - applications, however sits the package __doctoools::toc__, providing - the basic facilities to read and process files containing text in the - doctoc format\. - - 1. At last, but not least, *plugin writers* have to understand the - interaction between the __[doctools::toc](doctoc\.md)__ package and - its plugins, as described in the *[doctoc plugin API - reference](doctoc\_plugin\_apiref\.md)*\. - -# RELATED FORMATS - -doctoc does not stand alone, it has two companion formats\. These are called -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* and -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)*, and they are for the markup -of *keyword indices*, and general documentation, respectively\. They are -described in their own sets of documents, starting at the *[docidx -introduction](docidx\_intro\.md)* and the *[doctools -introduction](doctools\_intro\.md)*, respectively\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_faq](doctoc\_lang\_faq\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md), -[doctoc\_plugin\_apiref](doctoc\_plugin\_apiref\.md), -[doctools::toc](doctoc\.md), [doctools\_intro](doctools\_intro\.md) - -# KEYWORDS - -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_lang_cmdref.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_lang_cmdref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_lang_cmdref.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_lang_cmdref.md @@ -1,176 +0,0 @@ - -[//000000001]: # (doctoc\_lang\_cmdref \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_lang\_cmdref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctoc\_lang\_cmdref\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_lang\_cmdref \- doctoc language command reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext*](#1) -[__division\_end__](#2) -[__division\_start__ *text* ?*symfile*?](#3) -[__include__ *filename*](#4) -[__item__ *file* *text* *desc*](#5) -[__lb__](#6) -[__rb__](#7) -[__toc\_begin__ *text* *title*](#8) -[__toc\_end__](#9) -[__vset__ *varname* *value*](#10) -[__vset__ *varname*](#11) - -# DESCRIPTION - -This document specifies both names and syntax of all the commands which together -are the doctoc markup language, version 1\. As this document is intended to be a -reference the commands are listed in alphabetical order, and the descriptions -are relatively short\. A beginner should read the much more informally written -*[doctoc language introduction](doctoc\_lang\_intro\.md)* first\. - -# Commands - - - __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext* - - Toc markup\. The argument text is marked up as a comment standing outside of - the actual text of the document\. Main use is in free\-form text\. - - - __division\_end__ - - Toc structure\. This command closes the division opened by the last - __division\_begin__ command coming before it, and not yet closed\. - - - __division\_start__ *text* ?*symfile*? - - Toc structure\. This command opens a division in the table of contents\. Its - counterpart is __division\_end__\. Together they allow a user to give a - table of contents additional structure\. - - The title of the new division is provided by the argument *text*\. - - If the symbolic filename *symfile* is present then the section title - should link to the referenced document, if links are supported by the output - format\. - - - __include__ *filename* - - Templating\. The contents of the named file are interpreted as text written - in the doctoc markup and processed in the place of the include command\. The - markup in the file has to be self\-contained\. It is not possible for a markup - command to cross the file boundaries\. - - - __item__ *file* *text* *desc* - - Toc structure\. This command adds an individual element to the table of - contents\. Each such element refers to a document\. The document is specified - through the symbolic name *file*\. The *text* argument is used to label - the reference, whereas the *desc* provides a short descriptive text of - that document\. - - The symbolic names are used to preserve the convertibility of this format to - any output format\. The actual name of the file will be inserted by the - chosen formatting engine when converting the input\. This will be based on a - mapping from symbolic to actual names given to the engine\. - - - __lb__ - - Text\. The command is replaced with a left bracket\. Use in free\-form text\. - Required to avoid interpretation of a left bracket as the start of a markup - command\. Its usage is restricted to the arguments of other markup commands\. - - - __rb__ - - Text\. The command is replaced with a right bracket\. Use in free\-form text\. - Required to avoid interpretation of a right bracket as the end of a markup - command\. Its usage is restricted to the arguments of other commands\. - - - __toc\_begin__ *text* *title* - - Document structure\. The command to start a table of contents\. The arguments - are a label for the whole group of documents the index refers to \(*text*\) - and the overall title text for the index \(*title*\), without markup\. - - The label often is the name of the package \(or extension\) the documents - belong to\. - - - __toc\_end__ - - Document structure\. Command to end a table of contents\. Anything in the - document coming after this command is in error\. - - - __vset__ *varname* *value* - - Templating\. In this form the command sets the named document variable to the - specified *value*\. It does not generate output\. I\.e\. the command is - replaced by the empty string\. - - - __vset__ *varname* - - Templating\. In this form the command is replaced by the value of the named - document variable - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_intro](doctoc\_intro\.md), [doctoc\_lang\_faq](doctoc\_lang\_faq\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md) - -# KEYWORDS - -[doctoc commands](\.\./\.\./\.\./\.\./index\.md\#doctoc\_commands), [doctoc -language](\.\./\.\./\.\./\.\./index\.md\#doctoc\_language), [doctoc -markup](\.\./\.\./\.\./\.\./index\.md\#doctoc\_markup), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_lang_faq.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_lang_faq.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_lang_faq.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_lang_faq.md @@ -1,112 +0,0 @@ - -[//000000001]: # (doctoc\_lang\_faq \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_lang\_faq\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctoc\_lang\_faq\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_lang\_faq \- doctoc language faq - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [What is this document?](#subsection1) - - - [EXAMPLES](#section3) - - - [Where do I find doctoc examples?](#subsection2) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -# OVERVIEW - -## What is this document? - -This document is currently mainly a placeholder, to be filled with commonly -asked questions about the doctoc markup language and companions, and their -answers\. - -Please report any questions \(and, if possible, answers\) we should consider for -this document as explained in the section [Bugs, Ideas, -Feedback](#section4) below\. - -# EXAMPLES - -## Where do I find doctoc examples? - -We have no direct examples of documents written using doctoc markup\. However the -doctools processor __[dtplite](\.\./\.\./apps/dtplite\.md)__ does generate a -table of contents when processing a set of documents written in doctools markup\. -The intermediate file for it uses doctoc markup and is not deleted when -generation completes\. Such files can therefore serve as examples\. - -__[dtplite](\.\./\.\./apps/dtplite\.md)__ is distributed as part of Tcllib, -so to get it you need one of - - 1. A snapshot of Tcllib\. How to retrieve such a snapshot and the tools - required for this are described at [Development - Snapshots](/wiki?name=Development\+Snapshots) - - 1. A Tcllib release archive\. They are available at the [home](/home) page\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md) - -# KEYWORDS - -[doctoc commands](\.\./\.\./\.\./\.\./index\.md\#doctoc\_commands), [doctoc -language](\.\./\.\./\.\./\.\./index\.md\#doctoc\_language), [doctoc -markup](\.\./\.\./\.\./\.\./index\.md\#doctoc\_markup), [doctoc -syntax](\.\./\.\./\.\./\.\./index\.md\#doctoc\_syntax), -[examples](\.\./\.\./\.\./\.\./index\.md\#examples), -[faq](\.\./\.\./\.\./\.\./index\.md\#faq), [markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[semantic markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md @@ -1,299 +0,0 @@ - -[//000000001]: # (doctoc\_lang\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_lang\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctoc\_lang\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_lang\_intro \- doctoc language introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#subsection1) - - - [Basic structure](#subsection2) - - - [Items](#subsection3) - - - [Divisions](#subsection4) - - - [Advanced structure](#subsection5) - - - [Escapes](#subsection6) - - - [FURTHER READING](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document is an informal introduction to version 1\.1 of the doctoc markup -language based on a multitude of examples\. After reading this a writer should be -ready to understand the two parts of the formal specification, i\.e\. the -*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification and the -*[doctoc language command reference](doctoc\_lang\_cmdref\.md)*\. - -## Fundamentals - -While the *doctoc markup language* is quite similar to the *doctools markup -language*, in the broadest terms possible, there is one key difference\. A table -of contents consists essentially only of markup commands, with no plain text -interspersed between them, except for whitespace\. - -Each markup command is a Tcl command surrounded by a matching pair of __\[__ -and __\]__\. Inside of these delimiters the usual rules for a Tcl command -apply with regard to word quotation, nested commands, continuation lines, etc\. -I\.e\. - - ... [division_start {Appendix 1}] ... - - ... [item thefile \ - label {file description}] ... - -## Basic structure - -The most simple document which can be written in doctoc is - - [toc_begin GROUPTITLE TITLE] - [toc_end] - -This also shows us that all doctoc documents consist of only one part where we -will list *items* and *divisions*\. - -The user is free to mix these as she sees fit\. This is a change from version 1 -of the language, which did not allow this mixing, but only the use of either a -series of items or a series of divisions\. - -We will discuss the commands for each of these two possibilities in the next -sections\. - -## Items - -Use the command __item__ to put an *item* into a table of contents\. This -is essentially a reference to a section, subsection, etc\. in the document, or -set of documents, the table of contents is for\. The command takes three -arguments, a symbolic name for the file the item is for and two text to label -the item and describe the referenced section\. - -Symbolic names are used to preserve the convertibility of this format to any -output format\. The actual name of any file will be inserted by the chosen -formatting engine when converting the input, based on a mapping from symbolic to -actual names given to the engine\. - -Here a made up example for a table of contents of this document: - -> \[toc\_begin Doctoc \{Language Introduction\}\] -> \[__item 1 DESCRIPTION__\] -> \[__item 1\.1 \{Basic structure\}__\] -> \[__item 1\.2 Items__\] -> \[__item 1\.3 Divisions__\] -> \[__item 2 \{FURTHER READING\}__\] -> \[toc\_end\] - -## Divisions - -One thing of notice in the last example in the previous section is that the -referenced sections actually had a nested structure, something which was -expressed in the item labels, by using a common prefix for all the sections -nested under section 1\. - -This kind of structure can be made more explicit in the doctoc language by using -divisions\. Instead of using a series of plain items we use a series of divisions -for the major references, and then place the nested items inside of these\. - -Of course, instead of the nested items we can again use divisions and thus nest -arbitrarily deep\. - -A division is marked by two commands instead of one, one to start it, the other -to close the last opened division\. They are: - - - __division\_start__ - - This command opens a new division\. It takes one or two arguments, the title - of the division, and the symbolic name of the file it refers to\. The latter - is optional\. If the symbolic filename is present then the section title - should link to the referenced document, if links are supported by the output - format\. - - - __division\_end__ - - This command closes the last opened and not yet closed division\. - -Using this we can recast the last example like this - -> \[toc\_begin Doctoc \{Language Introduction\}\] -> \[__division\_start DESCRIPTION__\] -> \[item 1 \{Basic structure\}\] -> \[item 2 Items\] -> \[item 3 Divisions\] -> \[__division\_end__\] -> \[__division\_start \{FURTHER READING\}__\] -> \[__division\_end__\] -> \[toc\_end\] - -Or, to demonstrate deeper nesting - -> \[toc\_begin Doctoc \{Language Introduction\}\] -> \[__division\_start DESCRIPTION__\] -> \[__division\_start \{Basic structure\}__\] -> \[item 1 Do\] -> \[item 2 Re\] -> \[__division\_end__\] -> \[__division\_start Items__\] -> \[item a Fi\] -> \[item b Fo\] -> \[item c Fa\] -> \[__division\_end__\] -> \[__division\_start Divisions__\] -> \[item 1 Sub\] -> \[item 1 Zero\] -> \[__division\_end__\] -> \[__division\_end__\] -> \[__division\_start \{FURTHER READING\}__\] -> \[__division\_end__\] -> \[toc\_end\] - -And do not forget, it is possible to freely mix items and divisions, and to have -empty divisions\. - -> \[toc\_begin Doctoc \{Language Introduction\}\] -> \[item 1 Do\] -> \[__division\_start DESCRIPTION__\] -> \[__division\_start \{Basic structure\}__\] -> \[item 2 Re\] -> \[__division\_end__\] -> \[item a Fi\] -> \[__division\_start Items__\] -> \[item b Fo\] -> \[item c Fa\] -> \[__division\_end__\] -> \[__division\_start Divisions__\] -> \[__division\_end__\] -> \[__division\_end__\] -> \[__division\_start \{FURTHER READING\}__\] -> \[__division\_end__\] -> \[toc\_end\] - -## Advanced structure - -In all previous examples we fudged a bit regarding the markup actually allowed -to be used before the __toc\_begin__ command opening the document\. - -Instead of only whitespace the two templating commands __include__ and -__vset__ are also allowed, to enable the writer to either set and/or import -configuration settings relevant to the table of contents\. I\.e\. it is possible to -write - -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \[toc\_begin GROUPTITLE TITLE\] -> \.\.\. -> \[toc\_end\] - -Even more important, these two commands are allowed anywhere where a markup -command is allowed, without regard for any other structure\. - -> \[toc\_begin GROUPTITLE TITLE\] -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \.\.\. -> \[toc\_end\] - -The only restriction __include__ has to obey is that the contents of the -included file must be valid at the place of the inclusion\. I\.e\. a file included -before __toc\_begin__ may contain only the templating commands __vset__ -and __include__, a file included in a division may contain only items or -divisions commands, etc\. - -## Escapes - -Beyond the 6 commands shown so far we have two more available\. However their -function is not the marking up of toc structure, but the insertion of -characters, namely __\[__ and __\]__\. These commands, __lb__ and -__rb__ respectively, are required because our use of \[ and \] to bracket -markup commands makes it impossible to directly use \[ and \] within the text\. - -Our example of their use are the sources of the last sentence in the previous -paragraph, with some highlighting added\. - ->   \.\.\. ->   These commands, \[cmd lb\] and \[cmd lb\] respectively, are required ->   because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it ->   impossible to directly use \[__lb__\] and \[__rb__\] within the text\. ->   \.\.\. - -# FURTHER READING - -Now that this document has been digested the reader, assumed to be a *writer* -of documentation should be fortified enough to be able to understand the formal -*[doctoc language syntax](doctoc\_lang\_syntax\.md)* specification as well\. -From here on out the *[doctoc language command -reference](doctoc\_lang\_cmdref\.md)* will also serve as the detailed -specification and cheat sheet for all available commands and their syntax\. - -To be able to validate a document while writing it, it is also recommended to -familiarize oneself with Tclapps' ultra\-configurable __dtp__\. - -On the other hand, doctoc is perfectly suited for the automatic generation from -doctools documents, and this is the route Tcllib's easy and simple -__[dtplite](\.\./\.\./apps/dtplite\.md)__ goes, creating a table of contents -for a set of documents behind the scenes, without the writer having to do so on -their own\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_intro](doctoc\_intro\.md), -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md) - -# KEYWORDS - -[doctoc commands](\.\./\.\./\.\./\.\./index\.md\#doctoc\_commands), [doctoc -language](\.\./\.\./\.\./\.\./index\.md\#doctoc\_language), [doctoc -markup](\.\./\.\./\.\./\.\./index\.md\#doctoc\_markup), [doctoc -syntax](\.\./\.\./\.\./\.\./index\.md\#doctoc\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_lang_syntax.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_lang_syntax.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_lang_syntax.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_lang_syntax.md @@ -1,143 +0,0 @@ - -[//000000001]: # (doctoc\_lang\_syntax \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_lang\_syntax\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2009 Andreas Kupries ) -[//000000004]: # (doctoc\_lang\_syntax\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_lang\_syntax \- doctoc language syntax - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#section2) - - - [Lexical definitions](#section3) - - - [Syntax](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document contains the formal specification of the syntax of the doctoc -markup language, version 1\.1 in Backus\-Naur\-Form\. This document is intended to -be a reference, complementing the *[doctoc language command -reference](doctoc\_lang\_cmdref\.md)*\. A beginner should read the much more -informally written *[doctoc language introduction](doctoc\_lang\_intro\.md)* -first before trying to understand either this document or the command reference\. - -# Fundamentals - -In the broadest terms possible the *doctoc markup language* is like SGML and -similar languages\. A document written in this language consists primarily of -markup commands, with text embedded into it at some places\. - -Each markup command is a just Tcl command surrounded by a matching pair of -__\[__ and __\]__\. Which commands are available, and their arguments, i\.e\. -syntax is specified in the *[doctoc language command -reference](doctoc\_lang\_cmdref\.md)*\. - -In this document we specify first the lexeme, and then the syntax, i\.e\. how we -can mix text and markup commands with each other\. - -# Lexical definitions - -In the syntax rules listed in the next section - - 1. stands for all text except markup commands\. - - 1. Any XXX stands for the markup command \[xxx\] including its arguments\. Each - markup command is a Tcl command surrounded by a matching pair of __\[__ - and __\]__\. Inside of these delimiters the usual rules for a Tcl command - apply with regard to word quotation, nested commands, continuation lines, - etc\. - - 1. stands for all text consisting only of spaces, newlines, tabulators - and the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ markup command\. - -# Syntax - -The rules listed here specify only the syntax of doctoc documents\. The lexical -level of the language was covered in the previous section\. - -Regarding the syntax of the \(E\)BNF itself - - 1. The construct \{ X \} stands for zero or more occurrences of X\. - - 1. The construct \[ X \] stands for zero or one occurrence of X\. - -The syntax: - - toc = defs - TOC_BEGIN - contents - TOC_END - { } - - defs = { INCLUDE | VSET | } - contents = { defs entry } [ defs ] - - entry = ITEM | division - - division = DIVISION_START - contents - DIVISION_END - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_intro](doctoc\_intro\.md), -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_faq](doctoc\_lang\_faq\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md) - -# KEYWORDS - -[doctoc commands](\.\./\.\./\.\./\.\./index\.md\#doctoc\_commands), [doctoc -language](\.\./\.\./\.\./\.\./index\.md\#doctoc\_language), [doctoc -markup](\.\./\.\./\.\./\.\./index\.md\#doctoc\_markup), [doctoc -syntax](\.\./\.\./\.\./\.\./index\.md\#doctoc\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctoc_plugin_apiref.md Index: embedded/md/tcllib/files/modules/doctools/doctoc_plugin_apiref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctoc_plugin_apiref.md +++ embedded/md/tcllib/files/modules/doctools/doctoc_plugin_apiref.md @@ -1,418 +0,0 @@ - -[//000000001]: # (doctoc\_plugin\_apiref \- Documentation tools) -[//000000002]: # (Generated from file 'doctoc\_plugin\_apiref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctoc\_plugin\_apiref\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctoc\_plugin\_apiref \- doctoc plugin API reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [FRONTEND COMMANDS](#section3) - - - [PLUGIN COMMANDS](#section4) - - - [Management commands](#subsection1) - - - [Formatting commands](#subsection2) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__dt\_fmap__ *symfname*](#1) -[__dt\_format__](#2) -[__dt\_read__ *file*](#3) -[__dt\_source__ *file*](#4) -[__ex\_cappend__ *text*](#5) -[__ex\_cget__ *varname*](#6) -[__ex\_cis__ *cname*](#7) -[__ex\_cname__](#8) -[__ex\_cpop__ *cname*](#9) -[__ex\_cpush__ *cname*](#10) -[__ex\_cset__ *varname* *value*](#11) -[__ex\_lb__ ?*newbracket*?](#12) -[__ex\_rb__ ?*newbracket*?](#13) -[__toc\_initialize__](#14) -[__toc\_listvariables__](#15) -[__toc\_numpasses__](#16) -[__toc\_postprocess__ *text*](#17) -[__toc\_setup__ *n*](#18) -[__toc\_shutdown__](#19) -[__toc\_varset__ *varname* *text*](#20) -[__fmt\_plain\_text__ *text*](#21) - -# DESCRIPTION - -This document is intended for *plugin writers*, i\.e\. developers wishing to -write a toc *[formatting engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* -for some output format X\. - -It specifies the interaction between the __[doctools::toc](doctoc\.md)__ -package and its plugins, i\.e\. the interface any toc formatting engine has to -comply with\. - -This document deals with version 1 of the interface\. - -A reader who is on the other hand more interested in the markup language itself -should start with the *[doctoc language -introduction](doctoc\_lang\_intro\.md)* and proceed from there to the formal -specifications, i\.e\. the *[doctoc language syntax](doctoc\_lang\_syntax\.md)* -and the *[doctoc language command reference](doctoc\_lang\_cmdref\.md)*\. - -# OVERVIEW - -The API for a toc formatting engine consists of two major sections\. - -On the one side we have a set of commands through which the plugin is able to -query the frontend\. These commands are provided by the frontend and linked into -the plugin interpreter\. Please see section [FRONTEND COMMANDS](#section3) -for their detailed specification\. - -And on the other side the plugin has to provide its own set of commands which -will then be called by the frontend in a specific sequence while processing -input\. They, again, fall into two categories, management and formatting\. Please -see section [PLUGIN COMMANDS](#section4) and its subsections for their -detailed specification\. - -# FRONTEND COMMANDS - -This section specifies the set of commands through which a plugin, also known as -a toc formatting engine, is able to query the frontend\. These commands are -provided by the frontend and linked into the plugin interpreter\. - -I\.e\. a toc formatting engine can assume that all of the following commands are -present when any of its own commands \(as specified in section [PLUGIN -COMMANDS](#section4)\) are executed\. - -Beyond that it can also assume that it has full access to its own safe -interpreter and thus is not able to damage the other parts of the processor, nor -can it damage the filesystem\. It is however able to either kill or hang the -whole process, by exiting, or running an infinite loop\. - -Coming back to the imported commands, all the commands with prefix *dt\_* -provide limited access to specific parts of the frontend, whereas the commands -with prefix *ex\_* provide access to the state of the -__[textutil::expander](\.\./textutil/expander\.md)__ object which does the -main parsing of the input within the frontend\. These commands should not be -except under very special circumstances\. - - - __dt\_fmap__ *symfname* - - Query command\. It returns the actual pathname to use in the output in place - of the symbolic filename *symfname*\. It will return the unchanged input if - no mapping was established for *symfname*\. - - The required mappings are established with the method __map__ of a - frontend, as explained in section __OBJECT METHODS__ of the - documentation for the package __[doctools::toc](doctoc\.md)__\. - - - __dt\_format__ - - Query command\. It returns the name of the format associated with the toc - formatting engine\. - - - __dt\_read__ *file* - - Controlled filesystem access\. Returns contents of *file* for whatever use - desired by the plugin\. Only files which are either in the same directory as - the file containing the engine, or below it, can be loaded\. Trying to load a - file outside of this directory causes an error\. - - - __dt\_source__ *file* - - Controlled filesystem access\. This command allows the toc formatting engine - to load additional Tcl code it may need\. Only files which are either in the - same directory as the file containing the engine, or below it, can be - loaded\. Trying to load a file outside of this directory causes an error\. - - - __ex\_cappend__ *text* - - Appends a string to the output in the current context\. This command should - rarely be used by macros or application code\. - - - __ex\_cget__ *varname* - - Retrieves the value of variable *varname*, defined in the current context\. - - - __ex\_cis__ *cname* - - Determines whether or not the name of the current context is *cname*\. - - - __ex\_cname__ - - Returns the name of the current context\. - - - __ex\_cpop__ *cname* - - Pops a context from the context stack, returning all accumulated output in - that context\. The context must be named *cname*, or an error results\. - - - __ex\_cpush__ *cname* - - Pushes a context named *cname* onto the context stack\. The context must be - popped by __cpop__ before expansion ends or an error results\. - - - __ex\_cset__ *varname* *value* - - Sets variable *varname* to *value* in the current context\. - - - __ex\_lb__ ?*newbracket*? - - Returns the current value of the left macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - - - __ex\_rb__ ?*newbracket*? - - Returns the current value of the right macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - -# PLUGIN COMMANDS - -The plugin has to provide its own set of commands which will then be called by -the frontend in a specific sequence while processing input\. They fall into two -categories, management and formatting\. Their expected names, signatures, and -responsibilities are specified in the following two subsections\. - -## Management commands - -The management commands a plugin has to provide are used by the frontend to - - 1. initialize and shutdown the plugin - - 1. determine the number of passes it has to make over the input - - 1. initialize and shutdown each pass - - 1. query and initialize engine parameters - -After the plugin has been loaded and the frontend commands are established the -commands will be called in the following sequence: - - toc_numpasses -> n - toc_listvariables -> vars - - toc_varset var1 value1 - toc_varset var2 value2 - ... - toc_varset varK valueK - toc_initialize - toc_setup 1 - ... - toc_setup 2 - ... - ... - toc_setup n - ... - toc_postprocess - toc_shutdown - ... - -I\.e\. first the number of passes and the set of available engine parameters is -established, followed by calls setting the parameters\. That second part is -optional\. - -After that the plugin is initialized, the specified number of passes executed, -the final result run through a global post processing step and at last the -plugin is shutdown again\. This can be followed by more conversions, restarting -the sequence at __toc\_varset__\. - -In each of the passes, i\.e\. after the calls of __toc\_setup__ the frontend -will process the input and call the formatting commands as markup is -encountered\. This means that the sequence of formatting commands is determined -by the grammar of the doctoc markup language, as specified in the *[doctoc -language syntax](doctoc\_lang\_syntax\.md)* specification\. - -A different way of looking at the sequence is: - - - First some basic parameters are determined\. - - - Then everything starting at the first __toc\_varset__ to - __toc\_shutdown__ forms a *run*, the formatting of a single input\. Each - run can be followed by more\. - - - Embedded within each run we have one or more *passes*, each starting with - __toc\_setup__ and going until either the next __toc\_setup__ or - __toc\_postprocess__ is reached\. - - If more than one pass is required to perform the formatting only the output - of the last pass is relevant\. The output of all the previous, preparatory - passes is ignored\. - -The commands, their names, signatures, and responsibilities are, in detail: - - - __toc\_initialize__ - - *Initialization/Shutdown*\. This command is called at the beginning of - every conversion run, as the first command of that run\. Note that a run is - not a pass, but may consist of multiple passes\. It has to initialize the - general state of the plugin, beyond the initialization done during the load\. - No return value is expected, and any returned value is ignored\. - - - __toc\_listvariables__ - - *Initialization/Shutdown* and *Engine parameters*\. Second command is - called after the plugin code has been loaded, i\.e\. immediately after - __toc\_numpasses__\. It has to return a list containing the names of the - parameters the frontend can set to configure the engine\. This list can be - empty\. - - - __toc\_numpasses__ - - *Initialization/Shutdown* and *Pass management*\. First command called - after the plugin code has been loaded\. No other command of the engine will - be called before it\. It has to return the number of passes this engine - requires to fully process the input document\. This value has to be an - integer number greater or equal to one\. - - - __toc\_postprocess__ *text* - - *Initialization/Shutdown*\. This command is called immediately after the - last pass in a run\. Its argument is the result of the conversion generated - by that pass\. It is provided to allow the engine to perform any global - modifications of the generated document\. If no post\-processing is required - for a specific format the command has to just return the argument\. - - Expected to return a value, the final result of formatting the input\. - - - __toc\_setup__ *n* - - *Initialization/Shutdown* and *Pass management*\. This command is called - at the beginning of each pass over the input in a run\. Its argument is the - number of the pass which has begun\. Passes are counted from __1__ - upward\. The command has to set up the internal state of the plugin for this - particular pass\. No return value is expected, and any returned value is - ignored\. - - - __toc\_shutdown__ - - *Initialization/Shutdown*\. This command is called at the end of every - conversion run\. It is the last command called in a run\. It has to clean up - of all the run\-specific state in the plugin\. After the call the engine has - to be in a state which allows the initiation of another run without fear - that information from the last run is leaked into this new run\. No return - value is expected, and any returned value is ignored\. - - - __toc\_varset__ *varname* *text* - - *Engine parameters*\. This command is called by the frontend to set an - engine parameter to a particular value\. The parameter to change is specified - by *varname*, the value to set in *text*\. - - The command has to throw an error if an unknown *varname* is used\. Only - the names returned by __toc\_listvariables__ have to be considered as - known\. - - The values of all engine parameters have to persist between passes and runs\. - -## Formatting commands - -The formatting commands have to implement the formatting for the output format, -for all the markup commands of the doctoc markup language, except __lb__, -__rb__, __vset__, __include__, and -__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__\. These exceptions are -processed by the frontend and are never seen by the plugin\. In return a command -for the formatting of plain text has to be provided, something which has no -markup in the input at all\. - -This means, that each of the five markup commands specified in the *[doctoc -language command reference](doctoc\_lang\_cmdref\.md)* and outside of the set -of exceptions listed above has an equivalent formatting command which takes the -same arguments as the markup command and whose name is the name of markup -command with the prefix *fmt\_* added to it\. - -All commands are expected to format their input in some way per the semantics -specified in the command reference and to return whatever part of this that they -deem necessary as their result, which will be added to the output\. - -To avoid essentially duplicating the command reference we do not list any of the -command here and simply refer the reader to the *[doctoc language command -reference](doctoc\_lang\_cmdref\.md)* for their signature and description\. The -sole exception is the plain text formatter, which has no equivalent markup -command\. - -The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the doctoc markup -language, as specified in the *[doctoc language -syntax](doctoc\_lang\_syntax\.md)* specification\. - - - __fmt\_plain\_text__ *text* - - *No associated markup command*\. - - Called by the frontend for any plain text encountered in the input\. It has - to perform any and all special processing required for plain text\. - - The formatted text is expected as the result of the command, and added to - the output\. If no special processing is required it has to simply return its - argument without change\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctoc\_intro](doctoc\_intro\.md), -[doctoc\_lang\_cmdref](doctoc\_lang\_cmdref\.md), -[doctoc\_lang\_faq](doctoc\_lang\_faq\.md), -[doctoc\_lang\_intro](doctoc\_lang\_intro\.md), -[doctoc\_lang\_syntax](doctoc\_lang\_syntax\.md), [doctools::toc](doctoc\.md) - -# KEYWORDS - -[formatting engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc), [toc -formatter](\.\./\.\./\.\./\.\./index\.md\#toc\_formatter) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools.md Index: embedded/md/tcllib/files/modules/doctools/doctools.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools.md +++ embedded/md/tcllib/files/modules/doctools/doctools.md @@ -1,539 +0,0 @@ - -[//000000001]: # (doctools \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2019 Andreas Kupries ) -[//000000004]: # (doctools\(n\) 1\.5\.6 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools \- doctools \- Processing documents - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [PACKAGE COMMANDS](#subsection1) - - - [OBJECT COMMAND](#subsection2) - - - [OBJECT METHODS](#subsection3) - - - [OBJECT CONFIGURATION](#subsection4) - - - [FORMAT MAPPING](#subsection5) - - - [PREDEFINED ENGINES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require doctools ?1\.5\.6? - -[__::doctools::new__ *objectName* ?*option value*\.\.\.?](#1) -[__::doctools::help__](#2) -[__::doctools::search__ *path*](#3) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#4) -[*objectName* __configure__](#5) -[*objectName* __configure__ *option*](#6) -[*objectName* __configure__ __\-option__ *value*\.\.\.](#7) -[*objectName* __cget__ __\-option__](#8) -[*objectName* __destroy__](#9) -[*objectName* __format__ *text*](#10) -[*objectName* __map__ *symbolic* *actual*](#11) -[*objectName* __parameters__](#12) -[*objectName* __search__ *path*](#13) -[*objectName* __setparam__ *name* *value*](#14) -[*objectName* __warnings__](#15) - -# DESCRIPTION - -This package provides a class for the creation of objects able to process and -convert text written in the *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* -markup language into any output format X for which a *[formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* is available\. - -A reader interested in the markup language itself should start with the -*[doctools language introduction](doctools\_lang\_intro\.md)* and proceed -from there to the formal specifications, i\.e\. the *[doctools language -syntax](doctools\_lang\_syntax\.md)* and the *[doctools language command -reference](doctools\_lang\_cmdref\.md)*\. - -If on the other hand the reader wishes to write her own formatting engine for -some format, i\.e\. is a *plugin writer* then reading and understanding the -*[doctools plugin API reference](doctools\_plugin\_apiref\.md)* is an -absolute necessity, as that document specifies the interaction between this -package and its plugins, i\.e\. the formatting engines, in detail\. - -# PUBLIC API - -## PACKAGE COMMANDS - - - __::doctools::new__ *objectName* ?*option value*\.\.\.? - - This command creates a new doctools object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [OBJECT COMMAND](#subsection2) and [OBJECT - METHODS](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - - The options and their values coming after the name of the object are used to - set the initial configuration of the object\. - - - __::doctools::help__ - - This is a convenience command for applications wishing to provide their user - with a short description of the available formatting commands and their - meanings\. It returns a string containing a standard help text\. - - - __::doctools::search__ *path* - - Whenever an object created by this the package has to map the name of a - format to the file containing the code for its formatting engine it will - search for the file in a number of directories stored in a list\. See section - [FORMAT MAPPING](#subsection5) for more explanations\. - - This list not only contains three default directories which are declared by - the package itself, but is also extensible user of the package\. This command - is the means to do so\. When given a *path* to an existing and readable - directory it will prepend that directory to the list of directories to - search\. This means that the *path* added last is later searched through - first\. - - An error will be thrown if the *path* either does not exist, is not a - directory, or is not readable\. - -## OBJECT COMMAND - -All commands created by __::doctools::new__ have the following general form -and may be used to invoke various operations on their doctools converter object\. - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [OBJECT METHODS](#subsection3) for - the detailed specifications\. - -## OBJECT METHODS - - - *objectName* __configure__ - - The method returns a list of all known options and their current values when - called without any arguments\. - - - *objectName* __configure__ *option* - - The method behaves like the method __cget__ when called with a single - argument and returns the value of the option specified by said argument\. - - - *objectName* __configure__ __\-option__ *value*\.\.\. - - The method reconfigures the specified __option__s of the object, setting - them to the associated *value*s, when called with an even number of - arguments, at least two\. - - The legal options are described in the section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __cget__ __\-option__ - - This method expects a legal configuration option as argument and will return - the current value of that option for the object the method was invoked for\. - - The legal configuration options are described in section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __format__ *text* - - This method runs the *text* through the configured formatting engine and - returns the generated string as its result\. An error will be thrown if no - __\-format__ was configured for the object\. - - The method assumes that the *text* is in - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format as specified in the - companion document *doctools\_fmt*\. Errors will be thrown otherwise\. - - - *objectName* __map__ *symbolic* *actual* - - This methods add one entry to the per\-object mapping from *symbolic* - filenames to the *actual* uris\. The object just stores this mapping and - makes it available to the configured formatting engine through the command - __dt\_fmap__\. This command is described in more detail in the - *[doctools plugin API reference](doctools\_plugin\_apiref\.md)* which - specifies the interaction between the objects created by this package and - doctools formatting engines\. - - - *objectName* __parameters__ - - This method returns a list containing the names of all engine parameters - provided by the configured formatting engine\. It will return an empty list - if the object is not yet configured for a specific format\. - - - *objectName* __search__ *path* - - This method extends the per\-object list of paths searched for doctools - formatting engines\. See also the command __::doctools::search__ on how - to extend the per\-package list of paths\. Note that the path entered last - will be searched first\. For more details see section [FORMAT - MAPPING](#subsection5)\. - - - *objectName* __setparam__ *name* *value* - - This method sets the *name*d engine parameter to the specified *value*\. - It will throw an error if the object is either not yet configured for a - specific format, or if the formatting engine for the configured format does - not provide a parameter with the given *name*\. The list of parameters - provided by the configured formatting engine can be retrieved through the - method __parameters__\. - - - *objectName* __warnings__ - - This method returns a list containing all the warnings which were generated - by the configured formatting engine during the last invocation of the method - __format__\. - -## OBJECT CONFIGURATION - -All doctools objects understand the following configuration options: - - - __\-file__ *file* - - The argument of this option is stored in the object and made available to - the configured formatting engine through the commands __dt\_file__ and - __dt\_mainfile__\. These commands are described in more detail in the - companion document *doctools\_api* which specifies the API between the - object and formatting engines\. - - The default value of this option is the empty string\. - - The configured formatting engine should interpret the value as the name of - the file containing the document which is currently processed\. - - - __\-ibase__ *file* - - The argument of this option is stored in the object and used as the base - path for resolution of relative include paths\. If this option is not set - \(empty string\) the value of __\-file__ is used instead\. - - Note that __\-file__ and __\-ibase__, while similar looking, are - actually very different\. The value of __\-file__ is used by some engines - for the generation of proper relative references between output documents - \(HTML\)\. As such this is a *destination* path\. The __\-ibase__ on the - other hand is used to resolve relative include paths, and as such deals with - *[source](\.\./\.\./\.\./\.\./index\.md\#source)* paths\. - - The default value of this option is the empty string\. - - - __\-module__ *text* - - The argument of this option is stored in the object and made available to - the configured formatting engine through the command __dt\_module__\. This - command is described in more detail in the companion document - *doctools\_api* which specifies the API between the object and formatting - engines\. - - The default value of this option is the empty string\. - - The configured formatting engine should interpret the value as the name of - the module the file containing the document which is currently processed - belongs to\. - - - __\-format__ *text* - - The argument of this option specifies the format to generate and by - implication the formatting engine to use when converting text via the method - __format__\. Its default value is the empty string\. The method - __format__ cannot be used if this option is not set to a valid value at - least once\. - - The package will immediately try to map the given name to a file containing - the code for a formatting engine generating that format\. An error will be - thrown if this mapping fails\. In that case a previously configured format is - left untouched\. - - The section [FORMAT MAPPING](#subsection5) explains in detail how the - package and object will look for engine implementations\. - - - __\-deprecated__ *boolean* - - This option is a boolean flag\. The object will generate warnings if this - flag is set and the text given to method __format__ contains the - deprecated markup command __strong__\. Its default value is - __FALSE__\. In other words, no warnings will be generated\. - - - __\-copyright__ *text* - - The argument of this option is stored in the object and made available to - the configured formatting engine through the command __dt\_copyright__\. - This command is described in more detail in the companion document - *doctools\_api* which specifies the API between the object and formatting - engines\. - - The default value of this option is the empty string\. - - The configured formatting engine should interpret the value as a copyright - assignment for the document which is currently processed, or the package - described by it\. - - This information must be used if and only if the engine is unable to find - any copyright assignments within the document itself\. Such are specified by - the formatting command __copyright__\. This command is described in more - detail in the companion document *doctools\_fmt* which specifies the - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format itself\. - -## FORMAT MAPPING - -The package and object will perform the following algorithm when trying to map a -format name *foo* to a file containing an implementation of a formatting -engine for *foo*: - - 1. If *foo* is the name of an existing file then this file is directly taken - as the implementation\. - - 1. If not, the list of per\-object search paths is searched\. For each directory - in the list the package checks if that directory contains a file - "fmt\.*foo*"\. If yes, then that file is taken as the implementation\. - - Note that this list of paths is initially empty and can be extended through - the object method __search__\. - - 1. If not, the list of package paths is searched\. For each directory in the - list the package checks if that directory contains a file "fmt\.*foo*"\. If - yes, then that file is taken as the implementation\. - - This list of paths can be extended through the command - __::doctools::search__\. It contains initially one path, the - subdirectory "mpformats" of the directory the package itself is located in\. - In other words, if the package implementation "doctools\.tcl" is installed - in the directory "/usr/local/lib/tcllib/doctools" then it will by default - search the directory "/usr/local/lib/tcllib/doctools/mpformats" for format - implementations\. - - 1. The mapping fails\. - -# PREDEFINED ENGINES - -The package provides predefined engines for the following formats\. Some of the -engines support parameters\. These will be explained below as well\. - - - html - - This engine generates HTML markup, for processing by web browsers and the - like\. This engine supports four parameters: - - * footer - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just before the - ____ tag, closing the body of the generated HTML\. - - This can be used to insert boilerplate footer markup into the generated - document\. - - * header - - The value for this parameter has to be valid selfcontained HTML markup - for the body section of a HTML document\. The default value is the empty - string\. The value is inserted into the generated output just after the - ____ tag, starting the body of the generated HTML\. - - This can be used to insert boilerplate header markup into the generated - document\. - - * meta - - The value for this parameter has to be valid selfcontained HTML markup - for the header section of a HTML document\. The default value is the - empty string\. The value is inserted into the generated output just after - the ____ tag, starting the header section of the generated - HTML\. - - This can be used to insert boilerplate meta data markup into the - generated document, like references to a stylesheet, standard meta - keywords, etc\. - - * xref - - The value for this parameter has to be a list of triples specifying - cross\-reference information\. This information is used by the engine to - create more hyperlinks\. Each triple is a list containing a pattern, - symbolic filename and fragment reference, in this order\. If a pattern is - specified multiple times the last occurrence of the pattern will be - used\. - - The engine will consult the xref database when encountering specific - commands and will create a link if the relevant text matches one of the - patterns\. No link will be created if no match was found\. The link will - go to the uri __file\#fragment__ listed in the relevant triple, after - conversion of the symbolic file name to the actual uri via - __dt\_fmap__ \(see the *[doctools plugin API - reference](doctools\_plugin\_apiref\.md)*\)\. This file\-to\-uri mapping - was build by calls to the method __map__ of the doctools object \(See - section [OBJECT METHODS](#subsection3)\)\. - - The following formatting commands will consult the xref database: - - + __cmd__ *word* - - The command will look for the patterns __sa,__*word*, and - *word*, in this order\. If this fails if it will convert *word* - to all lowercase and try again\. - - + __syscmd__ *word* - - The command will look for the patterns __sa,__*word*, and - *word*, in this order\. If this fails if it will convert *word* - to all lowercase and try again\. - - + __[term](\.\./term/term\.md)__ *word* - - The command will look for the patterns __kw,__*word*, - __sa,__*word*, and *word*, in this order\. If this fails if - it will convert *word* to all lowercase and try again\. - - + __[package](\.\./\.\./\.\./\.\./index\.md\#package)__ *word* - - The command will look for the patterns __sa,__*word*, - __kw,__*word*, and *word*, in this order\. If this fails if - it will convert *word* to all lowercase and try again\. - - + __see\_also__ *word*\.\.\. - - The command will look for the patterns __sa,__*word*, and - *word*, in this order, for each *word* given to the command\. If - this fails if it will convert *word* to all lowercase and try - again\. - - + __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ *word*\.\.\. - - The command will look for the patterns __kw,__*word*, and - *word*, in this order, for each *word* given to the command\. If - this fails if it will convert *word* to all lowercase and try - again\. - - - latex - - This engine generates output suitable for the - __[latex](\.\./\.\./\.\./\.\./index\.md\#latex)__ text processor coming out of - the TeX world\. - - - list - - This engine retrieves version, section and title of the manpage from the - document\. As such it can be used to generate a directory listing for a set - of manpages\. - - - nroff - - This engine generates nroff output, for processing by - __[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff)__, or __groff__\. The - result will be standard man pages as they are known in the unix world\. - - - markdown - - This engine generates *[Markdown](\.\./\.\./\.\./\.\./index\.md\#markdown)* - markup\. This engine supports two parameters: - - * header - - The value for this parameter has to be valid selfcontained markdown - markup for the body section of a markdown document\. The default value is - the empty string\. The value is inserted into the generated output just - before the table of contents\. - - This can be used to insert boilerplate header markup into the generated - document\. - - * xref - - The value for this parameter has to be a list of triples specifying - cross\-reference information\. - - The full details of expected syntax and engine\-internal use are - explained above for the *[html](\.\./\.\./\.\./\.\./index\.md\#html)* - engine\. - - - null - - This engine generates no outout at all\. This can be used if one just wants - to validate some input\. - - - tmml - - This engine generates TMML markup as specified by Joe English\. The Tcl - Manpage Markup Language is a derivate of XML\. - - - wiki - - This engine generates Wiki markup as understood by Jean Claude Wippler's - __wikit__ application\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools\_intro](doctools\_intro\.md), -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md), -[doctools\_plugin\_apiref](doctools\_plugin\_apiref\.md) - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markdown](\.\./\.\./\.\./\.\./index\.md\#markdown), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2003\-2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_intro.md Index: embedded/md/tcllib/files/modules/doctools/doctools_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_intro.md +++ embedded/md/tcllib/files/modules/doctools/doctools_intro.md @@ -1,131 +0,0 @@ - -[//000000001]: # (doctools\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctools\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_intro \- doctools introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [RELATED FORMATS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* \(short for *documentation -tools*\) stands for a set of related, yet different, entities which are working -together for the easy creation and transformation of documentation\. These are - - 1. A tcl based language for the semantic markup of text\. Markup is represented - by Tcl commands interspersed with the actual text\. - - 1. A package providing the ability to read and transform texts written in that - markup language\. It is important to note that the actual transformation of - the input text is delegated to plugins\. - - 1. An API describing the interface between the package above and a plugin\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the documentation process\. - - 1. A *writer* of documentation has to understand the markup language itself\. - A beginner to doctools should read the more informally written *[doctools - language introduction](doctools\_lang\_intro\.md)* first\. Having digested - this the formal *[doctools language syntax](doctools\_lang\_syntax\.md)* - specification should become understandable\. A writer experienced with - doctools may only need the *[doctools language command - reference](doctools\_lang\_cmdref\.md)* from time to time to refresh her - memory\. - - While a document is written the - __[dtplite](\.\./\.\./apps/dtplite\.md)__ application can be used to - validate it, and after completion it also performs the conversion into the - chosen system of visual markup, be it \*roff, HTML, plain text, wiki, etc\. - - 1. A *processor* of documentation written in the - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* markup language has to - know which tools are available for use\. - - The main tool is the aforementioned - __[dtplite](\.\./\.\./apps/dtplite\.md)__ application provided by - Tcllib\. A more powerful one \(in terms of options and ability to configure - it\) is the __dtp__ application, provided by Tclapps\. At the bottom - level, common to both applications, however sits the package - __[doctools](doctools\.md)__, providing the basic facilities to read - and process files containing text in the doctools format\. - - 1. At last, but not least, *plugin writers* have to understand the - interaction between the __[doctools](doctools\.md)__ package and its - plugins, as described in the *[doctools plugin API - reference](doctools\_plugin\_apiref\.md)*\. - -# RELATED FORMATS - -doctools does not stand alone, it has two companion formats\. These are called -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* and -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)*, and they are for the markup of -*keyword indices*, and *tables of contents*, respectively\. They are -described in their own sets of documents, starting at the *[docidx -introduction](docidx\_intro\.md)* and the *[doctoc -introduction](doctoc\_intro\.md)*, respectively\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[docidx\_intro](docidx\_intro\.md), [doctoc\_intro](doctoc\_intro\.md), -[doctools](doctools\.md), -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](doctools\_lang\_faq\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md), -[doctools\_plugin\_apiref](doctools\_plugin\_apiref\.md) - -# KEYWORDS - -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md Index: embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md +++ embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md @@ -1,601 +0,0 @@ - -[//000000001]: # (doctools\_lang\_cmdref \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_lang\_cmdref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2010 Andreas Kupries ) -[//000000004]: # (doctools\_lang\_cmdref\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_lang\_cmdref \- doctools language command reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__arg__ *text*](#1) -[__arg\_def__ *type* *name* ?*mode*?](#2) -[__bullet__](#3) -[__call__ *args*](#4) -[__category__ *text*](#5) -[__[class](\.\./\.\./\.\./\.\./index\.md\#class)__ *text*](#6) -[__cmd__ *text*](#7) -[__cmd\_def__ *command*](#8) -[__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext*](#9) -[__const__ *text*](#10) -[__copyright__ *text*](#11) -[__def__ *text*](#12) -[__description__](#13) -[__enum__](#14) -[__emph__ *text*](#15) -[__example__ *text*](#16) -[__example\_begin__](#17) -[__example\_end__](#18) -[__[file](\.\./\.\./\.\./\.\./index\.md\#file)__ *text*](#19) -[__fun__ *text*](#20) -[__[image](\.\./\.\./\.\./\.\./index\.md\#image)__ *name* ?*label*?](#21) -[__include__ *filename*](#22) -[__item__](#23) -[__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ *args*](#24) -[__lb__](#25) -[__list\_begin__ *what*](#26) -[__list\_end__](#27) -[__lst\_item__ *text*](#28) -[__manpage\_begin__ *command* *section* *version*](#29) -[__manpage\_end__](#30) -[__[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *text*](#31) -[__moddesc__ *text*](#32) -[__namespace__ *text*](#33) -[__nl__](#34) -[__opt__ *text*](#35) -[__opt\_def__ *name* ?*arg*?](#36) -[__option__ *text*](#37) -[__[package](\.\./\.\./\.\./\.\./index\.md\#package)__ *text*](#38) -[__para__](#39) -[__rb__](#40) -[__require__ *package* ?*version*?](#41) -[__section__ *name*](#42) -[__sectref__ *id* ?*text*?](#43) -[__sectref\-external__ *text*](#44) -[__see\_also__ *args*](#45) -[__strong__ *text*](#46) -[__subsection__ *name*](#47) -[__syscmd__ *text*](#48) -[__[term](\.\./term/term\.md)__ *text*](#49) -[__titledesc__ *desc*](#50) -[__tkoption\_def__ *name* *dbname* *dbclass*](#51) -[__[type](\.\./\.\./\.\./\.\./index\.md\#type)__ *text*](#52) -[__[uri](\.\./uri/uri\.md)__ *text* ?*text*?](#53) -[__usage__ *args*](#54) -[__var__ *text*](#55) -[__vset__ *varname* *value*](#56) -[__vset__ *varname*](#57) -[__[widget](\.\./\.\./\.\./\.\./index\.md\#widget)__ *text*](#58) - -# DESCRIPTION - -This document specifies both names and syntax of all the commands which together -are the doctools markup language, version 1\. As this document is intended to be -a reference the commands are listed in alphabetical order, and the descriptions -are relatively short\. A beginner should read the much more informally written -*[doctools language introduction](doctools\_lang\_intro\.md)* first\. - -# Commands - - - __arg__ *text* - - Text markup\. The argument text is marked up as the *argument* of a - command\. Main uses are the highlighting of command arguments in free\-form - text, and for the argument parameters of the markup commands __call__ - and __usage__\. - - - __arg\_def__ *type* *name* ?*mode*? - - Text structure\. List element\. Argument list\. Automatically closes the - previous list element\. Specifies the data\-*type* of the described argument - of a command, its *name* and its i/o\-*mode*\. The latter is optional\. - - - __bullet__ - - *Deprecated*\. Text structure\. List element\. Itemized list\. See - __item__ for the canonical command to open a list item in an itemized - list\. - - - __call__ *args* - - Text structure\. List element\. Definition list\. Automatically closes the - previous list element\. Defines the term as a command and its arguments\. The - first argument is the name of the command described by the following - free\-form text, and all arguments coming after that are descriptions of the - command's arguments\. It is expected that the arguments are marked up with - __arg__, __[method](\.\./\.\./\.\./\.\./index\.md\#method)__, - __option__ etc\., as is appropriate, and that the command itself is - marked up with __cmd__\. It is expected that the formatted term is not - only printed in place, but also in the table of contents of the document, or - synopsis, depending on the output format\. - - - __category__ *text* - - Document information\. Anywhere\. This command registers its plain text - arguments as the category this document belongs to\. If this command is used - multiple times the last value specified is used\. - - - __[class](\.\./\.\./\.\./\.\./index\.md\#class)__ *text* - - Text markup\. The argument is marked up as the name of a - *[class](\.\./\.\./\.\./\.\./index\.md\#class)*\. The text may have other markup - already applied to it\. Main use is the highlighting of class names in - free\-form text\. - - - __cmd__ *text* - - Text markup\. The argument text is marked up as the name of a *Tcl - command*\. The text may have other markup already applied to it\. Main uses - are the highlighting of commands in free\-form text, and for the command - parameters of the markup commands __call__ and __usage__\. - - - __cmd\_def__ *command* - - Text structure\. List element\. Command list\. Automatically closes the - previous list element\. The argument specifies the name of the *Tcl - command* to be described by the list element\. Expected to be marked up in - the output as if it had been formatted with __cmd__\. - - - __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *plaintext* - - Text markup\. The argument text is marked up as a comment standing outside of - the actual text of the document\. Main use is in free\-form text\. - - - __const__ *text* - - Text markup\. The argument is marked up as a *constant* value\. The text may - have other markup already applied to it\. Main use is the highlighting of - constants in free\-form text\. - - - __copyright__ *text* - - Document information\. Anywhere\. The command registers the plain text - argument as a copyright assignment for the manpage\. When invoked more than - once the assignments are accumulated\. - - - __def__ *text* - - Text structure\. List element\. Definition list\. Automatically closes the - previous list element\. The argument text is the term defined by the new list - element\. Text markup can be applied to it\. - - - __description__ - - Document structure\. This command separates the header from the document - body\. Implicitly starts a section named "DESCRIPTION" \(See command - __section__\)\. - - - __enum__ - - Text structure\. List element\. Enumerated list\. Automatically closes the - previous list element\. - - - __emph__ *text* - - Text markup\. The argument text is marked up as emphasized\. Main use is for - general highlighting of pieces of free\-form text without attaching special - meaning to the pieces\. - - - __example__ *text* - - Text structure, Text markup\. This command marks its argument up as an - *example*\. Main use is the simple embedding of examples in free\-form text\. - It should be used if the example does *not* need special markup of its - own\. Otherwise use a sequence of __example\_begin__ \.\.\. - __example\_end__\. - - - __example\_begin__ - - Text structure\. This commands starts an example\. All text until the next - __example\_end__ belongs to the example\. Line breaks, spaces, and tabs - have to be preserved literally\. Examples cannot be nested\. - - - __example\_end__ - - Text structure\. This command closes the example started by the last - __example\_begin__\. - - - __[file](\.\./\.\./\.\./\.\./index\.md\#file)__ *text* - - Text markup\. The argument is marked up as a - *[file](\.\./\.\./\.\./\.\./index\.md\#file)* or *directory*, i\.e\. in general - a *path*\. The text may have other markup already applied to it\. Main use - is the highlighting of paths in free\-form text\. - - - __fun__ *text* - - Text markup\. The argument is marked up as the name of a *function*\. The - text may have other markup already applied to it\. Main use is the - highlighting of function names in free\-form text\. - - - __[image](\.\./\.\./\.\./\.\./index\.md\#image)__ *name* ?*label*? - - Text markup\. The argument is the symbolic name of an - *[image](\.\./\.\./\.\./\.\./index\.md\#image)* and replaced with the image - itself, if a suitable variant is found by the backend\. The second argument, - should it be present, will be interpreted the human\-readable description of - the image, and put into the output in a suitable position, if such is - supported by the format\. The HTML format, for example, can place it into the - *alt* attribute of image references\. - - - __include__ *filename* - - Templating\. The contents of the named file are interpreted as text written - in the doctools markup and processed in the place of the include command\. - The markup in the file has to be self\-contained\. It is not possible for a - markup command to cross the file boundaries\. - - - __item__ - - Text structure\. List element\. Itemized list\. Automatically closes the - previous list element\. - - - __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ *args* - - Document information\. Anywhere\. This command registers all its plain text - arguments as keywords applying to this document\. Each argument is a single - keyword\. If this command is used multiple times all the arguments - accumulate\. - - - __lb__ - - Text\. The command is replaced with a left bracket\. Use in free\-form text\. - Required to avoid interpretation of a left bracket as the start of a markup - command\. - - - __list\_begin__ *what* - - Text structure\. This command starts a list\. The exact nature of the list is - determined by the argument *what* of the command\. This further determines - which commands are have to be used to start the list elements\. Lists can be - nested, i\.e\. it is allowed to start a new list within a list element\. - - The allowed types \(and their associated item commands\) are: - - * __arguments__ - - __arg\_def__\. - - * __commands__ - - __cmd\_def__\. - - * __definitions__ - - __def__ and __call__\. - - * __enumerated__ - - __enum__ - - * __itemized__ - - __item__ - - * __options__ - - __opt\_def__ - - * __tkoptions__ - - __tkoption\_def__ - - Additionally the following names are recognized as shortcuts for some of the - regular types: - - * __args__ - - Short for __arguments__\. - - * __cmds__ - - Short for __commands__\. - - * __enum__ - - Short for __enumerated__\. - - * __item__ - - Short for __itemized__\. - - * __opts__ - - Short for __options__\. - - At last the following names are still recognized for backward compatibility, - but are otherwise considered to be *deprecated*\. - - * __arg__ - - *Deprecated*\. See __arguments__\. - - * __bullet__ - - *Deprecated*\. See __itemized__\. - - * __cmd__ - - *Deprecated*\. See __commands__\. - - * __opt__ - - *Deprecated*\. See __options__\. - - * __tkoption__ - - *Deprecated*\. See __tkoptions__\. - - - __list\_end__ - - Text structure\. This command closes the list opened by the last - __list\_begin__ command coming before it\. - - - __lst\_item__ *text* - - *Deprecated*\. Text structure\. List element\. Definition list\. See - __def__ for the canonical command to open a general list item in a - definition list\. - - - __manpage\_begin__ *command* *section* *version* - - Document structure\. The command to start a manpage\. The arguments are the - name of the *command* described by the manpage, the *section* of the - manpages this manpage resides in, and the *version* of the module - containing the command\. All arguments have to be plain text, without markup\. - - - __manpage\_end__ - - Document structure\. Command to end a manpage/document\. Anything in the - document coming after this command is in error\. - - - __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *text* - - Text markup\. The argument text is marked up as the name of an - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* - *[method](\.\./\.\./\.\./\.\./index\.md\#method)*, i\.e\. subcommand of a Tcl - command\. The text may have other markup already applied to it\. Main uses are - the highlighting of method names in free\-form text, and for the command - parameters of the markup commands __call__ and __usage__\. - - - __moddesc__ *text* - - Document information\. Header\. Registers the plain text argument as a short - description of the module the manpage resides in\. - - - __namespace__ *text* - - Text markup\. The argument text is marked up as a namespace name\. The text - may have other markup already applied to it\. Main use is the highlighting of - namespace names in free\-form text\. - - - __nl__ - - *Deprecated*\. Text structure\. See __para__ for the canonical command - to insert paragraph breaks into the text\. - - - __opt__ *text* - - Text markup\. The argument text is marked up as *optional*\. The text may - have other markup already applied to it\. Main use is the highlighting of - optional arguments, see the command arg __arg__\. - - - __opt\_def__ *name* ?*arg*? - - Text structure\. List element\. Option list\. Automatically closes the previous - list element\. Specifies *name* and arguments of the *option* described - by the list element\. It is expected that the name is marked up using - __option__\. - - - __option__ *text* - - Text markup\. The argument is marked up as *option*\. The text may have - other markup already applied to it\. Main use is the highlighting of options, - also known as command\-switches, in either free\-form text, or the arguments - of the __call__ and __usage__ commands\. - - - __[package](\.\./\.\./\.\./\.\./index\.md\#package)__ *text* - - Text markup\. The argument is marked up as the name of a - *[package](\.\./\.\./\.\./\.\./index\.md\#package)*\. The text may have other - markup already applied to it\. Main use is the highlighting of package names - in free\-form text\. - - - __para__ - - Text structure\. This command breaks free\-form text into paragraphs\. Each - command closes the paragraph coming before it and starts a new paragraph for - the text coming after it\. Higher\-level forms of structure are sections and - subsections\. - - - __rb__ - - Text\. The command is replaced with a right bracket\. Use in free\-form text\. - Required to avoid interpretation of a right bracket as the end of a markup - command\. - - - __require__ *package* ?*version*? - - Document information\. Header\. This command registers its argument - *package* as the name of a package or application required by the - described package or application\. A minimum version can be provided as well\. - This argument can be marked up\. The usual markup is __opt__\. - - - __section__ *name* - - Text structure\. This command starts a new named document section\. The - argument has to be plain text\. Implicitly closes the last paragraph coming - before it and also implicitly opens the first paragraph of the new section\. - - - __sectref__ *id* ?*text*? - - Text markup\. Formats a reference to the section identified by *id*\. If no - *text* is specified the title of the referenced section is used in the - output, otherwise *text* is used\. - - - __sectref\-external__ *text* - - Text markup\. Like __sectref__, except that the section is assumed to be - in a different document and therefore doesn't need to be identified, nor are - any checks for existence made\. Only the text to format is needed\. - - - __see\_also__ *args* - - Document information\. Anywhere\. The command defines direct cross\-references - to other documents\. Each argument is a plain text label identifying the - referenced document\. If this command is used multiple times all the - arguments accumulate\. - - - __strong__ *text* - - *Deprecated*\. Text markup\. See __emph__ for the canonical command to - emphasize text\. - - - __subsection__ *name* - - Text structure\. This command starts a new named subsection of a section\. The - argument has to be plain text\. Implicitly closes the last paragraph coming - before it and also implicitly opens the first paragraph of the new - subsection\. - - - __syscmd__ *text* - - Text markup\. The argument text is marked up as the name of an external - command\. The text may have other markup already applied to it\. Main use is - the highlighting of external commands in free\-form text\. - - - __[term](\.\./term/term\.md)__ *text* - - Text markup\. The argument is marked up as unspecific terminology\. The text - may have other markup already applied to it\. Main use is the highlighting of - important terms and concepts in free\-form text\. - - - __titledesc__ *desc* - - Document information\. Header\. Optional\. Registers the plain text argument as - the title of the manpage\. Defaults to the value registered by - __moddesc__\. - - - __tkoption\_def__ *name* *dbname* *dbclass* - - Text structure\. List element\. Widget option list\. Automatically closes the - previous list element\. Specifies the *name* of the option as used in - scripts, the name used by the option database \(*dbname*\), and its class - \(*dbclass*\), i\.e\. its type\. It is expected that the name is marked up - using __option__\. - - - __[type](\.\./\.\./\.\./\.\./index\.md\#type)__ *text* - - Text markup\. The argument is marked up as the name of a *data type*\. The - text may have other markup already applied to it\. Main use is the - highlighting of data types in free\-form text\. - - - __[uri](\.\./uri/uri\.md)__ *text* ?*text*? - - Text markup\. The argument is marked up as an - *[uri](\.\./\.\./\.\./\.\./index\.md\#uri)* \(i\.e\. a *uniform resource - identifier*\. The text may have other markup already applied to it\. Main use - is the highlighting of uris in free\-form text\. The second argument, should - it be present, will be interpreted the human\-readable description of the - uri\. In other words, as its label\. Without an explicit label the uri will be - its own label\. - - - __usage__ *args* - - Text markup\. See __call__ for the full description, this command is - syntactically identical, as it is in its expectations for the markup of its - arguments\. In contrast to __call__ it is however not allowed to generate - output where this command occurs in the text\. The command is *silent*\. The - formatted text may only appear in a different section of the output, for - example a table of contents, or synopsis, depending on the output format\. - - - __var__ *text* - - Text markup\. The argument is marked up as the name of a *variable*\. The - text may have other markup already applied to it\. Main use is the - highlighting of variables in free\-form text\. - - - __vset__ *varname* *value* - - Templating\. In this form the command sets the named document variable to the - specified *value*\. It does not generate output\. I\.e\. the command is - replaced by the empty string\. - - - __vset__ *varname* - - Templating\. In this form the command is replaced by the value of the named - document variable - - - __[widget](\.\./\.\./\.\./\.\./index\.md\#widget)__ *text* - - Text markup\. The argument is marked up as the name of a - *[widget](\.\./\.\./\.\./\.\./index\.md\#widget)*\. The text may have other - markup already applied to it\. Main use is the highlighting of widget names - in free\-form text\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools\_intro](doctools\_intro\.md), -[doctools\_lang\_faq](doctools\_lang\_faq\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md) - -# KEYWORDS - -[doctools commands](\.\./\.\./\.\./\.\./index\.md\#doctools\_commands), [doctools -language](\.\./\.\./\.\./\.\./index\.md\#doctools\_language), [doctools -markup](\.\./\.\./\.\./\.\./index\.md\#doctools\_markup), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007\-2010 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_lang_faq.md Index: embedded/md/tcllib/files/modules/doctools/doctools_lang_faq.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_lang_faq.md +++ embedded/md/tcllib/files/modules/doctools/doctools_lang_faq.md @@ -1,112 +0,0 @@ - -[//000000001]: # (doctools\_lang\_faq \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_lang\_faq\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctools\_lang\_faq\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_lang\_faq \- doctools language faq - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [What is this document?](#subsection1) - - - [EXAMPLES](#section3) - - - [Where do I find doctools examples?](#subsection2) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -# OVERVIEW - -## What is this document? - -This document is currently mainly a placeholder, to be filled with commonly -asked questions about the doctools markup language and companions, and their -answers\. - -Please report any questions \(and, if possible, answers\) we should consider for -this document as explained in the section [Bugs, Ideas, -Feedback](#section4) below\. - -# EXAMPLES - -## Where do I find doctools examples? - -We have no direct examples of documents written using doctools markup\. However -the doctools processor __[dtplite](\.\./\.\./apps/dtplite\.md)__ does -generate a table of contents when processing a set of documents written in -doctools markup\. The intermediate file for it uses doctools markup and is not -deleted when generation completes\. Such files can therefore serve as examples\. - -__[dtplite](\.\./\.\./apps/dtplite\.md)__ is distributed as part of Tcllib, -so to get it you need one of - - 1. A snapshot of Tcllib\. How to retrieve such a snapshot and the tools - required for this are described at [Development - Snapshots](/wiki?name=Development\+Snapshots) - - 1. A Tcllib release archive\. They are available at the [home](/home) page\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md) - -# KEYWORDS - -[doctools commands](\.\./\.\./\.\./\.\./index\.md\#doctools\_commands), [doctools -language](\.\./\.\./\.\./\.\./index\.md\#doctools\_language), [doctools -markup](\.\./\.\./\.\./\.\./index\.md\#doctools\_markup), [doctools -syntax](\.\./\.\./\.\./\.\./index\.md\#doctools\_syntax), -[examples](\.\./\.\./\.\./\.\./index\.md\#examples), -[faq](\.\./\.\./\.\./\.\./index\.md\#faq), [markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[semantic markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md Index: embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md +++ embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md @@ -1,626 +0,0 @@ - -[//000000001]: # (doctools\_lang\_intro \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_lang\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctools\_lang\_intro\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_lang\_intro \- doctools language introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#subsection1) - - - [Basic structure](#subsection2) - - - [Advanced structure](#subsection3) - - - [Text structure](#subsection4) - - - [Text markup](#subsection5) - - - [Escapes](#subsection6) - - - [Cross\-references](#subsection7) - - - [Examples](#subsection8) - - - [Lists](#subsection9) - - - [FURTHER READING](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document is an informal introduction to version 1 of the doctools markup -language based on a multitude of examples\. After reading this a writer should be -ready to understand the two parts of the formal specification, i\.e\. the -*[doctools language syntax](doctools\_lang\_syntax\.md)* specification and -the *[doctools language command reference](doctools\_lang\_cmdref\.md)*\. - -## Fundamentals - -In the broadest terms possible the *doctools markup language* is LaTeX\-like, -instead of like SGML and similar languages\. A document written in this language -consists primarily of text, with markup commands embedded into it\. - -Each markup command is a Tcl command surrounded by a matching pair of __\[__ -and __\]__\. Inside of these delimiters the usual rules for a Tcl command -apply with regard to word quotation, nested commands, continuation lines, etc\. -I\.e\. - - ... [list_begin enumerated] ... - - ... [call [cmd foo] \ - [arg bar]] ... - - ... [term {complex concept}] ... - - ... [opt "[arg key] [arg value]"] ... - -## Basic structure - -The most simple document which can be written in doctools is - - [manpage_begin NAME SECTION VERSION] - [see_also doctools_intro] - [see_also doctools_lang_cmdref] - [see_also doctools_lang_faq] - [see_also doctools_lang_syntax] - [keywords {doctools commands}] - [keywords {doctools language}] - [keywords {doctools markup}] - [keywords {doctools syntax}] - [keywords markup] - [keywords {semantic markup}] - [description] - [vset CATEGORY doctools] - [include ../common-text/feedback.inc] - [manpage_end] - -This also shows us that all doctools documents are split into two parts, the -*header* and the *body*\. Everything coming before \[__description__\] -belongs to the header, and everything coming after belongs to the body, with the -whole document bracketed by the two __manpage\_\*__ commands\. Before and after -these opening and closing commands we have only *whitespace*\. - -In the remainder of this section we will discuss only the contents of the -header, the structure of the body will be discussed in the section [Text -structure](#subsection4)\. - -The header section can be empty, and otherwise may contain only an arbitrary -sequence of the four so\-called *header* commands, plus *whitespace*\. These -commands are - - - __titledesc__ - - - __moddesc__ - - - __require__ - - - __copyright__ - -They provide, through their arguments, additional information about the -document, like its title, the title of the larger group the document belongs to -\(if applicable\), the requirements of the documented packages \(if applicable\), -and copyright assignments\. All of them can occur multiple times, including none, -and they can be used in any order\. However for __titledesc__ and -__moddesc__ only the last occurrence is taken\. For the other two the -specified information is accumulated, in the given order\. Regular text is not -allowed within the header\. - -Given the above a less minimal example of a document is - -> \[manpage\_begin NAME SECTION VERSION\] -> \[__copyright \{YEAR AUTHOR\}__\] -> \[__titledesc TITLE__\] -> \[__moddesc MODULE\_TITLE__\] -> \[__require PACKAGE VERSION__\] -> \[__require PACKAGE__\] -> \[description\] -> \[manpage\_end\] - -Remember that the whitespace is optional\. The document - - [manpage_begin NAME SECTION VERSION] - [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] - [require PACKAGE VERSION][require PACKAGE][description] - [vset CATEGORY doctools] - [include ../common-text/feedback.inc] - [manpage_end] - -has the same meaning as the example before\. - -On the other hand, if *whitespace* is present it consists not only of any -sequence of characters containing the space character, horizontal and vertical -tabs, carriage return, and newline, but it may contain comment markup as well, -in the form of the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ command\. - -> \[__comment \{ \.\.\. \}__\] -> \[manpage\_begin NAME SECTION VERSION\] -> \[copyright \{YEAR AUTHOR\}\] -> \[titledesc TITLE\] -> \[moddesc MODULE\_TITLE\]\[__comment \{ \.\.\. \}__\] -> \[require PACKAGE VERSION\] -> \[require PACKAGE\] -> \[description\] -> \[manpage\_end\] -> \[__comment \{ \.\.\. \}__\] - -## Advanced structure - -In the simple examples of the last section we fudged a bit regarding the markup -actually allowed to be used before the __manpage\_begin__ command opening the -document\. - -Instead of only whitespace the two templating commands __include__ and -__vset__ are also allowed, to enable the writer to either set and/or import -configuration settings relevant to the document\. I\.e\. it is possible to write - -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \[manpage\_begin NAME SECTION VERSION\] -> \[description\] -> \[manpage\_end\] - -Even more important, these two commands are allowed anywhere where a markup -command is allowed, without regard for any other structure\. I\.e\. for example in -the header as well\. - -> \[manpage\_begin NAME SECTION VERSION\] -> \[__include FILE__\] -> \[__vset VAR VALUE__\] -> \[description\] -> \[manpage\_end\] - -The only restriction __include__ has to obey is that the contents of the -included file must be valid at the place of the inclusion\. I\.e\. a file included -before __manpage\_begin__ may contain only the templating commands -__vset__ and __include__, a file included in the header may contain only -header commands, etc\. - -## Text structure - -The body of the document consists mainly of text, possibly split into sections, -subsections, and paragraphs, with parts marked up to highlight various semantic -categories of text, and additional structure through the use of examples and -\(nested\) lists\. - -This section explains the high\-level structural commands, with everything else -deferred to the following sections\. - -The simplest way of structuring the body is through the introduction of -paragraphs\. The command for doing so is __para__\. Each occurrence of this -command closes the previous paragraph and automatically opens the next\. The -first paragraph is automatically opened at the beginning of the body, by -__description__\. In the same manner the last paragraph automatically ends at -__manpage\_end__\. - -> \[manpage\_begin NAME SECTION VERSION\] -> \[description\] ->  \.\.\. -> \[__para__\] ->  \.\.\. -> \[__para__\] ->  \.\.\. -> \[manpage\_end\] - -Empty paragraphs are ignored\. - -A structure coarser than paragraphs are sections, which allow the writer to -split a document into larger, and labeled, pieces\. The command for doing so is -__section__\. Each occurrence of this command closes the previous section and -automatically opens the next, including its first paragraph\. The first section -is automatically opened at the beginning of the body, by __description__ -\(This section is labeled "DESCRIPTION"\)\. In the same manner the last section -automatically ends at __manpage\_end__\. - -Empty sections are *not* ignored\. We are free to \(not\) use paragraphs within -sections\. - -> \[manpage\_begin NAME SECTION VERSION\] -> \[description\] ->  \.\.\. -> \[__section \{Section A\}__\] ->  \.\.\. -> \[para\] ->  \.\.\. -> \[__section \{Section B\}__\] ->  \.\.\. -> \[manpage\_end\] - -Between sections and paragraphs we have subsections, to split sections\. The -command for doing so is __subsection__\. Each occurrence of this command -closes the previous subsection and automatically opens the next, including its -first paragraph\. A subsection is automatically opened at the beginning of the -body, by __description__, and at the beginning of each section\. In the same -manner the last subsection automatically ends at __manpage\_end__\. - -Empty subsections are *not* ignored\. We are free to \(not\) use paragraphs -within subsections\. - -> \[manpage\_begin NAME SECTION VERSION\] -> \[description\] ->  \.\.\. -> \[section \{Section A\}\] ->  \.\.\. -> \[__subsection \{Sub 1\}__\] ->  \.\.\. -> \[para\] ->  \.\.\. -> \[__subsection \{Sub 2\}__\] ->  \.\.\. -> \[section \{Section B\}\] ->  \.\.\. -> \[manpage\_end\] - -## Text markup - -Having handled the overall structure a writer can impose on the document we now -take a closer at the text in a paragraph\. - -While most often this is just the unadorned content of the document we do have -situations where we wish to highlight parts of it as some type of thing or -other, like command arguments, command names, concepts, uris, etc\. - -For this we have a series of markup commands which take the text to highlight as -their single argument\. It should be noted that while their predominant use is -the highlighting of parts of a paragraph they can also be used to mark up the -arguments of list item commands, and of other markup commands\. - -The commands available to us are - - - __arg__ - - Its argument is a the name of a command argument\. - - - __[class](\.\./\.\./\.\./\.\./index\.md\#class)__ - - Its argument is a class name\. - - - __cmd__ - - Its argument is a command name \(Tcl command\)\. - - - __const__ - - Its argument is a constant\. - - - __emph__ - - General, non\-semantic emphasis\. - - - __[file](\.\./\.\./\.\./\.\./index\.md\#file)__ - - Its argument is a filename / path\. - - - __fun__ - - Its argument is a function name\. - - - __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ - - Its argument is a method name - - - __namespace__ - - Its argument is namespace name\. - - - __opt__ - - Its argument is some optional syntax element\. - - - __option__ - - Its argument is a command line switch / widget option\. - - - __[package](\.\./\.\./\.\./\.\./index\.md\#package)__ - - Its argument is a package name\. - - - __sectref__ - - Its argument is the title of a section or subsection, i\.e\. a section - reference\. - - - __syscmd__ - - Its argument is a command name \(external, system command\)\. - - - __[term](\.\./term/term\.md)__ - - Its argument is a concept, or general terminology\. - - - __[type](\.\./\.\./\.\./\.\./index\.md\#type)__ - - Its argument is a type name\. - - - __[uri](\.\./uri/uri\.md)__ - - Its argument is a uniform resource identifier, i\.e an external reference\. A - second argument can be used to specify an explicit label for the reference - in question\. - - - __usage__ - - The arguments describe the syntax of a Tcl command\. - - - __var__ - - Its argument is a variable\. - - - __[widget](\.\./\.\./\.\./\.\./index\.md\#widget)__ - - Its argument is a widget name\. - -The example demonstrating the use of text markup is an excerpt from the -*[doctools language command reference](doctools\_lang\_cmdref\.md)*, with -some highlighting added\. It shows their use within a block of text, as the -arguments of a list item command \(__call__\), and our ability to nest them\. - ->   \.\.\. ->   \[call \[__cmd arg\_def__\] \[__arg type__\] \[__arg name__\] \[__opt__ \[__arg mode__\]\]\] -> ->   Text structure\. List element\. Argument list\. Automatically closes the ->   previous list element\. Specifies the data\-\[__arg type__\] of the described ->   argument of a command, its \[__arg name__\] and its i/o\-\[__arg mode__\]\. The ->   latter is optional\. ->   \.\.\. - -## Escapes - -Beyond the 20 commands for simple markup shown in the previous section we have -two more available which are technically simple markup\. However their function -is not the marking up of phrases as specific types of things, but the insertion -of characters, namely __\[__ and __\]__\. These commands, __lb__ and -__rb__ respectively, are required because our use of \[ and \] to bracket -markup commands makes it impossible to directly use \[ and \] within the text\. - -Our example of their use are the sources of the last sentence in the previous -paragraph, with some highlighting added\. - ->   \.\.\. ->   These commands, \[cmd lb\] and \[cmd lb\] respectively, are required ->   because our use of \[__lb__\] and \[__rb__\] to bracket markup commands makes it ->   impossible to directly use \[__lb__\] and \[__rb__\] within the text\. ->   \.\.\. - -## Cross\-references - -The last two commands we have to discuss are for the declaration of -cross\-references between documents, explicit and implicit\. They are -__[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ and __see\_also__\. Both -take an arbitrary number of arguments, all of which have to be plain unmarked -text\. I\.e\. it is not allowed to use markup on them\. Both commands can be used -multiple times in a document\. If that is done all arguments of all occurrences -of one of them are put together into a single set\. - - - __[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)__ - - The arguments of this command are interpreted as keywords describing the - document\. A processor can use this information to create an index indirectly - linking the containing document to all documents with the same keywords\. - - - __see\_also__ - - The arguments of this command are interpreted as references to other - documents\. A processor can format them as direct links to these documents\. - -All the cross\-reference commands can occur anywhere in the document between -__manpage\_begin__ and __manpage\_end__\. As such the writer can choose -whether she wants to have them at the beginning of the body, or at its end, -maybe near the place a keyword is actually defined by the main content, or -considers them as meta data which should be in the header, etc\. - -Our example shows the sources for the cross\-references of this document, with -some highlighting added\. Incidentally they are found at the end of the body\. - ->   \.\.\. ->   \[__see\_also doctools\_intro__\] ->   \[__see\_also doctools\_lang\_syntax__\] ->   \[__see\_also doctools\_lang\_cmdref__\] ->   \[__keywords markup \{semantic markup\}__\] ->   \[__keywords \{doctools markup\} \{doctools language\}__\] ->   \[__keywords \{doctools syntax\} \{doctools commands\}__\] ->   \[manpage\_end\] - -## Examples - -Where ever we can write plain text we can write examples too\. For simple -examples we have the command __example__ which takes a single argument, the -text of the argument\. The example text must not contain markup\. If we wish to -have markup within an example we have to use the 2\-command combination -__example\_begin__ / __example\_end__ instead\. - -The first opens an example block, the other closes it, and in between we can -write plain text and use all the regular text markup commands\. Note that text -structure commands are not allowed\. This also means that it is not possible to -embed examples and lists within an example\. On the other hand, we *can* use -templating commands within example blocks to read their contents from a file -\(Remember section [Advanced structure](#subsection3)\)\. - -The source for the very first example in this document \(see section -[Fundamentals](#subsection1)\), with some highlighting added, is - -> \[__example__ \{ ->     \.\.\. \[list\_begin enumerated\] \.\.\. ->   \}\] - -Using __example\_begin__ / __example\_end__ this would look like - -> \[__example\_begin__\] ->     \.\.\. \[list\_begin enumerated\] \.\.\. ->   \[__example\_end__\] - -## Lists - -Where ever we can write plain text we can write lists too\. The main commands are -__list\_begin__ to start a list, and __list\_end__ to close one\. The -opening command takes an argument specifying the type of list started it, and -this in turn determines which of the eight existing list item commands are -allowed within the list to start list items\. - -After the opening command only whitespace is allowed, until the first list item -command opens the first item of the list\. Each item is a regular series of -paragraphs and is closed by either the next list item command, or the end of the -list\. If closed by a list item command this command automatically opens the next -list item\. A consequence of a list item being a series of paragraphs is that all -regular text markup can be used within a list item, including examples and other -lists\. - -The list types recognized by __list\_begin__ and their associated list item -commands are: - - - __arguments__ - - \(__arg\_def__\) This opens an *argument \(declaration\) list*\. It is a - specialized form of a term definition list where the term is an argument - name, with its type and i/o\-mode\. - - - __commands__ - - \(__cmd\_def__\) This opens a *command \(declaration\) list*\. It is a - specialized form of a term definition list where the term is a command name\. - - - __definitions__ - - \(__def__ and __call__\) This opens a general *term definition - list*\. The terms defined by the list items are specified through the - argument\(s\) of the list item commands, either general terms, possibly with - markup \(__def__\), or Tcl commands with their syntax \(__call__\)\. - - - __enumerated__ - - \(__enum__\) This opens a general *enumerated list*\. - - - __itemized__ - - \(__item__\) This opens a general *itemized list*\. - - - __options__ - - \(__opt\_def__\) This opens an *option \(declaration\) list*\. It is a - specialized form of a term definition list where the term is an option name, - possibly with the option's arguments\. - - - __tkoptions__ - - \(__tkoption\_def__\) This opens a *widget option \(declaration\) list*\. It - is a specialized form of a term definition list where the term is the name - of a configuration option for a widget, with its name and class in the - option database\. - -Our example is the source of the definition list in the previous paragraph, with -most of the content in the middle removed\. - ->   \.\.\. ->   \[__list\_begin__ definitions\] ->   \[__def__ \[const arg\]\] -> ->   \(\[cmd arg\_def\]\) This opens an argument \(declaration\) list\. It is a ->   specialized form of a definition list where the term is an argument ->   name, with its type and i/o\-mode\. -> ->   \[__def__ \[const itemized\]\] -> ->   \(\[cmd item\]\) ->   This opens a general itemized list\. -> ->   \.\.\. ->   \[__def__ \[const tkoption\]\] -> ->   \(\[cmd tkoption\_def\]\) This opens a widget option \(declaration\) list\. It ->   is a specialized form of a definition list where the term is the name ->   of a configuration option for a widget, with its name and class in the ->   option database\. -> ->   \[__list\_end__\] ->   \.\.\. - -Note that a list cannot begin in one \(sub\)section and end in another\. -Differently said, \(sub\)section breaks are not allowed within lists and list -items\. An example of this *illegal* construct is - ->   \.\.\. ->   \[list\_begin itemized\] ->   \[item\] ->   \.\.\. ->   \[__section \{ILLEGAL WITHIN THE LIST\}__\] ->   \.\.\. ->   \[list\_end\] ->   \.\.\. - -# FURTHER READING - -Now that this document has been digested the reader, assumed to be a *writer* -of documentation should be fortified enough to be able to understand the formal -*[doctools language syntax](doctools\_lang\_syntax\.md)* specification as -well\. From here on out the *[doctools language command -reference](doctools\_lang\_cmdref\.md)* will also serve as the detailed -specification and cheat sheet for all available commands and their syntax\. - -To be able to validate a document while writing it, it is also recommended to -familiarize oneself with one of the applications for the processing and -conversion of doctools documents, i\.e\. either Tcllib's easy and simple -__[dtplite](\.\./\.\./apps/dtplite\.md)__, or Tclapps' ultra\-configurable -__dtp__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools\_intro](doctools\_intro\.md), -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](doctools\_lang\_faq\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md) - -# KEYWORDS - -[doctools commands](\.\./\.\./\.\./\.\./index\.md\#doctools\_commands), [doctools -language](\.\./\.\./\.\./\.\./index\.md\#doctools\_language), [doctools -markup](\.\./\.\./\.\./\.\./index\.md\#doctools\_markup), [doctools -syntax](\.\./\.\./\.\./\.\./index\.md\#doctools\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md Index: embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md +++ embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md @@ -1,180 +0,0 @@ - -[//000000001]: # (doctools\_lang\_syntax \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_lang\_syntax\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (doctools\_lang\_syntax\(n\) 1\.0 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_lang\_syntax \- doctools language syntax - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Fundamentals](#section2) - - - [Lexical definitions](#section3) - - - [Syntax](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document contains the formal specification of the syntax of the doctools -markup language, version 1 in Backus\-Naur\-Form\. This document is intended to be -a reference, complementing the *[doctools language command -reference](doctools\_lang\_cmdref\.md)*\. A beginner should read the much more -informally written *[doctools language -introduction](doctools\_lang\_intro\.md)* first before trying to understand -either this document or the command reference\. - -# Fundamentals - -In the broadest terms possible the *doctools markup language* is LaTeX\-like, -instead of like SGML and similar languages\. A document written in this language -consists primarily of text, with markup commands embedded into it\. - -Each markup command is a just Tcl command surrounded by a matching pair of -__\[__ and __\]__\. Which commands are available, and their arguments, i\.e\. -syntax is specified in the *[doctools language command -reference](doctools\_lang\_cmdref\.md)*\. - -In this document we specify first the lexeme, and then the syntax, i\.e\. how we -can mix text and markup commands with each other\. - -# Lexical definitions - -In the syntax rules listed in the next section - - 1. stands for all text except markup commands\. - - 1. Any XXX stands for the markup command \[xxx\] including its arguments\. Each - markup command is a Tcl command surrounded by a matching pair of __\[__ - and __\]__\. Inside of these delimiters the usual rules for a Tcl command - apply with regard to word quotation, nested commands, continuation lines, - etc\. - - 1. stands for all text consisting only of spaces, newlines, tabulators - and the __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ markup command\. - -# Syntax - -The rules listed here specify only the syntax of doctools documents\. The lexical -level of the language was covered in the previous section\. - -Regarding the syntax of the \(E\)BNF itself - - 1. The construct \{ X \} stands for zero or more occurrences of X\. - - 1. The construct \[ X \] stands for zero or one occurrence of X\. - - 1. The construct LIST\_BEGIN stands for the markup command - __list\_begin__ with __X__ as its type argument\. - -The syntax: - - manpage = defs - MANPAGE_BEGIN - header - DESCRIPTION - body - MANPAGE_END - { } - - defs = { INCLUDE | VSET | } - - header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref } - - xref = KEYWORDS | SEE_ALSO | CATEGORY - - body = paras { SECTION sbody } - sbody = paras { SUBSECTION ssbody } - ssbody = paras - - paras = tblock { (PARA | NL) tblock } - - tblock = { | defs | markup | xref | an_example | a_list } - - markup = ARG | CLASS | CMD | CONST | EMPH | FILE - | FUN | LB | METHOD | NAMESPACE | OPT | OPTION - | PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM - | TYPE | URI | USAGE | VAR | WIDGET - - example = EXAMPLE - | EXAMPLE_BEGIN extext EXAMPLE_END - - extext = { | defs | markup } - - a_list = LIST_BEGIN argd_list LIST_END - | LIST_BEGIN cmdd_list LIST_END - | LIST_BEGIN def_list LIST_END - | LIST_BEGIN enum_list LIST_END - | LIST_BEGIN item_list LIST_END - | LIST_BEGIN optd_list LIST_END - | LIST_BEGIN tkoptd_list LIST_END - - argd_list = [ ] { ARG_DEF paras } - cmdd_list = [ ] { CMD_DEF paras } - def_list = [ ] { (DEF|CALL) paras } - enum_list = [ ] { ENUM paras } - item_list = [ ] { ITEM paras } - optd_list = [ ] { OPT_DEF paras } - tkoptd_list = [ ] { TKOPTION_DEF paras } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools\_intro](doctools\_intro\.md), -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](doctools\_lang\_faq\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md) - -# KEYWORDS - -[doctools commands](\.\./\.\./\.\./\.\./index\.md\#doctools\_commands), [doctools -language](\.\./\.\./\.\./\.\./index\.md\#doctools\_language), [doctools -markup](\.\./\.\./\.\./\.\./index\.md\#doctools\_markup), [doctools -syntax](\.\./\.\./\.\./\.\./index\.md\#doctools\_syntax), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/doctools_plugin_apiref.md Index: embedded/md/tcllib/files/modules/doctools/doctools_plugin_apiref.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/doctools_plugin_apiref.md +++ embedded/md/tcllib/files/modules/doctools/doctools_plugin_apiref.md @@ -1,484 +0,0 @@ - -[//000000001]: # (doctools\_plugin\_apiref \- Documentation tools) -[//000000002]: # (Generated from file 'doctools\_plugin\_apiref\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2010 Andreas Kupries ) -[//000000004]: # (doctools\_plugin\_apiref\(n\) 1\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools\_plugin\_apiref \- doctools plugin API reference - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [FRONTEND COMMANDS](#section3) - - - [PLUGIN COMMANDS](#section4) - - - [Management commands](#subsection1) - - - [Formatting commands](#subsection2) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__dt\_copyright__](#1) -[__dt\_file__](#2) -[__dt\_mainfile__](#3) -[__dt\_fileid__](#4) -[__dt\_fmap__ *symfname*](#5) -[__dt\_format__](#6) -[__dt\_imgdata__ *key* *extensions*](#7) -[__dt\_imgdst__ *key* *extensions*](#8) -[__dt\_imgsrc__ *key* *extensions*](#9) -[__dt\_lnesting__](#10) -[__dt\_module__](#11) -[__dt\_read__ *file*](#12) -[__dt\_source__ *file*](#13) -[__dt\_user__](#14) -[__ex\_cappend__ *text*](#15) -[__ex\_cget__ *varname*](#16) -[__ex\_cis__ *cname*](#17) -[__ex\_cname__](#18) -[__ex\_cpop__ *cname*](#19) -[__ex\_cpush__ *cname*](#20) -[__ex\_cset__ *varname* *value*](#21) -[__ex\_lb__ ?*newbracket*?](#22) -[__ex\_rb__ ?*newbracket*?](#23) -[__fmt\_initialize__](#24) -[__fmt\_listvariables__](#25) -[__fmt\_numpasses__](#26) -[__fmt\_postprocess__ *text*](#27) -[__fmt\_setup__ *n*](#28) -[__fmt\_shutdown__](#29) -[__fmt\_varset__ *varname* *text*](#30) -[__fmt\_plain\_text__ *text*](#31) - -# DESCRIPTION - -This document is intended for *plugin writers*, i\.e\. developers wishing to -write a doctools *[formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine)* for some output format X\. - -It specifies the interaction between the __[doctools](doctools\.md)__ -package and its plugins, i\.e\. the interface any doctools formatting engine has -to comply with\. - -This document deals with version 1 of the interface\. - -A reader who is on the other hand more interested in the markup language itself -should start with the *[doctools language -introduction](doctools\_lang\_intro\.md)* and proceed from there to the formal -specifications, i\.e\. the *[doctools language -syntax](doctools\_lang\_syntax\.md)* and the *[doctools language command -reference](doctools\_lang\_cmdref\.md)*\. - -# OVERVIEW - -The API for a doctools formatting engine consists of two major sections\. - -On the one side we have a set of commands through which the plugin is able to -query the frontend\. These commands are provided by the frontend and linked into -the plugin interpreter\. Please see section [FRONTEND COMMANDS](#section3) -for their detailed specification\. - -And on the other side the plugin has to provide its own set of commands which -will then be called by the frontend in a specific sequence while processing -input\. They, again, fall into two categories, management and formatting\. Please -see section [PLUGIN COMMANDS](#section4) and its subsections for their -detailed specification\. - -# FRONTEND COMMANDS - -This section specifies the set of commands through which a plugin, also known as -a doctools formatting engine, is able to query the frontend\. These commands are -provided by the frontend and linked into the plugin interpreter\. - -I\.e\. a doctools formatting engine can assume that all of the following commands -are present when any of its own commands \(as specified in section [PLUGIN -COMMANDS](#section4)\) are executed\. - -Beyond that it can also assume that it has full access to its own safe -interpreter and thus is not able to damage the other parts of the processor, nor -can it damage the filesystem\. It is however able to either kill or hang the -whole process, by exiting, or running an infinite loop\. - -Coming back to the imported commands, all the commands with prefix *dt\_* -provide limited access to specific parts of the frontend, whereas the commands -with prefix *ex\_* provide access to the state of the -__[textutil::expander](\.\./textutil/expander\.md)__ object which does the -main parsing of the input within the frontend\. These commands should not be -except under very special circumstances\. - - - __dt\_copyright__ - - Query command\. It returns a string containing the copyright information the - doctools processor was configured with\. The relevant option is - __\-copyright__\)\. - - - __dt\_file__ - - Query command\. It returns the full path of the file containing the input - currently processed by the engine\. This may be an included file\. - - - __dt\_mainfile__ - - Query command\. It returns the full path of the toplevel file containing the - input currently processed by the engine\. - - - __dt\_fileid__ - - Query command\. It returns the name of the file containing the input - currently processed by the engine, without path, nor extension\. - - - __dt\_fmap__ *symfname* - - Query command\. It returns the actual pathname to use in the output in place - of the symbolic filename *symfname*\. It will return the unchanged input if - no mapping was established for *symfname*\. - - The required mappings are established with the method __map__ of a - frontend, as explained in section __OBJECT METHODS__ of the - documentation for the package __[doctools](doctools\.md)__\. - - - __dt\_format__ - - Query command\. It returns the name of the format associated with the - doctools formatting engine\. - - - __dt\_imgdata__ *key* *extensions* - - Query command\. Access to the image map\. Looks for an image recorded under - the *key* and having on the specified *extension*\. If a matching image - is found its data is returned as the result of the command\. Otherwise an - empty string is returned\. - - - __dt\_imgdst__ *key* *extensions* - - Query command\. Access to the image map\. Looks for an image recorded under - the *key* and having on the specified *extension*\. If a matching image - is found its destination path in the output is returned as the result of the - command\. Otherwise an empty string is returned\. - - - __dt\_imgsrc__ *key* *extensions* - - Query command\. Access to the image map\. Looks for an image recorded under - the *key* and having on the specified *extension*\. If a matching image - is found its origin path is returned as the result of the command\. Otherwise - an empty string is returned\. - - - __dt\_lnesting__ - - Query command\. It returns the number of lists currently open\. - - - __dt\_module__ - - Query command\. It returns the name of the module the input currently - processed belongs to\. - - - __dt\_read__ *file* - - Controlled filesystem access\. Returns contents of *file* for whatever use - desired by the plugin\. Only files which are either in the same directory as - the file containing the engine, or below it, can be loaded\. Trying to load a - file outside of this directory causes an error\. - - - __dt\_source__ *file* - - Controlled filesystem access\. This command allows the doctools formatting - engine to load additional Tcl code it may need\. Only files which are either - in the same directory as the file containing the engine, or below it, can be - loaded\. Trying to load a file outside of this directory causes an error\. - - - __dt\_user__ - - Query command\. It returns the name of the current user as known to the tcl - interpreter the frontend controlling the formatting engine resides in\. - - - __ex\_cappend__ *text* - - Appends a string to the output in the current context\. This command should - rarely be used by macros or application code\. - - - __ex\_cget__ *varname* - - Retrieves the value of variable *varname*, defined in the current context\. - - - __ex\_cis__ *cname* - - Determines whether or not the name of the current context is *cname*\. - - - __ex\_cname__ - - Returns the name of the current context\. - - - __ex\_cpop__ *cname* - - Pops a context from the context stack, returning all accumulated output in - that context\. The context must be named *cname*, or an error results\. - - - __ex\_cpush__ *cname* - - Pushes a context named *cname* onto the context stack\. The context must be - popped by __cpop__ before expansion ends or an error results\. - - - __ex\_cset__ *varname* *value* - - Sets variable *varname* to *value* in the current context\. - - - __ex\_lb__ ?*newbracket*? - - Returns the current value of the left macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - - - __ex\_rb__ ?*newbracket*? - - Returns the current value of the right macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - -# PLUGIN COMMANDS - -The plugin has to provide its own set of commands which will then be called by -the frontend in a specific sequence while processing input\. They fall into two -categories, management and formatting\. Their expected names, signatures, and -responsibilities are specified in the following two subsections\. - -## Management commands - -The management commands a plugin has to provide are used by the frontend to - - 1. initialize and shutdown the plugin - - 1. determine the number of passes it has to make over the input - - 1. initialize and shutdown each pass - - 1. query and initialize engine parameters - -After the plugin has been loaded and the frontend commands are established the -commands will be called in the following sequence: - - fmt_numpasses -> n - fmt_listvariables -> vars - - fmt_varset var1 value1 - fmt_varset var2 value2 - ... - fmt_varset varK valueK - fmt_initialize - fmt_setup 1 - ... - fmt_setup 2 - ... - ... - fmt_setup n - ... - fmt_postprocess - fmt_shutdown - ... - -I\.e\. first the number of passes and the set of available engine parameters is -established, followed by calls setting the parameters\. That second part is -optional\. - -After that the plugin is initialized, the specified number of passes executed, -the final result run through a global post processing step and at last the -plugin is shutdown again\. This can be followed by more conversions, restarting -the sequence at __fmt\_varset__\. - -In each of the passes, i\.e\. after the calls of __fmt\_setup__ the frontend -will process the input and call the formatting commands as markup is -encountered\. This means that the sequence of formatting commands is determined -by the grammar of the doctools markup language, as specified in the *[doctools -language syntax](doctools\_lang\_syntax\.md)* specification\. - -A different way of looking at the sequence is: - - - First some basic parameters are determined\. - - - Then everything starting at the first __fmt\_varset__ to - __fmt\_shutdown__ forms a *run*, the formatting of a single input\. Each - run can be followed by more\. - - - Embedded within each run we have one or more *passes*, each starting with - __fmt\_setup__ and going until either the next __fmt\_setup__ or - __fmt\_postprocess__ is reached\. - - If more than one pass is required to perform the formatting only the output - of the last pass is relevant\. The output of all the previous, preparatory - passes is ignored\. - -The commands, their names, signatures, and responsibilities are, in detail: - - - __fmt\_initialize__ - - *Initialization/Shutdown*\. This command is called at the beginning of - every conversion run, as the first command of that run\. Note that a run is - not a pass, but may consist of multiple passes\. It has to initialize the - general state of the plugin, beyond the initialization done during the load\. - No return value is expected, and any returned value is ignored\. - - - __fmt\_listvariables__ - - *Initialization/Shutdown* and *Engine parameters*\. Second command is - called after the plugin code has been loaded, i\.e\. immediately after - __fmt\_numpasses__\. It has to return a list containing the names of the - parameters the frontend can set to configure the engine\. This list can be - empty\. - - - __fmt\_numpasses__ - - *Initialization/Shutdown* and *Pass management*\. First command called - after the plugin code has been loaded\. No other command of the engine will - be called before it\. It has to return the number of passes this engine - requires to fully process the input document\. This value has to be an - integer number greater or equal to one\. - - - __fmt\_postprocess__ *text* - - *Initialization/Shutdown*\. This command is called immediately after the - last pass in a run\. Its argument is the result of the conversion generated - by that pass\. It is provided to allow the engine to perform any global - modifications of the generated document\. If no post\-processing is required - for a specific format the command has to just return the argument\. - - Expected to return a value, the final result of formatting the input\. - - - __fmt\_setup__ *n* - - *Initialization/Shutdown* and *Pass management*\. This command is called - at the beginning of each pass over the input in a run\. Its argument is the - number of the pass which has begun\. Passes are counted from __1__ - upward\. The command has to set up the internal state of the plugin for this - particular pass\. No return value is expected, and any returned value is - ignored\. - - - __fmt\_shutdown__ - - *Initialization/Shutdown*\. This command is called at the end of every - conversion run\. It is the last command called in a run\. It has to clean up - of all the run\-specific state in the plugin\. After the call the engine has - to be in a state which allows the initiation of another run without fear - that information from the last run is leaked into this new run\. No return - value is expected, and any returned value is ignored\. - - - __fmt\_varset__ *varname* *text* - - *Engine parameters*\. This command is called by the frontend to set an - engine parameter to a particular value\. The parameter to change is specified - by *varname*, the value to set in *text*\. - - The command has to throw an error if an unknown *varname* is used\. Only - the names returned by __fmt\_listvariables__ have to be considered as - known\. - - The values of all engine parameters have to persist between passes and runs\. - -## Formatting commands - -The formatting commands have to implement the formatting for the output format, -for all the markup commands of the doctools markup language, except __lb__, -__rb__, __vset__, __include__, and -__[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__\. These exceptions are -processed by the frontend and are never seen by the plugin\. In return a command -for the formatting of plain text has to be provided, something which has no -markup in the input at all\. - -This means, that each of the 49 markup commands specified in the *[doctools -language command reference](doctools\_lang\_cmdref\.md)* and outside of the set -of exceptions listed above has an equivalent formatting command which takes the -same arguments as the markup command and whose name is the name of markup -command with the prefix *fmt\_* added to it\. - -All commands are expected to format their input in some way per the semantics -specified in the command reference and to return whatever part of this that they -deem necessary as their result, which will be added to the output\. - -To avoid essentially duplicating the command reference we do not list any of the -command here and simply refer the reader to the *[doctools language command -reference](doctools\_lang\_cmdref\.md)* for their signature and description\. -The sole exception is the plain text formatter, which has no equivalent markup -command\. - -The calling sequence of formatting commands is not as rigid as for the -management commands, but determined by the grammar of the doctools markup -language, as specified in the *[doctools language -syntax](doctools\_lang\_syntax\.md)* specification\. - - - __fmt\_plain\_text__ *text* - - *No associated markup command*\. - - Called by the frontend for any plain text encountered in the input\. It has - to perform any and all special processing required for plain text\. - - The formatted text is expected as the result of the command, and added to - the output\. If no special processing is required it has to simply return its - argument without change\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[doctools](doctools\.md), [doctools\_intro](doctools\_intro\.md), -[doctools\_lang\_cmdref](doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](doctools\_lang\_faq\.md), -[doctools\_lang\_intro](doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](doctools\_lang\_syntax\.md) - -# KEYWORDS - -[document](\.\./\.\./\.\./\.\./index\.md\#document), -[formatter](\.\./\.\./\.\./\.\./index\.md\#formatter), [formatting -engine](\.\./\.\./\.\./\.\./index\.md\#formatting\_engine), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2007\-2010 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools/mpexpand.md Index: embedded/md/tcllib/files/modules/doctools/mpexpand.md ================================================================== --- embedded/md/tcllib/files/modules/doctools/mpexpand.md +++ embedded/md/tcllib/files/modules/doctools/mpexpand.md @@ -1,142 +0,0 @@ - -[//000000001]: # (mpexpand \- Documentation toolbox) -[//000000002]: # (Generated from file 'mpexpand\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (Copyright © 2003 Andreas Kupries ) -[//000000005]: # (mpexpand\(n\) 1\.0 tcllib "Documentation toolbox") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -mpexpand \- Markup processor - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [NOTES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__mpexpand__ ?\-module *module*? *format* *infile*|\- *outfile*|\-](#1) -[__mpexpand\.all__ ?*\-verbose*? ?*module*?](#2) - -# DESCRIPTION - -This manpage describes a processor / converter for manpages in the doctools -format as specified in __doctools\_fmt__\. The processor is based upon the -package __[doctools](doctools\.md)__\. - - - __mpexpand__ ?\-module *module*? *format* *infile*|\- *outfile*|\- - - The processor takes three arguments, namely the code describing which - formatting to generate as the output, the file to read the markup from, and - the file to write the generated output into\. If the *infile* is - "__\-__" the processor will read from __stdin__\. If *outfile* is - "__\-__" the processor will write to __stdout__\. - - If the option *\-module* is present its value overrides the internal - definition of the module name\. - - The currently known output formats are - - * __nroff__ - - The processor generates \*roff output, the standard format for unix - manpages\. - - * __html__ - - The processor generates HTML output, for usage in and display by web - browsers\. - - * __tmml__ - - The processor generates TMML output, the Tcl Manpage Markup Language, a - derivative of XML\. - - * __latex__ - - The processor generates LaTeX output\. - - * __wiki__ - - The processor generates Wiki markup as understood by __wikit__\. - - * __list__ - - The processor extracts the information provided by - __manpage\_begin__\. - - * __null__ - - The processor does not generate any output\. - - - __mpexpand\.all__ ?*\-verbose*? ?*module*? - - This command uses __mpexpand__ to generate all possible output formats - for all manpages in the current directory\. The manpages are recognized - through the extension "\.man"\. If *\-verbose* is specified the command will - list its actions before executing them\. - - The *module* information is passed to __mpexpand__\. - -# NOTES - -Possible future formats are plain text, pdf and postscript\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -expander\(n\), format\(n\), formatter\(n\) - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2002 Andreas Kupries -Copyright © 2003 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2base/html_cssdefaults.md Index: embedded/md/tcllib/files/modules/doctools2base/html_cssdefaults.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2base/html_cssdefaults.md +++ embedded/md/tcllib/files/modules/doctools2base/html_cssdefaults.md @@ -1,90 +0,0 @@ - -[//000000001]: # (doctools::html::cssdefaults \- Documentation tools) -[//000000002]: # (Generated from file 'html\_cssdefaults\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::html::cssdefaults\(n\) 0\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::html::cssdefaults \- Default CSS style for HTML export plugins - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require doctools::html::cssdefaults ?0\.1? - -[__::doctools::html::cssdefaults::contents__](#1) - -# DESCRIPTION - -This package provides a single command providing access to the text of the -default CSS style to use for HTML markup generated by the various HTML export -plugins\. - -This is an internal package of doctools, for use by -*[export](\.\./\.\./\.\./\.\./index\.md\#export)* plugins, i\.e\. the packages -converting doctools related documented into other formats, most notably -*[HTML](\.\./\.\./\.\./\.\./index\.md\#html)*\. - -# API - - - __::doctools::html::cssdefaults::contents__ - - This command returns the text of the default CSS style to use for HTML - markup generated by the various HTML export plugins\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[CSS](\.\./\.\./\.\./\.\./index\.md\#css), [HTML](\.\./\.\./\.\./\.\./index\.md\#html), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[style](\.\./\.\./\.\./\.\./index\.md\#style) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2base/nroff_manmacros.md Index: embedded/md/tcllib/files/modules/doctools2base/nroff_manmacros.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2base/nroff_manmacros.md +++ embedded/md/tcllib/files/modules/doctools2base/nroff_manmacros.md @@ -1,91 +0,0 @@ - -[//000000001]: # (doctools::nroff::man\_macros \- Documentation tools) -[//000000002]: # (Generated from file 'nroff\_manmacros\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::nroff::man\_macros\(n\) 0\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::nroff::man\_macros \- Default CSS style for NROFF export plugins - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require doctools::nroff::man\_macros ?0\.1? - -[__::doctools::nroff::man\_macros::contents__](#1) - -# DESCRIPTION - -This package provides a single command providing access to the definition of the -nroff *man* macro set to use for NROFF markup generated by the various NROFF -export plugins\. - -This is an internal package of doctools, for use by -*[export](\.\./\.\./\.\./\.\./index\.md\#export)* plugins, i\.e\. the packages -converting doctools related documented into other formats, most notably -*[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff)*\. - -# API - - - __::doctools::nroff::man\_macros::contents__ - - This command returns the text of the default CSS style to use for NROFF - generated by the various NROFF export plugins\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[macros](\.\./\.\./\.\./\.\./index\.md\#macros), -[man\_macros](\.\./\.\./\.\./\.\./index\.md\#man\_macros), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2base/tcl_parse.md Index: embedded/md/tcllib/files/modules/doctools2base/tcl_parse.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2base/tcl_parse.md +++ embedded/md/tcllib/files/modules/doctools2base/tcl_parse.md @@ -1,213 +0,0 @@ - -[//000000001]: # (doctools::tcl::parse \- Documentation tools) -[//000000002]: # (Generated from file 'tcl\_parse\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::tcl::parse\(n\) 1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::tcl::parse \- Processing text in 'subst \-novariables' format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error format](#section3) - - - [Tree Structure](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require fileutil -package require logger -package require struct::list -package require struct::stack -package require struct::set -package require treeql -package require doctools::tcl::parse - -[__::doctools::tcl::parse__ __text__ *tree* *text* ?*root*?](#1) -[__::doctools::tcl::parse__ __file__ *tree* *path* ?*root*?](#2) - -# DESCRIPTION - -This package provides commands for parsing text with embedded Tcl commands as -accepted by the Tcl builtin command __subst \-novariables__\. The result of -the parsing is an abstract syntax tree\. - -This is an internal package of doctools, for use by the higher level parsers -processing the *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)*, -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)*, and -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* markup languages\. - -# API - - - __::doctools::tcl::parse__ __text__ *tree* *text* ?*root*? - - The command takes the *text* and parses it under the assumption that it - contains a string acceptable to the Tcl builtin command __subst - \-novariables__\. Errors are thrown otherwise during the parsing\. The format - used for these errors in described in section [Error - format](#section3)\. - - The command returns the empty string as it result\. The actual result of the - parsing is entered into the tree structure *tree*, under the node - *root*\. If *root* is not specified the root of *tree* is used\. The - *tree* has to exist and be the command of a tree object which supports the - same methods as trees created by the package - __[struct::tree](\.\./struct/struct\_tree\.md)__\. - - In case of errors *tree* will be left in an undefined state\. - - - __::doctools::tcl::parse__ __file__ *tree* *path* ?*root*? - - The same as __text__, except that the text to parse is read from the - file specified by *path*\. - -# Error format - -When the parser encounters a problem in the input it will throw an error using -the format described here\. - - 1. The message will contain the reason for the problem \(unexpected character - or end of input in input\), the character in question, if any, and the line - and column the problem was found at, in a human readable form\. This part is - not documented further as its format may change as we see fit\. It is - intended for human consumption, not machine\. - - 1. The error code however will contain a machine\-readable representation of - the problem, in the form of a 5\-element list containing, in the order - listed below - - 1) the constant string __doctools::tcl::parse__ - - 1) the cause of the problem, one of - - - __char__ - - Unexpected character in input - - - __eof__ - - Unexpected end of the input - - 1) The location of the problem as offset from the beginning of the input, - counted in characters\. Note: Line markers count as one character\. - - 1) The line the problem was found on \(counted from 1 \(one\)\), - - 1) The column the problem was found at \(counted from 0 \(zero\)\) - -# Tree Structure - -After successfully parsing a string the generated tree will have the following -structure: - - 1. In the following items the word 'root' refers to the node which was - specified as the root of the tree when invoking either __text__ or - __file__\. This may be the actual root of the tree\. - - 1. All the following items further ignore the possibility of pre\-existing - attributes in the pre\-existing nodes\. If attributes exists with the same - names as the attributes used by the parser the pre\-existing values are - written over\. Attributes with names not clashing with the parser's - attributes are not touched\. - - 1. The root node has no attributes\. - - 1. All other nodes have the attributes - - - type - - The value is a string from the set \{ Command , Text , Word \} - - - range - - The value is either empty or a 2\-element list containing integer - numbers\. The numbers are the offsets of the first and last character in - the input text, of the token described by the node,\. - - - line - - The value is an integer, it describes the line in the input the token - described by the node ends on\. Lines are counted from 1 \(__one__\)\. - - - col - - The value is an integer, it describes the column in the line in the - input the token described by the node ends on\. Columns are counted from - 0 \(__zero__\)\. - - 1. The children of the root, if any, are of type Command and Text, in - semi\-alternation\. This means: After a Text node a Command node has to - follow, and anything can follow a Command node, a Text or other Command - node\. - - 1. The children of a Command node, if any, are of type Command, and Text, and - Word, they describe the arguments of the command\. - - 1. The children of a Word node, if any, are of type Command, Text, in - semi\-alternation\. This means: After a Text node a Command node has to - follow, and anything can follow a Command node, a Text or other Command - node\. - - 1. A Word node without children represents the empty string\. - - 1. All Text nodes are leaves of the tree\. - - 1. All leaves of the tree are either Text or Command nodes\. Word nodes cannot - be leaves\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Tcl syntax](\.\./\.\./\.\./\.\./index\.md\#tcl\_syntax), -[command](\.\./\.\./\.\./\.\./index\.md\#command), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), -[subst](\.\./\.\./\.\./\.\./index\.md\#subst), [word](\.\./\.\./\.\./\.\./index\.md\#word) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2base/tcllib_msgcat.md Index: embedded/md/tcllib/files/modules/doctools2base/tcllib_msgcat.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2base/tcllib_msgcat.md +++ embedded/md/tcllib/files/modules/doctools2base/tcllib_msgcat.md @@ -1,111 +0,0 @@ - -[//000000001]: # (doctools::msgcat \- Documentation tools) -[//000000002]: # (Generated from file 'tcllib\_msgcat\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::msgcat\(n\) 0\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::msgcat \- Message catalog management for the various document parsers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat ?0\.1? - -[__::doctools::msgcat::init__ *prefix*](#1) - -# DESCRIPTION - -The package __doctools::msgcat__ is a support module handling the selection -of message catalogs for the various document processing packages in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ - -Within the system architecture this package resides under the various parser -packages, and is shared by them\. Underneath it, but not explicit dependencies, -are the packages providing the message catalogs for the various languages\. - -# API - - - __::doctools::msgcat::init__ *prefix* - - The command locates and loads the message catalogs for all the languages - returned by __msgcat::mcpreferences__, provided that they could be - found\. It returns an integer number describing how many packages were found - and loaded\. - - The names of the packages the command will look for have the form - "doctools::msgcat::*prefix*::__langcode__", with *prefix* the - argument to the command, and the __langcode__ supplied by the result of - __msgcat::mcpreferences__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[catalog package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md Index: embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md +++ embedded/md/tcllib/files/modules/doctools2idx/export_docidx.md @@ -1,253 +0,0 @@ - -[//000000001]: # (doctools::idx::export::docidx \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) -[//000000004]: # (doctools::idx::export::docidx\(n\) 0\.2\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::idx::export::docidx \- docidx export plugin - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [\[docidx\] notation of keyword indices](#section3) - - - [Configuration](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::docidx ?0\.2\.1? - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of docidx markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates docidx markup encoding the index\. The created string is then - returned as the result of the command\. - -# \[docidx\] notation of keyword indices - -The docidx format for keyword indices, also called the *docidx markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[docidx language introduction](\.\./doctools/docidx\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[docidx language syntax](\.\./doctools/docidx\_lang\_syntax\.md)* and - - 1. *[docidx language command - reference](\.\./doctools/docidx\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# Configuration - -The docidx export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the index - came from\. This variable may not be set or contain the empty string\. The - plugin puts this information, if defined, i\.e\. set and not the empty string, - into the provenance comment at the beginning of the generated document\. - - - boolean *newlines* - - If this flag is set the plugin will break the generated docidx code across - lines, with each markup command on a separate line\. - - If this flag is not set \(the default\), the whole document will be written on - a single line, with minimum spacing between all elements\. - - - boolean *indented* - - If this flag is set the plugin will indent the markup commands according to - the structure of indices\. To make this work this also implies that - __newlines__ is set\. This effect is independent of the value for - __aligned__ however\. - - If this flag is not set \(the default\), the output is formatted as per the - values of __newlines__ and __aligned__, and no indenting is done\. - - - boolean *aligned* - - If this flag is set the generator ensures that the arguments for the - __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ and - __[url](\.\./\.\./\.\./\.\./index\.md\#url)__ commands in a keyword section - are aligned vertically for a nice table effect\. To make this work this also - implies that __newlines__ is set\. This effect is independent of the - value for __indented__ however\. - - If this flag is not set \(the default\), the output is formatted as per the - values of __newlines__ and __indented__, and no alignment is done\. - -*Note* that this plugin ignores the standard configuration variables -__format__, and __map__, and their values\. - -# Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# CATEGORY - -Text formatter plugin - -# COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_container.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_container.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_container.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_container.md @@ -1,443 +0,0 @@ - -[//000000001]: # (doctools::idx \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_container\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (doctools::idx\(n\) 2 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::idx \- Holding keyword indices - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require doctools::idx ?2? -package require Tcl 8\.4 -package require doctools::idx::structure -package require snit - -[__::doctools::idx__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __key add__ *name*](#4) -[*objectName* __key remove__ *name*](#5) -[*objectName* __key references__ *name*](#6) -[*objectName* __keys__](#7) -[*objectName* __reference add__ *type* *key* *name* *label*](#8) -[*objectName* __reference remove__ *name*](#9) -[*objectName* __reference label__ *name*](#10) -[*objectName* __reference keys__ *name*](#11) -[*objectName* __reference type__ *name*](#12) -[*objectName* __references__](#13) -[*objectName* __title__](#14) -[*objectName* __title__ *text*](#15) -[*objectName* __label__](#16) -[*objectName* __label__ *text*](#17) -[*objectName* __importer__](#18) -[*objectName* __importer__ *object*](#19) -[*objectName* __exporter__](#20) -[*objectName* __exporter__ *object*](#21) -[*objectName* __deserialize =__ *data* ?*format*?](#22) -[*objectName* __deserialize \+=__ *data* ?*format*?](#23) -[*objectName* __serialize__ ?*format*?](#24) - -# DESCRIPTION - -This package provides a class to contain and programmatically manipulate keyword -indices - -This is one of the three public pillars the management of keyword indices -resides on\. The other two pillars are - - 1. *[Exporting keyword indices](idx\_export\.md)*, and - - 1. *[Importing keyword indices](idx\_import\.md)* - -For information about the [Concepts](#section2) of keyword indices, and -their parts, see the same\-named section\. For information about the data -structure which is used to encode keyword indices as values see the section -[Keyword index serialization format](#section4)\. This is the only format -directly known to this class\. Conversions from and to any other format are -handled by export and import manager objects\. These may be attached to a -container, but do not have to be, it is merely a convenience\. - -# Concepts - - 1. A *[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index)* consists of a - \(possibly empty\) set of *[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)*\. - - 1. Each keyword in the set is identified by its name\. - - 1. Each keyword has a \(possibly empty\) set of *references*\. - - 1. A reference can be associated with more than one keyword\. - - 1. A reference not associated with at least one keyword is not possible - however\. - - 1. Each reference is identified by its target, specified as either an url or - symbolic filename, depending on the type of reference \(__url__, or - __manpage__\)\. - - 1. The type of a reference \(url, or manpage\) depends only on the reference - itself, and not the keywords it is associated with\. - - 1. In addition to a type each reference has a descriptive label as well\. This - label depends only on the reference itself, and not the keywords it is - associated with\. - -A few notes - - 1. Manpage references are intended to be used for references to the documents - the index is made for\. Their target is a symbolic file name identifying the - document, and export plugins may replace symbolic with actual file names, - if specified\. - - 1. Url references are intended on the othre hand are inteded to be used for - links to anything else, like websites\. Their target is an url\. - - 1. While url and manpage references share a namespace for their identifiers, - this should be no problem, given that manpage identifiers are symbolic - filenames and as such they should never look like urls, the identifiers for - url references\. - -# API - -## Package commands - - - __::doctools::idx__ *objectName* - - This command creates a new container object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## Object command - -All objects created by the __::doctools::idx__ command have the following -general form: - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __key add__ *name* - - This method adds the keyword *name* to the index\. If the keyword is - already known nothing is done\. The result of the method is the empty string\. - - - *objectName* __key remove__ *name* - - This method removes the keyword *name* from the index\. If the keyword is - already gone nothing is done\. Any references for whom this keyword was the - last association are removed as well\. The result of the method is the empty - string\. - - - *objectName* __key references__ *name* - - This method returns a list containing the names of all references associated - with the keyword *name*\. An error is thrown in the keyword is not known to - the index\. The order of the references in the list is undefined\. - - - *objectName* __keys__ - - This method returns a list containing the names of all keywords known to the - index\. The order of the keywords in the list is undefined\. - - - *objectName* __reference add__ *type* *key* *name* *label* - - This method adds the reference *name* to the index and associates it with - the keyword *key*\. The other two arguments hold the *type* and *label* - of the reference, respectively\. The type has to match the stored - information, should the reference exist already, i\.e\. this information is - immutable after the reference is known\. The only way to change it is delete - and recreate the reference\. The label on the other hand is automatically - updated to the value of the argument, overwriting any previously stored - information\. Should the reference exists already it is simply associated - with the *key*\. If that is true already as well nothing is done, but the - *label* updated to the new value\. The result of the method is the empty - string\. - - The *type* argument has be to one of __manpage__ or __url__\. - - - *objectName* __reference remove__ *name* - - The reference *name* is removed from the index\. All associations with - keywords are released and the relevant reference labels removed\. The result - of the method is the empty string\. - - - *objectName* __reference label__ *name* - - This method returns the label associated with the reference *name*\. An - error is thrown if the reference is not known\. - - - *objectName* __reference keys__ *name* - - This method returns a list containing the names of all keywords associated - with the reference *name*\. An error is thrown in the reference is not - known to the index\. The order of the keywords in the list is undefined\. - - - *objectName* __reference type__ *name* - - This method returns the type of the reference *name*\. An error is thrown - in the reference is not known to the index\. - - - *objectName* __references__ - - This method returns a list containing the names of all references known to - the index\. The order of the references in the list is undefined\. - - - *objectName* __title__ - - Returns the currently defined title of the keyword index\. - - - *objectName* __title__ *text* - - Sets the title of the keyword index to *text*, and returns it as the - result of the command\. - - - *objectName* __label__ - - Returns the currently defined label of the keyword index\. - - - *objectName* __label__ *text* - - Sets the label of the keyword index to *text*, and returns it as the - result of the command\. - - - *objectName* __importer__ - - Returns the import manager object currently attached to the container, if - any\. - - - *objectName* __importer__ *object* - - Attaches the *object* as import manager to the container, and returns it - as the result of the command\. Note that the *object* is *not* put into - ownership of the container\. I\.e\., destruction of the container will *not* - destroy the *object*\. - - It is expected that *object* provides a method named __import text__ - which takes a text and a format name, and returns the canonical - serialization of the keyword index contained in the text, assuming the given - format\. - - - *objectName* __exporter__ - - Returns the export manager object currently attached to the container, if - any\. - - - *objectName* __exporter__ *object* - - Attaches the *object* as export manager to the container, and returns it - as the result of the command\. Note that the *object* is *not* put into - ownership of the container\. I\.e\., destruction of the container will *not* - destroy the *object*\. - - It is expected that *object* provides a method named __export object__ - which takes the container and a format name, and returns a text encoding - keyword index stored in the container, in the given format\. It is further - expected that the *object* will use the container's method - __serialize__ to obtain the serialization of the keyword index from - which to generate the text\. - - - *objectName* __deserialize =__ *data* ?*format*? - - This method replaces the contents of the index object with the index - contained in the *data*\. If no *format* was specified it is assumed to - be the regular serialization of a keyword index\. - - Otherwise the object will use the attached import manager to convert the - data from the specified format to a serialization it can handle\. In that - case an error will be thrown if the container has no import manager attached - to it\. - - The result of the method is the empty string\. - - - *objectName* __deserialize \+=__ *data* ?*format*? - - This method behaves like __deserialize =__ in its essentials, except - that it merges the keyword index in the *data* to its contents instead of - replacing it\. The method will throw an error if merging is not possible, - i\.e\. would produce an invalid index\. The existing content is left unchanged - in that case\. - - The result of the method is the empty string\. - - - *objectName* __serialize__ ?*format*? - - This method returns the keyword index contained in the object\. If no - *format* is not specified the returned result is the canonical - serialization of its contents\. - - Otherwise the object will use the attached export manager to convert the - data to the specified format\. In that case an error will be thrown if the - container has no export manager attached to it\. - -# Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), [docidx -markup](\.\./\.\./\.\./\.\./index\.md\#docidx\_markup), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[generation](\.\./\.\./\.\./\.\./index\.md\#generation), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [json](\.\./\.\./\.\./\.\./index\.md\#json), -[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[latex](\.\./\.\./\.\./\.\./index\.md\#latex), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), [tcler's -wiki](\.\./\.\./\.\./\.\./index\.md\#tcler\_s\_wiki), -[text](\.\./\.\./\.\./\.\./index\.md\#text), [url](\.\./\.\./\.\./\.\./index\.md\#url), -[wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export.md @@ -1,472 +0,0 @@ - -[//000000001]: # (doctools::idx::export \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_export\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) -[//000000004]: # (doctools::idx::export\(n\) 0\.2\.1 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::idx::export \- Exporting keyword indices - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Export plugin API v2 reference](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require doctools::idx::export ?0\.2\.1? -package require Tcl 8\.4 -package require struct::map -package require doctools::idx::structure -package require snit -package require pluginmgr - -[__::doctools::idx::export__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __export serial__ *serial* ?*format*?](#4) -[*objectName* __export object__ *object* ?*format*?](#5) -[*objectName* __config names__](#6) -[*objectName* __config get__](#7) -[*objectName* __config set__ *name* ?*value*?](#8) -[*objectName* __config unset__ *pattern*\.\.\.](#9) -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#10) - -# DESCRIPTION - -This package provides a class to manage the plugins for the export of keyword -indices to other formats, i\.e\. their conversion to, for example -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)*, -*[HTML](\.\./\.\./\.\./\.\./index\.md\#html)*, etc\. - -This is one of the three public pillars the management of keyword indices -resides on\. The other two pillars are - - 1. *[Importing keyword indices](idx\_import\.md)*, and - - 1. *[Holding keyword indices](idx\_container\.md)* - -For information about the [Concepts](#section2) of keyword indices, and -their parts, see the same\-named section\. For information about the data -structure which is the major input to the manager objects provided by this -package see the section [Keyword index serialization format](#section5)\. - -The plugin system of our class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __DOCTOOLS\_IDX\_EXPORT\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_IDX\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_PLUGINS__, - - 1. the path "~/\.doctools/idx/export/plugin" - - 1. the path "~/\.doctools/idx/plugin" - - 1. the path "~/\.doctools/plugin" - - 1. the path "~/\.doctools/idx/export/plugins" - - 1. the path "~/\.doctools/idx/plugins" - - 1. the path "~/\.doctools/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\IDX\\EXPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\IDX\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" - -The last three are used only when the package is run on a machine using -Windows\(tm\) operating system\. - -The whole system is delivered with six predefined export plugins, namely - - - docidx - - See *[docidx export plugin](export\_docidx\.md)* for details\. - - - html - - See *html export plugin* for details\. - - - json - - See *json export plugin* for details\. - - - nroff - - See *[nroff export plugin](\.\./doctools2toc/toc\_export\_nroff\.md)* for - details\. - - - text - - See *text export plugin* for details\. - - - wiki - - See *[wiki export plugin](\.\./doctools2toc/toc\_export\_wiki\.md)* for - details\. - -Readers wishing to write their own export plugin for some format, i\.e\. *plugin -writer*s reading and understanding the section containing the [Export plugin -API v2 reference](#section4) is an absolute necessity, as it specifies the -interaction between this package and its plugins in detail\. - -# Concepts - - 1. A *[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index)* consists of a - \(possibly empty\) set of *[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)*\. - - 1. Each keyword in the set is identified by its name\. - - 1. Each keyword has a \(possibly empty\) set of *references*\. - - 1. A reference can be associated with more than one keyword\. - - 1. A reference not associated with at least one keyword is not possible - however\. - - 1. Each reference is identified by its target, specified as either an url or - symbolic filename, depending on the type of reference \(__url__, or - __manpage__\)\. - - 1. The type of a reference \(url, or manpage\) depends only on the reference - itself, and not the keywords it is associated with\. - - 1. In addition to a type each reference has a descriptive label as well\. This - label depends only on the reference itself, and not the keywords it is - associated with\. - -A few notes - - 1. Manpage references are intended to be used for references to the documents - the index is made for\. Their target is a symbolic file name identifying the - document, and export plugins may replace symbolic with actual file names, - if specified\. - - 1. Url references are intended on the othre hand are inteded to be used for - links to anything else, like websites\. Their target is an url\. - - 1. While url and manpage references share a namespace for their identifiers, - this should be no problem, given that manpage identifiers are symbolic - filenames and as such they should never look like urls, the identifiers for - url references\. - -# API - -## Package commands - - - __::doctools::idx::export__ *objectName* - - This command creates a new export manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## Object command - -All objects created by the __::doctools::idx::export__ command have the -following general form: - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __export serial__ *serial* ?*format*? - - This method takes the canonical serialization of a keyword index stored in - *serial* and converts it to the specified *format*, using the export - plugin for the format\. An error is thrown if no plugin could be found for - the format\. The string generated by the conversion process is returned as - the result of this method\. - - If no format is specified the method defaults to __docidx__\. - - The specification of what a *canonical* serialization is can be found in - the section [Keyword index serialization format](#section5)\. - - The plugin has to conform to the interface specified in section [Export - plugin API v2 reference](#section4)\. - - - *objectName* __export object__ *object* ?*format*? - - This method is a convenient wrapper around the __export serial__ method - described by the previous item\. It expects that *object* is an object - command supporting a __serialize__ method returning the canonical - serialization of a keyword index\. It invokes that method, feeds the result - into __export serial__ and returns the resulting string as its own - result\. - - - *objectName* __config names__ - - This method returns a list containing the names of all configuration - variables currently known to the object\. - - - *objectName* __config get__ - - This method returns a dictionary containing the names and values of all - configuration variables currently known to the object\. - - - *objectName* __config set__ *name* ?*value*? - - This method sets the configuration variable *name* to the specified - *value* and returns the new value of the variable\. - - If no value is specified it simply returns the current value, without - changing it\. - - Note that while the user can set the predefined configuration variables - __user__ and __format__ doing so will have no effect, these values - will be internally overridden when invoking an import plugin\. - - - *objectName* __config unset__ *pattern*\.\.\. - - This method unsets all configuration variables matching the specified glob - *pattern*s\. If no pattern is specified it will unset all currently defined - configuration variables\. - -# Export plugin API v2 reference - -Plugins are what this package uses to manage the support for any output format -beyond the [Keyword index serialization format](#section5)\. Here we specify -the API the objects created by this package use to interact with their plugins\. - -A plugin for this package has to follow the rules listed below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form - doctools::idx::export::__FOO__, where __FOO__ is the name of the - format the plugin will generate output for\. This name is also the argument - to provide to the various __export__ methods of export manager objects - to get a string encoding a keyword index in that format\. - - 1. The plugin can expect that the package - __doctools::idx::export::plugin__ is present, as indicator that it was - invoked from a genuine plugin manager\. - - 1. A plugin has to provide one command, with the signature shown below\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - Whenever an export manager of - __[doctools::idx](idx\_container\.md)__ has to generate output - for an index it will invoke this command\. - - * string *serial* - - This argument will contain the *canonical* serialization of the - index for which to generate the output\. The specification of what a - *canonical* serialization is can be found in the section - [Keyword index serialization format](#section5)\. - - * dictionary *configuration* - - This argument will contain the current configuration to apply to - the generation, as a dictionary mapping from variable names to - values\. - - The following configuration variables have a predefined meaning all - plugins have to obey, although they can ignore this information at - their discretion\. Any other other configuration variables - recognized by a plugin will be described in the manpage for that - plugin\. - - + user - - This variable is expected to contain the name of the user - owning the process invoking the plugin\. - - + format - - This variable is expected to contain the name of the format - whose plugin is invoked\. - - + file - - This variable, if defined by the user of the index object is - expected to contain the name of the input file for which the - plugin is generating its output for\. - - + map - - This variable, if defined by the user of the index object is - expected to contain a dictionary mapping from symbolic file - names used in the references of type __manpage__ to actual - paths \(or urls\)\. A plugin has to be able to handle the - possibility that a symbolic name is without entry in this - mapping\. - - 1. A single usage cycle of a plugin consists of the invokations of the command - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[generation](\.\./\.\./\.\./\.\./index\.md\#generation), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [json](\.\./\.\./\.\./\.\./index\.md\#json), -[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), [tcler's -wiki](\.\./\.\./\.\./\.\./index\.md\#tcler\_s\_wiki), -[text](\.\./\.\./\.\./\.\./index\.md\#text), [url](\.\./\.\./\.\./\.\./index\.md\#url), -[wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export_html.md @@ -1,351 +0,0 @@ - -[//000000001]: # (doctools::idx::export::html \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries ) -[//000000004]: # (doctools::idx::export::html\(n\) 0\.2 tcllib "Documentation tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -doctools::idx::export::html \- HTML export plugin - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::html ?0\.2? -package require doctools::text -package require doctools::html -package require doctools::html::cssdefaults - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of HTML markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section4), - and contained in *serial*, the *configuration*, a dictionary, and - generates HTML markup encoding the index\. The created string is then - returned as the result of the command\. - -# Configuration - -The html export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the index - came from\. This variable may not be set or contain the empty string\. The - plugin puts this information, if defined, i\.e\. set and not the empty string, - into the provenance comment at the beginning of the generated document\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - symbolic files names in manpage references to the actual filenames and/or - urls to be used in the output\. - - Url references and symbolic file names without a mapping are used unchanged\. - - - boolean *newlines* - - If this flag is set the plugin will break the generated html code across - lines, with each markup command on a separate line\. - - If this flag is not set \(the default\), the whole document will be written on - a single line, with minimum spacing between all elements\. - - - boolean *indented* - - If this flag is set the plugin will indent the markup commands according to - the structure of indices\. To make this work this also implies that - __newlines__ is set\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __newlines__, and no indenting is done\. - - - string *meta* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output in the - section of the document, just after the tag\. - - - string *header* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output just after - the <h1> title tag in the body of the document, in the class\.header - <div>'ision\. - - - string *footer* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output just before - the </body> tag, in the class\.footer <div>'ision\. - - - dictionary *kwid* - - The value of this variable \(default: empty\) maps keywords to the identifiers - to use as their anchor names\. Each keyword __FOO__ not found in the - dictionary uses __KW\-____FOO__ as anchor, i\.e\. itself prefixed with - the string __KW\-__\. - - - string *sepline* - - The value of this variable is the string to use for the separator comments - inserted into the output when the outpout is broken across lines and/or - indented\. The default string consists of 60 dashes\. - - - integer *kwidth* - - This variable holds the size of the keyword column in the main table - generated by the plugin, in percent of the total width of the table\. This is - an integer number in the range of 1 to 99\. Choosing a value outside of that - range causes the generator to switch back to the defauly setting, 35 - percent\. - - - string *dot* - - This variable contains a HTML fragment inserted between the entries of the - navigation bar, and the references associated with each keyword\. The default - is the HTML entity &\#183; i\.e\. the bullet character, also known as the - "Greek middle dot", i\.e\. the unicode character 00B7\. - - - string *class\.main* - - This variable contains the class name for the main <div>'ivision of the - generated document\. The default is __doctools__\. - - - string *class\.header* - - This variable contains the class name for the header <div>'ision of the - generated document\. The default is __idx\-header__\. This division - contains the document title, the user specified __header__, if any, a - visible separator line, and the navigation bar for quick access to each - keyword section\. - - - string *class\.title* - - This variable contains the class name for the <h1> tag enclosing the - document title\. The default is __idx\-title__\. - - - string *class\.navsep* - - This variable contains the class name for the <hr> separators in the header - and footer sections of the generated document\. The default is - __idx\-navsep__\. - - - string *class\.navbar* - - This variable contains the class name for the navigation <div>'ision - enclosing the navigation bar of the generated document\. The default is - __idx\-kwnav__\. - - - string *class\.contents* - - This variable contains the class name for the <table> holding the keywords - and their references in the generated document\. The default is - __idx\-contents__\. - - - string *class\.leader* - - This variable contains the class name for the anchor names the plugin - inserts into the keyword table when switching from one section to the next - \(Each section holds all keywords with a particular first character\)\. The - default is __idx\-leader__\. - - - string *class\.row0* - - This variable contains the class name used to label the even rows \(<tr>\) of - the keyword table\. The default is __idx\-even__\. - - - string *class\.row1* - - This variable contains the class name used to label the odd rows \(<tr>\) of - the keyword table\. The default is __idx\-odd__\. - - - string *class\.keyword* - - This variable contains the class name used to label the keyword cells/column - \(<td>\) in the keyword table of the document\. The default is - __idx\-keyword__\. - - - string *class\.refs* - - This variable contains the class name used to label the reference - cells/column \(<td>\) in the keyword table of the document\. The default is - __idx\-refs__\. - - - string *class\.footer* - - This variable contains the class name for the footer <div>'ision of the - generated document\. The default is __idx\-footer__\. This division - contains a browser\-visible separator line and the user specified - __footer__, if any\. - -*Note* that this plugin ignores the standard configuration variable -__format__, and its value\. - -# <a name='section4'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export_json.md @@ -1,260 +0,0 @@ - -[//000000001]: # (doctools::idx::export::json \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::export::json\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::export::json \- JSON export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON notation of keyword indices](#section3) - - - [Configuration](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::json ?0\.1? -package require textutil::adjust - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of JSON markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates JSON markup encoding the index\. The created string is then - returned as the result of the command\. - -# <a name='section3'></a>JSON notation of keyword indices - -The JSON format used for keyword indices is a direct translation of the -[Keyword index serialization format](#section5), mapping Tcl dictionaries -as JSON objects and Tcl lists as JSON arrays\. For example, the Tcl serialization - - doctools::idx { - label {Keyword Index} - keywords { - changelog {changelog.man cvs.man} - conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man} - cvs cvs.man - } - references { - apps/dtplite.man {manpage dtplite} - changelog.man {manpage doctools::changelog} - cvs.man {manpage doctools::cvs} - docidx.man {manpage doctools::idx} - doctoc.man {manpage doctools::toc} - doctools.man {manpage doctools} - mpexpand.man {manpage mpexpand} - } - title {} - } - -is equivalent to the JSON string - - { - "doctools::idx" : { - "label" : "Keyword Index", - "keywords" : { - "changelog" : ["changelog.man","cvs.man"], - "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"], - "cvs" : ["cvs.man"], - }, - "references" : { - "apps\/dtplite.man" : ["manpage","dtplite"], - "changelog.man" : ["manpage","doctools::changelog"], - "cvs.man" : ["manpage","doctools::cvs"], - "docidx.man" : ["manpage","doctools::idx"], - "doctoc.man" : ["manpage","doctools::toc"], - "doctools.man" : ["manpage","doctools"], - "mpexpand.man" : ["manpage","mpexpand"] - }, - "title" : "" - } - } - -# <a name='section4'></a>Configuration - -The JSON export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - boolean *indented* - - If this flag is set the plugin will break the generated JSON code across - lines and indent it according to its inner structure, with each key of a - dictionary on a separate line\. - - If this flag is not set \(the default\), the whole JSON object will be written - on a single line, with minimum spacing between all elements\. - - - boolean *aligned* - - If this flag is set the generator ensures that the values for the keys in a - dictionary are vertically aligned with each other, for a nice table effect\. - To make this work this also implies that __indented__ is set\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __indented__, without trying to align the values for dictionary - keys\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __format__, __file__, and __map__ and their values\. - -# <a name='section5'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export_nroff.md @@ -1,215 +0,0 @@ - -[//000000001]: # (doctools::idx::export::nroff \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::export::nroff\(n\) 0\.3 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::export::nroff \- nroff export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::nroff ?0\.3? -package require doctools::text -package require doctools::nroff::man\_macros - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of nroff markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section4), - and contained in *serial*, the *configuration*, a dictionary, and - generates nroff markup encoding the index\. The created string is then - returned as the result of the command\. - -# <a name='section3'></a>Configuration - -The nroff export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the index - came from\. This variable may not be set or contain the empty string\. The - plugin puts this information, if defined, i\.e\. set and not the empty string, - into the provenance comment at the beginning of the generated document\. - - - boolean *inline* - - If this flag is set \(default\) the plugin will place the definitions of the - man macro set directly into the output\. - - If this flag is not set, the plugin will place a reference to the - definitions of the man macro set into the output, but not the macro - definitions themselves\. - -*Note* that this plugin ignores the standard configuration variables -__format__, and __map__, and their values\. - -# <a name='section4'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export_text.md @@ -1,199 +0,0 @@ - -[//000000001]: # (doctools::idx::export::text \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::export::text\(n\) 0\.2 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::export::text \- plain text export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::text ?0\.2? -package require doctools::text - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of plain text markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section4), - and contained in *serial*, the *configuration*, a dictionary, and - generates plain text markup encoding the index\. The created string is then - returned as the result of the command\. - -# <a name='section3'></a>Configuration - -The text export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - symbolic files names in manpage references to the actual filenames and/or - urls to be used in the output\. - - Url references and symbolic file names without a mapping are used unchanged\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __file__, and __format__, and their values\. - -# <a name='section4'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [plain -text](\.\./\.\./\.\./\.\./index\.md\#plain\_text), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_export_wiki.md @@ -1,215 +0,0 @@ - -[//000000001]: # (doctools::idx::export::wiki \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::export::wiki\(n\) 0\.2 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::export::wiki \- wiki export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Wiki markup](#section3) - - - [Configuration](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::idx::export::wiki ?0\.2? -package require doctools::text - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index export plugin for the -generation of wiki markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::export](idx\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::export](idx\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a keyword index, as - specified in section [Keyword index serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates wiki markup encoding the index\. The created string is then - returned as the result of the command\. - -# <a name='section3'></a>Wiki markup - -The basic syntax of the wiki markup generated by this plugin are described at -[http://wiki\.tcl\.tk/14](http://wiki\.tcl\.tk/14)\. - -The plugin goes beyond the classic markup to generate proper headers and either -a table or indented list of the keywords and their references\. - -# <a name='section4'></a>Configuration - -The wiki export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - symbolic files names in manpage references to the actual filenames and/or - urls to be used in the output\. - - Url references and symbolic file names without a mapping are used unchanged\. - - - enum *style* - - This variable recognizes two values as legal, __list__ \(default\), and - __table__\. Depending on the value the plugin generates either a list\- or - table\-based wiki page for the index\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __file__ and __format__, and their values\. - -# <a name='section5'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[index](\.\./\.\./\.\./\.\./index\.md\#index), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_import.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_import.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_import.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_import.md @@ -1,529 +0,0 @@ - -[//000000001]: # (doctools::idx::import \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_import\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::import\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::import \- Importing keyword indices - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Import plugin API v2 reference](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::idx::import ?0\.2\.1? -package require Tcl 8\.4 -package require struct::map -package require doctools::idx::structure -package require snit -package require pluginmgr - -[__::doctools::idx::import__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __import text__ *text* ?*format*?](#4) -[*objectName* __import file__ *path* ?*format*?](#5) -[*objectName* __import object text__ *object* *text* ?*format*?](#6) -[*objectName* __import object file__ *object* *path* ?*format*?](#7) -[*objectName* __config names__](#8) -[*objectName* __config get__](#9) -[*objectName* __config set__ *name* ?*value*?](#10) -[*objectName* __config unset__ *pattern*\.\.\.](#11) -[*objectName* __includes__](#12) -[*objectName* __include add__ *path*](#13) -[*objectName* __include remove__ *path*](#14) -[*objectName* __include clear__](#15) -[__IncludeFile__ *currentfile* *path*](#16) -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*](#17) - -# <a name='description'></a>DESCRIPTION - -This package provides a class to manage the plugins for the import of keyword -indices from other formats, i\.e\. their conversion from, for example -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)*, -*[json](\.\./\.\./\.\./\.\./index\.md\#json)*, etc\. - -This is one of the three public pillars the management of keyword indices -resides on\. The other two pillars are - - 1. *[Exporting keyword indices](idx\_export\.md)*, and - - 1. *[Holding keyword indices](idx\_container\.md)* - -For information about the [Concepts](#section2) of keyword indices, and -their parts, see the same\-named section\. For information about the data -structure which is the major output of the manager objects provided by this -package see the section [Keyword index serialization format](#section5)\. - -The plugin system of our class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __DOCTOOLS\_IDX\_IMPORT\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_IDX\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_PLUGINS__, - - 1. the path "~/\.doctools/idx/import/plugin" - - 1. the path "~/\.doctools/idx/plugin" - - 1. the path "~/\.doctools/plugin" - - 1. the path "~/\.doctools/idx/import/plugins" - - 1. the path "~/\.doctools/idx/plugins" - - 1. the path "~/\.doctools/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\IDX\\IMPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\IDX\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" - -The last three are used only when the package is run on a machine using -Windows\(tm\) operating system\. - -The whole system is delivered with two predefined import plugins, namely - - - docidx - - See *[docidx import plugin](import\_docidx\.md)* for details\. - - - json - - See *json import plugin* for details\. - -Readers wishing to write their own import plugin for some format, i\.e\. *plugin -writer*s reading and understanding the section containing the [Import plugin -API v2 reference](#section4) is an absolute necessity, as it specifies the -interaction between this package and its plugins in detail\. - -# <a name='section2'></a>Concepts - - 1. A *[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index)* consists of a - \(possibly empty\) set of *[keywords](\.\./\.\./\.\./\.\./index\.md\#keywords)*\. - - 1. Each keyword in the set is identified by its name\. - - 1. Each keyword has a \(possibly empty\) set of *references*\. - - 1. A reference can be associated with more than one keyword\. - - 1. A reference not associated with at least one keyword is not possible - however\. - - 1. Each reference is identified by its target, specified as either an url or - symbolic filename, depending on the type of reference \(__url__, or - __manpage__\)\. - - 1. The type of a reference \(url, or manpage\) depends only on the reference - itself, and not the keywords it is associated with\. - - 1. In addition to a type each reference has a descriptive label as well\. This - label depends only on the reference itself, and not the keywords it is - associated with\. - -A few notes - - 1. Manpage references are intended to be used for references to the documents - the index is made for\. Their target is a symbolic file name identifying the - document, and export plugins may replace symbolic with actual file names, - if specified\. - - 1. Url references are intended on the othre hand are inteded to be used for - links to anything else, like websites\. Their target is an url\. - - 1. While url and manpage references share a namespace for their identifiers, - this should be no problem, given that manpage identifiers are symbolic - filenames and as such they should never look like urls, the identifiers for - url references\. - -# <a name='section3'></a>API - -## <a name='subsection1'></a>Package commands - - - <a name='1'></a>__::doctools::idx::import__ *objectName* - - This command creates a new import manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## <a name='subsection2'></a>Object command - -All objects created by the __::doctools::idx::import__ command have the -following general form: - - - <a name='2'></a>__objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## <a name='subsection3'></a>Object methods - - - <a name='3'></a>*objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - <a name='4'></a>*objectName* __import text__ *text* ?*format*? - - This method takes the *text* and converts it from the specified *format* - to the canonical serialization of a keyword index using the import plugin - for the format\. An error is thrown if no plugin could be found for the - format\. The serialization generated by the conversion process is returned as - the result of this method\. - - If no format is specified the method defaults to __docidx__\. - - The specification of what a *canonical* serialization is can be found in - the section [Keyword index serialization format](#section5)\. - - The plugin has to conform to the interface specified in section [Import - plugin API v2 reference](#section4)\. - - - <a name='5'></a>*objectName* __import file__ *path* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It reads the contents of the specified file - into memory, feeds the result into __import text__ and returns the - resulting serialization as its own result\. - - - <a name='6'></a>*objectName* __import object text__ *object* *text* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It expects that *object* is an object - command supporting a __deserialize__ method expecting the canonical - serialization of a keyword index\. It imports the text using __import - text__ and then feeds the resulting serialization into the *object* via - __deserialize__\. This method returns the empty string as it result\. - - - <a name='7'></a>*objectName* __import object file__ *object* *path* ?*format*? - - This method behaves like __import object text__, except that it reads - the text to convert from the specified file instead of being given it as - argument\. - - - <a name='8'></a>*objectName* __config names__ - - This method returns a list containing the names of all configuration - variables currently known to the object\. - - - <a name='9'></a>*objectName* __config get__ - - This method returns a dictionary containing the names and values of all - configuration variables currently known to the object\. - - - <a name='10'></a>*objectName* __config set__ *name* ?*value*? - - This method sets the configuration variable *name* to the specified - *value* and returns the new value of the variable\. - - If no value is specified it simply returns the current value, without - changing it\. - - Note that while the user can set the predefined configuration variables - __user__ and __format__ doing so will have no effect, these values - will be internally overridden when invoking an import plugin\. - - - <a name='11'></a>*objectName* __config unset__ *pattern*\.\.\. - - This method unsets all configuration variables matching the specified glob - *pattern*s\. If no pattern is specified it will unset all currently defined - configuration variables\. - - - <a name='12'></a>*objectName* __includes__ - - This method returns a list containing the currently specified paths to use - to search for include files when processing input\. The order of paths in the - list corresponds to the order in which they are used, from first to last, - and also corresponds to the order in which they were added to the object\. - - - <a name='13'></a>*objectName* __include add__ *path* - - This methods adds the specified *path* to the list of paths to use to - search for include files when processing input\. The path is added to the end - of the list, causing it to be searched after all previously added paths\. The - result of the command is the empty string\. - - The method does nothing if the path is already known\. - - - <a name='14'></a>*objectName* __include remove__ *path* - - This methods removes the specified *path* from the list of paths to use to - search for include files when processing input\. The result of the command is - the empty string\. - - The method does nothing if the path is not known\. - - - <a name='15'></a>*objectName* __include clear__ - - This method clears the list of paths to use to search for include files when - processing input\. The result of the command is the empty string\. - -# <a name='section4'></a>Import plugin API v2 reference - -Plugins are what this package uses to manage the support for any input format -beyond the [Keyword index serialization format](#section5)\. Here we specify -the API the objects created by this package use to interact with their plugins\. - -A plugin for this package has to follow the rules listed below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form - doctools::idx::import::__FOO__, where __FOO__ is the name of the - format the plugin will generate output for\. This name is also the argument - to provide to the various __import__ methods of import manager objects - to get a string encoding a keyword index in that format\. - - 1. The plugin can expect that the package - __doctools::idx::export::plugin__ is present, as indicator that it was - invoked from a genuine plugin manager\. - - 1. The plugin can expect that a command named __IncludeFile__ is present, - with the signature - - - <a name='16'></a>__IncludeFile__ *currentfile* *path* - - This command has to be invoked by the plugin when it has to process an - included file, if the format has the concept of such\. An example of - such a format would be *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)*\. - - The plugin has to supply the following arguments - - * string *currentfile* - - The path of the file it is currently processing\. This may be the - empty string if no such is known\. - - * string *path* - - The path of the include file as specified in the include directive - being processed\. - - The result of the command will be a 5\-element list containing - - 1) A boolean flag indicating the success \(__True__\) or failure - \(__False__\) of the operation\. - - 1) In case of success the contents of the included file, and the - empty string otherwise\. - - 1) The resolved, i\.e\. absolute path of the included file, if - possible, or the unchanged *path* argument\. This is for display - in an error message, or as the *currentfile* argument of another - call to __IncludeFile__ should this file contain more files\. - - 1) In case of success an empty string, and for failure a code - indicating the reason for it, one of - - * notfound - - The specified file could not be found\. - - * notread - - The specified file was found, but not be read into memory\. - - 1) An empty string in case of success of a __notfound__ failure, - and an additional error message describing the reason for a - __notread__ error in more detail\. - - 1. A plugin has to provide one command, with the signature shown below\. - - - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration* - - Whenever an import manager of - __[doctools::idx](idx\_container\.md)__ has to parse input for an - index it will invoke this command\. - - * string *text* - - This argument will contain the text encoding the index per the - format the plugin is for\. - - * dictionary *configuration* - - This argument will contain the current configuration to apply to - the parsing, as a dictionary mapping from variable names to values\. - - The following configuration variables have a predefined meaning all - plugins have to obey, although they can ignore this information at - their discretion\. Any other other configuration variables - recognized by a plugin will be described in the manpage for that - plugin\. - - + user - - This variable is expected to contain the name of the user - owning the process invoking the plugin\. - - + format - - This variable is expected to contain the name of the format - whose plugin is invoked\. - - 1. A single usage cycle of a plugin consists of the invokations of the command - __[import](\.\./\.\./\.\./\.\./index\.md\#import)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# <a name='section5'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [json](\.\./\.\./\.\./\.\./index\.md\#json), -[keyword index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), -[url](\.\./\.\./\.\./\.\./index\.md\#url) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_import_json.md @@ -1,232 +0,0 @@ - -[//000000001]: # (doctools::idx::import::json \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::import::json\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::import::json \- JSON import plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON notation of keyword indices](#section3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require doctools::idx::import::json ?0\.2\.1? -package require doctools::idx::structure -package require json - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index import plugin for the parsing -of JSON markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::import](idx\_import\.md)__, the import manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::import](idx\_import\.md)__ and the import -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -import plugin API version 2\. - - - <a name='1'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration* - - This command takes the *string* and parses it as JSON markup encoding a - keyword index, in the context of the specified *configuration* \(a - dictionary\)\. The result of the command is the canonical serialization of - that keyword index, in the form specified in section [Keyword index - serialization format](#section4)\. - -# <a name='section3'></a>JSON notation of keyword indices - -The JSON format used for keyword indices is a direct translation of the -[Keyword index serialization format](#section4), mapping Tcl dictionaries -as JSON objects and Tcl lists as JSON arrays\. For example, the Tcl serialization - - doctools::idx { - label {Keyword Index} - keywords { - changelog {changelog.man cvs.man} - conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man} - cvs cvs.man - } - references { - apps/dtplite.man {manpage dtplite} - changelog.man {manpage doctools::changelog} - cvs.man {manpage doctools::cvs} - docidx.man {manpage doctools::idx} - doctoc.man {manpage doctools::toc} - doctools.man {manpage doctools} - mpexpand.man {manpage mpexpand} - } - title {} - } - -is equivalent to the JSON string - - { - "doctools::idx" : { - "label" : "Keyword Index", - "keywords" : { - "changelog" : ["changelog.man","cvs.man"], - "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"], - "cvs" : ["cvs.man"], - }, - "references" : { - "apps\/dtplite.man" : ["manpage","dtplite"], - "changelog.man" : ["manpage","doctools::changelog"], - "cvs.man" : ["manpage","doctools::cvs"], - "docidx.man" : ["manpage","doctools::idx"], - "doctoc.man" : ["manpage","doctools::toc"], - "doctools.man" : ["manpage","doctools"], - "mpexpand.man" : ["manpage","mpexpand"] - }, - "title" : "" - } - } - -# <a name='section4'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[index](\.\./\.\./\.\./\.\./index\.md\#index) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_introduction.md @@ -1,207 +0,0 @@ - -[//000000001]: # (doctools2idx\_introduction \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_introduction\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools2idx\_introduction\(n\) 2\.0 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools2idx\_introduction \- DocTools \- Keyword indices - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Related formats](#section2) - - - [Package Overview](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='description'></a>DESCRIPTION - -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* \(short for *documentation -indices*\) stands for a set of related, yet different, entities which are -working together for the easy creation and transformation of keyword indices for -documentation\. - -These are - - 1. A tcl based language for the semantic markup of a keyword index\. Markup is - represented by Tcl commands\. Beginners should start with the *[docidx - language introduction](\.\./doctools/docidx\_lang\_intro\.md)*\. The formal - specification is split over two documents, one dealing with the *[docidx - language syntax](\.\./doctools/docidx\_lang\_syntax\.md)*, the other a - *[docidx language command - reference](\.\./doctools/docidx\_lang\_cmdref\.md)*\. - - 1. A set of packages for the programmatic manipulation of keyword indices in - memory, and their conversion between various formats, reading and writing\. - The aforementioned markup language is one of the formats which can be both - read from and written to\. - - 1. The system for the conversion of indices is based on a plugin mechanism, - for this we have two APIs describing the interface between the packages - above and the import/export plugins\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the documentation process\. - - 1. A *writer* of documentation has to understand the markup language itself\. - A beginner to docidx should read the more informally written *[docidx - language introduction](\.\./doctools/docidx\_lang\_intro\.md)* first\. Having - digested this the formal *[docidx language - syntax](\.\./doctools/docidx\_lang\_syntax\.md)* specification should become - understandable\. A writer experienced with docidx may only need the - *[docidx language command - reference](\.\./doctools/docidx\_lang\_cmdref\.md)* from time to time to - refresh her memory\. - - While a document is written the __dtp__ application can be used to - validate it, and after completion it also performs the conversion into the - chosen system of visual markup, be it \*roff, HTML, plain text, wiki, etc\. - The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ application makes - internal use of docidx when handling directories of documentation, - automatically generating a proper keyword index for them\. - - 1. A *processor* of documentation written in the - *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup language has to know - which tools are available for use\. - - The main tool is the aforementioned __dtp__ application provided by - Tcllib\. The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ does not - expose docidx to the user\. At the bottom level, common to both - applications, however we find the three packages providing the basic - facilities to handle keyword indices, i\.e\. import from textual formats, - programmatic manipulation in memory, and export to textual formats\. These - are - - - __[doctools::idx](idx\_container\.md)__ - - Programmatic manipulation of keyword indices in memory\. - - - __[doctools::idx::import](idx\_import\.md)__ - - Import of keyword indices from various textual formats\. The set of - supported formats is extensible through plugin packages\. - - - __[doctools::idx::export](idx\_export\.md)__ - - Export of keyword indices to various textual formats\. The set of - supported formats is extensible through plugin packages\. - - See also section [Package Overview](#section3) for an overview of the - dependencies between these and other, supporting packages\. - - 1. At last, but not least, *plugin writers* have to understand the - interaction between the import and export packages and their plugins\. These - APIs are described in the documentation for the two relevant packages, i\.e\. - - - __[doctools::idx::import](idx\_import\.md)__ - - - __[doctools::idx::export](idx\_export\.md)__ - -# <a name='section2'></a>Related formats - -The docidx format does not stand alone, it has two companion formats\. These are -called *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* and -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)*, and they are intended for the -markup of *tables of contents*, and of general documentation, respectively\. -They are described in their own sets of documents, starting at the *DocTools \- -Tables Of Contents* and the *DocTools \- General*, respectively\. - -# <a name='section3'></a>Package Overview - - ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~ - ~~ | ~~ - doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import - | | | - +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ - | | | | | | | | | - struct::map = | | | = doctools::include struct::map fileutil::paths - | | | | | - doctools::idx::export::<*> | | | doctools::idx::import::<*> - docidx | | | docidx, json - json | | | | \ - html | | | doctools::idx::parse \ - nroff | | | | \ - wiki | | | +---------------+ json - text | | | | | - doctools::idx::structure | - | - +-------+---------------+ - | | - doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat - | | - doctools::text doctools::nroff::man_macros = - | - doctools::msgcat::idx::<*> - c, en, de, fr - (fr == en for now) - ~~ Interoperable objects, without actual package dependencies - -- Package dependency, higher requires lower package - = Dynamic dependency through plugin system - <*> Multiple packages following the given form of naming. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[docidx\_intro](\.\./doctools/docidx\_intro\.md), -[doctoc\_intro](\.\./doctools/doctoc\_intro\.md), -[doctools](\.\./doctools/doctools\.md), doctools2doc\_introduction, -[doctools2toc\_introduction](\.\./doctools2toc/toc\_introduction\.md), -[doctools\_lang\_cmdref](\.\./doctools/doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](\.\./doctools/doctools\_lang\_faq\.md), -[doctools\_lang\_intro](\.\./doctools/doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](\.\./doctools/doctools\_lang\_syntax\.md), -[doctools\_plugin\_apiref](\.\./doctools/doctools\_plugin\_apiref\.md) - -# <a name='keywords'></a>KEYWORDS - -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[index](\.\./\.\./\.\./\.\./index\.md\#index), [keyword -index](\.\./\.\./\.\./\.\./index\.md\#keyword\_index), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_c.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_c.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_c.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_c.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::idx::c \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::idx::c\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::idx::c \- Message catalog for the docidx parser \(C\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::idx::c ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::idx::c__ is a support module providing the C -language message catalog for the docidx parser in the doctools system version 2\. -As such it is an internal package a regular user \(developer\) should not be in -direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[C](\.\./\.\./\.\./\.\./index\.md\#c), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_de.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_de.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_de.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_de.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::idx::de \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::idx::de\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::idx::de \- Message catalog for the docidx parser \(DE\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::idx::de ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::idx::de__ is a support module providing the -DE \(german\) language message catalog for the docidx parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[DE](\.\./\.\./\.\./\.\./index\.md\#de), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_en.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_en.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_en.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_en.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::idx::en \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::idx::en\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::idx::en \- Message catalog for the docidx parser \(EN\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::idx::en ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::idx::en__ is a support module providing the -EN \(english\) language message catalog for the docidx parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[EN](\.\./\.\./\.\./\.\./index\.md\#en), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_fr.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_fr.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_fr.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_msgcat_fr.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::idx::fr \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::idx::fr\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::idx::fr \- Message catalog for the docidx parser \(FR\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::idx::fr ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::idx::fr__ is a support module providing the -FR \(french\) language message catalog for the docidx parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[FR](\.\./\.\./\.\./\.\./index\.md\#fr), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_parse.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_parse.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_parse.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_parse.md @@ -1,308 +0,0 @@ - -[//000000001]: # (doctools::idx::parse \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_parse\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::parse\(n\) 1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::parse \- Parsing text in docidx format - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Parse errors](#section3) - - - [\[docidx\] notation of keyword indices](#section4) - - - [Keyword index serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::idx::parse ?0\.1? -package require Tcl 8\.4 -package require doctools::idx::structure -package require doctools::msgcat -package require doctools::tcl::parse -package require fileutil -package require logger -package require snit -package require struct::list -package require struct::stack - -[__::doctools::idx::parse__ __text__ *text*](#1) -[__::doctools::idx::parse__ __file__ *path*](#2) -[__::doctools::idx::parse__ __includes__](#3) -[__::doctools::idx::parse__ __include add__ *path*](#4) -[__::doctools::idx::parse__ __include remove__ *path*](#5) -[__::doctools::idx::parse__ __include clear__](#6) -[__::doctools::idx::parse__ __vars__](#7) -[__::doctools::idx::parse__ __var set__ *name* *value*](#8) -[__::doctools::idx::parse__ __var unset__ *name*](#9) -[__::doctools::idx::parse__ __var clear__ ?*pattern*?](#10) - -# <a name='description'></a>DESCRIPTION - -This package provides commands to parse text written in the -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup language and convert it -into the canonical serialization of the keyword index encoded in the text\. See -the section [Keyword index serialization format](#section5) for -specification of their format\. - -This is an internal package of doctools, for use by the higher level packages -handling *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* documents\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::doctools::idx::parse__ __text__ *text* - - The command takes the string contained in *text* and parses it under the - assumption that it contains a document written using the - *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup language\. An error is - thrown if this assumption is found to be false\. The format of these errors - is described in section [Parse errors](#section3)\. - - When successful the command returns the canonical serialization of the - keyword index which was encoded in the text\. See the section [Keyword index - serialization format](#section5) for specification of that format\. - - - <a name='2'></a>__::doctools::idx::parse__ __file__ *path* - - The same as __text__, except that the text to parse is read from the - file specified by *path*\. - - - <a name='3'></a>__::doctools::idx::parse__ __includes__ - - This method returns the current list of search paths used when looking for - include files\. - - - <a name='4'></a>__::doctools::idx::parse__ __include add__ *path* - - This method adds the *path* to the list of paths searched when looking for - an include file\. The call is ignored if the path is already in the list of - paths\. The method returns the empty string as its result\. - - - <a name='5'></a>__::doctools::idx::parse__ __include remove__ *path* - - This method removes the *path* from the list of paths searched when - looking for an include file\. The call is ignored if the path is not - contained in the list of paths\. The method returns the empty string as its - result\. - - - <a name='6'></a>__::doctools::idx::parse__ __include clear__ - - This method clears the list of search paths for include files\. - - - <a name='7'></a>__::doctools::idx::parse__ __vars__ - - This method returns a dictionary containing the current set of predefined - variables known to the __vset__ markup command during processing\. - - - <a name='8'></a>__::doctools::idx::parse__ __var set__ *name* *value* - - This method adds the variable *name* to the set of predefined variables - known to the __vset__ markup command during processing, and gives it the - specified *value*\. The method returns the empty string as its result\. - - - <a name='9'></a>__::doctools::idx::parse__ __var unset__ *name* - - This method removes the variable *name* from the set of predefined - variables known to the __vset__ markup command during processing\. The - method returns the empty string as its result\. - - - <a name='10'></a>__::doctools::idx::parse__ __var clear__ ?*pattern*? - - This method removes all variables matching the *pattern* from the set of - predefined variables known to the __vset__ markup command during - processing\. The method returns the empty string as its result\. - - The pattern matching is done with __string match__, and the default - pattern used when none is specified, is __\*__\. - -# <a name='section3'></a>Parse errors - -The format of the parse error messages thrown when encountering violations of -the *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup syntax is human -readable and not intended for processing by machines\. As such it is not -documented\. - -*However*, the errorCode attached to the message is machine\-readable and has -the following format: - - 1. The error code will be a list, each element describing a single error found - in the input\. The list has at least one element, possibly more\. - - 1. Each error element will be a list containing six strings describing an - error in detail\. The strings will be - - 1) The path of the file the error occurred in\. This may be empty\. - - 1) The range of the token the error was found at\. This range is a - two\-element list containing the offset of the first and last character - in the range, counted from the beginning of the input \(file\)\. Offsets - are counted from zero\. - - 1) The line the first character after the error is on\. Lines are counted - from one\. - - 1) The column the first character after the error is at\. Columns are - counted from zero\. - - 1) The message code of the error\. This value can be used as argument to - __msgcat::mc__ to obtain a localized error message, assuming that - the application had a suitable call of __doctools::msgcat::init__ - to initialize the necessary message catalogs \(See package - __[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__\)\. - - 1) A list of details for the error, like the markup command involved\. In - the case of message code __docidx/include/syntax__ this value is - the set of errors found in the included file, using the format - described here\. - -# <a name='section4'></a>\[docidx\] notation of keyword indices - -The docidx format for keyword indices, also called the *docidx markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[docidx language introduction](\.\./doctools/docidx\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[docidx language syntax](\.\./doctools/docidx\_lang\_syntax\.md)* and - - 1. *[docidx language command - reference](\.\./doctools/docidx\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# <a name='section5'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[lexer](\.\./\.\./\.\./\.\./index\.md\#lexer), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/idx_structure.md Index: embedded/md/tcllib/files/modules/doctools2idx/idx_structure.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/idx_structure.md +++ embedded/md/tcllib/files/modules/doctools2idx/idx_structure.md @@ -1,234 +0,0 @@ - -[//000000001]: # (doctools::idx::structure \- Documentation tools) -[//000000002]: # (Generated from file 'idx\_structure\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::structure\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::structure \- Docidx serialization utilities - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Keyword index serialization format](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::idx::structure ?0\.1? -package require Tcl 8\.4 -package require logger -package require snit - -[__::doctools::idx::structure__ __verify__ *serial* ?*canonvar*?](#1) -[__::doctools::idx::structure__ __verify\-as\-canonical__ *serial*](#2) -[__::doctools::idx::structure__ __canonicalize__ *serial*](#3) -[__::doctools::idx::structure__ __print__ *serial*](#4) -[__::doctools::idx::structure__ __merge__ *seriala* *serialb*](#5) - -# <a name='description'></a>DESCRIPTION - -This package provides commands to work with the serializations of keyword -indices as managed by the doctools system v2, and specified in section [Keyword -index serialization format](#section3)\. - -This is an internal package of doctools, for use by the higher level packages -handling keyword indices and their conversion into and out of various other -formats, like documents written using -*[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* markup\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::doctools::idx::structure__ __verify__ *serial* ?*canonvar*? - - This command verifies that the content of *serial* is a valid *regular* - serialization of a keyword index and will throw an error if that is not the - case\. The result of the command is the empty string\. - - If the argument *canonvar* is specified it is interpreted as the name of a - variable in the calling context\. This variable will be written to if and - only if *serial* is a valid regular serialization\. Its value will be a - boolean, with __True__ indicating that the serialization is not only - valid, but also *canonical*\. __False__ will be written for a valid, - but non\-canonical serialization\. - - For the specification of regular and canonical keyword index serializations - see the section [Keyword index serialization format](#section3)\. - - - <a name='2'></a>__::doctools::idx::structure__ __verify\-as\-canonical__ *serial* - - This command verifies that the content of *serial* is a valid - *canonical* serialization of a keyword index and will throw an error if - that is not the case\. The result of the command is the empty string\. - - For the specification of canonical keyword index serializations see the - section [Keyword index serialization format](#section3)\. - - - <a name='3'></a>__::doctools::idx::structure__ __canonicalize__ *serial* - - This command assumes that the content of *serial* is a valid *regular* - serialization of a keyword index and will throw an error if that is not the - case\. - - It will then convert the input into the *canonical* serialization of the - contained keyword index and return it as its result\. If the input is already - canonical it will be returned unchanged\. - - For the specification of regular and canonical keyword index serializations - see the section [Keyword index serialization format](#section3)\. - - - <a name='4'></a>__::doctools::idx::structure__ __print__ *serial* - - This command assumes that the argument *serial* contains a valid regular - serialization of a keyword index and returns a string containing that index - in a human readable form\. - - The exact format of this form is not specified and cannot be relied on for - parsing or other machine\-based activities\. - - For the specification of regular keyword index serializations see the - section [Keyword index serialization format](#section3)\. - - - <a name='5'></a>__::doctools::idx::structure__ __merge__ *seriala* *serialb* - - This command accepts the regular serializations of two keyword indices and - uses them to create their union\. The result of the command is the canonical - serialization of this unified keyword index\. - - Title and label of the resulting index are taken from the index contained in - *serialb*\. The set of keys, references and their connections is the union - of the set of keys and references of the two inputs\. - - For the specification of regular and canonical keyword index serializations - see the section [Keyword index serialization format](#section3)\. - -# <a name='section3'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md Index: embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md +++ embedded/md/tcllib/files/modules/doctools2idx/import_docidx.md @@ -1,211 +0,0 @@ - -[//000000001]: # (doctools::idx::import::docidx \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::idx::import::docidx\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::idx::import::docidx \- docidx import plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [\[docidx\] notation of keyword indices](#section3) - - - [Keyword index serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require doctools::idx::import::docidx ?0\.2\.1? -package require doctools::idx::parse -package require doctools::idx::structure -package require doctools::msgcat -package require doctools::tcl::parse -package require fileutil -package require logger -package require snit -package require struct::list -package require struct::set -package require struct::stack -package require struct::tree -package require treeql - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools keyword index import plugin for the parsing -of docidx markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling keyword indices, especially -__[doctools::idx::import](idx\_import\.md)__, the import manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::idx::import](idx\_import\.md)__ and the import -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the docidx -import plugin API version 2\. - - - <a name='1'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration* - - This command takes the *string* and parses it as docidx markup encoding a - keyword index, in the context of the specified *configuration* \(a - dictionary\)\. The result of the command is the canonical serialization of - that keyword index, in the form specified in section [Keyword index - serialization format](#section4)\. - -# <a name='section3'></a>\[docidx\] notation of keyword indices - -The docidx format for keyword indices, also called the *docidx markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[docidx language introduction](\.\./doctools/docidx\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[docidx language syntax](\.\./doctools/docidx\_lang\_syntax\.md)* and - - 1. *[docidx language command - reference](\.\./doctools/docidx\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# <a name='section4'></a>Keyword index serialization format - -Here we specify the format used by the doctools v2 packages to serialize keyword -indices as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -keyword index may have more than one regular serialization only exactly one of -them will be *canonical*\. - - - regular serialization - - 1. An index serialization is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::idx__, and its - value\. This value holds the contents of the index\. - - 1. The contents of the index are a Tcl dictionary holding the title of the - index, a label, and the keywords and references\. The relevant keys and - their values are - - * __title__ - - The value is a string containing the title of the index\. - - * __label__ - - The value is a string containing a label for the index\. - - * __keywords__ - - The value is a Tcl dictionary, using the keywords known to the - index as keys\. The associated values are lists containing the - identifiers of the references associated with that particular - keyword\. - - Any reference identifier used in these lists has to exist as a key - in the __references__ dictionary, see the next item for its - definition\. - - * __references__ - - The value is a Tcl dictionary, using the identifiers for the - references known to the index as keys\. The associated values are - 2\-element lists containing the type and label of the reference, in - this order\. - - Any key here has to be associated with at least one keyword, i\.e\. - occur in at least one of the reference lists which are the values - in the __keywords__ dictionary, see previous item for its - definition\. - - 1. The *[type](\.\./\.\./\.\./\.\./index\.md\#type)* of a reference can be one - of two values, - - * __manpage__ - - The identifier of the reference is interpreted as symbolic file - name, referring to one of the documents the index was made for\. - - * __url__ - - The identifier of the reference is interpreted as an url, referring - to some external location, like a website, etc\. - - - canonical serialization - - The canonical serialization of a keyword index has the format as specified - in the previous item, and then additionally satisfies the constraints below, - which make it unique among all the possible serializations of the keyword - index\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The references listed for each keyword of the index, if any, are listed - in ascending dictionary order of their *labels*, as generated by - Tcl's builtin command __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[index](\.\./\.\./\.\./\.\./index\.md\#index) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md Index: embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md +++ embedded/md/tcllib/files/modules/doctools2toc/export_doctoc.md @@ -1,281 +0,0 @@ - -[//000000001]: # (doctools::toc::export::doctoc \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::doctoc \- doctoc export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [\[doctoc\] notation of tables of contents](#section3) - - - [Configuration](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::doctoc ?0\.2\.1? - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of doctoc markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section5), and - contained in *serial*, the *configuration*, a dictionary, and generates - doctoc markup encoding the table\. The created string is then returned as the - result of the command\. - -# <a name='section3'></a>\[doctoc\] notation of tables of contents - -The doctoc format for tables of contents, also called the *doctoc markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[doctoc language introduction](\.\./doctools/doctoc\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[doctoc language syntax](\.\./doctools/doctoc\_lang\_syntax\.md)* and - - 1. *[doctoc language command - reference](\.\./doctools/doctoc\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# <a name='section4'></a>Configuration - -The doctoc export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the table - of contents came from\. This variable may not be set or contain the empty - string\. The plugin puts this information, if defined, i\.e\. set and not the - empty string, into the provenance comment at the beginning of the generated - document\. - - - boolean *newlines* - - If this flag is set the plugin will break the generated doctoc code across - lines, with each markup command on a separate line\. - - If this flag is not set \(the default\), the whole document will be written on - a single line, with minimum spacing between all elements\. - - - boolean *indented* - - If this flag is set the plugin will indent the markup commands according to - the structure of tables of contents\. To make this work this also implies - that __newlines__ is set\. This effect is independent of the value for - __aligned__ however\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __newlines__, and no indenting is done\. - - - boolean *aligned* - - If this flag is set the generator ensures that the arguments for the - __item__ commands in a division are aligned vertically for a nice table - effect\. To make this work this also implies that __newlines__ is set\. - This effect is independent of the value for __indented__ however\. - - If this flag is not set \(the default\), the output is formatted as per the - values of __newlines__ and __indented__, and no alignment is done\. - -*Note* that this plugin ignores the standard configuration variables -__format__, and __map__, and their values\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md Index: embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md +++ embedded/md/tcllib/files/modules/doctools2toc/import_doctoc.md @@ -1,240 +0,0 @@ - -[//000000001]: # (doctools::toc::import::doctoc \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::import::doctoc\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::import::doctoc \- doctoc import plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [\[doctoc\] notation of tables of contents](#section3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require doctools::toc::import::doctoc ?0\.2\.1? -package require doctools::toc::parse -package require doctools::toc::structure -package require doctools::msgcat -package require doctools::tcl::parse -package require fileutil -package require logger -package require snit -package require struct::list -package require struct::set -package require struct::stack -package require struct::tree -package require treeql - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents import plugin for the -parsing of doctoc markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::import](toc\_import\.md)__, the import manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::import](toc\_import\.md)__ and the import -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -import plugin API version 2\. - - - <a name='1'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration* - - This command takes the *string* and parses it as doctoc markup encoding a - table of contents, in the context of the specified *configuration* \(a - dictionary\)\. The result of the command is the canonical serialization of - that table of contents, in the form specified in section [ToC serialization - format](#section4)\. - -# <a name='section3'></a>\[doctoc\] notation of tables of contents - -The doctoc format for tables of contents, also called the *doctoc markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[doctoc language introduction](\.\./doctools/doctoc\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[doctoc language syntax](\.\./doctools/doctoc\_lang\_syntax\.md)* and - - 1. *[doctoc language command - reference](\.\./doctools/doctoc\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[import](\.\./\.\./\.\./\.\./index\.md\#import), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_container.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_container.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_container.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_container.md @@ -1,517 +0,0 @@ - -[//000000001]: # (doctools::toc \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_container\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc\(n\) 2 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc \- Holding tables of contents - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::toc ?2? -package require Tcl 8\.4 -package require doctools::toc::structure -package require struct::tree -package require snit - -[__::doctools::toc__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __\+ reference__ *id* *label* *docid* *desc*](#4) -[*objectName* __\+ division__ *id* *label* ?*docid*?](#5) -[*objectName* __remove__ *id*](#6) -[*objectName* __up__ *id*](#7) -[*objectName* __next__ *id*](#8) -[*objectName* __prev__ *id*](#9) -[*objectName* __child__ *id* *label* ?*\.\.\.*?](#10) -[*objectName* __element__ ?*\.\.\.*?](#11) -[*objectName* __children__ *id*](#12) -[*objectName* __type__ *id*](#13) -[*objectName* __full\-label__ *id*](#14) -[*objectName* __elabel__ *id* ?*newlabel*?](#15) -[*objectName* __description__ *id* ?*newdesc*?](#16) -[*objectName* __document__ *id* ?*newdocid*?](#17) -[*objectName* __title__](#18) -[*objectName* __title__ *text*](#19) -[*objectName* __label__](#20) -[*objectName* __label__ *text*](#21) -[*objectName* __importer__](#22) -[*objectName* __importer__ *object*](#23) -[*objectName* __exporter__](#24) -[*objectName* __exporter__ *object*](#25) -[*objectName* __deserialize =__ *data* ?*format*?](#26) -[*objectName* __deserialize \+=__ *data* ?*format*?](#27) -[*objectName* __serialize__ ?*format*?](#28) - -# <a name='description'></a>DESCRIPTION - -This package provides a class to contain and programmatically manipulate tables -of contents\. - -This is one of the three public pillars the management of tables of contents -resides on\. The other two pillars are - - 1. *[Exporting tables of contents](toc\_export\.md)*, and - - 1. *Importing tables of contents* - -For information about the [Concepts](#section2) of tables of contents, and -their parts, see the same\-named section\. For information about the data -structure which is used to encode tables of contents as values see the section -[ToC serialization format](#section4)\. This is the only format directly -known to this class\. Conversions from and to any other format are handled by -export and import manager objects\. These may be attached to a container, but do -not have to be, it is merely a convenience\. - -# <a name='section2'></a>Concepts - - 1. A *[table of contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents)* - consists of a \(possibly empty\) list of *elements*\. - - 1. Each element in the list is identified by its label\. - - 1. Each element is either a - *[reference](\.\./\.\./\.\./\.\./index\.md\#reference)*, or a *division*\. - - 1. Each reference has an associated document, identified by a symbolic id, and - a textual description\. - - 1. Each division may have an associated document, identified by a symbolic id\. - - 1. Each division consists consists of a \(possibly empty\) list of *elements*, - with each element following the rules as specified in item 2 and above\. - -A few notes - - 1. The above rules span up a tree of elements, with references as the leaf - nodes, and divisions as the inner nodes, and each element representing an - entry in the whole table of contents\. - - 1. The identifying labels of any element E are unique within their division - \(or toc\), and the full label of any element E is the list of labels for all - nodes on the unique path from the root of the tree to E, including E\. - -# <a name='section3'></a>API - -## <a name='subsection1'></a>Package commands - - - <a name='1'></a>__::doctools::toc__ *objectName* - - This command creates a new container object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## <a name='subsection2'></a>Object command - -All objects created by the __::doctools::toc__ command have the following -general form: - - - <a name='2'></a>__objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## <a name='subsection3'></a>Object methods - - - <a name='3'></a>*objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - <a name='4'></a>*objectName* __\+ reference__ *id* *label* *docid* *desc* - - This method adds a new reference element to the table of contents, under the - element specified via its handle *id*\. This parent element has to be a - division element, or the root\. An error is thrown otherwise\. The new element - will be externally identified by its *label*, which has to be be unique - within the parent element\. An error is thrown otherwise\. - - As a reference element it will refer to a document identified by the - symbolic *docid*\. This reference must not be the empty string, an error is - thrown otherwise\. Beyond the label the element also has a longer descriptive - string, supplied via *desc*\. - - The result of the method is the handle \(id\) of the new element\. - - - <a name='5'></a>*objectName* __\+ division__ *id* *label* ?*docid*? - - This method adds a new division element to the table of contents, under the - element specified via its handle *id*\. This parent element has to be a - division element, or the root\. An error is thrown otherwise\. The new element - will be externally identified by its *label*, which has to be be unique - within the parent element\. An error is thrown otherwise\. - - As a division element it is can refer to a document, identified by the - symbolic *docid*, but may choose not to\. - - The result of the method is the handle \(id\) of the new element\. - - - <a name='6'></a>*objectName* __remove__ *id* - - This method removes the element identified by the handle *id* from the - table of contents\. If the element is a division all of its children, if any, - are removed as well\. The root element/division of the table of contents - cannot be removed however, only its children\. - - The result of the method is the empty string\. - - - <a name='7'></a>*objectName* __up__ *id* - - This method returns the handle of the parent for the element identified by - its handle *id*, or the empty string if *id* referred to the root - element\. - - - <a name='8'></a>*objectName* __next__ *id* - - This method returns the handle of the right sibling for the element - identified by its handle *id*, or the handle of the parent if the element - has no right sibling, or the empty string if *id* referred to the root - element\. - - - <a name='9'></a>*objectName* __prev__ *id* - - This method returns the handle of the left sibling for the element - identified by its handle *id*, or the handle of the parent if the element - has no left sibling, or the empty string if *id* referred to the root - element\. - - - <a name='10'></a>*objectName* __child__ *id* *label* ?*\.\.\.*? - - This method returns the handle of a child of the element identified by its - handle *id*\. The child itself is identified by a series of labels\. - - - <a name='11'></a>*objectName* __element__ ?*\.\.\.*? - - This method returns the handle of the element identified by a series of - labels, starting from the root of the table of contents\. The series of - labels is allowed to be empty, in which case the handle of the root element - is returned\. - - - <a name='12'></a>*objectName* __children__ *id* - - This method returns a list containing the handles of all children of the - element identified by the handle *id*, from first to last, in that order\. - - - <a name='13'></a>*objectName* __type__ *id* - - This method returns the type of the element, either __reference__, or - __division__\. - - - <a name='14'></a>*objectName* __full\-label__ *id* - - This method is the complement of the method __element__, converting the - handle *id* of an element into a list of labels full identifying the - element within the whole table of contents\. - - - <a name='15'></a>*objectName* __elabel__ *id* ?*newlabel*? - - This method queries and/or changes the label of the element identified by - the handle *id*\. If the argument *newlabel* is present then the label is - changed to that value\. Regardless of this, the result of the method is the - current value of the label\. - - If the label is changed the new label has to be unique within the containing - division, or an error is thrown\. - - Further, of the *id* refers to the root element of the table of contents, - then using this method is equivalent to using the method *label*, i\.e\. it - is accessing the global label for the whole table\. - - - <a name='16'></a>*objectName* __description__ *id* ?*newdesc*? - - This method queries and/or changes the description of the element identified - by the handle *id*\. If the argument *newdesc* is present then the - description is changed to that value\. Regardless of this, the result of the - method is the current value of the description\. - - The element this method operates on has to be a reference element, or an - error will be thrown\. - - - <a name='17'></a>*objectName* __document__ *id* ?*newdocid*? - - This method queries and/or changes the document reference of the element - identified by the handle *id*\. If the argument *newdocid* is present - then the description is changed to that value\. Regardless of this, the - result of the method is the current value of the document reference\. - - Setting the reference to the empty string means unsetting it, and is allowed - only for division elements\. Conversely, if the result is the empty string - then the element has no document reference, and this can happen only for - division elements\. - - - <a name='18'></a>*objectName* __title__ - - Returns the currently defined title of the table of contents\. - - - <a name='19'></a>*objectName* __title__ *text* - - Sets the title of the table of contents to *text*, and returns it as the - result of the command\. - - - <a name='20'></a>*objectName* __label__ - - Returns the currently defined label of the table of contents\. - - - <a name='21'></a>*objectName* __label__ *text* - - Sets the label of the table of contents to *text*, and returns it as the - result of the command\. - - - <a name='22'></a>*objectName* __importer__ - - Returns the import manager object currently attached to the container, if - any\. - - - <a name='23'></a>*objectName* __importer__ *object* - - Attaches the *object* as import manager to the container, and returns it - as the result of the command\. Note that the *object* is *not* put into - ownership of the container\. I\.e\., destruction of the container will *not* - destroy the *object*\. - - It is expected that *object* provides a method named __import text__ - which takes a text and a format name, and returns the canonical - serialization of the table of contents contained in the text, assuming the - given format\. - - - <a name='24'></a>*objectName* __exporter__ - - Returns the export manager object currently attached to the container, if - any\. - - - <a name='25'></a>*objectName* __exporter__ *object* - - Attaches the *object* as export manager to the container, and returns it - as the result of the command\. Note that the *object* is *not* put into - ownership of the container\. I\.e\., destruction of the container will *not* - destroy the *object*\. - - It is expected that *object* provides a method named __export object__ - which takes the container and a format name, and returns a text encoding - table of contents stored in the container, in the given format\. It is - further expected that the *object* will use the container's method - __serialize__ to obtain the serialization of the table of contents from - which to generate the text\. - - - <a name='26'></a>*objectName* __deserialize =__ *data* ?*format*? - - This method replaces the contents of the table object with the table - contained in the *data*\. If no *format* was specified it is assumed to - be the regular serialization of a table of contents\. - - Otherwise the object will use the attached import manager to convert the - data from the specified format to a serialization it can handle\. In that - case an error will be thrown if the container has no import manager attached - to it\. - - The result of the method is the empty string\. - - - <a name='27'></a>*objectName* __deserialize \+=__ *data* ?*format*? - - This method behaves like __deserialize =__ in its essentials, except - that it merges the table of contents in the *data* to its contents instead - of replacing it\. The method will throw an error if merging is not possible, - i\.e\. would produce an invalid table\. The existing content is left unchanged - in that case\. - - The result of the method is the empty string\. - - - <a name='28'></a>*objectName* __serialize__ ?*format*? - - This method returns the table of contents contained in the object\. If no - *format* is not specified the returned result is the canonical - serialization of its contents\. - - Otherwise the object will use the attached export manager to convert the - data to the specified format\. In that case an error will be thrown if the - container has no export manager attached to it\. - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), [doctoc -markup](\.\./\.\./\.\./\.\./index\.md\#doctoc\_markup), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[generation](\.\./\.\./\.\./\.\./index\.md\#generation), -[json](\.\./\.\./\.\./\.\./index\.md\#json), [latex](\.\./\.\./\.\./\.\./index\.md\#latex), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), -[table](\.\./\.\./\.\./\.\./index\.md\#table), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), [tcler's -wiki](\.\./\.\./\.\./\.\./index\.md\#tcler\_s\_wiki), -[text](\.\./\.\./\.\./\.\./index\.md\#text), [wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export.md @@ -1,486 +0,0 @@ - -[//000000001]: # (doctools::toc::export \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_export\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export \- Exporting tables of contents - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Export plugin API v2 reference](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::toc::export ?0\.2\.1? -package require Tcl 8\.4 -package require struct::map -package require doctools::toc::structure -package require snit -package require pluginmgr - -[__::doctools::toc::export__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __export serial__ *serial* ?*format*?](#4) -[*objectName* __export object__ *object* ?*format*?](#5) -[*objectName* __config names__](#6) -[*objectName* __config get__](#7) -[*objectName* __config set__ *name* ?*value*?](#8) -[*objectName* __config unset__ *pattern*\.\.\.](#9) -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#10) - -# <a name='description'></a>DESCRIPTION - -This package provides a class to manage the plugins for the export of tables of -contents to other formats, i\.e\. their conversion to, for example -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)*, -*[HTML](\.\./\.\./\.\./\.\./index\.md\#html)*, etc\. - -This is one of the three public pillars the management of tables of contents -resides on\. The other two pillars are - - 1. *Importing tables of contents*, and - - 1. *[Holding tables of contents](toc\_container\.md)* - -For information about the [Concepts](#section2) of tables of contents, and -their parts, see the same\-named section\. For information about the data -structure which is the major input to the manager objects provided by this -package see the section [ToC serialization format](#section5)\. - -The plugin system of our class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __DOCTOOLS\_TOC\_EXPORT\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_TOC\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_PLUGINS__, - - 1. the path "~/\.doctools/toc/export/plugin" - - 1. the path "~/\.doctools/toc/plugin" - - 1. the path "~/\.doctools/plugin" - - 1. the path "~/\.doctools/toc/export/plugins" - - 1. the path "~/\.doctools/toc/plugins" - - 1. the path "~/\.doctools/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\TOC\\EXPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\TOC\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" - -The last three are used only when the package is run on a machine using -Windows\(tm\) operating system\. - -The whole system is delivered with six predefined export plugins, namely - - - doctoc - - See *[doctoc export plugin](export\_doctoc\.md)* for details\. - - - html - - See *html export plugin* for details\. - - - json - - See *json export plugin* for details\. - - - nroff - - See *[nroff export plugin](toc\_export\_nroff\.md)* for details\. - - - text - - See *text export plugin* for details\. - - - wiki - - See *[wiki export plugin](toc\_export\_wiki\.md)* for details\. - -Readers wishing to write their own export plugin for some format, i\.e\. *plugin -writer*s reading and understanding the section containing the [Export plugin -API v2 reference](#section4) is an absolute necessity, as it specifies the -interaction between this package and its plugins in detail\. - -# <a name='section2'></a>Concepts - - 1. A *[table of contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents)* - consists of a \(possibly empty\) list of *elements*\. - - 1. Each element in the list is identified by its label\. - - 1. Each element is either a - *[reference](\.\./\.\./\.\./\.\./index\.md\#reference)*, or a *division*\. - - 1. Each reference has an associated document, identified by a symbolic id, and - a textual description\. - - 1. Each division may have an associated document, identified by a symbolic id\. - - 1. Each division consists consists of a \(possibly empty\) list of *elements*, - with each element following the rules as specified in item 2 and above\. - -A few notes - - 1. The above rules span up a tree of elements, with references as the leaf - nodes, and divisions as the inner nodes, and each element representing an - entry in the whole table of contents\. - - 1. The identifying labels of any element E are unique within their division - \(or toc\), and the full label of any element E is the list of labels for all - nodes on the unique path from the root of the tree to E, including E\. - -# <a name='section3'></a>API - -## <a name='subsection1'></a>Package commands - - - <a name='1'></a>__::doctools::toc::export__ *objectName* - - This command creates a new export manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## <a name='subsection2'></a>Object command - -All objects created by the __::doctools::toc::export__ command have the -following general form: - - - <a name='2'></a>__objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## <a name='subsection3'></a>Object methods - - - <a name='3'></a>*objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - <a name='4'></a>*objectName* __export serial__ *serial* ?*format*? - - This method takes the canonical serialization of a table of contents stored - in *serial* and converts it to the specified *format*, using the export - plugin for the format\. An error is thrown if no plugin could be found for - the format\. The string generated by the conversion process is returned as - the result of this method\. - - If no format is specified the method defaults to __doctoc__\. - - The specification of what a *canonical* serialization is can be found in - the section [ToC serialization format](#section5)\. - - The plugin has to conform to the interface specified in section [Export - plugin API v2 reference](#section4)\. - - - <a name='5'></a>*objectName* __export object__ *object* ?*format*? - - This method is a convenient wrapper around the __export serial__ method - described by the previous item\. It expects that *object* is an object - command supporting a __serialize__ method returning the canonical - serialization of a table of contents\. It invokes that method, feeds the - result into __export serial__ and returns the resulting string as its - own result\. - - - <a name='6'></a>*objectName* __config names__ - - This method returns a list containing the names of all configuration - variables currently known to the object\. - - - <a name='7'></a>*objectName* __config get__ - - This method returns a dictionary containing the names and values of all - configuration variables currently known to the object\. - - - <a name='8'></a>*objectName* __config set__ *name* ?*value*? - - This method sets the configuration variable *name* to the specified - *value* and returns the new value of the variable\. - - If no value is specified it simply returns the current value, without - changing it\. - - Note that while the user can set the predefined configuration variables - __user__ and __format__ doing so will have no effect, these values - will be internally overridden when invoking an import plugin\. - - - <a name='9'></a>*objectName* __config unset__ *pattern*\.\.\. - - This method unsets all configuration variables matching the specified glob - *pattern*s\. If no pattern is specified it will unset all currently defined - configuration variables\. - -# <a name='section4'></a>Export plugin API v2 reference - -Plugins are what this package uses to manage the support for any output format -beyond the [ToC serialization format](#section5)\. Here we specify the API -the objects created by this package use to interact with their plugins\. - -A plugin for this package has to follow the rules listed below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form - doctools::toc::export::__FOO__, where __FOO__ is the name of the - format the plugin will generate output for\. This name is also the argument - to provide to the various __export__ methods of export manager objects - to get a string encoding a table of contents in that format\. - - 1. The plugin can expect that the package - __doctools::toc::export::plugin__ is present, as indicator that it was - invoked from a genuine plugin manager\. - - 1. A plugin has to provide one command, with the signature shown below\. - - - <a name='10'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - Whenever an export manager of - __[doctools::toc](\.\./doctools/doctoc\.md)__ has to generate - output for a table of contents it will invoke this command\. - - * string *serial* - - This argument will contain the *canonical* serialization of the - table of contents for which to generate the output\. The - specification of what a *canonical* serialization is can be found - in the section [ToC serialization format](#section5)\. - - * dictionary *configuration* - - This argument will contain the current configuration to apply to - the generation, as a dictionary mapping from variable names to - values\. - - The following configuration variables have a predefined meaning all - plugins have to obey, although they can ignore this information at - their discretion\. Any other other configuration variables - recognized by a plugin will be described in the manpage for that - plugin\. - - + user - - This variable is expected to contain the name of the user - owning the process invoking the plugin\. - - + format - - This variable is expected to contain the name of the format - whose plugin is invoked\. - - + file - - This variable, if defined by the user of the table object is - expected to contain the name of the input file for which the - plugin is generating its output for\. - - + map - - This variable, if defined by the user of the table object is - expected to contain a dictionary mapping from symbolic document - ids used in the table entries to actual paths \(or urls\)\. A - plugin has to be able to handle the possibility that a document - id is without entry in this mapping\. - - 1. A single usage cycle of a plugin consists of the invokations of the command - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[generation](\.\./\.\./\.\./\.\./index\.md\#generation), -[json](\.\./\.\./\.\./\.\./index\.md\#json), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), -[table](\.\./\.\./\.\./\.\./index\.md\#table), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), [tcler's -wiki](\.\./\.\./\.\./\.\./index\.md\#tcler\_s\_wiki), -[text](\.\./\.\./\.\./\.\./index\.md\#text), [url](\.\./\.\./\.\./\.\./index\.md\#url), -[wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export_html.md @@ -1,340 +0,0 @@ - -[//000000001]: # (doctools::toc::export::html \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::html\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::html \- HTML export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::html ?0\.1? -package require doctools::text -package require doctools::html -package require doctools::html::cssdefaults - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of HTML markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section4), and - contained in *serial*, the *configuration*, a dictionary, and generates - HTML markup encoding the table\. The created string is then returned as the - result of the command\. - -# <a name='section3'></a>Configuration - -The html export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the table - of contents came from\. This variable may not be set or contain the empty - string\. The plugin puts this information, if defined, i\.e\. set and not the - empty string, into the provenance comment at the beginning of the generated - document\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - \(symbolic\) document ids in reference entries to the actual filenames and/or - urls to be used in the output\. - - Document ids without a mapping are used unchanged\. - - - boolean *newlines* - - If this flag is set the plugin will break the generated html code across - lines, with each markup command on a separate line\. - - If this flag is not set \(the default\), the whole document will be written on - a single line, with minimum spacing between all elements\. - - - boolean *indented* - - If this flag is set the plugin will indent the markup commands according to - the structure of indices\. To make this work this also implies that - __newlines__ is set\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __newlines__, and no indenting is done\. - - - string *meta* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output in the - <head> section of the document, just after the <title> tag\. - - - string *header* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output just after - the <h1> title tag in the body of the document, in the class\.header - <div>'ision\. - - - string *footer* - - This variable is meant to hold a fragment of HTML \(default: empty\)\. The - fragment it contains will be inserted into the generated output just before - the </body> tag, in the class\.footer <div>'ision\. - - - dictionary *rid* - - The value of this variable \(default: empty\) maps references to the - identifiers to use as their anchor names\. Each reference __FOO__ not - found in the dictionary uses __REF\-____FOO__ as anchor, i\.e\. itself - prefixed with the string __REF\-__\. - - - string *sepline* - - The value of this variable is the string to use for the separator comments - inserted into the output when the outpout is broken across lines and/or - indented\. The default string consists of 60 dashes\. - - - string *class\.main* - - This variable contains the class name for the main <div>'ivision of the - generated document\. The default is __doctools__\. - - - string *class\.header* - - This variable contains the class name for the header <div>'ision of the - generated document\. The default is __toc\-header__\. This division - contains the document title, the user specified __header__, if any, and - a visible separator line\. - - - string *class\.title* - - This variable contains the class name for the <h1> tag enclosing the - document title\. The default is __toc\-title__\. - - - string *class\.navsep* - - This variable contains the class name for the <hr> separators in the header - and footer sections of the generated document\. The default is - __toc\-navsep__\. - - - string *class\.contents* - - This variable contains the class name for the XXXXX holding the keywords and - their references in the generated document\. The default is - __toc\-contents__\. - - - string *class\.ref* - - This variable contains the class name for the table elements which are - references to other documents\. The default is __toc\-ref__\. - - - string *class\.div* - - This variable contains the class name for the table elements which are - divisions\. The default is __toc\-div__\. - - - string *class\.footer* - - This variable contains the class name for the footer <div>'ision of the - generated document\. The default is __toc\-footer__\. This division - contains a browser\-visible separator line and the user specified - __footer__, if any\. - -*Note* that this plugin ignores the standard configuration variable -__format__, and its value\. - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export_json.md @@ -1,309 +0,0 @@ - -[//000000001]: # (doctools::toc::export::json \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::json\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::json \- JSON export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON notation of tables of contents](#section3) - - - [Configuration](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::json ?0\.1? -package require textutil::adjust - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of JSON markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section5), and - contained in *serial*, the *configuration*, a dictionary, and generates - JSON markup encoding the table\. The created string is then returned as the - result of the command\. - -# <a name='section3'></a>JSON notation of tables of contents - -The JSON format used for tables of contents is a direct translation of the [ToC -serialization format](#section5), mapping Tcl dictionaries as JSON objects -and Tcl lists as JSON arrays\. For example, the Tcl serialization - - doctools::toc { - items { - {reference { - desc {DocTools - Tables of Contents} - id introduction.man - label doctools::toc::introduction - }} - {division { - id processing.man - items { - {reference { - desc {doctoc serialization utilities} - id structure.man - label doctools::toc::structure - }} - {reference { - desc {Parsing text in doctoc format} - id parse.man - label doctools::toc::parse - }} - } - label Processing - }} - } - label {Table of Contents} - title TOC - } - -is equivalent to the JSON string - - { - "doctools::toc" : { - "items" : [{ - "reference" : { - "desc" : "DocTools - Tables of Contents", - "id" : "introduction.man", - "label" : "doctools::toc::introduction" - } - },{ - "division" : { - "id" : "processing.man", - "items" : [{ - "reference" : { - "desc" : "doctoc serialization utilities", - "id" : "structure.man", - "label" : "doctools::toc::structure" - } - },{ - "reference" : { - "desc" : "Parsing text in doctoc format", - "id" : "parse.man", - "label" : "doctools::toc::parse" - } - }], - "label" : "Processing" - } - }], - "label" : "Table of Contents", - "title" : "TOC" - } - } - -# <a name='section4'></a>Configuration - -The JSON export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - boolean *indented* - - If this flag is set the plugin will break the generated JSON code across - lines and indent it according to its inner structure, with each key of a - dictionary on a separate line\. - - If this flag is not set \(the default\), the whole JSON object will be written - on a single line, with minimum spacing between all elements\. - - - boolean *aligned* - - If this flag is set the generator ensures that the values for the keys in a - dictionary are vertically aligned with each other, for a nice table effect\. - To make this work this also implies that __indented__ is set\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __indented__, without trying to align the values for dictionary - keys\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __format__, __file__, and __map__ and their values\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export_nroff.md @@ -1,245 +0,0 @@ - -[//000000001]: # (doctools::toc::export::nroff \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::nroff\(n\) 0\.2 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::nroff \- nroff export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::nroff ?0\.2? -package require doctools::text -package require doctools::nroff::man\_macros - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of nroff markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section4), and - contained in *serial*, the *configuration*, a dictionary, and generates - nroff markup encoding the table\. The created string is then returned as the - result of the command\. - -# <a name='section3'></a>Configuration - -The nroff export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *user* - - This standard configuration variable contains the name of the user running - the process which invoked the export plugin\. The plugin puts this - information into the provenance comment at the beginning of the generated - document\. - - - string *file* - - This standard configuration variable contains the name of the file the table - of contents came from\. This variable may not be set or contain the empty - string\. The plugin puts this information, if defined, i\.e\. set and not the - empty string, into the provenance comment at the beginning of the generated - document\. - - - boolean *inline* - - If this flag is set \(default\) the plugin will place the definitions of the - man macro set directly into the output\. - - If this flag is not set, the plugin will place a reference to the - definitions of the man macro set into the output, but not the macro - definitions themselves\. - -*Note* that this plugin ignores the standard configuration variables -__format__, and __map__, and their values\. - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export_text.md @@ -1,228 +0,0 @@ - -[//000000001]: # (doctools::toc::export::text \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::text\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::text \- plain text export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::text ?0\.1? -package require doctools::text - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of plain text markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section4), and - contained in *serial*, the *configuration*, a dictionary, and generates - plain text markup encoding the table\. The created string is then returned as - the result of the command\. - -# <a name='section3'></a>Configuration - -The text export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - \(symbolic\) document ids in reference entries to the actual filenames and/or - urls to be used in the output\. - - Document ids without a mapping are used unchanged\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __file__, and __format__, and their values\. - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), [plain -text](\.\./\.\./\.\./\.\./index\.md\#plain\_text), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_export_wiki.md @@ -1,237 +0,0 @@ - -[//000000001]: # (doctools::toc::export::wiki \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::export::wiki\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::export::wiki \- wiki export plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Wiki markup](#section3) - - - [Configuration](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require doctools::toc::export::wiki ?0\.1? -package require doctools::text - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents export plugin for the -generation of wiki markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::export](toc\_export\.md)__, the export manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::export](toc\_export\.md)__ and the export -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -export plugin API version 2\. - - - <a name='1'></a>__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a table of contents, as - specified in section [ToC serialization format](#section5), and - contained in *serial*, the *configuration*, a dictionary, and generates - wiki markup encoding the table\. The created string is then returned as the - result of the command\. - -# <a name='section3'></a>Wiki markup - -The basic syntax of the wiki markup generated by this plugin are described at -[http://wiki\.tcl\.tk/14](http://wiki\.tcl\.tk/14)\. - -The plugin goes beyond the classic markup to generate proper headers and -indenting\. - -# <a name='section4'></a>Configuration - -The wiki export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - dictionary *map* - - This standard configuration variable contains a dictionary mapping from the - \(symbolic\) document ids in reference entries to the actual filenames and/or - urls to be used in the output\. - - Document ids without a mapping are used unchanged\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __file__ and __format__, and their values\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc), [wiki](\.\./\.\./\.\./\.\./index\.md\#wiki) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_import.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_import.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_import.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_import.md @@ -1,546 +0,0 @@ - -[//000000001]: # (doctools::toc::import \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_import\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::import\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::import \- Importing keyword indices - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [API](#section3) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Import plugin API v2 reference](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::toc::import ?0\.2\.1? -package require Tcl 8\.4 -package require struct::map -package require doctools::toc::structure -package require snit -package require pluginmgr - -[__::doctools::toc::import__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __import text__ *text* ?*format*?](#4) -[*objectName* __import file__ *path* ?*format*?](#5) -[*objectName* __import object text__ *object* *text* ?*format*?](#6) -[*objectName* __import object file__ *object* *path* ?*format*?](#7) -[*objectName* __config names__](#8) -[*objectName* __config get__](#9) -[*objectName* __config set__ *name* ?*value*?](#10) -[*objectName* __config unset__ *pattern*\.\.\.](#11) -[*objectName* __includes__](#12) -[*objectName* __include add__ *path*](#13) -[*objectName* __include remove__ *path*](#14) -[*objectName* __include clear__](#15) -[__IncludeFile__ *currentfile* *path*](#16) -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration*](#17) - -# <a name='description'></a>DESCRIPTION - -This package provides a class to manage the plugins for the import of tables of -contents from other formats, i\.e\. their conversion from, for example -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)*, -*[json](\.\./\.\./\.\./\.\./index\.md\#json)*, etc\. - -This is one of the three public pillars the management of tables of contents -resides on\. The other two pillars are - - 1. *[Exporting tables of contents](toc\_export\.md)*, and - - 1. *[Holding tables of contents](toc\_container\.md)* - -For information about the [Concepts](#section2) of tables of contents, and -their parts, see the same\-named section\. For information about the data -structure which is the major output of the manager objects provided by this -package see the section [ToC serialization format](#section5)\. - -The plugin system of our class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __DOCTOOLS\_TOC\_IMPORT\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_TOC\_PLUGINS__, - - 1. the environment variable __DOCTOOLS\_PLUGINS__, - - 1. the path "~/\.doctools/toc/import/plugin" - - 1. the path "~/\.doctools/toc/plugin" - - 1. the path "~/\.doctools/plugin" - - 1. the path "~/\.doctools/toc/import/plugins" - - 1. the path "~/\.doctools/toc/plugins" - - 1. the path "~/\.doctools/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\TOC\\IMPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\TOC\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\DOCTOOLS\\PLUGINS" - -The last three are used only when the package is run on a machine using -Windows\(tm\) operating system\. - -The whole system is delivered with two predefined import plugins, namely - - - doctoc - - See *[doctoc import plugin](import\_doctoc\.md)* for details\. - - - json - - See *json import plugin* for details\. - -Readers wishing to write their own import plugin for some format, i\.e\. *plugin -writer*s reading and understanding the section containing the [Import plugin -API v2 reference](#section4) is an absolute necessity, as it specifies the -interaction between this package and its plugins in detail\. - -# <a name='section2'></a>Concepts - - 1. A *[table of contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents)* - consists of a \(possibly empty\) list of *elements*\. - - 1. Each element in the list is identified by its label\. - - 1. Each element is either a - *[reference](\.\./\.\./\.\./\.\./index\.md\#reference)*, or a *division*\. - - 1. Each reference has an associated document, identified by a symbolic id, and - a textual description\. - - 1. Each division may have an associated document, identified by a symbolic id\. - - 1. Each division consists consists of a \(possibly empty\) list of *elements*, - with each element following the rules as specified in item 2 and above\. - -A few notes - - 1. The above rules span up a tree of elements, with references as the leaf - nodes, and divisions as the inner nodes, and each element representing an - entry in the whole table of contents\. - - 1. The identifying labels of any element E are unique within their division - \(or toc\), and the full label of any element E is the list of labels for all - nodes on the unique path from the root of the tree to E, including E\. - -# <a name='section3'></a>API - -## <a name='subsection1'></a>Package commands - - - <a name='1'></a>__::doctools::toc::import__ *objectName* - - This command creates a new import manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## <a name='subsection2'></a>Object command - -All objects created by the __::doctools::toc::import__ command have the -following general form: - - - <a name='2'></a>__objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## <a name='subsection3'></a>Object methods - - - <a name='3'></a>*objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - <a name='4'></a>*objectName* __import text__ *text* ?*format*? - - This method takes the *text* and converts it from the specified *format* - to the canonical serialization of a table of contents using the import - plugin for the format\. An error is thrown if no plugin could be found for - the format\. The serialization generated by the conversion process is - returned as the result of this method\. - - If no format is specified the method defaults to __doctoc__\. - - The specification of what a *canonical* serialization is can be found in - the section [ToC serialization format](#section5)\. - - The plugin has to conform to the interface specified in section [Import - plugin API v2 reference](#section4)\. - - - <a name='5'></a>*objectName* __import file__ *path* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It reads the contents of the specified file - into memory, feeds the result into __import text__ and returns the - resulting serialization as its own result\. - - - <a name='6'></a>*objectName* __import object text__ *object* *text* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It expects that *object* is an object - command supporting a __deserialize__ method expecting the canonical - serialization of a table of contents\. It imports the text using __import - text__ and then feeds the resulting serialization into the *object* via - __deserialize__\. This method returns the empty string as it result\. - - - <a name='7'></a>*objectName* __import object file__ *object* *path* ?*format*? - - This method behaves like __import object text__, except that it reads - the text to convert from the specified file instead of being given it as - argument\. - - - <a name='8'></a>*objectName* __config names__ - - This method returns a list containing the names of all configuration - variables currently known to the object\. - - - <a name='9'></a>*objectName* __config get__ - - This method returns a dictionary containing the names and values of all - configuration variables currently known to the object\. - - - <a name='10'></a>*objectName* __config set__ *name* ?*value*? - - This method sets the configuration variable *name* to the specified - *value* and returns the new value of the variable\. - - If no value is specified it simply returns the current value, without - changing it\. - - Note that while the user can set the predefined configuration variables - __user__ and __format__ doing so will have no effect, these values - will be internally overridden when invoking an import plugin\. - - - <a name='11'></a>*objectName* __config unset__ *pattern*\.\.\. - - This method unsets all configuration variables matching the specified glob - *pattern*s\. If no pattern is specified it will unset all currently defined - configuration variables\. - - - <a name='12'></a>*objectName* __includes__ - - This method returns a list containing the currently specified paths to use - to search for include files when processing input\. The order of paths in the - list corresponds to the order in which they are used, from first to last, - and also corresponds to the order in which they were added to the object\. - - - <a name='13'></a>*objectName* __include add__ *path* - - This methods adds the specified *path* to the list of paths to use to - search for include files when processing input\. The path is added to the end - of the list, causing it to be searched after all previously added paths\. The - result of the command is the empty string\. - - The method does nothing if the path is already known\. - - - <a name='14'></a>*objectName* __include remove__ *path* - - This methods removes the specified *path* from the list of paths to use to - search for include files when processing input\. The result of the command is - the empty string\. - - The method does nothing if the path is not known\. - - - <a name='15'></a>*objectName* __include clear__ - - This method clears the list of paths to use to search for include files when - processing input\. The result of the command is the empty string\. - -# <a name='section4'></a>Import plugin API v2 reference - -Plugins are what this package uses to manage the support for any input format -beyond the [ToC serialization format](#section5)\. Here we specify the API -the objects created by this package use to interact with their plugins\. - -A plugin for this package has to follow the rules listed below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form - doctools::toc::import::__FOO__, where __FOO__ is the name of the - format the plugin will generate output for\. This name is also the argument - to provide to the various __import__ methods of import manager objects - to get a string encoding a table of contents in that format\. - - 1. The plugin can expect that the package - __doctools::toc::export::plugin__ is present, as indicator that it was - invoked from a genuine plugin manager\. - - 1. The plugin can expect that a command named __IncludeFile__ is present, - with the signature - - - <a name='16'></a>__IncludeFile__ *currentfile* *path* - - This command has to be invoked by the plugin when it has to process an - included file, if the format has the concept of such\. An example of - such a format would be *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)*\. - - The plugin has to supply the following arguments - - * string *currentfile* - - The path of the file it is currently processing\. This may be the - empty string if no such is known\. - - * string *path* - - The path of the include file as specified in the include directive - being processed\. - - The result of the command will be a 5\-element list containing - - 1) A boolean flag indicating the success \(__True__\) or failure - \(__False__\) of the operation\. - - 1) In case of success the contents of the included file, and the - empty string otherwise\. - - 1) The resolved, i\.e\. absolute path of the included file, if - possible, or the unchanged *path* argument\. This is for display - in an error message, or as the *currentfile* argument of another - call to __IncludeFile__ should this file contain more files\. - - 1) In case of success an empty string, and for failure a code - indicating the reason for it, one of - - * notfound - - The specified file could not be found\. - - * notread - - The specified file was found, but not be read into memory\. - - 1) An empty string in case of success of a __notfound__ failure, - and an additional error message describing the reason for a - __notread__ error in more detail\. - - 1. A plugin has to provide one command, with the signature shown below\. - - - <a name='17'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* *configuration* - - Whenever an import manager of - __[doctools::toc](\.\./doctools/doctoc\.md)__ has to parse input - for a table of contents it will invoke this command\. - - * string *text* - - This argument will contain the text encoding the table of contents - per the format the plugin is for\. - - * dictionary *configuration* - - This argument will contain the current configuration to apply to - the parsing, as a dictionary mapping from variable names to values\. - - The following configuration variables have a predefined meaning all - plugins have to obey, although they can ignore this information at - their discretion\. Any other other configuration variables - recognized by a plugin will be described in the manpage for that - plugin\. - - + user - - This variable is expected to contain the name of the user - owning the process invoking the plugin\. - - + format - - This variable is expected to contain the name of the format - whose plugin is invoked\. - - 1. A single usage cycle of a plugin consists of the invokations of the command - __[import](\.\./\.\./\.\./\.\./index\.md\#import)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[json](\.\./\.\./\.\./\.\./index\.md\#json), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), -[reference](\.\./\.\./\.\./\.\./index\.md\#reference), -[table](\.\./\.\./\.\./\.\./index\.md\#table), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[url](\.\./\.\./\.\./\.\./index\.md\#url) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_import_json.md @@ -1,281 +0,0 @@ - -[//000000001]: # (doctools::toc::import::json \- Documentation tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::import::json\(n\) 0\.2\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::import::json \- JSON import plugin - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON notation of tables of contents](#section3) - - - [ToC serialization format](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require doctools::toc::import::json ?0\.2\.1? -package require doctools::toc::structure -package require json - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration*](#1) - -# <a name='description'></a>DESCRIPTION - -This package implements the doctools table of contents import plugin for the -parsing of JSON markup\. - -This is an internal package of doctools, for use by the higher level management -packages handling tables of contents, especially -__[doctools::toc::import](toc\_import\.md)__, the import manager\. - -Using it from a regular interpreter is possible, however only with contortions, -and is not recommended\. The proper way to use this functionality is through the -package __[doctools::toc::import](toc\_import\.md)__ and the import -manager objects it provides\. - -# <a name='section2'></a>API - -The API provided by this package satisfies the specification of the doctoc -import plugin API version 2\. - - - <a name='1'></a>__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *string* *configuration* - - This command takes the *string* and parses it as JSON markup encoding a - table of contents, in the context of the specified *configuration* \(a - dictionary\)\. The result of the command is the canonical serialization of - that table of contents, in the form specified in section [ToC serialization - format](#section4)\. - -# <a name='section3'></a>JSON notation of tables of contents - -The JSON format used for tables of contents is a direct translation of the [ToC -serialization format](#section4), mapping Tcl dictionaries as JSON objects -and Tcl lists as JSON arrays\. For example, the Tcl serialization - - doctools::toc { - items { - {reference { - desc {DocTools - Tables of Contents} - id introduction.man - label doctools::toc::introduction - }} - {division { - id processing.man - items { - {reference { - desc {doctoc serialization utilities} - id structure.man - label doctools::toc::structure - }} - {reference { - desc {Parsing text in doctoc format} - id parse.man - label doctools::toc::parse - }} - } - label Processing - }} - } - label {Table of Contents} - title TOC - } - -is equivalent to the JSON string - - { - "doctools::toc" : { - "items" : [{ - "reference" : { - "desc" : "DocTools - Tables of Contents", - "id" : "introduction.man", - "label" : "doctools::toc::introduction" - } - },{ - "division" : { - "id" : "processing.man", - "items" : [{ - "reference" : { - "desc" : "doctoc serialization utilities", - "id" : "structure.man", - "label" : "doctools::toc::structure" - } - },{ - "reference" : { - "desc" : "Parsing text in doctoc format", - "id" : "parse.man", - "label" : "doctools::toc::parse" - } - }], - "label" : "Processing" - } - }], - "label" : "Table of Contents", - "title" : "TOC" - } - } - -# <a name='section4'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[import](\.\./\.\./\.\./\.\./index\.md\#import), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents), -[toc](\.\./\.\./\.\./\.\./index\.md\#toc) - -# <a name='category'></a>CATEGORY - -Text formatter plugin - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009\-2019 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_introduction.md @@ -1,206 +0,0 @@ - -[//000000001]: # (doctools2toc\_introduction \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_introduction\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools2toc\_introduction\(n\) 2\.0 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools2toc\_introduction \- DocTools \- Tables of Contents - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Related formats](#section2) - - - [Package Overview](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='description'></a>DESCRIPTION - -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* \(short for *documentation tables -of contents*\) stands for a set of related, yet different, entities which are -working together for the easy creation and transformation of tables and contents -for documentation\. - -These are - - 1. A tcl based language for the semantic markup of a table of contents\. Markup - is represented by Tcl commands\. Beginners should start with the *[doctoc - language introduction](\.\./doctools/doctoc\_lang\_intro\.md)*\. The formal - specification is split over two documents, one dealing with the *[doctoc - language syntax](\.\./doctools/doctoc\_lang\_syntax\.md)*, the other a - *[doctoc language command - reference](\.\./doctools/doctoc\_lang\_cmdref\.md)*\. - - 1. A set of packages for the programmatic manipulation of tables of contents - in memory, and their conversion between various formats, reading and - writing\. The aforementioned markup language is one of the formats which can - be both read from and written to\. - - 1. The system for the conversion of tables of contents is based on a plugin - mechanism, for this we have two APIs describing the interface between the - packages above and the import/export plugins\. - -Which of the more detailed documents are relevant to the reader of this -introduction depends on their role in the documentation process\. - - 1. A *writer* of documentation has to understand the markup language itself\. - A beginner to doctoc should read the more informally written *[doctoc - language introduction](\.\./doctools/doctoc\_lang\_intro\.md)* first\. Having - digested this the formal *[doctoc language - syntax](\.\./doctools/doctoc\_lang\_syntax\.md)* specification should become - understandable\. A writer experienced with doctoc may only need the - *[doctoc language command - reference](\.\./doctools/doctoc\_lang\_cmdref\.md)* from time to time to - refresh her memory\. - - While a document is written the __dtp__ application can be used to - validate it, and after completion it also performs the conversion into the - chosen system of visual markup, be it \*roff, HTML, plain text, wiki, etc\. - The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ application makes - internal use of doctoc when handling directories of documentation, - automatically generating a proper table of contents for them\. - - 1. A *processor* of documentation written in the - *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup language has to know - which tools are available for use\. - - The main tool is the aforementioned __dtp__ application provided by - Tcllib\. The simpler __[dtplite](\.\./\.\./apps/dtplite\.md)__ does not - expose doctoc to the user\. At the bottom level, common to both - applications, however we find the three packages providing the basic - facilities to handle tables of contents, i\.e\. import from textual formats, - programmatic manipulation in memory, and export to textual formats\. These - are - - - __doctoools::toc__ - - Programmatic manipulation of tables of contents in memory\. - - - __doctoools::toc::import__ - - Import of tables of contents from various textual formats\. The set of - supported formats is extensible through plugin packages\. - - - __doctoools::toc::export__ - - Export of tables of contents to various textual formats\. The set of - supported formats is extensible through plugin packages\. - - See also section [Package Overview](#section3) for an overview of the - dependencies between these and other, supporting packages\. - - 1. At last, but not least, *plugin writers* have to understand the - interaction between the import and export packages and their plugins\. These - APIs are described in the documentation for the two relevant packages, i\.e\. - - - __doctoools::toc::import__ - - - __doctoools::toc::export__ - -# <a name='section2'></a>Related formats - -The doctoc format does not stand alone, it has two companion formats\. These are -called *[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx)* and -*[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)*, and they are intended for the -markup of *keyword indices*, and of general documentation, respectively\. They -are described in their own sets of documents, starting at the *DocTools \- -Keyword Indices* and the *DocTools \- General*, respectively\. - -# <a name='section3'></a>Package Overview - - ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~ - ~~ | ~~ - doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import - | | | - +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ - | | | | | | | | | - struct:map = | | | = doctools::include struct::map fileutil::paths - | | | | | - doctools::toc::export::<*> | | | doctools::toc::import::<*> - doctoc | | | doctoc, json - json | | | | \ - html | | | doctools::toc::parse \ - nroff | | | | \ - wiki | | | +---------------+ json - text | | | | | - doctools::toc::structure | - | - +-------+---------------+ - | | - doctools::html doctools::html::cssdefaults doctools::tcl::parse doctools::msgcat - | | - doctools::text doctools::nroff::man_macros = - | - doctools::msgcat::toc::<*> - c, en, de, fr - (fr == en for now) - ~~ Interoperable objects, without actual package dependencies - -- Package dependency, higher requires lower package - = Dynamic dependency through plugin system - <*> Multiple packages following the given form of naming. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[doctoc\_intro](\.\./doctools/doctoc\_intro\.md), -[doctools](\.\./doctools/doctools\.md), doctools2doc\_introduction, -[doctools2idx\_introduction](\.\./doctools2idx/idx\_introduction\.md), -[doctools\_lang\_cmdref](\.\./doctools/doctools\_lang\_cmdref\.md), -[doctools\_lang\_faq](\.\./doctools/doctools\_lang\_faq\.md), -[doctools\_lang\_intro](\.\./doctools/doctools\_lang\_intro\.md), -[doctools\_lang\_syntax](\.\./doctools/doctools\_lang\_syntax\.md), -[doctools\_plugin\_apiref](\.\./doctools/doctools\_plugin\_apiref\.md) - -# <a name='keywords'></a>KEYWORDS - -[contents](\.\./\.\./\.\./\.\./index\.md\#contents), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [semantic -markup](\.\./\.\./\.\./\.\./index\.md\#semantic\_markup), [table of -contents](\.\./\.\./\.\./\.\./index\.md\#table\_of\_contents) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_c.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_c.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_c.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_c.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::toc::c \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::toc::c\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::toc::c \- Message catalog for the doctoc parser \(C\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::toc::c ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::toc::c__ is a support module providing the C -language message catalog for the doctoc parser in the doctools system version 2\. -As such it is an internal package a regular user \(developer\) should not be in -direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[C](\.\./\.\./\.\./\.\./index\.md\#c), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_de.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_de.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_de.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_de.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::toc::de \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::toc::de\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::toc::de \- Message catalog for the doctoc parser \(DE\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::toc::de ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::toc::de__ is a support module providing the -DE \(german\) language message catalog for the doctoc parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[DE](\.\./\.\./\.\./\.\./index\.md\#de), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_en.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_en.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_en.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_en.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::toc::en \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::toc::en\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::toc::en \- Message catalog for the doctoc parser \(EN\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::toc::en ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::toc::en__ is a support module providing the -EN \(english\) language message catalog for the doctoc parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[EN](\.\./\.\./\.\./\.\./index\.md\#en), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_fr.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_fr.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_fr.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_msgcat_fr.md @@ -1,101 +0,0 @@ - -[//000000001]: # (doctools::msgcat::toc::fr \- Documentation tools) -[//000000002]: # (Generated from file 'msgcat\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::msgcat::toc::fr\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::msgcat::toc::fr \- Message catalog for the doctoc parser \(FR\) - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require msgcat -package require doctools::msgcat::toc::fr ?0\.1? - -# <a name='description'></a>DESCRIPTION - -The package __doctools::msgcat::toc::fr__ is a support module providing the -FR \(french\) language message catalog for the doctoc parser in the doctools -system version 2\. As such it is an internal package a regular user \(developer\) -should not be in direct contact with\. - -If you are such please go the documentation of either - - 1. __doctools::doc__, - - 1. __[doctools::toc](\.\./doctools/doctoc\.md)__, or - - 1. __[doctools::idx](\.\./doctools2idx/idx\_container\.md)__ - -Within the system architecture this package resides under the package -__[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__ providing the -general message catalog management within the system\. *Note* that there is -*no* explicit dependency between the manager and catalog packages\. The catalog -is a plugin which is selected and loaded dynamically\. - -# <a name='section2'></a>API - -This package has no exported API\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[FR](\.\./\.\./\.\./\.\./index\.md\#fr), [catalog -package](\.\./\.\./\.\./\.\./index\.md\#catalog\_package), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[i18n](\.\./\.\./\.\./\.\./index\.md\#i18n), -[internationalization](\.\./\.\./\.\./\.\./index\.md\#internationalization), -[l10n](\.\./\.\./\.\./\.\./index\.md\#l10n), -[localization](\.\./\.\./\.\./\.\./index\.md\#localization), [message -catalog](\.\./\.\./\.\./\.\./index\.md\#message\_catalog), [message -package](\.\./\.\./\.\./\.\./index\.md\#message\_package) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_parse.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_parse.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_parse.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_parse.md @@ -1,336 +0,0 @@ - -[//000000001]: # (doctools::toc::parse \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_parse\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::parse\(n\) 1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::parse \- Parsing text in doctoc format - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Parse errors](#section3) - - - [\[doctoc\] notation of tables of contents](#section4) - - - [ToC serialization format](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::toc::parse ?0\.1? -package require Tcl 8\.4 -package require doctools::toc::structure -package require doctools::msgcat -package require doctools::tcl::parse -package require fileutil -package require logger -package require snit -package require struct::list -package require struct::stack - -[__::doctools::toc::parse__ __text__ *text*](#1) -[__::doctools::toc::parse__ __file__ *path*](#2) -[__::doctools::toc::parse__ __includes__](#3) -[__::doctools::toc::parse__ __include add__ *path*](#4) -[__::doctools::toc::parse__ __include remove__ *path*](#5) -[__::doctools::toc::parse__ __include clear__](#6) -[__::doctools::toc::parse__ __vars__](#7) -[__::doctools::toc::parse__ __var set__ *name* *value*](#8) -[__::doctools::toc::parse__ __var unset__ *name*](#9) -[__::doctools::toc::parse__ __var clear__ ?*pattern*?](#10) - -# <a name='description'></a>DESCRIPTION - -This package provides commands to parse text written in the -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup language and convert it -into the canonical serialization of the table of contents encoded in the text\. -See the section [ToC serialization format](#section5) for specification of -their format\. - -This is an internal package of doctools, for use by the higher level packages -handling *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* documents\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::doctools::toc::parse__ __text__ *text* - - The command takes the string contained in *text* and parses it under the - assumption that it contains a document written using the - *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup language\. An error is - thrown if this assumption is found to be false\. The format of these errors - is described in section [Parse errors](#section3)\. - - When successful the command returns the canonical serialization of the table - of contents which was encoded in the text\. See the section [ToC - serialization format](#section5) for specification of that format\. - - - <a name='2'></a>__::doctools::toc::parse__ __file__ *path* - - The same as __text__, except that the text to parse is read from the - file specified by *path*\. - - - <a name='3'></a>__::doctools::toc::parse__ __includes__ - - This method returns the current list of search paths used when looking for - include files\. - - - <a name='4'></a>__::doctools::toc::parse__ __include add__ *path* - - This method adds the *path* to the list of paths searched when looking for - an include file\. The call is ignored if the path is already in the list of - paths\. The method returns the empty string as its result\. - - - <a name='5'></a>__::doctools::toc::parse__ __include remove__ *path* - - This method removes the *path* from the list of paths searched when - looking for an include file\. The call is ignored if the path is not - contained in the list of paths\. The method returns the empty string as its - result\. - - - <a name='6'></a>__::doctools::toc::parse__ __include clear__ - - This method clears the list of search paths for include files\. - - - <a name='7'></a>__::doctools::toc::parse__ __vars__ - - This method returns a dictionary containing the current set of predefined - variables known to the __vset__ markup command during processing\. - - - <a name='8'></a>__::doctools::toc::parse__ __var set__ *name* *value* - - This method adds the variable *name* to the set of predefined variables - known to the __vset__ markup command during processing, and gives it the - specified *value*\. The method returns the empty string as its result\. - - - <a name='9'></a>__::doctools::toc::parse__ __var unset__ *name* - - This method removes the variable *name* from the set of predefined - variables known to the __vset__ markup command during processing\. The - method returns the empty string as its result\. - - - <a name='10'></a>__::doctools::toc::parse__ __var clear__ ?*pattern*? - - This method removes all variables matching the *pattern* from the set of - predefined variables known to the __vset__ markup command during - processing\. The method returns the empty string as its result\. - - The pattern matching is done with __string match__, and the default - pattern used when none is specified, is __\*__\. - -# <a name='section3'></a>Parse errors - -The format of the parse error messages thrown when encountering violations of -the *[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup syntax is human -readable and not intended for processing by machines\. As such it is not -documented\. - -*However*, the errorCode attached to the message is machine\-readable and has -the following format: - - 1. The error code will be a list, each element describing a single error found - in the input\. The list has at least one element, possibly more\. - - 1. Each error element will be a list containing six strings describing an - error in detail\. The strings will be - - 1) The path of the file the error occurred in\. This may be empty\. - - 1) The range of the token the error was found at\. This range is a - two\-element list containing the offset of the first and last character - in the range, counted from the beginning of the input \(file\)\. Offsets - are counted from zero\. - - 1) The line the first character after the error is on\. Lines are counted - from one\. - - 1) The column the first character after the error is at\. Columns are - counted from zero\. - - 1) The message code of the error\. This value can be used as argument to - __msgcat::mc__ to obtain a localized error message, assuming that - the application had a suitable call of __doctools::msgcat::init__ - to initialize the necessary message catalogs \(See package - __[doctools::msgcat](\.\./doctools2base/tcllib\_msgcat\.md)__\)\. - - 1) A list of details for the error, like the markup command involved\. In - the case of message code __doctoc/include/syntax__ this value is - the set of errors found in the included file, using the format - described here\. - -# <a name='section4'></a>\[doctoc\] notation of tables of contents - -The doctoc format for tables of contents, also called the *doctoc markup -language*, is too large to be covered in single section\. The interested reader -should start with the document - - 1. *[doctoc language introduction](\.\./doctools/doctoc\_lang\_intro\.md)* - -and then proceed from there to the formal specifications, i\.e\. the documents - - 1. *[doctoc language syntax](\.\./doctools/doctoc\_lang\_syntax\.md)* and - - 1. *[doctoc language command - reference](\.\./doctools/doctoc\_lang\_cmdref\.md)*\. - -to get a thorough understanding of the language\. - -# <a name='section5'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[lexer](\.\./\.\./\.\./\.\./index\.md\#lexer), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/doctools2toc/toc_structure.md Index: embedded/md/tcllib/files/modules/doctools2toc/toc_structure.md ================================================================== --- embedded/md/tcllib/files/modules/doctools2toc/toc_structure.md +++ embedded/md/tcllib/files/modules/doctools2toc/toc_structure.md @@ -1,279 +0,0 @@ - -[//000000001]: # (doctools::toc::structure \- Documentation tools) -[//000000002]: # (Generated from file 'toc\_structure\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (doctools::toc::structure\(n\) 0\.1 tcllib "Documentation tools") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -doctools::toc::structure \- Doctoc serialization utilities - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [ToC serialization format](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require doctools::toc::structure ?0\.1? -package require Tcl 8\.4 -package require logger -package require snit - -[__::doctools::toc::structure__ __verify__ *serial* ?*canonvar*?](#1) -[__::doctools::toc::structure__ __verify\-as\-canonical__ *serial*](#2) -[__::doctools::toc::structure__ __canonicalize__ *serial*](#3) -[__::doctools::toc::structure__ __print__ *serial*](#4) -[__::doctools::toc::structure__ __merge__ *seriala* *serialb*](#5) - -# <a name='description'></a>DESCRIPTION - -This package provides commands to work with the serializations of tables of -contents as managed by the doctools system v2, and specified in section [ToC -serialization format](#section3)\. - -This is an internal package of doctools, for use by the higher level packages -handling tables of contents and their conversion into and out of various other -formats, like documents written using -*[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc)* markup\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::doctools::toc::structure__ __verify__ *serial* ?*canonvar*? - - This command verifies that the content of *serial* is a valid *regular* - serialization of a table of contents and will throw an error if that is not - the case\. The result of the command is the empty string\. - - If the argument *canonvar* is specified it is interpreted as the name of a - variable in the calling context\. This variable will be written to if and - only if *serial* is a valid regular serialization\. Its value will be a - boolean, with __True__ indicating that the serialization is not only - valid, but also *canonical*\. __False__ will be written for a valid, - but non\-canonical serialization\. - - For the specification of regular and canonical serializations see the - section [ToC serialization format](#section3)\. - - - <a name='2'></a>__::doctools::toc::structure__ __verify\-as\-canonical__ *serial* - - This command verifies that the content of *serial* is a valid - *canonical* serialization of a table of contents and will throw an error - if that is not the case\. The result of the command is the empty string\. - - For the specification of canonical serializations see the section [ToC - serialization format](#section3)\. - - - <a name='3'></a>__::doctools::toc::structure__ __canonicalize__ *serial* - - This command assumes that the content of *serial* is a valid *regular* - serialization of a table of contents and will throw an error if that is not - the case\. - - It will then convert the input into the *canonical* serialization of the - contained table of contents and return it as its result\. If the input is - already canonical it will be returned unchanged\. - - For the specification of regular and canonical serializations see the - section [ToC serialization format](#section3)\. - - - <a name='4'></a>__::doctools::toc::structure__ __print__ *serial* - - This command assumes that the argument *serial* contains a valid regular - serialization of a table of contents and returns a string containing that - table in a human readable form\. - - The exact format of this form is not specified and cannot be relied on for - parsing or other machine\-based activities\. - - For the specification of regular serializations see the section [ToC - serialization format](#section3)\. - - - <a name='5'></a>__::doctools::toc::structure__ __merge__ *seriala* *serialb* - - This command accepts the regular serializations of two tables of contents - and uses them to create their union\. The result of the command is the - canonical serialization of this unified table of contents\. - - Title and label of the resulting table are taken from the table contained in - *serialb*\. - - The whole table and its divisions are merged recursively in the same manner: - - 1. All reference elements which occur in both divisions \(identified by - their label\) are unified with document id's and descriptions taken from - the second table\. - - 1. All division elements which occur in both divisions \(identified by - their label\) are unified with the optional document id taken from the - second table, if any, or from the first if none is in the second\. The - elements in the division are merged recursively using the same - algorithm as described in this list\. - - 1. Type conflicts between elements, i\.e\. finding two elements with the - same label but different types result in a merge error\. - - 1. All elements found in the second division but not in the first are - added to the end of the list of elements in the merge result\. - - For the specification of regular and canonical serializations see the - section [ToC serialization format](#section3)\. - -# <a name='section3'></a>ToC serialization format - -Here we specify the format used by the doctools v2 packages to serialize tables -of contents as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -table of contents may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - regular serialization - - 1. The serialization of any table of contents is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __doctools::toc__, and its - value\. This value holds the contents of the table of contents\. - - 1. The contents of the table of contents are a Tcl dictionary holding the - title of the table of contents, a label, and its elements\. The relevant - keys and their values are - - * __title__ - - The value is a string containing the title of the table of - contents\. - - * __label__ - - The value is a string containing a label for the table of contents\. - - * __items__ - - The value is a Tcl list holding the elements of the table, in the - order they are to be shown\. - - Each element is a Tcl list holding the type of the item, and its - description, in this order\. An alternative description would be - that it is a Tcl dictionary holding a single key, the item type, - mapped to the item description\. - - The two legal item types and their descriptions are - - + __reference__ - - This item describes a single entry in the table of contents, - referencing a single document\. To this end its value is a Tcl - dictionary containing an id for the referenced document, a - label, and a longer textual description which can be associated - with the entry\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the entry\. - - - __label__ - - The value is a string containing a label for this entry\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __desc__ - - The value is a string containing a longer description for - this entry\. - - + __division__ - - This item describes a group of entries in the table of - contents, inducing a hierarchy of entries\. To this end its - value is a Tcl dictionary containing a label for the group, an - optional id to a document for the whole group, and the list of - entries in the group\. The relevant keys and their values are - - - __id__ - - The value is a string containing the id of the document - associated with the whole group\. This key is optional\. - - - __label__ - - The value is a string containing a label for the group\. - This string also identifies the entry, and no two entries - \(references and divisions\) in the containing list are - allowed to have the same label\. - - - __items__ - - The value is a Tcl list holding the elements of the group, - in the order they are to be shown\. This list has the same - structure as the value for the keyword __items__ used - to describe the whole table of contents, see above\. This - closes the recusrive definition of the structure, with - divisions holding the same type of elements as the whole - table of contents, including other divisions\. - - - canonical serialization - - The canonical serialization of a table of contents has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this table of contents\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[deserialization](\.\./\.\./\.\./\.\./index\.md\#deserialization), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/dtplite/pkg_dtplite.md Index: embedded/md/tcllib/files/modules/dtplite/pkg_dtplite.md ================================================================== --- embedded/md/tcllib/files/modules/dtplite/pkg_dtplite.md +++ embedded/md/tcllib/files/modules/dtplite/pkg_dtplite.md @@ -1,412 +0,0 @@ - -[//000000001]: # (dtplite \- Documentation toolbox) -[//000000002]: # (Generated from file 'pkg\_dtplite\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2013 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (dtplite\(n\) 1\.3\.1 tcllib "Documentation toolbox") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -dtplite \- Lightweight DocTools Markup Processor - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USE CASES](#subsection1) - - - [COMMAND LINE](#subsection2) - - - [OPTIONS](#subsection3) - - - [FORMATS](#subsection4) - - - [DIRECTORY STRUCTURES](#subsection5) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require dtplite ?1\.3\.1? - -[__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-o__ *output* ?options? *format* *inputfile*](#1) -[__[dtplite](\.\./\.\./apps/dtplite\.md)__ __validate__ *inputfile*](#2) -[__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-o__ *output* ?options? *format* *inputdirectory*](#3) -[__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-merge__ __\-o__ *output* ?options? *format* *inputdirectory*](#4) - -# <a name='description'></a>DESCRIPTION - -The application described by this document, -__[dtplite](\.\./\.\./apps/dtplite\.md)__, is the successor to the extremely -simple __[mpexpand](\.\./doctools/mpexpand\.md)__\. Influenced in its -functionality by the __dtp__ doctools processor it is much more powerful -than __[mpexpand](\.\./doctools/mpexpand\.md)__, yet still as easy to use; -definitely easier than __dtp__ with its myriad of subcommands and options\. - -__[dtplite](\.\./\.\./apps/dtplite\.md)__ is based upon the package -__[doctools](\.\./doctools/doctools\.md)__, like the other two processors\. - -## <a name='subsection1'></a>USE CASES - -__[dtplite](\.\./\.\./apps/dtplite\.md)__ was written with the following -three use cases in mind\. - - 1. Validation of a single document, i\.e\. checking that it was written in valid - doctools format\. This mode can also be used to get a preliminary version of - the formatted output for a single document, for display in a browser, - nroff, etc\., allowing proofreading of the formatting\. - - 1. Generation of the formatted documentation for a single package, i\.e\. all - the manpages, plus a table of contents and an index of keywords\. - - 1. An extension of the previous mode of operation, a method for the easy - generation of one documentation tree for several packages, and especially - of a unified table of contents and keyword index\. - -Beyond the above we also want to make use of the customization features provided -by the HTML formatter\. It is not the only format the application should be able -to generate, but we anticipiate it to be the most commonly used, and it is one -of the few which do provide customization hooks\. - -We allow the caller to specify a header string, footer string, a stylesheet, and -data for a bar of navigation links at the top of the generated document\. While -all can be set as long as the formatting engine provides an appropriate engine -parameter \(See section [OPTIONS](#subsection3)\) the last two have internal -processing which make them specific to HTML\. - -## <a name='subsection2'></a>COMMAND LINE - - - <a name='1'></a>__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-o__ *output* ?options? *format* *inputfile* - - This is the form for use case \[1\]\. The *options* will be explained later, - in section [OPTIONS](#subsection3)\. - - * path *output* \(in\) - - This argument specifies where to write the generated document\. It can be - the path to a file or directory, or __\-__\. The last value causes the - application to write the generated documented to __stdout__\. - - If the *output* does not exist then \[file dirname $output\] has to - exist and must be a writable directory\. The generated document will be - written to a file in that directory, and the name of that file will be - derived from the *inputfile*, the *format*, and the value given to - option __\-ext__ \(if present\)\. - - * \(path|handle\) *format* \(in\) - - This argument specifies the formatting engine to use when processing the - input, and thus the format of the generated document\. See section - [FORMATS](#subsection4) for the possibilities recognized by the - application\. - - * path *inputfile* \(in\) - - This argument specifies the path to the file to process\. It has to - exist, must be readable, and written in - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - <a name='2'></a>__[dtplite](\.\./\.\./apps/dtplite\.md)__ __validate__ *inputfile* - - This is a simpler form for use case \[1\]\. The "validate" format generates no - output at all, only syntax checks are performed\. As such the specification - of an output file or other options is not necessary and left out\. - - - <a name='3'></a>__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-o__ *output* ?options? *format* *inputdirectory* - - This is the form for use case \[2\]\. It differs from the form for use case \[1\] - by having the input documents specified through a directory instead of a - file\. The other arguments are identical, except for *output*, which now - has to be the path to an existing and writable directory\. - - The input documents are all files in *inputdirectory* or any of its - subdirectories which were recognized by __fileutil::fileType__ as - containing text in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - <a name='4'></a>__[dtplite](\.\./\.\./apps/dtplite\.md)__ __\-merge__ __\-o__ *output* ?options? *format* *inputdirectory* - - This is the form for use case \[3\]\. The only difference to the form for use - case \[2\] is the additional option __\-merge__\. - - Each such call will merge the generated documents coming from processing the - input documents under *inputdirectory* or any of its subdirectories to the - files under *output*\. In this manner it is possible to incrementally build - the unified documentation for any number of packages\. Note that it is - necessary to run through all the packages twice to get fully correct - cross\-references \(for formats supporting them\)\. - -## <a name='subsection3'></a>OPTIONS - -This section describes all the options available to the user of the application, -with the exception of the options __\-o__ and __\-merge__\. These two were -described already, in section [COMMAND LINE](#subsection2)\. - - - __\-exclude__ string - - This option specifies an exclude \(glob\) pattern\. Any files identified as - manpages to process which match the exclude pattern are ignored\. The option - can be provided multiple times, each usage adding an additional pattern to - the list of exclusions\. - - - __\-ext__ string - - If the name of an output file has to be derived from the name of an input - file it will use the name of the *format* as the extension by default\. - This option here will override this however, forcing it to use *string* as - the file extension\. This option is ignored if the name of the output file is - fully specified through option __\-o__\. - - When used multiple times only the last definition is relevant\. - - - __\-header__ file - - This option can be used if and only if the selected *format* provides an - engine parameter named "header"\. It takes the contents of the specified file - and assign them to that parameter, for whatever use by the engine\. The HTML - engine will insert the text just after the tag __<body>__\. If navigation - buttons are present \(see option __\-nav__ below\), then the HTML generated - for them is appended to the header data originating here before the final - assignment to the parameter\. - - When used multiple times only the last definition is relevant\. - - - __\-footer__ file - - Like __\-header__, except that: Any navigation buttons are ignored, the - corresponding required engine parameter is named "footer", and the data is - inserted just before the tag __</body>__\. - - When used multiple times only the last definition is relevant\. - - - __\-style__ file - - This option can be used if and only if the selected *format* provides an - engine parameter named "meta"\. When specified it will generate a piece of - HTML code declaring the *file* as the stylesheet for the generated - document and assign that to the parameter\. The HTML engine will insert this - inot the document, just after the tag __<head>__\. - - When processing an input directory the stylesheet file is copied into the - output directory and the generated HTML will refer to the copy, to make the - result more self\-contained\. When processing an input file we have no - location to copy the stylesheet to and so just reference it as specified\. - - When used multiple times only the last definition is relevant\. - - - __\-toc__ path|text - - This option specifies a doctoc file \(or text\) to use for the table of - contents instead of generating our own\. - - When used multiple times only the last definition is relevant\. - - - __\-pre\+toc__ label path|text - - - __\-post\+toc__ label path|text - - This option specifies additional doctoc files \(or texts\) to use in the - navigation bar\. - - Positioning and handling of multiple uses is like for options - __\-prenav__ and __\-postnav__, see below\. - - - __\-nav__ label url - - - __\-prenav__ label url - - Use this option to specify a navigation button with *label* to display and - the *url* to link to\. This option can be used if and only if the selected - *format* provides an engine parameter named "header"\. The HTML generated - for this is appended to whatever data we got from option __\-header__ - before it is inserted into the generated documents\. - - When used multiple times all definitions are collected and a navigation bar - is created, with the first definition shown at the left edge and the last - definition to the right\. - - The url can be relative\. In that case it is assumed to be relative to the - main files \(TOC and Keyword index\), and will be transformed for all others - to still link properly\. - - - __\-postnav__ label url - - Use this option to specify a navigation button with *label* to display and - the *url* to link to\. This option can be used if and only if the selected - *format* provides an engine parameter named "header"\. The HTML generated - for this is appended to whatever data we got from option __\-header__ - before it is inserted into the generated documents\. - - When used multiple times all definitions are collected and a navigation bar - is created, with the last definition shown at the right edge and the first - definition to the left\. - - The url can be relative\. In that case it is assumed to be relative to the - main files \(TOC and Keyword index\), and will be transformed for all others - to still link properly\. - -## <a name='subsection4'></a>FORMATS - -At first the *format* argument will be treated as a path to a tcl file -containing the code for the requested formatting engine\. The argument will be -treated as the name of one of the predefined formats listed below if and only if -the path does not exist\. - -*Note a limitation*: If treating the format as path to the tcl script -implementing the engine was sucessful, then this script has to implement not -only the engine API for doctools, i\.e\. *doctools\_api*, but for *doctoc\_api* -and *docidx\_api* as well\. Otherwise the generation of a table of contents and -of a keyword index will fail\. - -List of predefined formats, i\.e\. as provided by the package -__[doctools](\.\./doctools/doctools\.md)__: - - - __nroff__ - - The processor generates \*roff output, the standard format for unix manpages\. - - - __html__ - - The processor generates HTML output, for usage in and display by web - browsers\. This engine is currently the only one providing the various engine - parameters required for the additional customaization of the output\. - - - __tmml__ - - The processor generates TMML output, the Tcl Manpage Markup Language, a - derivative of XML\. - - - __latex__ - - The processor generates LaTeX output\. - - - __wiki__ - - The processor generates Wiki markup as understood by __wikit__\. - - - __list__ - - The processor extracts the information provided by __manpage\_begin__\. - This format is used internally to extract the meta data from which both - table of contents and keyword index are derived from\. - - - __null__ - - The processor does not generate any output\. This is equivalent to - __validate__\. - -## <a name='subsection5'></a>DIRECTORY STRUCTURES - -In this section we describe the directory structures generated by the -application under *output* when processing all documents in an -*inputdirectory*\. In other words, this is only relevant to the use cases \[2\] -and \[3\]\. - - - \[2\] - - The following directory structure is created when processing a single set of - input documents\. The file extension used is for output in HTML, but that is - not relevant to the structure and was just used to have proper file names\. - - output/ - toc.html - index.html - files/ - path/to/FOO.html - - The last line in the example shows the document generated for a file FOO - located at - - inputdirectory/path/to/FOO - - - \[3\] - - When merging many packages into a unified set of documents the generated - directory structure is a bit deeper: - - output - .toc - .idx - .tocdoc - .idxdoc - .xrf - toc.html - index.html - FOO1/ - ... - FOO2/ - toc.html - files/ - path/to/BAR.html - - Each of the directories FOO1, \.\.\. contains the documents generated for the - package FOO1, \.\.\. and follows the structure shown for use case \[2\]\. The only - exception is that there is no per\-package index\. - - The files "\.toc", "\.idx", and "\.xrf" contain the internal status of the - whole output and will be read and updated by the next invokation\. Their - contents will not be documented\. Remove these files when all packages wanted - for the output have been processed, i\.e\. when the output is complete\. - - The files "\.tocdoc", and "\.idxdoc", are intermediate files in doctoc and - docidx markup, respectively, containing the main table of contents and - keyword index for the set of documents before their conversion to the chosen - output format\. They are left in place, i\.e\. not deleted, to serve as - demonstrations of doctoc and docidx markup\. - -# <a name='section2'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *doctools* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[docidx introduction](\.\./doctools/docidx\_intro\.md), [doctoc -introduction](\.\./doctools/doctoc\_intro\.md), [doctools -introduction](\.\./doctools/doctools\_intro\.md) - -# <a name='keywords'></a>KEYWORDS - -[HTML](\.\./\.\./\.\./\.\./index\.md\#html), [TMML](\.\./\.\./\.\./\.\./index\.md\#tmml), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[docidx](\.\./\.\./\.\./\.\./index\.md\#docidx), -[doctoc](\.\./\.\./\.\./\.\./index\.md\#doctoc), -[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools), -[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage), -[markup](\.\./\.\./\.\./\.\./index\.md\#markup), -[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff) - -# <a name='category'></a>CATEGORY - -Documentation tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2004\-2013 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/fileutil/fileutil.md Index: embedded/md/tcllib/files/modules/fileutil/fileutil.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/fileutil.md +++ embedded/md/tcllib/files/modules/fileutil/fileutil.md @@ -1,540 +0,0 @@ - -[//000000001]: # (fileutil \- file utilities) -[//000000002]: # (Generated from file 'fileutil\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil\(n\) 1\.16 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil \- Procedures implementing some file utilities - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Warnings and Incompatibilities](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8 -package require fileutil ?1\.16? - -[__::fileutil::lexnormalize__ *path*](#1) -[__::fileutil::fullnormalize__ *path*](#2) -[__::fileutil::test__ *path* *codes* ?*msgvar*? ?*label*?](#3) -[__::fileutil::cat__ \(?*options*? *file*\)\.\.\.](#4) -[__::fileutil::writeFile__ ?*options*? *file* *data*](#5) -[__::fileutil::appendToFile__ ?*options*? *file* *data*](#6) -[__::fileutil::insertIntoFile__ ?*options*? *file* *at* *data*](#7) -[__::fileutil::removeFromFile__ ?*options*? *file* *at* *n*](#8) -[__::fileutil::replaceInFile__ ?*options*? *file* *at* *n* *data*](#9) -[__::fileutil::updateInPlace__ ?*options*? *file* *cmd*](#10) -[__::fileutil::fileType__ *filename*](#11) -[__::fileutil::find__ ?*basedir* ?*filtercmd*??](#12) -[__::fileutil::findByPattern__ *basedir* ?__\-regexp__|__\-glob__? ?__\-\-__? *patterns*](#13) -[__::fileutil::foreachLine__ *var filename cmd*](#14) -[__::fileutil::grep__ *pattern* ?*files*?](#15) -[__::fileutil::install__ ?__\-m__ *mode*? *source* *destination*](#16) -[__::fileutil::stripN__ *path* *n*](#17) -[__::fileutil::stripPwd__ *path*](#18) -[__::fileutil::stripPath__ *prefix* *path*](#19) -[__::fileutil::jail__ *jail* *path*](#20) -[__::fileutil::touch__ ?__\-a__? ?__\-c__? ?__\-m__? ?__\-r__ *ref\_file*? ?__\-t__ *time*? *filename* ?*\.\.\.*?](#21) -[__::fileutil::tempdir__](#22) -[__::fileutil::tempdir__ *path*](#23) -[__::fileutil::tempdirReset__](#24) -[__::fileutil::tempfile__ ?*prefix*?](#25) -[__::fileutil::maketempdir__ ?__\-prefix__ *str*? ?__\-suffix__ *str*? ?__\-dir__ *str*?](#26) -[__::fileutil::relative__ *base* *dst*](#27) -[__::fileutil::relativeUrl__ *base* *dst*](#28) - -# <a name='description'></a>DESCRIPTION - -This package provides implementations of standard unix utilities\. - - - <a name='1'></a>__::fileutil::lexnormalize__ *path* - - This command performs purely lexical normalization on the *path* and - returns the changed path as its result\. Symbolic links in the path are - *not* resolved\. - - Examples: - - fileutil::lexnormalize /foo/./bar - => /foo/bar - - fileutil::lexnormalize /foo/../bar - => /bar - - - <a name='2'></a>__::fileutil::fullnormalize__ *path* - - This command resolves all symbolic links in the *path* and returns the - changed path as its result\. In contrast to the builtin __file - normalize__ this command resolves a symbolic link in the last element of - the path as well\. - - - <a name='3'></a>__::fileutil::test__ *path* *codes* ?*msgvar*? ?*label*? - - A command for the testing of several properties of a *path*\. The - properties to test for are specified in *codes*, either as a list of - keywords describing the properties, or as a string where each letter is a - shorthand for a property to test\. The recognized keywords, shorthands, and - associated properties are shown in the list below\. The tests are executed in - the order given to the command\. - - The result of the command is a boolean value\. It will be true if and only if - the *path* passes all the specified tests\. In the case of the *path* not - passing one or more test the first failing test will leave a message in the - variable referenced by *msgvar*, if such is specified\. The message will be - prefixed with *label*, if it is specified\. *Note* that the variabled - referenced by *msgvar* is not touched at all if all the tests pass\. - - * *r*ead - - __file readable__ - - * *w*rite - - __file writable__ - - * *e*xists - - __file exists__ - - * e*x*ec - - __file executable__ - - * *f*ile - - __file isfile__ - - * *d*ir - - __file isdirectory__ - - - <a name='4'></a>__::fileutil::cat__ \(?*options*? *file*\)\.\.\. - - A tcl implementation of the UNIX __[cat](\.\./\.\./\.\./\.\./index\.md\#cat)__ - command\. Returns the contents of the specified file\(s\)\. The arguments are - files to read, with interspersed options configuring the process\. If there - are problems reading any of the files, an error will occur, and no data will - be returned\. - - The options accepted are __\-encoding__, __\-translation__, - __\-eofchar__, and __\-\-__\. With the exception of the last all options - take a single value as argument, as specified by the tcl builtin command - __fconfigure__\. The __\-\-__ has to be used to terminate option - processing before a file if that file's name begins with a dash\. - - Each file can have its own set of options coming before it, and for anything - not specified directly the defaults are inherited from the options of the - previous file\. The first file inherits the system default for unspecified - options\. - - - <a name='5'></a>__::fileutil::writeFile__ ?*options*? *file* *data* - - The command replaces the current contents of the specified *file* with - *data*, with the process configured by the options\. The command accepts - the same options as __::fileutil::cat__\. The specification of a - non\-existent file is legal and causes the command to create the file \(and - all required but missing directories\)\. - - - <a name='6'></a>__::fileutil::appendToFile__ ?*options*? *file* *data* - - This command is like __::fileutil::writeFile__, except that the previous - contents of *file* are not replaced, but appended to\. The command accepts - the same options as __::fileutil::cat__ - - - <a name='7'></a>__::fileutil::insertIntoFile__ ?*options*? *file* *at* *data* - - This comment is similar to __::fileutil::appendToFile__, except that the - new data is not appended at the end, but inserted at a specified location - within the file\. In further contrast this command has to be given the path - to an existing file\. It will not create a missing file, but throw an error - instead\. - - The specified location *at* has to be an integer number in the range - __0__ \.\.\. \[file size *file*\]\. __0__ will cause insertion of the - new data before the first character of the existing content, whereas \[file - size *file*\] causes insertion after the last character of the existing - content, i\.e\. appending\. - - The command accepts the same options as __::fileutil::cat__\. - - - <a name='8'></a>__::fileutil::removeFromFile__ ?*options*? *file* *at* *n* - - This command is the complement to __::fileutil::insertIntoFile__, - removing *n* characters from the *file*, starting at location *at*\. - The specified location *at* has to be an integer number in the range - __0__ \.\.\. \[file size *file*\] \- *n*\. __0__ will cause the removal - of the new data to start with the first character of the existing content, - whereas \[file size *file*\] \- *n* causes the removal of the tail of the - existing content, i\.e\. the truncation of the file\. - - The command accepts the same options as __::fileutil::cat__\. - - - <a name='9'></a>__::fileutil::replaceInFile__ ?*options*? *file* *at* *n* *data* - - This command is a combination of __::fileutil::removeFromFile__ and - __::fileutil::insertIntoFile__\. It first removes the part of the - contents specified by the arguments *at* and *n*, and then inserts - *data* at the given location, effectively replacing the removed by content - with *data*\. All constraints imposed on *at* and *n* by - __::fileutil::removeFromFile__ and __::fileutil::insertIntoFile__ - are obeyed\. - - The command accepts the same options as __::fileutil::cat__\. - - - <a name='10'></a>__::fileutil::updateInPlace__ ?*options*? *file* *cmd* - - This command can be seen as the generic core functionality of - __::fileutil::replaceInFile__\. It first reads the contents of the - specified *file*, then runs the command prefix *cmd* with that data - appended to it, and at last writes the result of that invokation back as the - new contents of the file\. - - If the executed command throws an error the *file* is not changed\. - - The command accepts the same options as __::fileutil::cat__\. - - - <a name='11'></a>__::fileutil::fileType__ *filename* - - An implementation of the UNIX __[file](\.\./\.\./\.\./\.\./index\.md\#file)__ - command, which uses various heuristics to guess the type of a file\. Returns - a list specifying as much type information as can be determined about the - file, from most general \(eg, "binary" or "text"\) to most specific \(eg, - "gif"\)\. For example, the return value for a GIF file would be "binary - graphic gif"\. The command will detect the following types of files: - directory, empty, binary, text, script \(with interpreter\), executable elf, - executable dos, executable ne, executable pe, graphic gif, graphic jpeg, - graphic png, graphic tiff, graphic bitmap, html, xml \(with doctype if - available\), message pgp, binary pdf, text ps, text eps, binary - gravity\_wave\_data\_frame, compressed bzip, compressed gzip, compressed zip, - compressed tar, audio wave, audio mpeg, and link\. It further detects - doctools, doctoc, and docidx documentation files, and tklib diagrams\. - - - <a name='12'></a>__::fileutil::find__ ?*basedir* ?*filtercmd*?? - - An implementation of the unix command - __[find](\.\./\.\./\.\./\.\./index\.md\#find)__\. Adapted from the Tcler's - Wiki\. Takes at most two arguments, the path to the directory to start - searching from and a command to use to evaluate interest in each file\. The - path defaults to "\.", i\.e\. the current directory\. The command defaults to - the empty string, which means that all files are of interest\. The command - takes care *not* to lose itself in infinite loops upon encountering - circular link structures\. The result of the command is a list containing the - paths to the interesting files\. - - The *filtercmd*, if specified, is interpreted as a command prefix and one - argument is added to it, the name of the file or directory find is currently - looking at\. Note that this name is *not* fully qualified\. It has to be - joined it with the result of __pwd__ to get an absolute filename\. - - The result of *filtercmd* is a boolean value that indicates if the current - file should be included in the list of interesting files\. - - Example: - - # find .tcl files - package require fileutil - proc is_tcl {name} {return [string match *.tcl $name]} - set tcl_files [fileutil::find . is_tcl] - - - <a name='13'></a>__::fileutil::findByPattern__ *basedir* ?__\-regexp__|__\-glob__? ?__\-\-__? *patterns* - - This command is based upon the __TclX__ command __recursive\_glob__, - except that it doesn't allow recursion over more than one directory at a - time\. It uses __::fileutil::find__ internally and is thus able to and - does follow symbolic links, something the __TclX__ command does not do\. - First argument is the directory to start the search in, second argument is a - list of *patterns*\. The command returns a list of all files reachable - through *basedir* whose names match at least one of the patterns\. The - options before the pattern\-list determine the style of matching, either - regexp or glob\. glob\-style matching is the default if no options are given\. - Usage of the option __\-\-__ stops option processing\. This allows the use - of a leading '\-' in the patterns\. - - - <a name='14'></a>__::fileutil::foreachLine__ *var filename cmd* - - The command reads the file *filename* and executes the script *cmd* for - every line in the file\. During the execution of the script the variable - *var* is set to the contents of the current line\. The return value of this - command is the result of the last invocation of the script *cmd* or the - empty string if the file was empty\. - - - <a name='15'></a>__::fileutil::grep__ *pattern* ?*files*? - - Implementation of __[grep](\.\./\.\./\.\./\.\./index\.md\#grep)__\. Adapted - from the Tcler's Wiki\. The first argument defines the *pattern* to search - for\. This is followed by a list of *files* to search through\. The list is - optional and __stdin__ will be used if it is missing\. The result of the - procedures is a list containing the matches\. Each match is a single element - of the list and contains filename, number and contents of the matching line, - separated by a colons\. - - - <a name='16'></a>__::fileutil::install__ ?__\-m__ *mode*? *source* *destination* - - The __install__ command is similar in functionality to the - __install__ command found on many unix systems, or the shell script - distributed with many source distributions \(unix/install\-sh in the Tcl - sources, for example\)\. It copies *source*, which can be either a file or - directory to *destination*, which should be a directory, unless *source* - is also a single file\. The ?\-m? option lets the user specify a unix\-style - mode \(either octal or symbolic \- see __file attributes__\. - - - <a name='17'></a>__::fileutil::stripN__ *path* *n* - - Removes the first *n* elements from the specified *path* and returns the - modified path\. If *n* is greater than the number of components in *path* - an empty string is returned\. The number of components in a given path may be - determined by performing __llength__ on the list returned by __file - split__\. - - - <a name='18'></a>__::fileutil::stripPwd__ *path* - - If, and only if the *path* is inside of the directory returned by - \[__pwd__\] \(or the current working directory itself\) it is made relative - to that directory\. In other words, the current working directory is stripped - from the *path*\. The possibly modified path is returned as the result of - the command\. If the current working directory itself was specified for - *path* the result is the string "__\.__"\. - - - <a name='19'></a>__::fileutil::stripPath__ *prefix* *path* - - If, and only of the *path* is inside of the directory "prefix" \(or the - prefix directory itself\) it is made relative to that directory\. In other - words, the prefix directory is stripped from the *path*\. The possibly - modified path is returned as the result of the command\. If the prefix - directory itself was specified for *path* the result is the string - "__\.__"\. - - - <a name='20'></a>__::fileutil::jail__ *jail* *path* - - This command ensures that the *path* is not escaping the directory - *jail*\. It always returns an absolute path derived from *path* which is - within *jail*\. - - If *path* is an absolute path and already within *jail* it is returned - unmodified\. - - An absolute path outside of *jail* is stripped of its root element and - then put into the *jail* by prefixing it with it\. The same happens if - *path* is relative, except that nothing is stripped of it\. Before adding - the *jail* prefix the *path* is lexically normalized to prevent the - caller from using __\.\.__ segments in *path* to escape the jail\. - - - <a name='21'></a>__::fileutil::touch__ ?__\-a__? ?__\-c__? ?__\-m__? ?__\-r__ *ref\_file*? ?__\-t__ *time*? *filename* ?*\.\.\.*? - - Implementation of __[touch](\.\./\.\./\.\./\.\./index\.md\#touch)__\. Alter the - atime and mtime of the specified files\. If __\-c__, do not create files - if they do not already exist\. If __\-r__, use the atime and mtime from - *ref\_file*\. If __\-t__, use the integer clock value *time*\. It is - illegal to specify both __\-r__ and __\-t__\. If __\-a__, only - change the atime\. If __\-m__, only change the mtime\. - - *This command is not available for Tcl versions less than 8\.3\.* - - - <a name='22'></a>__::fileutil::tempdir__ - - The command returns the path of a directory where the caller can place - temporary files, such as "/tmp" on Unix systems\. The algorithm we use to - find the correct directory is as follows: - - 1. The directory set by an invokation of __::fileutil::tempdir__ with - an argument\. If this is present it is tried exclusively and none of the - following item are tried\. - - 1. The directory named in the TMPDIR environment variable\. - - 1. The directory named in the TEMP environment variable\. - - 1. The directory named in the TMP environment variable\. - - 1. A platform specific location: - - * Windows - - "C:\\TEMP", "C:\\TMP", "\\TEMP", and "\\TMP" are tried in that order\. - - * \(classic\) Macintosh - - The TRASH\_FOLDER environment variable is used\. This is most likely - not correct\. - - * Unix - - The directories "/tmp", "/var/tmp", and "/usr/tmp" are tried in - that order\. - - The algorithm utilized is mainly that used in the Python standard library\. - The exception is the first item, the ability to have the search overridden - by a user\-specified directory\. - - - <a name='23'></a>__::fileutil::tempdir__ *path* - - In this mode the command sets the *path* as the first and only directory - to try as a temp\. directory\. See the previous item for the use of the set - directory\. The command returns the empty string\. - - - <a name='24'></a>__::fileutil::tempdirReset__ - - Invoking this command clears the information set by the last call of - \[__::fileutil::tempdir__ *path*\]\. See the last item too\. - - - <a name='25'></a>__::fileutil::tempfile__ ?*prefix*? - - The command generates a temporary file name suitable for writing to, and the - associated file\. The file name will be unique, and the file will be writable - and contained in the appropriate system specific temp directory\. The name of - the file will be returned as the result of the command\. - - The code was taken from - [http://wiki\.tcl\.tk/772](http://wiki\.tcl\.tk/772), attributed to Igor - Volobouev and anon\. - - - <a name='26'></a>__::fileutil::maketempdir__ ?__\-prefix__ *str*? ?__\-suffix__ *str*? ?__\-dir__ *str*? - - The command generates a temporary directory suitable for writing to\. The - directory name will be unique, and the directory will be writable and - contained in the appropriate system specific temp directory\. The name of the - directory will be returned as the result of the command\. - - The three options can used to tweak the behaviour of the command: - - * __\-prefix__ str - - The initial, fixed part of the directory name\. Defaults to __tmp__ - if not specified\. - - * __\-suffix__ str - - The fixed tail of the directory\. Defaults to the empty string if not - specified\. - - * __\-dir__ str - - The directory to place the new directory into\. Defaults to the result of - __fileutil::tempdir__ if not specified\. - - The initial code for this was supplied by [Miguel Martinez - Lopez](mailto:aplicacionamedida@gmail\.com)\. - - - <a name='27'></a>__::fileutil::relative__ *base* *dst* - - This command takes two directory paths, both either absolute or relative and - computes the path of *dst* relative to *base*\. This relative path is - returned as the result of the command\. As implied in the previous sentence, - the command is not able to compute this relationship between the arguments - if one of the paths is absolute and the other relative\. - - *Note:* The processing done by this command is purely lexical\. Symbolic - links are *not* taken into account\. - - - <a name='28'></a>__::fileutil::relativeUrl__ *base* *dst* - - This command takes two file paths, both either absolute or relative and - computes the path of *dst* relative to *base*, as seen from inside of - the *base*\. This is the algorithm how a browser resolves a relative link - found in the currently shown file\. - - The computed relative path is returned as the result of the command\. As - implied in the previous sentence, the command is not able to compute this - relationship between the arguments if one of the paths is absolute and the - other relative\. - - *Note:* The processing done by this command is purely lexical\. Symbolic - links are *not* taken into account\. - -# <a name='section2'></a>Warnings and Incompatibilities - - - __1\.14\.9__ - - In this version __fileutil::find__'s broken system for handling symlinks - was replaced with one working correctly and properly enumerating all the - legal non\-cyclic paths under a base directory\. - - While correct this means that certain pathological directory hierarchies - with cross\-linked sym\-links will now take about O\(n\*\*2\) time to enumerate - whereas the original broken code managed O\(n\) due to its brokenness\. - - A concrete example and extreme case is the "/sys" hierarchy under Linux - where some hundred devices exist under both "/sys/devices" and "/sys/class" - with the two sub\-hierarchies linking to the other, generating millions of - legal paths to enumerate\. The structure, reduced to three devices, roughly - looks like - - /sys/class/tty/tty0 --> ../../dev/tty0 - /sys/class/tty/tty1 --> ../../dev/tty1 - /sys/class/tty/tty2 --> ../../dev/tty1 - - /sys/dev/tty0/bus - /sys/dev/tty0/subsystem --> ../../class/tty - /sys/dev/tty1/bus - /sys/dev/tty1/subsystem --> ../../class/tty - /sys/dev/tty2/bus - /sys/dev/tty2/subsystem --> ../../class/tty - - The command __fileutil::find__ currently has no way to escape this\. When - having to handle such a pathological hierarchy It is recommended to switch - to package __fileutil::traverse__ and the same\-named command it - provides, and then use the __\-prefilter__ option to prevent the - traverser from following symbolic links, like so: - - package require fileutil::traverse - - proc NoLinks {fileName} { - if {[string equal [file type $fileName] link]} { - return 0 - } - return 1 - } - - fileutil::traverse T /sys/devices -prefilter NoLinks - T foreach p { - puts $p - } - T destroy - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[cat](\.\./\.\./\.\./\.\./index\.md\#cat), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[grep](\.\./\.\./\.\./\.\./index\.md\#grep), [temp -file](\.\./\.\./\.\./\.\./index\.md\#temp\_file), [test](\.\./\.\./\.\./\.\./index\.md\#test), -[touch](\.\./\.\./\.\./\.\./index\.md\#touch), [type](\.\./\.\./\.\./\.\./index\.md\#type) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fileutil/multi.md Index: embedded/md/tcllib/files/modules/fileutil/multi.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/multi.md +++ embedded/md/tcllib/files/modules/fileutil/multi.md @@ -1,95 +0,0 @@ - -[//000000001]: # (fileutil::multi \- file utilities) -[//000000002]: # (Generated from file 'multi\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::multi\(n\) 0\.1 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::multi \- Multi\-file operation, scatter/gather, standard object - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require fileutil::multi ?0\.1? -package require fileutil::multi::op ?0\.1? -package require wip ?1\.0? - -[__::fileutil::multi__ ?*word*\.\.\.?](#1) - -# <a name='description'></a>DESCRIPTION - -This package provides a single command to perform actions on multiple files -selected by glob patterns\. It is a thin layer over the package -__[fileutil::multi::op](multiop\.md)__ which provides objects for the -same\. This package simply creates a single such object and directs all file -commands to it\. - -At the core is a domain specific language allowing the easy specification of -multi\-file copy and/or move and/or deletion operations\. Alternate names would be -scatter/gather processor, or maybe even assembler\. For the detailed -specification of this language, and examples, please see the documention for the -package __[fileutil::multi::op](multiop\.md)__\. - -# <a name='section2'></a>PUBLIC API - -The main command of the package is: - - - <a name='1'></a>__::fileutil::multi__ ?*word*\.\.\.? - - This command interprets the specified words as file commands to execute\. See - the section __FILE API__ of the documentation for the package - __[fileutil::multi::op](multiop\.md)__ for the set of acceptable - commands, their syntax, and semantics\. - - The result of the command is the result generated by the last file command - it executed\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[move](\.\./\.\./\.\./\.\./index\.md\#move), -[multi\-file](\.\./\.\./\.\./\.\./index\.md\#multi\_file), -[remove](\.\./\.\./\.\./\.\./index\.md\#remove) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fileutil/multiop.md Index: embedded/md/tcllib/files/modules/fileutil/multiop.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/multiop.md +++ embedded/md/tcllib/files/modules/fileutil/multiop.md @@ -1,485 +0,0 @@ - -[//000000001]: # (fileutil::multi::op \- file utilities) -[//000000002]: # (Generated from file 'multiop\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::multi::op\(n\) 0\.5\.3 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::multi::op \- Multi\-file operation, scatter/gather - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [CLASS API](#section2) - - - [OBJECT API](#section3) - - - [FILE API](#section4) - - - [EXAMPLES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require fileutil::multi::op ?0\.5\.3? -package require wip ?1\.0? - -[__::fileutil::multi::op__ ?*opName*? ?*word*\.\.\.?](#1) -[__opName__ *option* ?*arg arg \.\.\.*?](#2) -[__$opName__ __do__ ?*word*\.\.\.?](#3) -[__into__ *directory*](#4) -[__in__ *directory*](#5) -[__to__ *directory*](#6) -[__from__ *directory*](#7) -[__not__ *pattern*](#8) -[__for__ *pattern*](#9) -[__exclude__ *pattern*](#10) -[__but__](#11) -[__except__](#12) -[__as__ *name*](#13) -[__recursive__](#14) -[__recursively__](#15) -[__[copy](\.\./\.\./\.\./\.\./index\.md\#copy)__](#16) -[__[move](\.\./\.\./\.\./\.\./index\.md\#move)__](#17) -[__[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__](#18) -[__expand__](#19) -[__invoke__ *cmdprefix*](#20) -[__reset__](#21) -[__\(__](#22) -[__\)__](#23) -[__cd__ *directory*](#24) -[__up__](#25) -[__for\-windows__](#26) -[__for\-win__](#27) -[__for\-unix__](#28) -[__the__ *pattern*](#29) -[__the\-set__ *varname*](#30) -[__\->__ *varname*](#31) -[__strict__](#32) -[__\!strict__](#33) -[__files__](#34) -[__links__](#35) -[__directories__](#36) -[__dirs__](#37) -[__all__](#38) -[__state?__](#39) -[__as?__](#40) -[__excluded?__](#41) -[__from?__](#42) -[__into?__](#43) -[__operation?__](#44) -[__recursive?__](#45) -[__strict?__](#46) -[__type?__](#47) - -# <a name='description'></a>DESCRIPTION - -This package provides objects which are able to perform actions on multiple -files selected by glob patterns\. - -At the core is a domain specific language allowing the easy specification of -multi\-file copy and/or move and/or deletion operations\. Alternate names would be -scatter/gather processor, or maybe even assembler\. - -# <a name='section2'></a>CLASS API - -The main command of the package is: - - - <a name='1'></a>__::fileutil::multi::op__ ?*opName*? ?*word*\.\.\.? - - The command creates a new multi\-file operation object with an associated - global Tcl command whose name is *opName*\. This command can be used to - invoke the various possible file operations\. It has the following general - form: - - * <a name='2'></a>__opName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - If the string __%AUTO%__ is used as the *opName* then the package will - generate a unique name on its own\. - - If one or more *word*s are specified they are interpreted as an initial - set of file commands to execute\. I\.e\. the method __do__ of the newly - constructed object is implicitly invoked using the words as its arguments\. - -# <a name='section3'></a>OBJECT API - -The following methods are possible for multi\-file operation objects: - - - <a name='3'></a>__$opName__ __do__ ?*word*\.\.\.? - - This method interprets the specified words as file commands to execute\. See - the section [FILE API](#section4) for the set of acceptable commands, - their syntax, and semantics\. - - The result of the method is the result generated by the last file command it - executed\. - -# <a name='section4'></a>FILE API - -Both object constructor and method __do__ take a list of words and interpret -them as file commands to execute\. The names were chosen to allow the -construction of operations as sentences in near\-natural language\. Most of the -commands influence just the state of the object, i\.e\. are simply providing the -configuration used by the command triggering the actual action\. - - - <a name='4'></a>__into__ *directory* - - Specifies the destination directory for operations\. - - - <a name='5'></a>__in__ *directory* - - Alias for __into__\. - - - <a name='6'></a>__to__ *directory* - - Alias for __into__\. - - - <a name='7'></a>__from__ *directory* - - Specifies the source directory for operations\. - - - <a name='8'></a>__not__ *pattern* - - Specifies a glob pattern for paths to be excluded from the operation\. - - - <a name='9'></a>__for__ *pattern* - - Alias for __not__\. - - - <a name='10'></a>__exclude__ *pattern* - - Alias for __not__\. - - - <a name='11'></a>__but__ - - Has no arguments of its own, but looks ahead in the list of words and - executes all __not__ commands immediately following it\. This allows the - construction of "but not" and "but exclude" clauses for a more natural - sounding specification of excluded paths\. - - - <a name='12'></a>__except__ - - A semi\-alias for __but__\. Has no arguments of its own, but looks ahead - in the list of words and executes all __for__ commands immediately - following it\. This allows the construction of "except for" clauses for a - more natural sounding specification of excluded paths\. - - - <a name='13'></a>__as__ *name* - - Specifies a new name for the first file handled by the current operation\. - I\.e\. for the renaming of a single file during the operation\. - - - <a name='14'></a>__recursive__ - - Signals that file expansion should happen in the whole directory hierarchy - and not just the directory itself\. - - - <a name='15'></a>__recursively__ - - An alias for __recursive__\. - - - <a name='16'></a>__[copy](\.\./\.\./\.\./\.\./index\.md\#copy)__ - - Signals that the operation is the copying of files from source to - destination directory per the specified inclusion and exclusion patterns\. - - - <a name='17'></a>__[move](\.\./\.\./\.\./\.\./index\.md\#move)__ - - Signals that the operation is the moving of files from source to destination - directory per the specified inclusion and exclusion patterns\. - - - <a name='18'></a>__[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ - - Signals that the operation is the removal of files in the destination - directory per the specified inclusion and exclusion patterns\. - - - <a name='19'></a>__expand__ - - Signals that there is no operation but the calculation of the set of files - from the include and exclude patterns\. This operation is not available if - __the\-set__ is used\. - - - <a name='20'></a>__invoke__ *cmdprefix* - - Signals that the user\-specified command prefix *cmdprefix* is the - operation to perform\. The command prefix is executed at the global level and - given the source directory, destination directory, and set of files \(as - dictionary mapping from source to destination files\), in this order\. - - - <a name='21'></a>__reset__ - - Forces the object into the ground state where all parts of the configuration - have default values\. - - - <a name='22'></a>__\(__ - - Saves a copy of the current object state on a stack\. - - - <a name='23'></a>__\)__ - - Takes the state at the top of the state stack and restores it, i\.e\. makes it - the new current object state\. - - - <a name='24'></a>__cd__ *directory* - - Changes the destination directory to the sub\-directory *directory* of the - current destination\. - - - <a name='25'></a>__up__ - - Changes the destination directory to the parent directory of the current - destination\. - - - <a name='26'></a>__for\-windows__ - - Checks that Windows is the current platform\. Aborts processing if not\. - - - <a name='27'></a>__for\-win__ - - An alias for __for\-windows__\. - - - <a name='28'></a>__for\-unix__ - - Checks that Unix is the current platform\. Aborts processing if not\. - - - <a name='29'></a>__the__ *pattern* - - This command specifies the files to operate on per a glob pattern, and is - also the active element, i\.e\. the command which actually performs the - specified operation\. All the other commands only modified the object state - to set the operation up, but di nothing else\. - - To allow for a more natural sounding syntax this command also looks ahead in - the list of words looks and executes several commands immediately following - it before performing its own actions\. These commands are __as__, - __but__, __exclude__, __except__, __from__, and __into__ - \(and aliases\)\. That way these commands act like qualifiers, and still take - effect as if they had been written before this command\. - - After the operation has been performed the object state the exclude patterns - and the alias name, if specified, are reset to their default values \(i\.e\. - empty\), but nothing else\. - - - <a name='30'></a>__the\-set__ *varname* - - Like __the__, however the set of files to use is not specified - implicitly per a glob pattern, but contained and loaded from the specified - variable\. The operation __expand__ is not available if this command is - used\. - - - <a name='31'></a>__\->__ *varname* - - Saves the set of files from the last expansion into the specified variable\. - - - <a name='32'></a>__strict__ - - Make file expansion and definition of destination directory \(__in__ and - aliases\) strict, i\.e\. report errors for missing directories, and empty - expansion\. - - - <a name='33'></a>__\!strict__ - - Complement of __strict__\. A missing destination directory or empty - expansion are not reported as errors\. - - - <a name='34'></a>__files__ - - Limit the search to files\. Default is to accept every type of path\. - - - <a name='35'></a>__links__ - - Limit the search to symbolic links\. Default is to accept every type of path\. - - - <a name='36'></a>__directories__ - - Limit the search to directories\. Default is to accept every type of path\. - - - <a name='37'></a>__dirs__ - - An alias for __directories__\. - - - <a name='38'></a>__all__ - - Accept all types of paths \(default\)\. - - - <a name='39'></a>__state?__ - - Returns the current state of the object as dictionary\. The dictionary keys - and their meanings are: - - * __as__ - - Last setting made by __as__\. - - * __excluded__ - - List of currently known exclusion patterns\. - - * __from__ - - Current source directory, set by __from__\. - - * __into__ - - Current destination directory, set by __into__ \(and aliases\)\. - - * __operation__ - - Current operation to perform, set by - __[copy](\.\./\.\./\.\./\.\./index\.md\#copy)__, - __[move](\.\./\.\./\.\./\.\./index\.md\#move)__, - __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__, __expand__, or - __invoke__\. - - * __recursive__ - - Current recursion status\. Set/unset by __recursive__ and - __\!recursive__\. - - * __strict__ - - Current strictness\. Set/unset by __strict__ and __\!strict__\. - - * __type__ - - Current path type limiter\. Set by either __files__, - __directories__, __links__, or __all__\. - - - <a name='40'></a>__as?__ - - Returns the current alias name\. - - - <a name='41'></a>__excluded?__ - - Returns the current set of exclusion patterns\. - - - <a name='42'></a>__from?__ - - Returns the current source directory\. - - - <a name='43'></a>__into?__ - - Returns the current destination directory\. - - - <a name='44'></a>__operation?__ - - Returns the current operation to perform\. - - - <a name='45'></a>__recursive?__ - - Returns the current recursion status\. - - - <a name='46'></a>__strict?__ - - Returns the current strictness\. - - - <a name='47'></a>__type?__ - - Returns the current path type limiter\. - -# <a name='section5'></a>EXAMPLES - -The following examples assume that the variable __F__ contains a reference -to a multi\-file operation object\. - - $F do copy \ - the *.dll \ - from c:/TDK/PrivateOpenSSL/bin \ - to [installdir_of tls] - - $F do move \ - the * \ - from /sources \ - into /scratch \ - but not *.html - - # Alternatively use 'except for *.html'. - - $F do \ - move \ - the index \ - from /sources \ - into /scratch \ - as pkgIndex.tcl - - $F do \ - remove \ - the *.txt \ - in /scratch - -Note that the fact that most commands just modify the object state allows us to -use more off forms as specifications instead of just nearly\-natural language -sentences\. For example the second example in this section can re\-arranged into: - - $F do \ - from /sources \ - into /scratch \ - but not *.html \ - move \ - the * - -and the result is not only still a valid specification, but even stays -relatively readable\. - -Further note that the information collected by the commands __but__, -__except__, and __as__ is automatically reset after the associated -__the__ was executed\. However no other state is reset in that manner, -allowing the user to avoid repetitions of unchanging information\. For example -the second and third examples of this section can be merged and rewritten into -the equivalent: - - $F do \ - move \ - the * \ - from /sources \ - into /scratch \ - but not *.html not index \ - the index \ - as pkgIndex.tcl - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[move](\.\./\.\./\.\./\.\./index\.md\#move), -[multi\-file](\.\./\.\./\.\./\.\./index\.md\#multi\_file), -[remove](\.\./\.\./\.\./\.\./index\.md\#remove) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fileutil/paths.md Index: embedded/md/tcllib/files/modules/fileutil/paths.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/paths.md +++ embedded/md/tcllib/files/modules/fileutil/paths.md @@ -1,100 +0,0 @@ - -[//000000001]: # (fileutil::paths \- ) -[//000000002]: # (Generated from file 'paths\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::paths\(n\) 1 tcllib "") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::paths \- Manage search path pools - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require fileutil::paths ?1? - -[__::fileutil::paths__ *poolName*](#1) -[__poolName__ __method__ ?*arg arg \.\.\.*?](#2) -[*poolName* __add__ *path*](#3) -[*poolName* __clear__](#4) -[*poolName* __paths__](#5) -[*poolName* __remove__ *path*](#6) - -# <a name='description'></a>DESCRIPTION - -Provides a snit class whose instances manage a pool of \(search\) paths\. - -# <a name='section2'></a>API - -The main command provides construction of search path pools: - - - <a name='1'></a>__::fileutil::paths__ *poolName* - - Creates a new, empty pool of search paths with an associated global Tcl - command whose name is *poolName*\. It may be used to invoke various - operations on the pool\. It has the following general form: - - * <a name='2'></a>__poolName__ __method__ ?*arg arg \.\.\.*? - - __method__ and *arg*uments determine the exact behavior of the - command\. - - If *poolName* is specified as __%AUTO%__ a unique name will be - generated by the package itself\. The result of the command is the - fully\-qualified name of the instance command\. - -The following commands are possible for pool objects: - - - <a name='3'></a>*poolName* __add__ *path* - - Adds the *path* to the pool\. Nothing is done if the *path* is already - known to the pool\. The result of the command is the empty string\. - - - <a name='4'></a>*poolName* __clear__ - - Clears the entire pool\. In other words, removes all paths from it\. The - result of the command is the empty string\. - - - <a name='5'></a>*poolName* __paths__ - - Returns the list of all paths known to the pool, in the order they were - added\. - - - <a name='6'></a>*poolName* __remove__ *path* - - Removes the *path* from the pool, if it is known to the pool\. Unknown - paths are ignored without error\. The result of the command is the empty - string\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. DELETED embedded/md/tcllib/files/modules/fileutil/traverse.md Index: embedded/md/tcllib/files/modules/fileutil/traverse.md ================================================================== --- embedded/md/tcllib/files/modules/fileutil/traverse.md +++ embedded/md/tcllib/files/modules/fileutil/traverse.md @@ -1,209 +0,0 @@ - -[//000000001]: # (fileutil\_traverse \- file utilities) -[//000000002]: # (Generated from file 'traverse\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil\_traverse\(n\) 0\.6 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil\_traverse \- Iterative directory traversal - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OPTIONS](#section2) - - - [Warnings and Incompatibilities](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.3 -package require fileutil::traverse ?0\.6? -package require fileutil -package require control - -[__::fileutil::traverse__ ?*objectName*? *path* ?*option* *value*\.\.\.?](#1) -[__$traverser__ __command__ ?*arg arg \.\.\.*?](#2) -[__$traverser__ __files__](#3) -[__$traverser__ __foreach__ *filevar* *script*](#4) -[__$traverser__ __next__ *filevar*](#5) - -# <a name='description'></a>DESCRIPTION - -This package provides objects for the programmable traversal of directory -hierarchies\. The main command exported by the package is: - - - <a name='1'></a>__::fileutil::traverse__ ?*objectName*? *path* ?*option* *value*\.\.\.? - - The command creates a new traversal object with an associated global Tcl - command whose name is *objectName*\. This command may be used to invoke - various operations on the traverser\. If the string __%AUTO%__ is used as - the *objectName* then a unique name will be generated by the package - itself\. - - Regarding the recognized options see section [OPTIONS](#section2)\. Note - that all these options can be set only during the creation of the traversal - object\. Changing them later is not possible and causes errors to be thrown - if attempted\. - - The object command has the following general form: - - * <a name='2'></a>__$traverser__ __command__ ?*arg arg \.\.\.*? - - *Command* and its *arg*uments determine the exact behavior of the - object\. - -The following commands are possible for traversal objects: - - - <a name='3'></a>__$traverser__ __files__ - - This method is the most highlevel one provided by traversal objects\. When - invoked it returns a list containing the names of all files and directories - matching the current configuration of the traverser\. - - - <a name='4'></a>__$traverser__ __foreach__ *filevar* *script* - - The highlevel __files__ method \(see above\) is based on this mid\-level - method\. When invoked it finds all files and directories matching per the - current configuration and executes the *script* for each path\. The current - path under consideration is stored in the variable named by *filevar*\. - Both variable and script live / are executed in the context of the caller of - the method\. In the method __files__ the script simply saves the found - paths into the list to return\. - - - <a name='5'></a>__$traverser__ __next__ *filevar* - - This is the lowest possible interface to the traverser, the core all higher - methods are built on\. When invoked it returns a boolean value indicating - whether it found a path matching the current configuration \(__True__\), - or not \(__False__\)\. If a path was found it is stored into the variable - named by *filevar*, in the context of the caller\. - - The __foreach__ method simply calls this method in a loop until it - returned __False__\. This method is exposed so that we are also able to - incrementally traverse a directory hierarchy in an event\-based manner\. - - Note that the traverser does follow symbolic links, except when doing so - would cause it to enter a link\-cycle\. In other words, the command takes care - to *not* lose itself in infinite loops upon encountering circular link - structures\. Note that even links which are not followed will still appear in - the result\. - -# <a name='section2'></a>OPTIONS - - - __\-prefilter__ command\_prefix - - This callback is executed for directories\. Its result determines if the - traverser recurses into the directory or not\. The default is to always - recurse into all directories\. The callback is invoked with a single - argument, the *absolute* path of the directory, and has to return a - boolean value, __True__ when the directory passes the filter, and - __False__ if not\. - - - __\-filter__ command\_prefix - - This callback is executed for all paths\. Its result determines if the - current path is a valid result, and returned by __next__\. The default is - to accept all paths as valid\. The callback is invoked with a single - argument, the *absolute* path to check, and has to return a boolean value, - __True__ when the path passes the filter, and __False__ if not\. - - - __\-errorcmd__ command\_prefix - - This callback is executed for all paths the traverser has trouble with\. Like - being unable to change into them, get their status, etc\. The default is to - ignore any such problems\. The callback is invoked with a two arguments, the - *absolute* path for which the error occured, and the error message\. Errors - thrown by the filter callbacks are handled through this callback too\. Errors - thrown by the error callback itself are not caught and ignored, but allowed - to pass to the caller, i\.e\. however invoked the __next__\. Any other - results from the callback are ignored\. - -# <a name='section3'></a>Warnings and Incompatibilities - - - __0\.4\.4__ - - In this version the traverser's broken system for handling symlinks was - replaced with one working correctly and properly enumerating all the legal - non\-cyclic paths under a base directory\. - - While correct this means that certain pathological directory hierarchies - with cross\-linked sym\-links will now take about O\(n\*\*2\) time to enumerate - whereas the original broken code managed O\(n\) due to its brokenness\. - - A concrete example and extreme case is the "/sys" hierarchy under Linux - where some hundred devices exist under both "/sys/devices" and "/sys/class" - with the two sub\-hierarchies linking to the other, generating millions of - legal paths to enumerate\. The structure, reduced to three devices, roughly - looks like - - /sys/class/tty/tty0 --> ../../dev/tty0 - /sys/class/tty/tty1 --> ../../dev/tty1 - /sys/class/tty/tty2 --> ../../dev/tty1 - - /sys/dev/tty0/bus - /sys/dev/tty0/subsystem --> ../../class/tty - /sys/dev/tty1/bus - /sys/dev/tty1/subsystem --> ../../class/tty - /sys/dev/tty2/bus - /sys/dev/tty2/subsystem --> ../../class/tty - - When having to handle such a pathological hierarchy it is recommended to use - the __\-prefilter__ option to prevent the traverser from following - symbolic links, like so: - - package require fileutil::traverse - - proc NoLinks {fileName} { - if {[string equal [file type $fileName] link]} { - return 0 - } - return 1 - } - - fileutil::traverse T /sys/devices -prefilter NoLinks - T foreach p { - puts $p - } - T destroy - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[directory traversal](\.\./\.\./\.\./\.\./index\.md\#directory\_traversal), -[traversal](\.\./\.\./\.\./\.\./index\.md\#traversal) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/ftp/ftp.md Index: embedded/md/tcllib/files/modules/ftp/ftp.md ================================================================== --- embedded/md/tcllib/files/modules/ftp/ftp.md +++ embedded/md/tcllib/files/modules/ftp/ftp.md @@ -1,425 +0,0 @@ - -[//000000001]: # (ftp \- ftp client) -[//000000002]: # (Generated from file 'ftp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (ftp\(n\) 2\.4\.13 tcllib "ftp client") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -ftp \- Client\-side tcl implementation of the ftp protocol - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [BUGS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.2 -package require ftp ?2\.4\.13? - -[__::ftp::Open__ *server* *user* *passwd* ?*options*?](#1) -[__::ftp::Close__ *handle*](#2) -[__::ftp::Cd__ *handle* *directory*](#3) -[__::ftp::Pwd__ *handle*](#4) -[__::ftp::Type__ *handle* ?__ascii|binary|tenex__?](#5) -[__::ftp::List__ *handle* ?*pattern*?](#6) -[__::ftp::NList__ *handle* ?*directory*?](#7) -[__::ftp::FileSize__ *handle* *file*](#8) -[__::ftp::ModTime__ *handle* *file*](#9) -[__::ftp::Delete__ *handle* *file*](#10) -[__::ftp::Rename__ *handle* *from* *to*](#11) -[__::ftp::Put__ *handle* \(*local* | \-data *data* | \-channel *chan*\) ?*remote*?](#12) -[__::ftp::Append__ *handle* \(*local* | \-data *data* | \-channel *chan*\) ?*remote*?](#13) -[__::ftp::Get__ *handle* *remote* ?\(*local* | \-variable *varname* | \-channel *chan*\)?](#14) -[__::ftp::Reget__ *handle* *remote* ?*local*? ?*from*? ?*to*?](#15) -[__::ftp::Newer__ *handle* *remote* ?*local*?](#16) -[__::ftp::MkDir__ *handle* *directory*](#17) -[__::ftp::RmDir__ *handle* *directory*](#18) -[__::ftp::Quote__ *handle* *arg1* *arg2* *\.\.\.*](#19) -[__::ftp::DisplayMsg__ *handle* *msg* ?*state*?](#20) - -# <a name='description'></a>DESCRIPTION - -The ftp package provides the client side of the ftp protocol as specified in RFC -959 -\([http://www\.rfc\-editor\.org/rfc/rfc959\.txt](http://www\.rfc\-editor\.org/rfc/rfc959\.txt)\)\. -The package implements both active \(default\) and passive ftp sessions\. - -A new ftp session is started with the __::ftp::Open__ command\. To shutdown -an existing ftp session use __::ftp::Close__\. All other commands are -restricted to usage in an an open ftp session\. They will generate errors if they -are used out of context\. The ftp package includes file and directory -manipulating commands for remote sites\. To perform the same operations on the -local site use commands built into the core, like __cd__ or -__[file](\.\./\.\./\.\./\.\./index\.md\#file)__\. - -The output of the package is controlled by two state variables, -__::ftp::VERBOSE__ and __::ftp::DEBUG__\. Setting __::ftp::VERBOSE__ -to "1" forces the package to show all responses from a remote server\. The -default value is "0"\. Setting __::ftp::DEBUG__ to "1" enables debugging and -forces the package to show all return codes, states, state changes and "real" -ftp commands\. The default value is "0"\. - -The command __::ftp::DisplayMsg__ is used to show the different messages -from the ftp session\. The setting of __::ftp::VERBOSE__ determines if this -command is called or not\. The current implementation of the command uses the -__[log](\.\./log/log\.md)__ package of tcllib to write the messages to -their final destination\. This means that the behaviour of -__::ftp::DisplayMsg__ can be customized without changing its implementation\. -For more radical changes overwriting its implementation by the application is of -course still possible\. Note that the default implementation honors the option -__\-output__ to __::ftp::Open__ for a session specific log command\. - -*Caution*: The default implementation logs error messages like all other -messages\. If this behaviour is changed to throwing an error instead all commands -in the API will change their behaviour too\. In such a case they will not return -a failure code as described below but pass the thrown error to their caller\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::ftp::Open__ *server* *user* *passwd* ?*options*? - - This command is used to start a FTP session by establishing a control - connection to the FTP server\. The defaults are used for any option not - specified by the caller\. - - The command takes a host name *server*, a user name *user* and a - password *password* as its parameters and returns a session handle that is - an integer number greater than or equal to "0", if the connection is - successfully established\. Otherwise it returns "\-1"\. The *server* - parameter must be the name or internet address \(in dotted decimal notation\) - of the ftp server to connect to\. The *user* and *passwd* parameters must - contain a valid user name and password to complete the login process\. - - The options overwrite some default values or set special abilities: - - * __\-blocksize__ *size* - - The blocksize is used during data transfer\. At most *size* bytes are - transfered at once\. The default value for this option is 4096\. The - package will evaluate the __\-progress callback__ for the session - after the transfer of each block\. - - * __\-timeout__ *seconds* - - If *seconds* is non\-zero, then __::ftp::Open__ sets up a timeout - which will occur after the specified number of seconds\. The default - value is 600\. - - * __\-port__ *number* - - The port *number* specifies an alternative remote port on the ftp - server on which the ftp service resides\. Most ftp services listen for - connection requests on the default port 21\. Sometimes, usually for - security reasons, port numbers other than 21 are used for ftp - connections\. - - * __\-mode__ *mode* - - The transfer *mode* option determines if a file transfer occurs in - __active__ or __passive__ mode\. In passive mode the client will - ask the ftp server to listen on a data port and wait for the connection - rather than to initiate the process by itself when a data transfer - request comes in\. Passive mode is normally a requirement when accessing - sites via a firewall\. The default mode is __active__\. - - * __\-progress__ *callback* - - This *callback* is evaluated whenever a block of data was transfered\. - See the option __\-blocksize__ for how to specify the size of the - transfered blocks\. - - When evaluating the *callback* one argument is appended to the - callback script, the current accumulated number of bytes transferred so - far\. - - * __\-command__ *callback* - - Specifying this option places the connection into asynchronous mode\. The - *callback* is evaluated after the completion of any operation\. When an - operation is running no further operations must be started until a - callback has been received for the currently executing operation\. - - When evaluating the *callback* several arguments are appended to the - callback script, namely the keyword of the operation that has completed - and any additional arguments specific to the operation\. If an error - occurred during the execution of the operation the callback is given the - keyword __error__\. - - * __\-output__ *callback* - - This option has no default\. If it is set the default implementation of - __::ftp::DisplayMsg__ will use its value as command prefix to log - all internal messages\. The callback will have three arguments appended - to it before evaluation, the id of the session, the message itself, and - the connection state, in this order\. - - - <a name='2'></a>__::ftp::Close__ *handle* - - This command terminates the specified ftp session\. If no file transfer is in - progress, the server will close the control connection immediately\. If a - file transfer is in progress however, the control connection will remain - open until the transfers completes\. When that happens the server will write - the result response for the transfer to it and close the connection - afterward\. - - - <a name='3'></a>__::ftp::Cd__ *handle* *directory* - - This command changes the current working directory on the ftp server to a - specified target *directory*\. The command returns 1 if the current working - directory was successfully changed to the specified directory or 0 if it - fails\. The target directory can be - - * a subdirectory of the current directory, - - * Two dots, __\.\.__ \(as an indicator for the parent directory of the - current directory\) - - * or a fully qualified path to a new working directory\. - - - <a name='4'></a>__::ftp::Pwd__ *handle* - - This command returns the complete path of the current working directory on - the ftp server, or an empty string in case of an error\. - - - <a name='5'></a>__::ftp::Type__ *handle* ?__ascii|binary|tenex__? - - This command sets the ftp file transfer type to either __ascii__, - __binary__, or __tenex__\. The command always returns the currently - set type\. If called without type no change is made\. - - Currently only __ascii__ and __binary__ types are supported\. There - is some early \(alpha\) support for Tenex mode\. The type __ascii__ is - normally used to convert text files into a format suitable for text editors - on the platform of the destination machine\. This mainly affects end\-of\-line - markers\. The type __binary__ on the other hand allows the undisturbed - transfer of non\-text files, such as compressed files, images and - executables\. - - - <a name='6'></a>__::ftp::List__ *handle* ?*pattern*? - - This command returns a human\-readable list of files\. Wildcard expressions - such as "\*\.tcl" are allowed\. If *pattern* refers to a specific directory, - then the contents of that directory are returned\. If the *pattern* is not - a fully\-qualified path name, the command lists entries relative to the - current remote directory\. If no *pattern* is specified, the contents of - the current remote directory is returned\. - - The listing includes any system\-dependent information that the server - chooses to include\. For example most UNIX systems produce output from the - command __ls \-l__\. The command returns the retrieved information as a - tcl list with one item per entry\. Empty lines and UNIX's "total" lines are - ignored and not included in the result as reported by this command\. - - If the command fails an empty list is returned\. - - - <a name='7'></a>__::ftp::NList__ *handle* ?*directory*? - - This command has the same behavior as the __::ftp::List__ command, - except that it only retrieves an abbreviated listing\. This means only file - names are returned in a sorted list\. - - - <a name='8'></a>__::ftp::FileSize__ *handle* *file* - - This command returns the size of the specified *file* on the ftp server\. - If the command fails an empty string is returned\. - - *ATTENTION\!* It will not work properly when in ascii mode and is not - supported by all ftp server implementations\. - - - <a name='9'></a>__::ftp::ModTime__ *handle* *file* - - This command retrieves the time of the last modification of the *file* on - the ftp server as a system dependent integer value in seconds or an empty - string if an error occurred\. Use the built\-in command __clock__ to - convert the retrieves value into other formats\. - - - <a name='10'></a>__::ftp::Delete__ *handle* *file* - - This command deletes the specified *file* on the ftp server\. The command - returns 1 if the specified file was successfully deleted or 0 if it failed\. - - - <a name='11'></a>__::ftp::Rename__ *handle* *from* *to* - - This command renames the file *from* in the current directory of the ftp - server to the specified new file name *to*\. This new file name must not be - the same as any existing subdirectory or file name\. The command returns 1 if - the specified file was successfully renamed or 0 if it failed\. - - - <a name='12'></a>__::ftp::Put__ *handle* \(*local* | \-data *data* | \-channel *chan*\) ?*remote*? - - This command transfers a local file *local* to a remote file *remote* on - the ftp server\. If the file parameters passed to the command do not fully - qualified path names the command will use the current directory on local and - remote host\. If the remote file name is unspecified, the server will use the - name of the local file as the name of the remote file\. The command returns 1 - to indicate a successful transfer and 0 in the case of a failure\. - - If __\-data__ *data* is specified instead of a local file, the system - will not transfer a file, but the *data* passed into it\. In this case the - name of the remote file has to be specified\. - - If __\-channel__ *chan* is specified instead of a local file, the - system will not transfer a file, but read the contents of the channel - *chan* and write this to the remote file\. In this case the name of the - remote file has to be specified\. After the transfer *chan* will be closed\. - - - <a name='13'></a>__::ftp::Append__ *handle* \(*local* | \-data *data* | \-channel *chan*\) ?*remote*? - - This command behaves like __::ftp::Puts__, but appends the transfered - information to the remote file\. If the file did not exist on the server it - will be created\. - - - <a name='14'></a>__::ftp::Get__ *handle* *remote* ?\(*local* | \-variable *varname* | \-channel *chan*\)? - - This command retrieves a remote file *remote* on the ftp server and stores - its contents into the local file *local*\. If the file parameters passed to - the command are not fully qualified path names the command will use the - current directory on local and remote host\. If the local file name is - unspecified, the server will use the name of the remote file as the name of - the local file\. The command returns 1 to indicate a successful transfer and - 0 in the case of a failure\. The command will throw an error if the directory - the file *local* is to be placed in does not exist\. - - If __\-variable__ *varname* is specified, the system will store the - retrieved data into the variable *varname* instead of a file\. - - If __\-channel__ *chan* is specified, the system will write the - retrieved data into the channel *chan* instead of a file\. The system will - *not* close *chan* after the transfer, this is the responsibility of the - caller to __::ftp::Get__\. - - - <a name='15'></a>__::ftp::Reget__ *handle* *remote* ?*local*? ?*from*? ?*to*? - - This command behaves like __::ftp::Get__, except that if local file - *local* exists and is smaller than remote file *remote*, the local file - is presumed to be a partially transferred copy of the remote file and the - transfer is continued from the apparent point of failure\. The command will - throw an error if the directory the file *local* is to be placed in does - not exist\. This command is useful when transferring very large files over - networks that tend to drop connections\. - - Specifying the additional byte offsets *from* and *to* will cause the - command to change its behaviour and to download exactly the specified slice - of the remote file\. This mode is possible only if a local destination is - explicitly provided\. Omission of *to* leads to downloading till the end of - the file\. - - - <a name='16'></a>__::ftp::Newer__ *handle* *remote* ?*local*? - - This command behaves like __::ftp::Get__, except that it retrieves the - remote file only if the modification time of the remote file is more recent - than the file on the local system\. If the file does not exist on the local - system, the remote file is considered newer\. The command will throw an error - if the directory the file *local* is to be placed in does not exist\. - - - <a name='17'></a>__::ftp::MkDir__ *handle* *directory* - - This command creates the specified *directory* on the ftp server\. If the - specified path is relative the new directory will be created as a - subdirectory of the current working directory\. Else the created directory - will have the specified path name\. The command returns 1 to indicate a - successful creation of the directory and 0 in the case of a failure\. - - - <a name='18'></a>__::ftp::RmDir__ *handle* *directory* - - This command removes the specified directory on the ftp server\. The remote - directory has to be empty or the command will fail\. The command returns 1 to - indicate a successful removal of the directory and 0 in the case of a - failure\. - - - <a name='19'></a>__::ftp::Quote__ *handle* *arg1* *arg2* *\.\.\.* - - This command is used to send an arbitrary ftp command to the server\. It - cannot be used to obtain a directory listing or for transferring files\. It - is included to allow an application to execute commands on the ftp server - which are not provided by this package\. The arguments are sent verbatim, - i\.e\. as is, with no changes\. - - In contrast to the other commands in this package this command will not - parse the response it got from the ftp server but return it verbatim to the - caller\. - - - <a name='20'></a>__::ftp::DisplayMsg__ *handle* *msg* ?*state*? - - This command is used by the package itself to show the different messages - from the ftp sessions\. The package itself declares this command very simple, - writing the messages to __stdout__ \(if __::ftp::VERBOSE__ was set, - see below\) and throwing tcl errors for error messages\. It is the - responsibility of the application to overwrite it as needed\. A state - variable for different states assigned to different colors is recommended by - the author\. The package __[log](\.\./log/log\.md)__ is useful for this\. - - - __::ftp::VERBOSE__ - - A state variable controlling the output of the package\. Setting - __::ftp::VERBOSE__ to "1" forces the package to show all responses from - a remote server\. The default value is "0"\. - - - __::ftp::DEBUG__ - - A state variable controlling the output of ftp\. Setting __::ftp::DEBUG__ - to "1" enables debugging and forces the package to show all return codes, - states, state changes and "real" ftp commands\. The default value is "0"\. - -# <a name='section3'></a>BUGS - -The correct execution of many commands depends upon the proper behavior by the -remote server, network and router configuration\. - -An update command placed in the procedure __::ftp::DisplayMsg__ may run into -persistent errors or infinite loops\. The solution to this problem is to use -__update idletasks__ instead of -__[update](\.\./\.\./\.\./\.\./index\.md\#update)__\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ftp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[ftpd](\.\./ftpd/ftpd\.md), [mime](\.\./mime/mime\.md), -[pop3](\.\./pop3/pop3\.md), [smtp](\.\./mime/smtp\.md) - -# <a name='keywords'></a>KEYWORDS - -[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[net](\.\./\.\./\.\./\.\./index\.md\#net), [rfc 959](\.\./\.\./\.\./\.\./index\.md\#rfc\_959) - -# <a name='category'></a>CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/ftp/ftp_geturl.md Index: embedded/md/tcllib/files/modules/ftp/ftp_geturl.md ================================================================== --- embedded/md/tcllib/files/modules/ftp/ftp_geturl.md +++ embedded/md/tcllib/files/modules/ftp/ftp_geturl.md @@ -1,102 +0,0 @@ - -[//000000001]: # (ftp::geturl \- ftp client) -[//000000002]: # (Generated from file 'ftp\_geturl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (ftp::geturl\(n\) 0\.2\.2 tcllib "ftp client") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -ftp::geturl \- Uri handler for ftp urls - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.2 -package require ftp::geturl ?0\.2\.2? - -[__::ftp::geturl__ *url*](#1) - -# <a name='description'></a>DESCRIPTION - -This package provides a command which wraps around the client side of the -*[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)* protocol provided by package -__[ftp](ftp\.md)__ to allow the retrieval of urls using the -*[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)* schema\. - -# <a name='section2'></a>API - - - <a name='1'></a>__::ftp::geturl__ *url* - - This command can be used by the generic command __::uri::geturl__ \(See - package __[uri](\.\./uri/uri\.md)__\) to retrieve the contents of ftp - urls\. Internally it uses the commands of the package - __[ftp](ftp\.md)__ to fulfill the request\. - - The contents of a *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)* url are defined as - follows: - - * *[file](\.\./\.\./\.\./\.\./index\.md\#file)* - - The contents of the specified file itself\. - - * *directory* - - A listing of the contents of the directory in key value notation where - the file name is the key and its attributes the associated value\. - - * *link* - - The attributes of the link, including the path it refers to\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ftp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[ftpd](\.\./ftpd/ftpd\.md), [mime](\.\./mime/mime\.md), -[pop3](\.\./pop3/pop3\.md), [smtp](\.\./mime/smtp\.md) - -# <a name='keywords'></a>KEYWORDS - -[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[net](\.\./\.\./\.\./\.\./index\.md\#net), [rfc 959](\.\./\.\./\.\./\.\./index\.md\#rfc\_959) - -# <a name='category'></a>CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/ftpd/ftpd.md Index: embedded/md/tcllib/files/modules/ftpd/ftpd.md ================================================================== --- embedded/md/tcllib/files/modules/ftpd/ftpd.md +++ embedded/md/tcllib/files/modules/ftpd/ftpd.md @@ -1,312 +0,0 @@ - -[//000000001]: # (ftpd \- Tcl FTP Server Package) -[//000000002]: # (Generated from file 'ftpd\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (ftpd\(n\) 1\.3 tcllib "Tcl FTP Server Package") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -ftpd \- Tcl FTP server implementation - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [CALLBACKS](#section3) - - - [VARIABLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.3 -package require ftpd ?1\.3? - -[__::ftpd::server__ ?*myaddr*?](#1) -[__::ftpd::config__ ?*option value*? ?*option value \.\.\.*?](#2) -[*fsCmd* __append__ *path*](#3) -[*fsCmd* __delete__ *path* *channel*](#4) -[*fsCmd* __dlist__ *path* *style* *channel*](#5) -[*fsCmd* __exists__ *path*](#6) -[*fsCmd* __mkdir__ *path* *channel*](#7) -[*fsCmd* __mtime__ *path* *channel*](#8) -[*fsCmd* __permissions__ *path*](#9) -[*fsCmd* __rename__ *path* *newpath* *channel*](#10) -[*fsCmd* __retr__ *path*](#11) -[*fsCmd* __rmdir__ *path* *channel*](#12) -[*fsCmd* __size__ *path* *channel*](#13) -[*fsCmd* __store__ *path*](#14) - -# <a name='description'></a>DESCRIPTION - -The __ftpd__ package provides a simple Tcl\-only server library for the FTP -protocol as specified in RFC 959 -\([http://www\.rfc\-editor\.org/rfc/rfc959\.txt](http://www\.rfc\-editor\.org/rfc/rfc959\.txt)\)\. -It works by listening on the standard FTP socket\. Most server errors are -returned as error messages with the appropriate code attached to them\. Since the -server code for the ftp daemon is executed in the event loop, it is possible -that a __bgerror__ will be thrown on the server if there are problems with -the code in the module\. - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__::ftpd::server__ ?*myaddr*? - - Open a listening socket to listen to and accept ftp connections\. myaddr is - an optional argument\. *myaddr* is the domain\-style name or numerical IP - address of the client\-side network interface to use for the connection\. - - - <a name='2'></a>__::ftpd::config__ ?*option value*? ?*option value \.\.\.*? - - The value is always the name of the command to call as the callback\. The - option specifies which callback should be configured\. See section - [CALLBACKS](#section3) for descriptions of the arguments and return - values for each of the callbacks\. - - * \-authIpCmd *proc* - - Callback to authenticate new connections based on the ip\-address of the - peer\. - - * \-authUsrCmd *proc* - - Callback to authenticate new connections based on the user logging in - \(and the users password\)\. - - * \-authFileCmd *proc* - - Callback to accept or deny a users access to read and write to a - specific path or file\. - - * \-logCmd *proc* - - Callback for log information generated by the FTP engine\. - - * \-fsCmd *proc* - - Callback to connect the engine to the filesystem it operates on\. - - * \-closeCmd *proc* - - Callback to be called when a connection is closed\. This allows the - embedding application to perform its own cleanup operations\. - - * \-xferDoneCmd *proc* - - Callback for transfer completion notification\. In other words, it is - called whenever a transfer of data to or from the client has completed\. - -# <a name='section3'></a>CALLBACKS - - - __authIpCmd__ callback - - The authIpCmd receives the ip\-address of the peer attempting to connect to - the ftp server as its argument\. It returns a 1 to allow users from the - specified IP to attempt to login and a 0 to reject the login attempt from - the specified IP\. - - - __authUsrCmd__ callback - - The authUsrCmd receives the username and password as its two arguments\. It - returns a 1 to accept the attempted login to the ftpd and a 0 to reject the - attempted login\. - - - __authFileCmd__ callback - - The authFileCmd receives the user \(that is currently logged in\), the path or - filename that is about to be read or written, and __read__ or - __write__ as its three arguments\. It returns a 1 to allow the path or - filename to be read or written, and a 0 to reject the attempted read or - write with a permissions error code\. - - - __logCmd__ callback - - The logCmd receives a severity and a message as its two arguments\. The - severities used within the ftpd package are __note__, __debug__, and - __error__\. The logCmd doesn't return anything\. - - - __fsCmd__ callback - - The fsCmd receives a subcommand, a filename or path, and optional additional - arguments \(depending on the subcommand\)\. - - The subcommands supported by the fsCmd are: - - * <a name='3'></a>*fsCmd* __append__ *path* - - The append subcommand receives the filename to append to as its - argument\. It returns a writable tcl channel as its return value\. - - * <a name='4'></a>*fsCmd* __delete__ *path* *channel* - - The delete subcommand receives the filename to delete, and a channel to - write to as its two arguments\. The file specified is deleted and the - appropriate ftp message is written to the channel that is passed as the - second argument\. The delete subcommand returns nothing\. - - * <a name='5'></a>*fsCmd* __dlist__ *path* *style* *channel* - - The dlist subcommand receives the path that it should list the files - that are in, the style in which the files should be listed which is - either __nlst__ or __list__, and a channel to write to as its - three arguments\. The files in the specified path are printed to the - specified channel one per line\. If the style is __nlst__ only the - name of the file is printed to the channel\. If the style is __list__ - then the file permissions, number of links to the file, the name of the - user that owns the file, the name of the group that owns the file, the - size \(in bytes\) of the file, the modify time of the file, and the - filename are printed out to the channel in a formatted space separated - format\. The __dlist__ subcommand returns nothing\. - - * <a name='6'></a>*fsCmd* __exists__ *path* - - The exists subcommand receives the name of a file to check the existence - of as its only argument\. The exists subcommand returns a 1 if the path - specified exists and the path is not a directory\. - - * <a name='7'></a>*fsCmd* __mkdir__ *path* *channel* - - The mkdir subcommand receives the path of a directory to create and a - channel to write to as its two arguments\. The mkdir subcommand creates - the specified directory if necessary and possible\. The mkdir subcommand - then prints the appropriate success or failure message to the channel\. - The mkdir subcommand returns nothing\. - - * <a name='8'></a>*fsCmd* __mtime__ *path* *channel* - - The mtime subcommand receives the path of a file to check the modify - time on and a channel as its two arguments\. If the file exists the mtime - is printed to the channel in the proper FTP format, otherwise an - appropriate error message and code are printed to the channel\. The mtime - subcommand returns nothing\. - - * <a name='9'></a>*fsCmd* __permissions__ *path* - - The permissions subcommand receives the path of a file to retrieve the - permissions of\. The permissions subcommand returns the octal file - permissions of the specified file\. The file is expected to exist\. - - * <a name='10'></a>*fsCmd* __rename__ *path* *newpath* *channel* - - The rename subcommand receives the path of the current file, the new - file path, and a channel to write to as its three arguments\. The rename - subcommand renames the current file to the new file path if the path to - the new file exists, and then prints out the appropriate message to the - channel\. If the new file path doesn't exist the appropriate error - message is printed to the channel\. The rename subcommand returns - nothing\. - - * <a name='11'></a>*fsCmd* __retr__ *path* - - The retr subcommand receives the path of a file to read as its only - argument\. The retr subcommand returns a readable channel that the - specified file can be read from\. - - * <a name='12'></a>*fsCmd* __rmdir__ *path* *channel* - - The rmdir subcommand receives the path of a directory to remove and a - channel to write to as its two arguments\. The rmdir subcommand removes - the specified directory \(if possible\) and prints the appropriate message - to the channel \(which may be an error if the specified directory does - not exist or is not empty\)\. The rmdir subcommand returns nothing\. - - * <a name='13'></a>*fsCmd* __size__ *path* *channel* - - The size subcommand receives the path of a file to get the size \(in - bytes\) of and a channel to write to as its two arguments\. The size - subcommand prints the appropriate code and the size of the file if the - specified path is a file, otherwise an appropriate error code and - message are printed to the channel\. The size subcommand returns nothing\. - - * <a name='14'></a>*fsCmd* __store__ *path* - - The store subcommand receives the path of a file to write as its only - argument\. The store subcommand returns a writable channel\. - - - __closeCmd__ - - The __closeCmd__ receives no arguments when it is invoked, and any - return value it may generate is discarded\. - - - __xferDoneCmd__ sock sock2 file bytes filename err - - The __xferDoneCmd__ receives six arguments when invoked\. These are, in - this order, the channel handle of the control socket for the connection, the - channel handle of the data socket used for the transfer \(already closed\), - the handle of the channel containing the transfered file, the number of - bytes transfered, the path of the file which was transfered, and a \(possibly - empty\) error message\. Any return value it may generate is discarded\. - -# <a name='section4'></a>VARIABLES - - - __::ftpd::cwd__ - - The current working directory for a session when someone first connects to - the FTPD or when the __REIN__ ftp command is received\. - - - __::ftpd::contact__ - - The e\-mail address of the person that is the contact for the ftp server\. - This address is printed out as part of the response to the __FTP HELP__ - command\. - - - __::ftpd::port__ - - The port that the ftp server should listen on\. If port is specified as zero, - the operating system will allocate an unused port for use as a server - socket; afterwards, the variable will contain the port number that was - allocated\. - - - __::ftpd::welcome__ - - The message that is printed out when the user first connects to the ftp - server\. - - - __::ftpd::CurrentSocket__ - - Accessible to all callbacks and all filesystem commands \(which are a special - form of callback\) and contains the handle of the socket channel which was - active when the callback was invoked\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ftpd* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp), [ftpd](\.\./\.\./\.\./\.\./index\.md\#ftpd), -[ftpserver](\.\./\.\./\.\./\.\./index\.md\#ftpserver), [rfc -959](\.\./\.\./\.\./\.\./index\.md\#rfc\_959), -[services](\.\./\.\./\.\./\.\./index\.md\#services) - -# <a name='category'></a>CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/fumagic/cfront.md Index: embedded/md/tcllib/files/modules/fumagic/cfront.md ================================================================== --- embedded/md/tcllib/files/modules/fumagic/cfront.md +++ embedded/md/tcllib/files/modules/fumagic/cfront.md @@ -1,113 +0,0 @@ - -[//000000001]: # (fileutil::magic::cfront \- file utilities) -[//000000002]: # (Generated from file 'cfront\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::magic::cfront\(n\) 1\.2\.0 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::magic::cfront \- Generator core for compiler of magic\(5\) files - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require fileutil::magic::cfront ?1\.2\.0? -package require fileutil::magic::cgen ?1\.2\.0? -package require fileutil::magic::rt ?1\.2\.0? -package require struct::list -package require fileutil - -[__::fileutil::magic::cfront::compile__ *path*\.\.\.](#1) -[__::fileutil::magic::cfront::procdef__ *procname* *path*\.\.\.](#2) -[__::fileutil::magic::cfront::install__ *path*\.\.\.](#3) - -# <a name='description'></a>DESCRIPTION - -This package provides the frontend of a compiler of magic\(5\) files into -recognizers based on the __[fileutil::magic::rt](rtcore\.md)__ recognizer -runtime package\. For the generator backed used by this compiler see the package -__[fileutil::magic::cgen](cgen\.md)__\. - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__::fileutil::magic::cfront::compile__ *path*\.\.\. - - This command takes the paths of one or more files and directories and - compiles all the files, and the files in all the directories into a single - recognizer for all the file types specified in these files\. - - All the files have to be in the format specified by magic\(5\)\. - - The result of the command is a Tcl script containing the generated - recognizer\. - - - <a name='2'></a>__::fileutil::magic::cfront::procdef__ *procname* *path*\.\.\. - - This command behaves like __::fileutil::magic::cfront::compile__ with - regard to the specified path arguments, then wraps the resulting recognizer - script into a procedure named *procname*, puts code setting up the - namespace of *procname* in front, and returns the resulting script\. - - - <a name='3'></a>__::fileutil::magic::cfront::install__ *path*\.\.\. - - This command uses __::fileutil::magic::cfront::procdef__ to compile each - of the paths into a recognizer procedure and installs the result in the - current interpreter\. - - The name of each new procedure is derived from the name of the - file/directory used in its creation, with file/directory "FOO" causing the - creation of procedure __::fileutil::magic::/FOO::run__\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil :: magic* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -file\(1\), [fileutil](\.\./fileutil/fileutil\.md), magic\(5\) - -# <a name='keywords'></a>KEYWORDS - -[file recognition](\.\./\.\./\.\./\.\./index\.md\#file\_recognition), [file -type](\.\./\.\./\.\./\.\./index\.md\#file\_type), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[mime](\.\./\.\./\.\./\.\./index\.md\#mime), [type](\.\./\.\./\.\./\.\./index\.md\#type) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fumagic/cgen.md Index: embedded/md/tcllib/files/modules/fumagic/cgen.md ================================================================== --- embedded/md/tcllib/files/modules/fumagic/cgen.md +++ embedded/md/tcllib/files/modules/fumagic/cgen.md @@ -1,107 +0,0 @@ - -[//000000001]: # (fileutil::magic::cgen \- file utilities) -[//000000002]: # (Generated from file 'cgen\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::magic::cgen\(n\) 1\.2\.0 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::magic::cgen \- Generator core for compiler of magic\(5\) files - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require fileutil::magic::cgen ?1\.2\.0? -package require fileutil::magic::rt ?1\.2\.0? -package require struct::tree -package require struct::list - -[__::fileutil::magic::cgen::2tree__ *script*](#1) -[__::fileutil::magic::cgen::treedump__ *tree*](#2) -[__::fileutil::magic::cgen::treegen__ *tree* *node*](#3) - -# <a name='description'></a>DESCRIPTION - -This package provides the generator backend for a compiler of magic\(5\) files -into recognizers based on the __[fileutil::magic::rt](rtcore\.md)__ -recognizer runtime package\. For the compiler frontend using this generator see -the package __[fileutil::magic::cfront](cfront\.md)__\. - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__::fileutil::magic::cgen::2tree__ *script* - - This command converts the recognizer specified by the *script* into a tree - and returns the object command of that tree as its result\. It uses the - package __[struct::tree](\.\./struct/struct\_tree\.md)__ for the tree\. - - The *script* is in the format specified by magic\(5\)\. - - - <a name='2'></a>__::fileutil::magic::cgen::treedump__ *tree* - - This command takes a *tree* as generated by - __::fileutil::magic::cgen::2tree__ and returns a string encoding the - tree for human consumption, to aid in debugging\. - - - <a name='3'></a>__::fileutil::magic::cgen::treegen__ *tree* *node* - - This command takes a *tree* as generated by - __::fileutil::magic::cgen::2tree__ and returns a Tcl script, the - recognizer for the file types represented by the sub\-tree rooted at the - *node*\. The generated script makes extensive use of the commands provided - by the recognizer runtime package - __[fileutil::magic::rt](rtcore\.md)__ to perform its duties\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil :: magic* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -file\(1\), [fileutil](\.\./fileutil/fileutil\.md), magic\(5\) - -# <a name='keywords'></a>KEYWORDS - -[file recognition](\.\./\.\./\.\./\.\./index\.md\#file\_recognition), [file -type](\.\./\.\./\.\./\.\./index\.md\#file\_type), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[mime](\.\./\.\./\.\./\.\./index\.md\#mime), [type](\.\./\.\./\.\./\.\./index\.md\#type) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fumagic/filetypes.md Index: embedded/md/tcllib/files/modules/fumagic/filetypes.md ================================================================== --- embedded/md/tcllib/files/modules/fumagic/filetypes.md +++ embedded/md/tcllib/files/modules/fumagic/filetypes.md @@ -1,93 +0,0 @@ - -[//000000001]: # (fileutil::magic::filetype \- file utilities) -[//000000002]: # (Generated from file 'filetypes\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::magic::filetype\(n\) 2\.0 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::magic::filetype \- Procedures implementing file\-type recognition - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [REFERENCES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.6 -package require fileutil::magic::filetype ?2\.0? - -[__::fileutil::magic::filetype__ *filename*](#1) - -# <a name='description'></a>DESCRIPTION - -This package provides a command for the recognition of file types in pure Tcl\. - -The core part of the recognizer was generated from a "magic\(5\)" file containing -the checks to perform to recognize files, and associated file\-types\. - -*Beware\!* This recognizer is large, about 752 Kilobyte of generated Tcl code\. - - - <a name='1'></a>__::fileutil::magic::filetype__ *filename* - - This command is similar to the command __fileutil::fileType__\. - - Returns a list containing a list of descriptions, a list of mimetype - components, and a list file extensions\. Returns an empty string if the file - content is not recognized\. - -# <a name='section2'></a>REFERENCES - - 1. [File\(1\) sources](ftp://ftp\.astron\.com/pub/file/) This site contains - the current sources for the file command, including the magic definitions - used by it\. The latter were used by us to generate this recognizer\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil :: magic* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -file\(1\), [fileutil](\.\./fileutil/fileutil\.md), magic\(5\) - -# <a name='keywords'></a>KEYWORDS - -[file recognition](\.\./\.\./\.\./\.\./index\.md\#file\_recognition), [file -type](\.\./\.\./\.\./\.\./index\.md\#file\_type), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[type](\.\./\.\./\.\./\.\./index\.md\#type) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/fumagic/rtcore.md Index: embedded/md/tcllib/files/modules/fumagic/rtcore.md ================================================================== --- embedded/md/tcllib/files/modules/fumagic/rtcore.md +++ embedded/md/tcllib/files/modules/fumagic/rtcore.md @@ -1,319 +0,0 @@ - -[//000000001]: # (fileutil::magic::rt \- file utilities) -[//000000002]: # (Generated from file 'rtcore\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (fileutil::magic::rt\(n\) 2\.0 tcllib "file utilities") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -fileutil::magic::rt \- Runtime core for file type recognition engines written in -pure Tcl - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [NUMERIC TYPES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require fileutil::magic::rt ?2\.0? - -[__::fileutil::magic::rt::>__](#1) -[__::fileutil::magic::rt::<__](#2) -[__::fileutil::magic::rt::open__ *filename*](#3) -[__::fileutil::magic::rt::close__](#4) -[__::fileutil::magic::rt::file\_start__ *name*](#5) -[__::fileutil::magic::rt::result__ ?*msg*?](#6) -[__::fileutil::magic::rt::resultv__ ?*msg*?](#7) -[__::fileutil::magic::rt::emit__ *msg*](#8) -[__::fileutil::magic::rt::offset__ *where*](#9) -[__::fileutil::magic::rt::Nv__ *type* *offset* ?*qual*?](#10) -[__::fileutil::magic::rt::N__ *type* *offset* *comp* *val* ?*qual*?](#11) -[__::fileutil::magic::rt::Nvx__ *type* *offset* ?*qual*?](#12) -[__::fileutil::magic::rt::Nx__ *type* *offset* *comp* *val* ?*qual*?](#13) -[__::fileutil::magic::rt::S__ *offset* *comp* *val* ?*qual*?](#14) -[__::fileutil::magic::rt::Sx__ *offset* *comp* *val* ?*qual*?](#15) -[__::fileutil::magic::rt::L__ *newlevel*](#16) -[__::fileutil::magic::rt::I__ *base* *type* *delta*](#17) -[__::fileutil::magic::rt::R__ *offset*](#18) -[__::fileutil::magic::rt::U__ *fileindex* *name*](#19) - -# <a name='description'></a>DESCRIPTION - -This package provides the runtime core for file type recognition engines written -in pure Tcl and is thus used by all other packages in this module, i\.e\. the two -frontend packages __fileutil::magic::mimetypes__ and -__fileutil::magic::filetypes__, and the two engine compiler packages -__[fileutil::magic::cgen](cgen\.md)__ and -__[fileutil::magic::cfront](cfront\.md)__\. - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__::fileutil::magic::rt::>__ - - Shorthand for __incr level__\. - - - <a name='2'></a>__::fileutil::magic::rt::<__ - - Shorthand for __incr level \-1__\. - - - <a name='3'></a>__::fileutil::magic::rt::open__ *filename* - - This command initializes the runtime and prepares the file *filename* for - use by the system\. This command has to be invoked first, before any other - command of this package\. - - The command returns the channel handle of the opened file as its result\. - - - <a name='4'></a>__::fileutil::magic::rt::close__ - - This command closes the last file opened via - __::fileutil::magic::rt::open__ and shuts the runtime down\. This command - has to be invoked last, after the file has been dealt with completely\. - Afterward another invokation of __::fileutil::magic::rt::open__ is - required to process another file\. - - This command returns the empty string as its result\. - - - <a name='5'></a>__::fileutil::magic::rt::file\_start__ *name* - - This command marks the start of a magic file when debugging\. It returns the - empty string as its result\. - - - <a name='6'></a>__::fileutil::magic::rt::result__ ?*msg*? - - This command returns the current result and stops processing\. - - If *msg* is specified its text is added to the result before it is - returned\. See __::fileutil::magic::rt::emit__ for the allowed special - character sequences\. - - - <a name='7'></a>__::fileutil::magic::rt::resultv__ ?*msg*? - - This command returns the current result\. In contrast to - __::fileutil::magic::rt::result__ processing continues\. - - If *msg* is specified its text is added to the result before it is - returned\. See __::fileutil::magic::rt::emit__ for the allowed special - character sequences\. - - - <a name='8'></a>__::fileutil::magic::rt::emit__ *msg* - - This command adds the text *msg* to the result buffer\. The message may - contain the following special character sequences\. They will be replaced - with buffered values before the message is added to the result\. The command - returns the empty string as its result\. - - * __\\b__ - - This sequence is removed - - * __%s__ - - Replaced with the last buffered string value\. - - * __%ld__ - - Replaced with the last buffered numeric value\. - - * __%d__ - - See above\. - - - <a name='9'></a>__::fileutil::magic::rt::offset__ *where* - - - <a name='10'></a>__::fileutil::magic::rt::Nv__ *type* *offset* ?*qual*? - - This command fetches the numeric value with *type* from the absolute - location *offset* and returns it as its result\. The fetched value is - further stored in the numeric buffer\. - - If *qual* is specified it is considered to be a mask and applied to the - fetched value before it is stored and returned\. It has to have the form of a - partial Tcl bit\-wise expression, i\.e\. - - & number - - For example: - - Nv lelong 0 &0x8080ffff - - For the possible types see section [NUMERIC TYPES](#section3)\. - - - <a name='11'></a>__::fileutil::magic::rt::N__ *type* *offset* *comp* *val* ?*qual*? - - This command behaves mostly like __::fileutil::magic::rt::Nv__, except - that it compares the fetched and masked value against *val* as specified - with *comp* and returns the result of that comparison\. - - The argument *comp* has to contain one of Tcl's comparison operators, and - the comparison made will be - - <val> <comp> <fetched-and-masked-value> - - The special comparison operator __x__ signals that no comparison should - be done, or, in other words, that the fetched value will always match - *val*\. - - - <a name='12'></a>__::fileutil::magic::rt::Nvx__ *type* *offset* ?*qual*? - - This command behaves like __::fileutil::magic::rt::Nv__, except that it - additionally remembers the location in the file after the fetch in the - calling context, for the current level, for later use by - __::fileutil::magic::rt::R__\. - - - <a name='13'></a>__::fileutil::magic::rt::Nx__ *type* *offset* *comp* *val* ?*qual*? - - This command behaves like __::fileutil::magic::rt::N__, except that it - additionally remembers the location in the file after the fetch in the - calling context, for the current, for later use by - __::fileutil::magic::rt::R__\. - - - <a name='14'></a>__::fileutil::magic::rt::S__ *offset* *comp* *val* ?*qual*? - - This command behaves like __::fileutil::magic::rt::N__, except that it - fetches and compares strings, not numeric data\. The fetched value is also - stored in the internal string buffer instead of the numeric buffer\. - - - <a name='15'></a>__::fileutil::magic::rt::Sx__ *offset* *comp* *val* ?*qual*? - - This command behaves like __::fileutil::magic::rt::S__, except that it - additionally remembers the location in the file after the fetch in the - calling context, for the current level, for later use by - __::fileutil::magic::rt::R__\. - - - <a name='16'></a>__::fileutil::magic::rt::L__ *newlevel* - - This command sets the current level in the calling context to *newlevel*\. - The command returns the empty string as its result\. - - - <a name='17'></a>__::fileutil::magic::rt::I__ *base* *type* *delta* - - This command handles base locations specified indirectly through the - contents of the inspected file\. It returns the sum of *delta* and the - value of numeric *type* fetched from the absolute location *base*\. - - For the possible types see section [NUMERIC TYPES](#section3)\. - - - <a name='18'></a>__::fileutil::magic::rt::R__ *offset* - - This command handles base locations specified relative to the end of the - last field one level above\. - - In other words, the command computes an absolute location in the file based - on the relative *offset* and returns it as its result\. The base the offset - is added to is the last location remembered for the level in the calling - context\. - - - <a name='19'></a>__::fileutil::magic::rt::U__ *fileindex* *name* - - Use a named test script at the current level\. - -# <a name='section3'></a>NUMERIC TYPES - - - __byte__ - - 8\-bit integer - - - __short__ - - 16\-bit integer, stored in native endianess - - - __beshort__ - - see above, stored in big endian - - - __leshort__ - - see above, stored in small/little endian - - - __long__ - - 32\-bit integer, stored in native endianess - - - __belong__ - - see above, stored in big endian - - - __lelong__ - - see above, stored in small/little endian - -All of the types above exit in an unsigned form as well\. The type names are the -same, with the character "u" added as prefix\. - - - __date__ - - 32\-bit integer timestamp, stored in native endianess - - - __bedate__ - - see above, stored in big endian - - - __ledate__ - - see above, stored in small/little endian - - - __ldate__ - - 32\-bit integer timestamp, stored in native endianess - - - __beldate__ - - see above, stored in big endian - - - __leldate__ - - see above, stored in small/little endian - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *fileutil :: magic* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -file\(1\), [fileutil](\.\./fileutil/fileutil\.md), magic\(5\) - -# <a name='keywords'></a>KEYWORDS - -[file recognition](\.\./\.\./\.\./\.\./index\.md\#file\_recognition), [file -type](\.\./\.\./\.\./\.\./index\.md\#file\_type), [file -utilities](\.\./\.\./\.\./\.\./index\.md\#file\_utilities), -[mime](\.\./\.\./\.\./\.\./index\.md\#mime), [type](\.\./\.\./\.\./\.\./index\.md\#type) - -# <a name='category'></a>CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/generator/generator.md Index: embedded/md/tcllib/files/modules/generator/generator.md ================================================================== --- embedded/md/tcllib/files/modules/generator/generator.md +++ embedded/md/tcllib/files/modules/generator/generator.md @@ -1,511 +0,0 @@ - -[//000000001]: # (generator \- Tcl Generator Commands) -[//000000002]: # (Generated from file 'generator\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (generator\(n\) 0\.1 tcllib "Tcl Generator Commands") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -generator \- Procedures for creating and using generators\. - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PRELUDE](#section3) - - - [BUGS, IDEAS, FEEDBACK](#section4) - - - [Keywords](#keywords) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.6 -package require generator ?0\.1? - -[__generator__ __define__ *name* *params* *body*](#1) -[__generator__ __yield__ *arg* ?*args\.\.*?](#2) -[__generator__ __foreach__ *varList* *generator* *varList* *generator* ?\.\.\.? *body*](#3) -[__generator__ __next__ *generator* ?*varName\.\.*?](#4) -[__generator__ __exists__ *generator*](#5) -[__generator__ __names__](#6) -[__generator__ __destroy__ ?*generator\.\.*?](#7) -[__generator__ __finally__ *cmd* ?*arg\.\.*?](#8) -[__generator__ __from__ *format* *value*](#9) -[__generator__ __to__ *format* *generator*](#10) -[__generator__ __map__ *function* *generator*](#11) -[__generator__ __filter__ *predicate* *generator*](#12) -[__generator__ __reduce__ *function* *zero* *generator*](#13) -[__generator__ __foldl__ *function* *zero* *generator*](#14) -[__generator__ __foldr__ *function* *zero* *generator*](#15) -[__generator__ __all__ *predicate* *generator*](#16) -[__generator__ __and__ *generator*](#17) -[__generator__ __any__ *generator*](#18) -[__generator__ __concat__ *generator* ?*generator\.\.*?](#19) -[__generator__ __concatMap__ *function* *generator*](#20) -[__generator__ __drop__ *n* *generator*](#21) -[__generator__ __dropWhile__ *predicate* *generator*](#22) -[__generator__ __contains__ *element* *generator*](#23) -[__generator__ __foldl1__ *function* *generator*](#24) -[__generator__ __foldli__ *function* *zero* *generator*](#25) -[__generator__ __foldri__ *function* *zero* *generator*](#26) -[__generator__ __head__ *generator*](#27) -[__generator__ __tail__ *generator*](#28) -[__generator__ __init__ *generator*](#29) -[__generator__ __takeList__ *n* *generator*](#30) -[__generator__ __take__ *n* *generator*](#31) -[__generator__ __iterate__ *function* *init*](#32) -[__generator__ __last__ *generator*](#33) -[__generator__ __length__ *generator*](#34) -[__generator__ __or__ *predicate* *generator*](#35) -[__generator__ __product__ *generator*](#36) -[__generator__ __repeat__ *n* *value\.\.*](#37) -[__generator__ __sum__ *generator*](#38) -[__generator__ __takeWhile__ *predicate* *generator*](#39) -[__generator__ __splitWhen__ *predicate* *generator*](#40) -[__generator__ __scanl__ *function* *zero* *generator*](#41) - -# <a name='description'></a>DESCRIPTION - -The __generator__ package provides commands to define and iterate over -generator expressions\. A *generator* is a command that returns a sequence of -values\. However, unlike an ordinary command that returns a list, a generator -*yields* each value and then suspends, allowing subsequent values to be -fetched on\-demand\. As such, generators can be used to efficiently iterate over a -set of values, without having to generate all answers in\-memory\. Generators can -be used to iterate over elements of a data structure, or rows in the result set -of a database query, or to decouple producer/consumer software designs such as -parsers and tokenizers, or to implement sophisticated custom control strategies -such as backtracking search\. Generators reduce the need to implement custom -control structures, as many such structures can be recast as generators, leading -to both a simpler implementation and a more standardised interface\. The -generator mechanism is built on top of the Tcl 8\.6 coroutine mechanism\. - -The package exports a single ensemble command, __generator__\. All -functionality is provided as subcommands of this command\. The core subcommands -of the package are __define__, __yield__, and __foreach__\. The -__define__ command works like Tcl's -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ command, but creates a generator -procedure; that is, a procedure that returns a generator when called\. The -generator itself is a command that can be called multiple times: each time it -returns the next value in the generated series\. When the series has been -exhausted, the generator command returns an empty list and then destroys itself\. -Rather than manually call a generator, however, the package also provides a -flexible __foreach__ command that loops through the values of one or more -generators\. This loop construct mimicks the functionality of the built\-in Tcl -__[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__ command, including handling -multiple return values and looping over multiple generators at once\. Writing a -generator is also a simple task, much like writing a normal procedure: simply -use the __define__ command to define the generator, and then call -__yield__ instead of __[return](\.\./\.\./\.\./\.\./index\.md\#return)__\. For -example, we can define a generator for looping through the integers in a -particular range: - - generator define range {n m} { - for {set i $n} {$i <= $m} {incr i} { generator yield $i } - } - generator foreach x [range 1 10] { - puts "x = $x" - } - -The above example will print the numbers from 1 to 10 in sequence, as you would -expect\. The difference from a normal loop over a list is that the numbers are -only generated as they are needed\. If we insert a break into the loop then any -remaining numbers in the sequence would never be generated\. To illustrate, we -can define a generator that produces the sequence of natural numbers: an -infinite series\. A normal procedure would never return trying to produce this -series as a list\. By using a generator we only have to generate those values -which are actually used: - - generator define nats {} { - while 1 { generator yield [incr nat] } - } - generator foreach n [nats] { - if {$n > 100} { break } - } - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__generator__ __define__ *name* *params* *body* - - Creates a new generator procedure\. The arguments to the command are - identical to those for __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__: a - *name*, a list of parameters, and a body\. The parameter list format is - identical to a procedure\. In particular, default values and the ?args? - syntax can be used as usual\. Each time the resulting generator procedure is - called it creates a new generator command \(coroutine\) that will yield a list - of values on each call\. Each result from a generator is guaranteed to be a - non\-empty list of values\. When a generator is exhausted it returns an empty - list and then destroys itself to free up resources\. It is an error to - attempt to call an exhausted generator as the command no longer exists\. - - - <a name='2'></a>__generator__ __yield__ *arg* ?*args\.\.*? - - Used in the definition of a generator, this command returns the next set of - values to the consumer\. Once the __yield__ command has been called the - generator will suspend to allow the consumer to process that value\. When the - next value is requested, the generator will resume as if the yield command - had just returned, and can continue processing to yield the next result\. The - __yield__ command must be called with at least one argument, but can be - called with multiple arguments, in which case this is equivalent to calling - __yield__ once for each argument\. - - - <a name='3'></a>__generator__ __foreach__ *varList* *generator* *varList* *generator* ?\.\.\.? *body* - - Loops through one or more generators, assigning the next values to variables - and then executing the loop body\. Works much like the built\-in - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__ command, but working - with generators rather than lists\. Multiple generators can be iterated over - in parallel, and multiple results can be retrieved from a single generator - at once\. Like the built\-in - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__, the loop will continue - until all of the generators have been exhausted: variables for generators - that are exhausted early will be set to the empty string\. - - The __foreach__ command will automatically clean\-up all of the - generators at the end of the loop, regardless of whether the loop terminated - early or not\. This behaviour is provided as a convenience to avoid having to - explicitly clean up a generator in the usual cases\. Generators can however - be destroyed before the end of the loop, in which case the loop will - continue as normal until all the other generators have been destroyed or - exhausted\. - - The __foreach__ command does not take a snapshot of the generator\. Any - changes in the state of the generator made inside the loop or by other code - will affect the state of the loop\. In particular, if the code in the loop - invokes the generator to manually retrieve the next element, this element - will then be excluded from the loop, and the next iteration will continue - from the element after that one\. Care should be taken to avoid concurrent - updates to generators unless this behaviour is required \(e\.g\., in argument - processing\)\. - - - <a name='4'></a>__generator__ __next__ *generator* ?*varName\.\.*? - - Manually retrieves the next values from a generator\. One value is retrieved - for each variable supplied and assigned to the corresponding variable\. If - the generator becomes exhausted at any time then any remaining variables are - set to the empty string\. - - - <a name='5'></a>__generator__ __exists__ *generator* - - Returns 1 if the generator \(still\) exists, or 0 otherwise\. - - - <a name='6'></a>__generator__ __names__ - - Returns a list of all currently existing generator commands\. - - - <a name='7'></a>__generator__ __destroy__ ?*generator\.\.*? - - Destroys one or more generators, freeing any associated resources\. - - - <a name='8'></a>__generator__ __finally__ *cmd* ?*arg\.\.*? - - Used in the definition of a generator procedure, this command arranges for a - resource to be cleaned up whenever the generator is destroyed, either - explicitly or implicitly when the generator is exhausted\. This command can - be used like a __finally__ block in the - __[try](\.\./try/tcllib\_try\.md)__ command, except that it is tied to - the life\-cycle of the generator rather than to a particular scope\. For - example, if we create a generator to iterate over the lines in a text file, - we can use __finally__ to ensure that the file is closed whenever the - generator is destroyed: - - generator define lines file { - set in [open $file] - # Ensure file is always closed - generator finally close $in - while {[gets $in line] >= 0} { - generator yield $line - } - } - generator foreach line [lines /etc/passwd] { - puts "[incr count]: $line" - if {$count > 10} { break } - } - # File will be closed even on early exit - - If you create a generator that consumes another generator \(such as the - standard __map__ and __filter__ generators defined later\), then you - should use a __finally__ command to ensure that this generator is - destroyed when its parent is\. For example, the __map__ generator is - defined as follows: - - generator define map {f xs} { - generator finally generator destroy $xs - generator foreach x $xs { generator yield [{*}$f $x] } - } - - - <a name='9'></a>__generator__ __from__ *format* *value* - - Creates a generator from a data structure\. Currently, supported formats are - __list__, __dict__, or __string__\. The list format yields each - element in turn\. For dictionaries, each key and value are yielded - separately\. Finally, strings are yielded a character at a time\. - - - <a name='10'></a>__generator__ __to__ *format* *generator* - - Converts a generator into a data structure\. This is the reverse operation of - the __from__ command, and supports the same data structures\. The two - operations obey the following identity laws \(where __=__ is interpreted - appropriately\): - - [generator to $fmt [generator from $fmt $value]] = $value - [generator from $fmt [generator to $fmt $gen]] = $gen - -# <a name='section3'></a>PRELUDE - -The following commands are provided as a standard library of generator -combinators and functions that perform convenience operations on generators\. The -functions in this section are loosely modelled on the equivalent functions from -the Haskell Prelude\. *Warning:* most of the functions in this prelude destroy -any generator arguments they are passed as a side\-effect\. If you want to have -persistent generators, see the streams library\. - - - <a name='11'></a>__generator__ __map__ *function* *generator* - - Apply a function to every element of a generator, returning a new generator - of the results\. This is the classic map function from functional - programming, applied to generators\. For example, we can generate all the - square numbers using the following code \(where __nats__ is defined as - earlier\): - - proc square x { expr {$x * $x} } - generator foreach n [generator map square [nats]] { - puts "n = $n" - if {$n > 1000} { break } - } - - - <a name='12'></a>__generator__ __filter__ *predicate* *generator* - - Another classic functional programming gem\. This command returns a generator - that yields only those items from the argument generator that satisfy the - predicate \(boolean function\)\. For example, if we had a generator - __employees__ that returned a stream of dictionaries representing - people, we could filter all those whose salaries are above 100,000 dollars - \(or whichever currency you prefer\) using a simple filter: - - proc salary> {amount person} { expr {[dict get $person salary] > $amount} } - set fat-cats [generator filter {salary> 100000} $employees] - - - <a name='13'></a>__generator__ __reduce__ *function* *zero* *generator* - - This is the classic left\-fold operation\. This command takes a function, an - initial value, and a generator of values\. For each element in the generator - it applies the function to the current accumulator value \(the *zero* - argument initially\) and that element, and then uses the result as the new - accumulator value\. This process is repeated through the entire generator - \(eagerly\) and the final accumulator value is then returned\. If we consider - the function to be a binary operator, and the zero argument to be the left - identity element of that operation, then we can consider the __reduce__ - command as *folding* the operator between each successive pair of values - in the generator in a left\-associative fashion\. For example, the sum of a - sequence of numbers can be calculated by folding a __\+__ operator - between them, with 0 as the identity: - - # sum xs = reduce + 0 xs - # sum [range 1 5] = reduce + 0 [range 1 5] - # = reduce + [+ 0 1] [range 2 5] - # = reduce + [+ 1 2] [range 3 5] - # = ... - # = reduce + [+ 10 5] <empty> - # = ((((0+1)+2)+3)+4)+5 - # = 15 - proc + {a b} { expr {$a + $b} } - proc sum gen { generator reduce + 0 $gen } - puts [sum [range 1 10]] - - The __reduce__ operation is an extremely useful one, and a great variety - of different operations can be defined using it\. For example, we can define - a factorial function as the product of a range using generators\. This - definition is both very clear and also quite efficient \(in both memory and - running time\): - - proc * {x y} { expr {$x * $y} } - proc prod gen { generator reduce * 0 $gen } - proc fac n { prod [range 1 $n] } - - However, while the __reduce__ operation is efficient for finite - generators, care should be taken not to apply it to an infinite generator, - as this will result in an infinite loop: - - sum [nats]; # Never returns - - - <a name='14'></a>__generator__ __foldl__ *function* *zero* *generator* - - This is an alias for the __reduce__ command\. - - - <a name='15'></a>__generator__ __foldr__ *function* *zero* *generator* - - This is the right\-associative version of __reduce__\. This operation is - generally inefficient, as the entire generator needs to be evaluated into - memory \(as a list\) before the reduction can commence\. In an eagerly - evaluated language like Tcl, this operation has limited use, and should be - avoided if possible\. - - - <a name='16'></a>__generator__ __all__ *predicate* *generator* - - Returns true if all elements of the generator satisfy the given predicate\. - - - <a name='17'></a>__generator__ __and__ *generator* - - Returns true if all elements of the generator are true \(i\.e\., takes the - logical conjunction of the elements\)\. - - - <a name='18'></a>__generator__ __any__ *generator* - - Returns true if any of the elements of the generator are true \(i\.e\., logical - disjunction\)\. - - - <a name='19'></a>__generator__ __concat__ *generator* ?*generator\.\.*? - - Returns a generator which is the concatenation of each of the argument - generators\. - - - <a name='20'></a>__generator__ __concatMap__ *function* *generator* - - Given a function which maps a value to a series of values, and a generator - of values of that type, returns a generator of all of the results in one - flat series\. Equivalent to __concat__ applied to the result of - __map__\. - - - <a name='21'></a>__generator__ __drop__ *n* *generator* - - Removes the given number of elements from the front of the generator and - returns the resulting generator with those elements removed\. - - - <a name='22'></a>__generator__ __dropWhile__ *predicate* *generator* - - Removes all elements from the front of the generator that satisfy the - predicate\. - - - <a name='23'></a>__generator__ __contains__ *element* *generator* - - Returns true if the generator contains the given element\. Note that this - will destroy the generator\! - - - <a name='24'></a>__generator__ __foldl1__ *function* *generator* - - A version of __foldl__ that takes the *zero* argument from the first - element of the generator\. Therefore this function is only valid on non\-empty - generators\. - - - <a name='25'></a>__generator__ __foldli__ *function* *zero* *generator* - - A version of __foldl__ that supplies the integer index of each element - as the first argument to the function\. The first element in the generator at - this point is given index 0\. - - - <a name='26'></a>__generator__ __foldri__ *function* *zero* *generator* - - Right\-associative version of __foldli__\. - - - <a name='27'></a>__generator__ __head__ *generator* - - Returns the first element of the generator\. - - - <a name='28'></a>__generator__ __tail__ *generator* - - Removes the first element of the generator, returning the rest\. - - - <a name='29'></a>__generator__ __init__ *generator* - - Returns a new generator consisting of all elements except the last of the - argument generator\. - - - <a name='30'></a>__generator__ __takeList__ *n* *generator* - - Returns the next *n* elements of the generator as a list\. If not enough - elements are left in the generator, then just the remaining elements are - returned\. - - - <a name='31'></a>__generator__ __take__ *n* *generator* - - Returns the next *n* elements of the generator as a new generator\. The old - generator is destroyed\. - - - <a name='32'></a>__generator__ __iterate__ *function* *init* - - Returns an infinite generator formed by repeatedly applying the function to - the initial argument\. For example, the Fibonacci numbers can be defined as - follows: - - proc fst pair { lindex $pair 0 } - proc snd pair { lindex $pair 1 } - proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] } - proc fibs {} { generator map fst [generator iterate nextFib {0 1}] } - - - <a name='33'></a>__generator__ __last__ *generator* - - Returns the last element of the generator \(if it exists\)\. - - - <a name='34'></a>__generator__ __length__ *generator* - - Returns the length of the generator, destroying it in the process\. - - - <a name='35'></a>__generator__ __or__ *predicate* *generator* - - Returns 1 if any of the elements of the generator satisfy the predicate\. - - - <a name='36'></a>__generator__ __product__ *generator* - - Returns the product of the numbers in a generator\. - - - <a name='37'></a>__generator__ __repeat__ *n* *value\.\.* - - Returns a generator that consists of *n* copies of the given elements\. The - special value *Inf* can be used to generate an infinite sequence\. - - - <a name='38'></a>__generator__ __sum__ *generator* - - Returns the sum of the values in the generator\. - - - <a name='39'></a>__generator__ __takeWhile__ *predicate* *generator* - - Returns a generator of the first elements in the argument generator that - satisfy the predicate\. - - - <a name='40'></a>__generator__ __splitWhen__ *predicate* *generator* - - Splits the generator into lists of elements using the predicate to identify - delimiters\. The resulting lists are returned as a generator\. Elements - matching the delimiter predicate are discarded\. For example, to split up a - generator using the string "|" as a delimiter: - - set xs [generator from list {a | b | c}] - generator split {string equal "|"} $xs ;# returns a then b then c - - - <a name='41'></a>__generator__ __scanl__ *function* *zero* *generator* - - Similar to __foldl__, but returns a generator of all of the intermediate - values for the accumulator argument\. The final element of this generator is - equivalent to __foldl__ called on the same arguments\. - -# <a name='section4'></a>BUGS, IDEAS, FEEDBACK - -Please report any errors in this document, or in the package it describes, to -[Neil Madden](mailto:nem@cs\.nott\.ac\.uk)\. - -# <a name='keywords'></a>KEYWORDS - -[control structure](\.\./\.\./\.\./\.\./index\.md\#control\_structure), -[coroutine](\.\./\.\./\.\./\.\./index\.md\#coroutine), -[filter](\.\./\.\./\.\./\.\./index\.md\#filter), -[foldl](\.\./\.\./\.\./\.\./index\.md\#foldl), -[foldr](\.\./\.\./\.\./\.\./index\.md\#foldr), -[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach), -[generator](\.\./\.\./\.\./\.\./index\.md\#generator), -[iterator](\.\./\.\./\.\./\.\./index\.md\#iterator), -[map](\.\./\.\./\.\./\.\./index\.md\#map), [reduce](\.\./\.\./\.\./\.\./index\.md\#reduce), -[scanl](\.\./\.\./\.\./\.\./index\.md\#scanl) DELETED embedded/md/tcllib/files/modules/gpx/gpx.md Index: embedded/md/tcllib/files/modules/gpx/gpx.md ================================================================== --- embedded/md/tcllib/files/modules/gpx/gpx.md +++ embedded/md/tcllib/files/modules/gpx/gpx.md @@ -1,207 +0,0 @@ - -[//000000001]: # (gpx \- GPS eXchange Format \(GPX\)) -[//000000002]: # (Generated from file 'gpx\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010, Keith Vetter <kvetter@gmail\.com>) -[//000000004]: # (gpx\(n\) 0\.9 tcllib "GPS eXchange Format \(GPX\)") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -gpx \- Extracts waypoints, tracks and routes from GPX files - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [DATA STRUCTURES](#section3) - - - [EXAMPLE](#section4) - - - [REFERENCES](#section5) - - - [AUTHOR](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require gpx ?0\.9? - -[__::gpx::Create__ *gpxFilename* ?*rawXML*?](#1) -[__::gpx::Cleanup__ *token*](#2) -[__::gpx::GetGPXMetadata__ *token*](#3) -[__::gpx::GetWaypointCount__ *token*](#4) -[__::gpx::GetAllWaypoints__ *token*](#5) -[__::gpx::GetTrackCount__ *token*](#6) -[__::gpx::GetTrackMetadata__ *token* *whichTrack*](#7) -[__::gpx::GetTrackPoints__ *token* *whichTrack*](#8) -[__::gpx::GetRouteCount__ *token*](#9) -[__::gpx::GetRouteMetadata__ *token* *whichRoute*](#10) -[__::gpx::GetRoutePoints__ *token* *whichRoute*](#11) - -# <a name='description'></a>DESCRIPTION - -This module parses and extracts waypoints, tracks, routes and metadata from a -GPX \(GPS eXchange\) file\. Both GPX version 1\.0 and 1\.1 are supported\. - -# <a name='section2'></a>COMMANDS - - - <a name='1'></a>__::gpx::Create__ *gpxFilename* ?*rawXML*? - - The __::gpx::Create__ is the first command called to process GPX data\. - It takes the GPX data from either the *rawXML* parameter if present or - from the contents of *gpxFilename*, and parses it using *tdom*\. It - returns a token value that is used by all the other commands\. - - - <a name='2'></a>__::gpx::Cleanup__ *token* - - This procedure cleans up resources associated with *token*\. It is - *strongly* recommended that you call this function after you are done with - a given GPX file\. Not doing so will result in memory not being freed, and if - your app calls __::gpx::Create__ enough times, the memory leak could - cause a performance hit\.\.\.or worse\. - - - <a name='3'></a>__::gpx::GetGPXMetadata__ *token* - - This procedure returns a dictionary of the metadata associated with the GPX - data identified by *token*\. The format of the metadata dictionary is - described below, but keys *version* and *creator* will always be - present\. - - - <a name='4'></a>__::gpx::GetWaypointCount__ *token* - - This procedure returns the number of waypoints defined in the GPX data - identified by *token*\. - - - <a name='5'></a>__::gpx::GetAllWaypoints__ *token* - - This procedure returns the a list of waypoints defined in the GPX data - identified by *token*\. The format of each waypoint item is described - below\. - - - <a name='6'></a>__::gpx::GetTrackCount__ *token* - - This procedure returns the number of tracks defined in the GPX data - identified by *token*\. - - - <a name='7'></a>__::gpx::GetTrackMetadata__ *token* *whichTrack* - - This procedure returns a dictionary of the metadata associated track number - *whichTrack* \(1 based\) in the GPX data identified by *token*\. The format - of the metadata dictionary is described below\. - - - <a name='8'></a>__::gpx::GetTrackPoints__ *token* *whichTrack* - - The procedure returns a list of track points comprising track number - *whichTrack* \(1 based\) in the GPX data identified by *token*\. The format - of the metadata dictionary is described below\. - - - <a name='9'></a>__::gpx::GetRouteCount__ *token* - - This procedure returns the number of routes defined in the GPX data - identified by *token*\. - - - <a name='10'></a>__::gpx::GetRouteMetadata__ *token* *whichRoute* - - This procedure returns a dictionary of the metadata associated route number - *whichRoute* \(1 based\) in the GPX data identified by *token*\. The format - of the metadata dictionary is described below\. - - - <a name='11'></a>__::gpx::GetRoutePoints__ *token* *whichRoute* - - The procedure returns a list of route points comprising route number - *whichRoute* \(1 based\) in the GPX data identified by *token*\. The format - of the metadata dictionary is described below\. - -# <a name='section3'></a>DATA STRUCTURES - - - metadata dictionary - - The metadata associated with either the GPX document, a track, a route, a - waypoint, a track point or route point is returned in a dictionary\. The keys - of that dictionary will be whatever optional GPX elements are present\. The - value for each key depends on the GPX schema for that element\. For example, - the value for a version key will be a string, while for a link key will be a - sub\-dictionary with keys *href* and optionally *text* and *type*\. - - - point item - - Each item in a track or route list of points consists of a list of three - elements: *latitude*, *longitude* and *metadata dictionary*\. - *Latitude* and *longitude* are decimal numbers\. The *metadata - dictionary* format is described above\. For points in a track, typically - there will always be ele \(elevation\) and time metadata keys\. - -# <a name='section4'></a>EXAMPLE - - % set token [::gpx::Create myGpxFile.gpx] - % set version [dict get [::gpx::GetGPXMetadata $token] version] - % set trackCnt [::gpx::GetTrackCount $token] - % set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0] - % lassign $firstPoint lat lon ptMetadata - % puts "first point in the first track is at $lat, $lon" - % if {[dict exists $ptMetadata ele]} { - puts "at elevation [dict get $ptMetadata ele] meters" - } - % ::gpx::Cleanup $token - -# <a name='section5'></a>REFERENCES - - 1. GPX: the GPS Exchange Format - \([http://www\.topografix\.com/gpx\.asp](http://www\.topografix\.com/gpx\.asp)\) - - 1. GPX 1\.1 Schema Documentation - \([http://www\.topografix\.com/GPX/1/1/](http://www\.topografix\.com/GPX/1/1/)\) - - 1. GPX 1\.0 Developer's Manual - \([http://www\.topografix\.com/gpx\_manual\.asp](http://www\.topografix\.com/gpx\_manual\.asp)\) - -# <a name='section6'></a>AUTHOR - -Keith Vetter - -# <a name='section7'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *gpx* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[gps](\.\./\.\./\.\./\.\./index\.md\#gps), [gpx](\.\./\.\./\.\./\.\./index\.md\#gpx) - -# <a name='category'></a>CATEGORY - -File formats - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2010, Keith Vetter <kvetter@gmail\.com> DELETED embedded/md/tcllib/files/modules/grammar_aycock/aycock.md Index: embedded/md/tcllib/files/modules/grammar_aycock/aycock.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_aycock/aycock.md +++ embedded/md/tcllib/files/modules/grammar_aycock/aycock.md @@ -1,178 +0,0 @@ - -[//000000001]: # (grammar::aycock \- Aycock\-Horspool\-Earley parser generator for Tcl) -[//000000002]: # (Generated from file 'aycock\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 by Kevin B\. Kenny <kennykb@acm\.org>) -[//000000004]: # (Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/>) -[//000000005]: # (grammar::aycock\(n\) 1\.0 tcllib "Aycock\-Horspool\-Earley parser generator for Tcl") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::aycock \- Aycock\-Horspool\-Earley parser generator for Tcl - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [OBJECT COMMAND](#section3) - - - [DESCRIPTION](#section4) - - - [EXAMPLE](#section5) - - - [KEYWORDS](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require grammar::aycock ?1\.0? - -[__::aycock::parser__ *grammar* ?__\-verbose__?](#1) -[*parserName* __parse__ *symList* *valList* ?*clientData*?](#2) -[*parserName* __destroy__](#3) -[*parserName* __terminals__](#4) -[*parserName* __nonterminals__](#5) -[*parserName* __save__](#6) - -# <a name='description'></a>DESCRIPTION - -The __grammar::aycock__ package implements a parser generator for the class -of parsers described in John Aycock and R\. Nigel Horspool\. Practical Earley -Parsing\. *The Computer Journal,* *45*\(6\):620\-630, 2002\. -[http://citeseerx\.ist\.psu\.edu/viewdoc/summary?doi=10\.1\.1\.12\.4254](http://citeseerx\.ist\.psu\.edu/viewdoc/summary?doi=10\.1\.1\.12\.4254) - -# <a name='section2'></a>PROCEDURES - -The __grammar::aycock__ package exports the single procedure: - - - <a name='1'></a>__::aycock::parser__ *grammar* ?__\-verbose__? - - Generates a parser for the given *grammar*, and returns its name\. If the - optional __\-verbose__ flag is given, dumps verbose information relating - to the generated parser to the standard output\. The returned parser is an - object that accepts commands as shown in [OBJECT COMMAND](#section3) - below\. - -# <a name='section3'></a>OBJECT COMMAND - - - <a name='2'></a>*parserName* __parse__ *symList* *valList* ?*clientData*? - - Invokes a parser returned from __::aycock::parser__\. *symList* is a - list of grammar symbols representing the terminals in an input string, and - *valList* is a list of their semantic values\. The result is the semantic - value of the entire string when parsed\. - - - <a name='3'></a>*parserName* __destroy__ - - Destroys a parser constructed by __::aycock::parser__\. - - - <a name='4'></a>*parserName* __terminals__ - - Returns a list of terminal symbols that may be presented in the *symList* - argument to the __parse__ object command\. - - - <a name='5'></a>*parserName* __nonterminals__ - - Returns a list of nonterminal symbols that were defined in the parser's - grammar\. - - - <a name='6'></a>*parserName* __save__ - - Returns a Tcl script that will reconstruct the parser without needing all - the mechanism of the parser generator at run time\. The reconstructed parser - depends on a set of commands in the package - __grammar::aycock::runtime__, which is also automatically loaded when - the __grammar::aycock__ package is loaded\. - -# <a name='section4'></a>DESCRIPTION - -The __grammar::aycock::parser__ command accepts a grammar expressed as a Tcl -list\. The list must be structured as the concatenation of a set of *rule*s\. -Each *rule* comprises a variable number of elements in the list: - - - The name of the nonterminal symbol that the rule reduces\. - - - The literal string, __::=__ - - - Zero or more names of terminal or nonterminal symbols that comprise the - right\-hand\-side of the rule\. - - - Finally, a Tcl script to execute when the rule is reduced\. Within the given - script, a variable called __\___ contains a list of the semantic values - of the symbols on the right\-hand side\. The value returned by the script is - expected to be the semantic value of the left\-hand side\. If the - *clientData* parameter was passed to the __parse__ method, it is - available in a variable called __clientData__\. It is permissible for the - script to be the empty string\. In this case, the semantic value of the rule - will be the same as the semantic value of the first symbol on the right\-hand - side\. If the right\-hand side is also empty, the semantic value will be the - empty string\. - -Parsing is done with an Earley parser, which is not terribly efficient in speed -or memory consumption, but which deals effectively with ambiguous grammars\. For -this reason, the __grammar::aycock__ package is perhaps best adapted to -natural\-language processing or the parsing of extraordinarily complex languages -in which ambiguity can be tolerated\. - -# <a name='section5'></a>EXAMPLE - -The following code demonstrates a trivial desk calculator, admitting only -__\+__, __\*__ and parentheses as its operators\. It also shows the format -in which the lexical analyzer is expected to present terminal symbols to the -parser\. - - set p [aycock::parser { - start ::= E {} - E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}} - E ::= T {} - T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}} - T ::= F {} - F ::= NUMBER {} - F ::= ( E ) {lindex $_ 1} - }] - puts [$p parse {( NUMBER + NUMBER ) * ( NUMBER + NUMBER ) } {{} 2 {} 3 {} {} {} 7 {} 1 {}}] - $p destroy - -The example, when run, prints __40__\. - -# <a name='section6'></a>KEYWORDS - -Aycock, Earley, Horspool, parser, compiler - -# <a name='keywords'></a>KEYWORDS - -[ambiguous](\.\./\.\./\.\./\.\./index\.md\#ambiguous), -[aycock](\.\./\.\./\.\./\.\./index\.md\#aycock), -[earley](\.\./\.\./\.\./\.\./index\.md\#earley), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[horspool](\.\./\.\./\.\./\.\./index\.md\#horspool), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2006 by Kevin B\. Kenny <kennykb@acm\.org> -Redistribution permitted under the terms of the Open Publication License <http://www\.opencontent\.org/openpub/> DELETED embedded/md/tcllib/files/modules/grammar_fa/dacceptor.md Index: embedded/md/tcllib/files/modules/grammar_fa/dacceptor.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_fa/dacceptor.md +++ embedded/md/tcllib/files/modules/grammar_fa/dacceptor.md @@ -1,141 +0,0 @@ - -[//000000001]: # (grammar::fa::dacceptor \- Finite automaton operations and usage) -[//000000002]: # (Generated from file 'dacceptor\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::fa::dacceptor\(n\) 0\.1\.1 tcllib "Finite automaton operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::fa::dacceptor \- Create and use deterministic acceptors - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [ACCEPTOR METHODS](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require struct::set -package require grammar::fa::dacceptor ?0\.1\.1? - -[__::grammar::fa::dacceptor__ *daName* *fa* ?__\-any__ *any*?](#1) -[__daName__ *option* ?*arg arg \.\.\.*?](#2) -[*daName* __destroy__](#3) -[*daName* __accept?__ *symbols*](#4) - -# <a name='description'></a>DESCRIPTION - -This package provides a class for acceptors constructed from deterministic -*finite automatons* \(DFA\)\. Acceptors are objects which can be given a string -of symbols and tell if the DFA they are constructed from would *accept* that -string\. For the actual creation of the DFAs the acceptors are based on we have -the packages __[grammar::fa](fa\.md)__ and -__[grammar::fa::op](faop\.md)__\. - -# <a name='section2'></a>API - -The package exports the API described here\. - - - <a name='1'></a>__::grammar::fa::dacceptor__ *daName* *fa* ?__\-any__ *any*? - - Creates a new deterministic acceptor with an associated global Tcl command - whose name is *daName*\. This command may be used to invoke various - operations on the acceptor\. It has the following general form: - - * <a name='2'></a>__daName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - See section [ACCEPTOR METHODS](#section3) for more explanations\. - - The acceptor will be based on the deterministic finite automaton stored - in the object *fa*\. It will keep a copy of the relevant data of the FA - in its own storage, in a form easy to use for its purposes\. This also - means that changes made to the *fa* after the construction of the - acceptor *will not* influence the acceptor\. - - If *any* has been specified, then the acceptor will convert all - symbols in the input which are unknown to the base FA to that symbol - before proceeding with the processing\. - -# <a name='section3'></a>ACCEPTOR METHODS - -All acceptors provide the following methods for their manipulation: - - - <a name='3'></a>*daName* __destroy__ - - Destroys the automaton, including its storage space and associated command\. - - - <a name='4'></a>*daName* __accept?__ *symbols* - - Takes the list of *symbols* and checks if the FA the acceptor is based on - would accept it\. The result is a boolean value\. __True__ is returned if - the symbols are accepted, and __False__ otherwise\. Note that bogus - symbols in the input are either translated to the *any* symbol \(if - specified\), or cause the acceptance test to simply fail\. No errors will be - thrown\. The method will process only just that prefix of the input which is - enough to fully determine \(non\-\)acceptance\. - -# <a name='section4'></a>EXAMPLES - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_fa* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[acceptance](\.\./\.\./\.\./\.\./index\.md\#acceptance), -[acceptor](\.\./\.\./\.\./\.\./index\.md\#acceptor), -[automaton](\.\./\.\./\.\./\.\./index\.md\#automaton), [finite -automaton](\.\./\.\./\.\./\.\./index\.md\#finite\_automaton), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), [regular -grammar](\.\./\.\./\.\./\.\./index\.md\#regular\_grammar), [regular -languages](\.\./\.\./\.\./\.\./index\.md\#regular\_languages), -[state](\.\./\.\./\.\./\.\./index\.md\#state), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2004 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_fa/dexec.md Index: embedded/md/tcllib/files/modules/grammar_fa/dexec.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_fa/dexec.md +++ embedded/md/tcllib/files/modules/grammar_fa/dexec.md @@ -1,211 +0,0 @@ - -[//000000001]: # (grammar::fa::dexec \- Finite automaton operations and usage) -[//000000002]: # (Generated from file 'dexec\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (Copyright © 2007 Bogdan <rftghost@users\.sourceforge\.net>) -[//000000005]: # (grammar::fa::dexec\(n\) 0\.2 tcllib "Finite automaton operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::fa::dexec \- Execute deterministic finite automatons - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [EXECUTOR METHODS](#section3) - - - [EXECUTOR CALLBACK](#section4) - - - [EXAMPLES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require grammar::fa::dexec ?0\.2? - -[__::grammar::fa::dexec__ *daName* *fa* ?__\-any__ *any*? ?__\-command__ *cmdprefix*?](#1) -[__daName__ *option* ?*arg arg \.\.\.*?](#2) -[*daName* __destroy__](#3) -[*daName* __put__ *symbol*](#4) -[*daName* __reset__](#5) -[*daName* __state__](#6) -[*cmdprefix* __error__ *code* *message*](#7) -[*cmdprefix* __final__ *stateid*](#8) -[*cmdprefix* __reset__](#9) -[*cmdprefix* __state__ *stateid*](#10) - -# <a name='description'></a>DESCRIPTION - -This package provides a class for executors constructed from deterministic -*finite automatons* \(DFA\)\. Executors are objects which are given a string of -symbols in a piecemal fashion, perform state transitions and report back when -they enter a final state, or find an error in the input\. For the actual creation -of the DFAs the executors are based on we have the packages -__[grammar::fa](fa\.md)__ and __[grammar::fa::op](faop\.md)__\. - -The objects follow a push model\. Symbols are pushed into the executor, and when -something important happens, i\.e\. error occurs, a state transition, or a final -state is entered this will be reported via the callback specified via the option -__\-command__\. Note that conversion of this into a pull model where the -environment retrieves messages from the object and the object uses a callback to -ask for more symbols is a trivial thing\. - -*Side note*: The acceptor objects provided by -__[grammar::fa::dacceptor](dacceptor\.md)__ could have been implemented -on top of the executors provided here, but were not, to get a bit more -performance \(we avoid a number of method calls and the time required for their -dispatch\)\. - -# <a name='section2'></a>API - -The package exports the API described here\. - - - <a name='1'></a>__::grammar::fa::dexec__ *daName* *fa* ?__\-any__ *any*? ?__\-command__ *cmdprefix*? - - Creates a new deterministic executor with an associated global Tcl command - whose name is *daName*\. This command may be used to invoke various - operations on the executor\. It has the following general form: - - * <a name='2'></a>__daName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - See section [EXECUTOR METHODS](#section3) for more explanations\. - - The executor will be based on the deterministic finite automaton stored - in the object *fa*\. It will keep a copy of the relevant data of the FA - in its own storage, in a form easy to use for its purposes\. This also - means that changes made to the *fa* after the construction of the - executor *will not* influence the executor\. - - If *any* has been specified, then the executor will convert all - symbols in the input which are unknown to the base FA to that symbol - before proceeding with the processing\. - -# <a name='section3'></a>EXECUTOR METHODS - -All executors provide the following methods for their manipulation: - - - <a name='3'></a>*daName* __destroy__ - - Destroys the automaton, including its storage space and associated command\. - - - <a name='4'></a>*daName* __put__ *symbol* - - Takes the current state of the executor and the *symbol* and performs the - appropriate state transition\. Reports any errors encountered via the command - callback, as well as entering a final state of the underlying FA\. - - When an error is reported all further invokations of __put__ will do - nothing, until the error condition has been cleared via an invokation of - method __reset__\. - - - <a name='5'></a>*daName* __reset__ - - Unconditionally sets the executor into the start state of the underlying FA\. - This also clears any error condition __put__ may have encountered\. - - - <a name='6'></a>*daName* __state__ - - Returns the current state of the underlying FA\. This allow for introspection - without the need to pass data from the callback command\. - -# <a name='section4'></a>EXECUTOR CALLBACK - -The callback command *cmdprefix* given to an executor via the option -__\-command__ will be executed by the object at the global level, using the -syntax described below\. Note that *cmdprefix* is not simply the name of a -command, but a full command prefix\. In other words it may contain additional -fixed argument words beyond the command word\. - - - <a name='7'></a>*cmdprefix* __error__ *code* *message* - - The executor has encountered an error, and *message* contains a - human\-readable text explaining the nature of the problem\. The *code* on - the other hand is a fixed machine\-readable text\. The following error codes - can be generated by executor objects\. - - * __BADSYM__ - - An unknown symbol was found in the input\. This can happen if and only if - no __\-any__ symbol was specified\. - - * __BADTRANS__ - - The underlying FA has no transition for the current combination of input - symbol and state\. In other words, the executor was not able to compute a - new state for this combination\. - - - <a name='8'></a>*cmdprefix* __final__ *stateid* - - The executor has entered the final state *stateid*\. - - - <a name='9'></a>*cmdprefix* __reset__ - - The executor was reset\. - - - <a name='10'></a>*cmdprefix* __state__ *stateid* - - The FA changed state due to a transition\. *stateid* is the new state\. - -# <a name='section5'></a>EXAMPLES - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_fa* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[automaton](\.\./\.\./\.\./\.\./index\.md\#automaton), -[execution](\.\./\.\./\.\./\.\./index\.md\#execution), [finite -automaton](\.\./\.\./\.\./\.\./index\.md\#finite\_automaton), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), [regular -grammar](\.\./\.\./\.\./\.\./index\.md\#regular\_grammar), [regular -languages](\.\./\.\./\.\./\.\./index\.md\#regular\_languages), -[running](\.\./\.\./\.\./\.\./index\.md\#running), -[state](\.\./\.\./\.\./\.\./index\.md\#state), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2004 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> -Copyright © 2007 Bogdan <rftghost@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_fa/fa.md Index: embedded/md/tcllib/files/modules/grammar_fa/fa.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_fa/fa.md +++ embedded/md/tcllib/files/modules/grammar_fa/fa.md @@ -1,634 +0,0 @@ - -[//000000001]: # (grammar::fa \- Finite automaton operations and usage) -[//000000002]: # (Generated from file 'fa\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::fa\(n\) 0\.4 tcllib "Finite automaton operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::fa \- Create and manipulate finite automatons - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [FA METHODS](#section3) - - - [EXAMPLES](#section4) - - - [FINITE AUTOMATONS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require snit 1\.3 -package require struct::list -package require struct::set -package require grammar::fa::op ?0\.2? -package require grammar::fa ?0\.4? - -[__::grammar::fa__ *faName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*|__fromRegex__ *re* ?*over*??](#1) -[__faName__ *option* ?*arg arg \.\.\.*?](#2) -[*faName* __destroy__](#3) -[*faName* __clear__](#4) -[*faName* __=__ *srcFA*](#5) -[*faName* __\-\->__ *dstFA*](#6) -[*faName* __serialize__](#7) -[*faName* __deserialize__ *serialization*](#8) -[*faName* __states__](#9) -[*faName* __state__ __add__ *s1* ?*s2* \.\.\.?](#10) -[*faName* __state__ __delete__ *s1* ?*s2* \.\.\.?](#11) -[*faName* __state__ __exists__ *s*](#12) -[*faName* __state__ __rename__ *s* *snew*](#13) -[*faName* __startstates__](#14) -[*faName* __start__ __add__ *s1* ?*s2* \.\.\.?](#15) -[*faName* __start__ __remove__ *s1* ?*s2* \.\.\.?](#16) -[*faName* __start?__ *s*](#17) -[*faName* __start?set__ *stateset*](#18) -[*faName* __finalstates__](#19) -[*faName* __final__ __add__ *s1* ?*s2* \.\.\.?](#20) -[*faName* __final__ __remove__ *s1* ?*s2* \.\.\.?](#21) -[*faName* __final?__ *s*](#22) -[*faName* __final?set__ *stateset*](#23) -[*faName* __symbols__](#24) -[*faName* __symbols@__ *s* ?*d*?](#25) -[*faName* __symbols@set__ *stateset*](#26) -[*faName* __symbol__ __add__ *sym1* ?*sym2* \.\.\.?](#27) -[*faName* __symbol__ __delete__ *sym1* ?*sym2* \.\.\.?](#28) -[*faName* __symbol__ __rename__ *sym* *newsym*](#29) -[*faName* __symbol__ __exists__ *sym*](#30) -[*faName* __next__ *s* *sym* ?__\-\->__ *next*?](#31) -[*faName* __\!next__ *s* *sym* ?__\-\->__ *next*?](#32) -[*faName* __nextset__ *stateset* *sym*](#33) -[*faName* __is__ __deterministic__](#34) -[*faName* __is__ __complete__](#35) -[*faName* __is__ __useful__](#36) -[*faName* __is__ __epsilon\-free__](#37) -[*faName* __reachable\_states__](#38) -[*faName* __unreachable\_states__](#39) -[*faName* __reachable__ *s*](#40) -[*faName* __useful\_states__](#41) -[*faName* __unuseful\_states__](#42) -[*faName* __useful__ *s*](#43) -[*faName* __epsilon\_closure__ *s*](#44) -[*faName* __reverse__](#45) -[*faName* __complete__](#46) -[*faName* __remove\_eps__](#47) -[*faName* __trim__ ?*what*?](#48) -[*faName* __determinize__ ?*mapvar*?](#49) -[*faName* __minimize__ ?*mapvar*?](#50) -[*faName* __complement__](#51) -[*faName* __kleene__](#52) -[*faName* __optional__](#53) -[*faName* __union__ *fa* ?*mapvar*?](#54) -[*faName* __intersect__ *fa* ?*mapvar*?](#55) -[*faName* __difference__ *fa* ?*mapvar*?](#56) -[*faName* __concatenate__ *fa* ?*mapvar*?](#57) -[*faName* __fromRegex__ *regex* ?*over*?](#58) - -# <a name='description'></a>DESCRIPTION - -This package provides a container class for *finite automatons* \(Short: FA\)\. -It allows the incremental definition of the automaton, its manipulation and -querying of the definition\. While the package provides complex operations on the -automaton \(via package __[grammar::fa::op](faop\.md)__\), it does not have -the ability to execute a definition for a stream of symbols\. Use the packages -__[grammar::fa::dacceptor](dacceptor\.md)__ and -__[grammar::fa::dexec](dexec\.md)__ for that\. Another package related to -this is __grammar::fa::compiler__\. It turns a FA into an executor class -which has the definition of the FA hardwired into it\. The output of this package -is configurable to suit a large number of different implementation languages and -paradigms\. - -For more information about what a finite automaton is see section [FINITE -AUTOMATONS](#section5)\. - -# <a name='section2'></a>API - -The package exports the API described here\. - - - <a name='1'></a>__::grammar::fa__ *faName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*|__fromRegex__ *re* ?*over*?? - - Creates a new finite automaton with an associated global Tcl command whose - name is *faName*\. This command may be used to invoke various operations on - the automaton\. It has the following general form: - - * <a name='2'></a>__faName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - See section [FA METHODS](#section3) for more explanations\. The new - automaton will be empty if no *src* is specified\. Otherwise it will - contain a copy of the definition contained in the *src*\. The *src* - has to be a FA object reference for all operators except - __deserialize__ and __fromRegex__\. The __deserialize__ - operator requires *src* to be the serialization of a FA instead, and - __fromRegex__ takes a regular expression in the form a of a syntax - tree\. See __::grammar::fa::op::fromRegex__ for more detail on that\. - -# <a name='section3'></a>FA METHODS - -All automatons provide the following methods for their manipulation: - - - <a name='3'></a>*faName* __destroy__ - - Destroys the automaton, including its storage space and associated command\. - - - <a name='4'></a>*faName* __clear__ - - Clears out the definition of the automaton contained in *faName*, but does - *not* destroy the object\. - - - <a name='5'></a>*faName* __=__ *srcFA* - - Assigns the contents of the automaton contained in *srcFA* to *faName*, - overwriting any existing definition\. This is the assignment operator for - automatons\. It copies the automaton contained in the FA object *srcFA* - over the automaton definition in *faName*\. The old contents of *faName* - are deleted by this operation\. - - This operation is in effect equivalent to - - > *faName* __deserialize__ \[*srcFA* __serialize__\] - - - <a name='6'></a>*faName* __\-\->__ *dstFA* - - This is the reverse assignment operator for automatons\. It copies the - automation contained in the object *faName* over the automaton definition - in the object *dstFA*\. The old contents of *dstFA* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *dstFA* __deserialize__ \[*faName* __serialize__\] - - - <a name='7'></a>*faName* __serialize__ - - This method serializes the automaton stored in *faName*\. In other words it - returns a tcl *value* completely describing that automaton\. This allows, - for example, the transfer of automatons over arbitrary channels, - persistence, etc\. This method is also the basis for both the copy - constructor and the assignment operator\. - - The result of this method has to be semantically identical over all - implementations of the __grammar::fa__ interface\. This is what will - enable us to copy automatons between different implementations of the same - interface\. - - The result is a list of three elements with the following structure: - - 1. The constant string __grammar::fa__\. - - 1. A list containing the names of all known input symbols\. The order of - elements in this list is not relevant\. - - 1. The last item in the list is a dictionary, however the order of the - keys is important as well\. The keys are the states of the serialized - FA, and their order is the order in which to create the states when - deserializing\. This is relevant to preserve the order relationship - between states\. - - The value of each dictionary entry is a list of three elements - describing the state in more detail\. - - 1) A boolean flag\. If its value is __true__ then the state is a - start state, otherwise it is not\. - - 1) A boolean flag\. If its value is __true__ then the state is a - final state, otherwise it is not\. - - 1) The last element is a dictionary describing the transitions for - the state\. The keys are symbols \(or the empty string\), and the - values are sets of successor states\. - - Assuming the following FA \(which describes the life of a truck driver in a - very simple way :\) - - Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive - (...) is the start state. - - a possible serialization is - - grammar::fa \ - {yellow red green red/yellow} \ - {Drive {0 0 {yellow Brake}} \ - Brake {0 0 {red Stop}} \ - Stop {1 0 {red/yellow Attention}} \ - Attention {0 0 {green Drive}}} - - A possible one, because I did not care about creation order here - - - <a name='8'></a>*faName* __deserialize__ *serialization* - - This is the complement to __serialize__\. It replaces the automaton - definition in *faName* with the automaton described by the - *serialization* value\. The old contents of *faName* are deleted by this - operation\. - - - <a name='9'></a>*faName* __states__ - - Returns the set of all states known to *faName*\. - - - <a name='10'></a>*faName* __state__ __add__ *s1* ?*s2* \.\.\.? - - Adds the states *s1*, *s2*, et cetera to the FA definition in - *faName*\. The operation will fail any of the new states is already - declared\. - - - <a name='11'></a>*faName* __state__ __delete__ *s1* ?*s2* \.\.\.? - - Deletes the state *s1*, *s2*, et cetera, and all associated information - from the FA definition in *faName*\. The latter means that the information - about in\- or outbound transitions is deleted as well\. If the deleted state - was a start or final state then this information is invalidated as well\. The - operation will fail if the state *s* is not known to the FA\. - - - <a name='12'></a>*faName* __state__ __exists__ *s* - - A predicate\. It tests whether the state *s* is known to the FA in - *faName*\. The result is a boolean value\. It will be set to __true__ if - the state *s* is known, and __false__ otherwise\. - - - <a name='13'></a>*faName* __state__ __rename__ *s* *snew* - - Renames the state *s* to *snew*\. Fails if *s* is not a known state\. - Also fails if *snew* is already known as a state\. - - - <a name='14'></a>*faName* __startstates__ - - Returns the set of states which are marked as *start* states, also known - as *initial* states\. See [FINITE AUTOMATONS](#section5) for - explanations what this means\. - - - <a name='15'></a>*faName* __start__ __add__ *s1* ?*s2* \.\.\.? - - Mark the states *s1*, *s2*, et cetera in the FA *faName* as *start* - \(aka *initial*\)\. - - - <a name='16'></a>*faName* __start__ __remove__ *s1* ?*s2* \.\.\.? - - Mark the states *s1*, *s2*, et cetera in the FA *faName* as *not - start* \(aka *not accepting*\)\. - - - <a name='17'></a>*faName* __start?__ *s* - - A predicate\. It tests if the state *s* in the FA *faName* is *start* - or not\. The result is a boolean value\. It will be set to __true__ if the - state *s* is *start*, and __false__ otherwise\. - - - <a name='18'></a>*faName* __start?set__ *stateset* - - A predicate\. It tests if the set of states *stateset* contains at least - one start state\. They operation will fail if the set contains an element - which is not a known state\. The result is a boolean value\. It will be set to - __true__ if a start state is present in *stateset*, and __false__ - otherwise\. - - - <a name='19'></a>*faName* __finalstates__ - - Returns the set of states which are marked as - *[final](\.\./\.\./\.\./\.\./index\.md\#final)* states, also known as - *accepting* states\. See [FINITE AUTOMATONS](#section5) for - explanations what this means\. - - - <a name='20'></a>*faName* __final__ __add__ *s1* ?*s2* \.\.\.? - - Mark the states *s1*, *s2*, et cetera in the FA *faName* as - *[final](\.\./\.\./\.\./\.\./index\.md\#final)* \(aka *accepting*\)\. - - - <a name='21'></a>*faName* __final__ __remove__ *s1* ?*s2* \.\.\.? - - Mark the states *s1*, *s2*, et cetera in the FA *faName* as *not - final* \(aka *not accepting*\)\. - - - <a name='22'></a>*faName* __final?__ *s* - - A predicate\. It tests if the state *s* in the FA *faName* is - *[final](\.\./\.\./\.\./\.\./index\.md\#final)* or not\. The result is a boolean - value\. It will be set to __true__ if the state *s* is - *[final](\.\./\.\./\.\./\.\./index\.md\#final)*, and __false__ otherwise\. - - - <a name='23'></a>*faName* __final?set__ *stateset* - - A predicate\. It tests if the set of states *stateset* contains at least - one final state\. They operation will fail if the set contains an element - which is not a known state\. The result is a boolean value\. It will be set to - __true__ if a final state is present in *stateset*, and __false__ - otherwise\. - - - <a name='24'></a>*faName* __symbols__ - - Returns the set of all symbols known to the FA *faName*\. - - - <a name='25'></a>*faName* __symbols@__ *s* ?*d*? - - Returns the set of all symbols for which the state *s* has transitions\. If - the empty symbol is present then *s* has epsilon transitions\. If two - states are specified the result is the set of symbols which have transitions - from *s* to *t*\. This set may be empty if there are no transitions - between the two specified states\. - - - <a name='26'></a>*faName* __symbols@set__ *stateset* - - Returns the set of all symbols for which at least one state in the set of - states *stateset* has transitions\. In other words, the union of - \[*faName* __symbols@__ __s__\] for all states __s__ in - *stateset*\. If the empty symbol is present then at least one state - contained in *stateset* has epsilon transitions\. - - - <a name='27'></a>*faName* __symbol__ __add__ *sym1* ?*sym2* \.\.\.? - - Adds the symbols *sym1*, *sym2*, et cetera to the FA definition in - *faName*\. The operation will fail any of the symbols is already declared\. - The empty string is not allowed as a value for the symbols\. - - - <a name='28'></a>*faName* __symbol__ __delete__ *sym1* ?*sym2* \.\.\.? - - Deletes the symbols *sym1*, *sym2* et cetera, and all associated - information from the FA definition in *faName*\. The latter means that all - transitions using the symbols are deleted as well\. The operation will fail - if any of the symbols is not known to the FA\. - - - <a name='29'></a>*faName* __symbol__ __rename__ *sym* *newsym* - - Renames the symbol *sym* to *newsym*\. Fails if *sym* is not a known - symbol\. Also fails if *newsym* is already known as a symbol\. - - - <a name='30'></a>*faName* __symbol__ __exists__ *sym* - - A predicate\. It tests whether the symbol *sym* is known to the FA in - *faName*\. The result is a boolean value\. It will be set to __true__ if - the symbol *sym* is known, and __false__ otherwise\. - - - <a name='31'></a>*faName* __next__ *s* *sym* ?__\-\->__ *next*? - - Define or query transition information\. - - If *next* is specified, then the method will add a transition from the - state *s* to the *successor* state *next* labeled with the symbol - *sym* to the FA contained in *faName*\. The operation will fail if *s*, - or *next* are not known states, or if *sym* is not a known symbol\. An - exception to the latter is that *sym* is allowed to be the empty string\. - In that case the new transition is an *epsilon transition* which will not - consume input when traversed\. The operation will also fail if the - combination of \(*s*, *sym*, and *next*\) is already present in the FA\. - - If *next* was not specified, then the method will return the set of states - which can be reached from *s* through a single transition labeled with - symbol *sym*\. - - - <a name='32'></a>*faName* __\!next__ *s* *sym* ?__\-\->__ *next*? - - Remove one or more transitions from the Fa in *faName*\. - - If *next* was specified then the single transition from the state *s* to - the state *next* labeled with the symbol *sym* is removed from the FA\. - Otherwise *all* transitions originating in state *s* and labeled with - the symbol *sym* will be removed\. - - The operation will fail if *s* and/or *next* are not known as states\. It - will also fail if a non\-empty *sym* is not known as symbol\. The empty - string is acceptable, and allows the removal of epsilon transitions\. - - - <a name='33'></a>*faName* __nextset__ *stateset* *sym* - - Returns the set of states which can be reached by a single transition - originating in a state in the set *stateset* and labeled with the symbol - *sym*\. - - In other words, this is the union of \[*faName* next __s__ *symbol*\] - for all states __s__ in *stateset*\. - - - <a name='34'></a>*faName* __is__ __deterministic__ - - A predicate\. It tests whether the FA in *faName* is a deterministic FA or - not\. The result is a boolean value\. It will be set to __true__ if the FA - is deterministic, and __false__ otherwise\. - - - <a name='35'></a>*faName* __is__ __complete__ - - A predicate\. It tests whether the FA in *faName* is a complete FA or not\. - A FA is complete if it has at least one transition per state and symbol\. - This also means that a FA without symbols, or states is also complete\. The - result is a boolean value\. It will be set to __true__ if the FA is - deterministic, and __false__ otherwise\. - - Note: When a FA has epsilon\-transitions transitions over a symbol for a - state S can be indirect, i\.e\. not attached directly to S, but to a state in - the epsilon\-closure of S\. The symbols for such indirect transitions count - when computing completeness\. - - - <a name='36'></a>*faName* __is__ __useful__ - - A predicate\. It tests whether the FA in *faName* is an useful FA or not\. A - FA is useful if all states are *reachable* and *useful*\. The result is a - boolean value\. It will be set to __true__ if the FA is deterministic, - and __false__ otherwise\. - - - <a name='37'></a>*faName* __is__ __epsilon\-free__ - - A predicate\. It tests whether the FA in *faName* is an epsilon\-free FA or - not\. A FA is epsilon\-free if it has no epsilon transitions\. This definition - means that all deterministic FAs are epsilon\-free as well, and - epsilon\-freeness is a necessary pre\-condition for deterministic'ness\. The - result is a boolean value\. It will be set to __true__ if the FA is - deterministic, and __false__ otherwise\. - - - <a name='38'></a>*faName* __reachable\_states__ - - Returns the set of states which are reachable from a start state by one or - more transitions\. - - - <a name='39'></a>*faName* __unreachable\_states__ - - Returns the set of states which are not reachable from any start state by - any number of transitions\. This is - - [faName states] - [faName reachable_states] - - - <a name='40'></a>*faName* __reachable__ *s* - - A predicate\. It tests whether the state *s* in the FA *faName* can be - reached from a start state by one or more transitions\. The result is a - boolean value\. It will be set to __true__ if the state can be reached, - and __false__ otherwise\. - - - <a name='41'></a>*faName* __useful\_states__ - - Returns the set of states which are able to reach a final state by one or - more transitions\. - - - <a name='42'></a>*faName* __unuseful\_states__ - - Returns the set of states which are not able to reach a final state by any - number of transitions\. This is - - [faName states] - [faName useful_states] - - - <a name='43'></a>*faName* __useful__ *s* - - A predicate\. It tests whether the state *s* in the FA *faName* is able - to reach a final state by one or more transitions\. The result is a boolean - value\. It will be set to __true__ if the state is useful, and - __false__ otherwise\. - - - <a name='44'></a>*faName* __epsilon\_closure__ *s* - - Returns the set of states which are reachable from the state *s* in the FA - *faName* by one or more epsilon transitions, i\.e transitions over the - empty symbol, transitions which do not consume input\. This is called the - *epsilon closure* of *s*\. - - - <a name='45'></a>*faName* __reverse__ - - - <a name='46'></a>*faName* __complete__ - - - <a name='47'></a>*faName* __remove\_eps__ - - - <a name='48'></a>*faName* __trim__ ?*what*? - - - <a name='49'></a>*faName* __determinize__ ?*mapvar*? - - - <a name='50'></a>*faName* __minimize__ ?*mapvar*? - - - <a name='51'></a>*faName* __complement__ - - - <a name='52'></a>*faName* __kleene__ - - - <a name='53'></a>*faName* __optional__ - - - <a name='54'></a>*faName* __union__ *fa* ?*mapvar*? - - - <a name='55'></a>*faName* __intersect__ *fa* ?*mapvar*? - - - <a name='56'></a>*faName* __difference__ *fa* ?*mapvar*? - - - <a name='57'></a>*faName* __concatenate__ *fa* ?*mapvar*? - - - <a name='58'></a>*faName* __fromRegex__ *regex* ?*over*? - - These methods provide more complex operations on the FA\. Please see the - same\-named commands in the package __[grammar::fa::op](faop\.md)__ - for descriptions of what they do\. - -# <a name='section4'></a>EXAMPLES - -# <a name='section5'></a>FINITE AUTOMATONS - -For the mathematically inclined, a FA is a 5\-tuple \(S,Sy,St,Fi,T\) where - - - S is a set of *states*, - - - Sy a set of *input symbols*, - - - St is a subset of S, the set of *start* states, also known as *initial* - states\. - - - Fi is a subset of S, the set of *[final](\.\./\.\./\.\./\.\./index\.md\#final)* - states, also known as *accepting*\. - - - T is a function from S x \(Sy \+ epsilon\) to \{S\}, the *transition function*\. - Here __epsilon__ denotes the empty input symbol and is distinct from all - symbols in Sy; and \{S\} is the set of subsets of S\. In other words, T maps a - combination of State and Input \(which can be empty\) to a set of *successor - states*\. - -In computer theory a FA is most often shown as a graph where the nodes represent -the states, and the edges between the nodes encode the transition function: For -all n in S' = T \(s, sy\) we have one edge between the nodes representing s and n -resp\., labeled with sy\. The start and accepting states are encoded through -distinct visual markers, i\.e\. they are attributes of the nodes\. - -FA's are used to process streams of symbols over Sy\. - -A specific FA is said to *accept* a finite stream sy\_1 sy\_2 \.\.\. sy\_n if there -is a path in the graph of the FA beginning at a state in St and ending at a -state in Fi whose edges have the labels sy\_1, sy\_2, etc\. to sy\_n\. The set of all -strings accepted by the FA is the *language* of the FA\. One important -equivalence is that the set of languages which can be accepted by an FA is the -set of *[regular languages](\.\./\.\./\.\./\.\./index\.md\#regular\_languages)*\. - -Another important concept is that of deterministic FAs\. A FA is said to be -*deterministic* if for each string of input symbols there is exactly one path -in the graph of the FA beginning at the start state and whose edges are labeled -with the symbols in the string\. While it might seem that non\-deterministic FAs -to have more power of recognition, this is not so\. For each non\-deterministic FA -we can construct a deterministic FA which accepts the same language \(\-\-> -Thompson's subset construction\)\. - -While one of the premier applications of FAs is in -*[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing)*, especially in the -*[lexer](\.\./\.\./\.\./\.\./index\.md\#lexer)* stage \(where symbols == characters\), -this is not the only possibility by far\. - -Quite a lot of processes can be modeled as a FA, albeit with a possibly large -set of states\. For these the notion of accepting states is often less or not -relevant at all\. What is needed instead is the ability to act to state changes -in the FA, i\.e\. to generate some output in response to the input\. This -transforms a FA into a *finite transducer*, which has an additional set OSy of -*output symbols* and also an additional *output function* O which maps from -"S x \(Sy \+ epsilon\)" to "\(Osy \+ epsilon\)", i\.e a combination of state and input, -possibly empty to an output symbol, or nothing\. - -For the graph representation this means that edges are additional labeled with -the output symbol to write when this edge is traversed while matching input\. -Note that for an application "writing an output symbol" can also be "executing -some code"\. - -Transducers are not handled by this package\. They will get their own package in -the future\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_fa* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[automaton](\.\./\.\./\.\./\.\./index\.md\#automaton), [finite -automaton](\.\./\.\./\.\./\.\./index\.md\#finite\_automaton), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), [regular -grammar](\.\./\.\./\.\./\.\./index\.md\#regular\_grammar), [regular -languages](\.\./\.\./\.\./\.\./index\.md\#regular\_languages), -[state](\.\./\.\./\.\./\.\./index\.md\#state), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2004\-2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_fa/faop.md Index: embedded/md/tcllib/files/modules/grammar_fa/faop.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_fa/faop.md +++ embedded/md/tcllib/files/modules/grammar_fa/faop.md @@ -1,457 +0,0 @@ - -[//000000001]: # (grammar::fa::op \- Finite automaton operations and usage) -[//000000002]: # (Generated from file 'faop\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::fa::op\(n\) 0\.4 tcllib "Finite automaton operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::fa::op \- Operations on finite automatons - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require struct::list -package require struct::set -package require grammar::fa::op ?0\.4\.1? - -[__::grammar::fa::op::constructor__ *cmd*](#1) -[__::grammar::fa::op::reverse__ *fa*](#2) -[__::grammar::fa::op::complete__ *fa* ?*sink*?](#3) -[__::grammar::fa::op::remove\_eps__ *fa*](#4) -[__::grammar::fa::op::trim__ *fa* ?*what*?](#5) -[__::grammar::fa::op::determinize__ *fa* ?*mapvar*?](#6) -[__::grammar::fa::op::minimize__ *fa* ?*mapvar*?](#7) -[__::grammar::fa::op::complement__ *fa*](#8) -[__::grammar::fa::op::kleene__ *fa*](#9) -[__::grammar::fa::op::optional__ *fa*](#10) -[__::grammar::fa::op::union__ *fa* *fb* ?*mapvar*?](#11) -[__::grammar::fa::op::intersect__ *fa* *fb* ?*mapvar*?](#12) -[__::grammar::fa::op::difference__ *fa* *fb* ?*mapvar*?](#13) -[__::grammar::fa::op::concatenate__ *fa* *fb* ?*mapvar*?](#14) -[__::grammar::fa::op::fromRegex__ *fa* *regex* ?*over*?](#15) -[__::grammar::fa::op::toRegexp__ *fa*](#16) -[__::grammar::fa::op::toRegexp2__ *fa*](#17) -[__::grammar::fa::op::toTclRegexp__ *regexp* *symdict*](#18) -[__::grammar::fa::op::simplifyRegexp__ *regexp*](#19) - -# <a name='description'></a>DESCRIPTION - -This package provides a number of complex operations on finite automatons -\(Short: FA\), as provided by the package __[grammar::fa](fa\.md)__\. The -package does not provide the ability to create and/or manipulate such FAs, nor -the ability to execute a FA for a stream of symbols\. Use the packages -__[grammar::fa](fa\.md)__ and __grammar::fa::interpreter__ for that\. -Another package related to this is __grammar::fa::compiler__ which turns a -FA into an executor class which has the definition of the FA hardwired into it\. - -For more information about what a finite automaton is see section *FINITE -AUTOMATONS* in package __[grammar::fa](fa\.md)__\. - -# <a name='section2'></a>API - -The package exports the API described here\. All commands modify their first -argument\. I\.e\. whatever FA they compute is stored back into it\. Some of the -operations will construct an automaton whose states are all new, but related to -the states in the source automaton\(s\)\. These operations take variable names as -optional arguments where they will store mappings which describe the -relationship\(s\)\. The operations can be loosely partitioned into structural and -language operations\. The latter are defined in terms of the language the -automaton\(s\) accept, whereas the former are defined in terms of the structural -properties of the involved automaton\(s\)\. Some operations are both\. *Structure -operations* - - - <a name='1'></a>__::grammar::fa::op::constructor__ *cmd* - - This command has to be called by the user of the package before any other - operations is performed, to establish a command which can be used to - construct a FA container object\. If this is not done several operations will - fail as they are unable to construct internal and transient containers to - hold state and/or partial results\. - - Any container class using this package for complex operations should set its - own class command as the constructor\. See package - __[grammar::fa](fa\.md)__ for an example\. - - - <a name='2'></a>__::grammar::fa::op::reverse__ *fa* - - Reverses the *fa*\. This is done by reversing the direction of all - transitions and swapping the sets of *start* and - *[final](\.\./\.\./\.\./\.\./index\.md\#final)* states\. The language of *fa* - changes unpredictably\. - - - <a name='3'></a>__::grammar::fa::op::complete__ *fa* ?*sink*? - - Completes the *fa* *complete*, but nothing is done if the *fa* is - already *complete*\. This implies that only the first in a series of - multiple consecutive complete operations on *fa* will perform anything\. - The remainder will be null operations\. - - The language of *fa* is unchanged by this operation\. - - This is done by adding a single new state, the *sink*, and transitions - from all other states to that sink for all symbols they have no transitions - for\. The sink itself is made complete by adding loop transitions for all - symbols\. - - Note: When a FA has epsilon\-transitions transitions over a symbol for a - state S can be indirect, i\.e\. not attached directly to S, but to a state in - the epsilon\-closure of S\. The symbols for such indirect transitions count - when computing completeness of a state\. In other words, these indirectly - reached symbols are *not* missing\. - - The argument *sink* provides the name for the new state and most not be - present in the *fa* if specified\. If the name is not specified the command - will name the state "sink__n__", where __n__ is set so that there - are no collisions with existing states\. - - Note that the sink state is *not useful* by definition\. In other words, - while the FA becomes complete, it is also *not useful* in the strict sense - as it has a state from which no final state can be reached\. - - - <a name='4'></a>__::grammar::fa::op::remove\_eps__ *fa* - - Removes all epsilon\-transitions from the *fa* in such a manner the the - language of *fa* is unchanged\. However nothing is done if the *fa* is - already *epsilon\-free*\. This implies that only the first in a series of - multiple consecutive complete operations on *fa* will perform anything\. - The remainder will be null operations\. - - *Note:* This operation may cause states to become unreachable or not - useful\. These states are not removed by this operation\. Use - __::grammar::fa::op::trim__ for that instead\. - - - <a name='5'></a>__::grammar::fa::op::trim__ *fa* ?*what*? - - Removes unwanted baggage from *fa*\. The legal values for *what* are - listed below\. The command defaults to __\!reachable|\!useful__ if no - specific argument was given\. - - * __\!reachable__ - - Removes all states which are not reachable from a start state\. - - * __\!useful__ - - Removes all states which are unable to reach a final state\. - - * __\!reachable&\!useful__ - - * __\!\(reachable|useful\)__ - - Removes all states which are not reachable from a start state and are - unable to reach a final state\. - - * __\!reachable|\!useful__ - - * __\!\(reachable&useful\)__ - - Removes all states which are not reachable from a start state or are - unable to reach a final state\. - - - <a name='6'></a>__::grammar::fa::op::determinize__ *fa* ?*mapvar*? - - Makes the *fa* deterministic without changing the language accepted by the - *fa*\. However nothing is done if the *fa* is already *deterministic*\. - This implies that only the first in a series of multiple consecutive - complete operations on *fa* will perform anything\. The remainder will be - null operations\. - - The command will store a dictionary describing the relationship between the - new states of the resulting dfa and the states of the input nfa in - *mapvar*, if it has been specified\. Keys of the dictionary are the handles - for the states of the resulting dfa, values are sets of states from the - input nfa\. - - *Note*: An empty dictionary signals that the command was able to make the - *fa* deterministic without performing a full subset construction, just by - removing states and shuffling transitions around \(As part of making the FA - epsilon\-free\)\. - - *Note*: The algorithm fails to make the FA deterministic in the technical - sense if the FA has no start state\(s\), because determinism requires the FA - to have exactly one start states\. In that situation we make a best effort; - and the missing start state will be the only condition preventing the - generated result from being *deterministic*\. It should also be noted that - in this case the possibilities for trimming states from the FA are also - severely reduced as we cannot declare states unreachable\. - - - <a name='7'></a>__::grammar::fa::op::minimize__ *fa* ?*mapvar*? - - Creates a FA which accepts the same language as *fa*, but has a minimal - number of states\. Uses Brzozowski's method to accomplish this\. - - The command will store a dictionary describing the relationship between the - new states of the resulting minimal fa and the states of the input fa in - *mapvar*, if it has been specified\. Keys of the dictionary are the handles - for the states of the resulting minimal fa, values are sets of states from - the input fa\. - - *Note*: An empty dictionary signals that the command was able to minimize - the *fa* without having to compute new states\. This should happen if and - only if the input FA was already minimal\. - - *Note*: If the algorithm has no start or final states to work with then - the result might be technically minimal, but have a very unexpected - structure\. It should also be noted that in this case the possibilities for - trimming states from the FA are also severely reduced as we cannot declare - states unreachable\. - -*Language operations* All operations in this section require that all input -FAs have at least one start and at least one final state\. Otherwise the language -of the FAs will not be defined, making the operation senseless \(as it operates -on the languages of the FAs in a defined manner\)\. - - - <a name='8'></a>__::grammar::fa::op::complement__ *fa* - - Complements *fa*\. This is possible if and only if *fa* is *complete* - and *deterministic*\. The resulting FA accepts the complementary language - of *fa*\. In other words, all inputs not accepted by the input are accepted - by the result, and vice versa\. - - The result will have all states and transitions of the input, and different - final states\. - - - <a name='9'></a>__::grammar::fa::op::kleene__ *fa* - - Applies Kleene's closure to *fa*\. The resulting FA accepts all strings - __S__ for which we can find a natural number __n__ \(0 inclusive\) and - strings __A1__ \.\.\. __An__ in the language of *fa* such that - __S__ is the concatenation of __A1__ \.\.\. __An__\. In other words, - the language of the result is the infinite union over finite length - concatenations over the language of *fa*\. - - The result will have all states and transitions of the input, and new start - and final states\. - - - <a name='10'></a>__::grammar::fa::op::optional__ *fa* - - Makes the *fa* optional\. In other words it computes the FA which accepts - the language of *fa* and the empty the word \(epsilon\) as well\. - - The result will have all states and transitions of the input, and new start - and final states\. - - - <a name='11'></a>__::grammar::fa::op::union__ *fa* *fb* ?*mapvar*? - - Combines the FAs *fa* and *fb* such that the resulting FA accepts the - union of the languages of the two FAs\. - - The result will have all states and transitions of the two input FAs, and - new start and final states\. All states of *fb* which exist in *fa* as - well will be renamed, and the *mapvar* will contain a mapping from the old - states of *fb* to the new ones, if present\. - - It should be noted that the result will be non\-deterministic, even if the - inputs are deterministic\. - - - <a name='12'></a>__::grammar::fa::op::intersect__ *fa* *fb* ?*mapvar*? - - Combines the FAs *fa* and *fb* such that the resulting FA accepts the - intersection of the languages of the two FAs\. In other words, the result - will accept a word if and only if the word is accepted by both *fa* and - *fb*\. The result will be useful, but not necessarily deterministic or - minimal\. - - The command will store a dictionary describing the relationship between the - new states of the resulting fa and the pairs of states of the input FAs in - *mapvar*, if it has been specified\. Keys of the dictionary are the handles - for the states of the resulting fa, values are pairs of states from the - input FAs\. Pairs are represented by lists\. The first element in each pair - will be a state in *fa*, the second element will be drawn from *fb*\. - - - <a name='13'></a>__::grammar::fa::op::difference__ *fa* *fb* ?*mapvar*? - - Combines the FAs *fa* and *fb* such that the resulting FA accepts the - difference of the languages of the two FAs\. In other words, the result will - accept a word if and only if the word is accepted by *fa*, but not by - *fb*\. This can also be expressed as the intersection of *fa* with the - complement of *fb*\. The result will be useful, but not necessarily - deterministic or minimal\. - - The command will store a dictionary describing the relationship between the - new states of the resulting fa and the pairs of states of the input FAs in - *mapvar*, if it has been specified\. Keys of the dictionary are the handles - for the states of the resulting fa, values are pairs of states from the - input FAs\. Pairs are represented by lists\. The first element in each pair - will be a state in *fa*, the second element will be drawn from *fb*\. - - - <a name='14'></a>__::grammar::fa::op::concatenate__ *fa* *fb* ?*mapvar*? - - Combines the FAs *fa* and *fb* such that the resulting FA accepts the - cross\-product of the languages of the two FAs\. I\.e\. a word W will be - accepted by the result if there are two words A and B accepted by *fa*, - and *fb* resp\. and W is the concatenation of A and B\. - - The result FA will be non\-deterministic\. - - - <a name='15'></a>__::grammar::fa::op::fromRegex__ *fa* *regex* ?*over*? - - Generates a non\-deterministic FA which accepts the same language as the - regular expression *regex*\. If the *over* is specified it is treated as - the set of symbols the regular expression and the automaton are defined - over\. The command will compute the set from the "S" constructors in - *regex* when *over* was not specified\. This set is important if and only - if the complement operator "\!" is used in *regex* as the complementary - language of an FA is quite different for different sets of symbols\. - - The regular expression is represented by a nested list, which forms a syntax - tree\. The following structures are legal: - - * \{S x\} - - Atomic regular expression\. Everything else is constructed from these\. - Accepts the __S__ymbol "x"\. - - * \{\. A1 A2 \.\.\.\} - - Concatenation operator\. Accepts the concatenation of the regular - expressions __A1__, __A2__, etc\. - - *Note* that this operator accepts zero or more arguments\. With zero - arguments the represented language is *epsilon*, the empty word\. - - * \{| A1 A2 \.\.\.\} - - Choice operator, also called "Alternative"\. Accepts all input accepted - by at least one of the regular expressions __A1__, __A2__, etc\. - In other words, the union of __A1__, __A2__\. - - *Note* that this operator accepts zero or more arguments\. With zero - arguments the represented language is the *empty* language, the - language without words\. - - * \{& A1 A2 \.\.\.\} - - Intersection operator, logical and\. Accepts all input accepted which is - accepted by all of the regular expressions __A1__, __A2__, etc\. - In other words, the intersection of __A1__, __A2__\. - - * \{? A\} - - Optionality operator\. Accepts the empty word and anything from the - regular expression __A__\. - - * \{\* A\} - - Kleene closure\. Accepts the empty word and any finite concatenation of - words accepted by the regular expression __A__\. - - * \{\+ A\} - - Positive Kleene closure\. Accepts any finite concatenation of words - accepted by the regular expression __A__, but not the empty word\. - - * \{\! A\} - - Complement operator\. Accepts any word not accepted by the regular - expression __A__\. Note that the complement depends on the set of - symbol the result should run over\. See the discussion of the argument - *over* before\. - - - <a name='16'></a>__::grammar::fa::op::toRegexp__ *fa* - - This command generates and returns a regular expression which accepts the - same language as the finite automaton *fa*\. The regular expression is in - the format as described above, for __::grammar::fa::op::fromRegex__\. - - - <a name='17'></a>__::grammar::fa::op::toRegexp2__ *fa* - - This command has the same functionality as - __::grammar::fa::op::toRegexp__, but uses a different algorithm to - simplify the generated regular expressions\. - - - <a name='18'></a>__::grammar::fa::op::toTclRegexp__ *regexp* *symdict* - - This command generates and returns a regular expression in Tcl syntax for - the regular expression *regexp*, if that is possible\. *regexp* is in the - same format as expected by __::grammar::fa::op::fromRegex__\. - - The command will fail and throw an error if *regexp* contains - complementation and intersection operations\. - - The argument *symdict* is a dictionary mapping symbol names to pairs of - *syntactic type* and Tcl\-regexp\. If a symbol occurring in the *regexp* - is not listed in this dictionary then single\-character symbols are - considered to designate themselves whereas multiple\-character symbols are - considered to be a character class name\. - - - <a name='19'></a>__::grammar::fa::op::simplifyRegexp__ *regexp* - - This command simplifies a regular expression by applying the following - algorithm first to the main expression and then recursively to all - sub\-expressions: - - 1. Convert the expression into a finite automaton\. - - 1. Minimize the automaton\. - - 1. Convert the automaton back to a regular expression\. - - 1. Choose the shorter of original expression and expression from the - previous step\. - -# <a name='section3'></a>EXAMPLES - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_fa* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[automaton](\.\./\.\./\.\./\.\./index\.md\#automaton), [finite -automaton](\.\./\.\./\.\./\.\./index\.md\#finite\_automaton), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), [regular -grammar](\.\./\.\./\.\./\.\./index\.md\#regular\_grammar), [regular -languages](\.\./\.\./\.\./\.\./index\.md\#regular\_languages), -[state](\.\./\.\./\.\./\.\./index\.md\#state), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2004\-2008 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/gasm.md Index: embedded/md/tcllib/files/modules/grammar_me/gasm.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/gasm.md +++ embedded/md/tcllib/files/modules/grammar_me/gasm.md @@ -1,438 +0,0 @@ - -[//000000001]: # (grammar::me::cpu::gasm \- Grammar operations and usage) -[//000000002]: # (Generated from file 'gasm\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me::cpu::gasm\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me::cpu::gasm \- ME assembler - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [DEFINITIONS](#section2) - - - [API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require grammar::me::cpu::gasm ?0\.1? - -[__::grammar::me::cpu::gasm::begin__ *g* *n* ?*mode*? ?*note*?](#1) -[__::grammar::me::cpu::gasm::done__ __\-\->__ *t*](#2) -[__::grammar::me::cpu::gasm::state__](#3) -[__::grammar::me::cpu::gasm::state\!__ *s*](#4) -[__::grammar::me::cpu::gasm::lift__ *t* *dst* __=__ *src*](#5) -[__::grammar::me::cpu::gasm::Inline__ *t* *node* *label*](#6) -[__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*\.\.\.?](#7) -[__::grammar::me::cpu::gasm::Bra__](#8) -[__::grammar::me::cpu::gasm::Nop__ *text*](#9) -[__::grammar::me::cpu::gasm::Note__ *text*](#10) -[__::grammar::me::cpu::gasm::Jmp__ *label*](#11) -[__::grammar::me::cpu::gasm::Exit__](#12) -[__::grammar::me::cpu::gasm::Who__ *label*](#13) -[__::grammar::me::cpu::gasm::/Label__ *name*](#14) -[__::grammar::me::cpu::gasm::/Clear__](#15) -[__::grammar::me::cpu::gasm::/Ok__](#16) -[__::grammar::me::cpu::gasm::/Fail__](#17) -[__::grammar::me::cpu::gasm::/At__ *name*](#18) -[__::grammar::me::cpu::gasm::/CloseLoop__](#19) - -# <a name='description'></a>DESCRIPTION - -This package provides a simple in\-memory assembler\. Its origin is that of a -support package for use by packages converting PEG and other grammars into a -corresponding matcher based on the ME virtual machine, like -__page::compiler::peg::mecpu__\. Despite that it is actually mostly agnostic -regarding the instructions, users can choose any instruction set they like\. - -The program under construction is held in a graph structure \(See package -__[struct::graph](\.\./struct/graph\.md)__\) during assembly and subsequent -manipulation, with instructions represented by nodes, and the flow of execution -between instructions explicitly encoded in the arcs between them\. - -In this model jumps are not encoded explicitly, they are implicit in the arcs\. -The generation of explicit jumps is left to any code converting the graph -structure into a more conventional representation\. The same goes for branches\. -They are implicitly encoded by all instructions which have two outgoing arcs, -whereas all other instructions have only one outgoing arc\. Their conditonality -is handled by tagging their outgoing arcs with information about the conditions -under which they are taken\. - -While the graph the assembler operates on is supplied from the outside, i\.e\. -external, it does manage some internal state, namely: - - 1. The handle of the graph node most assembler operations will work on, the - *anchor*\. - - 1. A mapping from arbitrary strings to instructions\. I\.e\. it is possible to - *label* an instruction during assembly, and later recall that instruction - by its label\. - - 1. The condition code to use when creating arcs between instructions, which is - one of __always__, __ok__, and __fail__\. - - 1. The current operation mode, one of __halt__, __okfail__, and - __\!okfail__\. - - 1. The name of a node in a tree\. This, and the operation mode above are the - parts most heavily influenced by the needs of a grammar compiler, as they - assume some basic program structures \(selected through the operation mode\), - and intertwine the graph with a tree, like the AST for the grammar to be - compiled\. - -# <a name='section2'></a>DEFINITIONS - -As the graph the assembler is operating on, and the tree it is intertwined with, -are supplied to the assembler from the outside it is necessary to specify the -API expected from them, and to describe the structures expected and/or generated -by the assembler in either\. - - 1. Any graph object command used by the assembler has to provide the API as - specified in the documentation for the package - __[struct::graph](\.\./struct/graph\.md)__\. - - 1. Any tree object command used by the assembler has to provide the API as - specified in the documentation for the package - __[struct::tree](\.\./struct/struct\_tree\.md)__\. - - 1. Any instruction \(node\) generated by the assembler in a graph will have at - least two, and at most three attributes: - - - __instruction__ - - The value of this attribute is the name of the instruction\. The only - names currently defined by the assembler are the three - pseudo\-instructions - - * __NOP__ - - This instruction does nothing\. Useful for fixed framework nodes, - unchanging jump destinations, and the like\. No arguments\. - - * __C__ - - A \.NOP to allow the insertion of arbitrary comments into the - instruction stream, i\.e\. a comment node\. One argument, the text of - the comment\. - - * __BRA__ - - A \.NOP serving as explicitly coded conditional branch\. No - arguments\. - - However we reserve the space of all instructions whose names begin with - a "\." \(dot\) for future use by the assembler\. - - - __arguments__ - - The value of this attribute is a list of strings, the arguments of the - instruction\. The contents are dependent on the actual instruction and - the assembler doesn't know or care about them\. This means for example - that it has no builtin knowledge about what instruction need which - arguments and thus doesn't perform any type of checking\. - - - __expr__ - - This attribute is optional\. When it is present its value is the name of - a node in the tree intertwined with the graph\. - - 1. Any arc between two instructions will have one attribute: - - - __condition__ - - The value of this attribute determines under which condition execution - will take this arc\. It is one of __always__, __ok__, and - __fail__\. The first condition is used for all arcs which are the - single outgoing arc of an instruction\. The other two are used for the - two outgoing arcs of an instruction which implicitly encode a branch\. - - 1. A tree node given to the assembler for cross\-referencing will be written to - and given the following attributes, some fixed, some dependent on the - operation mode\. All values will be references to nodes in the instruction - graph\. Some of the instruction will expect some or specific sets of these - attributes\. - - - __gas::entry__ - - Always written\. - - - __gas::exit__ - - Written for all modes but __okfail__\. - - - __gas::exit::ok__ - - Written for mode __okfail__\. - - - __gas::exit::fail__ - - Written for mode __okfail__\. - -# <a name='section3'></a>API - - - <a name='1'></a>__::grammar::me::cpu::gasm::begin__ *g* *n* ?*mode*? ?*note*? - - This command starts the assembly of an instruction sequence, and - \(re\)initializes the state of the assembler\. After completion of the - instruction sequence use __::grammar::me::cpu::gasm::done__ to finalize - the assembler\. - - It will operate on the graph *g* in the specified *mode* \(Default is - __okfail__\)\. As part of the initialization it will always create a - standard \.NOP instruction and label it "entry"\. The creation of the - remaining standard instructions is *mode*\-dependent: - - * __halt__ - - An "icf\_halt" instruction labeled "exit/return"\. - - * __\!okfail__ - - An "icf\_ntreturn" instruction labeled "exit/return"\. - - * __okfail__ - - Two \.NOP instructions labeled "exit/ok" and "exit/fail" respectively\. - - The *note*, if specified \(default is not\), is given to the "entry" \.NOP - instruction\. - - The node reference *n* is simply stored for use by - __::grammar::me::cpu::gasm::done__\. It has to refer to a node in the - tree *t* argument of that command\. - - After the initialization is done the "entry" instruction will be the - *anchor*, and the condition code will be set to __always__\. - - The command returns the empy string as its result\. - - - <a name='2'></a>__::grammar::me::cpu::gasm::done__ __\-\->__ *t* - - This command finalizes the creation of an instruction sequence and then - clears the state of the assembler\. *NOTE* that this *does not* delete - any of the created instructions\. They can be made available to future - begin/done cycles\. Further assembly will be possible only after - reinitialization of the system via __::grammar::me::cpu::gasm::begin__\. - - Before the state is cleared selected references to selected instructions - will be written to attributes of the node *n* in the tree *t*\. Which - instructions are saved is *mode*\-dependent\. Both *mode* and the - destination node *n* were specified during invokation of - __::grammar::me::cpu::gasm::begin__\. - - Independent of the mode a reference to the instruction labeled "entry" will - be saved to the attribute __gas::entry__ of *n*\. The reference to the - node *n* will further be saved into the attribute "expr" of the "entry" - instruction\. Beyond that - - * __halt__ - - A reference to the instruction labeled "exit/return" will be saved to - the attribute __gas::exit__ of *n*\. - - * __okfail__ - - See __halt__\. - - * __\!okfail__ - - Reference to the two instructions labeled "exit/ok" and "exit/fail" will - be saved to the attributes __gas::exit::ok__ and - __gas::exit::fail__ of *n* respectively\. - - The command returns the empy string as its result\. - - - <a name='3'></a>__::grammar::me::cpu::gasm::state__ - - This command returns the current state of the assembler\. Its format is not - documented and considered to be internal to the package\. - - - <a name='4'></a>__::grammar::me::cpu::gasm::state\!__ *s* - - This command takes a serialized assembler state *s* as returned by - __::grammar::me::cpu::gasm::state__ and makes it the current state of - the assembler\. - - *Note* that this may overwrite label definitions, however all - non\-conflicting label definitions in the state before are not touched and - merged with *s*\. - - The command returns the empty string as its result\. - - - <a name='5'></a>__::grammar::me::cpu::gasm::lift__ *t* *dst* __=__ *src* - - This command operates on the tree *t*\. It copies the contents of the - attributes __gas::entry__, __gas::exit::ok__ and - __gas::exit::fail__ from the node *src* to the node *dst*\. It - returns the empty string as its result\. - - - <a name='6'></a>__::grammar::me::cpu::gasm::Inline__ *t* *node* *label* - - This command links an instruction sequence created by an earlier begin/done - pair into the current instruction sequence\. - - To this end it - - 1. reads the instruction references from the attributes - __gas::entry__, __gas::exit::ok__, and __gas::exit::fail__ - from the node *n* of the tree *t* and makes them available to - assembler und the labels *label*/entry, *label*/exit::ok, and - *label*/exit::fail respectively\. - - 1. Creates an arc from the *anchor* to the node labeled *label*/entry, - and tags it with the current condition code\. - - 1. Makes the node labeled *label*/exit/ok the new *anchor*\. - - The command returns the empty string as its result\. - - - <a name='7'></a>__::grammar::me::cpu::gasm::Cmd__ *cmd* ?*arg*\.\.\.? - - This is the basic command to add instructions to the graph\. It creates a new - instruction of type *cmd* with the given arguments *arg*\.\.\. If the - *anchor* was defined it will also create an arc from the *anchor* to the - new instruction using the current condition code\. After the call the new - instruction will be the *anchor* and the current condition code will be - set to __always__\. - - The command returns the empty string as its result\. - - - <a name='8'></a>__::grammar::me::cpu::gasm::Bra__ - - This is a convenience command to create a \.BRA pseudo\-instruction\. It uses - __::grammar::me::cpu::gasm::Cmd__ to actually create the instruction and - inherits its behaviour\. - - - <a name='9'></a>__::grammar::me::cpu::gasm::Nop__ *text* - - This is a convenience command to create a \.NOP pseudo\-instruction\. It uses - __::grammar::me::cpu::gasm::Cmd__ to actually create the instruction and - inherits its behaviour\. The *text* will be saved as the first and only - argument of the new instruction\. - - - <a name='10'></a>__::grammar::me::cpu::gasm::Note__ *text* - - This is a convenience command to create a \.C pseudo\-instruction, i\.e\. a - comment\. It uses __::grammar::me::cpu::gasm::Cmd__ to actually create - the instruction and inherits its behaviour\. The *text* will be saved as - the first and only argument of the new instruction\. - - - <a name='11'></a>__::grammar::me::cpu::gasm::Jmp__ *label* - - This command creates an arc from the *anchor* to the instruction labeled - with *label*, and tags with the the current condition code\. - - The command returns the empty string as its result\. - - - <a name='12'></a>__::grammar::me::cpu::gasm::Exit__ - - This command creates an arc from the *anchor* to one of the exit - instructions, based on the operation mode \(see - __::grammar::me::cpu::gasm::begin__\), and tags it with current condition - code\. - - For mode __okfail__ it links to the instruction labeled either "exit/ok" - or "exit/fail", depending on the current condition code, and tagging it with - the current condition code For the other two modes it links to the - instruction labeled "exit/return", tagging it condition code __always__, - independent the current condition code\. - - The command returns the empty string as its result\. - - - <a name='13'></a>__::grammar::me::cpu::gasm::Who__ *label* - - This command returns a reference to the instruction labeled with *label*\. - - - <a name='14'></a>__::grammar::me::cpu::gasm::/Label__ *name* - - This command labels the *anchor* with *name*\. *Note* that an - instruction can have more than one label\. - - The command returns the empty string as its result\. - - - <a name='15'></a>__::grammar::me::cpu::gasm::/Clear__ - - This command clears the *anchor*, leaving it undefined, and further resets - the current condition code to __always__\. - - The command returns the empty string as its result\. - - - <a name='16'></a>__::grammar::me::cpu::gasm::/Ok__ - - This command sets the current condition code to __ok__\. - - The command returns the empty string as its result\. - - - <a name='17'></a>__::grammar::me::cpu::gasm::/Fail__ - - This command sets the current condition code to __fail__\. - - The command returns the empty string as its result\. - - - <a name='18'></a>__::grammar::me::cpu::gasm::/At__ *name* - - This command sets the *anchor* to the instruction labeled with *name*, - and further resets the current condition code to __always__\. - - The command returns the empty string as its result\. - - - <a name='19'></a>__::grammar::me::cpu::gasm::/CloseLoop__ - - This command marks the *anchor* as the last instruction in a loop body, by - creating the attribute __LOOP__\. - - The command returns the empty string as its result\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[assembler](\.\./\.\./\.\./\.\./index\.md\#assembler), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[graph](\.\./\.\./\.\./\.\./index\.md\#graph), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[tree](\.\./\.\./\.\./\.\./index\.md\#tree), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_ast.md Index: embedded/md/tcllib/files/modules/grammar_me/me_ast.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_ast.md +++ embedded/md/tcllib/files/modules/grammar_me/me_ast.md @@ -1,154 +0,0 @@ - -[//000000001]: # (grammar::me\_ast \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_ast\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me\_ast\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me\_ast \- Various representations of ASTs - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [AST VALUES](#section2) - - - [AST OBJECTS](#section3) - - - [EXTENDED AST OBJECTS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='description'></a>DESCRIPTION - -This document specifies various representations for the *[abstract syntax -tree](\.\./\.\./\.\./\.\./index\.md\#abstract\_syntax\_tree)*s \(short -*[AST](\.\./\.\./\.\./\.\./index\.md\#ast)*\) generated by instances of ME virtual -machines, independent of variant\. Please go and read the document -__[grammar::me\_intro](me\_intro\.md)__ first if you do not know what a ME -virtual machine is\. - -ASTs and all the representations we specify distinguish between two types of -nodes, namely: - - - Terminal - - Terminal nodes refer to the terminal symbols found in the token stream\. They - are always leaf nodes\. I\.e\. terminal nodes never have children\. - - - Nonterminal - - Nonterminal nodes represent a nonterminal symbol of the grammar used during - parsing\. They can occur as leaf and inner nodes of the tree\. - -Both types of nodes carry basic range information telling a user which parts of -the input are covered by the node by providing the location of the first and -last tokens found within the range\. Locations are provided as non\-negative -integer offsets from the beginning of the token stream, with the first token -found in the stream located at offset 0 \(zero\)\. - -The root of an AS tree can be either a terminal or nonterminal node\. - -# <a name='section2'></a>AST VALUES - -This representation of ASTs is a Tcl list\. The main list represents the root -node of the tree, with the representations of the children nested within\. - -Each node is represented by a single Tcl list containing three or more elements\. -The first element is either the empty string or the name of a nonterminal symbol -\(which is never the empty string\)\. The second and third elements are then the -locations of the first and last tokens\. Any additional elements after the third -are then the representations of the children, with the leftmost child first, -i\.e\. as the fourth element of the list representing the node\. - -# <a name='section3'></a>AST OBJECTS - -In this representation an AST is represented by a Tcl object command whose API -is compatible to the tree objects provided by the package -__[struct::tree](\.\./struct/struct\_tree\.md)__\. I\.e it has to support at -least all of the methods described by that package, and may support more\. - -Because of this the remainder of the specifications is written using the terms -of __[struct::tree](\.\./struct/struct\_tree\.md)__\. - -Each node of the AST directly maps to a node in the tree object\. All data beyond -the child nodes, i\.e\. node type and input locations, are stored in attributes of -the node in the tree object\. They are: - - - type - - The type of the AST node\. The recognized values are __terminal__ and - __nonterminal__\. - - - range - - The locations of the first and last token of the terminal data in the input - covered by the node\. This is a list containing two locations\. - - - detail - - This attribute is present only for nonterminal nodes\. It contains the name - of the nonterminal symbol stored in the node\. - -# <a name='section4'></a>EXTENDED AST OBJECTS - -Extended AST objects are like AST objects, with additional information\. - - - detail - - This attribute is now present at all nodes\. Its contents are unchanged for - nonterminal nodes\. For terminal nodes it contains a list describing all - tokens from the input which are covered by the node\. - - Each element of the list contains the token name, the associated lexeme - attribute, line number, and column index, in this order\. - - - range\_lc - - This new attribute is defined for all nodes, and contains the locations from - attribute *range* translated into line number and column index\. Lines are - counted from 1, columns are counted from 0\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[AST](\.\./\.\./\.\./\.\./index\.md\#ast), [abstract syntax -tree](\.\./\.\./\.\./\.\./index\.md\#abstract\_syntax\_tree) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_cpu.md Index: embedded/md/tcllib/files/modules/grammar_me/me_cpu.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_cpu.md +++ embedded/md/tcllib/files/modules/grammar_me/me_cpu.md @@ -1,323 +0,0 @@ - -[//000000001]: # (grammar::me::cpu \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_cpu\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2006 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me::cpu\(n\) 0\.2 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me::cpu \- Virtual machine implementation II for parsing token streams - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [CLASS API](#subsection1) - - - [OBJECT API](#subsection2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require grammar::me::cpu ?0\.2? - -[__::grammar::me::cpu__ *meName* *matchcode*](#1) -[__meName__ __option__ ?*arg arg \.\.\.*?](#2) -[*meName* __lc__ *location*](#3) -[*meName* __tok__ ?*from* ?*to*??](#4) -[*meName* __pc__ *state*](#5) -[*meName* __iseof__ *state*](#6) -[*meName* __at__ *state*](#7) -[*meName* __cc__ *state*](#8) -[*meName* __sv__](#9) -[*meName* __ok__](#10) -[*meName* __error__](#11) -[*meName* __lstk__ *state*](#12) -[*meName* __astk__ *state*](#13) -[*meName* __mstk__ *state*](#14) -[*meName* __estk__ *state*](#15) -[*meName* __rstk__ *state*](#16) -[*meName* __nc__ *state*](#17) -[*meName* __ast__](#18) -[*meName* __halted__](#19) -[*meName* __code__](#20) -[*meName* __eof__](#21) -[*meName* __put__ *tok* *lex* *line* *col*](#22) -[*meName* __putstring__ *string* *lvar* *cvar*](#23) -[*meName* __run__ ?*n*?](#24) -[*meName* __pull__ *nextcmd*](#25) -[*meName* __reset__](#26) -[*meName* __destroy__](#27) - -# <a name='description'></a>DESCRIPTION - -This package provides an implementation of the ME virtual machine\. Please go and -read the document __[grammar::me\_intro](me\_intro\.md)__ first if you do -not know what a ME virtual machine is\. - -This implementation provides an object\-based API and the machines are not truly -tied to Tcl\. A C implementation of the same API is quite possible\. - -Internally the package actually uses the value\-based machine manipulation -commands as provided by the package -__[grammar::me::cpu::core](me\_cpucore\.md)__ to perform its duties\. - -# <a name='section2'></a>API - -## <a name='subsection1'></a>CLASS API - -The package directly provides only a single command for the construction of ME -virtual machines\. - - - <a name='1'></a>__::grammar::me::cpu__ *meName* *matchcode* - - The command creates a new ME machine object with an associated global Tcl - command whose name is *meName*\. This command may be used to invoke various - operations on the machine\. It has the following general form: - - * <a name='2'></a>__meName__ __option__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - The argument *matchcode* contains the match instructions the machine has - to execute while parsing the input stream\. Please read section __MATCH - CODE REPRESENTATION__ of the documentation for the package - __[grammar::me::cpu::core](me\_cpucore\.md)__ for the specification of - the structure of this value\. - - The *tokmap* argument taken by the implementation provided by the package - __[grammar::me::tcl](me\_tcl\.md)__ is here hidden inside of the match - instructions and therefore not needed\. - -## <a name='subsection2'></a>OBJECT API - -All ME virtual machine objects created by the class command specified in section -[CLASS API](#subsection1) support the methods listed below\. - -The machines provided by this package provide methods for operation in both -push\- and pull\-styles\. Push\-style means that tokens are pushed into the machine -state when they arrive, triggering further execution until they are consumed\. In -other words, this allows the machine to be suspended and resumed at will and an -arbitrary number of times, the quasi\-parallel operation of several machines, and -the operation as part of the event loop\. - - - <a name='3'></a>*meName* __lc__ *location* - - This method converts the location of a token given as offset in the input - stream into the associated line number and column index\. The result of the - command is a 2\-element list containing the two values, in the order - mentioned in the previous sentence\. This allows higher levels to convert the - location information found in the error status and the generated AST into - more human readable data\. - - *Note* that the command is not able to convert locations which have not - been reached by the machine yet\. In other words, if the machine has read 7 - tokens the command is able to convert the offsets __0__ to __6__, - but nothing beyond that\. This also shows that it is not possible to convert - offsets which refer to locations before the beginning of the stream\. - - - <a name='4'></a>*meName* __tok__ ?*from* ?*to*?? - - This method returns a Tcl list containing the part of the input stream - between the locations *from* and *to* \(both inclusive\)\. If *to* is not - specified it will default to the value of *from*\. If *from* is not - specified either the whole input stream is returned\. - - Each element of the returned list is a list of four elements, the token, its - associated lexeme, line number, and column index, in this order\. This - command places the same restrictions on its location arguments as the method - __lc__\. - - - <a name='5'></a>*meName* __pc__ *state* - - This method takes the state value of a ME virtual machine and returns the - current value of the stored program counter\. - - - <a name='6'></a>*meName* __iseof__ *state* - - This method takes the state value of a ME virtual machine and returns the - current value of the stored eof flag\. - - - <a name='7'></a>*meName* __at__ *state* - - This method takes the state value of a ME virtual machine and returns the - current location in the input stream\. - - - <a name='8'></a>*meName* __cc__ *state* - - This method takes the state value of a ME virtual machine and returns the - current token\. - - - <a name='9'></a>*meName* __sv__ - - This command returns the current semantic value *SV* stored in the - machine\. This is an abstract syntax tree as specified in the document - __[grammar::me\_ast](me\_ast\.md)__, section __AST VALUES__\. - - - <a name='10'></a>*meName* __ok__ - - This method returns the current match status *OK*\. - - - <a name='11'></a>*meName* __error__ - - This method returns the current error status *ER*\. - - - <a name='12'></a>*meName* __lstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - location stack\. - - - <a name='13'></a>*meName* __astk__ *state* - - This method takes the state value of a ME virtual machine and returns the - AST stack\. - - - <a name='14'></a>*meName* __mstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - AST marker stack\. - - - <a name='15'></a>*meName* __estk__ *state* - - This method takes the state value of a ME virtual machine and returns the - error stack\. - - - <a name='16'></a>*meName* __rstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - subroutine return stack\. - - - <a name='17'></a>*meName* __nc__ *state* - - This method takes the state value of a ME virtual machine and returns the - nonterminal match cache as a dictionary\. - - - <a name='18'></a>*meName* __ast__ - - This method returns the current top entry of the AST stack *AS*\. This is - an abstract syntax tree as specified in the document - __[grammar::me\_ast](me\_ast\.md)__, section __AST VALUES__\. - - - <a name='19'></a>*meName* __halted__ - - This method returns a boolean value telling the caller whether the engine - has halted execution or not\. Halt means that no further matching is - possible, and the information retrieved via the other method is final\. - Attempts to __run__ the engine will be ignored, until a __reset__ is - made\. - - - <a name='20'></a>*meName* __code__ - - This method returns the *code* information used to construct the object\. - In other words, the match program executed by the machine\. - - - <a name='21'></a>*meName* __eof__ - - This method adds an end of file marker to the end of the input stream\. This - signals the machine that the current contents of the input queue are the - final parts of the input and nothing will come after\. Attempts to put more - characters into the queue will fail\. - - - <a name='22'></a>*meName* __put__ *tok* *lex* *line* *col* - - This method adds the token *tok* to the end of the input stream, with - associated lexeme data *lex* and *line*/*col*umn information\. - - - <a name='23'></a>*meName* __putstring__ *string* *lvar* *cvar* - - This method adds each individual character in the *string* as a token to - the end of the input stream, from first to last\. The lexemes will be empty - and the line/col information is computed based on the characters encountered - and the data in the variables *lvar* and *cvar*\. - - - <a name='24'></a>*meName* __run__ ?*n*? - - This methods causes the engine to execute match instructions until either - - * *n* instructions have been executed, or - - * a halt instruction was executed, or - - * the input queue is empty and the code is asking for more tokens to - process\. - - If no limit *n* was set only the last two conditions are checked for\. - - - <a name='25'></a>*meName* __pull__ *nextcmd* - - This method implements pull\-style operation of the machine\. It causes it to - execute match instructions until either a halt instruction is reached, or - the command prefix *nextcmd* ceases to deliver more tokens\. - - The command prefix *nextcmd* represents the input stream of characters and - is invoked by the machine whenever the a new character from the stream is - required\. The instruction for handling this is *ict\_advance*\. The callback - has to return either the empty list, or a list of 4 elements containing the - token, its lexeme attribute, and its location as line number and column - index, in this order\. The empty list is the signal that the end of the input - stream has been reached\. The lexeme attribute is stored in the terminal - cache, but otherwise not used by the machine\. - - The end of the input stream for this method does not imply that method - __eof__ is called for the machine as a whole\. By avoiding this and still - asking for an explicit call of the method it is possible to mix push\- and - pull\-style operation during the lifetime of the machine\. - - - <a name='26'></a>*meName* __reset__ - - This method resets the machine to its initial state, discarding any state it - may have\. - - - <a name='27'></a>*meName* __destroy__ - - This method deletes the object and releases all resurces it claimed\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005\-2006 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md Index: embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md +++ embedded/md/tcllib/files/modules/grammar_me/me_cpucore.md @@ -1,440 +0,0 @@ - -[//000000001]: # (grammar::me::cpu::core \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_cpucore\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2006 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me::cpu::core\(n\) 0\.2 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me::cpu::core \- ME virtual machine state manipulation - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [MATCH PROGRAM REPRESENTATION](#subsection1) - - - [CPU STATE](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require grammar::me::cpu::core ?0\.2? - -[__::grammar::me::cpu::core__ __disasm__ *asm*](#1) -[__::grammar::me::cpu::core__ __asm__ *asm*](#2) -[__::grammar::me::cpu::core__ __new__ *asm*](#3) -[__::grammar::me::cpu::core__ __lc__ *state* *location*](#4) -[__::grammar::me::cpu::core__ __tok__ *state* ?*from* ?*to*??](#5) -[__::grammar::me::cpu::core__ __pc__ *state*](#6) -[__::grammar::me::cpu::core__ __iseof__ *state*](#7) -[__::grammar::me::cpu::core__ __at__ *state*](#8) -[__::grammar::me::cpu::core__ __cc__ *state*](#9) -[__::grammar::me::cpu::core__ __sv__ *state*](#10) -[__::grammar::me::cpu::core__ __ok__ *state*](#11) -[__::grammar::me::cpu::core__ __error__ *state*](#12) -[__::grammar::me::cpu::core__ __lstk__ *state*](#13) -[__::grammar::me::cpu::core__ __astk__ *state*](#14) -[__::grammar::me::cpu::core__ __mstk__ *state*](#15) -[__::grammar::me::cpu::core__ __estk__ *state*](#16) -[__::grammar::me::cpu::core__ __rstk__ *state*](#17) -[__::grammar::me::cpu::core__ __nc__ *state*](#18) -[__::grammar::me::cpu::core__ __ast__ *state*](#19) -[__::grammar::me::cpu::core__ __halted__ *state*](#20) -[__::grammar::me::cpu::core__ __code__ *state*](#21) -[__::grammar::me::cpu::core__ __eof__ *statevar*](#22) -[__::grammar::me::cpu::core__ __put__ *statevar* *tok* *lex* *line* *col*](#23) -[__::grammar::me::cpu::core__ __run__ *statevar* ?*n*?](#24) - -# <a name='description'></a>DESCRIPTION - -This package provides an implementation of the ME virtual machine\. Please go and -read the document __[grammar::me\_intro](me\_intro\.md)__ first if you do -not know what a ME virtual machine is\. - -This implementation represents each ME virtual machine as a Tcl value and -provides commands to manipulate and query such values to show the effects of -executing instructions, adding tokens, retrieving state, etc\. - -The values fully follow the paradigm of Tcl that every value is a string and -while also allowing C implementations for a proper Tcl\_ObjType to keep all the -important data in native data structures\. Because of the latter it is -recommended to access the state values *only* through the commands of this -package to ensure that internal representation is not shimmered away\. - -The actual structure used by all state values is described in section [CPU -STATE](#section3)\. - -# <a name='section2'></a>API - -The package directly provides only a single command, and all the functionality -is made available through its methods\. - - - <a name='1'></a>__::grammar::me::cpu::core__ __disasm__ *asm* - - This method returns a list containing a disassembly of the match - instructions in *asm*\. The format of *asm* is specified in the section - [MATCH PROGRAM REPRESENTATION](#subsection1)\. - - Each element of the result contains instruction label, instruction name, and - the instruction arguments, in this order\. The label can be the empty string\. - Jump destinations are shown as labels, strings and tokens unencoded\. Token - names are prefixed with their numeric id, if, and only if a tokmap is - defined\. The two components are separated by a colon\. - - - <a name='2'></a>__::grammar::me::cpu::core__ __asm__ *asm* - - This method returns code in the format as specified in section [MATCH - PROGRAM REPRESENTATION](#subsection1) generated from ME assembly code - *asm*, which is in the format as returned by the method __disasm__\. - - - <a name='3'></a>__::grammar::me::cpu::core__ __new__ *asm* - - This method creates state value for a ME virtual machine in its initial - state and returns it as its result\. - - The argument *matchcode* contains a Tcl representation of the match - instructions the machine has to execute while parsing the input stream\. Its - format is specified in the section [MATCH PROGRAM - REPRESENTATION](#subsection1)\. - - The *tokmap* argument taken by the implementation provided by the package - __[grammar::me::tcl](me\_tcl\.md)__ is here hidden inside of the match - instructions and therefore not needed\. - - - <a name='4'></a>__::grammar::me::cpu::core__ __lc__ *state* *location* - - This method takes the state value of a ME virtual machine and uses it to - convert a location in the input stream \(as offset\) into a line number and - column index\. The result of the method is a 2\-element list containing the - two pieces in the order mentioned in the previous sentence\. - - *Note* that the method cannot convert locations which the machine has not - yet read from the input stream\. In other words, if the machine has read 7 - characters so far it is possible to convert the offsets __0__ to - __6__, but nothing beyond that\. This also shows that it is not possible - to convert offsets which refer to locations before the beginning of the - stream\. - - This utility allows higher levels to convert the location offsets found in - the error status and the AST into more human readable data\. - - - <a name='5'></a>__::grammar::me::cpu::core__ __tok__ *state* ?*from* ?*to*?? - - This method takes the state value of a ME virtual machine and returns a Tcl - list containing the part of the input stream between the locations *from* - and *to* \(both inclusive\)\. If *to* is not specified it will default to - the value of *from*\. If *from* is not specified either the whole input - stream is returned\. - - This method places the same restrictions on its location arguments as the - method __lc__\. - - - <a name='6'></a>__::grammar::me::cpu::core__ __pc__ *state* - - This method takes the state value of a ME virtual machine and returns the - current value of the stored program counter\. - - - <a name='7'></a>__::grammar::me::cpu::core__ __iseof__ *state* - - This method takes the state value of a ME virtual machine and returns the - current value of the stored eof flag\. - - - <a name='8'></a>__::grammar::me::cpu::core__ __at__ *state* - - This method takes the state value of a ME virtual machine and returns the - current location in the input stream\. - - - <a name='9'></a>__::grammar::me::cpu::core__ __cc__ *state* - - This method takes the state value of a ME virtual machine and returns the - current token\. - - - <a name='10'></a>__::grammar::me::cpu::core__ __sv__ *state* - - This method takes the state value of a ME virtual machine and returns the - current semantic value stored in it\. This is an abstract syntax tree as - specified in the document __[grammar::me\_ast](me\_ast\.md)__, section - __AST VALUES__\. - - - <a name='11'></a>__::grammar::me::cpu::core__ __ok__ *state* - - This method takes the state value of a ME virtual machine and returns the - match status stored in it\. - - - <a name='12'></a>__::grammar::me::cpu::core__ __error__ *state* - - This method takes the state value of a ME virtual machine and returns the - current error status stored in it\. - - - <a name='13'></a>__::grammar::me::cpu::core__ __lstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - location stack\. - - - <a name='14'></a>__::grammar::me::cpu::core__ __astk__ *state* - - This method takes the state value of a ME virtual machine and returns the - AST stack\. - - - <a name='15'></a>__::grammar::me::cpu::core__ __mstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - AST marker stack\. - - - <a name='16'></a>__::grammar::me::cpu::core__ __estk__ *state* - - This method takes the state value of a ME virtual machine and returns the - error stack\. - - - <a name='17'></a>__::grammar::me::cpu::core__ __rstk__ *state* - - This method takes the state value of a ME virtual machine and returns the - subroutine return stack\. - - - <a name='18'></a>__::grammar::me::cpu::core__ __nc__ *state* - - This method takes the state value of a ME virtual machine and returns the - nonterminal match cache as a dictionary\. - - - <a name='19'></a>__::grammar::me::cpu::core__ __ast__ *state* - - This method takes the state value of a ME virtual machine and returns the - abstract syntax tree currently at the top of the AST stack stored in it\. - This is an abstract syntax tree as specified in the document - __[grammar::me\_ast](me\_ast\.md)__, section __AST VALUES__\. - - - <a name='20'></a>__::grammar::me::cpu::core__ __halted__ *state* - - This method takes the state value of a ME virtual machine and returns the - current halt status stored in it, i\.e\. if the machine has stopped or not\. - - - <a name='21'></a>__::grammar::me::cpu::core__ __code__ *state* - - This method takes the state value of a ME virtual machine and returns the - code stored in it, i\.e\. the instructions executed by the machine\. - - - <a name='22'></a>__::grammar::me::cpu::core__ __eof__ *statevar* - - This method takes the state value of a ME virtual machine as stored in the - variable named by *statevar* and modifies it so that the eof flag inside - is set\. This signals to the machine that whatever token are in the input - queue are the last to be processed\. There will be no more\. - - - <a name='23'></a>__::grammar::me::cpu::core__ __put__ *statevar* *tok* *lex* *line* *col* - - This method takes the state value of a ME virtual machine as stored in the - variable named by *statevar* and modifies it so that the token *tok* is - added to the end of the input queue, with associated lexeme data *lex* and - *line*/*col*umn information\. - - The operation will fail with an error if the eof flag of the machine has - been set through the method __eof__\. - - - <a name='24'></a>__::grammar::me::cpu::core__ __run__ *statevar* ?*n*? - - This method takes the state value of a ME virtual machine as stored in the - variable named by *statevar*, executes a number of instructions and stores - the state resulting from their modifications back into the variable\. - - The execution loop will run until either - - * *n* instructions have been executed, or - - * a halt instruction was executed, or - - * the input queue is empty and the code is asking for more tokens to - process\. - - If no limit *n* was set only the last two conditions are checked for\. - -## <a name='subsection1'></a>MATCH PROGRAM REPRESENTATION - -A match program is represented by nested Tcl list\. The first element, *asm*, -is a list of integer numbers, the instructions to execute, and their arguments\. -The second element, *[pool](\.\./\.\./\.\./\.\./index\.md\#pool)*, is a list of -strings, referenced by the instructions, for error messages, token names, etc\. -The third element, *tokmap*, provides ordering information for the tokens, -mapping their names to their numerical rank\. This element can be empty, forcing -lexicographic comparison when matching ranges\. - -All ME instructions are encoded as integer numbers, with the mapping given -below\. A number of the instructions, those which handle error messages, have -been given an additional argument to supply that message explicitly instead of -having it constructed from token names, etc\. This allows the machine state to -store only the message ids instead of the full strings\. - -Jump destination arguments are absolute indices into the *asm* element, -refering to the instruction to jump to\. Any string arguments are absolute -indices into the *[pool](\.\./\.\./\.\./\.\./index\.md\#pool)* element\. Tokens, -characters, messages, and token \(actually character\) classes to match are coded -as references into the *[pool](\.\./\.\./\.\./\.\./index\.md\#pool)* as well\. - - 1. "__ict\_advance__ *message*" - - 1. "__ict\_match\_token__ *tok* *message*" - - 1. "__ict\_match\_tokrange__ *tokbegin* *tokend* *message*" - - 1. "__ict\_match\_tokclass__ *code* *message*" - - 1. "__inc\_restore__ *branchlabel* *nt*" - - 1. "__inc\_save__ *nt*" - - 1. "__icf\_ntcall__ *branchlabel*" - - 1. "__icf\_ntreturn__" - - 1. "__iok\_ok__" - - 1. "__iok\_fail__" - - 1. "__iok\_negate__" - - 1. "__icf\_jalways__ *branchlabel*" - - 1. "__icf\_jok__ *branchlabel*" - - 1. "__icf\_jfail__ *branchlabel*" - - 1. "__icf\_halt__" - - 1. "__icl\_push__" - - 1. "__icl\_rewind__" - - 1. "__icl\_pop__" - - 1. "__ier\_push__" - - 1. "__ier\_clear__" - - 1. "__ier\_nonterminal__ *message*" - - 1. "__ier\_merge__" - - 1. "__isv\_clear__" - - 1. "__isv\_terminal__" - - 1. "__isv\_nonterminal\_leaf__ *nt*" - - 1. "__isv\_nonterminal\_range__ *nt*" - - 1. "__isv\_nonterminal\_reduce__ *nt*" - - 1. "__ias\_push__" - - 1. "__ias\_mark__" - - 1. "__ias\_mrewind__" - - 1. "__ias\_mpop__" - -# <a name='section3'></a>CPU STATE - -A state value is a list containing the following elements, in the order listed -below: - - 1. *code*: Match instructions, see [MATCH PROGRAM - REPRESENTATION](#subsection1)\. - - 1. *pc*: Program counter, *int*\. - - 1. *halt*: Halt flag, *boolean*\. - - 1. *eof*: Eof flag, *boolean* - - 1. *tc*: Terminal cache, and input queue\. Structure see below\. - - 1. *cl*: Current location, *int*\. - - 1. *ct*: Current token, *[string](\.\./\.\./\.\./\.\./index\.md\#string)*\. - - 1. *ok*: Match status, *boolean*\. - - 1. *sv*: Semantic value, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *er*: Error status, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *ls*: Location stack, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *as*: AST stack, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *ms*: AST marker stack, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *es*: Error stack, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *rs*: Return stack, *[list](\.\./\.\./\.\./\.\./index\.md\#list)*\. - - 1. *nc*: Nonterminal cache, *dictionary*\. - -*tc*, the input queue of tokens waiting for processing and the terminal cache -containing the tokens already processing are one unified data structure simply -holding all tokens and their information, with the current location separating -that which has been processed from that which is waiting\. Each element of the -queue/cache is a list containing the token, its lexeme information, line number, -and column index, in this order\. - -All stacks have their top element aat the end, i\.e\. pushing an item is -equivalent to appending to the list representing the stack, and popping it -removes the last element\. - -*er*, the error status is either empty or a list of two elements, a location -in the input, and a list of messages, encoded as references into the -*[pool](\.\./\.\./\.\./\.\./index\.md\#pool)* element of the *code*\. - -*nc*, the nonterminal cache is keyed by nonterminal name and location, each -value a four\-element list containing current location, match status, semantic -value, and error status, in this order\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005\-2006 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_intro.md Index: embedded/md/tcllib/files/modules/grammar_me/me_intro.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_intro.md +++ embedded/md/tcllib/files/modules/grammar_me/me_intro.md @@ -1,119 +0,0 @@ - -[//000000001]: # (grammar::me\_intro \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me\_intro\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me\_intro \- Introduction to virtual machines for parsing token streams - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='description'></a>DESCRIPTION - -This document is an introduction to and overview of the basic facilities for the -parsing and/or matching of *token* streams\. One possibility often used for the -token domain are characters\. - -The packages themselves all provide variants of one *[virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine)*, called a *match engine* -\(short *ME*\), which has all the facilities needed for the matching and parsing -of a stream, and which are either controlled directly, or are customized with a -match program\. The virtual machine is basically a pushdown automaton, with -additional elements for backtracking and/or handling of semantic data and -construction of abstract syntax trees \(*[AST](\.\./\.\./\.\./\.\./index\.md\#ast)*\)\. - -Because of the high degree of similarity in the actual implementations of the -aforementioned virtual machine and the data structures they receive and generate -these common parts are specified in a separate document which will be referenced -by the documentation for packages actually implementing it\. - -The relevant documents are: - - - __[grammar::me\_vm](me\_vm\.md)__ - - Virtual machine specification\. - - - __[grammar::me\_ast](me\_ast\.md)__ - - Specification of various representations used for abstract syntax trees\. - - - __[grammar::me::util](me\_util\.md)__ - - Utility commands\. - - - __[grammar::me::tcl](me\_tcl\.md)__ - - Singleton ME virtual machine implementation tied to Tcl for control flow and - stacks\. Hardwired for pull operation\. Uninteruptible during processing\. - - - __[grammar::me::cpu](me\_cpu\.md)__ - - Object\-based ME virtual machine implementation with explicit control flow, - and stacks, using bytecodes\. Suspend/Resumable\. Push/pull operation\. - - - __[grammar::me::cpu::core](me\_cpucore\.md)__ - - Core functionality for state manipulation and stepping used in the bytecode - based implementation of ME virtual machines\. - -# <a name='section2'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[CFG](\.\./\.\./\.\./\.\./index\.md\#cfg), [CFL](\.\./\.\./\.\./\.\./index\.md\#cfl), -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TPDL](\.\./\.\./\.\./\.\./index\.md\#tpdl), [context\-free -grammar](\.\./\.\./\.\./\.\./index\.md\#context\_free\_grammar), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_tcl.md Index: embedded/md/tcllib/files/modules/grammar_me/me_tcl.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_tcl.md +++ embedded/md/tcllib/files/modules/grammar_me/me_tcl.md @@ -1,398 +0,0 @@ - -[//000000001]: # (grammar::me::tcl \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_tcl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me::tcl\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me::tcl \- Virtual machine implementation I for parsing token streams - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [MACHINE STATE](#section3) - - - [MACHINE INSTRUCTIONS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require grammar::me::tcl ?0\.1? - -[__::grammar::me::tcl__ __cmd__ *\.\.\.*](#1) -[__::grammar::me::tcl__ __init__ *nextcmd* ?*tokmap*?](#2) -[__::grammar::me::tcl__ __lc__ *location*](#3) -[__::grammar::me::tcl__ __tok__ *from* ?*to*?](#4) -[__::grammar::me::tcl__ __tokens__](#5) -[__::grammar::me::tcl__ __sv__](#6) -[__::grammar::me::tcl__ __ast__](#7) -[__::grammar::me::tcl__ __astall__](#8) -[__::grammar::me::tcl__ __ctok__](#9) -[__::grammar::me::tcl__ __nc__](#10) -[__::grammar::me::tcl__ __next__](#11) -[__::grammar::me::tcl__ __ord__](#12) -[__::grammar::me::tcl::ict\_advance__ *message*](#13) -[__::grammar::me::tcl::ict\_match\_token__ *tok* *message*](#14) -[__::grammar::me::tcl::ict\_match\_tokrange__ *tokbegin* *tokend* *message*](#15) -[__::grammar::me::tcl::ict\_match\_tokclass__ *code* *message*](#16) -[__::grammar::me::tcl::inc\_restore__ *nt*](#17) -[__::grammar::me::tcl::inc\_save__ *nt* *startlocation*](#18) -[__::grammar::me::tcl::iok\_ok__](#19) -[__::grammar::me::tcl::iok\_fail__](#20) -[__::grammar::me::tcl::iok\_negate__](#21) -[__::grammar::me::tcl::icl\_get__](#22) -[__::grammar::me::tcl::icl\_rewind__ *oldlocation*](#23) -[__::grammar::me::tcl::ier\_get__](#24) -[__::grammar::me::tcl::ier\_clear__](#25) -[__::grammar::me::tcl::ier\_nonterminal__ *message* *location*](#26) -[__::grammar::me::tcl::ier\_merge__ *olderror*](#27) -[__::grammar::me::tcl::isv\_clear__](#28) -[__::grammar::me::tcl::isv\_terminal__](#29) -[__::grammar::me::tcl::isv\_nonterminal\_leaf__ *nt* *startlocation*](#30) -[__::grammar::me::tcl::isv\_nonterminal\_range__ *nt* *startlocation*](#31) -[__::grammar::me::tcl::isv\_nonterminal\_reduce__ *nt* *startlocation* ?*marker*?](#32) -[__::grammar::me::tcl::ias\_push__](#33) -[__::grammar::me::tcl::ias\_mark__](#34) -[__::grammar::me::tcl::ias\_pop2mark__ *marker*](#35) - -# <a name='description'></a>DESCRIPTION - -This package provides an implementation of the ME virtual machine\. Please go and -read the document __[grammar::me\_intro](me\_intro\.md)__ first if you do -not know what a ME virtual machine is\. - -This implementation is tied very strongly to Tcl\. All the stacks in the machine -state are handled through the Tcl stack, all control flow is handled by Tcl -commands, and the remaining machine instructions are directly mapped to Tcl -commands\. Especially the matching of nonterminal symbols is handled by Tcl -procedures as well, essentially extending the machine implementation with custom -instructions\. - -Further on the implementation handles only a single machine which is -uninteruptible during execution and hardwired for pull operation\. I\.e\. it -explicitly requests each new token through a callback, pulling them into its -state\. - -A related package is -__[grammar::peg::interp](\.\./grammar\_peg/peg\_interp\.md)__ which provides -a generic interpreter / parser for parsing expression grammars \(PEGs\), -implemented on top of this implementation of the ME virtual machine\. - -# <a name='section2'></a>API - -The commands documented in this section do not implement any of the instructions -of the ME virtual machine\. They provide the facilities for the initialization of -the machine and the retrieval of important information\. - - - <a name='1'></a>__::grammar::me::tcl__ __cmd__ *\.\.\.* - - This is an ensemble command providing access to the commands listed in this - section\. See the methods themselves for detailed specifications\. - - - <a name='2'></a>__::grammar::me::tcl__ __init__ *nextcmd* ?*tokmap*? - - This command \(re\)initializes the machine\. It returns the empty string\. This - command has to be invoked before any other command of this package\. - - The command prefix *nextcmd* represents the input stream of characters and - is invoked by the machine whenever the a new character from the stream is - required\. The instruction for handling this is *ict\_advance*\. The callback - has to return either the empty list, or a list of 4 elements containing the - token, its lexeme attribute, and its location as line number and column - index, in this order\. The empty list is the signal that the end of the input - stream has been reached\. The lexeme attribute is stored in the terminal - cache, but otherwise not used by the machine\. - - The optional dictionary *tokmap* maps from tokens to integer numbers\. If - present the numbers impose an order on the tokens, which is subsequently - used by *ict\_match\_tokrange* to determine if a token is in the specified - range or not\. If no token map is specified the lexicographic order of th - token names will be used instead\. This choice is especially asensible when - using characters as tokens\. - - - <a name='3'></a>__::grammar::me::tcl__ __lc__ *location* - - This command converts the location of a token given as offset in the input - stream into the associated line number and column index\. The result of the - command is a 2\-element list containing the two values, in the order - mentioned in the previous sentence\. This allows higher levels to convert the - location information found in the error status and the generated AST into - more human readable data\. - - *Note* that the command is not able to convert locations which have not - been reached by the machine yet\. In other words, if the machine has read 7 - tokens the command is able to convert the offsets __0__ to __6__, - but nothing beyond that\. This also shows that it is not possible to convert - offsets which refer to locations before the beginning of the stream\. - - After a call of __init__ the state used for the conversion is cleared, - making further conversions impossible until the machine has read tokens - again\. - - - <a name='4'></a>__::grammar::me::tcl__ __tok__ *from* ?*to*? - - This command returns a Tcl list containing the part of the input stream - between the locations *from* and *to* \(both inclusive\)\. If *to* is not - specified it will default to the value of *from*\. - - Each element of the returned list is a list of four elements, the token, its - associated lexeme, line number, and column index, in this order\. In other - words, each element has the same structure as the result of the *nextcmd* - callback given to __::grammar::me::tcl::init__ - - This command places the same restrictions on its location arguments as - __::grammar::me::tcl::lc__\. - - - <a name='5'></a>__::grammar::me::tcl__ __tokens__ - - This command returns the number of tokens currently known to the ME virtual - machine\. - - - <a name='6'></a>__::grammar::me::tcl__ __sv__ - - This command returns the current semantic value *SV* stored in the - machine\. This is an abstract syntax tree as specified in the document - __[grammar::me\_ast](me\_ast\.md)__, section __AST VALUES__\. - - - <a name='7'></a>__::grammar::me::tcl__ __ast__ - - This method returns the abstract syntax tree currently at the top of the AST - stack of the ME virtual machine\. This is an abstract syntax tree as - specified in the document __[grammar::me\_ast](me\_ast\.md)__, section - __AST VALUES__\. - - - <a name='8'></a>__::grammar::me::tcl__ __astall__ - - This method returns the whole stack of abstract syntax trees currently known - to the ME virtual machine\. Each element of the returned list is an abstract - syntax tree as specified in the document - __[grammar::me\_ast](me\_ast\.md)__, section __AST VALUES__\. The - top of the stack resides at the end of the list\. - - - <a name='9'></a>__::grammar::me::tcl__ __ctok__ - - This method returns the current token considered by the ME virtual machine\. - - - <a name='10'></a>__::grammar::me::tcl__ __nc__ - - This method returns the contents of the nonterminal cache as a dictionary - mapping from "__symbol__,__location__" to match information\. - - - <a name='11'></a>__::grammar::me::tcl__ __next__ - - This method returns the next token callback as specified during - initialization of the ME virtual machine\. - - - <a name='12'></a>__::grammar::me::tcl__ __ord__ - - This method returns a dictionary containing the *tokmap* specified during - initialization of the ME virtual machine\. - ____::grammar::me::tcl::ok____ This variable contains the current - match status *OK*\. It is provided as variable instead of a command because - that makes access to this information faster, and the speed of access is - considered very important here as this information is used constantly to - determine the control flow\. - -# <a name='section3'></a>MACHINE STATE - -Please go and read the document __[grammar::me\_vm](me\_vm\.md)__ first for -a specification of the basic ME virtual machine and its state\. - -This implementation manages the state described in that document, except for the -stacks minus the AST stack\. In other words, location stack, error stack, return -stack, and ast marker stack are implicitly managed through standard Tcl scoping, -i\.e\. Tcl variables in procedures, outside of this implementation\. - -# <a name='section4'></a>MACHINE INSTRUCTIONS - -Please go and read the document __[grammar::me\_vm](me\_vm\.md)__ first for -a specification of the basic ME virtual machine and its instruction set\. - -This implementation maps all instructions to Tcl commands in the namespace -"::grammar::me::tcl", except for the stack related commands, nonterminal symbols -and control flow\. Here we simply list the commands and explain the differences -to the specified instructions, if there are any\. For their semantics see the -aforementioned specification\. The machine commands are *not* reachable through -the ensemble command __::grammar::me::tcl__\. - - - <a name='13'></a>__::grammar::me::tcl::ict\_advance__ *message* - - No changes\. - - - <a name='14'></a>__::grammar::me::tcl::ict\_match\_token__ *tok* *message* - - No changes\. - - - <a name='15'></a>__::grammar::me::tcl::ict\_match\_tokrange__ *tokbegin* *tokend* *message* - - If, and only if a token map was specified during initialization then the - arguments are the numeric representations of the smallest and largest tokens - in the range\. Otherwise they are the relevant tokens themselves and - lexicographic comparison is used\. - - - <a name='16'></a>__::grammar::me::tcl::ict\_match\_tokclass__ *code* *message* - - No changes\. - - - <a name='17'></a>__::grammar::me::tcl::inc\_restore__ *nt* - - Instead of taking a branchlabel the command returns a boolean value\. The - result will be __true__ if and only if cached information was found\. The - caller has to perform the appropriate branching\. - - - <a name='18'></a>__::grammar::me::tcl::inc\_save__ *nt* *startlocation* - - The command takes the start location as additional argument, as it is - managed on the Tcl stack, and not in the machine state\. - - - __icf\_ntcall__ *branchlabel* - - - __icf\_ntreturn__ - - These two instructions are not mapped to commands\. They are control flow - instructions and handled in Tcl\. - - - <a name='19'></a>__::grammar::me::tcl::iok\_ok__ - - No changes\. - - - <a name='20'></a>__::grammar::me::tcl::iok\_fail__ - - No changes\. - - - <a name='21'></a>__::grammar::me::tcl::iok\_negate__ - - No changes\. - - - __icf\_jalways__ *branchlabel* - - - __icf\_jok__ *branchlabel* - - - __icf\_jfail__ *branchlabel* - - - __icf\_halt__ - - These four instructions are not mapped to commands\. They are control flow - instructions and handled in Tcl\. - - - <a name='22'></a>__::grammar::me::tcl::icl\_get__ - - This command returns the current location *CL* in the input\. It replaces - *icl\_push*\. - - - <a name='23'></a>__::grammar::me::tcl::icl\_rewind__ *oldlocation* - - The command takes the location as argument as it comes from the Tcl stack, - not the machine state\. - - - __icl\_pop__ - - Not mapped, the stacks are not managed by the package\. - - - <a name='24'></a>__::grammar::me::tcl::ier\_get__ - - This command returns the current error state *ER*\. It replaces - *ier\_push*\. - - - <a name='25'></a>__::grammar::me::tcl::ier\_clear__ - - No changes\. - - - <a name='26'></a>__::grammar::me::tcl::ier\_nonterminal__ *message* *location* - - The command takes the location as argument as it comes from the Tcl stack, - not the machine state\. - - - <a name='27'></a>__::grammar::me::tcl::ier\_merge__ *olderror* - - The command takes the second error state to merge as argument as it comes - from the Tcl stack, not the machine state\. - - - <a name='28'></a>__::grammar::me::tcl::isv\_clear__ - - No changes\. - - - <a name='29'></a>__::grammar::me::tcl::isv\_terminal__ - - No changes\. - - - <a name='30'></a>__::grammar::me::tcl::isv\_nonterminal\_leaf__ *nt* *startlocation* - - The command takes the start location as argument as it comes from the Tcl - stack, not the machine state\. - - - <a name='31'></a>__::grammar::me::tcl::isv\_nonterminal\_range__ *nt* *startlocation* - - The command takes the start location as argument as it comes from the Tcl - stack, not the machine state\. - - - <a name='32'></a>__::grammar::me::tcl::isv\_nonterminal\_reduce__ *nt* *startlocation* ?*marker*? - - The command takes start location and marker as argument as it comes from the - Tcl stack, not the machine state\. - - - <a name='33'></a>__::grammar::me::tcl::ias\_push__ - - No changes\. - - - <a name='34'></a>__::grammar::me::tcl::ias\_mark__ - - This command returns a marker for the current state of the AST stack *AS*\. - The marker stack is not managed by the machine\. - - - <a name='35'></a>__::grammar::me::tcl::ias\_pop2mark__ *marker* - - The command takes the marker as argument as it comes from the Tcl stack, not - the machine state\. It replaces *ias\_mpop*\. - -# <a name='section5'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_util.md Index: embedded/md/tcllib/files/modules/grammar_me/me_util.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_util.md +++ embedded/md/tcllib/files/modules/grammar_me/me_util.md @@ -1,122 +0,0 @@ - -[//000000001]: # (grammar::me::util \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_util\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me::util\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me::util \- AST utilities - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require grammar::me::util ?0\.1? - -[__::grammar::me::util::ast2tree__ *ast* *tree* ?*root*?](#1) -[__::grammar::me::util::ast2etree__ *ast* *mcmd* *tree* ?*root*?](#2) -[__mcmd__ __lc__ *location*](#3) -[__mcmd__ __tok__ *from* ?*to*?](#4) -[__::grammar::me::util::tree2ast__ *tree* ?*root*?](#5) - -# <a name='description'></a>DESCRIPTION - -This package provides a number of utility command for the conversion between the -various representations of abstract syntax trees as specified in the document -__[grammar::me\_ast](me\_ast\.md)__\. - - - <a name='1'></a>__::grammar::me::util::ast2tree__ *ast* *tree* ?*root*? - - This command converts an *ast* from value to object representation\. All - nodes in the *ast* will be converted into nodes of this *tree*, with the - root of the AST a child of the node *root*\. If this node is not explicitly - specified the root of the tree is used\. Existing content of tree is not - touched, i\.e\. neither removed nor changed, with the exception of the - specified root node, which will gain a new child\. - - - <a name='2'></a>__::grammar::me::util::ast2etree__ *ast* *mcmd* *tree* ?*root*? - - This command is like __::grammar::me::util::ast2tree__, except that the - result is in the extended object representation of the input AST\. The source - of the extended information is the command prefix *mcmd*\. It has to - understand two methods, __lc__, and __tok__, with the semantics - specified below\. - - * <a name='3'></a>__mcmd__ __lc__ *location* - - Takes the location of a token given as offset in the input stream and - return a 2\-element list containing the associated line number and column - index, in this order\. - - * <a name='4'></a>__mcmd__ __tok__ *from* ?*to*? - - Takes one or two locations *from* and *to* as offset in the input - stream and returns a Tcl list containing the specified part of the input - stream\. Both location are inclusive\. If *to* is not specified it will - default to the value of *from*\. - - Each element of the returned list is a list containing the token, its - associated lexeme, the line number, and column index, in this order\. - - Both the ensemble command __::grammar::me::tcl__ provided by the package - __[grammar::me::tcl](me\_tcl\.md)__ and the objects command created by - the package __::grammar::me::cpu__ fit the above specification\. - - - <a name='5'></a>__::grammar::me::util::tree2ast__ *tree* ?*root*? - - This command converts an *ast* in \(extended\) object representation into a - value and returns it\. If a *root* node is specified the AST is generated - from that node downward\. Otherwise the root of the tree object is used as - the starting point\. - -# <a name='section2'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[abstract syntax tree](\.\./\.\./\.\./\.\./index\.md\#abstract\_syntax\_tree), [syntax -tree](\.\./\.\./\.\./\.\./index\.md\#syntax\_tree), -[tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_me/me_vm.md Index: embedded/md/tcllib/files/modules/grammar_me/me_vm.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_me/me_vm.md +++ embedded/md/tcllib/files/modules/grammar_me/me_vm.md @@ -1,560 +0,0 @@ - -[//000000001]: # (grammar::me\_vm \- Grammar operations and usage) -[//000000002]: # (Generated from file 'me\_vm\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::me\_vm\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::me\_vm \- Virtual machine for parsing token streams - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [MACHINE STATE](#section2) - - - [MACHINE INSTRUCTIONS](#section3) - - - [TERMINAL MATCHING](#subsection1) - - - [NONTERMINAL MATCHING](#subsection2) - - - [UNCONDITIONAL MATCHING](#subsection3) - - - [CONTROL FLOW](#subsection4) - - - [INPUT LOCATION HANDLING](#subsection5) - - - [ERROR HANDLING](#subsection6) - - - [SEMANTIC VALUES](#subsection7) - - - [AST STACK HANDLING](#subsection8) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='description'></a>DESCRIPTION - -Please go and read the document __[grammar::me\_intro](me\_intro\.md)__ -first for an overview of the various documents and their relations\. - -This document specifies a virtual machine for the controlled matching and -parsing of token streams, creating an *[abstract syntax -tree](\.\./\.\./\.\./\.\./index\.md\#abstract\_syntax\_tree)* \(short -*[AST](\.\./\.\./\.\./\.\./index\.md\#ast)*\) reflecting the structure of the input\. -Special machine features are the caching and reuse of partial results, caching -of the encountered input, and the ability to backtrack in both input and AST -creation\. - -These features make the specified virtual machine especially useful to packrat -parsers based on parsing expression grammars\. It is however not restricted to -this type of parser\. Normal LL and LR parsers can be implemented with it as -well\. - -The following sections will discuss first the abstract state kept by ME virtual -machines, and then their instruction set\. - -# <a name='section2'></a>MACHINE STATE - -A ME virtual machine manages the following state: - - - *Current token* CT - - The token from the input under consideration by the machine\. - - This information is used and modified by the instructions defined in the - section [TERMINAL MATCHING](#subsection1)\. - - - *Current location* CL - - The location of the *current token* in the input stream, as offset - relative to the beginning of the stream\. The first token is considered to be - at offset __0__\. - - This information is implicitly used and modified by the instructions defined - in the sections [TERMINAL MATCHING](#subsection1) and [NONTERMINAL - MATCHING](#subsection2), and can be directly queried and modified by the - instructions defined in section [INPUT LOCATION - HANDLING](#subsection5)\. - - - *Location stack* LS - - In addition to the above a stack of locations, for backtracking\. Locations - can put on the stack, removed from it, and removed with setting the current - location\. - - This information is implicitly used and modified by the instructions defined - in the sections [TERMINAL MATCHING](#subsection1) and [NONTERMINAL - MATCHING](#subsection2), and can be directly queried and modified by the - instructions defined in section [INPUT LOCATION - HANDLING](#subsection5)\. - - - *Match status* OK - - A boolean value, the result of the last attempt at matching input\. It is set - to __true__ if that attempt was successful, and __false__ otherwise\. - - This information is influenced by the instructions defined in the sections - [TERMINAL MATCHING](#subsection1), [NONTERMINAL - MATCHING](#subsection2), and [UNCONDITIONAL - MATCHING](#subsection3)\. It is queried by the instructions defined in - the section [CONTROL FLOW](#subsection4)\. - - - *Semantic value* SV - - The semantic value associated with \(generated by\) the last attempt at - matching input\. Contains either the empty string or a node for the abstract - syntax tree constructed from the input\. - - This information is influenced by the instructions defined in the sections - [SEMANTIC VALUES](#subsection7), and [AST STACK - HANDLING](#subsection8)\. - - - *AST stack* AS - - A stack of partial abstract syntax trees constructed by the machine during - matching\. - - This information is influenced by the instructions defined in the sections - [SEMANTIC VALUES](#subsection7), and [AST STACK - HANDLING](#subsection8)\. - - - *AST Marker stack* MS - - In addition to the above a stack of stacks, for backtracking\. This is - actually a stack of markers into the AST stack, thus implicitly snapshooting - the state of the AST stack at some point in time\. Markers can be put on the - stack, dropped from it, and used to roll back the AST stack to an earlier - state\. - - This information is influenced by the instructions defined in the sections - [SEMANTIC VALUES](#subsection7), and [AST STACK - HANDLING](#subsection8)\. - - - *Error status* ER - - Error information associated with the last attempt at matching input\. - Contains either the empty string or a list of 2 elements, a location in the - input and a list of error messages associated with it, in this order\. - - *Note* that error information can be set even if the last attempt at - matching input was successful\. For example the \*\-operator \(matching a - sub\-expression zero or more times\) in a parsing expression grammar is always - successful, even if it encounters a problem further in the input and has to - backtrack\. Such problems must not be forgotten when continuing to match\. - - This information is queried and influenced by the instructions defined in - the sections [TERMINAL MATCHING](#subsection1), [NONTERMINAL - MATCHING](#subsection2), and [ERROR HANDLING](#subsection6)\. - - - *Error stack* ES - - In addition to the above a stack of error information, to allow the merging - of current and older error information when performing backtracking in - choices after an unsucessful match\. - - This information is queried and influenced by the instructions defined in - the sections [TERMINAL MATCHING](#subsection1), [NONTERMINAL - MATCHING](#subsection2), and [ERROR HANDLING](#subsection6)\. - - - *Return stack* RS - - A stack of program counter values, i\.e\. locations in the code controlling - the virtual machine, for the management of subroutine calls, i\.e\. the - matching of nonterminal symbols\. - - This information is queried and influenced by the instructions defined in - the section [NONTERMINAL MATCHING](#subsection2)\. - - - *Nonterminal cache* NC - - A cache of machine states \(A 4\-tuple containing a location in the input, - match status *OK*, semantic value *SV*, and error status *ER*\) keyed - by name of nonterminal symbol and location in the input stream\. - - The key location is where machine started the attempt to match the named - nonterminal symbol, and the location in the value is where machine ended up - after the attempt completed, independent of the success of the attempt\. - - This status is queried and influenced by the instructions defined in the - section [NONTERMINAL MATCHING](#subsection2)\. - -# <a name='section3'></a>MACHINE INSTRUCTIONS - -With the machine state specified it is now possible to explain the instruction -set of ME virtual machines\. They are grouped roughly by the machine state they -influence and/or query\. - -## <a name='subsection1'></a>TERMINAL MATCHING - -First the instructions to match tokens from the input stream, and by extension -all terminal symbols\. - -These instructions are the only ones which may retrieve a new token from the -input stream\. This is a *may* and not a *will* because the instructions will -a retrieve new token if, and only if the current location *CL* is at the head -of the stream\. If the machine has backtracked \(see __icl\_rewind__\) the -instructions will retrieve the token to compare against from the internal cache\. - - - __ict\_advance__ *message* - - This instruction tries to advance to the next token in the input stream, - i\.e\. the one after the current location *CL*\. The instruction will fail - if, and only if the end of the input stream is reached, i\.e\. if there is no - next token\. - - The sucess/failure of the instruction is remembered in the match status - *OK*\. In the case of failure the error status *ER* is set to the current - location and the message *message*\. In the case of success the error - status *ER* is cleared, the new token is made the current token *CT*, - and the new location is made the current location *CL*\. - - The argument *message* is a reference to the string to put into the error - status *ER*, if such is needed\. - - - __ict\_match\_token__ *tok* *message* - - This instruction tests the current token *CT* for equality with the - argument *tok* and records the result in the match status *OK*\. The - instruction fails if the current token is not equal to *tok*\. - - In case of failure the error status *ER* is set to the current location - *CL* and the message *message*, and the current location *CL* is moved - one token backwards\. Otherwise, i\.e\. upon success, the error status *ER* - is cleared and the current location *CL* is not touched\. - - - __ict\_match\_tokrange__ *tokbegin* *tokend* *message* - - This instruction tests the current token *CT* for being in the range of - tokens from *tokbegin* to *tokend* \(inclusive\) and records the result in - the match status *OK*\. The instruction fails if the current token is not - inside the range\. - - In case of failure the error status *ER* is set to the current location - *CL* and the message *message*, and the current location *CL* is moved - one token backwards\. Otherwise, i\.e\. upon success, the error status *ER* - is cleared and the current location *CL* is not touched\. - - - __ict\_match\_tokclass__ *code* *message* - - This instruction tests the current token *CT* for being a member of the - token class *code* and records the result in the match status *OK*\. The - instruction fails if the current token is not a member of the specified - class\. - - In case of failure the error status *ER* is set to the current location - *CL* and the message *message*, and the current location *CL* is moved - one token backwards\. Otherwise, i\.e\. upon success, the error status *ER* - is cleared and the current location *CL* is not touched\. - - Currently the following classes are legal: - - * alnum - - A token is accepted if it is a unicode alphabetical character, or a - digit\. - - * alpha - - A token is accepted if it is a unicode alphabetical character\. - - * digit - - A token is accepted if it is a unicode digit character\. - - * xdigit - - A token is accepted if it is a hexadecimal digit character\. - - * punct - - A token is accepted if it is a unicode punctuation character\. - - * space - - A token is accepted if it is a unicode space character\. - -## <a name='subsection2'></a>NONTERMINAL MATCHING - -The instructions in this section handle the matching of nonterminal symbols\. -They query the nonterminal cache *NC* for saved information, and put such -information into the cache\. - -The usage of the cache is a performance aid for backtracking parsers, allowing -them to avoid an expensive rematch of complex nonterminal symbols if they have -been encountered before\. - - - __inc\_restore__ *branchlabel* *nt* - - This instruction checks if the nonterminal cache *NC* contains information - about the nonterminal symbol *nt*, at the current location *CL*\. If that - is the case the instruction will update the machine state \(current location - *CL*, match status *OK*, semantic value *SV*, and error status *ER*\) - with the found information and continue execution at the instruction refered - to by the *branchlabel*\. The new current location *CL* will be the last - token matched by the nonterminal symbol, i\.e\. belonging to it\. - - If no information was found the instruction will continue execution at the - next instruction\. - - Together with __icf\_ntcall__ it is possible to generate code for - memoized and non\-memoized matching of nonterminal symbols, either as - subroutine calls, or inlined in the caller\. - - - __inc\_save__ *nt* - - This instruction saves the current state of the machine \(current location - *CL*, match status *OK*, semantic value *SV*, and error status - *ER*\), to the nonterminal cache *NC*\. It will also pop an entry from the - location stack *LS* and save it as the start location of the match\. - - It is expected to be called at the end of matching a nonterminal symbol, - with *nt* the name of the nonterminal symbol the code was working on\. This - allows the instruction __inc\_restore__ to check for and retrieve the - data, should we have to match this nonterminal symbol at the same location - again, during backtracking\. - - - __icf\_ntcall__ *branchlabel* - - This instruction invokes the code for matching the nonterminal symbol *nt* - as a subroutine\. To this end it stores the current program counter *PC* on - the return stack *RS*, the current location *CL* on the location stack - *LS*, and then continues execution at the address *branchlabel*\. - - The next matching __icf\_ntreturn__ will cause the execution to continue - at the instruction coming after the call\. - - - __icf\_ntreturn__ - - This instruction will pop an entry from the return stack *RS*, assign it - to the program counter *PC*, and then continue execution at the new - address\. - -## <a name='subsection3'></a>UNCONDITIONAL MATCHING - -The instructions in this section are the remaining match operators\. They change -the match status *OK* directly and unconditionally\. - - - __iok\_ok__ - - This instruction sets the match status *OK* to __true__, indicating a - successful match\. - - - __iok\_fail__ - - This instruction sets the match status *OK* to __false__, indicating a - failed match\. - - - __iok\_negate__ - - This instruction negates the match status *OK*, turning a failure into a - success and vice versa\. - -## <a name='subsection4'></a>CONTROL FLOW - -The instructions in this section implement both conditional and unconditional -control flow\. The conditional jumps query the match status *OK*\. - - - __icf\_jalways__ *branchlabel* - - This instruction sets the program counter *PC* to the address specified by - *branchlabel* and then continues execution from there\. This is an - unconditional jump\. - - - __icf\_jok__ *branchlabel* - - This instruction sets the program counter *PC* to the address specified by - *branchlabel*\. This happens if, and only if the match status *OK* - indicates a success\. Otherwise it simply continues execution at the next - instruction\. This is a conditional jump\. - - - __icf\_jfail__ *branchlabel* - - This instruction sets the program counter *PC* to the address specified by - *branchlabel*\. This happens if, and only if the match status *OK* - indicates a failure\. Otherwise it simply continues execution at the next - instruction\. This is a conditional jump\. - - - __icf\_halt__ - - This instruction halts the machine and blocks any further execution\. - -## <a name='subsection5'></a>INPUT LOCATION HANDLING - -The instructions in this section are for backtracking, they manipulate the -current location *CL* of the machine state\. They allow a user of the machine -to query and save locations in the input, and to rewind the current location -*CL* to saved locations, making them one of the components enabling the -implementation of backtracking parsers\. - - - __icl\_push__ - - This instruction pushes a copy of the current location *CL* on the - location stack *LS*\. - - - __icl\_rewind__ - - This instruction pops an entry from the location stack *LS* and then moves - the current location *CL* back to this point in the input\. - - - __icl\_pop__ - - This instruction pops an entry from the location stack *LS* and discards - it\. - -## <a name='subsection6'></a>ERROR HANDLING - -The instructions in this section provide read and write access to the error -status *ER* of the machine\. - - - __ier\_push__ - - This instruction pushes a copy of the current error status *ER* on the - error stack *ES*\. - - - __ier\_clear__ - - This instruction clears the error status *ER*\. - - - __ier\_nonterminal__ *message* - - This instruction checks if the error status *ER* contains an error whose - location is just past the location found in the top entry of the location - stack *LS*\. Nothing happens if no such error is found\. Otherwise the found - error is replaced by an error at the location found on the stack, having the - message *message*\. - - - __ier\_merge__ - - This instruction pops an entry from the error stack *ES*, merges it with - the current error status *ER* and stores the result of the merge as the - new error status *ER*\. - - The merge is performed as described below: - - If one of the two error states is empty the other is chosen\. If neither - error state is empty, and refering to different locations, then the error - state with the location further in the input is chosen\. If both error states - refer to the same location their messages are merged \(with removing - duplicates\)\. - -## <a name='subsection7'></a>SEMANTIC VALUES - -The instructions in this section manipulate the semantic value *SV*\. - - - __isv\_clear__ - - This instruction clears the semantic value *SV*\. - - - __isv\_terminal__ - - This instruction creates a terminal AST node for the current token *CT*, - makes it the semantic value *SV*, and also pushes the node on the AST - stack *AS*\. - - - __isv\_nonterminal\_leaf__ *nt* - - This instruction creates a nonterminal AST node without any children for the - nonterminal *nt*, and makes it the semantic value *SV*\. - - This instruction should be executed if, and only if the match status *OK* - indicates a success\. In the case of a failure __isv\_clear__ should be - called\. - - - __isv\_nonterminal\_range__ *nt* - - This instruction creates a nonterminal AST node for the nonterminal *nt*, - with a single terminal node as its child, and makes this AST the semantic - value *SV*\. The terminal node refers to the input string from the location - found on top of the location stack *LS* to the current location *CL* - \(both inclusive\)\. - - This instruction should be executed if, and only if the match status *OK* - indicates a success\. In the case of a failure __isv\_clear__ should be - called\. - - - __isv\_nonterminal\_reduce__ *nt* - - This instruction creates a nonterminal AST node for the nonterminal *nt* - and makes it the semantic value *SV*\. - - All entries on the AST stack *AS* above the marker found in the top entry - of the AST Marker stack *MS* become children of the new node, with the - entry at the stack top becoming the rightmost child\. If the AST Marker stack - *MS* is empty the whole stack is used\. The AST marker stack *MS* is left - unchanged\. - - This instruction should be executed if, and only if the match status *OK* - indicates a success\. In the case of a failure __isv\_clear__ should be - called\. - -## <a name='subsection8'></a>AST STACK HANDLING - -The instructions in this section manipulate the AST stack *AS*, and the AST -Marker stack *MS*\. - - - __ias\_push__ - - This instruction pushes the semantic value *SV* on the AST stack *AS*\. - - - __ias\_mark__ - - This instruction pushes a marker for the current state of the AST stack - *AS* on the AST Marker stack *MS*\. - - - __ias\_mrewind__ - - This instruction pops an entry from the AST Marker stack *MS* and then - proceeds to pop entries from the AST stack *AS* until the state - represented by the popped marker has been reached again\. Nothing is done if - the AST stack *AS* is already smaller than indicated by the popped marker\. - - - __ias\_mpop__ - - This instruction pops an entry from the AST Marker stack *MS* and discards - it\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_me* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_peg/peg.md Index: embedded/md/tcllib/files/modules/grammar_peg/peg.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_peg/peg.md +++ embedded/md/tcllib/files/modules/grammar_peg/peg.md @@ -1,573 +0,0 @@ - -[//000000001]: # (grammar::peg \- Grammar operations and usage) -[//000000002]: # (Generated from file 'peg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::peg\(n\) 0\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::peg \- Create and manipulate parsing expression grammars - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TERMS & CONCEPTS](#subsection1) - - - [CONTAINER CLASS API](#subsection2) - - - [CONTAINER OBJECT API](#subsection3) - - - [PARSING EXPRESSIONS](#subsection4) - - - [PARSING EXPRESSION GRAMMARS](#section2) - - - [REFERENCES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require grammar::peg ?0\.1? - -[__::grammar::peg__ *pegName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*?](#1) -[*pegName* __destroy__](#2) -[*pegName* __clear__](#3) -[*pegName* __=__ *srcPEG*](#4) -[*pegName* __\-\->__ *dstPEG*](#5) -[*pegName* __serialize__](#6) -[*pegName* __deserialize__ *serialization*](#7) -[*pegName* __is valid__](#8) -[*pegName* __start__ ?*pe*?](#9) -[*pegName* __nonterminals__](#10) -[*pegName* __nonterminal add__ *nt* *pe*](#11) -[*pegName* __nonterminal delete__ *nt1* ?*nt2* \.\.\.?](#12) -[*pegName* __nonterminal exists__ *nt*](#13) -[*pegName* __nonterminal rename__ *nt* *ntnew*](#14) -[*pegName* __nonterminal mode__ *nt* ?*mode*?](#15) -[*pegName* __nonterminal rule__ *nt*](#16) -[*pegName* __unknown nonterminals__](#17) - -# <a name='description'></a>DESCRIPTION - -This package provides a container class for *parsing expression grammars* -\(Short: PEG\)\. It allows the incremental definition of the grammar, its -manipulation and querying of the definition\. The package neither provides -complex operations on the grammar, nor has it the ability to execute a grammar -definition for a stream of symbols\. Two packages related to this one are -__grammar::mengine__ and __grammar::peg::interpreter__\. The first of -them defines a general virtual machine for the matching of a character stream, -and the second implements an interpreter for parsing expression grammars on top -of that virtual machine\. - -## <a name='subsection1'></a>TERMS & CONCEPTS - -PEGs are similar to context\-free grammars, but not equivalent; in some cases -PEGs are strictly more powerful than context\-free grammars \(there exist PEGs for -some non\-context\-free languages\)\. The formal mathematical definition of parsing -expressions and parsing expression grammars can be found in section [PARSING -EXPRESSION GRAMMARS](#section2)\. - -In short, we have *terminal symbols*, which are the most basic building blocks -for *sentences*, and *nonterminal symbols* with associated *parsing -expressions*, defining the grammatical structure of the sentences\. The two sets -of symbols are distinctive, and do not overlap\. When speaking about symbols the -word "symbol" is often left out\. The union of the sets of terminal and -nonterminal symbols is called the set of *symbols*\. - -Here the set of *terminal symbols* is not explicitly managed, but implicitly -defined as the set of all characters\. Note that this means that we inherit from -Tcl the ability to handle all of Unicode\. - -A pair of *nonterminal* and *[parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression)* is also called a -*grammatical rule*, or *rule* for short\. In the context of a rule the -nonterminal is often called the left\-hand\-side \(LHS\), and the parsing expression -the right\-hand\-side \(RHS\)\. - -The *start expression* of a grammar is a parsing expression from which all the -sentences contained in the language specified by the grammar are *derived*\. To -make the understanding of this term easier let us assume for a moment that the -RHS of each rule, and the start expression, is either a sequence of symbols, or -a series of alternate parsing expressions\. In the latter case the rule can be -seen as a set of rules, each providing one alternative for the nonterminal\. A -parsing expression A' is now a derivation of a parsing expression A if we pick -one of the nonterminals N in the expression, and one of the alternative rules R -for N, and then replace the nonterminal in A with the RHS of the chosen rule\. -Here we can see why the terminal symbols are called such\. They cannot be -expanded any further, thus terminate the process of deriving new expressions\. An -example - - Rules - (1) A <- a B c - (2a) B <- d B - (2b) B <- e - - Some derivations, using starting expression A. - - A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c - -A derived expression containing only terminal symbols is a *sentence*\. The set -of all sentences which can be derived from the start expression is the -*language* of the grammar\. - -Some definitions for nonterminals and expressions: - - 1. A nonterminal A is called *reachable* if it is possible to derive a - parsing expression from the start expression which contains A\. - - 1. A nonterminal A is called *useful* if it is possible to derive a sentence - from it\. - - 1. A nonterminal A is called *recursive* if it is possible to derive a - parsing expression from it which contains A, again\. - - 1. The *FIRST set* of a nonterminal A contains all the symbols which can - occur of as the leftmost symbol in a parsing expression derived from A\. If - the FIRST set contains A itself then that nonterminal is called - *left\-recursive*\. - - 1. The *LAST set* of a nonterminal A contains all the symbols which can - occur of as the rightmost symbol in a parsing expression derived from A\. If - the LAST set contains A itself then that nonterminal is called - *right\-recursive*\. - - 1. The *FOLLOW set* of a nonterminal A contains all the symbols which can - occur after A in a parsing expression derived from the start expression\. - - 1. A nonterminal \(or parsing expression\) is called *nullable* if the empty - sentence can be derived from it\. - -And based on the above definitions for grammars: - - 1. A grammar G is *recursive* if and only if it contains a nonterminal A - which is recursive\. The terms *left\-* and *right\-recursive*, and - *useful* are analogously defined\. - - 1. A grammar is *minimal* if it contains only *reachable* and *useful* - nonterminals\. - - 1. A grammar is *wellformed* if it is not left\-recursive\. Such grammars are - also *complete*, which means that they always succeed or fail on all - input sentences\. For an incomplete grammar on the other hand input - sentences exist for which an attempt to match them against the grammar will - not terminate\. - - 1. As we wish to allow ourselves to build a grammar incrementally in a - container object we will encounter stages where the RHS of one or more - rules reference symbols which are not yet known to the container\. Such a - grammar we call *invalid*\. We cannot use the term *incomplete* as this - term is already taken, see the last item\. - -## <a name='subsection2'></a>CONTAINER CLASS API - -The package exports the API described here\. - - - <a name='1'></a>__::grammar::peg__ *pegName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*? - - The command creates a new container object for a parsing expression grammar - and returns the fully qualified name of the object command as its result\. - The API the returned command is following is described in the section - [CONTAINER OBJECT API](#subsection3)\. It may be used to invoke various - operations on the container and the grammar within\. - - The new container, i\.e\. grammar will be empty if no *src* is specified\. - Otherwise it will contain a copy of the grammar contained in the *src*\. - The *src* has to be a container object reference for all operators except - __deserialize__\. The __deserialize__ operator requires *src* to be - the serialization of a parsing expression grammar instead\. - - An empty grammar has no nonterminal symbols, and the start expression is the - empty expression, i\.e\. epsilon\. It is *valid*, but not *useful*\. - -## <a name='subsection3'></a>CONTAINER OBJECT API - -All grammar container objects provide the following methods for the manipulation -of their contents: - - - <a name='2'></a>*pegName* __destroy__ - - Destroys the grammar, including its storage space and associated command\. - - - <a name='3'></a>*pegName* __clear__ - - Clears out the definition of the grammar contained in *pegName*, but does - *not* destroy the object\. - - - <a name='4'></a>*pegName* __=__ *srcPEG* - - Assigns the contents of the grammar contained in *srcPEG* to *pegName*, - overwriting any existing definition\. This is the assignment operator for - grammars\. It copies the grammar contained in the grammar object *srcPEG* - over the grammar definition in *pegName*\. The old contents of *pegName* - are deleted by this operation\. - - This operation is in effect equivalent to - - > *pegName* __deserialize__ \[*srcPEG* __serialize__\] - - - <a name='5'></a>*pegName* __\-\->__ *dstPEG* - - This is the reverse assignment operator for grammars\. It copies the - automation contained in the object *pegName* over the grammar definition - in the object *dstPEG*\. The old contents of *dstPEG* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *dstPEG* __deserialize__ \[*pegName* __serialize__\] - - - <a name='6'></a>*pegName* __serialize__ - - This method serializes the grammar stored in *pegName*\. In other words it - returns a tcl *value* completely describing that grammar\. This allows, for - example, the transfer of grammars over arbitrary channels, persistence, etc\. - This method is also the basis for both the copy constructor and the - assignment operator\. - - The result of this method has to be semantically identical over all - implementations of the __grammar::peg__ interface\. This is what will - enable us to copy grammars between different implementations of the same - interface\. - - The result is a list of four elements with the following structure: - - 1. The constant string __grammar::peg__\. - - 1. A dictionary\. Its keys are the names of all known nonterminal symbols, - and their associated values are the parsing expressions describing - their sentennial structure\. - - 1. A dictionary\. Its keys are the names of all known nonterminal symbols, - and their associated values hints to a matcher regarding the semantic - values produced by the symbol\. - - 1. The last item is a parsing expression, the *start expression* of the - grammar\. - - Assuming the following PEG for simple mathematical expressions - - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' - Sign <- '+' / '-' - Number <- Sign? Digit+ - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) - MulOp <- '*' / '/' - Factor <- Term (AddOp Term)* - AddOp <- '+'/'-' - Term <- Number - - a possible serialization is - - grammar::peg \ - {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \ - Factor {x Term {* {x AddOp Term}}} \ - Term Number \ - MulOp {/ * /} \ - AddOp {/ + -} \ - Number {x {? Sign} {+ Digit}} \ - Sign {/ + -} \ - Digit {/ 0 1 2 3 4 5 6 7 8 9} \ - } \ - {Expression value Factor value \ - Term value MulOp value \ - AddOp value Number value \ - Sign value Digit value \ - } - Expression - - A possible one, because the order of the nonterminals in the dictionary is - not relevant\. - - - <a name='7'></a>*pegName* __deserialize__ *serialization* - - This is the complement to __serialize__\. It replaces the grammar - definition in *pegName* with the grammar described by the - *serialization* value\. The old contents of *pegName* are deleted by this - operation\. - - - <a name='8'></a>*pegName* __is valid__ - - A predicate\. It tests whether the PEG in *pegName* is *valid*\. See - section [TERMS & CONCEPTS](#subsection1) for the definition of this - grammar property\. The result is a boolean value\. It will be set to - __true__ if the PEG has the tested property, and __false__ - otherwise\. - - - <a name='9'></a>*pegName* __start__ ?*pe*? - - This method defines the *start expression* of the grammar\. It replaces the - previously defined start expression with the parsing expression *pe*\. The - method fails and throws an error if *pe* does not contain a valid parsing - expression as specified in the section [PARSING - EXPRESSIONS](#subsection4)\. In that case the existing start expression - is not changed\. The method returns the empty string as its result\. - - If the method is called without an argument it will return the currently - defined start expression\. - - - <a name='10'></a>*pegName* __nonterminals__ - - Returns the set of all nonterminal symbols known to the grammar\. - - - <a name='11'></a>*pegName* __nonterminal add__ *nt* *pe* - - This method adds the nonterminal *nt* and its associated parsing - expression *pe* to the set of nonterminal symbols and rules of the PEG - contained in the object *pegName*\. The method fails and throws an error if - either the string *nt* is already known as a symbol of the grammar, or if - *pe* does not contain a valid parsing expression as specified in the - section [PARSING EXPRESSIONS](#subsection4)\. In that case the current - set of nonterminal symbols and rules is not changed\. The method returns the - empty string as its result\. - - - <a name='12'></a>*pegName* __nonterminal delete__ *nt1* ?*nt2* \.\.\.? - - This method removes the named symbols *nt1*, *nt2* from the set of - nonterminal symbols of the PEG contained in the object *pegName*\. The - method fails and throws an error if any of the strings is not known as a - nonterminal symbol\. In that case the current set of nonterminal symbols is - not changed\. The method returns the empty string as its result\. - - The stored grammar becomes invalid if the deleted nonterminals are - referenced by the RHS of still\-known rules\. - - - <a name='13'></a>*pegName* __nonterminal exists__ *nt* - - A predicate\. It tests whether the nonterminal symbol *nt* is known to the - PEG in *pegName*\. The result is a boolean value\. It will be set to - __true__ if the symbol *nt* is known, and __false__ otherwise\. - - - <a name='14'></a>*pegName* __nonterminal rename__ *nt* *ntnew* - - This method renames the nonterminal symbol *nt* to *ntnew*\. The method - fails and throws an error if either *nt* is not known as a nonterminal, or - if *ntnew* is a known symbol\. The method returns the empty string as its - result\. - - - <a name='15'></a>*pegName* __nonterminal mode__ *nt* ?*mode*? - - This mode returns or sets the semantic mode associated with the nonterminal - symbol *nt*\. If no *mode* is specified the current mode of the - nonterminal is returned\. Otherwise the current mode is set to *mode*\. The - method fails and throws an error if *nt* is not known as a nonterminal\. - The grammar interpreter implemented by the package - __grammar::peg::interpreter__ recognizes the following modes: - - * value - - The semantic value of the nonterminal is the abstract syntax tree - created from the AST's of the RHS and a node for the nonterminal itself\. - - * match - - The semantic value of the nonterminal is an the abstract syntax tree - consisting of single a node for the string matched by the RHS\. The ASTs - generated by the RHS are discarded\. - - * leaf - - The semantic value of the nonterminal is an the abstract syntax tree - consisting of single a node for the nonterminal itself\. The ASTs - generated by the RHS are discarded\. - - * discard - - The nonterminal has no semantic value\. The ASTs generated by the RHS are - discarded \(as well\)\. - - - <a name='16'></a>*pegName* __nonterminal rule__ *nt* - - This method returns the parsing expression associated with the nonterminal - *nt*\. The method fails and throws an error if *nt* is not known as a - nonterminal\. - - - <a name='17'></a>*pegName* __unknown nonterminals__ - - This method returns a list containing the names of all nonterminal symbols - which are referenced on the RHS of a grammatical rule, but have no rule - definining their structure\. In other words, a list of the nonterminal - symbols which make the grammar invalid\. The grammar is valid if this list is - empty\. - -## <a name='subsection4'></a>PARSING EXPRESSIONS - -Various methods of PEG container objects expect a parsing expression as their -argument, or will return such\. This section specifies the format such parsing -expressions are in\. - - 1. The string __epsilon__ is an atomic parsing expression\. It matches the - empty string\. - - 1. The string __alnum__ is an atomic parsing expression\. It matches any - alphanumeric character\. - - 1. The string __alpha__ is an atomic parsing expression\. It matches any - alphabetical character\. - - 1. The string __dot__ is an atomic parsing expression\. It matches any - character\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. It - matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. It - matches the nonterminal __A__\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of \[list / - __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is the - *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of \[list x - __e1__ __e2__ \.\.\. \] is a parsing expression as well\. This is the - *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] is a - parsing expression as well\. This is the *kleene closure*, describing zero - or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] is a - parsing expression as well\. This is the *positive kleene closure*, - describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] is a - parsing expression as well\. This is the *and lookahead predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] is a - parsing expression as well\. This is the *not lookahead predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] is a - parsing expression as well\. This is the *optional input*\. - -Examples of parsing expressions where already shown, in the description of the -method __serialize__\. - -# <a name='section2'></a>PARSING EXPRESSION GRAMMARS - -For the mathematically inclined, a PEG is a 4\-tuple \(VN,VT,R,eS\) where - - - VN is a set of *nonterminal symbols*, - - - VT is a set of *terminal symbols*, - - - R is a finite set of rules, where each rule is a pair \(A,e\), A in VN, and - *[e](\.\./\.\./\.\./\.\./index\.md\#e)* a *[parsing - expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression)*\. - - - eS is a parsing expression, the *start expression*\. - -Further constraints are - - - The intersection of VN and VT is empty\. - - - For all A in VT exists exactly one pair \(A,e\) in R\. In other words, R is a - function from nonterminal symbols to parsing expressions\. - -Parsing expression are inductively defined via - - - The empty string \(epsilon\) is a parsing expression\. - - - A terminal symbol *a* is a parsing expression\. - - - A nonterminal symbol *A* is a parsing expression\. - - - *e1**e2* is a parsing expression for parsing expressions *e1* and - *2*\. This is called *sequence*\. - - - *e1*/*e2* is a parsing expression for parsing expressions *e1* and - *2*\. This is called *ordered choice*\. - - - *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\* is a parsing expression for parsing - expression *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\. This is called - *zero\-or\-more repetitions*, also known as *kleene closure*\. - - - *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\+ is a parsing expression for parsing - expression *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\. This is called *one\-or\-more - repetitions*, also known as *positive kleene closure*\. - - - \!*[e](\.\./\.\./\.\./\.\./index\.md\#e)* is a parsing expression for parsing - expression *e1*\. This is called a *not lookahead predicate*\. - - - &*[e](\.\./\.\./\.\./\.\./index\.md\#e)* is a parsing expression for parsing - expression *e1*\. This is called an *and lookahead predicate*\. - -PEGs are used to define a grammatical structure for streams of symbols over VT\. -They are a modern phrasing of older formalisms invented by Alexander Birham\. -These formalisms were called TS \(TMG recognition scheme\), and gTS \(generalized -TS\)\. Later they were renamed to TPDL \(Top\-Down Parsing Languages\) and gTPDL -\(generalized TPDL\)\. - -They can be easily implemented by recursive descent parsers with backtracking\. -This makes them relatives of LL\(k\) Context\-Free Grammars\. - -# <a name='section3'></a>REFERENCES - - 1. [The Packrat Parsing and Parsing Expression Grammars - Page](http://www\.pdos\.lcs\.mit\.edu/~baford/packrat/), by Bryan Ford, - Massachusetts Institute of Technology\. This is the main entry page to PEGs, - and their realization through Packrat Parsers\. - - 1. [Parsing Techniques \- A Practical Guide - ](http://www\.cs\.vu\.nl/~dick/PTAPG\.html), an online book offering a - clear, accessible, and thorough discussion of many different parsing - techniques with their interrelations and applicabilities, including error - recovery techniques\. - - 1. [Compilers and Compiler Generators](http://scifac\.ru\.ac\.za/compilers/), - an online book using CoCo/R, a generator for recursive descent parsers\. - -# <a name='section4'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_peg* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/grammar_peg/peg_interp.md Index: embedded/md/tcllib/files/modules/grammar_peg/peg_interp.md ================================================================== --- embedded/md/tcllib/files/modules/grammar_peg/peg_interp.md +++ embedded/md/tcllib/files/modules/grammar_peg/peg_interp.md @@ -1,146 +0,0 @@ - -[//000000001]: # (grammar::peg::interp \- Grammar operations and usage) -[//000000002]: # (Generated from file 'peg\_interp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2011 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) -[//000000004]: # (grammar::peg::interp\(n\) 0\.1\.1 tcllib "Grammar operations and usage") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -grammar::peg::interp \- Interpreter for parsing expression grammars - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [THE INTERPRETER API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.4 -package require grammar::mengine ?0\.1? -package require grammar::peg::interp ?0\.1\.1? - -[__::grammar::peg::interp::setup__ *peg*](#1) -[__::grammar::peg::interp::parse__ *nextcmd* *errorvar* *astvar*](#2) - -# <a name='description'></a>DESCRIPTION - -This package provides commands for the controlled matching of a character stream -via a parsing expression grammar and the creation of an abstract syntax tree for -the stream and partials\. - -It is built on top of the virtual machine provided by the package -__[grammar::me::tcl](\.\./grammar\_me/me\_tcl\.md)__ and directly interprets -the parsing expression grammar given to it\. In other words, the grammar is -*not* pre\-compiled but used as is\. - -The grammar to be interpreted is taken from a container object following the -interface specified by the package __grammar::peg::container__\. Only the -relevant parts are copied into the state of this package\. - -It should be noted that the package provides exactly one instance of the -interpreter, and interpreting a second grammar requires the user to either abort -or complete a running interpretation, or to put them into different Tcl -interpreters\. - -Also of note is that the implementation assumes a pull\-type handling of the -input\. In other words, the interpreter pulls characters from the input stream as -it needs them\. For usage in a push environment, i\.e\. where the environment -pushes new characters as they come we have to put the engine into its own -thread\. - -# <a name='section2'></a>THE INTERPRETER API - -The package exports the following API - - - <a name='1'></a>__::grammar::peg::interp::setup__ *peg* - - This command \(re\)initializes the interpreter\. It returns the empty string\. - This command has to be invoked first, before any matching run\. - - Its argument *peg* is the handle of an object containing the parsing - expression grammar to interpret\. This grammar has to be valid, or an error - will be thrown\. - - - <a name='2'></a>__::grammar::peg::interp::parse__ *nextcmd* *errorvar* *astvar* - - This command interprets the loaded grammar and tries to match it against the - stream of characters represented by the command prefix *nextcmd*\. - - The command prefix *nextcmd* represents the input stream of characters and - is invoked by the interpreter whenever the a new character from the stream - is required\. The callback has to return either the empty list, or a list of - 4 elements containing the token, its lexeme attribute, and its location as - line number and column index, in this order\. The empty list is the signal - that the end of the input stream has been reached\. The lexeme attribute is - stored in the terminal cache, but otherwise not used by the machine\. - - The result of the command is a boolean value indicating whether the matching - process was successful \(__true__\), or not \(__false__\)\. In the case - of a match failure error information will be stored into the variable - referenced by *errorvar*\. The variable referenced by *astvar* will - always contain the generated abstract syntax tree, however in the case of an - error it will be only partial and possibly malformed\. - - The abstract syntax tree is represented by a nested list, as described in - section __AST VALUES__ of document - *[grammar::me\_ast](\.\./grammar\_me/me\_ast\.md)*\. - -# <a name='section3'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *grammar\_peg* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='keywords'></a>KEYWORDS - -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# <a name='category'></a>CATEGORY - -Grammars and finite automata - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2005\-2011 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> DELETED embedded/md/tcllib/files/modules/hook/hook.md Index: embedded/md/tcllib/files/modules/hook/hook.md ================================================================== --- embedded/md/tcllib/files/modules/hook/hook.md +++ embedded/md/tcllib/files/modules/hook/hook.md @@ -1,371 +0,0 @@ - -[//000000001]: # (hook \- Hooks) -[//000000002]: # (Generated from file 'hook\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010, by William H\. Duquette) -[//000000004]: # (hook\(n\) 0\.1 tcllib "Hooks") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -hook \- Hooks - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Concepts](#section2) - - - [Introduction](#subsection1) - - - [Bindings](#subsection2) - - - [Subjects and observers](#subsection3) - - - [Reference](#section3) - - - [Example](#section4) - - - [Credits](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require hook ?0\.1? - -[__hook__ __bind__ ?*subject*? ?*hook*? ?*observer*? ?*cmdPrefix*?](#1) -[__hook__ __call__ *subject* *hook* ?*args*\.\.\.?](#2) -[__hook__ __forget__ *object*](#3) -[__hook__ __cget__ *option*](#4) -[__hook__ __configure__ __option__ *value* \.\.\.](#5) - -# <a name='description'></a>DESCRIPTION - -This package provides the __hook__ ensemble command, which implements the -Subject/Observer pattern\. It allows *subjects*, which may be *modules*, -*objects*, *widgets*, and so forth, to synchronously call *hooks* which -may be bound to an arbitrary number of subscribers, called *observers*\. A -subject may call any number of distinct hooks, and any number of observers can -bind callbacks to a particular hook called by a particular subject\. Hook -bindings can be queried and deleted\. - -This man page is intended to be a reference only\. - -# <a name='section2'></a>Concepts - -## <a name='subsection1'></a>Introduction - -Tcl modules usually send notifications to other modules in two ways: via Tk -events, and via callback options like the text widget's __\-yscrollcommand__ -option\. Tk events are available only in Tk, and callback options require tight -coupling between the modules sending and receiving the notification\. - -Loose coupling between sender and receiver is often desirable, however\. In -Model/View/Controller terms, a View can send a command \(stemming from user -input\) to the Controller, which updates the Model\. The Model can then call a -hook *to which all relevant* *Views subscribe\.* The Model is decoupled from -the Views, and indeed need not know whether any Views actually exist\. At -present, Tcl/Tk has no standard mechanism for implementing loose coupling of -this kind\. This package defines a new command, __hook__, which implements -just such a mechanism\. - -## <a name='subsection2'></a>Bindings - -The __hook__ command manages a collection of hook bindings\. A hook binding -has four elements: - - 1. A *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*: the name of the entity - that will be calling the hook\. - - 1. The *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* itself\. A hook usually - reflects some occurrence in the life of the - *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* that other entities might - care to know about\. A *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* has a name, - and may also have arguments\. Hook names are arbitrary strings\. Each - *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* must document the names and - arguments of the hooks it can call\. - - 1. The name of the *[observer](\.\./\.\./\.\./\.\./index\.md\#observer)* that - wishes to receive the *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* from the - *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*\. - - 1. A command prefix to which the *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* - arguments will be appended when the binding is executed\. - -## <a name='subsection3'></a>Subjects and observers - -For convenience, this document collectively refers to subjects and observers as -*objects*, while placing no requirements on how these *objects* are actually -implemented\. An object can be a __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ -or __[Snit](\.\./\.\./\.\./\.\./index\.md\#snit)__ or __XOTcl__ object, a Tcl -command, a namespace, a module, a pseudo\-object managed by some other object \(as -tags are managed by the Tk text widget\) or simply a well\-known name\. - -Subject and observer names are arbitrary strings; however, as __hook__ might -be used at the package level, it's necessary to have conventions that avoid name -collisions between packages written by different people\. - -Therefore, any subject or observer name used in core or package level code -should look like a Tcl command name, and should be defined in a namespace owned -by the package\. Consider, for example, an ensemble command __::foo__ that -creates a set of pseudo\-objects and uses __hook__ to send notifications\. The -pseudo\-objects have names that are not commands and exist in their own -namespace, rather like file handles do\. To avoid name collisions with subjects -defined by other packages, users of __hook__, these __::foo__ handles -should have names like __::foo::1__, __::foo::2__, and so on\. - -Because object names are arbitrary strings, application code can use whatever -additional conventions are dictated by the needs of the application\. - -# <a name='section3'></a>Reference - -Hook provides the following commands: - - - <a name='1'></a>__hook__ __bind__ ?*subject*? ?*hook*? ?*observer*? ?*cmdPrefix*? - - This subcommand is used to create, update, delete, and query hook bindings\. - - Called with no arguments it returns a list of the subjects with hooks to - which observers are currently bound\. - - Called with one argument, a *subject*, it returns a list of the subject's - hooks to which observers are currently bound\. - - Called with two arguments, a *subject* and a *hook*, it returns a list - of the observers which are currently bound to this *subject* and *hook*\. - - Called with three arguments, a *subject*, a *hook*, and an *observer*, - it returns the binding proper, the command prefix to be called when the hook - is called, or the empty string if there is no such binding\. - - Called with four arguments, it creates, updates, or deletes a binding\. If - *cmdPrefix* is the empty string, it deletes any existing binding for the - *subject*, *hook*, and *observer*; nothing is returned\. Otherwise, - *cmdPrefix* must be a command prefix taking as many additional arguments - as are documented for the *subject* and *hook*\. The binding is added or - updated, and the observer is returned\. - - If the *observer* is the empty string, "", it will create a new binding - using an automatically generated observer name of the form - __::hook::ob__<__number__>\. The automatically generated name will be - returned, and can be used to query, update, and delete the binding as usual\. - If automated observer names are always used, the observer name effectively - becomes a unique binding ID\. - - It is possible to call __hook bind__ to create or delete a binding to a - *subject* and *hook* while in an observer binding for that same - *subject* and *hook*\. The following rules determine what happens when - - hook bind $s $h $o $binding - - is called during the execution of - - hook call $s $h - - 1. No binding is ever called after it is deleted\. - - 1. When a binding is called, the most recently given command prefix is - always used\. - - 1. The set of observers whose bindings are to be called is determined when - this method begins to execute, and does not change thereafter, except - that deleted bindings are not called\. - - In particular: - - 1. If __$o__s binding to __$s__ and __$h__ is deleted, and - __$o__s binding has not yet been called during this execution of - - hook call $s $h - - it will not be called\. \(Note that it might already have been called; - and in all likelihood, it is probably deleting itself\.\) - - 1. If __$o__ changes the command prefix that's bound to __$s__ and - __$h__, and if __$o__s binding has not yet been called during - this execution of - - hook call $s $h - - the new binding will be called when the time comes\. \(But again, it is - probably __$o__s binding that is is making the change\.\) - - 1. If a new observer is bound to __$s__ and __$h__, its binding - will not be called until the next invocation of - - hook call $s $h - - - <a name='2'></a>__hook__ __call__ *subject* *hook* ?*args*\.\.\.? - - This command is called when the named *subject* wishes to call the named - *hook*\. All relevant bindings are called with the specified arguments in - the global namespace\. Note that the bindings are called synchronously, - before the command returns; this allows the *args* to include references - to entities that will be cleaned up as soon as the hook has been called\. - - The order in which the bindings are called is not guaranteed\. If sequence - among observers must be preserved, define one observer and have its bindings - call the other callbacks directly in the proper sequence\. - - Because the __hook__ mechanism is intended to support loose coupling, it - is presumed that the *subject* has no knowledge of the observers, nor any - expectation regarding return values\. This has a number of implications: - - 1. __hook call__ returns the empty string\. - - 1. Normal return values from observer bindings are ignored\. - - 1. Errors and other exceptional returns propagate normally by default\. - This will rarely be what is wanted, because the subjects usually have - no knowledge of the observers and will therefore have no particular - competence at handling their errors\. That makes it an application - issue, and so applications will usually want to define an - __\-errorcommand__\. - - If the __\-errorcommand__ configuration option has a non\-empty value, its - value will be invoked for all errors and other exceptional returns in - observer bindings\. See __hook configure__, below, for more information - on configuration options\. - - - <a name='3'></a>__hook__ __forget__ *object* - - This command deletes any existing bindings in which the named *object* - appears as either the *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)* or the - *[observer](\.\./\.\./\.\./\.\./index\.md\#observer)*\. Bindings deleted by this - method will never be called again\. In particular, - - 1. If an observer is forgotten during a call to __hook call__, any - uncalled binding it might have had to the relevant subject and hook - will *not* be called subsequently\. - - 1. If a subject __$s__ is forgotten during a call to - - hook call $s $h - - then __hook call__ will return as soon as the current binding - returns\. No further bindings will be called\. - - - <a name='4'></a>__hook__ __cget__ *option* - - This command returns the value of one of the __hook__ command's - configuration options\. - - - <a name='5'></a>__hook__ __configure__ __option__ *value* \.\.\. - - This command sets the value of one or more of the __hook__ command's - configuration options: - - * __\-errorcommand__ *cmdPrefix* - - If the value of this option is the empty string, "", then errors and - other exception returns in binding scripts are propagated normally\. - Otherwise, it must be a command prefix taking three additional - arguments: - - 1. a 4\-element list \{subject hook arglist observer\}, - - 1. the result string, and - - 1. the return options dictionary\. - - Given this information, the __\-errorcommand__ can choose to log the - error, call __interp bgerror__, delete the errant binding \(thus - preventing the error from arising a second time\) and so forth\. - - * __\-tracecommand__ *cmdPrefix* - - The option's value should be a command prefix taking four arguments: - - 1. a *[subject](\.\./\.\./\.\./\.\./index\.md\#subject)*, - - 1. a *[hook](\.\./\.\./\.\./\.\./index\.md\#hook)*, - - 1. a list of the hook's argument values, and - - 1. a list of *objects* the hook was called for\. - - The command will be called for each hook that is called\. This allows the - application to trace hook execution for debugging purposes\. - -# <a name='section4'></a>Example - -The __::model__ module calls the <Update> hook in response to commands that -change the model's data: - - hook call ::model <Update> - -The __\.view__ megawidget displays the model state, and needs to know about -model updates\. Consequently, it subscribes to the ::model's <Update> hook\. - - hook bind ::model <Update> .view [list .view ModelUpdate] - -When the __::model__ calls the hook, the __\.view__s ModelUpdate -subcommand will be called\. - -Later the __\.view__ megawidget is destroyed\. In its destructor, it tells the -*[hook](\.\./\.\./\.\./\.\./index\.md\#hook)* that it no longer exists: - - hook forget .view - -All bindings involving __\.view__ are deleted\. - -# <a name='section5'></a>Credits - -Hook has been designed and implemented by William H\. Duquette\. - -# <a name='section6'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *hook* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[uevent\(n\)](\.\./uev/uevent\.md) - -# <a name='keywords'></a>KEYWORDS - -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), -[event](\.\./\.\./\.\./\.\./index\.md\#event), [hook](\.\./\.\./\.\./\.\./index\.md\#hook), -[observer](\.\./\.\./\.\./\.\./index\.md\#observer), -[producer](\.\./\.\./\.\./\.\./index\.md\#producer), -[publisher](\.\./\.\./\.\./\.\./index\.md\#publisher), -[subject](\.\./\.\./\.\./\.\./index\.md\#subject), -[subscriber](\.\./\.\./\.\./\.\./index\.md\#subscriber), -[uevent](\.\./\.\./\.\./\.\./index\.md\#uevent) - -# <a name='category'></a>CATEGORY - -Programming tools - -# <a name='copyright'></a>COPYRIGHT - -Copyright © 2010, by William H\. Duquette DELETED embedded/md/tcllib/files/modules/html/html.md Index: embedded/md/tcllib/files/modules/html/html.md ================================================================== --- embedded/md/tcllib/files/modules/html/html.md +++ embedded/md/tcllib/files/modules/html/html.md @@ -1,594 +0,0 @@ - -[//000000001]: # (html \- HTML Generation) -[//000000002]: # (Generated from file 'html\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (html\(n\) 1\.5 tcllib "HTML Generation") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -html \- Procedures to generate HTML structures - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.2 -package require html ?1\.5? - -[__::html::author__ *author*](#1) -[__::html::bodyTag__ *args*](#2) -[__::html::cell__ *param value* ?*tag*?](#3) -[__::html::checkbox__ *name value*](#4) -[__::html::checkSet__ *key sep list*](#5) -[__::html::checkValue__ *name* ?*value*?](#6) -[__::html::closeTag__](#7) -[__::html::default__ *key* ?*param*?](#8) -[__::html::description__ *description*](#9) -[__::html::end__](#10) -[__::html::eval__ *arg* ?*args*?](#11) -[__::html::extractParam__ *param key* ?*varName*?](#12) -[__::html::font__ *args*](#13) -[__::html::for__ *start test next body*](#14) -[__::html::foreach__ *varlist1 list1* ?*varlist2 list2 \.\.\.*? *body*](#15) -[__::html::formValue__ *name* ?*defvalue*?](#16) -[__::html::getFormInfo__ *args*](#17) -[__::html::getTitle__](#18) -[__::html::h__ *level string* ?*param*?](#19) -[__::html::h1__ *string* ?*param*?](#20) -[__::html::h2__ *string* ?*param*?](#21) -[__::html::h3__ *string* ?*param*?](#22) -[__::html::h4__ *string* ?*param*?](#23) -[__::html::h5__ *string* ?*param*?](#24) -[__::html::h6__ *string* ?*param*?](#25) -[__::html::hdrRow__ *args*](#26) -[__::html::head__ *title*](#27) -[__::html::headTag__ *string*](#28) -[__::html::html\_entities__ *string*](#29) -[__::html::if__ *expr1 body1* ?__elseif__ *expr2 body2 \.\.\.*? ?__else__ *bodyN*?](#30) -[__::html::init__ ?*list*?](#31) -[__::html::keywords__ *args*](#32) -[__::html::mailto__ *email* ?*subject*?](#33) -[__::html::meta__ *args*](#34) -[__::html::meta\_name__ *args*](#35) -[__::html::meta\_equiv__ *args*](#36) -[__::html::meta\_charset__ *charset*](#37) -[__::html::css__ *href*](#38) -[__::html::css\-clear__](#39) -[__::html::js__ *href*](#40) -[__::html::js\-clear__](#41) -[__::html::minorList__ *list* ?*ordered*?](#42) -[__::html::minorMenu__ *list* ?*sep*?](#43) -[__::html::nl2br__ *string*](#44) -[__::html::openTag__ *tag* ?*param*?](#45) -[__::html::paramRow__ *list* ?*rparam*? ?*cparam*?](#46) -[__::html::passwordInput__ ?*name*?](#47) -[__::html::passwordInputRow__ *label* ?*name*?](#48) -[__::html::quoteFormValue__ *value*](#49) -[__::html::radioSet__ *key sep list*](#50) -[__::html::radioValue__ *name value*](#51) -[__::html::refresh__ *seconds url*](#52) -[__::html::row__ *args*](#53) -[__::html::select__ *name param choices* ?*current*?](#54) -[__::html::selectPlain__ *name param choices* ?*current*?](#55) -[__::html::set__ *var val*](#56) -[__::html::submit__ *label* ?*name*? ?*title*?](#57) -[__::html::tableFromArray__ *arrname* ?*param*? ?*pat*?](#58) -[__::html::tableFromList__ *querylist* ?*param*?](#59) -[__::html::textarea__ *name* ?*param*? ?*current*?](#60) -[__::html::textInput__ *name value args*](#61) -[__::html::textInputRow__ *label name value args*](#62) -[__::html::varEmpty__ *name*](#63) -[__::html::while__ *test body*](#64) -[__::html::doctype__ *id*](#65) -[__::html::wrapTag__ *tag* ?*text*? ?*args*?](#66) - -# <a name='description'></a>DESCRIPTION - -The package __html__ provides commands that generate HTML\. These commands -typically return an HTML string as their result\. In particular, they do not -output their result to __stdout__\. - -The command __::html::init__ should be called early to initialize the -module\. You can also use this procedure to define default values for HTML tag -parameters\. - - - <a name='1'></a>__::html::author__ *author* - - *Side effect only*\. Call this before __::html::head__ to define an - author for the page\. The author is noted in a comment in the HEAD section\. - - - <a name='2'></a>__::html::bodyTag__ *args* - - Generate a *body* tag\. The tag parameters are taken from *args* or from - the body\.\* attributes define with __::html::init__\. - - - <a name='3'></a>__::html::cell__ *param value* ?*tag*? - - Generate a *td* \(or *th*\) tag, a value, and a closing *td* \(or *th*\) - tag\. The tag parameters come from *param* or TD\.\* attributes defined with - __::html::init__\. This uses __::html::font__ to insert a standard - *font* tag into the table cell\. The *tag* argument defaults to "td"\. - - - <a name='4'></a>__::html::checkbox__ *name value* - - Generate a *[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox)* form element - with the specified name and value\. This uses __::html::checkValue__\. - - - <a name='5'></a>__::html::checkSet__ *key sep list* - - Generate a set of *[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox)* form - elements and associated labels\. The *list* should contain an alternating - list of labels and values\. This uses __::html::checkbox__\. All the - *[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox)* buttons share the same - *key* for their name\. The *sep* is text used to separate the elements\. - - - <a name='6'></a>__::html::checkValue__ *name* ?*value*? - - Generate the "name=*name* value=*value*" for a - *[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox)* form element\. If the CGI - variable *name* has the value *value*, then SELECTED is added to the - return value\. *value* defaults to "1"\. - - - <a name='7'></a>__::html::closeTag__ - - Pop a tag off the stack created by __::html::openTag__ and generate the - corresponding close tag \(e\.g\., </body>\)\. - - - <a name='8'></a>__::html::default__ *key* ?*param*? - - This procedure is used by __::html::tagParam__ to generate the name, - value list of parameters for a tag\. The __::html::default__ procedure is - used to generate default values for those items not already in *param*\. If - the value identified by *key* matches a value in *param* then this - procedure returns the empty string\. Otherwise, it returns a - "parameter=value" string for a form element identified by *key*\. The - *key* has the form "tag\.parameter" \(e\.g\., body\.bgcolor\)\. Use - __::html::init__ to register default values\. *param* defaults to the - empty string\. - - - <a name='9'></a>__::html::description__ *description* - - *Side effect only*\. Call this before __::html::head__ to define a - description *meta* tag for the page\. This tag is generated later in the - call to __::html::head__\. - - - <a name='10'></a>__::html::end__ - - Pop all open tags from the stack and generate the corresponding close HTML - tags, \(e\.g\., </body></html>\)\. - - - <a name='11'></a>__::html::eval__ *arg* ?*args*? - - This procedure is similar to the built\-in Tcl __eval__ command\. The only - difference is that it returns "" so it can be called from an HTML template - file without appending unwanted results\. - - - <a name='12'></a>__::html::extractParam__ *param key* ?*varName*? - - This is a parsing procedure that extracts the value of *key* from - *param*, which is a HTML\-style "name=quotedvalue" list\. *varName* is - used as the name of a Tcl variable that is changed to have the value found - in the parameters\. The function returns 1 if the parameter was found in - *param*, otherwise it returns 0\. If the *varName* is not specified, then - *key* is used as the variable name\. - - - <a name='13'></a>__::html::font__ *args* - - Generate a standard *font* tag\. The parameters to the tag are taken from - *args* and the HTML defaults defined with __::html::init__\. - - - <a name='14'></a>__::html::for__ *start test next body* - - This procedure is similar to the built\-in Tcl __for__ control structure\. - Rather than evaluating the body, it returns the subst'ed *body*\. Each - iteration of the loop causes another string to be concatenated to the result - value\. - - - <a name='15'></a>__::html::foreach__ *varlist1 list1* ?*varlist2 list2 \.\.\.*? *body* - - This procedure is similar to the built\-in Tcl - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__ control structure\. - Rather than evaluating the body, it returns the subst'ed *body*\. Each - iteration of the loop causes another string to be concatenated to the result - value\. - - - <a name='16'></a>__::html::formValue__ *name* ?*defvalue*? - - Return a name and value pair, where the value is initialized from existing - CGI data, if any\. The result has this form: - - name="fred" value="freds value" - - - <a name='17'></a>__::html::getFormInfo__ *args* - - Generate hidden fields to capture form values\. If *args* is empty, then - hidden fields are generated for all CGI values\. Otherwise args is a list of - string match patterns for form element names\. - - - <a name='18'></a>__::html::getTitle__ - - Return the title string, with out the surrounding *title* tag, set with a - previous call to __::html::title__\. - - - <a name='19'></a>__::html::h__ *level string* ?*param*? - - Generate a heading \(e\.g\., *h__level__*\) tag\. The *string* is nested - in the heading, and *param* is used for the tag parameters\. - - - <a name='20'></a>__::html::h1__ *string* ?*param*? - - Generate an *h1* tag\. See __::html::h__\. - - - <a name='21'></a>__::html::h2__ *string* ?*param*? - - Generate an *h2* tag\. See __::html::h__\. - - - <a name='22'></a>__::html::h3__ *string* ?*param*? - - Generate an *h3* tag\. See __::html::h__\. - - - <a name='23'></a>__::html::h4__ *string* ?*param*? - - Generate an *h4* tag\. See __::html::h__\. - - - <a name='24'></a>__::html::h5__ *string* ?*param*? - - Generate an *h5* tag\. See __::html::h__\. - - - <a name='25'></a>__::html::h6__ *string* ?*param*? - - Generate an *h6* tag\. See __::html::h__\. - - - <a name='26'></a>__::html::hdrRow__ *args* - - Generate a table row, including *tr* and *th* tags\. Each value in - *args* is place into its own table cell\. This uses __::html::cell__\. - - - <a name='27'></a>__::html::head__ *title* - - Generate the *head* section that includes the page *title*\. If previous - calls have been made to __::html::author__, __::html::keywords__, - __::html::description__, or __::html::meta__ then additional tags - are inserted into the *head* section\. This leaves an open - *[html](\.\./\.\./\.\./\.\./index\.md\#html)* tag pushed on the stack with - __::html::openTag__\. - - - <a name='28'></a>__::html::headTag__ *string* - - Save a tag for inclusion in the *head* section generated by - __::html::head__\. The *string* is everything in the tag except the - enclosing angle brackets, < >\. - - - <a name='29'></a>__::html::html\_entities__ *string* - - This command replaces all special characters in the *string* with their - HTML entities and returns the modified text\. - - - <a name='30'></a>__::html::if__ *expr1 body1* ?__elseif__ *expr2 body2 \.\.\.*? ?__else__ *bodyN*? - - This procedure is similar to the built\-in Tcl __if__ control structure\. - Rather than evaluating the body of the branch that is taken, it returns the - subst'ed *body*\. Note that the syntax is slightly more restrictive than - that of the built\-in Tcl __if__ control structure\. - - - <a name='31'></a>__::html::init__ ?*list*? - - __::html::init__ accepts a Tcl\-style name\-value list that defines values - for items with a name of the form "tag\.parameter"\. For example, a default - with key "body\.bgcolor" defines the background color for the *body* tag\. - - - <a name='32'></a>__::html::keywords__ *args* - - *Side effect only*\. Call this before __::html::head__ to define a - keyword *meta* tag for the page\. The *meta* tag is included in the - result of __::html::head__\. - - - <a name='33'></a>__::html::mailto__ *email* ?*subject*? - - Generate a hypertext link to a mailto: URL\. - - - <a name='34'></a>__::html::meta__ *args* - - Compatibility name for __html::meta\_name__\. - - - <a name='35'></a>__::html::meta\_name__ *args* - - *Side effect only*\. Call this before __::html::head__ to define a - *meta* tag for the page\. The arguments \(*args*\) are a Tcl\-style name, - value list that is used for the __name=__ and __content=__ - attributes of the *meta* tag\. The *meta* tag is included in the result - of __::html::head__\. - - - <a name='36'></a>__::html::meta\_equiv__ *args* - - *Side effect only*\. Call this before __::html::head__ to define a - *meta* tag for the page\. The arguments \(*args*\) are a Tcl\-style name, - value list that is used for the __http\-equiv=__ and __content=__ - attributes of the *meta* tag\. The *meta* tag is included in the result - of __::html::head__\. - - - <a name='37'></a>__::html::meta\_charset__ *charset* - - *Side effect only*\. Call this before __::html::head__ to define a - *meta* tag for the page\. The *charset* is used with the __charset=__ - attribute of the *meta* tag\. The *meta* tag is included in the result of - __::html::head__\. - - - <a name='38'></a>__::html::css__ *href* - - *Side effect only*\. Call this before __::html::head__ to define a - *link* tag for a linked CSS document\. The *href* value is a HTTP URL to - a CSS document\. The *link* tag is included in the result of - __::html::head__\. - - Multiple calls of this command are allowed, enabling the use of multiple CSS - document references\. In other words, the arguments of multiple calls are - accumulated, and do not overwrite each other\. - - - <a name='39'></a>__::html::css\-clear__ - - *Side effect only*\. Call this before __::html::head__ to clear all - links to CSS documents\. - - Multiple calls of this command are allowed, doing nothing after the first of - a sequence with no intervening __::html::css__\. - - - <a name='40'></a>__::html::js__ *href* - - *Side effect only*\. Call this before __::html::head__ to define a - *script* tag for a linked JavaScript document\. The *href* is a HTTP URL - to a JavaScript document\. The *script* tag is included in the result of - __::html::head__\. - - Multiple calls of this command are allowed, enabling the use of multiple - JavaScript document references\. In other words, the arguments of multiple - calls are accumulated, and do not overwrite each other\. - - - <a name='41'></a>__::html::js\-clear__ - - *Side effect only*\. Call this before __::html::head__ to clear all - links to JavaScript documents\. - - Multiple calls of this command are allowed, doing nothing after the first of - a sequence with no intervening __::html::js__\. - - - <a name='42'></a>__::html::minorList__ *list* ?*ordered*? - - Generate an ordered or unordered list of links\. The *list* is a Tcl\-style - name, value list of labels and urls for the links\. *ordered* is a boolean - used to choose between an ordered or unordered list\. It defaults to - __false__\. - - - <a name='43'></a>__::html::minorMenu__ *list* ?*sep*? - - Generate a series of hypertext links\. The *list* is a Tcl\-style name, - value list of labels and urls for the links\. The *sep* is the text to put - between each link\. It defaults to " | "\. - - - <a name='44'></a>__::html::nl2br__ *string* - - This command replaces all line\-endings in the *string* with a *br* tag - and returns the modified text\. - - - <a name='45'></a>__::html::openTag__ *tag* ?*param*? - - Push *tag* onto a stack and generate the opening tag for *tag*\. Use - __::html::closeTag__ to pop the tag from the stack\. The second argument - provides any tag arguments, as a list whose elements are formatted to be in - the form "__key__=__value__"\. - - - <a name='46'></a>__::html::paramRow__ *list* ?*rparam*? ?*cparam*? - - Generate a table row, including *tr* and *td* tags\. Each value in - *list* is placed into its own table cell\. This uses __::html::cell__\. - The value of *rparam* is used as parameter for the *tr* tag\. The value - of *cparam* is passed to __::html::cell__ as parameter for the *td* - tags\. - - - <a name='47'></a>__::html::passwordInput__ ?*name*? - - Generate an *input* tag of type - *[password](\.\./\.\./\.\./\.\./index\.md\#password)*\. The *name* defaults to - "password"\. - - - <a name='48'></a>__::html::passwordInputRow__ *label* ?*name*? - - Format a table row containing a label and an *input* tag of type - *[password](\.\./\.\./\.\./\.\./index\.md\#password)*\. The *name* defaults to - "password"\. - - - <a name='49'></a>__::html::quoteFormValue__ *value* - - Quote special characters in *value* by replacing them with HTML entities - for quotes, ampersand, and angle brackets\. - - - <a name='50'></a>__::html::radioSet__ *key sep list* - - Generate a set of *input* tags of type *radio* and an associated text - label\. All the radio buttons share the same *key* for their name\. The - *sep* is text used to separate the elements\. The *list* is a Tcl\-style - label, value list\. - - - <a name='51'></a>__::html::radioValue__ *name value* - - Generate the "name=*name* value=*value*" for a *radio* form element\. - If the CGI variable *name* has the value *value*, then SELECTED is added - to the return value\. - - - <a name='52'></a>__::html::refresh__ *seconds url* - - Set up a refresh *meta* tag\. Call this before __::html::head__ and the - HEAD section will contain a *meta* tag that causes the document to refresh - in *seconds* seconds\. The *url* is optional\. If specified, it specifies - a new page to load after the refresh interval\. - - - <a name='53'></a>__::html::row__ *args* - - Generate a table row, including *tr* and *td* tags\. Each value in - *args* is place into its own table cell\. This uses __::html::cell__\. - Ignores any default information set up via __::html::init__\. - - - <a name='54'></a>__::html::select__ *name param choices* ?*current*? - - Generate a *select* form element and nested *option* tags\. The *name* - and *param* are used to generate the *select* tag\. The *choices* list - is a Tcl\-style name, value list\. - - - <a name='55'></a>__::html::selectPlain__ *name param choices* ?*current*? - - Like __::html::select__ except that *choices* is a Tcl list of values - used for the *option* tags\. The label and the value for each *option* - are the same\. - - - <a name='56'></a>__::html::set__ *var val* - - This procedure is similar to the built\-in Tcl - __[set](\.\./\.\./\.\./\.\./index\.md\#set)__ command\. The main difference is - that it returns "" so it can be called from an HTML template file without - appending unwanted results\. The other difference is that it must take two - arguments\. - - - <a name='57'></a>__::html::submit__ *label* ?*name*? ?*title*? - - Generate an *input* tag of type *submit*\. The *name* defaults to - "submit"\. When a non\-empty *title* string is specified the button gains a - __title=__ attribute with that value\. - - - <a name='58'></a>__::html::tableFromArray__ *arrname* ?*param*? ?*pat*? - - Generate a two\-column *[table](\.\./\.\./\.\./\.\./index\.md\#table)* and nested - rows to display a Tcl array\. The table gets a heading that matches the array - name, and each generated row contains a name, value pair\. The array names - are sorted \(__lsort__ without special options\)\. The argument *param* - is for the *[table](\.\./\.\./\.\./\.\./index\.md\#table)* tag and has to - contain a pre\-formatted string\. The *pat* is a __string match__ - pattern used to select the array elements to show in the table\. It defaults - to __\*__, i\.e\. the whole array is shown\. - - - <a name='59'></a>__::html::tableFromList__ *querylist* ?*param*? - - Generate a two\-column *[table](\.\./\.\./\.\./\.\./index\.md\#table)* and nested - rows to display *querylist*, which is a Tcl dictionary\. Each generated row - contains a name, value pair\. The information is shown in the same order as - specified in the dictionary\. The argument *param* is for the - *[table](\.\./\.\./\.\./\.\./index\.md\#table)* tag and has to contain a - pre\-formatted string\. - - - <a name='60'></a>__::html::textarea__ *name* ?*param*? ?*current*? - - Generate a *textarea* tag wrapped around its current values\. - - - <a name='61'></a>__::html::textInput__ *name value args* - - Generate an *input* form tag with type - *[text](\.\./\.\./\.\./\.\./index\.md\#text)*\. This uses - __::html::formValue__\. The args is any additional tag attributes you - want to put into the *input* tag\. - - - <a name='62'></a>__::html::textInputRow__ *label name value args* - - Generate an *input* form tag with type - *[text](\.\./\.\./\.\./\.\./index\.md\#text)* formatted into a table row with an - associated label\. The args is any additional tag attributes you want to put - into the *input* tag\. - - - <a name='63'></a>__::html::varEmpty__ *name* - - This returns 1 if the named variable either does not exist or has the empty - string for its value\. - - - <a name='64'></a>__::html::while__ *test body* - - This procedure is similar to the built\-in Tcl __while__ control - structure\. Rather than evaluating the body, it returns the subst'ed - *body*\. Each iteration of the loop causes another string to be - concatenated to the result value\. - - - <a name='65'></a>__::html::doctype__ *id* - - This procedure can be used to build the standard DOCTYPE declaration string\. - It will return the standard declaration string for the id, or throw an error - if the id is not known\. The following id's are defined: - - 1. HTML32 - - 1. HTML40 - - 1. HTML40T - - 1. HTML40F - - 1. HTML401 - - 1. HTML401T - - 1. HTML401F - - 1. XHTML10S - - 1. XHTML10T - - 1. XHTML10F - - 1. XHTML11 - - 1. XHTMLB - - - <a name='66'></a>__::html::wrapTag__ *tag* ?*text*? ?*args*? - - A helper to wrap a *text* in a pair of open/close *tag*s\. The arguments - \(*args*\) are a Tcl\-style name, value list that is used to provide - attributes and associated values to the opening tag\. The result is a string - with the open *tag* along with the optional attributes, the optional text, - and the closed tag\. - -# <a name='section2'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *html* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[htmlparse](\.\./htmlparse/htmlparse\.md), [ncgi](\.\./ncgi/ncgi\.md) - -# <a name='keywords'></a>KEYWORDS - -[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox), -[checkbutton](\.\./\.\./\.\./\.\./index\.md\#checkbutton), -[form](\.\./\.\./\.\./\.\./index\.md\#form), [html](\.\./\.\./\.\./\.\./index\.md\#html), -[radiobutton](\.\./\.\./\.\./\.\./index\.md\#radiobutton), -[table](\.\./\.\./\.\./\.\./index\.md\#table) - -# <a name='category'></a>CATEGORY - -CGI programming DELETED embedded/md/tcllib/files/modules/htmlparse/htmlparse.md Index: embedded/md/tcllib/files/modules/htmlparse/htmlparse.md ================================================================== --- embedded/md/tcllib/files/modules/htmlparse/htmlparse.md +++ embedded/md/tcllib/files/modules/htmlparse/htmlparse.md @@ -1,264 +0,0 @@ - -[//000000001]: # (htmlparse \- HTML Parser) -[//000000002]: # (Generated from file 'htmlparse\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (htmlparse\(n\) 1\.2\.2 tcllib "HTML Parser") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -htmlparse \- Procedures to parse HTML strings - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.2 -package require struct::stack 1\.3 -package require cmdline 1\.1 -package require htmlparse ?1\.2\.2? - -[__::htmlparse::parse__ ?\-cmd *cmd*? ?\-vroot *tag*? ?\-split *n*? ?\-incvar *var*? ?\-queue *q*? *html*](#1) -[__::htmlparse::debugCallback__ ?*clientdata*? *tag slash param textBehindTheTag*](#2) -[__::htmlparse::mapEscapes__ *html*](#3) -[__::htmlparse::2tree__ *html tree*](#4) -[__::htmlparse::removeVisualFluff__ *tree*](#5) -[__::htmlparse::removeFormDefs__ *tree*](#6) - -# <a name='description'></a>DESCRIPTION - -The __htmlparse__ package provides commands that allow libraries and -applications to parse HTML in a string into a representation of their choice\. - -The following commands are available: - - - <a name='1'></a>__::htmlparse::parse__ ?\-cmd *cmd*? ?\-vroot *tag*? ?\-split *n*? ?\-incvar *var*? ?\-queue *q*? *html* - - This command is the basic parser for HTML\. It takes an HTML string, parses - it and invokes a command prefix for every tag encountered\. It is not - necessary for the HTML to be valid for this parser to function\. It is the - responsibility of the command invoked for every tag to check this\. Another - responsibility of the invoked command is the handling of tag attributes and - character entities \(escaped characters\)\. The parser provides the - un\-interpreted tag attributes to the invoked command to aid in the former, - and the package at large provides a helper command, - __::htmlparse::mapEscapes__, to aid in the handling of the latter\. The - parser *does* ignore leading DOCTYPE declarations and all valid HTML - comments it encounters\. - - All information beyond the HTML string itself is specified via options, - these are explained below\. - - To help understand the options, some more background information about the - parser\. - - It is capable of detecting incomplete tags in the HTML string given to it\. - Under normal circumstances this will cause the parser to throw an error, but - if the option *\-incvar* is used to specify a global \(or namespace\) - variable, the parser will store the incomplete part of the input into this - variable instead\. This will aid greatly in the handling of incrementally - arriving HTML, as the parser will handle whatever it can and defer the - handling of the incomplete part until more data has arrived\. - - Another feature of the parser are its two possible modes of operation\. The - normal mode is activated if the option *\-queue* is not present on the - command line invoking the parser\. If it is present, the parser will go into - the incremental mode instead\. - - The main difference is that a parser in normal mode will immediately invoke - the command prefix for each tag it encounters\. In incremental mode however - the parser will generate a number of scripts which invoke the command prefix - for groups of tags in the HTML string and then store these scripts in the - specified queue\. It is then the responsibility of the caller of the parser - to ensure the execution of the scripts in the queue\. - - *Note*: The queue object given to the parser has to provide the same - interface as the queue defined in tcllib \-> struct\. This means, for example, - that all queues created via that tcllib module can be immediately used here\. - Still, the queue doesn't have to come from tcllib \-> struct as long as the - same interface is provided\. - - In both modes the parser will return an empty string to the caller\. - - The *\-split* option may be given to a parser in incremental mode to - specify the size of the groups it creates\. In other words, \-split 5 means - that each of the generated scripts will invoke the command prefix for 5 - consecutive tags in the HTML string\. A parser in normal mode will ignore - this option and its value\. - - The option *\-vroot* specifies a virtual root tag\. A parser in normal mode - will invoke the command prefix for it immediately before and after it - processes the tags in the HTML, thus simulating that the HTML string is - enclosed in a <vroot> </vroot> combination\. In incremental mode however the - parser is unable to provide the closing virtual root as it never knows when - the input is complete\. In this case the first script generated by each - invocation of the parser will contain an invocation of the command prefix - for the virtual root as its first command\. The following options are - available: - - * __\-cmd__ *cmd* - - The command prefix to invoke for every tag in the HTML string\. Defaults - to *::htmlparse::debugCallback*\. - - * __\-vroot__ *tag* - - The virtual root tag to add around the HTML in normal mode\. In - incremental mode it is the first tag in each chunk processed by the - parser, but there will be no closing tags\. Defaults to *hmstart*\. - - * __\-split__ *n* - - The size of the groups produced by an incremental mode parser\. Ignored - when in normal mode\. Defaults to 10\. Values <= 0 are not allowed\. - - * __\-incvar__ *var* - - The name of the variable where to store any incomplete HTML into\. This - makes most sense for the incremental mode\. The parser will throw an - error if it sees incomplete HTML and has no place to store it to\. This - makes sense for the normal mode\. Only incomplete tags are detected, not - missing tags\. Optional, defaults to 'no variable'\. - - * *Interface to the command prefix* - - In normal mode the parser will invoke the command prefix with four - arguments appended\. See __::htmlparse::debugCallback__ for a - description\. - - In incremental mode, however, the generated scripts will invoke the - command prefix with five arguments appended\. The last four of these are - the same which were mentioned above\. The first is a placeholder string - \(__@win@__\) for a clientdata value to be supplied later during the - actual execution of the generated scripts\. This could be a tk window - path, for example\. This allows the user of this package to preprocess - HTML strings without committing them to a specific window, object, - whatever during parsing\. This connection can be made later\. This also - means that it is possible to cache preprocessed HTML\. Of course, nothing - prevents the user of the parser from replacing the placeholder with an - empty string\. - - - <a name='2'></a>__::htmlparse::debugCallback__ ?*clientdata*? *tag slash param textBehindTheTag* - - This command is the standard callback used by the parser in - __::htmlparse::parse__ if none was specified by the user\. It simply - dumps its arguments to stdout\. This callback can be used for both normal and - incremental mode of the calling parser\. In other words, it accepts four or - five arguments\. The last four arguments are described below\. The optional - fifth argument contains the clientdata value passed to the callback by a - parser in incremental mode\. All callbacks have to follow the signature of - this command in the last four arguments, and callbacks used in incremental - parsing have to follow this signature in the last five arguments\. - - The first argument, *clientdata*, is optional and present only if this - command is invoked by a parser in incremental mode\. It contains whatever the - user of this package wishes\. - - The second argument, *tag*, contains the name of the tag which is - currently processed by the parser\. - - The third argument, *slash*, is either empty or contains a slash - character\. It allows the callback to distinguish between opening \(slash is - empty\) and closing tags \(slash contains a slash character\)\. - - The fourth argument, *param*, contains the un\-interpreted list of - parameters to the tag\. - - The fifth and last argument, *textBehindTheTag*, contains the text found - by the parser behind the tag named in *tag*\. - - - <a name='3'></a>__::htmlparse::mapEscapes__ *html* - - This command takes a HTML string, substitutes all escape sequences with - their actual characters and then returns the resulting string\. HTML strings - which do not contain escape sequences are returned unchanged\. - - - <a name='4'></a>__::htmlparse::2tree__ *html tree* - - This command is a wrapper around __::htmlparse::parse__ which takes an - HTML string \(in *html*\) and converts it into a tree containing the logical - structure of the parsed document\. The name of the tree is given to the - command as its second argument \(*tree*\)\. The command does __not__ - generate the tree by itself but expects that the caller provided it with an - existing and empty tree\. It also expects that the specified tree object - follows the same interface as the tree object in tcllib \-> struct\. It - doesn't have to be from tcllib \-> struct, but it must provide the same - interface\. - - The internal callback does some basic checking of HTML validity and tries to - recover from the most basic errors\. The command returns the contents of its - second argument\. Side effects are the creation and manipulation of a tree - object\. - - Each node in the generated tree represent one tag in the input\. The name of - the tag is stored in the attribute *type* of the node\. Any html attributes - coming with the tag are stored unmodified in the attribute *data* of the - tag\. In other words, the command does *not* parse html attributes into - their names and values\. - - If a tag contains text its node will have children of type *PCDATA* - containing this text\. The text will be stored in the attribute *data* of - these children\. - - - <a name='5'></a>__::htmlparse::removeVisualFluff__ *tree* - - This command walks a tree as generated by __::htmlparse::2tree__ and - removes all the nodes which represent visual tags and not structural ones\. - The purpose of the command is to make the tree easier to navigate without - getting bogged down in visual information not relevant to the search\. Its - only argument is the name of the tree to cut down\. - - - <a name='6'></a>__::htmlparse::removeFormDefs__ *tree* - - Like __::htmlparse::removeVisualFluff__ this command is here to cut down - on the size of the tree as generated by __::htmlparse::2tree__\. It - removes all nodes representing forms and form elements\. Its only argument is - the name of the tree to cut down\. - -# <a name='section2'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *htmlparse* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -[struct::tree](\.\./struct/struct\_tree\.md) - -# <a name='keywords'></a>KEYWORDS - -[html](\.\./\.\./\.\./\.\./index\.md\#html), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[queue](\.\./\.\./\.\./\.\./index\.md\#queue), [tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# <a name='category'></a>CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/http/autoproxy.md Index: embedded/md/tcllib/files/modules/http/autoproxy.md ================================================================== --- embedded/md/tcllib/files/modules/http/autoproxy.md +++ embedded/md/tcllib/files/modules/http/autoproxy.md @@ -1,299 +0,0 @@ - -[//000000001]: # (autoproxy \- HTTP protocol helper modules) -[//000000002]: # (Generated from file 'autoproxy\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (autoproxy\(n\) 1\.7 tcllib "HTTP protocol helper modules") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -autoproxy \- Automatic HTTP proxy usage and authentication - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TLS Security Considerations](#section2) - - - [COMMANDS](#section3) - - - [OPTIONS](#section4) - - - [Basic Authentication](#section5) - - - [EXAMPLES](#section6) - - - [REFERENCES](#section7) - - - [BUGS](#section8) - - - [AUTHORS](#section9) - - - [Bugs, Ideas, Feedback](#section10) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.5 -package require http ?2\.0? -package require autoproxy ?1\.7? - -[__::autoproxy::init__](#1) -[__::autoproxy::cget__ *\-option*](#2) -[__::autoproxy::configure__ ?\-option *value*?](#3) -[__::autoproxy::tls\_connect__ *args*](#4) -[__::autoproxy::tunnel\_connect__ *args*](#5) -[__::autoproxy::tls\_socket__ *args*](#6) - -# <a name='description'></a>DESCRIPTION - -This package attempts to automate the use of HTTP proxy servers in Tcl HTTP -client code\. It tries to initialize the web access settings from system standard -locations and can be configured to negotiate authentication with the proxy if -required\. - -On Unix the standard for identifying the local HTTP proxy server seems to be to -use the environment variable http\_proxy or ftp\_proxy and no\_proxy to list those -domains to be excluded from proxying\. On Windows we can retrieve the Internet -Settings values from the registry to obtain pretty much the same information\. -With this information we can setup a suitable filter procedure for the Tcl http -package and arrange for automatic use of the proxy\. - -There seem to be a number of ways that the http\_proxy environment variable may -be set up\. Either a plain host:port or more commonly a URL and sometimes the URL -may contain authentication parameters or these may be requested from the user or -provided via http\_proxy\_user and http\_proxy\_pass\. This package attempts to deal -with all these schemes\. It will do it's best to get the required parameters from -the environment or registry and if it fails can be reconfigured\. - -# <a name='section2'></a>TLS Security Considerations - -*Note* This section only applies if TLS support is provided by the -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package\. It does not apply when -__autoproxy__ was configured to use some other package which can provide the -same \(i\.e __twapi__\), via the __\-tls\_package__ configuration option\. - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# <a name='section3'></a>COMMANDS - - - <a name='1'></a>__::autoproxy::init__ - - Initialize the autoproxy package from system resources\. Under unix this - means we look for environment variables\. Under windows we look for the same - environment variables but also look at the registry settings used by - Internet Explorer\. - - - <a name='2'></a>__::autoproxy::cget__ *\-option* - - Retrieve individual package configuration options\. See - [OPTIONS](#section4)\. - - - <a name='3'></a>__::autoproxy::configure__ ?\-option *value*? - - Configure the autoproxy package\. Calling __configure__ with no options - will return a list of all option names and values\. See - [OPTIONS](#section4)\. - - - <a name='4'></a>__::autoproxy::tls\_connect__ *args* - - Connect to a secure socket through a proxy\. HTTP proxy servers permit the - use of the CONNECT HTTP command to open a link through the proxy to the - target machine\. This function hides the details\. For use with the http - package see __tls\_socket__\. - - The *args* list may contain any of the options supported by the specific - TLS package that is in use but must end with the host and port as the last - two items\. - - - <a name='5'></a>__::autoproxy::tunnel\_connect__ *args* - - Connect to a target host throught a proxy\. This uses the same CONNECT HTTP - command as the __tls\_connect__ but does not promote the link security - once the connection is established\. - - The *args* list may contain any of the options supported by the specific - TLS package that is in use but must end with the host and port as the last - two items\. - - Note that many proxy servers will permit CONNECT calls to a limited set of - ports \- typically only port 443 \(the secure HTTP port\)\. - - - <a name='6'></a>__::autoproxy::tls\_socket__ *args* - - This function is to be used to register a proxy\-aware secure socket handler - for the https protocol\. It may only be used with the Tcl http package and - should be registered using the http::register command \(see the examples - below\)\. The job of actually creating the tunnelled connection is done by the - tls\_connect command and this may be used when not registering with the http - package\. - -# <a name='section4'></a>OPTIONS - - - __\-host__ hostname - - - __\-proxy\_host__ hostname - - Set the proxy hostname\. This is normally set up by __init__ but may be - configured here as well\. - - - __\-port__ number - - - __\-proxy\_port__ number - - Set the proxy port number\. This is normally set up by __init__\. e\.g\. - __configure__ __\-port__ *3128* - - - __\-no\_proxy__ list - - You may manipulate the __no\_proxy__ list that was setup by __init__\. - The value of this option is a tcl list of strings that are matched against - the http request host using the tcl __string match__ command\. Therefore - glob patterns are permitted\. For instance, __configure__ - __\-no\_proxy__ *\*\.localdomain* - - - __\-authProc__ procedure - - This option may be used to set an application defined procedure to be called - when __configure__ __\-basic__ is called with either no or - insufficient authentication details\. This can be used to present a dialog to - the user to request the additional information\. - - - __\-basic__ - - Following options are for configuring the Basic authentication scheme - parameters\. See [Basic Authentication](#section5)\. To unset the proxy - authentication information retained from a previous call of this function - either "\-\-" or no additional parameters can be supplied\. This will remove - the existing authentication information\. - - - __\-tls\_package__ packagename - - This option may be used to configure the Tcl package to use for TLS support\. - Valid package names are __tls__ \(default\) and __twapi__\. - -# <a name='section5'></a>Basic Authentication - -Basic is the simplest and most commonly use HTTP proxy authentication scheme\. It -is described in \(1 section 11\) and also in \(2\)\. It offers no privacy whatsoever -and its use should be discouraged in favour of more secure alternatives like -Digest\. To perform Basic authentication the client base64 encodes the username -and plaintext password separated by a colon\. This encoded text is prefixed with -the word "Basic" and a space\. - -The following options exists for this scheme: - - - __\-username__ name - - The username required to authenticate with the configured proxy\. - - - __\-password__ password - - The password required for the username specified\. - - - __\-realm__ realm - - This option is not used by this package but may be used in requesting - authentication details from the user\. - - - __\-\-__ - - The end\-of\-options indicator may be used alone to unset any authentication - details currently enabled\. - -# <a name='section6'></a>EXAMPLES - - package require autoproxy - autoproxy::init - autoproxy::configure -basic -username ME -password SEKRET - set tok [http::geturl http://wiki.tcl.tk/] - http::data $tok - - package require http - package require tls - package require autoproxy - autoproxy::init - http::register https 443 autoproxy::tls_socket - set tok [http::geturl https://www.example.com/] - -# <a name='section7'></a>REFERENCES - - 1. Berners\-Lee, T\., Fielding R\. and Frystyk, H\. "Hypertext Transfer Protocol - \-\- HTTP/1\.0", RFC 1945, May 1996, - \([http://www\.rfc\-editor\.org/rfc/rfc1945\.txt](http://www\.rfc\-editor\.org/rfc/rfc1945\.txt)\) - - 1. Franks, J\. et al\. "HTTP Authentication: Basic and Digest Access - Authentication", RFC 2617, June 1999 - \([http://www\.rfc\-editor\.org/rfc/rfc2617\.txt](http://www\.rfc\-editor\.org/rfc/rfc2617\.txt)\) - -# <a name='section8'></a>BUGS - -At this time only Basic authentication \(1\) \(2\) is supported\. It is planned to -add support for Digest \(2\) and NTLM in the future\. - -# <a name='section9'></a>AUTHORS - -Pat Thoyts - -# <a name='section10'></a>Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *http :: autoproxy* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# <a name='seealso'></a>SEE ALSO - -http\(n\) - -# <a name='keywords'></a>KEYWORDS - -[authentication](\.\./\.\./\.\./\.\./index\.md\#authentication), -[http](\.\./\.\./\.\./\.\./index\.md\#http), [proxy](\.\./\.\./\.\./\.\./index\.md\#proxy) - -# <a name='category'></a>CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/httpd/httpd.md Index: embedded/md/tcllib/files/modules/httpd/httpd.md ================================================================== --- embedded/md/tcllib/files/modules/httpd/httpd.md +++ embedded/md/tcllib/files/modules/httpd/httpd.md @@ -1,854 +0,0 @@ - -[//000000001]: # (httpd \- Tcl Web Server) -[//000000002]: # (Generated from file 'httpd\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2018 Sean Woods <yoda@etoyoc\.com>) -[//000000004]: # (httpd\(n\) 4\.3\.5 tcllib "Tcl Web Server") - -<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a -href="../../../toc.md">Table Of Contents</a> | <a -href="../../../../index.md">Keyword Index</a> | <a -href="../../../../toc0.md">Categories</a> | <a -href="../../../../toc1.md">Modules</a> | <a -href="../../../../toc2.md">Applications</a> ] <hr> - -# NAME - -httpd \- A TclOO and coroutine based web server - -# <a name='toc'></a>Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Minimal Example](#section2) - - - [Classes](#section3) - - - [Class httpd::mime](#subsection1) - - - [Class httpd::reply](#subsection2) - - - [Class httpd::server](#subsection3) - - - [Class httpd::server::dispatch](#subsection4) - - - [Class httpd::content\.redirect](#subsection5) - - - [Class httpd::content\.cache](#subsection6) - - - [Class httpd::content\.template](#subsection7) - - - [Class httpd::content\.file](#subsection8) - - - [Class httpd::content\.exec](#subsection9) - - - [Class httpd::content\.proxy](#subsection10) - - - [Class httpd::content\.cgi](#subsection11) - - - [Class httpd::protocol\.scgi](#subsection12) - - - [Class httpd::content\.scgi](#subsection13) - - - [Class httpd::server\.scgi](#subsection14) - - - [Class httpd::content\.websocket](#subsection15) - - - [Class httpd::plugin](#subsection16) - - - [Class httpd::plugin\.dict\_dispatch](#subsection17) - - - [Class httpd::reply\.memchan](#subsection18) - - - [Class httpd::plugin\.local\_memchan](#subsection19) - - - [AUTHORS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# <a name='synopsis'></a>SYNOPSIS - -package require Tcl 8\.6 -package require uuid -package require clay -package require coroutine -package require fileutil -package require fileutil::magic::filetype -package require websocket -package require mime -package require cron -package require uri -package require Markdown - -[method __ChannelCopy__ *in* *out* ?*args*?](#1) -[method __html\_header__ ?*title* ____? ?*args*?](#2) -[method __html\_footer__ ?*args*?](#3) -[method __http\_code\_string__ *code*](#4) -[method __HttpHeaders__ *sock* ?*debug* ____?](#5) -[method __HttpHeaders\_Default__](#6) -[method __HttpServerHeaders__](#7) -[method __MimeParse__ *mimetext*](#8) -[method __Url\_Decode__ *data*](#9) -[method __Url\_PathCheck__ *urlsuffix*](#10) -[method __wait__ *mode* *sock*](#11) -[variable __ChannelRegister__](#12) -[variable __reply__](#13) -[variable __request__](#14) -[delegate __<server>__](#15) -[method __constructor__ *ServerObj* ?*args*?](#16) -[method __destructor__ ?*dictargs*?](#17) -[method __ChannelRegister__ ?*args*?](#18) -[method __close__](#19) -[method __Log\_Dispatched__](#20) -[method __dispatch__ *newsock* *datastate*](#21) -[method __Dispatch__](#22) -[method __html\_header__ *title* ?*args*?](#23) -[method __html\_footer__ ?*args*?](#24) -[method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* ?*msg* ____? ?*errorInfo* ____?](#25) -[method __content__](#26) -[method __EncodeStatus__ *status*](#27) -[method __[log](\.\./log/log\.md)__ *type* ?*info* ____?](#28) -[method __CoroName__](#29) -[method __DoOutput__](#30) -[method __FormData__](#31) -[method __PostData__ *length*](#32) -[method __Session\_Load__](#33) -[method __puts__ *line*](#34) -[method __RequestFind__ *field*](#35) -[method __request__ *subcommand* ?*args*?](#36) -[method __reply__ *subcommand* ?*args*?](#37) -[method __reset__](#38) -[method __timeOutCheck__](#39) -[method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__](#40) -[variable __template__](#41) -[variable __url\_patterns__](#42) -[method __constructor__ *args* ?*port* __auto__? ?*myaddr* __127\.0\.0\.1__? ?*string* __auto__? ?*name* __auto__? ?*doc\_root* ____? ?*reverse\_dns* __0__? ?*configuration\_file* ____? ?*protocol* __HTTP/1\.1__?](#43) -[method __destructor__ ?*dictargs*?](#44) -[method __connect__ *sock* *ip* *port*](#45) -[method __ServerHeaders__ *ip* *http\_request* *mimetxt*](#46) -[method __Connect__ *uuid* *sock* *ip*](#47) -[method __[counter](\.\./counter/counter\.md)__ *which*](#48) -[method __CheckTimeout__](#49) -[method __[debug](\.\./debug/debug\.md)__ ?*args*?](#50) -[method __dispatch__ *data*](#51) -[method __Dispatch\_Default__ *reply*](#52) -[method __Dispatch\_Local__ *data*](#53) -[method __Headers\_Local__ *varname*](#54) -[method __Headers\_Process__ *varname*](#55) -[method __HostName__ *ipaddr*](#56) -[method __[log](\.\./log/log\.md)__ ?*args*?](#57) -[method __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ *slot* ?*class* ____?](#58) -[method __port\_listening__](#59) -[method __PrefixNormalize__ *prefix*](#60) -[method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*](#61) -[method __start__](#62) -[method __stop__](#63) -[method __SubObject \{\} db__](#64) -[method __SubObject \{\} default__](#65) -[method __template__ *page*](#66) -[method __TemplateSearch__ *page*](#67) -[method __Thread\_start__](#68) -[method __Uuid\_Generate__](#69) -[method __Validate\_Connection__ *sock* *ip*](#70) -[method __reset__](#71) -[method __content__](#72) -[method __Dispatch__](#73) -[method __content__](#74) -[method __FileName__](#75) -[method __DirectoryListing__ *local\_file*](#76) -[method __content__](#77) -[method __Dispatch__](#78) -[variable __exename__](#79) -[method __CgiExec__ *execname* *script* *arglist*](#80) -[method __Cgi\_Executable__ *script*](#81) -[method __proxy\_channel__](#82) -[method __proxy\_path__](#83) -[method __ProxyRequest__ *chana* *chanb*](#84) -[method __ProxyReply__ *chana* *chanb* ?*args*?](#85) -[method __Dispatch__](#86) -[method __FileName__](#87) -[method __proxy\_channel__](#88) -[method __ProxyRequest__ *chana* *chanb*](#89) -[method __ProxyReply__ *chana* *chanb* ?*args*?](#90) -[method __DirectoryListing__ *local\_file*](#91) -[method __EncodeStatus__ *status*](#92) -[method __scgi\_info__](#93) -[method __proxy\_channel__](#94) -[method __ProxyRequest__ *chana* *chanb*](#95) -[method __ProxyReply__ *chana* *chanb* ?*args*?](#96) -[method __[debug](\.\./debug/debug\.md)__ ?*args*?](#97) -[method __Connect__ *uuid* *sock* *ip*](#98) -[method __Dispatch\_Dict__ *data*](#99) -[method __uri \{\} add__ *vhosts* *patterns* *info*](#100) -[method __uri \{\} direct__ *vhosts* *patterns* *info* *body*](#101) -[method __output__](#102) -[method __DoOutput__](#103) -[method __close__](#104) -[method __local\_memchan__ *command* ?*args*?](#105) -[method __Connect\_Local__ *uuid* *sock* ?*args*?](#106) - -# <a name='description'></a>DESCRIPTION - -This module implements a web server, suitable for embedding in an application\. -The server is object oriented, and contains all of the fundamentals needed for a -full service website\. - -# <a name='section2'></a>Minimal Example - -Starting a web service requires starting a class of type __httpd::server__, -and providing that server with one or more URIs to service, and -__httpd::reply__ derived classes to generate them\. - - oo::class create ::reply.hello { - method content {} { - my puts "<HTML><HEAD><TITLE>IRM Dispatch Server" - my puts "

Hello World!

" - my puts - } - } - ::httpd::server create HTTPD port 8015 myaddr 127.0.0.1 doc_root ~/htdocs - HTTPD plugin dispatch httpd::server::dispatch - HTTPD uri add * /hello [list mixin reply.hello] - -The bare module does have facilities to hose a files from a file system\. Files -that end in a \.tml will be substituted in the style of Tclhttpd: - - - [my html_header {Hello World!}] - Your Server is running. -

- The time is now [clock format [clock seconds]] - [my html_footer] - -A complete example of an httpd server is in the /examples directory of Tcllib\. -It also show how to dispatch URIs to other processes via SCGI and HTTP proxies\. - - cd ~/tcl/sandbox/tcllib - tclsh examples/httpd.tcl - -# Classes - -## Class httpd::mime - -A metaclass for MIME handling behavior across a live socket - -__Methods__ - - - method __ChannelCopy__ *in* *out* ?*args*? - - - method __html\_header__ ?*title* ____? ?*args*? - - Returns a block of HTML - - - method __html\_footer__ ?*args*? - - - method __http\_code\_string__ *code* - - - method __HttpHeaders__ *sock* ?*debug* ____? - - - method __HttpHeaders\_Default__ - - - method __HttpServerHeaders__ - - - method __MimeParse__ *mimetext* - - Converts a block of mime encoded text to a key/value list\. If an exception - is encountered, the method will generate its own call to the - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method, and immediately - invoke the __output__ method to produce an error code and close the - connection\. - - - method __Url\_Decode__ *data* - - De\-httpizes a string\. - - - method __Url\_PathCheck__ *urlsuffix* - - - method __wait__ *mode* *sock* - -## Class httpd::reply - -*ancestors*: __httpd::mime__ - -A class which shephards a request through the process of generating a reply\. The -socket associated with the reply is available at all times as the *chan* -variable\. The process of generating a reply begins with an __httpd::server__ -generating a __http::class__ object, mixing in a set of behaviors and then -invoking the reply object's __dispatch__ method\. In normal operations the -__dispatch__ method: - - 1. Invokes the __reset__ method for the object to populate default - headers\. - - 1. Invokes the __HttpHeaders__ method to stream the MIME headers out of - the socket - - 1. Invokes the __request parse__ method to convert the stream of MIME - headers into a dict that can be read via the __request__ method\. - - 1. Stores the raw stream of MIME headers in the *rawrequest* variable of the - object\. - - 1. Invokes the __content__ method for the object, generating an call to - the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method if an exception - is raised\. - - 1. Invokes the __output__ method for the object - -Developers have the option of streaming output to a buffer via the __puts__ -method of the reply, or simply populating the *reply\_body* variable of the -object\. The information returned by the __content__ method is not -interpreted in any way\. If an exception is thrown \(via the -__[error](\.\./\.\./\.\./\.\./index\.md\#error)__ command in Tcl, for example\) the -caller will auto\-generate a 500 \{Internal Error\} message\. A typical -implementation of __content__ look like: - - clay::define ::test::content.file { - superclass ::httpd::content.file - # Return a file - # Note: this is using the content.file mixin which looks for the reply_file variable - # and will auto-compute the Content-Type - method content {} { - my reset - set doc_root [my request get DOCUMENT_ROOT] - my variable reply_file - set reply_file [file join $doc_root index.html] - } - } - clay::define ::test::content.time { - # return the current system time - method content {} { - my variable reply_body - my reply set Content-Type text/plain - set reply_body [clock seconds] - } - } - clay::define ::test::content.echo { - method content {} { - my variable reply_body - my reply set Content-Type [my request get CONTENT_TYPE] - set reply_body [my PostData [my request get CONTENT_LENGTH]] - } - } - clay::define ::test::content.form_handler { - method content {} { - set form [my FormData] - my reply set Content-Type {text/html; charset=UTF-8} - my puts [my html_header {My Dynamic Page}] - my puts "" - my puts "You Sent

" - my puts "" - foreach {f v} $form { - my puts "" - } - my puts "
$f$v

" - my puts "Send some info:

" - my puts "

" - my puts "" - foreach field {name rank serial_number} { - set line "" - my puts $line - } - my puts "
$field
" - my puts [my html footer] - } - } - -__Variable__ - - - variable __ChannelRegister__ - - - variable __reply__ - - A dictionary which will converted into the MIME headers of the reply - - - variable __request__ - - A dictionary containing the SCGI transformed HTTP headers for the request - -__Delegate__ - - - delegate ____ - - The server object which spawned this reply - -__Methods__ - - - method __constructor__ *ServerObj* ?*args*? - - - method __destructor__ ?*dictargs*? - - clean up on exit - - - method __ChannelRegister__ ?*args*? - - Registers a channel to be closed by the close method - - - method __close__ - - Close channels opened by this object - - - method __Log\_Dispatched__ - - Record a dispatch event - - - method __dispatch__ *newsock* *datastate* - - Accept the handoff from the server object of the socket *newsock* and feed - it the state *datastate*\. Fields the *datastate* are looking for in - particular are: - - \* __mixin__ \- A key/value list of slots and classes to be mixed into the - object prior to invoking __Dispatch__\. - - \* __http__ \- A key/value list of values to populate the object's - *request* ensemble - - All other fields are passed along to the __clay__ structure of the - object\. - - - method __Dispatch__ - - - method __html\_header__ *title* ?*args*? - - - method __html\_footer__ ?*args*? - - - method __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ *code* ?*msg* ____? ?*errorInfo* ____? - - - method __content__ - - REPLACE ME: This method is the "meat" of your application\. It writes to the - result buffer via the "puts" method and can tweak the headers via "clay put - header\_reply" - - - method __EncodeStatus__ *status* - - Formulate a standard HTTP status header from he string provided\. - - - method __[log](\.\./log/log\.md)__ *type* ?*info* ____? - - - method __CoroName__ - - - method __DoOutput__ - - Generates the the HTTP reply, streams that reply back across *chan*, and - destroys the object\. - - - method __FormData__ - - For GET requests, converts the QUERY\_DATA header into a key/value list\. For - POST requests, reads the Post data and converts that information to a - key/value list for application/x\-www\-form\-urlencoded posts\. For multipart - posts, it composites all of the MIME headers of the post to a singular - key/value list, and provides MIME\_\* information as computed by the - __[mime](\.\./mime/mime\.md)__ package, including the MIME\_TOKEN, which - can be fed back into the mime package to read out the contents\. - - - method __PostData__ *length* - - Stream *length* bytes from the *chan* socket, but only of the request is - a POST or PUSH\. Returns an empty string otherwise\. - - - method __Session\_Load__ - - Manage session data - - - method __puts__ *line* - - Appends the value of *string* to the end of *reply\_body*, as well as a - trailing newline character\. - - - method __RequestFind__ *field* - - - method __request__ *subcommand* ?*args*? - - - method __reply__ *subcommand* ?*args*? - - - method __reset__ - - Clear the contents of the *reply\_body* variable, and reset all headers in - the __reply__ structure back to the defaults for this object\. - - - method __timeOutCheck__ - - Called from the __http::server__ object which spawned this reply\. Checks - to see if too much time has elapsed while waiting for data or generating a - reply, and issues a timeout error to the request if it has, as well as - destroy the object and close the *chan* socket\. - - - method __[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp)__ - - Return the current system time in the format: - - %a, %d %b %Y %T %Z - -## Class httpd::server - -*ancestors*: __httpd::mime__ - -__Variable__ - - - variable __template__ - - - variable __url\_patterns__ - -__Methods__ - - - method __constructor__ *args* ?*port* __auto__? ?*myaddr* __127\.0\.0\.1__? ?*string* __auto__? ?*name* __auto__? ?*doc\_root* ____? ?*reverse\_dns* __0__? ?*configuration\_file* ____? ?*protocol* __HTTP/1\.1__? - - - method __destructor__ ?*dictargs*? - - - method __connect__ *sock* *ip* *port* - - Reply to an open socket\. This method builds a coroutine to manage the - remainder of the connection\. The coroutine's operations are driven by the - __Connect__ method\. - - - method __ServerHeaders__ *ip* *http\_request* *mimetxt* - - - method __Connect__ *uuid* *sock* *ip* - - This method reads HTTP headers, and then consults the __dispatch__ - method to determine if the request is valid, and/or what kind of reply to - generate\. Under normal cases, an object of class __::http::reply__ is - created, and that class's __dispatch__ method\. This action passes - control of the socket to the reply object\. The reply object manages the rest - of the transaction, including closing the socket\. - - - method __[counter](\.\./counter/counter\.md)__ *which* - - Increment an internal counter\. - - - method __CheckTimeout__ - - Check open connections for a time out event\. - - - method __[debug](\.\./debug/debug\.md)__ ?*args*? - - - method __dispatch__ *data* - - Given a key/value list of information, return a data structure describing - how the server should reply\. - - - method __Dispatch\_Default__ *reply* - - Method dispatch method of last resort before returning a 404 NOT FOUND - error\. The default behavior is to look for a file in *DOCUMENT\_ROOT* which - matches the query\. - - - method __Dispatch\_Local__ *data* - - Method dispatch method invoked prior to invoking methods implemented by - plugins\. If this method returns a non\-empty dictionary, that structure will - be passed to the reply\. The default is an empty implementation\. - - - method __Headers\_Local__ *varname* - - Introspect and possibly modify a data structure destined for a reply\. This - method is invoked before invoking Header methods implemented by plugins\. The - default implementation is empty\. - - - method __Headers\_Process__ *varname* - - Introspect and possibly modify a data structure destined for a reply\. This - method is built dynamically by the - __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method\. - - - method __HostName__ *ipaddr* - - Convert an ip address to a host name\. If the server/ reverse\_dns flag is - false, this method simply returns the IP address back\. Internally, this - method uses the *dns* module from tcllib\. - - - method __[log](\.\./log/log\.md)__ ?*args*? - - Log an event\. The input for args is free form\. This method is intended to be - replaced by the user, and is a noop for a stock http::server object\. - - - method __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ *slot* ?*class* ____? - - Incorporate behaviors from a plugin\. This method dynamically rebuilds the - __Dispatch__ and __Headers__ method\. For every plugin, the server - looks for the following entries in *clay plugin/*: - - *load* \- A script to invoke in the server's namespace during the - __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method invokation\. - - *dispatch* \- A script to stitch into the server's __Dispatch__ method\. - - *headers* \- A script to stitch into the server's __Headers__ method\. - - *thread* \- A script to stitch into the server's __Thread\_start__ - method\. - - - method __port\_listening__ - - Return the actual port that httpd is listening on\. - - - method __PrefixNormalize__ *prefix* - - For the stock version, trim trailing /'s and \*'s from a prefix\. This method - can be replaced by the end user to perform any other transformations needed - for the application\. - - - method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename* - - - method __start__ - - Open the socket listener\. - - - method __stop__ - - Shut off the socket listener, and destroy any pending replies\. - - - method __SubObject \{\} db__ - - - method __SubObject \{\} default__ - - - method __template__ *page* - - Return a template for the string *page* - - - method __TemplateSearch__ *page* - - Perform a search for the template that best matches *page*\. This can - include local file searches, in\-memory structures, or even database lookups\. - The stock implementation simply looks for files with a \.tml or \.html - extension in the ?doc\_root? directory\. - - - method __Thread\_start__ - - Built by the __[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin)__ method\. - Called by the __start__ method\. Intended to allow plugins to spawn - worker threads\. - - - method __Uuid\_Generate__ - - Generate a GUUID\. Used to ensure every request has a unique ID\. The default - implementation is: - - return [::clay::uuid generate] - - - method __Validate\_Connection__ *sock* *ip* - - Given a socket and an ip address, return true if this connection should be - terminated, or false if it should be allowed to continue\. The stock - implementation always returns 0\. This is intended for applications to be - able to implement black lists and/or provide security based on IP address\. - -## Class httpd::server::dispatch - -*ancestors*: __httpd::server__ - -Provide a backward compadible alias - -## Class httpd::content\.redirect - -__Methods__ - - - method __reset__ - - - method __content__ - -## Class httpd::content\.cache - -__Methods__ - - - method __Dispatch__ - -## Class httpd::content\.template - -__Methods__ - - - method __content__ - -## Class httpd::content\.file - -Class to deliver Static content When utilized, this class is fed a local -filename by the dispatcher - -__Methods__ - - - method __FileName__ - - - method __DirectoryListing__ *local\_file* - - - method __content__ - - - method __Dispatch__ - -## Class httpd::content\.exec - -__Variable__ - - - variable __exename__ - -__Methods__ - - - method __CgiExec__ *execname* *script* *arglist* - - - method __Cgi\_Executable__ *script* - -## Class httpd::content\.proxy - -*ancestors*: __httpd::content\.exec__ - -Return data from an proxy process - -__Methods__ - - - method __proxy\_channel__ - - - method __proxy\_path__ - - - method __ProxyRequest__ *chana* *chanb* - - - method __ProxyReply__ *chana* *chanb* ?*args*? - - - method __Dispatch__ - -## Class httpd::content\.cgi - -*ancestors*: __httpd::content\.proxy__ - -__Methods__ - - - method __FileName__ - - - method __proxy\_channel__ - - - method __ProxyRequest__ *chana* *chanb* - - - method __ProxyReply__ *chana* *chanb* ?*args*? - - - method __DirectoryListing__ *local\_file* - - For most CGI applications a directory list is vorboten - -## Class httpd::protocol\.scgi - -Return data from an SCGI process - -__Methods__ - - - method __EncodeStatus__ *status* - -## Class httpd::content\.scgi - -*ancestors*: __httpd::content\.proxy__ - -__Methods__ - - - method __scgi\_info__ - - - method __proxy\_channel__ - - - method __ProxyRequest__ *chana* *chanb* - - - method __ProxyReply__ *chana* *chanb* ?*args*? - -## Class httpd::server\.scgi - -*ancestors*: __httpd::server__ - -Act as an SCGI Server - -__Methods__ - - - method __[debug](\.\./debug/debug\.md)__ ?*args*? - - - method __Connect__ *uuid* *sock* *ip* - -## Class httpd::content\.websocket - -Upgrade a connection to a websocket - -## Class httpd::plugin - -httpd plugin template - -## Class httpd::plugin\.dict\_dispatch - -A rudimentary plugin that dispatches URLs from a dict data structure - -__Methods__ - - - method __Dispatch\_Dict__ *data* - - Implementation of the dispatcher - - - method __uri \{\} add__ *vhosts* *patterns* *info* - - - method __uri \{\} direct__ *vhosts* *patterns* *info* *body* - -## Class httpd::reply\.memchan - -*ancestors*: __httpd::reply__ - -__Methods__ - - - method __output__ - - - method __DoOutput__ - - - method __close__ - -## Class httpd::plugin\.local\_memchan - -__Methods__ - - - method __local\_memchan__ *command* ?*args*? - - - method __Connect\_Local__ *uuid* *sock* ?*args*? - - A modified connection method that passes simple GET request to an object and - pulls data directly from the reply\_body data variable in the object Needed - because memchan is bidirectional, and we can't seem to communicate that the - server is one side of the link and the reply is another - -# AUTHORS - -Sean Woods - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *network* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), [WWW](\.\./\.\./\.\./\.\./index\.md\#www), -[http](\.\./\.\./\.\./\.\./index\.md\#http), [httpd](\.\./\.\./\.\./\.\./index\.md\#httpd), -[httpserver](\.\./\.\./\.\./\.\./index\.md\#httpserver), -[services](\.\./\.\./\.\./\.\./index\.md\#services) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2018 Sean Woods DELETED embedded/md/tcllib/files/modules/ident/ident.md Index: embedded/md/tcllib/files/modules/ident/ident.md ================================================================== --- embedded/md/tcllib/files/modules/ident/ident.md +++ embedded/md/tcllib/files/modules/ident/ident.md @@ -1,100 +0,0 @@ - -[//000000001]: # (ident \- Identification protocol client) -[//000000002]: # (Generated from file 'ident\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Reinhard Max ) -[//000000004]: # (ident\(n\) 0\.42 tcllib "Identification protocol client") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ident \- Ident protocol client - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require ident ?0\.42? - -[__::ident::query__ *socket* ?*callback*?](#1) - -# DESCRIPTION - -The __ident__ package provides a client implementation of the ident protocol -as defined in RFC 1413 -\([http://www\.rfc\-editor\.org/rfc/rfc1413\.txt](http://www\.rfc\-editor\.org/rfc/rfc1413\.txt)\)\. - - - __::ident::query__ *socket* ?*callback*? - - This command queries the ident daemon on the remote side of the given - socket, and returns the result of the query as a dictionary\. Interpreting - the dictionary as list the first key will always be __resp\-type__, and - can have one of the values __USERID__, __ERROR__, and __FATAL__\. - These *response types* have the following meanings: - - * USERID - - This indicates a successful response\. Two more keys and associated - values are returned, __opsys__, and __user\-id__\. - - * ERROR - - This means the ident server has returned an error\. A second key named - __error__ is present whose value contains the __error\-type__ - field from the server response\. - - * FATAL - - Fatal errors happen when no ident server is listening on the remote - side, or when the ident server gives a response that does not conform to - the RFC\. A detailed error message is returned under the __error__ - key\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ident* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ident](\.\./\.\./\.\./\.\./index\.md\#ident), -[identification](\.\./\.\./\.\./\.\./index\.md\#identification), [rfc -1413](\.\./\.\./\.\./\.\./index\.md\#rfc\_1413) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2004 Reinhard Max DELETED embedded/md/tcllib/files/modules/imap4/imap4.md Index: embedded/md/tcllib/files/modules/imap4/imap4.md ================================================================== --- embedded/md/tcllib/files/modules/imap4/imap4.md +++ embedded/md/tcllib/files/modules/imap4/imap4.md @@ -1,521 +0,0 @@ - -[//000000001]: # (imap4 \- imap client) -[//000000002]: # (Generated from file 'imap4\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (imap4\(n\) 0\.5\.3 tcllib "imap client") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -imap4 \- imap client\-side tcl implementation of imap protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [EXAMPLES](#section3) - - - [TLS Security Considerations](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require imap4 ?0\.5\.3? - -[__::imap4::open__ *hostname* ?*port*?](#1) -[__::imap4::starttls__ *chan*](#2) -[__::imap4::login__ *chan* *user* *pass*](#3) -[__::imap4::folders__ *chan* ?*\-inline*? ?*mboxref*? ?*mboxname*?](#4) -[__::imap4::select__ *chan* ?*mailbox*?](#5) -[__::imap4::examine__ *chan* ?*mailbox*?](#6) -[__::imap4::fetch__ *chan* *range* ?*\-inline*? ?*attr \.\.\.*?](#7) -[__::imap4::noop__ *chan*](#8) -[__::imap4::check__ *chan*](#9) -[__::imap4::folderinfo__ *chan* ?*info*?](#10) -[__::imap4::msginfo__ *chan* *msgid* ?*info*? ?*defval*?](#11) -[__::imap4::mboxinfo__ *chan* ?*info*?](#12) -[__::imap4::isableto__ *chan* ?*capability*?](#13) -[__::imap4::create__ *chan* *mailbox*](#14) -[__::imap4::delete__ *chan* *mailbox*](#15) -[__::imap4::rename__ *chan* *oldname* *newname*](#16) -[__::imap4::subscribe__ *chan* *mailbox*](#17) -[__::imap4::unsubscribe__ *chan* *mailbox*](#18) -[__::imap4::search__ *chan* *expr* ?*\.\.\.*?](#19) -[__::imap4::close__ *chan*](#20) -[__::imap4::cleanup__ *chan*](#21) -[__::imap4::debugmode__ *chan* ?*errormsg*?](#22) -[__::imap4::store__ *chan* *range* *data* *flaglist*](#23) -[__::imap4::expunge__ *chan*](#24) -[__::imap4::copy__ *chan* *msgid* *mailbox*](#25) -[__::imap4::logout__ *chan*](#26) - -# DESCRIPTION - -The __imap4__ library package provides the client side of the *Internet -Message Access Protocol* \(IMAP\) using standard sockets or secure connection via -TLS/SSL\. The package is fully implemented in Tcl\. - -This document describes the procedures and explains their usage\. - -# PROCEDURES - -This package defines the following public procedures: - - - __::imap4::open__ *hostname* ?*port*? - - Open a new IMAP connection and initalize the handler, the imap communication - channel \(handler\) is returned\. - - *hostname* \- mail server - - *port* \- connection port, defaults to 143 - - The namespace variable __::imap4::use\_ssl__ can be used to establish to - a secure connection via TSL/SSL if set to true\. In this case default - connection port defaults to 993\. - - *Note:* For connecting via SSL the Tcl module *tls* must be already - loaded otherwise an error is raised\. - - package require tls ; # must be loaded for TLS/SSL - set ::imap4::use_ssl 1 ; # request a secure connection - set chan [::imap4::open $server] ; # default port is now 993 - - - __::imap4::starttls__ *chan* - - Use this when tasked with connecting to an unsecure port which must be - changed to a secure port prior to user login\. This feature is known as - *STARTTLS*\. - - - __::imap4::login__ *chan* *user* *pass* - - Login using the IMAP LOGIN command, 0 is returned on successful login\. - - *chan* \- imap channel - - *user* \- username - - *pass* \- password - - - __::imap4::folders__ *chan* ?*\-inline*? ?*mboxref*? ?*mboxname*? - - Get list of matching folders, 0 is returned on success\. - - Wildcards '\*' as '%' are allowed for *mboxref* and *mboxname*, command - __::imap4::folderinfo__ can be used to retrieve folder information\. - - *chan* \- imap channel - - *mboxref* \- mailbox reference, defaults to "" - - *mboxname* \- mailbox name, defaults to "\*" - - If __\-inline__ is specified a compact folderlist is returned instead of - the result code\. All flags are converted to lowercase and leading special - characters are removed\. - - {{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}} - - - __::imap4::select__ *chan* ?*mailbox*? - - Select a mailbox, 0 is returned on success\. - - *chan* \- imap channel - - *mailbox* \- Path of the mailbox, defaults to *INBOX* - - Prior to examine/select an open mailbox must be closed \- see: - __::imap4::close__\. - - - __::imap4::examine__ *chan* ?*mailbox*? - - "Examines" a mailbox, read\-only equivalent of __::imap4::select__\. - - *chan* \- imap channel - - *mailbox* \- mailbox name or path to mailbox, defaults to *INBOX* - - Prior to examine/select an open mailbox must be closed \- see: - __::imap4::close__\. - - - __::imap4::fetch__ *chan* *range* ?*\-inline*? ?*attr \.\.\.*? - - Fetch attributes from messages\. - - The attributes are fetched and stored in the internal state which can be - retrieved with command __::imap4::msginfo__, 0 is returned on success\. - If __\-inline__ is specified, alle records are returned as list in order - as defined in the *attr* argument\. - - *chan* \- imap channel - - *range* \- message index in format *FROM*:*TO* - - *attr* \- imap attributes to fetch - - *Note:* If *FROM* is omitted, the 1st message is assumed, if *TO* is - ommitted the last message is assumed\. All message index ranges are 1\-based\. - - - __::imap4::noop__ *chan* - - Send NOOP command to server\. May get information as untagged data\. - - *chan* \- imap channel - - - __::imap4::check__ *chan* - - Send CHECK command to server\. Flush to disk\. - - *chan* \- imap channel - - - __::imap4::folderinfo__ *chan* ?*info*? - - Get information on the recently selected folderlist\. If the *info* - argument is omitted or a null string, the full list of information available - for the mailbox is returned\. - - If the required information name is suffixed with a ? character, the command - returns true if the information is available, or false if it is not\. - - *chan* \- imap channel - - *info* \- folderlist options to retrieve - - Currently supported options: *delim* \- hierarchy delimiter only, *match* - \- ref and mbox search patterns \(see __::imap4::folders__\), *names* \- - list of folder names only, *flags* \- list of folder names with flags in - format *\{ \{name \{flags\}\} \.\.\. \}* \(see also compact format in function - __::imap4::folders__\)\. - - {{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}} - - - __::imap4::msginfo__ *chan* *msgid* ?*info*? ?*defval*? - - Get information \(from previously collected using fetch\) from a given - *msgid*\. If the 'info' argument is omitted or a null string, the list of - available information options for the given message is returned\. - - If the required information name is suffixed with a ? character, the command - returns true if the information is available, or false if it is not\. - - *chan* \- imap channel - - *msgid* \- message number - - *info* \- imap keyword to retrieve - - *defval* \- default value, returned if info is empty - - *Note:* All message index ranges are 1\-based\. - - - __::imap4::mboxinfo__ *chan* ?*info*? - - Get information on the currently selected mailbox\. If the *info* argument - is omitted or a null string, the list of available information options for - the mailbox is returned\. - - If the required information name is suffixed with a ? character, the command - returns true if the information is available, or false if it is not\. - - *chan* \- imap channel - - *opt* \- mailbox option to retrieve - - Currently supported options: *EXISTS* \(noof msgs\), *RECENT* \(noof - 'recent' flagged msgs\), *FLAGS* - - In conjunction with OK: *PERMFLAGS*, *UIDNEXT*, *UIDVAL*, *UNSEEN* - - Div\. states: *CURRENT*, *FOUND*, *PERM*\. - - ::imap4::select $chan INBOX - puts "[::imap4::mboxinfo $chan exists] mails in INBOX" - - - __::imap4::isableto__ *chan* ?*capability*? - - Test for capability\. It returns 1 if requested capability is supported, 0 - otherwise\. If *capability* is omitted all capability imap codes are - retured as list\. - - *chan* \- imap channel - - *info* \- imap keyword to retrieve - - *Note:* Use the capability command to ask the server if not already done - by the user\. - - - __::imap4::create__ *chan* *mailbox* - - Create a new mailbox\. - - *chan* \- imap channel - - *mailbox* \- mailbox name - - - __::imap4::delete__ *chan* *mailbox* - - Delete a new mailbox\. - - *chan* \- imap channel - - *mailbox* \- mailbox name - - - __::imap4::rename__ *chan* *oldname* *newname* - - Rename a new mailbox\. - - *chan* \- imap channel - - *mailbox* \- old mailbox name - - *mailbox* \- new mailbox name - - - __::imap4::subscribe__ *chan* *mailbox* - - Subscribe a new mailbox\. - - *chan* \- imap channel - - *mailbox* \- mailbox name - - - __::imap4::unsubscribe__ *chan* *mailbox* - - Unsubscribe a new mailbox\. - - *chan* \- imap channel - - *mailbox* \- mailbox name - - - __::imap4::search__ *chan* *expr* ?*\.\.\.*? - - Search for mails matching search criterions, 0 is returned on success\. - - *chan* \- imap channel - - *expr* \- imap search expression - - *Notes:* Currently the following search expressions are handled: - - *Mail header flags:* all mail header entries \(ending with a colon ":"\), - like "From:", "Bcc:", \.\.\. - - *Imap message search flags:* ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, - SEEN, NEW, OLD, UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, UNSEEN, ALL - - *Imap header search flags:* BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC - - *Imap conditional search flags:* SMALLER, LARGER, ON, SENTBEFORE, SENTON, - SENTSINCE, SINCE, BEFORE \(not implemented\), UID \(not implemented\) - - *Logical search conditions:* OR, NOT - - ::imap4::search $chan larger 4000 seen - puts "Found messages: [::imap4::mboxinfo $chan found]" - Found messages: 1 3 6 7 8 9 13 14 15 19 20 - - - __::imap4::close__ *chan* - - Close the mailbox\. Permanently removes \\Deleted messages and return to the - AUTH state\. - - *chan* \- imap channel - - - __::imap4::cleanup__ *chan* - - Destroy an IMAP connection and free the used space\. Close the mailbox\. - Permanently removes \\Deleted messages and return to the AUTH state\. - - *chan* \- imap channel - - - __::imap4::debugmode__ *chan* ?*errormsg*? - - Switch client into command line debug mode\. - - This is a developers mode only that pass the control to the programmer\. - Every line entered is sent verbatim to the server \(after the addition of the - request identifier\)\. The ::imap4::debug variable is automatically set to '1' - on enter\. - - It's possible to execute Tcl commands starting the line with a slash\. - - *chan* \- imap channel - - *errormsg* \- optional error message to display - - - __::imap4::store__ *chan* *range* *data* *flaglist* - - Alters data associated with a message in the selected mailbox\. - - *chan* \- imap channel - - *range* \- message index in format *FROM*:*TO* - - *flaglist* \- Flags the *data* operates on\. - - *data* \- The currently defined *data* items that can be stored are shown - below\. *Note* that all of these data types may also be suffixed with - "\.SILENT" to suppress the untagged FETCH response\. - - * FLAGS - - Replace the flags for the message \(other than \\Recent\) with the - *flaglist*\. - - * \+FLAGS - - Add the flags in *flaglist* to the existing flags for the message\. - - * \-FLAGS - - Remove the flags in *flaglist* to the existing flags for the message\. - - For example: - - ::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted" - - - __::imap4::expunge__ *chan* - - Permanently removes all messages that have the \\Deleted flag set from the - currently selected mailbox, without the need to close the connection\. - - *chan* \- imap channel - - - __::imap4::copy__ *chan* *msgid* *mailbox* - - Copies the specified message \(identified by its message number\) to the named - mailbox, i\.e\. imap folder\. - - *chan* \- imap channel - - *msgid* \- message number - - *mailbox* \- mailbox name - - - __::imap4::logout__ *chan* - - Informs the server that the client is done with the connection and closes - the network connection\. Permanently removes \\Deleted messages\. - - A new connection will need to be established to login once more\. - - *chan* \- imap channel - -# EXAMPLES - - set user myusername - set pass xtremescrt - set server imap.test.tld - set FOLDER INBOX - # Connect to server - set imap [::imap4::open $server] - ::imap4::login $imap $user $pass - ::imap4::select $imap $FOLDER - # Output all the information about that mailbox - foreach info [::imap4::mboxinfo $imap] { - puts "$info -> [::imap4::mboxinfo $imap $info]" - } - # fetch 3 records inline - set fields {from: to: subject: size} - foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] { - puts -nonewline "#[incr idx])" - for {set j 0} {$j<[llength $fields]} {incr j} { - puts "\t[lindex $fields $j] [lindex $rec $j]" - } - } - - # Show all the information available about the message ID 1 - puts "Available info about message 1: [::imap4::msginfo $imap 1]" - - # Use the capability stuff - puts "Capabilities: [::imap4::isableto $imap]" - puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]" - - # Cleanup - ::imap4::cleanup $imap - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# REFERENCES - -Mark R\. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL \- VERSION 4rev1", RFC 3501, -March 2003, -[http://www\.rfc\-editor\.org/rfc/rfc3501\.txt](http://www\.rfc\-editor\.org/rfc/rfc3501\.txt) - -OpenSSL, [http://www\.openssl\.org/](http://www\.openssl\.org/) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *imap4* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. Only a small part of rfc3501 implemented\. - -# SEE ALSO - -[ftp](\.\./ftp/ftp\.md), [http](\.\./\.\./\.\./\.\./index\.md\#http), -[imap](\.\./\.\./\.\./\.\./index\.md\#imap), [mime](\.\./mime/mime\.md), -[pop3](\.\./pop3/pop3\.md), [tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# KEYWORDS - -[email](\.\./\.\./\.\./\.\./index\.md\#email), [imap](\.\./\.\./\.\./\.\./index\.md\#imap), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[mail](\.\./\.\./\.\./\.\./index\.md\#mail), [net](\.\./\.\./\.\./\.\./index\.md\#net), -[rfc3501](\.\./\.\./\.\./\.\./index\.md\#rfc3501), -[ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), [tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/inifile/ini.md Index: embedded/md/tcllib/files/modules/inifile/ini.md ================================================================== --- embedded/md/tcllib/files/modules/inifile/ini.md +++ embedded/md/tcllib/files/modules/inifile/ini.md @@ -1,150 +0,0 @@ - -[//000000001]: # (inifile \- Parsing of Windows INI files) -[//000000002]: # (Generated from file 'ini\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (inifile\(n\) 0\.3\.2 tcllib "Parsing of Windows INI files") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -inifile \- Parsing of Windows INI files - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require inifile ?0\.3\.2? - -[__::ini::open__ *file* ?__\-encoding__ *encoding*? ?*access*?](#1) -[__::ini::close__ *ini*](#2) -[__::ini::commit__ *ini*](#3) -[__::ini::revert__ *ini*](#4) -[__::ini::filename__ *ini*](#5) -[__::ini::sections__ *ini*](#6) -[__::ini::keys__ *ini* *section*](#7) -[__::ini::get__ *ini* *section*](#8) -[__::ini::exists__ *ini* *section* ?*key*?](#9) -[__::ini::value__ *ini* *section* *key* ?*default*?](#10) -[__::ini::set__ *ini* *section* *key* *value*](#11) -[__::ini::delete__ *ini* *section* ?*key*?](#12) -[__::ini::comment__ *ini* *section* ?*key*? ?*text*?](#13) -[__::ini::commentchar__ ?char?](#14) - -# DESCRIPTION - -This package provides an interface for easy manipulation of Windows INI files\. - - - __::ini::open__ *file* ?__\-encoding__ *encoding*? ?*access*? - - Opens an INI file and returns a handle that is used by other commands\. - *access* is the same as the first form \(non POSIX\) of the __open__ - command, with the exception that mode __a__ is not supported\. The - default mode is __r\+__\. - - The default *encoding* is the system encoding\. - - - __::ini::close__ *ini* - - Close the specified handle\. If any changes were made and not written by - __commit__ they are lost\. - - - __::ini::commit__ *ini* - - Writes the file and all changes to disk\. The sections are written in - arbitrary order\. The keys in a section are written in alphabetical order\. If - the ini was opened in read only mode an error will be thrown\. - - - __::ini::revert__ *ini* - - Rolls all changes made to the inifile object back to the last committed - state\. - - - __::ini::filename__ *ini* - - Returns the name of the file the *ini* object is associated with\. - - - __::ini::sections__ *ini* - - Returns a list of all the names of the existing sections in the file handle - specified\. - - - __::ini::keys__ *ini* *section* - - Returns a list of all they key names in the section and file specified\. - - - __::ini::get__ *ini* *section* - - Returns a list of key value pairs that exist in the section and file - specified\. - - - __::ini::exists__ *ini* *section* ?*key*? - - Returns a boolean value indicating the existance of the specified section as - a whole or the specified key within that section\. - - - __::ini::value__ *ini* *section* *key* ?*default*? - - Returns the value of the named key and section\. If specified, the default - value will be returned if the key does not exist\. If the key does not exist - and no default is specified an error will be thrown\. - - - __::ini::set__ *ini* *section* *key* *value* - - Sets the value of the key in the specified section\. If the section does not - exist then a new one is created\. - - - __::ini::delete__ *ini* *section* ?*key*? - - Removes the key or the entire section and all its keys\. A section is not - automatically deleted when it has no remaining keys\. - - - __::ini::comment__ *ini* *section* ?*key*? ?*text*? - - Reads and modifies comments for sections and keys\. To write a section - comment use an empty string for the *key*\. To remove all comments use an - empty string for *text*\. *text* may consist of a list of lines or one - single line\. Any embedded newlines in *text* are properly handled\. - Comments may be written to nonexistant sections or keys and will not return - an error\. Reading a comment from a nonexistant section or key will return an - empty string\. - - - __::ini::commentchar__ ?char? - - Reads and sets the comment character\. Lines that begin with this character - are treated as comments\. When comments are written out each line is preceded - by this character\. The default is __;__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *inifile* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/interp/deleg_method.md Index: embedded/md/tcllib/files/modules/interp/deleg_method.md ================================================================== --- embedded/md/tcllib/files/modules/interp/deleg_method.md +++ embedded/md/tcllib/files/modules/interp/deleg_method.md @@ -1,96 +0,0 @@ - -[//000000001]: # (deleg\_method \- Interpreter utilities) -[//000000002]: # (Generated from file 'deleg\_method\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (deleg\_method\(n\) 0\.2 tcllib "Interpreter utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -deleg\_method \- Creation of comm delegates \(snit methods\) - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require snit ?1\.1? -package require interp::delegate::method ?0\.2? - -[__::interp::delegate::method__ ?__\-async__? *name* *arguments* *comm* *id*](#1) - -# DESCRIPTION - -This package provides a single command for use within -__[snit](\.\./snit/snit\.md)__ type definition \(i\.e\. actually a -__snit::macro__\) for the convenient creation of methods which delegate the -actual work to a remote location via a "channel" created by the package -__[comm](\.\./comm/comm\.md)__\. - -# API - - - __::interp::delegate::method__ ?__\-async__? *name* *arguments* *comm* *id* - - This commands creates a method which is named by *name*\. All invokations - of this method will delegate the actual work to the remote location - identified by the comm channel *comm* and the endpoint *id*\. - - The name of the remote method invoked by the delegator is identical to the - name of the method itself\. - - Normally the generated method marshalls the *arguments*, and returns the - result from the remote method as its own result\. If however the option - __\-async__ was specified then the generated method will not wait for a - result and return immediately\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *interp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[comm](\.\./\.\./\.\./\.\./index\.md\#comm), -[delegation](\.\./\.\./\.\./\.\./index\.md\#delegation), -[interpreter](\.\./\.\./\.\./\.\./index\.md\#interpreter), -[method](\.\./\.\./\.\./\.\./index\.md\#method), [snit](\.\./\.\./\.\./\.\./index\.md\#snit) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/interp/deleg_proc.md Index: embedded/md/tcllib/files/modules/interp/deleg_proc.md ================================================================== --- embedded/md/tcllib/files/modules/interp/deleg_proc.md +++ embedded/md/tcllib/files/modules/interp/deleg_proc.md @@ -1,94 +0,0 @@ - -[//000000001]: # (deleg\_proc \- Interpreter utilities) -[//000000002]: # (Generated from file 'deleg\_proc\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (deleg\_proc\(n\) 0\.2 tcllib "Interpreter utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -deleg\_proc \- Creation of comm delegates \(procedures\) - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require interp::delegate::proc ?0\.2? - -[__::interp::delegate::proc__ ?__\-async__? *name* *arguments* *comm* *id*](#1) - -# DESCRIPTION - -This package provides a single command for the convenient creation of procedures -which delegate the actual work to a remote location via a "channel" created by -the package __[comm](\.\./comm/comm\.md)__\. - -# API - - - __::interp::delegate::proc__ ?__\-async__? *name* *arguments* *comm* *id* - - This commands creates a procedure which is named by *name* and returns its - fully\-qualified name\. All invokations of this procedure will delegate the - actual work to the remote location identified by the comm channel *comm* - and the endpoint *id*\. - - The name of the remote procedure invoked by the delegator is \[namespace tail - *name*\]\. I\.e\., namespace information is stripped from the call\. - - Normally the generated procedure marshalls the *arguments*, and returns - the result from the remote procedure as its own result\. If however the - option __\-async__ was specified then the generated procedure will not - wait for a result and return immediately\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *interp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[comm](\.\./\.\./\.\./\.\./index\.md\#comm), -[delegation](\.\./\.\./\.\./\.\./index\.md\#delegation), -[interpreter](\.\./\.\./\.\./\.\./index\.md\#interpreter), -[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/interp/tcllib_interp.md Index: embedded/md/tcllib/files/modules/interp/tcllib_interp.md ================================================================== --- embedded/md/tcllib/files/modules/interp/tcllib_interp.md +++ embedded/md/tcllib/files/modules/interp/tcllib_interp.md @@ -1,112 +0,0 @@ - -[//000000001]: # (interp \- Interpreter utilities) -[//000000002]: # (Generated from file 'tcllib\_interp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (interp\(n\) 0\.1\.2 tcllib "Interpreter utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -interp \- Interp creation and aliasing - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require interp ?0\.1\.2? - -[__::interp::createEmpty__ ?*path*?](#1) -[__::interp::snitLink__ *path* *methodlist*](#2) -[__::interp::snitDictLink__ *path* *methoddict*](#3) - -# DESCRIPTION - -This package provides a number of commands for the convenient creation of Tcl -interpreters for highly restricted execution\. - -# API - - - __::interp::createEmpty__ ?*path*? - - This commands creates an empty Tcl interpreter and returns it name\. Empty - means that the new interpreter has neither namespaces, nor any commands\. It - is useful only for the creation of aliases\. - - If a *path* is specified then it is taken as the name of the new - interpreter\. - - - __::interp::snitLink__ *path* *methodlist* - - This command assumes that it was called from within a method of a snit - object, and that the command __mymethod__ is available\. - - It extends the interpreter specified by *path* with aliases for all - methods found in the *methodlist*, with the alias directing execution to - the same\-named method of the snit object invoking this command\. Each element - of *methodlist* is actually interpreted as a command prefix, with the - first word of each prefix the name of the method to link to\. - - The result of the command is the empty string\. - - - __::interp::snitDictLink__ *path* *methoddict* - - This command behaves like __::interp::snitLink__, except that it takes a - dictionary mapping from commands to methods as its input, and not a list of - methods\. Like for __::interp::snitLink__ the method references are - actually command prefixes\. This command allows the creation of more complex - command\-method mappings than __::interp::snitLink__\. - - The result of the command is the empty string\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *interp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[alias](\.\./\.\./\.\./\.\./index\.md\#alias), [empty -interpreter](\.\./\.\./\.\./\.\./index\.md\#empty\_interpreter), -[interpreter](\.\./\.\./\.\./\.\./index\.md\#interpreter), -[method](\.\./\.\./\.\./\.\./index\.md\#method), [snit](\.\./\.\./\.\./\.\./index\.md\#snit) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/irc/irc.md Index: embedded/md/tcllib/files/modules/irc/irc.md ================================================================== --- embedded/md/tcllib/files/modules/irc/irc.md +++ embedded/md/tcllib/files/modules/irc/irc.md @@ -1,308 +0,0 @@ - -[//000000001]: # (irc \- Low Level Tcl IRC Interface) -[//000000002]: # (Generated from file 'irc\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (irc\(n\) 0\.7\.0 tcllib "Low Level Tcl IRC Interface") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -irc \- Create IRC connection and interface\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Per\-connection Commands](#section2) - - - [Callback Commands](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.6 -package require irc ?0\.7\.0? - -[__::irc::config__ ?key? ?value?](#1) -[__::irc::connection__](#2) -[__::irc::connections__](#3) -[*net* __registerevent__ *event* *script*](#4) -[*net* __getevent__ *event* *script*](#5) -[*net* __eventexists__ *event* *script*](#6) -[*net* __connect__ *hostname* ?port?](#7) -[*net* __config__ ?key? ?value?](#8) -[*net* __log__ *level* *message*](#9) -[*net* __logname__](#10) -[*net* __connected__](#11) -[*net* __sockname__](#12) -[*net* __peername__](#13) -[*net* __socket__](#14) -[*net* __user__ *username* *localhostname* *localdomainname* *userinfo*](#15) -[*net* __nick__ *nick*](#16) -[*net* __ping__ *target*](#17) -[*net* __serverping__](#18) -[*net* __join__ *channel* ?*key*?](#19) -[*net* __part__ *channel* ?*message*?](#20) -[*net* __quit__ ?*message*?](#21) -[*net* __privmsg__ *target* *message*](#22) -[*net* __notice__ *target* *message*](#23) -[*net* __ctcp__ *target* *message*](#24) -[*net* __kick__ *channel* *target* ?*message*?](#25) -[*net* __mode__ *target* *args*](#26) -[*net* __topic__ *channel* *message*](#27) -[*net* __invite__ *channel* *target*](#28) -[*net* __send__ *text*](#29) -[*net* __destroy__](#30) -[__who__ ?__address__?](#31) -[__action__](#32) -[__target__](#33) -[__additional__](#34) -[__header__](#35) -[__msg__](#36) - -# DESCRIPTION - -This package provides low\-level commands to deal with the IRC protocol \(Internet -Relay Chat\) for immediate and interactive multi\-cast communication\. - - - __::irc::config__ ?key? ?value? - - Sets configuration ?key? to ?value?\. The configuration keys currently - defined are the boolean flags __logger__ and __debug__\. - __logger__ makes __irc__ use the logger package for printing error\. - __debug__ requires __logger__ and prints extra debug output\. If no - ?key? or ?value? is given the current values are returned\. - - - __::irc::connection__ - - The command creates a new object to deal with an IRC connection\. Creating - this IRC object does not automatically create the network connection\. It - returns a new irc namespace command which can be used to interact with the - new IRC connection\. NOTE: the old form of the connection command, which took - a hostname and port as arguments, is deprecated\. Use __connect__ instead - to specify this information\. - - - __::irc::connections__ - - Returns a list of all the current connections that were created with - __connection__ - -# Per\-connection Commands - -In the following list of available connection methods *net* represents a -connection command as returned by __::irc::connection__\. - - - *net* __registerevent__ *event* *script* - - Registers a callback handler for the specific event\. Events available are - those described in RFC 1459 - [http://www\.rfc\-editor\.org/rfc/rfc1459\.txt](http://www\.rfc\-editor\.org/rfc/rfc1459\.txt)\. - In addition, there are several other events defined\. __defaultcmd__ adds - a command that is called if no other callback is present\. __EOF__ is - called if the connection signals an End of File condition\. The events - __defaultcmd__, __defaultnumeric__, __defaultevent__, and - __EOF__ are required\. *script* is executed in the connection - namespace, which can take advantage of several commands \(see [Callback - Commands](#section3) below\) to aid in the parsing of data\. - - - *net* __getevent__ *event* *script* - - Returns the current handler for the event if one exists\. Otherwise an empty - string is returned\. - - - *net* __eventexists__ *event* *script* - - Returns a boolean value indicating the existence of the event handler\. - - - *net* __connect__ *hostname* ?port? - - This causes the socket to be established\. __::irc::connection__ created - the namespace and the commands to be used, but did not actually open the - socket\. This is done here\. NOTE: the older form of 'connect' did not require - the user to specify a hostname and port, which were specified with - 'connection'\. That form is deprecated\. - - - *net* __config__ ?key? ?value? - - The same as __::irc::config__ but sets and gets options for the *net* - connection only\. - - - *net* __log__ *level* *message* - - If logger is turned on by __config__ this will write a log *message* - at *level*\. - - - *net* __logname__ - - Returns the name of the logger instance if logger is turned on\. - - - *net* __connected__ - - Returns a boolean value indicating if this connection is connected to a - server\. - - - *net* __sockname__ - - Returns a 3 element list consisting of the ip address, the hostname, and the - port of the local end of the connection, if currently connected\. - - - *net* __peername__ - - Returns a 3 element list consisting of the ip address, the hostname, and the - port of the remote end of the connection, if currently connected\. - - - *net* __socket__ - - Return the Tcl channel for the socket used by the connection\. - - - *net* __user__ *username* *localhostname* *localdomainname* *userinfo* - - Sends USER command to server\. *username* is the username you want to - appear\. *localhostname* is the host portion of your hostname, - *localdomainname* is your domain name, and *userinfo* is a short - description of who you are\. The 2nd and 3rd arguments are normally ignored - by the IRC server\. - - - *net* __nick__ *nick* - - NICK command\. *nick* is the nickname you wish to use for the particular - connection\. - - - *net* __ping__ *target* - - Send a CTCP PING to *target*\. - - - *net* __serverping__ - - PING the server\. - - - *net* __join__ *channel* ?*key*? - - *channel* is the IRC channel to join\. IRC channels typically begin with a - hashmark \("\#"\) or ampersand \("&"\)\. - - - *net* __part__ *channel* ?*message*? - - Makes the client leave *channel*\. Some networks may support the optional - argument *message* - - - *net* __quit__ ?*message*? - - Instructs the IRC server to close the current connection\. The package will - use a generic default if no *message* was specified\. - - - *net* __privmsg__ *target* *message* - - Sends *message* to *target*, which can be either a channel, or another - user, in which case their nick is used\. - - - *net* __notice__ *target* *message* - - Sends a __notice__ with message *message* to *target*, which can be - either a channel, or another user, in which case their nick is used\. - - - *net* __ctcp__ *target* *message* - - Sends a CTCP of type *message* to *target* - - - *net* __kick__ *channel* *target* ?*message*? - - Kicks the user *target* from the channel *channel* with a *message*\. - The latter can be left out\. - - - *net* __mode__ *target* *args* - - Sets the mode *args* on the target *target*\. *target* may be a - channel, a channel user, or yourself\. - - - *net* __topic__ *channel* *message* - - Sets the topic on *channel* to *message* specifying an empty string will - remove the topic\. - - - *net* __invite__ *channel* *target* - - Invites *target* to join the channel *channel* - - - *net* __send__ *text* - - Sends *text* to the IRC server\. - - - *net* __destroy__ - - Deletes the connection and its associated namespace and information\. - -# Callback Commands - -These commands can be used within callbacks - - - __who__ ?__address__? - - Returns the nick of the user who performed a command\. The optional keyword - __address__ causes the command to return the user in the format - "username@address"\. - - - __action__ - - Returns the action performed, such as KICK, PRIVMSG, MODE, etc\.\.\. Normally - not useful, as callbacks are bound to a particular event\. - - - __target__ - - Returns the target of a particular command, such as the channel or user to - whom a PRIVMSG is sent\. - - - __additional__ - - Returns a list of any additional arguments after the target\. - - - __header__ - - Returns the entire event header \(everything up to the :\) as a proper list\. - - - __msg__ - - Returns the message portion of the command \(the part after the :\)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *irc* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -rfc 1459 - -# KEYWORDS - -[chat](\.\./\.\./\.\./\.\./index\.md\#chat), [irc](\.\./\.\./\.\./\.\./index\.md\#irc) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/irc/picoirc.md Index: embedded/md/tcllib/files/modules/irc/picoirc.md ================================================================== --- embedded/md/tcllib/files/modules/irc/picoirc.md +++ embedded/md/tcllib/files/modules/irc/picoirc.md @@ -1,201 +0,0 @@ - -[//000000001]: # (picoirc \- Simple embeddable IRC interface) -[//000000002]: # (Generated from file 'picoirc\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (picoirc\(n\) 0\.7\.0 tcllib "Simple embeddable IRC interface") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -picoirc \- Small and simple embeddable IRC client\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [CALLBACK](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.6 -package require picoirc ?0\.7\.0? - -[__::picoirc::connect__ *callback* *nick* ?*password*? *url*](#1) -[__::picoirc::post__ *context* *channel* *message*](#2) -[__::picoirc::splituri__ *uri*](#3) -[__::picoirc::send__ *context* *line*](#4) - -# DESCRIPTION - -This package provides a general purpose minimal IRC client suitable for -embedding in other applications\. All communication with the parent application -is done via an application provided callback procedure\. Each connection has its -own state so you can hook up multiple servers in a single application instance\. - -To initiate an IRC connection you must call __picoirc::connect__ with a -callback procedure, a nick\-name to use on IRC and the IRC URL that describes the -connection\. This will return a variable name that is the irc connection context\. -See [CALLBACK](#section3) for details\. - -This package is a fairly simple IRC client\. If you need something with more -capability investigate the __[irc](irc\.md)__ package\. - -# COMMANDS - - - __::picoirc::connect__ *callback* *nick* ?*password*? *url* - - Creates a new irc connection to the server specified by *url* and login - using the *nick* as the username and optionally *password*\. If the - *url* starts with *ircs://* then a TLS connection is created\. The - *callback* must be as specified in [CALLBACK](#section3)\. Returns a - package\-specific variable that is used when calling other commands in this - package\. - - *Note:* For connecting via TLS the Tcl module *tls* must be already - loaded, otherwise an error is raised\. - - # must be loaded for TLS - package require tls - # default arguments - tls::init -autoservername true -command workaround \ - -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1.1 0 - # avoid annoying bgerror, errors are already catched internally - proc workaround {state args} { - if {$state == "verify"} { - return [lindex $args 3] - } - } - - - __::picoirc::post__ *context* *channel* *message* - - This should be called to process user input and send it to the server\. A - number of commands are recognised when prefixed with a forward\-slash \(/\)\. - Such commands are converted to IRC command sequences and then sent\. - - - __::picoirc::splituri__ *uri* - - Splits an IRC scheme uniform resource indicator into its component parts\. - Returns a list of server, port, channel and secure where secure is a boolean - flag which is __true__ if a TLS connection was requested via the - *ircs://* schema\. The default port is 6667 \(or 6697 if secured\) and there - is no default channel\. - - - __::picoirc::send__ *context* *line* - - This command is where all raw output to the server is handled\. The default - action is to write the *line* to the irc socket\. However, before this - happens the callback is called with "debug write"\. This permits the - application author to inspect the raw IRC data and if desired to return a - break error code to halt further processing\. In this way the application can - override the default send via the callback procedure\. - -# CALLBACK - -The callback must look like: - - proc Callback {context state args} { - } - -where context is the irc context variable name \(in case you need to pass it back -to a picoirc procedure\)\. state is one of a number of states as described below\. - - - __init__ - - called just before the socket is created - - - __connect__ - - called once we have connected, before we join any channels - - - __close__ - - called when the socket gets closed, before the context is deleted\. If an - error occurs before we get connected the only argument will be the socket - error message\. - - - __userlist__ *channel* *nicklist* - - called to notify the application of an updated userlist\. This is generated - when the output of the NAMES irc command is seen\. The package collects the - entire output which can span a number of output lines from the server and - calls this callback when they have all been received\. - - - __chat__ *target* *nick* *message* *type* - - called when a message arrives\. *target* is the identity that the message - was targetted for\. This can be the logged in nick or a channel name\. - *nick* is the name of the sender of the message\. *message* is the - message text\. *type* is set to "ACTION" if the message was sent as a CTCP - ACTION - - - __system__ *channel* *message* - - called when a system message is received - - - __topic__ *channel* *topic* - - called when the channel topic string is seen\. *topic* is the text of the - channel topic\. - - - __traffic__ *action* *channel* *nick* ?*newnick*? - - called when users join, leave or change names\. *action* is either entered, - left or nickchange and *nick* is the user doing the action\. *newnick* is - the new name if *action* is nickchange\. - - *NOTE*: *channel* is often empty for these messages as nick activities - are global for the irc server\. You will have to manage the nick for all - connected channels yourself\. - - - __version__ - - This is called to request a version string to use to override the internal - version\. If implemented, you should return as colon delimited string as - - Appname:Appversion:LibraryVersion - - For example, the default is - - PicoIRC:\[package provide picoirc\]:Tcl \[info patchlevel\] - - - __debug__ *type* *raw* - - called when data is either being read or written to the network socket\. - *type* is set to __read__ when reading data and __write__ if the - data is to be written\. *raw* is the unprocessed IRC protocol data\. - - In both cases the application can return a break error code to interrupt - further processing of the raw data\. If this is a __read__ operation then - the package will not handle this line\. If the operation is __write__ - then the package will not send the data\. This callback is intended for - debugging protocol issues but could be used to redirect all input and output - if desired\. - -# SEE ALSO - -rfc 1459 - -# KEYWORDS - -[chat](\.\./\.\./\.\./\.\./index\.md\#chat), [irc](\.\./\.\./\.\./\.\./index\.md\#irc) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/javascript/javascript.md Index: embedded/md/tcllib/files/modules/javascript/javascript.md ================================================================== --- embedded/md/tcllib/files/modules/javascript/javascript.md +++ embedded/md/tcllib/files/modules/javascript/javascript.md @@ -1,139 +0,0 @@ - -[//000000001]: # (javascript \- HTML and Java Script Generation) -[//000000002]: # (Generated from file 'javascript\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (javascript\(n\) 1\.0\.2 tcllib "HTML and Java Script Generation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -javascript \- Procedures to generate HTML and Java Script structures\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8 -package require javascript ?1\.0\.2? - -[__::javascript::makeSelectorWidget__ *id leftLabel leftValueList rightLabel rightValueList rightNameList* ?*length*? ?*minWidth*?](#1) -[__::javascript::makeSubmitButton__ *name value*](#2) -[__::javascript::makeProtectedSubmitButton__ *name value msg*](#3) -[__::javascript::makeMasterButton__ *master value slavePattern boolean*](#4) -[__::javascript::makeParentCheckbox__ *parentName childName*](#5) -[__::javascript::makeChildCheckbox__ *parentName childName*](#6) - -# DESCRIPTION - -The __::javascript__ package provides commands that generate HTML and Java -Script code\. These commands typically return an HTML string as their result\. In -particular, they do not output their result to __stdout__\. - - - __::javascript::makeSelectorWidget__ *id leftLabel leftValueList rightLabel rightValueList rightNameList* ?*length*? ?*minWidth*? - - Construct HTML code to create a dual\-multi\-selection megawidget\. This - megawidget consists of two side\-by\-side multi\-selection boxes separated by a - left arrow and a right arrow button\. The right arrow button moves all items - selected in the left box to the right box\. The left arrow button moves all - items selected in the right box to the left box\. The *id* argument is the - suffix of all HTML objects in this megawidget\. The *leftLabel* argument is - the text that appears above the left selection box\. The *leftValueList* - argument is the values of items in the left selection box\. The - *leftNameList* argument is the names to appear in the left selection box\. - The *rightLabel* argument is the text that appears above the right - selection box\. The *rightValueList* argument is the values of items in the - right selection box\. The *rightNameList* argument is the names to appear - in the right selection box\. The *length* argument \(optional\) determines - the number of elts to show before adding a vertical scrollbar; it defaults - to 8\. The *minWidth* argument \(optional\) is the number of spaces to - determine the minimum box width; it defaults to 32\. - - - __::javascript::makeSubmitButton__ *name value* - - Create an HTML submit button that resets a hidden field for each registered - multi\-selection box\. The *name* argument is the name of the HTML button - object to create\. The *value* argument is the label of the HTML button - object to create\. - - - __::javascript::makeProtectedSubmitButton__ *name value msg* - - Create an HTML submit button that prompts the user with a continue/cancel - shutdown warning before the form is submitted\. The *name* argument is the - name of the HTML button object to create\. The *value* argument is the - label of the HTML button object to create\. The *msg* argument is the - message to display when the button is pressed\. - - - __::javascript::makeMasterButton__ *master value slavePattern boolean* - - Create an HTML button that sets its slave checkboxs to the boolean value\. - The *master* argument is the name of the child's parent html checkbox - object\. The *value* argument is the value of the master\. The *slaves* - argument is the name of child html checkbox object to create\. The - *boolean* argument is the java script boolean value that will be given to - all the slaves; it must be "true" or "false"\. - - - __::javascript::makeParentCheckbox__ *parentName childName* - - Create an HTML checkbox and tie its value to that of its child checkbox\. If - the parent is unchecked, the child is automatically unchecked\. The - *parentName* argument is the name of parent html checkbox object to - create\. The *childName* argument is the name of the parent's child html - checkbox object\. - - - __::javascript::makeChildCheckbox__ *parentName childName* - - Create an HTML checkbox and tie its value to that of its parent checkbox\. If - the child is checked, the parent is automatically checked\. The - *parentName* argument is the name of the child's parent html checkbox - object\. The *childName* argument is the name of child html checkbox object - to create\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *javascript* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[html](\.\./html/html\.md), [ncgi](\.\./ncgi/ncgi\.md) - -# KEYWORDS - -[checkbox](\.\./\.\./\.\./\.\./index\.md\#checkbox), -[html](\.\./\.\./\.\./\.\./index\.md\#html), -[javascript](\.\./\.\./\.\./\.\./index\.md\#javascript), -[selectionbox](\.\./\.\./\.\./\.\./index\.md\#selectionbox), -[submitbutton](\.\./\.\./\.\./\.\./index\.md\#submitbutton) - -# CATEGORY - -CGI programming DELETED embedded/md/tcllib/files/modules/jpeg/jpeg.md Index: embedded/md/tcllib/files/modules/jpeg/jpeg.md ================================================================== --- embedded/md/tcllib/files/modules/jpeg/jpeg.md +++ embedded/md/tcllib/files/modules/jpeg/jpeg.md @@ -1,232 +0,0 @@ - -[//000000001]: # (jpeg \- JPEG image manipulation) -[//000000002]: # (Generated from file 'jpeg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2005, Code: Aaron Faupell ) -[//000000004]: # (Copyright © 2007, Code: Andreas Kupries ) -[//000000005]: # (Copyright © 2004\-2009, Doc: Andreas Kupries ) -[//000000006]: # (Copyright © 2011, Code: Pat Thoyts ) -[//000000007]: # (jpeg\(n\) 0\.5 tcllib "JPEG image manipulation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -jpeg \- JPEG querying and manipulation of meta data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [LIMITATIONS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require jpeg ?0\.5? - -[__::jpeg::isJPEG__ *file*](#1) -[__::jpeg::imageInfo__ *file*](#2) -[__::jpeg::dimensions__ *file*](#3) -[__::jpeg::getThumbnail__ *file*](#4) -[__::jpeg::getExif__ *file* ?*section*?](#5) -[__::jpeg::getExifFromChannel__ *channel* ?*section*?](#6) -[__::jpeg::formatExif__ *keys*](#7) -[__::jpeg::exifKeys__](#8) -[__::jpeg::removeExif__ *file*](#9) -[__::jpeg::stripJPEG__ *file*](#10) -[__::jpeg::getComments__ *file*](#11) -[__::jpeg::addComment__ *file* *text*\.\.\.](#12) -[__::jpeg::removeComments__ *file*](#13) -[__::jpeg::replaceComment__ *file* *text*](#14) -[__::jpeg::debug__ *file*](#15) -[__::jpeg::markers__ *channel*](#16) - -# DESCRIPTION - -This package provides commands to query and modify JPEG images\. JPEG stands for -*Joint Photography Experts Group* and is a standard for the lossy compression -of photographical images\. It is specified at [LINK\_HERE](LINK\_HERE)\. - -# COMMANDS - - - __::jpeg::isJPEG__ *file* - - Returns a boolean value indicating if *file* is a JPEG image\. - - - __::jpeg::imageInfo__ *file* - - Returns a dictionary with keys __version__, __units__, - __xdensity__, __ydensity__, __xthumb__, and __ythumb__\. The - values are the associated properties of the JPEG image in *file*\. Throws - an error if *file* is not a JPEG image\. - - - __::jpeg::dimensions__ *file* - - Returns the dimensions of the JPEG *file* as a list of the horizontal and - vertical pixel count\. Throws an error if *file* is not a JPEG image\. - - - __::jpeg::getThumbnail__ *file* - - This procedure will return the binary thumbnail image data, if a JPEG - thumbnail is included in *file*, and the empty string otherwise\. Note that - it is possible to include thumbnails in formats other than JPEG although - that is not common\. The command finds thumbnails that are encoded in either - the JFXX or EXIF segments of the JPEG information\. If both are present the - EXIF thumbnail will take precedence\. Throws an error if *file* is not a - JPEG image\. - - set fh [open thumbnail.jpg w+] - fconfigure $fh -translation binary -encoding binary - puts -nonewline $fh [::jpeg::getThumbnail photo.jpg] - close $fh - - - __::jpeg::getExif__ *file* ?*section*? - - *section* must be one of __main__ or __thumbnail__\. The default is - __main__\. Returns a dictionary containing the EXIF information for the - specified section\. For example: - - set exif { - Make Canon - Model {Canon DIGITAL IXUS} - DateTime {2001:06:09 15:17:32} - } - - Throws an error if *file* is not a JPEG image\. - - - __::jpeg::getExifFromChannel__ *channel* ?*section*? - - This command is as per __::jpeg::getExif__ except that it uses a - previously opened channel\. *channel* should be a seekable channel and - *section* is as described in the documentation of __::jpeg::getExif__\. - - *Note*: The jpeg parser expects that the start of the channel is the start - of the image data\. If working with an image embedded in a container file - format it may be necessary to read the jpeg data into a temporary container: - either a temporary file or a memory channel\. - - *Attention*: It is the resonsibility of the caller to close the channel - after its use\. - - - __::jpeg::formatExif__ *keys* - - Takes a list of key\-value pairs as returned by __getExif__ and formats - many of the values into a more human readable form\. As few as one key\-value - may be passed in, the entire exif is not required\. - - foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] { - puts "$key: $val" - } - - array set exif [::jpeg::getExif photo.jpg] - puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]] - - - __::jpeg::exifKeys__ - - Returns a list of the EXIF keys which are currently understood\. There may be - keys present in __getExif__ data that are not understood\. Those keys - will appear in a 4 digit hexadecimal format\. - - - __::jpeg::removeExif__ *file* - - Removes the Exif data segment from the specified file and replaces it with a - standard JFIF segment\. Throws an error if *file* is not a JPEG image\. - - - __::jpeg::stripJPEG__ *file* - - Removes all metadata from the JPEG file leaving only the image\. This - includes comments, EXIF segments, JFXX segments, and application specific - segments\. Throws an error if *file* is not a JPEG image\. - - - __::jpeg::getComments__ *file* - - Returns a list containing all the JPEG comments found in the *file*\. - Throws an error if *file* is not a valid JPEG image\. - - - __::jpeg::addComment__ *file* *text*\.\.\. - - Adds one or more plain *text* comments to the JPEG image in *file*\. - Throws an error if *file* is not a valid JPEG image\. - - - __::jpeg::removeComments__ *file* - - Removes all comments from the file specified\. Throws an error if *file* is - not a valid JPEG image\. - - - __::jpeg::replaceComment__ *file* *text* - - Replaces the first comment in the file with the new *text*\. This is merely - a shortcut for __::jpeg::removeComments__ and __::jpeg::addComment__ - Throws an error if *file* is not a valid JPEG image\. - - - __::jpeg::debug__ *file* - - Prints everything we know about the given file in a nice format\. - - - __::jpeg::markers__ *channel* - - This is an internal helper command, we document it for use by advanced users - of the package\. The argument *channel* is an open file handle positioned - at the start of the first marker \(usually 2 bytes\)\. The command returns a - list with one element for each JFIF marker found in the file\. Each element - consists of a list of the marker name, its offset in the file, and its - length\. The offset points to the beginning of the sections data, not the - marker itself\. The length is the length of the data from the offset listed - to the start of the next marker\. - -# LIMITATIONS - -can only work with files cant write exif data gps exif data not parsed makernote -data not yet implemented - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *jpeg* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[comment](\.\./\.\./\.\./\.\./index\.md\#comment), -[exif](\.\./\.\./\.\./\.\./index\.md\#exif), [image](\.\./\.\./\.\./\.\./index\.md\#image), -[jfif](\.\./\.\./\.\./\.\./index\.md\#jfif), [jpeg](\.\./\.\./\.\./\.\./index\.md\#jpeg), -[thumbnail](\.\./\.\./\.\./\.\./index\.md\#thumbnail) - -# CATEGORY - -File formats - -# COPYRIGHT - -Copyright © 2004\-2005, Code: Aaron Faupell -Copyright © 2007, Code: Andreas Kupries -Copyright © 2004\-2009, Doc: Andreas Kupries -Copyright © 2011, Code: Pat Thoyts DELETED embedded/md/tcllib/files/modules/json/json.md Index: embedded/md/tcllib/files/modules/json/json.md ================================================================== --- embedded/md/tcllib/files/modules/json/json.md +++ embedded/md/tcllib/files/modules/json/json.md @@ -1,163 +0,0 @@ - -[//000000001]: # (json \- JSON) -[//000000002]: # (Generated from file 'json\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 ActiveState Software Inc\.) -[//000000004]: # (Copyright © 2009 Thomas Maeder, Glue Software Engineering AG) -[//000000005]: # (json\(n\) 1\.3\.4 tcllib "JSON") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -json \- JSON parser - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [RELATED](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require json ?1\.3\.4? - -[__::json::json2dict__ *txt*](#1) -[__::json::many\-json2dict__ *txt* ?*max*?](#2) - -# DESCRIPTION - -The __json__ package provides a simple Tcl\-only library for parsing the JSON -[http://www\.json\.org/](http://www\.json\.org/) data exchange format as -specified in RFC 4627 -[http://www\.ietf\.org/rfc/rfc4627\.txt](http://www\.ietf\.org/rfc/rfc4627\.txt)\. -There is some ambiguity in parsing JSON because JSON has type information that -is not maintained by the Tcl conversion\. The __json__ package returns data -as a Tcl __[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__\. Either the -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ package or Tcl 8\.5 is required for -use\. - -# COMMANDS - - - __::json::json2dict__ *txt* - - Parse JSON formatted text *txt* into a Tcl dict and return the value\. - - If *txt* contains more than one JSON entity only the first one is - returned\. - - - __::json::many\-json2dict__ *txt* ?*max*? - - Parse JSON formatted text *txt* containing multiple JSON entities into a - list of dictionaries and return that list\. - - If *max* is specified exactly that many entities are extracted from - *txt*\. By default the command will attempt to extract all, without limits\. - A value of "*max* == 0" does not make sense and will cause the command to - throw an error\. - -# EXAMPLES - -An example of a JSON array converted to Tcl\. A JSON array is returned as a -single item with multiple elements\. - - [ - { - "precision": "zip", - "Latitude": 37.7668, - "Longitude": -122.3959, - "Address": "", - "City": "SAN FRANCISCO", - "State": "CA", - "Zip": "94107", - "Country": "US" - }, - { - "precision": "zip", - "Latitude": 37.371991, - "Longitude": -122.026020, - "Address": "", - "City": "SUNNYVALE", - "State": "CA", - "Zip": "94085", - "Country": "US" - } - ] - => - {Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020} - -An example of a JSON object converted to Tcl\. A JSON object is returned as a -multi\-element list \(a dict\)\. - - { - "Image": { - "Width": 800, - "Height": 600, - "Title": "View from 15th Floor", - "Thumbnail": { - "Url": "http://www.example.com/image/481989943", - "Height": 125, - "Width": "100" - }, - "IDs": [116, 943, 234, 38793] - } - } - => - Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}} - -# RELATED - -To write json, instead of parsing it, see package -__[json::write](json\_write\.md)__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *json* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[data exchange](\.\./\.\./\.\./\.\./index\.md\#data\_exchange), [exchange -format](\.\./\.\./\.\./\.\./index\.md\#exchange\_format), -[javascript](\.\./\.\./\.\./\.\./index\.md\#javascript), -[json](\.\./\.\./\.\./\.\./index\.md\#json) - -# CATEGORY - -CGI programming - -# COPYRIGHT - -Copyright © 2006 ActiveState Software Inc\. -Copyright © 2009 Thomas Maeder, Glue Software Engineering AG DELETED embedded/md/tcllib/files/modules/json/json_write.md Index: embedded/md/tcllib/files/modules/json/json_write.md ================================================================== --- embedded/md/tcllib/files/modules/json/json_write.md +++ embedded/md/tcllib/files/modules/json/json_write.md @@ -1,141 +0,0 @@ - -[//000000001]: # (json::write \- JSON) -[//000000002]: # (Generated from file 'json\_write\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2013 Andreas Kupries ) -[//000000004]: # (json::write\(n\) 1\.0\.3 tcllib "JSON") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -json::write \- JSON generation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [RELATED](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require json::write ?1\.0\.3? - -[__::json::write__ __indented__](#1) -[__::json::write__ __indented__ *flag*](#2) -[__::json::write__ __aligned__](#3) -[__::json::write__ __aligned__ *flag*](#4) -[__::json::write__ __string__ *s*](#5) -[__::json::write__ __array__ *arg*\.\.\.](#6) -[__::json::write__ __object__ *key* *value*\.\.\.](#7) - -# DESCRIPTION - -The __json::write__ package provides a simple Tcl\-only library for -generation of text in the JSON [http://www\.json\.org/](http://www\.json\.org/) -data exchange format as specified in RFC 4627 -[http://www\.ietf\.org/rfc/rfc4627\.txt](http://www\.ietf\.org/rfc/rfc4627\.txt)\. - -# COMMANDS - - - __::json::write__ __indented__ - - This method returns the current state of the indentation setting\. - - - __::json::write__ __indented__ *flag* - - This and the method __aligned__ configure the layout of the JSON - generated by the package\. - - If this *flag* is set \(default\) the package will break the generated JSON - code across lines and indent it according to its inner structure, with each - key of an object on a separate line\. - - If this flag is not set, the whole JSON object will be written on a single - line, with minimum spacing between all elements\. - - - __::json::write__ __aligned__ - - This method returns the current state of the alignment setting\. - - - __::json::write__ __aligned__ *flag* - - This and the method __indented__ configure the layout of the JSON - generated by the package\. - - If this *flag* is set \(default\) the package ensures that the values for - the keys in an object are vertically aligned with each other, for a nice - table effect\. To make this work this also implies that __indented__ is - set as well\. - - If this flag is not set, the output is formatted as per the value of - __indented__, without trying to align the values for object keys\. - - - __::json::write__ __string__ *s* - - This method takes the string *s* and returns it properly quoted for JSON - as its result\. - - - __::json::write__ __array__ *arg*\.\.\. - - This method takes a series of JSON formatted arguments and returns them as a - properly formatted JSON array as its result\. - - - __::json::write__ __object__ *key* *value*\.\.\. - - This method takes a series of key/value arguments, the values already - formatted for JSON, and returns them as a properly formatted JSON object as - its result, with the keys formatted as JSON strings\. - -# RELATED - -To parse json, instead of writing it, see package __[json](json\.md)__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *json* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[data exchange](\.\./\.\./\.\./\.\./index\.md\#data\_exchange), [exchange -format](\.\./\.\./\.\./\.\./index\.md\#exchange\_format), -[javascript](\.\./\.\./\.\./\.\./index\.md\#javascript), -[json](\.\./\.\./\.\./\.\./index\.md\#json) - -# CATEGORY - -CGI programming - -# COPYRIGHT - -Copyright © 2009\-2013 Andreas Kupries DELETED embedded/md/tcllib/files/modules/lambda/lambda.md Index: embedded/md/tcllib/files/modules/lambda/lambda.md ================================================================== --- embedded/md/tcllib/files/modules/lambda/lambda.md +++ embedded/md/tcllib/files/modules/lambda/lambda.md @@ -1,139 +0,0 @@ - -[//000000001]: # (lambda \- Utility commands for anonymous procedures) -[//000000002]: # (Generated from file 'lambda\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries, BSD licensed) -[//000000004]: # (lambda\(n\) 1 tcllib "Utility commands for anonymous procedures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -lambda \- Utility commands for anonymous procedures - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require lambda ?1? - -[__::lambda__ *arguments* *body* ?*arg*\.\.\.?](#1) -[__::lambda@__ *namespace* *arguments* *body* ?*arg*\.\.\.?](#2) - -# DESCRIPTION - -This package provides two convenience commands to make the writing of anonymous -procedures, i\.e\. lambdas more -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__\-like\. Instead of, for example, to -write - - set f {::apply {{x} { - .... - }}} - -with its deep nesting of braces, or - - set f [list ::apply {{x y} { - .... - }} $value_for_x] - -with a list command to insert some of the arguments of a partial application, -just write - - set f [lambda {x} { - .... - }] - -and - - set f [lambda {x y} { - .... - } $value_for_x] - -# COMMANDS - - - __::lambda__ *arguments* *body* ?*arg*\.\.\.? - - The command constructs an anonymous procedure from the list of arguments, - body script and \(optional\) predefined argument values and returns a command - prefix representing this anonymous procedure\. - - When invoked the *body* is run in a new procedure scope just underneath - the global scope, with the arguments set to the values supplied at both - construction and invokation time\. - - - __::lambda@__ *namespace* *arguments* *body* ?*arg*\.\.\.? - - The command constructs an anonymous procedure from the namespace name, list - of arguments, body script and \(optional\) predefined argument values and - returns a command prefix representing this anonymous procedure\. - - When invoked the *body* is run in a new procedure scope in the - *namespace*, with the arguments set to the values supplied at both - construction and invokation time\. - -# AUTHORS - -Andreas Kupries - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *lambda* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -apply\(n\), proc\(n\) - -# KEYWORDS - -[anonymous procedure](\.\./\.\./\.\./\.\./index\.md\#anonymous\_procedure), -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), [command -prefix](\.\./\.\./\.\./\.\./index\.md\#command\_prefix), -[currying](\.\./\.\./\.\./\.\./index\.md\#currying), -[lambda](\.\./\.\./\.\./\.\./index\.md\#lambda), [partial -application](\.\./\.\./\.\./\.\./index\.md\#partial\_application), -[proc](\.\./\.\./\.\./\.\./index\.md\#proc) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries, BSD licensed DELETED embedded/md/tcllib/files/modules/lazyset/lazyset.md Index: embedded/md/tcllib/files/modules/lazyset/lazyset.md ================================================================== --- embedded/md/tcllib/files/modules/lazyset/lazyset.md +++ embedded/md/tcllib/files/modules/lazyset/lazyset.md @@ -1,120 +0,0 @@ - -[//000000001]: # (lazyset \- Lazy evaluation for variables and arrays) -[//000000002]: # (Generated from file 'lazyset\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2018 Roy Keene) -[//000000004]: # (lazyset\(n\) 1 tcllib "Lazy evaluation for variables and arrays") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -lazyset \- Lazy evaluation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [AUTHORS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require lazyset ?1? - -[__::lazyset::variable__ ?*\-array boolean*? ?*\-appendArgs boolean*? *variableName* *commandPrefix*](#1) - -# DESCRIPTION - -The __lazyset__ package provides a mechanism for deferring execution of code -until a specific variable or any index of an array is referenced\. - -# COMMANDS - - - __::lazyset::variable__ ?*\-array boolean*? ?*\-appendArgs boolean*? *variableName* *commandPrefix* - - Arrange for the code specified as *commandPrefix* to be executed when the - variable whose name is specified by *variableName* is read for the first - time\. If the optional argument *\-array boolean* is specified as true, then - the variable specified as *variableName* is treated as an array and - attempting to read any index of the array causes that index to be set by the - *commandPrefix* as they are read\. If the optional argument *\-appendArgs - boolean* is specified as false, then the variable name and subnames are not - appended to the *commandPrefix* before it is evaluated\. If the argument - *\-appendArgs boolean* is not specified or is specified as true then 1 or 2 - additional arguments are appended to the *commandPrefix*\. If *\-array - boolean* is specified as true, then 2 arguments are appended corresponding - to the name of the variable and the index, otherwise 1 argument is appended - containing the name of variable\. The *commandPrefix* code is run in the - same scope as the variable is read\. - -# EXAMPLES - - ::lazyset::variable page {apply {{name} { - package require http - set token [http::geturl http://www.tcl.tk/] - set data [http::data $token] - return $data - }}} - - puts $page - - ::lazyset::variable -array true page {apply {{name index} { - package require http - set token [http::geturl $index] - set data [http::data $token] - return $data - }}} - - puts $page(http://www.tcl.tk/) - - ::lazyset::variable -appendArgs false simple { - return -level 0 42 - } - - puts $simple - -# AUTHORS - -Roy Keene - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *utility* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2018 Roy Keene DELETED embedded/md/tcllib/files/modules/ldap/ldap.md Index: embedded/md/tcllib/files/modules/ldap/ldap.md ================================================================== --- embedded/md/tcllib/files/modules/ldap/ldap.md +++ embedded/md/tcllib/files/modules/ldap/ldap.md @@ -1,666 +0,0 @@ - -[//000000001]: # (ldap \- LDAP client) -[//000000002]: # (Generated from file 'ldap\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Andreas Kupries ) -[//000000004]: # (Copyright © 2004 Jochen Loewer ) -[//000000005]: # (Copyright © 2006 Michael Schlenker ) -[//000000006]: # (ldap\(n\) 1\.10 tcllib "LDAP client") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ldap \- LDAP client - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TLS Security Considerations](#section2) - - - [COMMANDS](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require ldap ?1\.10? - -[__::ldap::connect__ *host* ?*port*?](#1) -[__::ldap::tlsoptions__ __reset__](#2) -[__::ldap::tlsoptions__ ?*opt1* *val1*? ?*opt2* *val2*? \.\.\.](#3) -[__::ldap::secure\_connect__ *host* ?*port*?](#4) -[__::ldap::secure\_connect__ *host* ?*port*? ?*verify\_cert*? ?*sni\_servername*?](#5) -[__::ldap::disconnect__ *handle*](#6) -[__::ldap::starttls__ *handle*](#7) -[__::ldap::starttls__ *handle* ?*cafile*? ?*certfile*? ?*keyfile*? ?*verify\_cert*? ?*sni\_servername*?](#8) -[__::ldap::bind__ *handle* ?*name*? ?*password*?](#9) -[__::ldap::bindSASL__ *handle* ?*name*? ?*password*?](#10) -[__::ldap::unbind__ *handle*](#11) -[__::ldap::search__ *handle* *baseObject* *filterString* *attributes* *options*](#12) -[__::ldap::searchInit__ *handle* *baseObject* *filterString* *attributes* *options*](#13) -[__::ldap::searchNext__ *handle*](#14) -[__::ldap::searchEnd__ *handle*](#15) -[__::ldap::modify__ *handle* *dn* *attrValToReplace* ?*attrToDelete*? ?*attrValToAdd*?](#16) -[__::ldap::modifyMulti__ *handle* *dn* *attrValToReplace* ?*attrValToDelete*? ?*attrValToAdd*?](#17) -[__::ldap::add__ *handle* *dn* *attrValueTuples*](#18) -[__::ldap::addMulti__ *handle* *dn* *attrValueTuples*](#19) -[__::ldap::delete__ *handle* *dn*](#20) -[__::ldap::modifyDN__ *handle* *dn* *newrdn* ?*deleteOld*? ?*newSuperior*?](#21) -[__::ldap::info__ __[ip](\.\./\.\./\.\./\.\./index\.md\#ip)__ *handle*](#22) -[__::ldap::info__ __bound__ *handle*](#23) -[__::ldap::info__ __bounduser__ *handle*](#24) -[__::ldap::info__ __connections__](#25) -[__::ldap::info__ __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ *handle*](#26) -[__::ldap::info__ __tlsstatus__ *handle*](#27) -[__::ldap::info__ __saslmechanisms__ *handle*](#28) -[__::ldap::info__ __[control](\.\./control/control\.md)__ *handle*](#29) -[__::ldap::info__ __extensions__ *extensions*](#30) -[__::ldap::info__ __whoami__ *handle*](#31) - -# DESCRIPTION - -The __ldap__ package provides a Tcl\-only client library for the LDAPv3 -protocol as specified in RFC 4511 -\([http://www\.rfc\-editor\.org/rfc/rfc4511\.txt](http://www\.rfc\-editor\.org/rfc/rfc4511\.txt)\)\. -It works by opening the standard \(or secure\) LDAP socket on the server, and then -providing a Tcl API to access the LDAP protocol commands\. All server errors are -returned as Tcl errors \(thrown\) which must be caught with the Tcl __catch__ -command\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __LDAPS__ connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# COMMANDS - - - __::ldap::connect__ *host* ?*port*? - - Opens a LDAPv3 connection to the specified *host*, at the given *port*, - and returns a token for the connection\. This token is the *handle* - argument for all other commands\. If no *port* is specified it will default - to __389__\. - - The command blocks until the connection has been established, or - establishment definitely failed\. - - - __::ldap::tlsoptions__ __reset__ - - This command resets TLS options to default values\. It returns the set of - options\. Using this command is incompatible with the obsolete form of - __::ldap::secure\_connect__ and __::ldap\_starttls__\. - - - __::ldap::tlsoptions__ ?*opt1* *val1*? ?*opt2* *val2*? \.\.\. - - This commands adds one or more options to some value, and may be used more - than one time in order to add options in several steps\. A complete - description of options may be found in the - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package documentation\. Valid - options and values are: - - * __\-cadir__ directory - - Provide the directory containing the CA certificates\. No default\. - - * __\-cafile__ file - - Provide the CA file\. No default\. - - * __\-cipher__ string - - Provide the cipher suites to use\. No default\. - - * __\-dhparams__ file - - Provide a Diffie\-Hellman parameters file\. No default\. - - * __\-request__ boolean - - Request a certificate from peer during SSL handshake\. Default: true\. - - * __\-require__ boolean - - Require a valid certificate from peer during SSL handshake\. If this is - set to true then \-request must also be set to true\. Default: false - - * __\-servername__ host - - Only available if the OpenSSL library the TLS package is linked against - supports the TLS hostname extension for 'Server Name Indication' \(SNI\)\. - Use to name the logical host we are talking to and expecting a - certificate for\. No default\. - - * __\-ssl2__ bool - - Enable use of SSL v2\. Default: false - - * __\-ssl3__ bool - - Enable use of SSL v3\. Default: false - - * __\-tls1__ bool - - Enable use of TLS v1 Default: true - - * __\-tls1\.1__ bool - - Enable use of TLS v1\.1 Default: true - - * __\-tls1\.2__ bool - - Enable use of TLS v1\.2 Default: true - - This command returns the current set of TLS options and values\. In - particular, one may use this command without any arguments to get the - current set of options\. - - Using this command is incompatible with the obsolete form of - __::ldap::secure\_connect__ and __::ldap\_starttls__ \(see below\)\. - - - __::ldap::secure\_connect__ *host* ?*port*? - - Like __::ldap::connect__, except that the created connection is secured - by SSL\. The port defaults to __636__\. This command depends on the - availability of the package __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, - which is a SSL binding for Tcl\. If - __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ is not available, then this - command will fail\. - - TLS options are specified with __::ldap::tlsoptions__\. - - The command blocks until the connection has been established, or - establishment definitely failed\. - - - __::ldap::secure\_connect__ *host* ?*port*? ?*verify\_cert*? ?*sni\_servername*? - - Note: this form of the command is deprecated, since TLS options had to be - specified with a combination of parameters to this command \(*verify\_cert* - and *sni\_servername*\) and arguments to __::tls::init__ \(from package - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__\) for example to setup defaults - for trusted certificates\. Prefer the above form \(without the *verify\_cert* - and *sni\_servername* parameters\) and set TLS options with - __::ldap::tlsoptions__\. - - If *verify\_cert* is set to 1, the default, this checks the server - certificate against the known hosts\. If *sni\_servername* is set, the given - hostname is used as the hostname for Server Name Indication in the TLS - handshake\. - - Use __::tls::init__ to setup defaults for trusted certificates\. - - TLS supports different protocol levels\. In common use are the versions 1\.0, - 1\.1 and 1\.2\. By default all those versions are offered\. If you need to - modify the acceptable protocols, you can change the ::ldap::tlsProtocols - list \(deprecated\)\. - - - __::ldap::disconnect__ *handle* - - Closes the ldap connection refered to by the token *handle*\. Returns the - empty string as its result\. - - - __::ldap::starttls__ *handle* - - Start TLS negotiation on the connection denoted by *handle*, with TLS - parameters set with __::ldap::tlsoptions__\. - - - __::ldap::starttls__ *handle* ?*cafile*? ?*certfile*? ?*keyfile*? ?*verify\_cert*? ?*sni\_servername*? - - Note: this form of the command is deprecated, since TLS options had to be - specified with a combination of parameters to this command \(*cafile*, - *certfile*, *keyfile*, *verify\_cert* and *sni\_servername*\) and - arguments to __::tls::init__ \(from package - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__\)\. Prefer the above form \(without - specific TLS arguments\) and set TLS options with __::ldap::tlsoptions__\. - - Start TLS negotiation on the connection denoted by *handle*\. You need to - set at least the *cafile* argument to a file with trusted certificates, if - *verify\_cert* is 1, which is the default\. The *sni\_servername* can be - used to signal a different hostname during the TLS handshake\. The announced - protocols are determined in the same way as __::ldap::secure\_connect__\. - You can specify a TLS client certificate with the *certfile* and - *keyfile* options\. - - - __::ldap::bind__ *handle* ?*name*? ?*password*? - - This command authenticates the ldap connection refered to by the token in - *handle*, with a user name and associated password\. It blocks until a - response from the ldap server arrives\. Its result is the empty string\. Both - *name* and *passwd* default to the empty string if they are not - specified\. By leaving out *name* and *passwd* you can make an anonymous - bind to the ldap server\. You can issue __::ldap::bind__ again to bind - with different credentials\. - - - __::ldap::bindSASL__ *handle* ?*name*? ?*password*? - - This command uses SASL authentication mechanisms to do a multistage bind\. - Its otherwise identical to the standard __::ldap::bind__\. This feature - is currently experimental and subject to change\. See the documentation for - the __[SASL](\.\./sasl/sasl\.md)__ and the "SASL\.txt" in the tcllib CVS - repository for details how to setup and use SASL with openldap\. - - - __::ldap::unbind__ *handle* - - This command asks the ldap server to release the last bind done for the - connection refered to by the token in *handle*\. The *handle* is invalid - after the unbind, as the server closes the connection\. So this is effectivly - just a more polite disconnect operation\. - - - __::ldap::search__ *handle* *baseObject* *filterString* *attributes* *options* - - This command performs a LDAP search below the *baseObject* tree using a - complex LDAP search expression *filterString* and returns the specified - *attributes* of all matching objects \(DNs\)\. If the list of *attributes* - was empty all attributes are returned\. The command blocks until it has - received all results\. The valid *options* are identical to the options - listed for __::ldap::searchInit__\. - - An example of a search expression is - - set filterString "|(cn=Linus*)(sn=Torvalds*)" - - The return value of the command is a list of nested dictionaries\. The first - level keys are object identifiers \(DNs\), second levels keys are attribute - names\. In other words, it is in the form - - {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ... - - - __::ldap::searchInit__ *handle* *baseObject* *filterString* *attributes* *options* - - This command initiates a LDAP search below the *baseObject* tree using a - complex LDAP search expression *filterString*\. The search gets the - specified *attributes* of all matching objects \(DNs\)\. The command itself - just starts the search, to retrieve the actual results, use - __::ldap::searchNext__\. A search can be terminated at any time by - __::ldap::searchEnd__\. This informs the server that no further results - should be sent by sending and ABANDON message and cleans up the internal - state of the search\. Only one __::ldap::search__ can be active at a - given time, this includes the introspection commands __::ldap::info - saslmechanisms__, __ldap::info control__ and __ldap::info - extensions__, which invoke a search internally\. Error responses from the - server due to wrong arguments or similar things are returned with the first - __::ldap::searchNext__ call and should be checked and dealed with there\. - If the list of requested *attributes* is empty all attributes will be - returned\. The parameter *options* specifies the options to be used in the - search, and has the following format: - - {-option1 value1 -option2 value2 ... } - - Following options are available: - - * __\-scope__ base one sub - - Control the scope of the search to be one of __base__, __one__, - or __sub__, to specify a base object, one\-level or subtree search\. - The default is __sub__\. - - * __\-derefaliases__ never search find always - - Control how aliases dereferencing is done\. Should be one of - __never__, __always__, __search__, or __find__ to - specify that aliases are never dereferenced, always dereferenced, - dereferenced when searching, or dereferenced only when locating the base - object for the search\. The default is to never dereference aliases\. - - * __\-sizelimit__ num - - Determines the maximum number of entries to return in a search\. If - specified as 0 no limit is enforced\. The server may enforce a - configuration dependent sizelimit, which may be lower than the one given - by this option\. The default is 0, no limit\. - - * __\-timelimit__ seconds - - Asks the server to use a timelimit of *seconds* for the search\. Zero - means no limit\. The default is 0, no limit\. - - * __\-attrsonly__ boolean - - If set to 1 only the attribute names but not the values will be present - in the search result\. The default is to retrieve attribute names and - values\. - - * __\-referencevar__ varname - - If set the search result reference LDAPURIs, if any, are returned in the - given variable\. The caller can than decide to follow those references - and query other LDAP servers for further results\. - - - __::ldap::searchNext__ *handle* - - This command returns the next entry from a LDAP search initiated by - __::ldap::searchInit__\. It returns only after a new result is received - or when no further results are available, but takes care to keep the event - loop alive\. The returned entry is a list with two elements: the first is the - DN of the entry, the second is the list of attributes and values, under the - format: - - dn {attr1 {val11 val12 ...} attr2 {val21...} ...} - - The __::ldap::searchNext__ command returns an empty list at the end of - the search\. - - - __::ldap::searchEnd__ *handle* - - This command terminates a LDAP search initiated by - __::ldap::searchInit__\. It also cleans up the internal state so a new - search can be initiated\. If the client has not yet received all results, the - client sends an ABANDON message to inform the server that no further results - for the previous search should to be sent\. - - - __::ldap::modify__ *handle* *dn* *attrValToReplace* ?*attrToDelete*? ?*attrValToAdd*? - - This command modifies the object *dn* on the ldap server we are connected - to via *handle*\. It replaces attributes with new values, deletes - attributes, and adds new attributes with new values\. All arguments are - dictionaries mapping attribute names to values\. The optional arguments - default to the empty dictionary, which means that no attributes will be - deleted nor added\. - - * dictionary *attrValToReplace* \(in\) - - No attributes will be changed if this argument is empty\. The dictionary - contains the new attributes and their values\. They *replace all* - attributes known to the object\. - - * dictionary *attrToDelete* \(in\) - - No attributes will be deleted if this argument is empty\. The dictionary - values are restrictions on the deletion\. An attribute listed here will - be deleted if and only if its current value at the server matches the - value specified in the dictionary, or if the value in the dictionary is - the empty string\. - - * dictionary *attrValToAdd* \(in\) - - No attributes will be added if this argument is empty\. The dictionary - values are the values for the new attributes\. - - The command blocks until all modifications have completed\. Its result is the - empty string\. - - - __::ldap::modifyMulti__ *handle* *dn* *attrValToReplace* ?*attrValToDelete*? ?*attrValToAdd*? - - This command modifies the object *dn* on the ldap server we are connected - to via *handle*\. It replaces attributes with new values, deletes - attributes, and adds new attributes with new values\. All arguments are lists - with the format: - - attr1 {val11 val12 ...} attr2 {val21...} ... - - where each value list may be empty for deleting all attributes\. The optional - arguments default to empty lists of attributes to delete and to add\. - - * list *attrValToReplace* \(in\) - - No attributes will be changed if this argument is empty\. The dictionary - contains the new attributes and their values\. They *replace all* - attributes known to the object\. - - * list *attrValToDelete* \(in\) - - No attributes will be deleted if this argument is empty\. If no value is - specified, the whole set of values for an attribute will be deleted\. - - * list *attrValToAdd* \(in\) - - No attributes will be added if this argument is empty\. - - The command blocks until all modifications have completed\. Its result is the - empty string\. - - - __::ldap::add__ *handle* *dn* *attrValueTuples* - - This command creates a new object using the specified *dn*\. The attributes - of the new object are set to the values in the list *attrValueTuples*\. - Multiple valuated attributes may be specified using multiple tuples\. The - command blocks until the operation has completed\. Its result is the empty - string\. - - - __::ldap::addMulti__ *handle* *dn* *attrValueTuples* - - This command is the preferred one to create a new object using the specified - *dn*\. The attributes of the new object are set to the values in the - dictionary *attrValueTuples* \(which is keyed by the attribute names\)\. Each - tuple is a list containing multiple values\. The command blocks until the - operation has completed\. Its result is the empty string\. - - - __::ldap::delete__ *handle* *dn* - - This command removes the object specified by *dn*, and all its attributes - from the server\. The command blocks until the operation has completed\. Its - result is the empty string\. - - - __::ldap::modifyDN__ *handle* *dn* *newrdn* ?*deleteOld*? ?*newSuperior*? - - This command moves or copies the object specified by *dn* to a new - location in the tree of object\. This location is specified by *newrdn*, a - *relative* designation, or by *newrdn* and *newSuperior*, a - *absolute* designation\. The optional argument *deleteOld* defaults to - __true__, i\.e\. a move operation\. If *deleteOld* is not set, then the - operation will create a copy of *dn* in the new location\. The optional - argument *newSuperior* defaults an empty string, meaning that the object - must not be relocated in another branch of the tree\. If this argument is - given, the argument *deleteOld* must be specified also\. The command blocks - until the operation has completed\. Its result is the empty string\. - - - __::ldap::info__ __[ip](\.\./\.\./\.\./\.\./index\.md\#ip)__ *handle* - - This command returns the IP address of the remote LDAP server the handle is - connected to\. - - - __::ldap::info__ __bound__ *handle* - - This command returns 1 if a handle has successfully completed a - __::ldap::bind__\. If no bind was done or it failed, a 0 is returned\. - - - __::ldap::info__ __bounduser__ *handle* - - This command returns the username used in the bind operation if a handle has - successfully completed a __::ldap::bind__\. If no bound was done or it - failed, an empty string is returned\. - - - __::ldap::info__ __connections__ - - This command returns all currently existing ldap connection handles\. - - - __::ldap::info__ __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ *handle* - - This command returns 1 if the ldap connection *handle* used TLS/SSL for - connection via __ldap::secure\_connect__ or completed - __ldap::starttls__, 0 otherwise\. - - - __::ldap::info__ __tlsstatus__ *handle* - - This command returns the current security status of an TLS secured channel\. - The result is a list of key\-value pairs describing the connected peer \(see - the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package documentation for - the returned values\)\. If the connection is not secured with TLS, an empty - list is returned\. - - - __::ldap::info__ __saslmechanisms__ *handle* - - Return the supported SASL mechanisms advertised by the server\. Only valid in - a bound state \(anonymous or other\)\. - - - __::ldap::info__ __[control](\.\./control/control\.md)__ *handle* - - Return the supported controls advertised by the server as a list of OIDs\. - Only valid in a bound state\. This is currently experimental and subject to - change\. - - - __::ldap::info__ __extensions__ *extensions* - - Returns the supported LDAP extensions as list of OIDs\. Only valid in a bound - state\. This is currently experimental and subject to change\. - - - __::ldap::info__ __whoami__ *handle* - - Returns authzId for the current connection\. This implements the RFC 4532 - protocol extension\. - -# EXAMPLES - -A small example, extracted from the test application coming with this code\. - - package require ldap - - # Connect, bind, add a new object, modify it in various ways - - set handle [ldap::connect localhost 9009] - - set dn "cn=Manager, o=University of Michigan, c=US" - set pw secret - - ldap::bind $handle $dn $pw - - set dn "cn=Test User,ou=People,o=University of Michigan,c=US" - - ldap::add $handle $dn { - objectClass OpenLDAPperson - cn {Test User} - mail test.user@google.com - uid testuid - sn User - telephoneNumber +31415926535 - telephoneNumber +27182818285 - } - - set dn "cn=Another User,ou=People,o=University of Michigan,c=US" - - ldap::addMulti $handle $dn { - objectClass {OpenLDAPperson} - cn {{Anotther User}} - mail {test.user@google.com} - uid {testuid} - sn {User} - telephoneNumber {+31415926535 +27182818285} - } - - # Replace all attributes - ldap::modify $handle $dn [list drink icetea uid JOLO] - - # Add some more - ldap::modify $handle $dn {} {} [list drink water drink orangeJuice pager "+1 313 555 7671"] - - # Delete - ldap::modify $handle $dn {} [list drink water pager ""] - - # Move - ldap::modifyDN $handle $dn "cn=Tester" - - # Kill the test object, and shut the connection down. - set dn "cn=Tester,ou=People,o=University of Michigan,c=US" - ldap::delete $handle $dn - - ldap::unbind $handle - ldap::disconnect $handle - -And another example, a simple query, and processing the results\. - - package require ldap - set handle [ldap::connect ldap.acme.com 389] - ldap::bind $handle - set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}] - foreach result $results { - foreach {object attributes} $result break - - # The processing here is similar to what 'parray' does. - # I.e. finding the longest attribute name and then - # generating properly aligned output listing all attributes - # and their values. - - set width 0 - set sortedAttribs {} - foreach {type values} $attributes { - if {[string length $type] > $width} { - set width [string length $type] - } - lappend sortedAttribs [list $type $values] - } - - puts "object='$object'" - - foreach sortedAttrib $sortedAttribs { - foreach {type values} $sortedAttrib break - foreach value $values { - regsub -all "\[\x01-\x1f\]" $value ? value - puts [format " %-${width}s %s" $type $value] - } - } - puts "" - } - ldap::unbind $handle - ldap::disconnect $handle - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ldap* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[directory access](\.\./\.\./\.\./\.\./index\.md\#directory\_access), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap), [ldap -client](\.\./\.\./\.\./\.\./index\.md\#ldap\_client), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), [rfc -2251](\.\./\.\./\.\./\.\./index\.md\#rfc\_2251), [rfc -4511](\.\./\.\./\.\./\.\./index\.md\#rfc\_4511), [x\.500](\.\./\.\./\.\./\.\./index\.md\#x\_500) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2004 Andreas Kupries -Copyright © 2004 Jochen Loewer -Copyright © 2006 Michael Schlenker DELETED embedded/md/tcllib/files/modules/ldap/ldapx.md Index: embedded/md/tcllib/files/modules/ldap/ldapx.md ================================================================== --- embedded/md/tcllib/files/modules/ldap/ldapx.md +++ embedded/md/tcllib/files/modules/ldap/ldapx.md @@ -1,800 +0,0 @@ - -[//000000001]: # (ldapx \- LDAP extended object interface) -[//000000002]: # (Generated from file 'ldapx\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2018 Pierre David ) -[//000000004]: # (ldapx\(n\) 1\.2 tcllib "LDAP extended object interface") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ldapx \- LDAP extended object interface - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [ENTRY CLASS](#section3) - - - [Entry Instance Data](#subsection1) - - - [Entry Options](#subsection2) - - - [Methods for all kinds of entries](#subsection3) - - - [Methods for standard entries only](#subsection4) - - - [Methods for change entries only](#subsection5) - - - [Entry Example](#subsection6) - - - [LDAP CLASS](#section4) - - - [Ldap Instance Data](#subsection7) - - - [Ldap Options](#subsection8) - - - [Ldap Methods](#subsection9) - - - [Ldap Example](#subsection10) - - - [LDIF CLASS](#section5) - - - [Ldif Instance Data](#subsection11) - - - [Ldif Options](#subsection12) - - - [Ldif Methods](#subsection13) - - - [Ldif Example](#subsection14) - - - [References](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require ldapx ?1\.2? - -[*e* __reset__](#1) -[*e* __dn__ ?*newdn*?](#2) -[*e* __rdn__](#3) -[*e* __superior__](#4) -[*e* __print__](#5) -[*se* __isempty__](#6) -[*se* __get__ *attr*](#7) -[*se* __get1__ *attr*](#8) -[*se* __set__ *attr* *values*](#9) -[*se* __set1__ *attr* *value*](#10) -[*se* __add__ *attr* *values*](#11) -[*se* __add1__ *attr* *value*](#12) -[*se* __del__ *attr* ?*values*?](#13) -[*se* __del1__ *attr* *value*](#14) -[*se* __getattr__](#15) -[*se* __getall__](#16) -[*se* __setall__ *avpairs*](#17) -[*se* __backup__ ?*other*?](#18) -[*se* __swap__](#19) -[*se* __restore__ ?*other*?](#20) -[*se* __apply__ *centry*](#21) -[*ce* __change__ ?*new*?](#22) -[*ce* __diff__ *new* ?*old*?](#23) -[*la* __error__ ?*newmsg*?](#24) -[*la* __connect__ *url* ?*binddn*? ?*bindpw*? ?*starttls*?](#25) -[*la* __disconnect__](#26) -[*la* __traverse__ *base* *filter* *attrs* *entry* *body*](#27) -[*la* __search__ *base* *filter* *attrs*](#28) -[*la* __read__ *base* *filter* *entry* \.\.\. *entry*](#29) -[*la* __commit__ *entry* \.\.\. *entry*](#30) -[*li* __channel__ *chan*](#31) -[*li* __error__ ?*newmsg*?](#32) -[*li* __read__ *entry*](#33) -[*li* __write__ *entry*](#34) - -# DESCRIPTION - -The __ldapx__ package provides an extended Tcl interface to LDAP directores -and LDIF files\. The __ldapx__ package is built upon the -__[ldap](ldap\.md)__ package in order to get low level LDAP access\. - -LDAP access is compatible with RFC 2251 -\([http://www\.rfc\-editor\.org/rfc/rfc2251\.txt](http://www\.rfc\-editor\.org/rfc/rfc2251\.txt)\)\. -LDIF access is compatible with RFC 2849 -\([http://www\.rfc\-editor\.org/rfc/rfc2849\.txt](http://www\.rfc\-editor\.org/rfc/rfc2849\.txt)\)\. - -# OVERVIEW - -The __ldapx__ package provides objects to interact with LDAP directories and -LDIF files with an easy to use programming interface\. It implements three -__[snit](\.\./snit/snit\.md)__::type classes\. - -The first class, __entry__, is used to store individual entries\. Two -different formats are available: the first one is the *standard* format, which -represents an entry as read from the directory\. The second format is the -*change* format, which stores differences between two standard entries\. - -With these entries, an application which wants to modify an entry in a directory -needs to read a \(standard\) entry from the directory, create a fresh copy into a -new \(standard\) entry, modify the new copy, and then compute the differences -between the two entries into a new \(change\) entry, which may be commited to the -directory\. - -Such kinds of modifications are so heavily used that standard entries may -contain their own copy of the original data\. With such a copy, the application -described above reads a \(standard\) entry from the directory, backs\-up the -original data, modifies the entry, and computes the differences between the -entry and its backup\. These differences are then commited to the directory\. - -Methods are provided to compute differences between two entries, to apply -differences to an entry in order to get a new entry, and to get or set -attributes in standard entries\. - -The second class is the __ldap__ class\. It provides a method to -__connect__ and bind to the directory with a uniform access to LDAP and -LDAPS through an URL \(ldap:// or ldaps://\)\. The __traverse__ control -structure executes a body for each entry found in the directory\. The -__commit__ method applies some changes \(represented as __entry__ -objects\) to the directory\. Since some attributes are represented as UTF\-8 -strings, the option __\-utf8__ controls which attributes must be converted -and which attributes must not be converted\. - -The last class is the __ldif__ class\. It provides a method to associate a -standard Tcl *channel* to an LDIF object\. Then, methods __read__ and -__write__ read or write entries from or to this channel\. This class can make -use of standard or change entries, according to the type of the LDIF file which -may contain either standard entries or change entries \(but not both at the same -time\)\. The option __\-utf8__ works exactly as with the __ldap__ class\. - -# ENTRY CLASS - -## Entry Instance Data - -An instance of the __entry__ class keeps the following data: - - - dn - - This is the DN of the entry, which includes \(in LDAP terminology\) the RDN - \(relative DN\) and the Superior parts\. - - - format - - The format may be *uninitialized* \(entry not yet used\), *standard* or - *change*\. Most methods check the format of the entry, which can be reset - with the __reset__ method\. - - - attrvals - - In a *standard* entry, this is where the attributes and associated values - are stored\. Many methods provide access to these informations\. Attribute - names are always converted into lower case\. - - - backup - - In a *standard* entry, the backup may contain a copy of the dn and all - attributes and values\. Methods __backup__ and __restore__ manipulate - these data, and method __diff__ may use this backup\. - - - change - - In a *change* entry, these data represent the modifications\. Such - modifications are handled by specialized methods such as __apply__ or - __commit__\. Detailed format should not be used directly by programs\. - - Internally, modifications are represented as a list of elements, each - element has one of the following formats \(which match the corresponding LDAP - operations\): - - 1. \{__add__ \{attr1 \{val1\.\.\.valn\} attr2 \{\.\.\.\} \.\.\.\}\} - - Addition of a new entry\. - - 1. \{__mod__ \{modop \{attr1 ?val1\.\.\.valn?\} attr2 \.\.\.\} \{modop \.\.\.\} \.\.\.\} - - Modification of one or more attributes and/or values, where can - be __modadd__, __moddel__ or __modrepl__ \(see the LDAP - modify operation\)\. - - 1. \{__del__\} - - Deletion of an old entry\. - - 1. \{__modrdn__ newrdn deleteoldrdn ?newsuperior?\} - - Renaming of an entry\. - -## Entry Options - -No option is defined by this class\. - -## Methods for all kinds of entries - - - *e* __reset__ - - This method resets the entry to an uninitialized state\. - - - *e* __dn__ ?*newdn*? - - This method returns the current DN of the entry\. If the optional *newdn* - is specified, it replaces the current DN of the entry\. - - - *e* __rdn__ - - This method returns the RDN part of the DN of the entry\. - - - *e* __superior__ - - This method returns the superior part of the DN of the entry\. - - - *e* __print__ - - This method returns the entry as a string ready to be printed\. - -## Methods for standard entries only - -In all methods, attribute names are converted in lower case\. - - - *se* __isempty__ - - This method returns 1 if the entry is empty \(i\.e\. without any attribute\)\. - - - *se* __get__ *attr* - - This method returns all values of the attribute *attr*, or the empty list - if the attribute is not fond\. - - - *se* __get1__ *attr* - - This method returns the first value of the attribute\. - - - *se* __set__ *attr* *values* - - This method sets the values \(list *values*\) of the attribute *attr*\. If - the list is empty, this method deletes all - - - *se* __set1__ *attr* *value* - - This method sets the values of the attribute *attr* to be an unique value - *value*\. Previous values, if any, are replaced by the new value\. - - - *se* __add__ *attr* *values* - - This method adds all elements the list *values* to the values of the - attribute *attr*\. - - - *se* __add1__ *attr* *value* - - This method adds a single value given by the parameter *value* to the - attribute *attr*\. - - - *se* __del__ *attr* ?*values*? - - If the optional list *values* is specified, this method deletes all - specified values from the attribute *attr*\. If the argument *values* is - not specified, this method deletes all values\. - - - *se* __del1__ *attr* *value* - - This method deletes a unique *value* from the attribute *attr*\. - - - *se* __getattr__ - - This method returns all attributes names\. - - - *se* __getall__ - - This method returns all attributes and values from the entry, packed in a - list of pairs \. - - - *se* __setall__ *avpairs* - - This method sets at once all attributes and values\. The format of the - *avpairs* argument is the same as the one returned by method - __getall__\. - - - *se* __backup__ ?*other*? - - This method stores in an *other* standard entry object a copy of the - current DN and attributes/values\. If the optional *other* argument is not - specified, copy is done in the current entry \(in a specific place, see - section [OVERVIEW](#section2)\)\. - - - *se* __swap__ - - This method swaps the current and backup contexts of the entry\. - - - *se* __restore__ ?*other*? - - If the optional argument *other* is given, which must then be a - *standard* entry, this method restores the current entry into the - *other* entry\. If the argument *other* argument is not specified, this - methods restores the current entry from its internal backup \(see section - [OVERVIEW](#section2)\)\. - - - *se* __apply__ *centry* - - This method applies changes defined in the *centry* argument, which must - be a *change* entry\. - -## Methods for change entries only - - - *ce* __change__ ?*new*? - - If the optional argument *new* is specified, this method modifies the - change list \(see subsection [Entry Instance Data](#subsection1) for the - exact format\)\. In both cases, current change list is returned\. Warning: - values returned by this method should only be used by specialized methods - such as __apply__ or __commit__\. - - - *ce* __diff__ *new* ?*old*? - - This method computes the differences between the *new* and *old* entries - under the form of a change list, and stores this list into the current - *change* entry\. If the optional argument *old* is not specified, - difference is computed from the entry and its internal backup \(see section - [OVERVIEW](#section2)\)\. Return value is the computed change list\. - -## Entry Example - - package require ldapx - - # - # Create an entry and fill it as a standard entry with - # attributes and values - # - ::ldapx::entry create e - e dn "uid=joe,ou=people,o=mycomp" - e set1 "uid" "joe" - e set "objectClass" {person anotherObjectClass} - e set1 "givenName" "Joe" - e set1 "sn" "User" - e set "telephoneNumber" {+31415926535 +2182818} - e set1 "anotherAttr" "This is a beautiful day, isn't it?" - - puts stdout "e\n[e print]" - - # - # Create a second entry as a backup of the first, and - # make some changes on it. - # Entry is named automatically by snit. - # - - set b [::ldapx::entry create %AUTO%] - e backup $b - - puts stdout "$b\n[$b print]" - - $b del "anotherAttr" - $b del1 "objectClass" "anotherObjectClass" - - # - # Create a change entry, a compute differences between first - # and second entry. - # - - ::ldapx::entry create c - c diff e $b - - puts stdout "$c\n[$c print]" - - # - # Apply changes to first entry. It should be the same as the - # second entry, now. - # - - e apply c - - ::ldapx::entry create nc - nc diff e $b - - puts stdout "nc\n[nc print]" - - # - # Clean-up - # - - e destroy - $b destroy - c destroy - nc destroy - -# LDAP CLASS - -## Ldap Instance Data - -An instance of the __ldap__ class keeps the following data: - - - channel - - This is the channel used by the __[ldap](ldap\.md)__ package for - communication with the LDAP server\. - - - lastError - - This variable contains the error message which appeared in the last method - of the __ldap__ class \(this string is modified in nearly all methods\)\. - The __error__ method may be used to fetch this message\. - -## Ldap Options - -Options are configured on __ldap__ instances using the __configure__ -method\. - -The first option is used for TLS parameters: - - - __\-tlsoptions__ *list* - - Specify the set of TLS options to use when connecting to the LDAP server - \(see the __connect__ method\)\. For the list of valid options, see the - __[LDAP](ldap\.md)__ package documentation\. - - The default is __\-request 1 \-require 1 \-ssl2 no \-ssl3 no \-tls1 yes \-tls1\.1 - yes \-tls1\.2 yes__\. - - Example: - - $l configure -tlsoptions {-request yes -require yes} - -A set of options of the __ldap__ class is used during search operations -\(methods __traverse__, __search__ and __read__, see below\)\. - - - __\-scope__ __base__|__one__|__sub__ - - Specify the scope of the LDAP search to be one of __base__, __one__ - or __sub__ to specify a base object, one\-level or subtree search\. - - The default is __sub__\. - - - __\-derefaliases__ __never__|__seach__|__find__|__always__ - - Specify how aliases dereferencing is handled: __never__ is used to - specify that aliases are never derefenced, __always__ that aliases are - always derefenced, __search__ that aliases are dereferenced when - searching, or __find__ that aliases are dereferenced only when locating - the base object for the search\. - - The default is __never__\. - - - __\-sizelimit__ integer - - Specify the maximum number of entries to be retreived during a search\. A - value of __0__ means no limit\. - - Default is __0__\. - - - __\-timelimit__ integer - - Specify the time limit for a search to complete\. A value of __0__ means - no limit\. - - Default is __0__\. - - - __\-attrsonly__ __0__|__1__ - - Specify if only attribute names are to be retrieved \(value __1__\)\. - Normally \(value __0__\), attribute values are also retrieved\. - - Default is __0__\. - -The last option is used when getting entries or committing changes in the -directory: - - - __\-utf8__ pattern\-yes pattern\-no - - Specify which attribute values are encoded in UTF\-8\. This information is - specific to the LDAP schema in use by the application, since some attributes - such as jpegPhoto, for example, are not encoded in UTF\-8\. This option takes - the form of a list with two regular expressions suitable for the - __regexp__ command \(anchored by ^ and $\)\. The first specifies which - attribute names are to be UTF\-8 encoded, and the second selects, among - those, the attribute names which will not be UTF\-8 encoded\. It is thus - possible to say: convert all attributes, except jpegPhoto\. - - Default is \{\{\.\*\} \{\}\}, meaning: all attributes are converted, without - exception\. - -## Ldap Methods - - - *la* __error__ ?*newmsg*? - - This method returns the error message that occurred in the last call to a - __ldap__ class method\. If the optional argument *newmsg* is supplied, - it becomes the last error message\. - - - *la* __connect__ *url* ?*binddn*? ?*bindpw*? ?*starttls*? - - This method connects to the LDAP server using given URL \(which can be of the - form [ldap://host:port](ldap://host:port) or - [ldaps://host:port](ldaps://host:port)\)\. If an optional *binddn* - argument is given together with the *bindpw* argument, the __connect__ - binds to the LDAP server using the specified DN and password\. - - If the *starttls* argument is given a true value \(__1__, __yes__, - etc\.\) and the URL uses the [ldap://](ldap://) scheme, a TLS negotiation - is initiated with the newly created connection, before LDAP binding\. Default - value: __no__\. - - This method returns 1 if connection was successful, or 0 if an error - occurred \(use the __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ method to - get the message\)\. - - - *la* __disconnect__ - - This method disconnects \(and unbinds, if necessary\) from the LDAP server\. - - - *la* __traverse__ *base* *filter* *attrs* *entry* *body* - - This method is a new control structure\. It searches the LDAP directory from - the specified base DN \(given by the *base* argument\) and selects entries - based on the argument *filter*\. For each entry found, this method fetches - attributes specified by the *attrs* argument \(or all attributes if it is - an empty list\), stores them in the *entry* instance of class __entry__ - and executes the script defined by the argument *body*\. Options are used - to refine the search\. - - Caution: when this method is used, the script *body* cannot perform - another LDAP search \(methods __traverse__, __search__ or - __read__\)\. - - - *la* __search__ *base* *filter* *attrs* - - This method searches the directory using the same way as method - __traverse__\. All found entries are stored in newly created instances of - class __entry__, which are returned in a list\. The newly created - instances should be destroyed when they are no longer used\. - - - *la* __read__ *base* *filter* *entry* \.\.\. *entry* - - This method reads one or more entries, using the same search criteria as - methods __traverse__ and __search__\. All attributes are stored in - the entries\. This method provides a quick way to read some entries\. It - returns the number of entries found in the directory \(which may be more than - the number of read entries\)\. If called without any *entry* argument, this - method just returns the number of entries found, without returning any data\. - - - *la* __commit__ *entry* \.\.\. *entry* - - This method commits the changes stored in the *entry* arguments\. Each - *entry* may be either a *change* entry, or a *standard* entry with a - backup\. - - Note: in the future, this method should use the LDAP transaction extension - provided by OpenLDAP 2\.3 and later\. - -## Ldap Example - - package require ldapx - - # - # Connects to the LDAP directory using StartTLS - # - - ::ldapx::ldap create l - l configure -tlsoptions {-cadir /etc/ssl/certs -request yes -require yes} - set url "ldap://server.mycomp.com" - if {! [l connect $url "cn=admin,o=mycomp" "mypasswd" yes]} then { - puts stderr "error: [l error]" - exit 1 - } - - # - # Search all entries matching some criterion - # - - l configure -scope one - ::ldapx::entry create e - set n 0 - l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e { - puts "dn: [e dn]" - puts " sn: [e get1 sn]" - puts " givenName: [e get1 givenName]" - incr n - } - puts "$n entries found" - e destroy - - # - # Add a telephone number to some entries - # Note this modification cannot be done in the "traverse" operation. - # - - set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}] - ::ldapx::entry create c - foreach e $lent { - $e backup - $e add1 "telephoneNumber" "+31415926535" - c diff $e - if {! [l commit c]} then { - puts stderr "error: [l error]" - exit 1 - } - $e destroy - } - c destroy - - l disconnect - l destroy - -# LDIF CLASS - -## Ldif Instance Data - -An instance of the __ldif__ class keeps the following data: - - - channel - - This is the Tcl channel used to retrieve or store LDIF file contents\. The - association between an instance and a channel is made by the method - __channel__\. There is no need to disrupt this association when the LDIF - file operation has ended\. - - - format - - LDIF files may contain *standard* entries or *change* entries, but not - both\. This variable contains the detected format of the file \(when reading\) - or the format of entries written to the file \(when writing\)\. - - - lastError - - This variable contains the error message which appeared in the last method - of the __ldif__ class \(this string is modified in nearly all methods\)\. - The __error__ method may be used to fetch this message\. - - - version - - This is the version of the LDIF file\. Only version 1 is supported: the - method __read__ can only read from version 1 files, and method - __write__ only creates version 1 files\. - -## Ldif Options - -This class defines two options: - - - __\-ignore__ list\-of\-attributes - - This option is used to ignore certain attribute names on reading\. For - example, to read OpenLDAP replica files \(replog\), one must ignore - __replica__ and __time__ attributes since they do not conform to the - RFC 2849 standard for LDIF files\. - - Default is empty list: no attribute is ignored\. - - - __\-utf8__ pattern\-yes pattern\-no - - Specify which attribute values are encoded in UTF\-8\. This information is - specific to the LDAP schema in use by the application, since some attributes - such as jpegPhoto, for example, are not encoded in UTF\-8\. This option takes - the form of a list with two regular expressions suitable for the - __regexp__ command \(anchored by ^ and $\)\. The first specifies which - attribute names are to be UTF\-8 encoded, and the second selects, among - those, the attribute names which will not be UTF\-8 encoded\. It is thus - possible to say: convert all attributes, except jpegPhoto\. - - Default is \{\{\.\*\} \{\}\}, meaning: all attributes are converted, without - exception\. - -## Ldif Methods - - - *li* __channel__ *chan* - - This method associates the Tcl channel named *chan* with the LDIF - instance\. It resets the type of LDIF object to *uninitialized*\. - - - *li* __error__ ?*newmsg*? - - This method returns the error message that occurred in the last call to a - __ldif__ class method\. If the optional argument *newmsg* is supplied, - it becomes the last error message\. - - - *li* __read__ *entry* - - This method reads the next entry from the LDIF file and stores it in the - *entry* object of class __entry__\. The entry may be a *standard* or - *change* entry\. - - - *li* __write__ *entry* - - This method writes the entry given in the argument *entry* to the LDIF - file\. - -## Ldif Example - - package require ldapx - - # This examples reads a LDIF file containing entries, - # compare them to a LDAP directory, and writes on standard - # output an LDIF file containing changes to apply to the - # LDAP directory to match exactly the LDIF file. - - ::ldapx::ldif create liin - liin channel stdin - - ::ldapx::ldif create liout - liout channel stdout - - ::ldapx::ldap create la - if {! [la connect "ldap://server.mycomp.com"]} then { - puts stderr "error: [la error]" - exit 1 - } - la configure -scope one - - # Reads LDIF file - - ::ldapx::entry create e1 - ::ldapx::entry create e2 - ::ldapx::entry create c - - while {[liin read e1] != 0} { - set base [e1 superior] - set id [e1 rdn] - if {[la read $base "($id)" e2] == 0} then { - e2 reset - } - - c diff e1 e2 - if {[llength [c change]] != 0} then { - liout write c - } - } - - la disconnect - la destroy - e1 destroy - e2 destroy - c destroy - liout destroy - liin destroy - -# References - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ldap* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[directory access](\.\./\.\./\.\./\.\./index\.md\#directory\_access), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap), [ldap -client](\.\./\.\./\.\./\.\./index\.md\#ldap\_client), -[ldif](\.\./\.\./\.\./\.\./index\.md\#ldif), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), [rfc -2251](\.\./\.\./\.\./\.\./index\.md\#rfc\_2251), [rfc -2849](\.\./\.\./\.\./\.\./index\.md\#rfc\_2849) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2006\-2018 Pierre David DELETED embedded/md/tcllib/files/modules/log/log.md Index: embedded/md/tcllib/files/modules/log/log.md ================================================================== --- embedded/md/tcllib/files/modules/log/log.md +++ embedded/md/tcllib/files/modules/log/log.md @@ -1,318 +0,0 @@ - -[//000000001]: # (log \- Logging facility) -[//000000002]: # (Generated from file 'log\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2001\-2009 Andreas Kupries ) -[//000000004]: # (log\(n\) 1\.4 tcllib "Logging facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -log \- Procedures to log messages of libraries and applications\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [LEVELS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8 -package require log ?1\.4? - -[__::log::levels__](#1) -[__::log::lv2longform__ *level*](#2) -[__::log::lv2color__ *level*](#3) -[__::log::lv2priority__ *level*](#4) -[__::log::lv2cmd__ *level*](#5) -[__::log::lv2channel__ *level*](#6) -[__::log::lvCompare__ *level1* *level2*](#7) -[__::log::lvSuppress__ *level* \{*suppress* 1\}](#8) -[__::log::lvSuppressLE__ *level* \{*suppress* 1\}](#9) -[__::log::lvIsSuppressed__ *level*](#10) -[__::log::lvCmd__ *level* *cmd*](#11) -[__::log::lvCmdForall__ *cmd*](#12) -[__::log::lvChannel__ *level* *chan*](#13) -[__::log::lvChannelForall__ *chan*](#14) -[__::log::lvColor__ *level* *color*](#15) -[__::log::lvColorForall__ *color*](#16) -[__::log::log__ *level* *text*](#17) -[__::log::logarray__ *level* *arrayvar* ?*pattern*?](#18) -[__::log::loghex__ *level* *text* *data*](#19) -[__::log::logsubst__ *level* *msg*](#20) -[__::log::logMsg__ *text*](#21) -[__::log::logError__ *text*](#22) -[__::log::Puts__ *level* *text*](#23) - -# DESCRIPTION - -The __log__ package provides commands that allow libraries and applications -to selectively log information about their internal operation and state\. - -To use the package just execute - - package require log - log::log notice "Some message" - -As can be seen above, each message given to the log facility is associated with -a *level* determining the importance of the message\. The user can then select -which levels to log, what commands to use for the logging of each level and the -channel to write the message to\. In the following example the logging of all -message with level __debug__ is deactivated\. - - package require log - log::lvSuppress debug - log::log debug "Unseen message" ; # No output - -By default all messages associated with an error\-level \(__emergency__, -__alert__, __critical__, and __error__\) are written to -__stderr__\. Messages with any other level are written to __stdout__\. In -the following example the log module is reconfigured to write __debug__ -messages to __stderr__ too\. - - package require log - log::lvChannel debug stderr - log::log debug "Written to stderr" - -Each message level is also associated with a command to use when logging a -message with that level\. The behaviour above for example relies on the fact that -all message levels use by default the standard command __::log::Puts__ to -log any message\. In the following example all messages of level __notice__ -are given to the non\-standard command __toText__ for logging\. This disables -the channel setting for such messages, assuming that __toText__ does not use -it by itself\. - - package require log - log::lvCmd notice toText - log::log notice "Handled by \"toText\"" - -Another database maintained by this facility is a map from message levels to -colors\. The information in this database has *no* influence on the behaviour -of the module\. It is merely provided as a convenience and in anticipation of the -usage of this facility in __tk__\-based application which may want to -colorize message logs\. - -# API - -The following commands are available: - - - __::log::levels__ - - Returns the names of all known levels, in alphabetical order\. - - - __::log::lv2longform__ *level* - - Converts any unique abbreviation of a level name to the full level name\. - - - __::log::lv2color__ *level* - - Converts any level name including unique abbreviations to the corresponding - color\. - - - __::log::lv2priority__ *level* - - Converts any level name including unique abbreviations to the corresponding - priority\. - - - __::log::lv2cmd__ *level* - - Converts any level name including unique abbreviations to the command prefix - used to write messages with that level\. - - - __::log::lv2channel__ *level* - - Converts any level name including unique abbreviations to the channel used - by __::log::Puts__ to write messages with that level\. - - - __::log::lvCompare__ *level1* *level2* - - Compares two levels \(including unique abbreviations\) with respect to their - priority\. This command can be used by the \-command option of lsort\. The - result is one of \-1, 0 or 1 or an error\. A result of \-1 signals that level1 - is of less priority than level2\. 0 signals that both levels have the same - priority\. 1 signals that level1 has higher priority than level2\. - - - __::log::lvSuppress__ *level* \{*suppress* 1\} - - \(Un\)suppresses the output of messages having the specified level\. Unique - abbreviations for the level are allowed here too\. - - - __::log::lvSuppressLE__ *level* \{*suppress* 1\} - - \(Un\)suppresses the output of messages having the specified level or one of - lesser priority\. Unique abbreviations for the level are allowed here too\. - - - __::log::lvIsSuppressed__ *level* - - Asks the package whether the specified level is currently suppressed\. Unique - abbreviations of level names are allowed\. - - - __::log::lvCmd__ *level* *cmd* - - Defines for the specified level with which command to write the messages - having this level\. Unique abbreviations of level names are allowed\. The - command is actually a command prefix and this facility will append 2 - arguments before calling it, the level of the message and the message - itself, in this order\. - - - __::log::lvCmdForall__ *cmd* - - Defines for all known levels with which command to write the messages having - this level\. The command is actually a command prefix and this facility will - append 2 arguments before calling it, the level of the message and the - message itself, in this order\. - - - __::log::lvChannel__ *level* *chan* - - Defines for the specified level into which channel __::log::Puts__ \(the - standard command\) shall write the messages having this level\. Unique - abbreviations of level names are allowed\. The command is actually a command - prefix and this facility will append 2 arguments before calling it, the - level of the message and the message itself, in this order\. - - - __::log::lvChannelForall__ *chan* - - Defines for all known levels with which which channel __::log::Puts__ - \(the standard command\) shall write the messages having this level\. The - command is actually a command prefix and this facility will append 2 - arguments before calling it, the level of the message and the message - itself, in this order\. - - - __::log::lvColor__ *level* *color* - - Defines for the specified level the color to return for it in a call to - __::log::lv2color__\. Unique abbreviations of level names are allowed\. - - - __::log::lvColorForall__ *color* - - Defines for all known levels the color to return for it in a call to - __::log::lv2color__\. Unique abbreviations of level names are allowed\. - - - __::log::log__ *level* *text* - - Log a message according to the specifications for commands, channels and - suppression\. In other words: The command will do nothing if the specified - level is suppressed\. If it is not suppressed the actual logging is delegated - to the specified command\. If there is no command specified for the level the - message won't be logged\. The standard command __::log::Puts__ will write - the message to the channel specified for the given level\. If no channel is - specified for the level the message won't be logged\. Unique abbreviations of - level names are allowed\. Errors in the actual logging command are *not* - caught, but propagated to the caller, as they may indicate misconfigurations - of the log facility or errors in the callers code itself\. - - - __::log::logarray__ *level* *arrayvar* ?*pattern*? - - Like __::log::log__, but logs the contents of the specified array - variable *arrayvar*, possibly restricted to entries matching the - *pattern*\. The pattern defaults to __\*__ \(i\.e\. all entries\) if none - was specified\. - - - __::log::loghex__ *level* *text* *data* - - Like __::log::log__, but assumes that *data* contains binary data\. It - converts this into a mixed hex/ascii representation before writing them to - the log\. - - - __::log::logsubst__ *level* *msg* - - Like __::log::log__, but *msg* may contain substitutions and variable - references, which are evaluated in the caller scope first\. The purpose of - this command is to avoid overhead in the non\-logging case, if the log - message building is expensive\. Any substitution errors raise an error in the - command execution\. The following example shows an xml text representation, - which is only generated in debug mode: - - log::logsubst debug {XML of node $node is '[$node toXml]'} - - - __::log::logMsg__ *text* - - Convenience wrapper around __::log::log__\. Equivalent to __::log::log - info text__\. - - - __::log::logError__ *text* - - Convenience wrapper around __::log::log__\. Equivalent to __::log::log - error text__\. - - - __::log::Puts__ *level* *text* - - The standard log command, it writes messages and their levels to - user\-specified channels\. Assumes that the suppression checks were done by - the caller\. Expects full level names, abbreviations are *not allowed*\. - -# LEVELS - -The package currently defines the following log levels, the level of highest -importance listed first\. - - - emergency - - - alert - - - critical - - - error - - - warning - - - notice - - - info - - - debug - -*Note* that by default all messages with levels __warning__ down to -__debug__ are suppressed\. This is done intentionally, because \(we believe -that\) in most situations debugging output is not wanted\. Most people wish to -have such output only when actually debugging an application\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *log* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[log](\.\./\.\./\.\./\.\./index\.md\#log), [log -level](\.\./\.\./\.\./\.\./index\.md\#log\_level), -[message](\.\./\.\./\.\./\.\./index\.md\#message), [message -level](\.\./\.\./\.\./\.\./index\.md\#message\_level) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2001\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/log/logger.md Index: embedded/md/tcllib/files/modules/log/logger.md ================================================================== --- embedded/md/tcllib/files/modules/log/logger.md +++ embedded/md/tcllib/files/modules/log/logger.md @@ -1,460 +0,0 @@ - -[//000000001]: # (logger \- Object Oriented logging facility) -[//000000002]: # (Generated from file 'logger\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (logger\(n\) 0\.9\.4 tcllib "Object Oriented logging facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -logger \- System to control logging of events\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [IMPLEMENTATION](#section2) - - - [Logprocs and Callstack](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require logger ?0\.9\.4? - -[__logger::init__ *service*](#1) -[__logger::import__ ?__\-all__? ?__\-force__? ?__\-prefix__ *prefix*? ?__\-namespace__ *namespace*? *service*](#2) -[__logger::initNamespace__ *ns* ?*level*?](#3) -[__logger::services__](#4) -[__logger::enable__ *level*](#5) -[__logger::disable__ *level*](#6) -[__logger::setlevel__ *level*](#7) -[__logger::levels__](#8) -[__logger::servicecmd__ *service*](#9) -[__$\{log\}::debug__ *message*](#10) -[__$\{log\}::info__ *message*](#11) -[__$\{log\}::notice__ *message*](#12) -[__$\{log\}::warn__ *message*](#13) -[__$\{log\}::error__ *message*](#14) -[__$\{log\}::critical__ *message*](#15) -[__$\{log\}::alert__ *message*](#16) -[__$\{log\}::emergency__ *message*](#17) -[__$\{log\}::setlevel__ *level*](#18) -[__$\{log\}::enable__ *level*](#19) -[__$\{log\}::disable__ *level*](#20) -[__$\{log\}::lvlchangeproc__ *command*](#21) -[__$\{log\}::lvlchangeproc__](#22) -[__$\{log\}::logproc__ *level*](#23) -[__$\{log\}::logproc__ *level* *command*](#24) -[__$\{log\}::logproc__ *level* *argname* *body*](#25) -[__$\{log\}::services__](#26) -[__$\{log\}::servicename__](#27) -[__$\{log\}::currentloglevel__](#28) -[__$\{log\}::delproc__ *command*](#29) -[__$\{log\}::delproc__](#30) -[__$\{log\}::delete__](#31) -[__$\{log\}::trace__ *command*](#32) -[__$\{log\}::trace__ __on__](#33) -[__$\{log\}::trace__ __off__](#34) -[__$\{log\}::trace__ __status__ ?procName? ?\.\.\.?](#35) -[__$\{log\}::trace__ __add__ *procName* ?\.\.\.?](#36) -[__$\{log\}::trace__ __add__ ?\-ns? *nsName* ?\.\.\.?](#37) -[__$\{log\}::trace__ __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *procName* ?\.\.\.?](#38) -[__$\{log\}::trace__ __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ ?\-ns? *nsName* ?\.\.\.?](#39) - -# DESCRIPTION - -The __logger__ package provides a flexible system for logging messages from -different services, at priority levels, with different commands\. - -To begin using the logger package, we do the following: - - package require logger - set log [logger::init myservice] - ${log}::notice "Initialized myservice logging" - - ... code ... - - ${log}::notice "Ending myservice logging" - ${log}::delete - -In the above code, after the package is loaded, the following things happen: - - - __logger::init__ *service* - - Initializes the service *service* for logging\. The service names are - actually Tcl namespace names, so they are separated with '::'\. The service - name may not be the empty string or only ':'s\. When a logger service is - initialized, it "inherits" properties from its parents\. For instance, if - there were a service *foo*, and we did a __logger::init__ *foo::bar* - \(to create a *bar* service underneath *foo*\), *bar* would copy the - current configuration of the *foo* service, although it would of course, - also be possible to then separately configure *bar*\. If a logger service - is initialized and the parent does not yet exist, the parent is also - created\. The new logger service is initialized with the default loglevel set - with __logger::setlevel__\. - - - __logger::import__ ?__\-all__? ?__\-force__? ?__\-prefix__ *prefix*? ?__\-namespace__ *namespace*? *service* - - Import the logger service commands into the current namespace\. Without the - __\-all__ option only the commands corresponding to the log levels are - imported\. If __\-all__ is given, all the __$\{log\}::cmd__ style - commands are imported\. If the import would overwrite a command an error is - returned and no command is imported\. Use the __\-force__ option to force - the import and overwrite existing commands without complaining\. If the - __\-prefix__ option is given, the commands are imported with the given - *prefix* prepended to their names\. If the __\-namespace__ option is - given, the commands are imported into the given namespace\. If the namespace - does not exist, it is created\. If a namespace without a leading :: is given, - it is interpreted as a child namespace to the current namespace\. - - - __logger::initNamespace__ *ns* ?*level*? - - Convenience command for setting up a namespace for logging\. Creates a logger - service named after the namespace *ns* \(a :: prefix is stripped\), imports - all the log commands into the namespace, and sets the default logging level, - either as specified by *level*, or inherited from a service in the parent - namespace, or a hardwired default, __warn__\. - - - __logger::services__ - - Returns a list of all the available services\. - - - __logger::enable__ *level* - - Globally enables logging at and "above" the given level\. Levels are - __debug__, __info__, __notice__, __warn__, __error__, - __critical__, __alert__, __emergency__\. - - - __logger::disable__ *level* - - Globally disables logging at and "below" the given level\. Levels are those - listed above\. - - - __logger::setlevel__ *level* - - Globally enable logging at and "above" the given level\. Levels are those - listed above\. This command changes the default loglevel for new loggers - created with __logger::init__\. - - - __logger::levels__ - - Returns a list of the available log levels \(also listed above under - __enable__\)\. - - - __logger::servicecmd__ *service* - - Returns the __$\{log\}__ token created by __logger::init__ for this - service\. - - - __$\{log\}::debug__ *message* - - - __$\{log\}::info__ *message* - - - __$\{log\}::notice__ *message* - - - __$\{log\}::warn__ *message* - - - __$\{log\}::error__ *message* - - - __$\{log\}::critical__ *message* - - - __$\{log\}::alert__ *message* - - - __$\{log\}::emergency__ *message* - - These are the commands called to actually log a message about an event\. - __$\{log\}__ is the variable obtained from __logger::init__\. - - - __$\{log\}::setlevel__ *level* - - Enable logging, in the service referenced by __$\{log\}__, and its - children, at and above the level specified, and disable logging below it\. - - - __$\{log\}::enable__ *level* - - Enable logging, in the service referenced by __$\{log\}__, and its - children, at and above the level specified\. Note that this does *not* - disable logging below this level, so you should probably use - __setlevel__ instead\. - - - __$\{log\}::disable__ *level* - - Disable logging, in the service referenced by __$\{log\}__, and its - children, at and below the level specified\. Note that this does *not* - enable logging above this level, so you should probably use __setlevel__ - instead\. Disabling the loglevel __emergency__ switches logging off for - the service and its children\. - - - __$\{log\}::lvlchangeproc__ *command* - - - __$\{log\}::lvlchangeproc__ - - Set the script to call when the log instance in question changes its log - level\. If called without a command it returns the currently registered - command\. The command gets two arguments appended, the old and the new - loglevel\. The callback is invoked after all changes have been done\. If child - loggers are affected, their callbacks are called before their parents - callback\. - - proc lvlcallback {old new} { - puts "Loglevel changed from $old to $new" - } - ${log}::lvlchangeproc lvlcallback - - - __$\{log\}::logproc__ *level* - - - __$\{log\}::logproc__ *level* *command* - - - __$\{log\}::logproc__ *level* *argname* *body* - - This command comes in three forms \- the third, older one is deprecated and - may be removed from future versions of the logger package\. The current set - version takes one argument, a command to be executed when the level is - called\. The callback command takes on argument, the text to be logged\. If - called only with a valid level __logproc__ returns the name of the - command currently registered as callback command\. __logproc__ specifies - which command will perform the actual logging for a given level\. The logger - package ships with default commands for all log levels, but with - __logproc__ it is possible to replace them with custom code\. This would - let you send your logs over the network, to a database, or anything else\. - For example: - - proc logtoserver {txt} { - variable socket - puts $socket "Notice: $txt" - } - - ${log}::logproc notice logtoserver - - Trace logs are slightly different: instead of a plain text argument, the - argument provided to the logproc is a dictionary consisting of the - __enter__ or __leave__ keyword along with another dictionary of - details about the trace\. These include: - - * __proc__ \- Name of the procedure being traced\. - - * __level__ \- The stack level for the procedure invocation \(from - __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ __level__\)\. - - * __script__ \- The name of the file in which the procedure is defined, - or an empty string if defined in interactive mode\. - - * __caller__ \- The name of the procedure calling the procedure being - traced, or an empty string if the procedure was called from the global - scope \(stack level 0\)\. - - * __procargs__ \- A dictionary consisting of the names of arguments to - the procedure paired with values given for those arguments - \(__enter__ traces only\)\. - - * __status__ \- The Tcl return code \(e\.g\. __ok__, __continue__, - etc\.\) \(__leave__ traces only\)\. - - * __result__ \- The value returned by the procedure \(__leave__ - traces only\)\. - - - __$\{log\}::services__ - - Returns a list of the registered logging services which are children of this - service\. - - - __$\{log\}::servicename__ - - Returns the name of this service\. - - - __$\{log\}::currentloglevel__ - - Returns the currently enabled log level for this service\. If no logging is - enabled returns __none__\. - - - __$\{log\}::delproc__ *command* - - - __$\{log\}::delproc__ - - Set the script to call when the log instance in question is deleted\. If - called without a command it returns the currently registered command\. For - example: - - ${log}::delproc [list closesock $logsock] - - - __$\{log\}::delete__ - - This command deletes a particular logging service, and its children\. You - must call this to clean up the resources used by a service\. - - - __$\{log\}::trace__ *command* - - This command controls logging of enter/leave traces for specified - procedures\. It is used to enable and disable tracing, query tracing status, - and specify procedures are to be traced\. Trace handlers are unregistered - when tracing is disabled\. As a result, there is not performance impact to a - library when tracing is disabled, just as with other log level commands\. - - proc tracecmd { dict } { - puts $dict - } - - set log [::logger::init example] - ${log}::logproc trace tracecmd - - proc foo { args } { - puts "In foo" - bar 1 - return "foo_result" - } - - proc bar { x } { - puts "In bar" - return "bar_result" - } - - ${log}::trace add foo bar - ${log}::trace on - - foo - - # Output: - enter {proc ::foo level 1 script {} caller {} procargs {args {}}} - In foo - enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}} - In bar - leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result} - leave {proc ::foo level 1 script {} caller {} status ok result foo_result} - - - __$\{log\}::trace__ __on__ - - Turns on trace logging for procedures registered through the - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __add__ command\. This is - similar to the __enable__ command for other logging levels, but allows - trace logging to take place at any level\. The trace logging mechanism takes - advantage of the execution trace feature of Tcl 8\.4 and later\. The - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __on__ command will - return an error if called from earlier versions of Tcl\. - - - __$\{log\}::trace__ __off__ - - Turns off trace logging for procedures registered for trace logging through - the __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __add__ command\. - This is similar to the __disable__ command for other logging levels, but - allows trace logging to take place at any level\. Procedures are not - unregistered, so logging for them can be turned back on with the - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __on__ command\. There is - no overhead imposed by trace registration when trace logging is disabled\. - - - __$\{log\}::trace__ __status__ ?procName? ?\.\.\.? - - This command returns a list of the procedures currently registered for trace - logging, or a flag indicating whether or not a trace is registered for one - or more specified procedures\. - - - __$\{log\}::trace__ __add__ *procName* ?\.\.\.? - - - __$\{log\}::trace__ __add__ ?\-ns? *nsName* ?\.\.\.? - - This command registers one or more procedures for logging of entry/exit - traces\. Procedures can be specified via a list of procedure names or - namespace names \(in which case all procedure within the namespace are - targeted by the operation\)\. By default, each name is first interpreted as a - procedure name or glob\-style search pattern, and if not found its - interpreted as a namespace name\. The *\-ns* option can be used to force - interpretation of all provided arguments as namespace names\. Procedures must - be defined prior to registering them for tracing through the - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __add__ command\. Any - procedure or namespace names/patterns that don't match any existing - procedures will be silently ignored\. - - - __$\{log\}::trace__ __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *procName* ?\.\.\.? - - - __$\{log\}::trace__ __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ ?\-ns? *nsName* ?\.\.\.? - - This command unregisters one or more procedures so that they will no longer - have trace logging performed, with the same matching rules as that of the - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ __add__ command\. - -# IMPLEMENTATION - -The logger package is implemented in such a way as to optimize \(for Tcl 8\.4 and -newer\) log procedures which are disabled\. They are aliased to a proc which has -no body, which is compiled to a no op in bytecode\. This should make the -peformance hit minimal\. If you really want to pull out all the stops, you can -replace the $\{log\} token in your code with the actual namespace and command -\($\{log\}::warn becomes ::logger::tree::myservice::warn\), so that no variable -lookup is done\. This puts the performance of disabled logger commands very close -to no logging at all\. - -The "object orientation" is done through a hierarchy of namespaces\. Using an -actual object oriented system would probably be a better way of doing things, or -at least provide for a cleaner implementation\. - -The service "object orientation" is done with namespaces\. - -# Logprocs and Callstack - -The logger package takes extra care to keep the logproc out of the call stack\. -This enables logprocs to execute code in the callers scope by using uplevel or -linking to local variables by using upvar\. This may fire traces with all usual -side effects\. - - # Print caller and current vars in the calling proc - proc log_local_var {txt} { - set caller [info level -1] - set vars [uplevel 1 info vars] - foreach var [lsort $vars] { - if {[uplevel 1 [list array exists $var]] == 1} { - lappend val $var - } else { - lappend val $var [uplevel 1 [list set $var]] - } - } - puts "$txt" - puts "Caller: $caller" - puts "Variables in callers scope:" - foreach {var value} $val { - puts "$var = $value" - } - } - - # install as logproc - ${log}::logproc debug log_local_var - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *logger* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[log](\.\./\.\./\.\./\.\./index\.md\#log), [log -level](\.\./\.\./\.\./\.\./index\.md\#log\_level), -[logger](\.\./\.\./\.\./\.\./index\.md\#logger), -[service](\.\./\.\./\.\./\.\./index\.md\#service) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/log/loggerAppender.md Index: embedded/md/tcllib/files/modules/log/loggerAppender.md ================================================================== --- embedded/md/tcllib/files/modules/log/loggerAppender.md +++ embedded/md/tcllib/files/modules/log/loggerAppender.md @@ -1,105 +0,0 @@ - -[//000000001]: # (logger::appender \- Object Oriented logging facility) -[//000000002]: # (Generated from file 'loggerAppender\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Aamer Akhter ) -[//000000004]: # (logger::appender\(n\) 1\.2 tcllib "Object Oriented logging facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -logger::appender \- Collection of predefined appenders for logger - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require logger::appender ?1\.2? - -[__::logger::appender::console__ __\-level__ *level* __\-service__ *service* ?*options*\.\.\.?](#1) -[__::logger::appender::colorConsole__ __\-level__ *level* __\-service__ *service* ?*options*\.\.\.?](#2) - -# DESCRIPTION - -This package provides a predefined set of logger templates\. - - - __::logger::appender::console__ __\-level__ *level* __\-service__ *service* ?*options*\.\.\.? - - * __\-level__ level - - Name of the level to fill in as "priority" in the log procedure\. - - * __\-service__ service - - Name of the service to fill in as "category" in the log procedure\. - - * __\-appenderArgs__ appenderArgs - - Any additional arguments for the log procedure in list form - - * __\-conversionPattern__ conversionPattern - - The log pattern to use \(see __logger::utils::createLogProc__ for the - allowed substitutions\)\. - - * __\-procName__ procName - - Explicitly set the name of the created procedure\. - - * __\-procNameVar__ procNameVar - - Name of the variable to set in the calling context\. This variable will - contain the name of the procedure\. - - - __::logger::appender::colorConsole__ __\-level__ *level* __\-service__ *service* ?*options*\.\.\.? - - See __::logger::appender::colorConsole__ for a description of the - applicable options\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *logger* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[appender](\.\./\.\./\.\./\.\./index\.md\#appender), -[logger](\.\./\.\./\.\./\.\./index\.md\#logger) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2005 Aamer Akhter DELETED embedded/md/tcllib/files/modules/log/loggerUtils.md Index: embedded/md/tcllib/files/modules/log/loggerUtils.md ================================================================== --- embedded/md/tcllib/files/modules/log/loggerUtils.md +++ embedded/md/tcllib/files/modules/log/loggerUtils.md @@ -1,193 +0,0 @@ - -[//000000001]: # (logger::utils \- Object Oriented logging facility) -[//000000002]: # (Generated from file 'loggerUtils\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Aamer Akhter ) -[//000000004]: # (logger::utils\(n\) 1\.3\.1 tcllib "Object Oriented logging facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -logger::utils \- Utilities for logger - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require logger::utils ?1\.3\.1? - -[__::logger::utils::createFormatCmd__ *formatString*](#1) -[__::logger::utils::createLogProc__ __\-procName__ *procName* ?*options*\.\.\.?](#2) -[__::logger::utils::applyAppender__ __\-appender__ *appenderType* ?*options*\.\.\.?](#3) -[__::logger::utils::autoApplyAppender__ *command* *command\-string* *log* *op* *args*\.\.\.](#4) - -# DESCRIPTION - -This package adds template based *appenders*\. - - - __::logger::utils::createFormatCmd__ *formatString* - - This command translates *formatString* into an expandable command string\. - The following strings are the known substitutions \(from log4perl\) allowed to - occur in the *formatString*: - - * %c - - Category of the logging event - - * %C - - Fully qualified name of logging event - - * %d - - Current date in yyyy/MM/dd hh:mm:ss - - * %H - - Hostname - - * %m - - Message to be logged - - * %M - - Method where logging event was issued - - * %p - - Priority of logging event - - * %P - - Pid of current process - - - __::logger::utils::createLogProc__ __\-procName__ *procName* ?*options*\.\.\.? - - This command \.\.\. - - * __\-procName__ procName - - The name of the procedure to create\. - - * __\-conversionPattern__ pattern - - See __::logger::utils::createFormatCmd__ for the substitutions - allowed in the *pattern*\. - - * __\-category__ category - - The category \(service\)\. - - * __\-priority__ priority - - The priority \(level\)\. - - * __\-outputChannel__ channel - - channel to output on \(default stdout\) - - - __::logger::utils::applyAppender__ __\-appender__ *appenderType* ?*options*\.\.\.? - - This command will create an appender for the specified logger services\. If - no service is specified then the appender will be added as the default - appender for the specified levels\. If no levels are specified, then all - levels are assumed\. - - * __\-service__ loggerservices - - * __\-serviceCmd__ loggerserviceCmds - - Name of the logger instance to modify\. __\-serviceCmd__ takes as - input the return of __logger::init__\. - - * __\-appender__ appenderType - - Type of the appender to use\. One of __console__, - __colorConsole__\. - - * __\-appenderArgs__ appenderArgs - - Additional arguments to apply to the appender\. The argument of the - option is a list of options and their arguments\. - - For example - - logger::utils::applyAppender -serviceCmd $log -appender console -appenderArgs {-conversionPattern {\[%M\] \[%p\] - %m}} - - The usual Tcl quoting rules apply\. - - * __\-levels__ levelList - - The list of levels to apply this appender to\. If not specified all - levels are assumed\. - - Example of usage: - - % set log [logger::init testLog] - ::logger::tree::testLog - % logger::utils::applyAppender -appender console -serviceCmd $log - % ${log}::error "this is an error" - [2005/08/22 10:14:13] [testLog] [global] [error] this is an error - - - __::logger::utils::autoApplyAppender__ *command* *command\-string* *log* *op* *args*\.\.\. - - This command is designed to be added via __trace leave__ to calls of - __logger::init__\. It will look at preconfigured state \(via - __::logger::utils::applyAppender__\) to autocreate appenders for newly - created logger instances\. It will return its argument *log*\. - - Example of usage: - - logger::utils::applyAppender -appender console - set log [logger::init applyAppender-3] - ${log}::error "this is an error" - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *logger* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[appender](\.\./\.\./\.\./\.\./index\.md\#appender), -[logger](\.\./\.\./\.\./\.\./index\.md\#logger) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2005 Aamer Akhter DELETED embedded/md/tcllib/files/modules/map/map_geocode_nominatim.md Index: embedded/md/tcllib/files/modules/map/map_geocode_nominatim.md ================================================================== --- embedded/md/tcllib/files/modules/map/map_geocode_nominatim.md +++ embedded/md/tcllib/files/modules/map/map_geocode_nominatim.md @@ -1,168 +0,0 @@ - -[//000000001]: # (map::geocode::nominatim \- Mapping utilities) -[//000000002]: # (Generated from file 'map\_geocode\_nominatim\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (map::geocode::nominatim\(n\) 0\.1 tcllib "Mapping utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -map::geocode::nominatim \- Resolving geographical names with a Nominatim service - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#subsection1) - - - [Methods](#subsection2) - - - [References](#section3) - - - [Keywords](#keywords) - -# SYNOPSIS - -package require Tcl 8\.5 -package require http -package require json -package require uri -package require snit -package require map::geocode::nominatim ?0\.1? - -[__::map::geocode::nominatim__ *requestor* ?__\-baseurl__ *url*? ?__\-callback__ *callback*? ?__\-error__ *error callback*?](#1) -[__$cmdprefix__ *result*](#2) -[__$cmdprefix__ *errorstring*](#3) -[*requestor* __search__ *query*](#4) - -# DESCRIPTION - -This package provides a class for accessing geocoding services which implement -the *[Nominatim](\.\./\.\./\.\./\.\./index\.md\#nominatim)* interface \(see -[References](#section3)\) - -# API - - - __::map::geocode::nominatim__ *requestor* ?__\-baseurl__ *url*? ?__\-callback__ *callback*? ?__\-error__ *error callback*? - - Creates a geocoding request object *requestor*, which will send its - requests to the *[Nominatim](\.\./\.\./\.\./\.\./index\.md\#nominatim)* server\. - - The result of the command is *name*\. - -## Options - - - __\-baseurl__ *url* - - The base URL of the *[Nominatim](\.\./\.\./\.\./\.\./index\.md\#nominatim)* - service\. Default value is *OpenStreetMap's* service at - [http://nominatim\.openstreetmap\.org/search](http://nominatim\.openstreetmap\.org/search) - A possible free alternative is at - [http://open\.mapquestapi\.com//nominatim/v1/search](http://open\.mapquestapi\.com//nominatim/v1/search) - - - __\-callback__ *cmdprefix* - - A command prefix to be invoked when search result become available\. The - default setting, active when nothing was specified on object creation, is to - print the *result* \(see below\) to - *[stdout](\.\./\.\./\.\./\.\./index\.md\#stdout)*\. The result of the command - prefix is ignored\. Errors thrown by the command prefix are caught and cause - the invokation of the error callback \(see option __\-error__ below\), with - the error message as argument\. - - The signature of the command prefix is: - - * __$cmdprefix__ *result* - - The *result* is a list of dictionaries, containing one item per hit\. - Each dictionary will have the following entries: - - + place\_id - - The place ID \(FIXME: what's this?\) - - + licence - - The data licence string - - + osm\_type - - The OSM type of the location - - + osm\_id - - FIXME - - + boundingbox - - The coordinates of the bounding box \(min and max latitude, min and - max longitude\) - - + lat - - The location's latitude - - + lon - - The location's longitude - - + display\_name - - the location's human readable name - - + class - - FIXME - - + type - - FIXME - - + icon - - FIXME - - - __\-error__ *cmdprefix* - - A command prefix to be invoked when encountering errors\. Typically these are - HTTP errors\. The default setting, active when nothing was specified on - object creation, is to print the *errorstring* \(see below\) to *stderr*\. - The result of the command prefix is ignored\. Errors thrown by the command - prefix are passed to higher levels\. - - The signature of the command prefix is: - - * __$cmdprefix__ *errorstring* - -## Methods - - - *requestor* __search__ *query* - - This method returns a list of dictionaries, one item per hit for the - specified *query*\. - -# References - - 1. [http://wiki\.openstreetmap\.org/wiki/Nominatim](http://wiki\.openstreetmap\.org/wiki/Nominatim) - - 1. [http://open\.mapquestapi\.com/nominatim/](http://open\.mapquestapi\.com/nominatim/) - -# KEYWORDS - -[geocoding](\.\./\.\./\.\./\.\./index\.md\#geocoding), -[http](\.\./\.\./\.\./\.\./index\.md\#http), -[location](\.\./\.\./\.\./\.\./index\.md\#location), -[map](\.\./\.\./\.\./\.\./index\.md\#map), -[nominatim](\.\./\.\./\.\./\.\./index\.md\#nominatim), -[server](\.\./\.\./\.\./\.\./index\.md\#server), [url](\.\./\.\./\.\./\.\./index\.md\#url) DELETED embedded/md/tcllib/files/modules/map/map_slippy.md Index: embedded/md/tcllib/files/modules/map/map_slippy.md ================================================================== --- embedded/md/tcllib/files/modules/map/map_slippy.md +++ embedded/md/tcllib/files/modules/map/map_slippy.md @@ -1,218 +0,0 @@ - -[//000000001]: # (map::slippy \- Mapping utilities) -[//000000002]: # (Generated from file 'map\_slippy\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (map::slippy\(n\) 0\.5 tcllib "Mapping utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -map::slippy \- Common code for slippy based map packages - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Coordinate systems](#section3) - - - [Geographic](#subsection1) - - - [Tiles](#subsection2) - - - [Pixels/Points](#subsection3) - - - [References](#section4) - - - [Keywords](#keywords) - -# SYNOPSIS - -package require Tcl 8\.4 -package require Tk 8\.4 -package require map::slippy ?0\.5? - -[__::map::slippy__ __length__ *level*](#1) -[__::map::slippy__ __tiles__ *level*](#2) -[__::map::slippy__ __tile size__](#3) -[__::map::slippy__ __tile valid__ *tile* *levels* ?*msgvar*?](#4) -[__::map::slippy__ __geo 2tile__ *geo*](#5) -[__::map::slippy__ __geo 2tile\.float__ *geo*](#6) -[__::map::slippy__ __geo 2point__ *geo*](#7) -[__::map::slippy__ __tile 2geo__ *tile*](#8) -[__::map::slippy__ __tile 2point__ *tile*](#9) -[__::map::slippy__ __point 2geo__ *point*](#10) -[__::map::slippy__ __point 2tile__ *point*](#11) -[__::map::slippy__ __fit geobox__ *canvdim* *geobox* *zmin* *zmax*](#12) - -# DESCRIPTION - -This package provides a number of methods doing things needed by all types of -slippy\-based map packages\. - -# API - - - __::map::slippy__ __length__ *level* - - This method returns the width/height of a slippy\-based map at the specified - zoom *level*, in pixels\. This is, in essence, the result of - - expr { [tiles $level] * [tile size] } - - - __::map::slippy__ __tiles__ *level* - - This method returns the width/height of a slippy\-based map at the specified - zoom *level*, in *tiles*\. - - - __::map::slippy__ __tile size__ - - This method returns the width/height of a tile in a slippy\-based map, in - pixels\. - - - __::map::slippy__ __tile valid__ *tile* *levels* ?*msgvar*? - - This method checks whether *tile* described a valid tile in a slippy\-based - map containing that many zoom *levels*\. The result is a boolean value, - __true__ if the tile is valid, and __false__ otherwise\. For the - latter a message is left in the variable named by *msgvar*, should it be - specified\. - - A tile identifier as stored in *tile* is a list containing zoom level, - tile row, and tile column, in this order\. The command essentially checks - this, i\.e\. the syntax, that the zoom level is between 0 and "*levels*\-1", - and that the row/col information is within the boundaries for the zoom - level, i\.e\. 0 \.\.\. "\[tiles $zoom\]\-1"\. - - - __::map::slippy__ __geo 2tile__ *geo* - - Converts a geographical location at a zoom level \(*geo*, a list containing - zoom level, latitude, and longitude, in this order\) to a tile identifier - \(list containing zoom level, row, and column\) at that level\. The tile - identifier uses pure integer numbers for the tile coordinates, for all - geographic coordinates mapping to that tile\. - - - __::map::slippy__ __geo 2tile\.float__ *geo* - - Converts a geographical location at a zoom level \(*geo*, a list containing - zoom level, latitude, and longitude, in this order\) to a tile identifier - \(list containing zoom level, row, and column\) at that level\. The tile - identifier uses floating point numbers for the tile coordinates, - representing not only the tile the geographic coordinates map to, but also - the fractional location inside of that tile\. - - - __::map::slippy__ __geo 2point__ *geo* - - Converts a geographical location at a zoom level \(*geo*, a list containing - zoom level, latitude, and longitude, in this order\) to a pixel position - \(list containing zoom level, y, and x\) at that level\. - - - __::map::slippy__ __tile 2geo__ *tile* - - Converts a tile identifier at a zoom level \(*tile*, list containing zoom - level, row, and column\) to a geographical location \(list containing zoom - level, latitude, and longitude, in this order\) at that level\. - - - __::map::slippy__ __tile 2point__ *tile* - - Converts a tile identifier at a zoom level \(*tile*, a list containing zoom - level, row, and column, in this order\) to a pixel position \(list containing - zoom level, y, and x\) at that level\. - - - __::map::slippy__ __point 2geo__ *point* - - Converts a pixel position at a zoom level \(*point*, list containing zoom - level, y, and x\) to a geographical location \(list containing zoom level, - latitude, and longitude, in this order\) at that level\. - - - __::map::slippy__ __point 2tile__ *point* - - Converts a pixel position at a zoom level \(*point*, a list containing zoom - level, y, and x, in this order\) to a tile identifier \(list containing zoom - level, row, and column\) at that level\. - - - __::map::slippy__ __fit geobox__ *canvdim* *geobox* *zmin* *zmax* - - Calculates the zoom level \(whithin the bounds *zmin* and *zmax*\) such - that *geobox* \(a 4\-element list containing the latitudes and longitudes - lat0, lat1, lon0 and lon1 of a geo box, in this order\) fits into a viewport - given by *canvdim*, a 2\-element list containing the width and height of - the viewport, in this order\. - -# Coordinate systems - -The commands of this package operate on three distinct coordinate systems, which -are explained below\. - -## Geographic - -*Geographic*al coordinates are represented by *Latitude* and -*[Longitude](\.\./\.\./\.\./\.\./index\.md\#longitude)*, each of which is measured -in degrees, as they are essentially angles\. - -__Zero__ longitude is the *Greenwich meridian*, with positive values going -*east*, and negative values going *west*, for a total range of \+/\- 180 -degrees\. Note that \+180 and \-180 longitude are the same *meridian*, opposite -to greenwich\. - -__zero__ latitude the *Equator*, with positive values going *north* and -negative values going *south*\. While the true range is \+/\- 90 degrees the -projection used by the package requires us to cap the range at \+/\- -85\.05112877983284 degrees\. This means that north and south pole are not -representable and not part of any map\. - -## Tiles - -While [Geographic](#subsection1)al coordinates of the previous section are -independent of zoom level the *tile coordinates* are not\. - -Generally the integer part of tile coordinates represent the row and column -number of the tile in question, wheras the fractional parts signal how far -inside the tile the location in question is, with pure integer coordinates \(no -fractional part\) representing the upper left corner of the tile\. - -The zero point of the map is at the upper left corner, regardless of zoom level, -with larger coordinates going right \(east\) and down \(south\), and smaller -coordinates going left \(west\) and up \(north\)\. Again regardless of zxoom level\. - -Negative tile coordinates are not allowed\. - -At zoom level 0 the whole map is represented by a single, putting the geographic -zero at 1/2, 1/2 of tile coordinates, and the range of tile coordinates as -\[0\.\.\.1\]\. - -To go from a zoom level N to the next deeper level N\+1 each tile of level N is -split into its four quadrants, which then are the tiles of level N\+1\. - -This means that at zoom level N the map is sliced \(horizontally and vertically\) -into 2^N stripes, for a total of 4^N tiles, with tile coordinates ranging from 0 -to 2^N\+1\. - -## Pixels/Points - -*pixel coordinates*, also called *point coordinates* are in essence [tile -coordinates](#subsection2) scaled by the size of the image representing a -tile\. This tile size currently has a fixed value, __256__\. - -# References - - 1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page) - -# KEYWORDS - -[geodesy](\.\./\.\./\.\./\.\./index\.md\#geodesy), -[geography](\.\./\.\./\.\./\.\./index\.md\#geography), -[latitute](\.\./\.\./\.\./\.\./index\.md\#latitute), -[location](\.\./\.\./\.\./\.\./index\.md\#location), -[longitude](\.\./\.\./\.\./\.\./index\.md\#longitude), -[map](\.\./\.\./\.\./\.\./index\.md\#map), [slippy](\.\./\.\./\.\./\.\./index\.md\#slippy), -[zoom](\.\./\.\./\.\./\.\./index\.md\#zoom) DELETED embedded/md/tcllib/files/modules/map/map_slippy_cache.md Index: embedded/md/tcllib/files/modules/map/map_slippy_cache.md ================================================================== --- embedded/md/tcllib/files/modules/map/map_slippy_cache.md +++ embedded/md/tcllib/files/modules/map/map_slippy_cache.md @@ -1,113 +0,0 @@ - -[//000000001]: # (map::slippy::cache \- Mapping utilities) -[//000000002]: # (Generated from file 'map\_slippy\_cache\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (map::slippy::cache\(n\) 0\.2 tcllib "Mapping utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -map::slippy::cache \- Management of a tile cache in the local filesystem - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Methods](#subsection1) - - - [References](#section3) - - - [Keywords](#keywords) - -# SYNOPSIS - -package require Tcl 8\.4 -package require Tk 8\.4 -package require img::png -package require map::slippy -package require map::slippy::cache ?0\.2? - -[__::map::slippy::cache__ *cacheName* *cachedir* *provider*](#1) -[*cacheName* __valid__ *tile* ?*msgvar*?](#2) -[*cacheName* __exists__ *tile*](#3) -[*cacheName* __get__ *tile* *donecmd*](#4) - -# DESCRIPTION - -This package provides a class for managing a cache of tiles for slippy\-based -maps in the local filesystem\. - -# API - - - __::map::slippy::cache__ *cacheName* *cachedir* *provider* - - Creates the cache *cacheName* and configures it with both the path to the - directory contaiing the locally cached tiles \(*cachedir*\), and the command - prefix from which it will pull tiles asked for and not yet known to the - cache itself \(*provider*\)\. - - The result of the command is *cacheName*\. - -## Methods - - - *cacheName* __valid__ *tile* ?*msgvar*? - - This method checks the validity of a the given *tile* identifier\. This is - a convenience wrapper to __::map::slippy tile valid__ and has the same - interface\. - - - *cacheName* __exists__ *tile* - - This methods tests whether the cache contains the specified *tile* or not\. - The result is a boolean value, __true__ if the tile is known, and - __false__ otherwise\. The tile is identified by a list containing three - elements, zoom level, row, and column number, in this order\. - - - *cacheName* __get__ *tile* *donecmd* - - This is the main method of the cache, retrieving the image for the specified - *tile* from the cache\. The tile identifier is a list containing three - elements, the zoom level, row, and column number of the tile, in this order\. - - The command refix *donecmd* will be invoked when the cache either knows - the image for the tile or that no image will forthcoming\. It will be invoked - with either 2 or 3 arguments, i\.e\. - - 1. The string __set__, the *tile*, and the image\. - - 1. The string __unset__, and the *tile*\. - - These two possibilities are used to either signal the image for the - *tile*, or that the *tile* has no image defined for it\. - - When the cache has no information about the tile it will invoke the - *provider* command prefix specified during its construction, adding three - arguments: The string __get__, the *tile*, and a callback into the - cache\. The latter will be invoked by the provider to either transfer the - image to the cache, or signal that the tile has no image\. - - When multiple requests for the same tile are made only one request will be - issued to the provider\. - -# References - - 1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page) - -# KEYWORDS - -[cache](\.\./\.\./\.\./\.\./index\.md\#cache), -[filesystem](\.\./\.\./\.\./\.\./index\.md\#filesystem), -[location](\.\./\.\./\.\./\.\./index\.md\#location), -[map](\.\./\.\./\.\./\.\./index\.md\#map), [slippy](\.\./\.\./\.\./\.\./index\.md\#slippy), -[tile](\.\./\.\./\.\./\.\./index\.md\#tile), [zoom](\.\./\.\./\.\./\.\./index\.md\#zoom) DELETED embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md Index: embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md ================================================================== --- embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md +++ embedded/md/tcllib/files/modules/map/map_slippy_fetcher.md @@ -1,105 +0,0 @@ - -[//000000001]: # (map::slippy::fetcher \- Mapping utilities) -[//000000002]: # (Generated from file 'map\_slippy\_fetcher\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (map::slippy::fetcher\(n\) 0\.4 tcllib "Mapping utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -map::slippy::fetcher \- Accessing a server providing tiles for slippy\-based maps - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Methods](#subsection1) - - - [References](#section3) - - - [Keywords](#keywords) - -# SYNOPSIS - -package require Tcl 8\.4 -package require Tk 8\.4 -package require img::png -package require map::slippy -package require map::slippy::fetcher ?0\.4? - -[__::map::slippy::fetcher__ *fetcherName* *levels* *url*](#1) -[*fetcherName* __levels__](#2) -[*fetcherName* __tileheight__](#3) -[*fetcherName* __tilewidth__](#4) -[*fetcherName* __get__ *tile* *donecmd*](#5) - -# DESCRIPTION - -This package provides a class for accessing http servers providing tiles for -slippy\-based maps\. - -# API - - - __::map::slippy::fetcher__ *fetcherName* *levels* *url* - - Creates the fetcher *fetcherName* and configures it with the number of - zoom *levels* supported by the tile server, and the *url* it is - listening on for tile requests\. - - The result of the command is *fetcherName*\. - -## Methods - - - *fetcherName* __levels__ - - This method returns the number of zoom levels supported by the fetcher - object, and the tile server it is accessing\. - - - *fetcherName* __tileheight__ - - This method returns the height of tiles served, in pixels\. - - - *fetcherName* __tilewidth__ - - This method returns the width of tiles served, in pixels\. - - - *fetcherName* __get__ *tile* *donecmd* - - This is the main method of the fetcher, retrieving the image for the - specified *tile*\. The tile identifier is a list containing three elements, - the zoom level, row, and column number of the tile, in this order\. - - The command refix *donecmd* will be invoked when the fetcher either knows - the image for the tile or that no image will forthcoming\. It will be invoked - with either 2 or 3 arguments, i\.e\. - - 1. The string __set__, the *tile*, and the image\. - - 1. The string __unset__, and the *tile*\. - - These two possibilities are used to either signal the image for the - *tile*, or that the *tile* has no image defined for it\. - -# References - - 1. [http://wiki\.openstreetmap\.org/wiki/Main\_Page](http://wiki\.openstreetmap\.org/wiki/Main\_Page) - -# KEYWORDS - -[http](\.\./\.\./\.\./\.\./index\.md\#http), -[location](\.\./\.\./\.\./\.\./index\.md\#location), -[map](\.\./\.\./\.\./\.\./index\.md\#map), [server](\.\./\.\./\.\./\.\./index\.md\#server), -[slippy](\.\./\.\./\.\./\.\./index\.md\#slippy), -[tile](\.\./\.\./\.\./\.\./index\.md\#tile), [url](\.\./\.\./\.\./\.\./index\.md\#url), -[zoom](\.\./\.\./\.\./\.\./index\.md\#zoom) DELETED embedded/md/tcllib/files/modules/mapproj/mapproj.md Index: embedded/md/tcllib/files/modules/mapproj/mapproj.md ================================================================== --- embedded/md/tcllib/files/modules/mapproj/mapproj.md +++ embedded/md/tcllib/files/modules/mapproj/mapproj.md @@ -1,479 +0,0 @@ - -[//000000001]: # (mapproj \- Tcl Library) -[//000000002]: # (Generated from file 'mapproj\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Kevin B\. Kenny ) -[//000000004]: # (mapproj\(n\) 0\.1 tcllib "Tcl Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -mapproj \- Map projection routines - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Arguments](#section3) - - - [Results](#section4) - - - [Choosing a projection](#section5) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require math::interpolate ?1\.0? -package require math::special ?0\.2\.1? -package require mapproj ?1\.0? - -[__::mapproj::toPlateCarree__ *lambda\_0* *phi\_0* *lambda* *phi*](#1) -[__::mapproj::fromPlateCarree__ *lambda\_0* *phi\_0* *x* *y*](#2) -[__::mapproj::toCylindricalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi*](#3) -[__::mapproj::fromCylindricalEqualArea__ *lambda\_0* *phi\_0* *x* *y*](#4) -[__::mapproj::toMercator__ *lambda\_0* *phi\_0* *lambda* *phi*](#5) -[__::mapproj::fromMercator__ *lambda\_0* *phi\_0* *x* *y*](#6) -[__::mapproj::toMillerCylindrical__ *lambda\_0* *lambda* *phi*](#7) -[__::mapproj::fromMillerCylindrical__ *lambda\_0* *x* *y*](#8) -[__::mapproj::toSinusoidal__ *lambda\_0* *phi\_0* *lambda* *phi*](#9) -[__::mapproj::fromSinusoidal__ *lambda\_0* *phi\_0* *x* *y*](#10) -[__::mapproj::toMollweide__ *lambda\_0* *lambda* *phi*](#11) -[__::mapproj::fromMollweide__ *lambda\_0* *x* *y*](#12) -[__::mapproj::toEckertIV__ *lambda\_0* *lambda* *phi*](#13) -[__::mapproj::fromEckertIV__ *lambda\_0* *x* *y*](#14) -[__::mapproj::toEckertVI__ *lambda\_0* *lambda* *phi*](#15) -[__::mapproj::fromEckertVI__ *lambda\_0* *x* *y*](#16) -[__::mapproj::toRobinson__ *lambda\_0* *lambda* *phi*](#17) -[__::mapproj::fromRobinson__ *lambda\_0* *x* *y*](#18) -[__::mapproj::toCassini__ *lambda\_0* *phi\_0* *lambda* *phi*](#19) -[__::mapproj::fromCassini__ *lambda\_0* *phi\_0* *x* *y*](#20) -[__::mapproj::toPeirceQuincuncial__ *lambda\_0* *lambda* *phi*](#21) -[__::mapproj::fromPeirceQuincuncial__ *lambda\_0* *x* *y*](#22) -[__::mapproj::toOrthographic__ *lambda\_0* *phi\_0* *lambda* *phi*](#23) -[__::mapproj::fromOrthographic__ *lambda\_0* *phi\_0* *x* *y*](#24) -[__::mapproj::toStereographic__ *lambda\_0* *phi\_0* *lambda* *phi*](#25) -[__::mapproj::fromStereographic__ *lambda\_0* *phi\_0* *x* *y*](#26) -[__::mapproj::toGnomonic__ *lambda\_0* *phi\_0* *lambda* *phi*](#27) -[__::mapproj::fromGnomonic__ *lambda\_0* *phi\_0* *x* *y*](#28) -[__::mapproj::toAzimuthalEquidistant__ *lambda\_0* *phi\_0* *lambda* *phi*](#29) -[__::mapproj::fromAzimuthalEquidistant__ *lambda\_0* *phi\_0* *x* *y*](#30) -[__::mapproj::toLambertAzimuthalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi*](#31) -[__::mapproj::fromLambertAzimuthalEqualArea__ *lambda\_0* *phi\_0* *x* *y*](#32) -[__::mapproj::toHammer__ *lambda\_0* *lambda* *phi*](#33) -[__::mapproj::fromHammer__ *lambda\_0* *x* *y*](#34) -[__::mapproj::toConicEquidistant__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi*](#35) -[__::mapproj::fromConicEquidistant__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y*](#36) -[__::mapproj::toAlbersEqualAreaConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi*](#37) -[__::mapproj::fromAlbersEqualAreaConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y*](#38) -[__::mapproj::toLambertConformalConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi*](#39) -[__::mapproj::fromLambertConformalConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y*](#40) -[__::mapproj::toLambertCylindricalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi*](#41) -[__::mapproj::fromLambertCylindricalEqualArea__ *lambda\_0* *phi\_0* *x* *y*](#42) -[__::mapproj::toBehrmann__ *lambda\_0* *phi\_0* *lambda* *phi*](#43) -[__::mapproj::fromBehrmann__ *lambda\_0* *phi\_0* *x* *y*](#44) -[__::mapproj::toTrystanEdwards__ *lambda\_0* *phi\_0* *lambda* *phi*](#45) -[__::mapproj::fromTrystanEdwards__ *lambda\_0* *phi\_0* *x* *y*](#46) -[__::mapproj::toHoboDyer__ *lambda\_0* *phi\_0* *lambda* *phi*](#47) -[__::mapproj::fromHoboDyer__ *lambda\_0* *phi\_0* *x* *y*](#48) -[__::mapproj::toGallPeters__ *lambda\_0* *phi\_0* *lambda* *phi*](#49) -[__::mapproj::fromGallPeters__ *lambda\_0* *phi\_0* *x* *y*](#50) -[__::mapproj::toBalthasart__ *lambda\_0* *phi\_0* *lambda* *phi*](#51) -[__::mapproj::fromBalthasart__ *lambda\_0* *phi\_0* *x* *y*](#52) - -# DESCRIPTION - -The __mapproj__ package provides a set of procedures for converting between -world co\-ordinates \(latitude and longitude\) and map co\-ordinates on a number of -different map projections\. - -# Commands - -The following commands convert between world co\-ordinates and map co\-ordinates: - - - __::mapproj::toPlateCarree__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the *plate carrée* \(cylindrical equidistant\) projection\. - - - __::mapproj::fromPlateCarree__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the *plate carrée* \(cylindrical equidistant\) projection\. - - - __::mapproj::toCylindricalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the cylindrical equal\-area projection\. - - - __::mapproj::fromCylindricalEqualArea__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the cylindrical equal\-area projection\. - - - __::mapproj::toMercator__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Mercator \(cylindrical conformal\) projection\. - - - __::mapproj::fromMercator__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Mercator \(cylindrical conformal\) projection\. - - - __::mapproj::toMillerCylindrical__ *lambda\_0* *lambda* *phi* - - Converts to the Miller Cylindrical projection\. - - - __::mapproj::fromMillerCylindrical__ *lambda\_0* *x* *y* - - Converts from the Miller Cylindrical projection\. - - - __::mapproj::toSinusoidal__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the sinusoidal \(Sanson\-Flamsteed\) projection\. projection\. - - - __::mapproj::fromSinusoidal__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the sinusoidal \(Sanson\-Flamsteed\) projection\. projection\. - - - __::mapproj::toMollweide__ *lambda\_0* *lambda* *phi* - - Converts to the Mollweide projection\. - - - __::mapproj::fromMollweide__ *lambda\_0* *x* *y* - - Converts from the Mollweide projection\. - - - __::mapproj::toEckertIV__ *lambda\_0* *lambda* *phi* - - Converts to the Eckert IV projection\. - - - __::mapproj::fromEckertIV__ *lambda\_0* *x* *y* - - Converts from the Eckert IV projection\. - - - __::mapproj::toEckertVI__ *lambda\_0* *lambda* *phi* - - Converts to the Eckert VI projection\. - - - __::mapproj::fromEckertVI__ *lambda\_0* *x* *y* - - Converts from the Eckert VI projection\. - - - __::mapproj::toRobinson__ *lambda\_0* *lambda* *phi* - - Converts to the Robinson projection\. - - - __::mapproj::fromRobinson__ *lambda\_0* *x* *y* - - Converts from the Robinson projection\. - - - __::mapproj::toCassini__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Cassini \(transverse cylindrical equidistant\) projection\. - - - __::mapproj::fromCassini__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Cassini \(transverse cylindrical equidistant\) projection\. - - - __::mapproj::toPeirceQuincuncial__ *lambda\_0* *lambda* *phi* - - Converts to the Peirce Quincuncial Projection\. - - - __::mapproj::fromPeirceQuincuncial__ *lambda\_0* *x* *y* - - Converts from the Peirce Quincuncial Projection\. - - - __::mapproj::toOrthographic__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the orthographic projection\. - - - __::mapproj::fromOrthographic__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the orthographic projection\. - - - __::mapproj::toStereographic__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the stereographic \(azimuthal conformal\) projection\. - - - __::mapproj::fromStereographic__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the stereographic \(azimuthal conformal\) projection\. - - - __::mapproj::toGnomonic__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the gnomonic projection\. - - - __::mapproj::fromGnomonic__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the gnomonic projection\. - - - __::mapproj::toAzimuthalEquidistant__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the azimuthal equidistant projection\. - - - __::mapproj::fromAzimuthalEquidistant__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the azimuthal equidistant projection\. - - - __::mapproj::toLambertAzimuthalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Lambert azimuthal equal\-area projection\. - - - __::mapproj::fromLambertAzimuthalEqualArea__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Lambert azimuthal equal\-area projection\. - - - __::mapproj::toHammer__ *lambda\_0* *lambda* *phi* - - Converts to the Hammer projection\. - - - __::mapproj::fromHammer__ *lambda\_0* *x* *y* - - Converts from the Hammer projection\. - - - __::mapproj::toConicEquidistant__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi* - - Converts to the conic equidistant projection\. - - - __::mapproj::fromConicEquidistant__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y* - - Converts from the conic equidistant projection\. - - - __::mapproj::toAlbersEqualAreaConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi* - - Converts to the Albers equal\-area conic projection\. - - - __::mapproj::fromAlbersEqualAreaConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y* - - Converts from the Albers equal\-area conic projection\. - - - __::mapproj::toLambertConformalConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *lambda* *phi* - - Converts to the Lambert conformal conic projection\. - - - __::mapproj::fromLambertConformalConic__ *lambda\_0* *phi\_0* *phi\_1* *phi\_2* *x* *y* - - Converts from the Lambert conformal conic projection\. - -Among the cylindrical equal\-area projections, there are a number of choices of -standard parallels that have names: - - - __::mapproj::toLambertCylindricalEqualArea__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Lambert cylindrical equal area projection\. \(standard - parallel is the Equator\.\) - - - __::mapproj::fromLambertCylindricalEqualArea__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Lambert cylindrical equal area projection\. \(standard - parallel is the Equator\.\) - - - __::mapproj::toBehrmann__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Behrmann cylindrical equal area projection\. \(standard - parallels are 30 degrees North and South\) - - - __::mapproj::fromBehrmann__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Behrmann cylindrical equal area projection\. \(standard - parallels are 30 degrees North and South\.\) - - - __::mapproj::toTrystanEdwards__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Trystan Edwards cylindrical equal area projection\. \(standard - parallels are 37\.4 degrees North and South\) - - - __::mapproj::fromTrystanEdwards__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Trystan Edwards cylindrical equal area projection\. - \(standard parallels are 37\.4 degrees North and South\.\) - - - __::mapproj::toHoboDyer__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Hobo\-Dyer cylindrical equal area projection\. \(standard - parallels are 37\.5 degrees North and South\) - - - __::mapproj::fromHoboDyer__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Hobo\-Dyer cylindrical equal area projection\. \(standard - parallels are 37\.5 degrees North and South\.\) - - - __::mapproj::toGallPeters__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Gall\-Peters cylindrical equal area projection\. \(standard - parallels are 45 degrees North and South\) - - - __::mapproj::fromGallPeters__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Gall\-Peters cylindrical equal area projection\. \(standard - parallels are 45 degrees North and South\.\) - - - __::mapproj::toBalthasart__ *lambda\_0* *phi\_0* *lambda* *phi* - - Converts to the Balthasart cylindrical equal area projection\. \(standard - parallels are 50 degrees North and South\) - - - __::mapproj::fromBalthasart__ *lambda\_0* *phi\_0* *x* *y* - - Converts from the Balthasart cylindrical equal area projection\. \(standard - parallels are 50 degrees North and South\.\) - -# Arguments - -The following arguments are accepted by the projection commands: - - - *lambda* - - Longitude of the point to be projected, in degrees\. - - - *phi* - - Latitude of the point to be projected, in degrees\. - - - *lambda\_0* - - Longitude of the center of the sheet, in degrees\. For many projections, this - figure is also the reference meridian of the projection\. - - - *phi\_0* - - Latitude of the center of the sheet, in degrees\. For the azimuthal - projections, this figure is also the latitude of the center of the - projection\. - - - *phi\_1* - - Latitude of the first reference parallel, for projections that use reference - parallels\. - - - *phi\_2* - - Latitude of the second reference parallel, for projections that use - reference parallels\. - - - *x* - - X co\-ordinate of a point on the map, in units of Earth radii\. - - - *y* - - Y co\-ordinate of a point on the map, in units of Earth radii\. - -# Results - -For all of the procedures whose names begin with 'to', the return value is a -list comprising an *x* co\-ordinate and a *y* co\-ordinate\. The co\-ordinates -are relative to the center of the map sheet to be drawn, measured in Earth radii -at the reference location on the map\. For all of the functions whose names begin -with 'from', the return value is a list comprising the longitude and latitude, -in degrees\. - -# Choosing a projection - -This package offers a great many projections, because no single projection is -appropriate to all maps\. This section attempts to provide guidance on how to -choose a projection\. - -First, consider the type of data that you intend to display on the map\. If the -data are *directional* \(*e\.g\.,* winds, ocean currents, or magnetic fields\) -then you need to use a projection that preserves angles; these are known as -*conformal* projections\. Conformal projections include the Mercator, the -Albers azimuthal equal\-area, the stereographic, and the Peirce Quincuncial -projection\. If the data are *thematic*, describing properties of land or -water, such as temperature, population density, land use, or demographics; then -you need a projection that will show these data with the areas on the map -proportional to the areas in real life\. These so\-called *equal area* -projections include the various cylindrical equal area projections, the -sinusoidal projection, the Lambert azimuthal equal\-area projection, the Albers -equal\-area conic projection, and several of the world\-map projections \(Miller -Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, and Hammer\)\. If the -significant factor in your data is distance from a central point or line \(such -as air routes\), then you will do best with an *equidistant* projection such as -*plate carrée*, Cassini, azimuthal equidistant, or conic equidistant\. If -direction from a central point is a critical factor in your data \(for instance, -air routes, radio antenna pointing\), then you will almost surely want to use one -of the azimuthal projections\. Appropriate choices are azimuthal equidistant, -azimuthal equal\-area, stereographic, and perhaps orthographic\. - -Next, consider how much of the Earth your map will cover, and the general shape -of the area of interest\. For maps of the entire Earth, the cylindrical equal -area, Eckert IV and VI, Mollweide, Robinson, and Hammer projections are good -overall choices\. The Mercator projection is traditional, but the extreme -distortions of area at high latitudes make it a poor choice unless a conformal -projection is required\. The Peirce projection is a better choice of conformal -projection, having less distortion of landforms\. The Miller Cylindrical is a -compromise designed to give shapes similar to the traditional Mercator, but with -less polar stretching\. The Peirce Quincuncial projection shows all the -continents with acceptable distortion if a reference meridian close to \+20 -degrees is chosen\. The Robinson projection yields attractive maps for things -like political divisions, but should be avoided in presenting scientific data, -since other projections have moe useful geometric properties\. - -If the map will cover a hemisphere, then choose stereographic, -azimuthal\-equidistant, Hammer, or Mollweide projections; these all project the -hemisphere into a circle\. - -If the map will cover a large area \(at least a few hundred km on a side\), but -less than a hemisphere, then you have several choices\. Azimuthal projections are -usually good \(choose stereographic, azimuthal equidistant, or Lambert azimuthal -equal\-area according to whether shapes, distances from a central point, or areas -are important\)\. Azimuthal projections \(and possibly the Cassini projection\) are -the only really good choices for mapping the polar regions\. - -If the large area is in one of the temperate zones and is round or has a -primarily east\-west extent, then the conic projections are good choices\. Choose -the Lambert conformal conic, the conic equidistant, or the Albers equal\-area -conic according to whether shape, distance, or area are the most important -parameters\. For any of these, the reference parallels should be chosen at -approximately 1/6 and 5/6 of the range of latitudes to be displayed\. For -instance, maps of the 48 coterminous United States are attractive with reference -parallels of 28\.5 and 45\.5 degrees\. - -If the large area is equatorial and is round or has a primarily east\-west -extent, then the Mercator projection is a good choice for a conformal -projection; Lambert cylindrical equal\-area and sinusoidal projections are good -equal\-area projections; and the *plate carrée* is a good equidistant -projection\. - -Large areas having a primarily North\-South aspect, particularly those spanning -the Equator, need some other choices\. The Cassini projection is a good choice -for an equidistant projection \(for instance, a Cassini projection with a central -meridian of 80 degrees West produces an attractive map of the Americas\)\. The -cylindrical equal\-area, Albers equal\-area conic, sinusoidal, Mollweide and -Hammer projections are possible choices for equal\-area projections\. A good -conformal projection in this situation is the Transverse Mercator, which alas, -is not yet implemented\. - -Small areas begin to get into a realm where the ellipticity of the Earth affects -the map scale\. This package does not attempt to handle accurate mapping for -large\-scale topographic maps\. If slight scale errors are acceptable in your -application, then any of the projections appropriate to large areas should work -for small ones as well\. - -There are a few projections that are included for their special properties\. The -orthographic projection produces views of the Earth as seen from space\. The -gnomonic projection produces a map on which all great circles \(the shortest -distance between two points on the Earth's surface\) are rendered as straight -lines\. While this projection is useful for navigational planning, it has extreme -distortions of shape and area, and can display only a limited area of the Earth -\(substantially less than a hemisphere\)\. - -# KEYWORDS - -[geodesy](\.\./\.\./\.\./\.\./index\.md\#geodesy), -[map](\.\./\.\./\.\./\.\./index\.md\#map), -[projection](\.\./\.\./\.\./\.\./index\.md\#projection) - -# COPYRIGHT - -Copyright © 2007 Kevin B\. Kenny DELETED embedded/md/tcllib/files/modules/markdown/markdown.md Index: embedded/md/tcllib/files/modules/markdown/markdown.md ================================================================== --- embedded/md/tcllib/files/modules/markdown/markdown.md +++ embedded/md/tcllib/files/modules/markdown/markdown.md @@ -1,94 +0,0 @@ - -[//000000001]: # (markdown \- Markdown to HTML Converter) -[//000000002]: # (Generated from file 'markdown\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (markdown\(n\) 1\.2 tcllib "Markdown to HTML Converter") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -markdown \- Converts Markdown text to HTML - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require Markdown 1\.2 -package require textutil ?0\.8? - -[__::Markdown::convert__ *markdown*](#1) -[__::Markdown::register__ *langspec* *converter*](#2) -[__::Markdown::get\_lang\_counter__](#3) -[__::Markdown::reset\_lang\_counter__](#4) - -# DESCRIPTION - -The package __Markdown__ provides a command to convert Markdown annotated -text into HMTL\. - - - __::Markdown::convert__ *markdown* - - This command takes in a block of Markdown text, and returns a block of HTML\. - - The converter supports two types of syntax highlighting for fenced code - blocks: highlighting via a registered converter \(see - __::Markdown::register__\), or pure JavaScript highlighting, e\.g\. via - "highlight\.js", where the language specifier used in the markup is set as - CSS class of the "code" element in the returned markup\. - - - __::Markdown::register__ *langspec* *converter* - - Register a language specific converter for prettifying a code block \(e\.g\. - syntax highlighting\)\. Markdown supports fenced code blocks with an optional - language specifier \(e\.g\. "tcl"\)\. When the markdown parser processes such a - code block and a converter for the specified langspec is registered, the - converter is called with the raw code block as argument\. The converter is - supposed to return the markup of the code block as result\. The specified - converter can be an arbitrary Tcl command, the raw text block is added as - last argument upon invocation\. - - - __::Markdown::get\_lang\_counter__ - - Return a dict of language specifier and number of occurrences in fenced code - blocks\. This function can be used e\.g\. to detect, whether some CSS or - JavaScript headers should be included for rendering without the need of - postprocessing the rendered result\. - - - __::Markdown::reset\_lang\_counter__ - - Reset the language counters\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/math/bigfloat.md Index: embedded/md/tcllib/files/modules/math/bigfloat.md ================================================================== --- embedded/md/tcllib/files/modules/math/bigfloat.md +++ embedded/md/tcllib/files/modules/math/bigfloat.md @@ -1,535 +0,0 @@ - -[//000000001]: # (math::bigfloat \- Tcl Math Library) -[//000000002]: # (Generated from file 'bigfloat\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008, by Stephane Arnold ) -[//000000004]: # (math::bigfloat\(n\) 2\.0\.3 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::bigfloat \- Arbitrary precision floating\-point numbers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [INTRODUCTION](#section2) - - - [ARITHMETICS](#section3) - - - [COMPARISONS](#section4) - - - [ANALYSIS](#section5) - - - [ROUNDING](#section6) - - - [PRECISION](#section7) - - - [WHAT ABOUT TCL 8\.4 ?](#section8) - - - [NAMESPACES AND OTHER PACKAGES](#section9) - - - [EXAMPLES](#section10) - - - [Bugs, Ideas, Feedback](#section11) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require math::bigfloat ?2\.0\.3? - -[__fromstr__ *number* ?*trailingZeros*?](#1) -[__tostr__ ?__\-nosci__? *number*](#2) -[__fromdouble__ *double* ?*decimals*?](#3) -[__todouble__ *number*](#4) -[__isInt__ *number*](#5) -[__isFloat__ *number*](#6) -[__int2float__ *integer* ?*decimals*?](#7) -[__add__ *x* *y*](#8) -[__sub__ *x* *y*](#9) -[__mul__ *x* *y*](#10) -[__div__ *x* *y*](#11) -[__mod__ *x* *y*](#12) -[__abs__ *x*](#13) -[__opp__ *x*](#14) -[__pow__ *x* *n*](#15) -[__iszero__ *x*](#16) -[__[equal](\.\./\.\./\.\./\.\./index\.md\#equal)__ *x* *y*](#17) -[__compare__ *x* *y*](#18) -[__sqrt__ *x*](#19) -[__[log](\.\./log/log\.md)__ *x*](#20) -[__exp__ *x*](#21) -[__cos__ *x*](#22) -[__sin__ *x*](#23) -[__tan__ *x*](#24) -[__cotan__ *x*](#25) -[__acos__ *x*](#26) -[__asin__ *x*](#27) -[__atan__ *x*](#28) -[__cosh__ *x*](#29) -[__sinh__ *x*](#30) -[__tanh__ *x*](#31) -[__[pi](\.\./\.\./\.\./\.\./index\.md\#pi)__ *n*](#32) -[__rad2deg__ *radians*](#33) -[__deg2rad__ *degrees*](#34) -[__round__ *x*](#35) -[__ceil__ *x*](#36) -[__floor__ *x*](#37) - -# DESCRIPTION - -The bigfloat package provides arbitrary precision floating\-point math -capabilities to the Tcl language\. It is designed to work with Tcl 8\.5, but for -Tcl 8\.4 is provided an earlier version of this package\. See [WHAT ABOUT TCL 8\.4 -?](#section8) for more explanations\. By convention, we will talk about the -numbers treated in this library as : - - - BigFloat for floating\-point numbers of arbitrary length\. - - - integers for arbitrary length signed integers, just as basic integers since - Tcl 8\.5\. - -Each BigFloat is an interval, namely \[*m\-d, m\+d*\], where *m* is the mantissa -and *d* the uncertainty, representing the limitation of that number's -precision\. This is why we call such mathematics *interval computations*\. Just -take an example in physics : when you measure a temperature, not all digits you -read are *significant*\. Sometimes you just cannot trust all digits \- not to -mention if doubles \(f\.p\. numbers\) can handle all these digits\. BigFloat can -handle this problem \- trusting the digits you get \- plus the ability to store -numbers with an arbitrary precision\. BigFloats are internally represented at Tcl -lists: this package provides a set of procedures operating against the internal -representation in order to : - - - perform math operations on BigFloats and \(optionnaly\) with integers\. - - - convert BigFloats from their internal representations to strings, and vice - versa\. - -# INTRODUCTION - - - __fromstr__ *number* ?*trailingZeros*? - - Converts *number* into a BigFloat\. Its precision is at least the number of - digits provided by *number*\. If the *number* contains only digits and - eventually a minus sign, it is considered as an integer\. Subsequently, no - conversion is done at all\. - - *trailingZeros* \- the number of zeros to append at the end of the - floating\-point number to get more precision\. It cannot be applied to an - integer\. - - # x and y are BigFloats : the first string contained a dot, and the second an e sign - set x [fromstr -1.000000] - set y [fromstr 2000e30] - # let's see how we get integers - set t 20000000000000 - # the old way (package 1.2) is still supported for backwards compatibility : - set m [fromstr 10000000000] - # but we do not need fromstr for integers anymore - set n -39 - # t, m and n are integers - - The *number*'s last digit is considered by the procedure to be true at - \+/\-1, For example, 1\.00 is the interval \[0\.99, 1\.01\], and 0\.43 the interval - \[0\.42, 0\.44\]\. The Pi constant may be approximated by the number "3\.1415"\. - This string could be considered as the interval \[3\.1414 , 3\.1416\] by - __fromstr__\. So, when you mean 1\.0 as a double, you may have to write - 1\.000000 to get enough precision\. To learn more about this subject, see - [PRECISION](#section7)\. - - For example : - - set x [fromstr 1.0000000000] - # the next line does the same, but smarter - set y [fromstr 1. 10] - - - __tostr__ ?__\-nosci__? *number* - - Returns a string form of a BigFloat, in which all digits are exacts\. *All - exact digits* means a rounding may occur, for example to zero, if the - uncertainty interval does not clearly show the true digits\. *number* may - be an integer, causing the command to return exactly the input argument\. - With the __\-nosci__ option, the number returned is never shown in - scientific notation, i\.e\. not like '3\.4523e\+5' but like '345230\.'\. - - puts [tostr [fromstr 0.99999]] ;# 1.0000 - puts [tostr [fromstr 1.00001]] ;# 1.0000 - puts [tostr [fromstr 0.002]] ;# 0.e-2 - - See [PRECISION](#section7) for that matter\. See also __iszero__ for - how to detect zeros, which is useful when performing a division\. - - - __fromdouble__ *double* ?*decimals*? - - Converts a double \(a simple floating\-point value\) to a BigFloat, with - exactly *decimals* digits\. Without the *decimals* argument, it behaves - like __fromstr__\. Here, the only important feature you might care of is - the ability to create BigFloats with a fixed number of *decimals*\. - - tostr [fromstr 1.111 4] - # returns : 1.111000 (3 zeros) - tostr [fromdouble 1.111 4] - # returns : 1.111 - - - __todouble__ *number* - - Returns a double, that may be used in *expr*, from a BigFloat\. - - - __isInt__ *number* - - Returns 1 if *number* is an integer, 0 otherwise\. - - - __isFloat__ *number* - - Returns 1 if *number* is a BigFloat, 0 otherwise\. - - - __int2float__ *integer* ?*decimals*? - - Converts an integer to a BigFloat with *decimals* trailing zeros\. The - default, and minimal, number of *decimals* is 1\. When converting back to - string, one decimal is lost: - - set n 10 - set x [int2float $n]; # like fromstr 10.0 - puts [tostr $x]; # prints "10." - set x [int2float $n 3]; # like fromstr 10.000 - puts [tostr $x]; # prints "10.00" - -# ARITHMETICS - - - __add__ *x* *y* - - - __sub__ *x* *y* - - - __mul__ *x* *y* - - Return the sum, difference and product of *x* by *y*\. *x* \- may be - either a BigFloat or an integer *y* \- may be either a BigFloat or an - integer When both are integers, these commands behave like __expr__\. - - - __div__ *x* *y* - - - __mod__ *x* *y* - - Return the quotient and the rest of *x* divided by *y*\. Each argument - \(*x* and *y*\) can be either a BigFloat or an integer, but you cannot - divide an integer by a BigFloat Divide by zero throws an error\. - - - __abs__ *x* - - Returns the absolute value of *x* - - - __opp__ *x* - - Returns the opposite of *x* - - - __pow__ *x* *n* - - Returns *x* taken to the *n*th power\. It only works if *n* is an - integer\. *x* might be a BigFloat or an integer\. - -# COMPARISONS - - - __iszero__ *x* - - Returns 1 if *x* is : - - * a BigFloat close enough to zero to raise "divide by zero"\. - - * the integer 0\. - - See here how numbers that are close to zero are converted to strings: - - tostr [fromstr 0.001] ; # -> 0.e-2 - tostr [fromstr 0.000000] ; # -> 0.e-5 - tostr [fromstr -0.000001] ; # -> 0.e-5 - tostr [fromstr 0.0] ; # -> 0. - tostr [fromstr 0.002] ; # -> 0.e-2 - - set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003 - tostr $a ; # 0.e-2 - iszero $a ; # false - - set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002 - tostr $a ; # 0.e-2 - iszero $a ; # true - - - __[equal](\.\./\.\./\.\./\.\./index\.md\#equal)__ *x* *y* - - Returns 1 if *x* and *y* are equal, 0 elsewhere\. - - - __compare__ *x* *y* - - Returns 0 if both BigFloat arguments are equal, 1 if *x* is greater than - *y*, and \-1 if *x* is lower than *y*\. You would not be able to compare - an integer to a BigFloat : the operands should be both BigFloats, or both - integers\. - -# ANALYSIS - - - __sqrt__ *x* - - - __[log](\.\./log/log\.md)__ *x* - - - __exp__ *x* - - - __cos__ *x* - - - __sin__ *x* - - - __tan__ *x* - - - __cotan__ *x* - - - __acos__ *x* - - - __asin__ *x* - - - __atan__ *x* - - - __cosh__ *x* - - - __sinh__ *x* - - - __tanh__ *x* - - The above functions return, respectively, the following : square root, - logarithm, exponential, cosine, sine, tangent, cotangent, arc cosine, arc - sine, arc tangent, hyperbolic cosine, hyperbolic sine, hyperbolic tangent, - of a BigFloat named *x*\. - - - __[pi](\.\./\.\./\.\./\.\./index\.md\#pi)__ *n* - - Returns a BigFloat representing the Pi constant with *n* digits after the - dot\. *n* is a positive integer\. - - - __rad2deg__ *radians* - - - __deg2rad__ *degrees* - - *radians* \- angle expressed in radians \(BigFloat\) - - *degrees* \- angle expressed in degrees \(BigFloat\) - - Convert an angle from radians to degrees, and *vice versa*\. - -# ROUNDING - - - __round__ *x* - - - __ceil__ *x* - - - __floor__ *x* - - The above functions return the *x* BigFloat, rounded like with the same - mathematical function in *expr*, and returns it as an integer\. - -# PRECISION - -How do conversions work with precision ? - - - When a BigFloat is converted from string, the internal representation holds - its uncertainty as 1 at the level of the last digit\. - - - During computations, the uncertainty of each result is internally computed - the closest to the reality, thus saving the memory used\. - - - When converting back to string, the digits that are printed are not subject - to uncertainty\. However, some rounding is done, as not doing so causes - severe problems\. - -Uncertainties are kept in the internal representation of the number ; it is -recommended to use __tostr__ only for outputting data \(on the screen or in a -file\), and NEVER call __fromstr__ with the result of __tostr__\. It is -better to always keep operands in their internal representation\. Due to the -internals of this library, the uncertainty interval may be slightly wider than -expected, but this should not cause false digits\. - -Now you may ask this question : What precision am I going to get after calling -add, sub, mul or div? First you set a number from the string representation and, -by the way, its uncertainty is set: - - set a [fromstr 1.230] - # $a belongs to [1.229, 1.231] - set a [fromstr 1.000] - # $a belongs to [0.999, 1.001] - # $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value) - -The uncertainty of the sum, or the difference, of two numbers, is the sum of -their respective uncertainties\. - - set a [fromstr 1.230] - set b [fromstr 2.340] - set sum [add $a $b]] - # the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2) - tostr $sum ; # 3.57 - -But when, for example, we add or substract an integer to a BigFloat, the -relative uncertainty of the result is unchanged\. So it is desirable not to -convert integers to BigFloats: - - set a [fromstr 0.999999999] - # now something dangerous - set b [fromstr 2.000] - # the result has only 3 digits - tostr [add $a $b] - - # how to keep precision at its maximum - puts [tostr [add $a 2]] - -For multiplication and division, the relative uncertainties of the product or -the quotient, is the sum of the relative uncertainties of the operands\. Take -care of division by zero : check each divider with __iszero__\. - - set num [fromstr 4.00] - set denom [fromstr 0.01] - - puts [iszero $denom];# true - set quotient [div $num $denom];# error : divide by zero - - # opposites of our operands - puts [compare $num [opp $num]]; # 1 - puts [compare $denom [opp $denom]]; # 0 !!! - # No suprise ! 0 and its opposite are the same... - -Effects of the precision of a number considered equal to zero to the cos -function: - - puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000 - puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000 - puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000 - puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000 - -BigFloats with different internal representations may be converted to the same -string\. - -For most analysis functions \(cosine, square root, logarithm, etc\.\), determining -the precision of the result is difficult\. It seems however that in many cases, -the loss of precision in the result is of one or two digits\. There are some -exceptions : for example, - - tostr [exp [fromstr 100.0 10]] - # returns : 2.688117142e+43 which has only 10 digits of precision, although the entry - # has 14 digits of precision. - -# WHAT ABOUT TCL 8\.4 ? - -If your setup do not provide Tcl 8\.5 but supports 8\.4, the package can still be -loaded, switching back to *math::bigfloat* 1\.2\. Indeed, an important function -introduced in Tcl 8\.5 is required \- the ability to handle bignums, that we can -do with __expr__\. Before 8\.5, this ability was provided by several packages, -including the pure\-Tcl *math::bignum* package provided by *tcllib*\. In this -case, all you need to know, is that arguments to the commands explained here, -are expected to be in their internal representation\. So even with integers, you -will need to call __fromstr__ and __tostr__ in order to convert them -between string and internal representations\. - - # - # with Tcl 8.5 - # ============ - set a [pi 20] - # round returns an integer and 'everything is a string' applies to integers - # whatever big they are - puts [round [mul $a 10000000000]] - # - # the same with Tcl 8.4 - # ===================== - set a [pi 20] - # bignums (arbitrary length integers) need a conversion hook - set b [fromstr 10000000000] - # round returns a bignum: - # before printing it, we need to convert it with 'tostr' - puts [tostr [round [mul $a $b]]] - -# NAMESPACES AND OTHER PACKAGES - -We have not yet discussed about namespaces because we assumed that you had -imported public commands into the global namespace, like this: - - namespace import ::math::bigfloat::* - -If you matter much about avoiding names conflicts, I considere it should be -resolved by the following : - - package require math::bigfloat - # beware: namespace ensembles are not available in Tcl 8.4 - namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat} - # from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands - set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]] - puts [bigfloat tostr $a] - -# EXAMPLES - -Guess what happens when you are doing some astronomy\. Here is an example : - - # convert acurrate angles with a millisecond-rated accuracy - proc degree-angle {degrees minutes seconds milliseconds} { - set result 0 - set div 1 - foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] { - # we convert each entry var into milliseconds - set div [expr {$div*$factor}] - incr result [expr {$var*$div}] - } - return [div [int2float $result] $div] - } - # load the package - package require math::bigfloat - namespace import ::math::bigfloat::* - # work with angles : a standard formula for navigation (taking bearings) - set angle1 [deg2rad [degree-angle 20 30 40 0]] - set angle2 [deg2rad [degree-angle 21 0 50 500]] - set opposite3 [deg2rad [degree-angle 51 0 50 500]] - set sinProduct [mul [sin $angle1] [sin $angle2]] - set cosProduct [mul [cos $angle1] [cos $angle2]] - set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]] - puts "angle3 : [tostr [rad2deg $angle3]]" - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: bignum :: float* -of the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[computations](\.\./\.\./\.\./\.\./index\.md\#computations), -[floating\-point](\.\./\.\./\.\./\.\./index\.md\#floating\_point), -[interval](\.\./\.\./\.\./\.\./index\.md\#interval), -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[multiprecision](\.\./\.\./\.\./\.\./index\.md\#multiprecision), -[tcl](\.\./\.\./\.\./\.\./index\.md\#tcl) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004\-2008, by Stephane Arnold DELETED embedded/md/tcllib/files/modules/math/bignum.md Index: embedded/md/tcllib/files/modules/math/bignum.md ================================================================== --- embedded/md/tcllib/files/modules/math/bignum.md +++ embedded/md/tcllib/files/modules/math/bignum.md @@ -1,332 +0,0 @@ - -[//000000001]: # (math::bignum \- Tcl Math Library) -[//000000002]: # (Generated from file 'bignum\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Salvatore Sanfilippo ) -[//000000004]: # (Copyright © 2004 Arjen Markus ) -[//000000005]: # (math::bignum\(n\) 3\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::bignum \- Arbitrary precision integer numbers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require math::bignum ?3\.1? - -[__::math::bignum::fromstr__ *string* ?*radix*?](#1) -[__::math::bignum::tostr__ *bignum* ?*radix*?](#2) -[__::math::bignum::sign__ *bignum*](#3) -[__::math::bignum::abs__ *bignum*](#4) -[__::math::bignum::cmp__ *a* *b*](#5) -[__::math::bignum::iszero__ *bignum*](#6) -[__::math::bignum::lt__ *a* *b*](#7) -[__::math::bignum::le__ *a* *b*](#8) -[__::math::bignum::gt__ *a* *b*](#9) -[__::math::bignum::ge__ *a* *b*](#10) -[__::math::bignum::eq__ *a* *b*](#11) -[__::math::bignum::ne__ *a* *b*](#12) -[__::math::bignum::isodd__ *bignum*](#13) -[__::math::bignum::iseven__ *bignum*](#14) -[__::math::bignum::add__ *a* *b*](#15) -[__::math::bignum::sub__ *a* *b*](#16) -[__::math::bignum::mul__ *a* *b*](#17) -[__::math::bignum::divqr__ *a* *b*](#18) -[__::math::bignum::div__ *a* *b*](#19) -[__::math::bignum::rem__ *a* *b*](#20) -[__::math::bignum::mod__ *n* *m*](#21) -[__::math::bignum::pow__ *base* *exp*](#22) -[__::math::bignum::powm__ *base* *exp* *m*](#23) -[__::math::bignum::sqrt__ *bignum*](#24) -[__::math::bignum::rand__ *bits*](#25) -[__::math::bignum::lshift__ *bignum* *bits*](#26) -[__::math::bignum::rshift__ *bignum* *bits*](#27) -[__::math::bignum::bitand__ *a* *b*](#28) -[__::math::bignum::bitor__ *a* *b*](#29) -[__::math::bignum::bitxor__ *a* *b*](#30) -[__::math::bignum::setbit__ *bignumVar* *bit*](#31) -[__::math::bignum::clearbit__ *bignumVar* *bit*](#32) -[__::math::bignum::testbit__ *bignum* *bit*](#33) -[__::math::bignum::bits__ *bignum*](#34) - -# DESCRIPTION - -The bignum package provides arbitrary precision integer math \(also known as "big -numbers"\) capabilities to the Tcl language\. Big numbers are internally -represented at Tcl lists: this package provides a set of procedures operating -against the internal representation in order to: - - - perform math operations - - - convert bignums from the internal representation to a string in the desired - radix and vice versa\. - -But the two constants "0" and "1" are automatically converted to the internal -representation, in order to easily compare a number to zero, or increment a big -number\. - -The bignum interface is opaque, so operations on bignums that are not returned -by procedures in this package \(but created by hand\) may lead to unspecified -behaviours\. It's safe to treat bignums as pure values, so there is no need to -free a bignum, or to duplicate it via a special operation\. - -# EXAMPLES - -This section shows some simple example\. This library being just a way to perform -math operations, examples may be the simplest way to learn how to work with it\. -Consult the API section of this man page for information about individual -procedures\. - - package require math::bignum - - # Multiplication of two bignums - set a [::math::bignum::fromstr 88888881111111] - set b [::math::bignum::fromstr 22222220000000] - set c [::math::bignum::mul $a $b] - puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000 - set c [::math::bignum::sqrt $c] - puts [::math::bignum::tostr $c] ; # => will output 44444440277777 - - # From/To string conversion in different radix - set a [::math::bignum::fromstr 1100010101010111001001111010111 2] - puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7 - - # Factorial example - proc fact n { - # fromstr is not needed for 0 and 1 - set z 1 - for {set i 2} {$i <= $n} {incr i} { - set z [::math::bignum::mul $z [::math::bignum::fromstr $i]] - } - return $z - } - - puts [::math::bignum::tostr [fact 100]] - -# API - - - __::math::bignum::fromstr__ *string* ?*radix*? - - Convert *string* into a bignum\. If *radix* is omitted or zero, the - string is interpreted in hex if prefixed with *0x*, in octal if prefixed - with *ox*, in binary if it's pefixed with *bx*, as a number in radix 10 - otherwise\. If instead the *radix* argument is specified in the range 2\-36, - the *string* is interpreted in the given radix\. Please note that this - conversion is not needed for two constants : *0* and *1*\. \(see the - example\) - - - __::math::bignum::tostr__ *bignum* ?*radix*? - - Convert *bignum* into a string representing the number in the specified - radix\. If *radix* is omitted, the default is 10\. - - - __::math::bignum::sign__ *bignum* - - Return the sign of the bignum\. The procedure returns 0 if the number is - positive, 1 if it's negative\. - - - __::math::bignum::abs__ *bignum* - - Return the absolute value of the bignum\. - - - __::math::bignum::cmp__ *a* *b* - - Compare the two bignums a and b, returning *0* if *a == b*, *1* if *a - > b*, and *\-1* if *a < b*\. - - - __::math::bignum::iszero__ *bignum* - - Return true if *bignum* value is zero, otherwise false is returned\. - - - __::math::bignum::lt__ *a* *b* - - Return true if *a < b*, otherwise false is returned\. - - - __::math::bignum::le__ *a* *b* - - Return true if *a <= b*, otherwise false is returned\. - - - __::math::bignum::gt__ *a* *b* - - Return true if *a > b*, otherwise false is returned\. - - - __::math::bignum::ge__ *a* *b* - - Return true if *a >= b*, otherwise false is returned\. - - - __::math::bignum::eq__ *a* *b* - - Return true if *a == b*, otherwise false is returned\. - - - __::math::bignum::ne__ *a* *b* - - Return true if *a \!= b*, otherwise false is returned\. - - - __::math::bignum::isodd__ *bignum* - - Return true if *bignum* is odd\. - - - __::math::bignum::iseven__ *bignum* - - Return true if *bignum* is even\. - - - __::math::bignum::add__ *a* *b* - - Return the sum of the two bignums *a* and *b*\. - - - __::math::bignum::sub__ *a* *b* - - Return the difference of the two bignums *a* and *b*\. - - - __::math::bignum::mul__ *a* *b* - - Return the product of the two bignums *a* and *b*\. The implementation - uses Karatsuba multiplication if both the numbers are bigger than a given - threshold, otherwise the direct algorith is used\. - - - __::math::bignum::divqr__ *a* *b* - - Return a two\-elements list containing as first element the quotient of the - division between the two bignums *a* and *b*, and the remainder of the - division as second element\. - - - __::math::bignum::div__ *a* *b* - - Return the quotient of the division between the two bignums *a* and *b*\. - - - __::math::bignum::rem__ *a* *b* - - Return the remainder of the division between the two bignums *a* and - *b*\. - - - __::math::bignum::mod__ *n* *m* - - Return *n* modulo *m*\. This operation is called modular reduction\. - - - __::math::bignum::pow__ *base* *exp* - - Return *base* raised to the exponent *exp*\. - - - __::math::bignum::powm__ *base* *exp* *m* - - Return *base* raised to the exponent *exp*, modulo *m*\. This function - is often used in the field of cryptography\. - - - __::math::bignum::sqrt__ *bignum* - - Return the integer part of the square root of *bignum* - - - __::math::bignum::rand__ *bits* - - Return a random number of at most *bits* bits\. The returned number is - internally generated using Tcl's *expr rand\(\)* function and is not - suitable where an unguessable and cryptographically secure random number is - needed\. - - - __::math::bignum::lshift__ *bignum* *bits* - - Return the result of left shifting *bignum*'s binary representation of - *bits* positions on the left\. This is equivalent to multiplying by - 2^*bits* but much faster\. - - - __::math::bignum::rshift__ *bignum* *bits* - - Return the result of right shifting *bignum*'s binary representation of - *bits* positions on the right\. This is equivalent to dividing by - *2^bits* but much faster\. - - - __::math::bignum::bitand__ *a* *b* - - Return the result of doing a bitwise AND operation on a and b\. The operation - is restricted to positive numbers, including zero\. When negative numbers are - provided as arguments the result is undefined\. - - - __::math::bignum::bitor__ *a* *b* - - Return the result of doing a bitwise OR operation on a and b\. The operation - is restricted to positive numbers, including zero\. When negative numbers are - provided as arguments the result is undefined\. - - - __::math::bignum::bitxor__ *a* *b* - - Return the result of doing a bitwise XOR operation on a and b\. The operation - is restricted to positive numbers, including zero\. When negative numbers are - provided as arguments the result is undefined\. - - - __::math::bignum::setbit__ *bignumVar* *bit* - - Set the bit at *bit* position to 1 in the bignum stored in the variable - *bignumVar*\. Bit 0 is the least significant\. - - - __::math::bignum::clearbit__ *bignumVar* *bit* - - Set the bit at *bit* position to 0 in the bignum stored in the variable - *bignumVar*\. Bit 0 is the least significant\. - - - __::math::bignum::testbit__ *bignum* *bit* - - Return true if the bit at the *bit* position of *bignum* is on, - otherwise false is returned\. If *bit* is out of range, it is considered as - set to zero\. - - - __::math::bignum::bits__ *bignum* - - Return the number of bits needed to represent bignum in radix 2\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: bignum* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[bignums](\.\./\.\./\.\./\.\./index\.md\#bignums), -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[multiprecision](\.\./\.\./\.\./\.\./index\.md\#multiprecision), -[tcl](\.\./\.\./\.\./\.\./index\.md\#tcl) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Salvatore Sanfilippo -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/calculus.md Index: embedded/md/tcllib/files/modules/math/calculus.md ================================================================== --- embedded/md/tcllib/files/modules/math/calculus.md +++ embedded/md/tcllib/files/modules/math/calculus.md @@ -1,518 +0,0 @@ - -[//000000001]: # (math::calculus \- Tcl Math Library) -[//000000002]: # (Generated from file 'calculus\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002,2003,2004 Arjen Markus) -[//000000004]: # (math::calculus\(n\) 0\.8\.2 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::calculus \- Integration and ordinary differential equations - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require math::calculus 0\.8\.2 - -[__::math::calculus::integral__ *begin* *end* *nosteps* *func*](#1) -[__::math::calculus::integralExpr__ *begin* *end* *nosteps* *expression*](#2) -[__::math::calculus::integral2D__ *xinterval* *yinterval* *func*](#3) -[__::math::calculus::integral2D\_accurate__ *xinterval* *yinterval* *func*](#4) -[__::math::calculus::integral3D__ *xinterval* *yinterval* *zinterval* *func*](#5) -[__::math::calculus::integral3D\_accurate__ *xinterval* *yinterval* *zinterval* *func*](#6) -[__::math::calculus::qk15__ *xstart* *xend* *func* *nosteps*](#7) -[__::math::calculus::qk15\_detailed__ *xstart* *xend* *func* *nosteps*](#8) -[__::math::calculus::eulerStep__ *t* *tstep* *xvec* *func*](#9) -[__::math::calculus::heunStep__ *t* *tstep* *xvec* *func*](#10) -[__::math::calculus::rungeKuttaStep__ *t* *tstep* *xvec* *func*](#11) -[__::math::calculus::boundaryValueSecondOrder__ *coeff\_func* *force\_func* *leftbnd* *rightbnd* *nostep*](#12) -[__::math::calculus::solveTriDiagonal__ *acoeff* *bcoeff* *ccoeff* *dvalue*](#13) -[__::math::calculus::newtonRaphson__ *func* *deriv* *initval*](#14) -[__::math::calculus::newtonRaphsonParameters__ *maxiter* *tolerance*](#15) -[__::math::calculus::regula\_falsi__ *f* *xb* *xe* *eps*](#16) - -# DESCRIPTION - -This package implements several simple mathematical algorithms: - - - The integration of a function over an interval - - - The numerical integration of a system of ordinary differential equations\. - - - Estimating the root\(s\) of an equation of one variable\. - -The package is fully implemented in Tcl\. No particular attention has been paid -to the accuracy of the calculations\. Instead, well\-known algorithms have been -used in a straightforward manner\. - -This document describes the procedures and explains their usage\. - -# PROCEDURES - -This package defines the following public procedures: - - - __::math::calculus::integral__ *begin* *end* *nosteps* *func* - - Determine the integral of the given function using the Simpson rule\. The - interval for the integration is \[*begin*, *end*\]\. The remaining - arguments are: - - * *nosteps* - - Number of steps in which the interval is divided\. - - * *func* - - Function to be integrated\. It should take one single argument\. - - - __::math::calculus::integralExpr__ *begin* *end* *nosteps* *expression* - - Similar to the previous proc, this one determines the integral of the given - *expression* using the Simpson rule\. The interval for the integration is - \[*begin*, *end*\]\. The remaining arguments are: - - * *nosteps* - - Number of steps in which the interval is divided\. - - * *expression* - - Expression to be integrated\. It should use the variable "x" as the only - variable \(the "integrate"\) - - - __::math::calculus::integral2D__ *xinterval* *yinterval* *func* - - - __::math::calculus::integral2D\_accurate__ *xinterval* *yinterval* *func* - - The commands __integral2D__ and __integral2D\_accurate__ calculate - the integral of a function of two variables over the rectangle given by the - first two arguments, each a list of three items, the start and stop interval - for the variable and the number of steps\. - - The command __integral2D__ evaluates the function at the centre of each - rectangle, whereas the command __integral2D\_accurate__ uses a four\-point - quadrature formula\. This results in an exact integration of polynomials of - third degree or less\. - - The function must take two arguments and return the function value\. - - - __::math::calculus::integral3D__ *xinterval* *yinterval* *zinterval* *func* - - - __::math::calculus::integral3D\_accurate__ *xinterval* *yinterval* *zinterval* *func* - - The commands __integral3D__ and __integral3D\_accurate__ are the - three\-dimensional equivalent of __integral2D__ and - __integral3D\_accurate__\. The function *func* takes three arguments and - is integrated over the block in 3D space given by three intervals\. - - - __::math::calculus::qk15__ *xstart* *xend* *func* *nosteps* - - Determine the integral of the given function using the Gauss\-Kronrod 15 - points quadrature rule\. The returned value is the estimate of the integral - over the interval \[*xstart*, *xend*\]\. The remaining arguments are: - - * *func* - - Function to be integrated\. It should take one single argument\. - - * ?nosteps? - - Number of steps in which the interval is divided\. Defaults to 1\. - - - __::math::calculus::qk15\_detailed__ *xstart* *xend* *func* *nosteps* - - Determine the integral of the given function using the Gauss\-Kronrod 15 - points quadrature rule\. The interval for the integration is \[*xstart*, - *xend*\]\. The procedure returns a list of four values: - - * The estimate of the integral over the specified interval \(I\)\. - - * An estimate of the absolute error in I\. - - * The estimate of the integral of the absolute value of the function over - the interval\. - - * The estimate of the integral of the absolute value of the function minus - its mean over the interval\. - - The remaining arguments are: - - * *func* - - Function to be integrated\. It should take one single argument\. - - * ?nosteps? - - Number of steps in which the interval is divided\. Defaults to 1\. - - - __::math::calculus::eulerStep__ *t* *tstep* *xvec* *func* - - Set a single step in the numerical integration of a system of differential - equations\. The method used is Euler's\. - - * *t* - - Value of the independent variable \(typically time\) at the beginning of - the step\. - - * *tstep* - - Step size for the independent variable\. - - * *xvec* - - List \(vector\) of dependent values - - * *func* - - Function of t and the dependent values, returning a list of the - derivatives of the dependent values\. \(The lengths of xvec and the return - value of "func" must match\)\. - - - __::math::calculus::heunStep__ *t* *tstep* *xvec* *func* - - Set a single step in the numerical integration of a system of differential - equations\. The method used is Heun's\. - - * *t* - - Value of the independent variable \(typically time\) at the beginning of - the step\. - - * *tstep* - - Step size for the independent variable\. - - * *xvec* - - List \(vector\) of dependent values - - * *func* - - Function of t and the dependent values, returning a list of the - derivatives of the dependent values\. \(The lengths of xvec and the return - value of "func" must match\)\. - - - __::math::calculus::rungeKuttaStep__ *t* *tstep* *xvec* *func* - - Set a single step in the numerical integration of a system of differential - equations\. The method used is Runge\-Kutta 4th order\. - - * *t* - - Value of the independent variable \(typically time\) at the beginning of - the step\. - - * *tstep* - - Step size for the independent variable\. - - * *xvec* - - List \(vector\) of dependent values - - * *func* - - Function of t and the dependent values, returning a list of the - derivatives of the dependent values\. \(The lengths of xvec and the return - value of "func" must match\)\. - - - __::math::calculus::boundaryValueSecondOrder__ *coeff\_func* *force\_func* *leftbnd* *rightbnd* *nostep* - - Solve a second order linear differential equation with boundary values at - two sides\. The equation has to be of the form \(the "conservative" form\): - - d dy d - -- A(x)-- + -- B(x)y + C(x)y = D(x) - dx dx dx - - Ordinarily, such an equation would be written as: - - d2y dy - a(x)--- + b(x)-- + c(x) y = D(x) - dx2 dx - - The first form is easier to discretise \(by integrating over a finite volume\) - than the second form\. The relation between the two forms is fairly - straightforward: - - A(x) = a(x) - B(x) = b(x) - a'(x) - C(x) = c(x) - B'(x) = c(x) - b'(x) + a''(x) - - Because of the differentiation, however, it is much easier to ask the user - to provide the functions A, B and C directly\. - - * *coeff\_func* - - Procedure returning the three coefficients \(A, B, C\) of the equation, - taking as its one argument the x\-coordinate\. - - * *force\_func* - - Procedure returning the right\-hand side \(D\) as a function of the - x\-coordinate\. - - * *leftbnd* - - A list of two values: the x\-coordinate of the left boundary and the - value at that boundary\. - - * *rightbnd* - - A list of two values: the x\-coordinate of the right boundary and the - value at that boundary\. - - * *nostep* - - Number of steps by which to discretise the interval\. The procedure - returns a list of x\-coordinates and the approximated values of the - solution\. - - - __::math::calculus::solveTriDiagonal__ *acoeff* *bcoeff* *ccoeff* *dvalue* - - Solve a system of linear equations Ax = b with A a tridiagonal matrix\. - Returns the solution as a list\. - - * *acoeff* - - List of values on the lower diagonal - - * *bcoeff* - - List of values on the main diagonal - - * *ccoeff* - - List of values on the upper diagonal - - * *dvalue* - - List of values on the righthand\-side - - - __::math::calculus::newtonRaphson__ *func* *deriv* *initval* - - Determine the root of an equation given by - - func(x) = 0 - - using the method of Newton\-Raphson\. The procedure takes the following - arguments: - - * *func* - - Procedure that returns the value the function at x - - * *deriv* - - Procedure that returns the derivative of the function at x - - * *initval* - - Initial value for x - - - __::math::calculus::newtonRaphsonParameters__ *maxiter* *tolerance* - - Set the numerical parameters for the Newton\-Raphson method: - - * *maxiter* - - Maximum number of iteration steps \(defaults to 20\) - - * *tolerance* - - Relative precision \(defaults to 0\.001\) - - - __::math::calculus::regula\_falsi__ *f* *xb* *xe* *eps* - - Return an estimate of the zero or one of the zeros of the function contained - in the interval \[xb,xe\]\. The error in this estimate is of the order of - eps\*abs\(xe\-xb\), the actual error may be slightly larger\. - - The method used is the so\-called *regula falsi* or *false position* - method\. It is a straightforward implementation\. The method is robust, but - requires that the interval brackets a zero or at least an uneven number of - zeros, so that the value of the function at the start has a different sign - than the value at the end\. - - In contrast to Newton\-Raphson there is no need for the computation of the - function's derivative\. - - * command *f* - - Name of the command that evaluates the function for which the zero is to - be returned - - * float *xb* - - Start of the interval in which the zero is supposed to lie - - * float *xe* - - End of the interval - - * float *eps* - - Relative allowed error \(defaults to 1\.0e\-4\) - -*Notes:* - -Several of the above procedures take the *names* of procedures as arguments\. -To avoid problems with the *visibility* of these procedures, the -fully\-qualified name of these procedures is determined inside the calculus -routines\. For the user this has only one consequence: the named procedure must -be visible in the calling procedure\. For instance: - - namespace eval ::mySpace { - namespace export calcfunc - proc calcfunc { x } { return $x } - } - # - # Use a fully-qualified name - # - namespace eval ::myCalc { - proc detIntegral { begin end } { - return [integral $begin $end 100 ::mySpace::calcfunc] - } - } - # - # Import the name - # - namespace eval ::myCalc { - namespace import ::mySpace::calcfunc - proc detIntegral { begin end } { - return [integral $begin $end 100 calcfunc] - } - } - -Enhancements for the second\-order boundary value problem: - - - Other types of boundary conditions \(zero gradient, zero flux\) - - - Other schematisation of the first\-order term \(now central differences are - used, but upstream differences might be useful too\)\. - -# EXAMPLES - -Let us take a few simple examples: - -Integrate x over the interval \[0,100\] \(20 steps\): - - proc linear_func { x } { return $x } - puts "Integral: [::math::calculus::integral 0 100 20 linear_func]" - -For simple functions, the alternative could be: - - puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]" - -Do not forget the braces\! - -The differential equation for a dampened oscillator: - - x'' + rx' + wx = 0 - -can be split into a system of first\-order equations: - - x' = y - y' = -ry - wx - -Then this system can be solved with code like this: - - proc dampened_oscillator { t xvec } { - set x [lindex $xvec 0] - set x1 [lindex $xvec 1] - return [list $x1 [expr {-$x1-$x}]] - } - - set xvec { 1.0 0.0 } - set t 0.0 - set tstep 0.1 - for { set i 0 } { $i < 20 } { incr i } { - set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator] - puts "Result ($t): $result" - set t [expr {$t+$tstep}] - set xvec $result - } - -Suppose we have the boundary value problem: - - Dy'' + ky = 0 - x = 0: y = 1 - x = L: y = 0 - -This boundary value problem could originate from the diffusion of a decaying -substance\. - -It can be solved with the following fragment: - - proc coeffs { x } { return [list $::Diff 0.0 $::decay] } - proc force { x } { return 0.0 } - - set Diff 1.0e-2 - set decay 0.0001 - set length 100.0 - - set y [::math::calculus::boundaryValueSecondOrder \ - coeffs force {0.0 1.0} [list $length 0.0] 100] - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: calculus* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -romberg - -# KEYWORDS - -[calculus](\.\./\.\./\.\./\.\./index\.md\#calculus), [differential -equations](\.\./\.\./\.\./\.\./index\.md\#differential\_equations), -[integration](\.\./\.\./\.\./\.\./index\.md\#integration), -[math](\.\./\.\./\.\./\.\./index\.md\#math), [roots](\.\./\.\./\.\./\.\./index\.md\#roots) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2002,2003,2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/changepoint.md Index: embedded/md/tcllib/files/modules/math/changepoint.md ================================================================== --- embedded/md/tcllib/files/modules/math/changepoint.md +++ embedded/md/tcllib/files/modules/math/changepoint.md @@ -1,191 +0,0 @@ - -[//000000001]: # (math::changepoint \- Tcl Math Library) -[//000000002]: # (Generated from file 'changepoint\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2020 by Arjen Markus) -[//000000004]: # (math::changepoint\(n\) 0\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::changepoint \- Change point detection methods - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::statistics -package require math::changepoint ?0\.1? - -[__::math::changepoint::cusum\-detect__ *data* ?args?](#1) -[__::math::changepoint::cusum\-online__ ?args?](#2) -[__$cusumObj__ examine *value*](#3) -[__$cusumObj__ reset](#4) -[__::math::changepoint::binary\-segmentation__ *data* ?args?](#5) - -# DESCRIPTION - -The __math::changepoint__ package implements a number of well\-known methods -to determine if a series of data contains a shift in the mean or not\. Note that -these methods only indicate if a shift in the mean is probably\. Due to the -stochastic nature of the data that will be analysed, false positives are -possible\. The CUSUM method is implemented in both an "offline" and an "online" -version, so that it can be used either for a complete data series or for -detecting changes in data that come in one by one\. The implementation has been -based on these websites mostly: - - - [https://www\.itl\.nist\.gov/div898/handbook/pmc/section3/pmc323\.htm](https://www\.itl\.nist\.gov/div898/handbook/pmc/section3/pmc323\.htm) - - - [https://en\.wikipedia\.org/wiki/CUSUM](https://en\.wikipedia\.org/wiki/CUSUM) - -Basically, the deviation of the data from a given target value is accumulated -and when the total deviation becomes too large, a change point is reported\. A -second method, binary segmentation, is implemented only as an "offline" method, -as it needs to examine the data series as a whole\. In the variant contained here -the following ideas have been used: - - - The segments in which the data series may be separated shold not be too - short, otherwise the ultimate result could be segments of only one data - point long\. So a minimum length is used\. - - - To make the segmentation worthwhile there should be a minimum gain in - reducing the cost function \(the sum of the squared deviations from the mean - for each segment\)\. - -This may not be in agreement with the descriptions of the method found in -various publications, but it is simple to understand and intuitive\. One -publication that provides more information on the method in general is -"Selective review of offline change point detection methods" by Truong et al\. -[https://arxiv\.org/abs/1801\.00718](https://arxiv\.org/abs/1801\.00718)\. - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::changepoint::cusum\-detect__ *data* ?args? - - Examine a given data series and return the location of the first change \(if - any\) - - * double *data* - - Series of data to be examined - - * list *args* - - Optional list of key\-value pairs: - - + __\-target__ *value* - - The target \(or mean\) for the time series - - + __\-tolerance__ *value* - - The tolerated standard deviation - - + __\-kfactor__ *value* - - The factor by which to multiply the standard deviation \(defaults to - 0\.5, typically between 0\.5 and 1\.0\) - - + __\-hfactor__ *value* - - The factor determining the limits betweem which the "cusum" - statistic is accepted \(typicaly 3\.0\-5\.0, default 4\.0\) - - - __::math::changepoint::cusum\-online__ ?args? - - Class to examine data passed in against expected properties\. At least the - keywords *\-target* and *\-tolerance* must be given\. - - * list *args* - - List of key\-value pairs: - - + __\-target__ *value* - - The target \(or mean\) for the time series - - + __\-tolerance__ *value* - - The tolerated standard deviation - - + __\-kfactor__ *value* - - The factor by which to multiply the standard deviation \(defaults to - 0\.5, typically between 0\.5 and 1\.0\) - - + __\-hfactor__ *value* - - The factor determining the limits betweem which the "cusum" - statistic is accepted \(typicaly 3\.0\-5\.0, default 4\.0\) - - - __$cusumObj__ examine *value* - - Pass a value to the *cusum\-online* object and examine it\. If, with this - new value, the cumulative sum remains within the bounds, zero \(0\) is - returned, otherwise one \(1\) is returned\. - - * double *value* - - The new value - - - __$cusumObj__ reset - - Reset the cumulative sum, so that the examination can start afresh\. - - - __::math::changepoint::binary\-segmentation__ *data* ?args? - - Apply the binary segmentation method recursively to find change points\. - Returns a list of indices of potential change points - - * list *data* - - Data to be examined - - * list *args* - - Optional key\-value pairs: - - + __\-minlength__ *number* - - Minimum number of points in each segment \(default: 5\) - - + __\-threshold__ *value* - - Factor applied to the standard deviation functioning as a threshold - for accepting the change in cost function as an improvement - \(default: 1\.0\) - -# KEYWORDS - -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[statistics](\.\./\.\./\.\./\.\./index\.md\#statistics) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2020 by Arjen Markus DELETED embedded/md/tcllib/files/modules/math/combinatorics.md Index: embedded/md/tcllib/files/modules/math/combinatorics.md ================================================================== --- embedded/md/tcllib/files/modules/math/combinatorics.md +++ embedded/md/tcllib/files/modules/math/combinatorics.md @@ -1,350 +0,0 @@ - -[//000000001]: # (math::combinatorics \- Tcl Math Library) -[//000000002]: # (Generated from file 'combinatorics\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::combinatorics\(n\) 2\.0 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::combinatorics \- Combinatorial functions in the Tcl Math Library - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require math ?1\.2\.3? -package require Tcl 8\.6 -package require math::combinatorics ?2\.0? - -[__::math::ln\_Gamma__ *z*](#1) -[__::math::factorial__ *x*](#2) -[__::math::choose__ *n k*](#3) -[__::math::Beta__ *z w*](#4) -[__::math::combinatorics::permutations__ *n*](#5) -[__::math::combinatorics::variations__ *n* *k*](#6) -[__::math::combinatorics::combinations__ *n* *k*](#7) -[__::math::combinatorics::derangements__ *n*](#8) -[__::math::combinatorics::catalan__ *n*](#9) -[__::math::combinatorics::firstStirling__ *n* *m*](#10) -[__::math::combinatorics::secondStirling__ *n* *m*](#11) -[__::math::combinatorics::partitionP__ *n*](#12) -[__::math::combinatorics::list\-permutations__ *n*](#13) -[__::math::combinatorics::list\-variations__ *n* *k*](#14) -[__::math::combinatorics::list\-combinations__ *n* *k*](#15) -[__::math::combinatorics::list\-derangements__ *n*](#16) -[__::math::combinatorics::list\-powerset__ *n*](#17) -[__::math::combinatorics::permutationObj__ new/create NAME *n*](#18) -[__$perm__ next](#19) -[__$perm__ reset](#20) -[__$perm__ setElements *elements*](#21) -[__$perm__ setElements](#22) -[__::math::combinatorics::combinationObj__ new/create NAME *n* *k*](#23) -[__$combin__ next](#24) -[__$combin__ reset](#25) -[__$combin__ setElements *elements*](#26) -[__$combin__ setElements](#27) - -# DESCRIPTION - -The __[math](math\.md)__ package contains implementations of several -functions useful in combinatorial problems\. The __math::combinatorics__ -extends the collections based on features in Tcl 8\.6\. Note: the meaning of the -partitionP function, Catalan and Stirling numbers is explained on the -[MathWorld website](http://mathworld\.wolfram\.com) - -# COMMANDS - - - __::math::ln\_Gamma__ *z* - - Returns the natural logarithm of the Gamma function for the argument *z*\. - - The Gamma function is defined as the improper integral from zero to positive - infinity of - - t**(x-1)*exp(-t) dt - - The approximation used in the Tcl Math Library is from Lanczos, *ISIAM J\. - Numerical Analysis, series B,* volume 1, p\. 86\. For "__x__ > 1", the - absolute error of the result is claimed to be smaller than 5\.5\*10\*\*\-10 \-\- - that is, the resulting value of Gamma when - - exp( ln_Gamma( x) ) - - is computed is expected to be precise to better than nine significant - figures\. - - - __::math::factorial__ *x* - - Returns the factorial of the argument *x*\. - - For integer *x*, 0 <= *x* <= 12, an exact integer result is returned\. - - For integer *x*, 13 <= *x* <= 21, an exact floating\-point result is - returned on machines with IEEE floating point\. - - For integer *x*, 22 <= *x* <= 170, the result is exact to 1 ULP\. - - For real *x*, *x* >= 0, the result is approximated by computing - *Gamma\(x\+1\)* using the __::math::ln\_Gamma__ function, and the result - is expected to be precise to better than nine significant figures\. - - It is an error to present *x* <= \-1 or *x* > 170, or a value of *x* - that is not numeric\. - - - __::math::choose__ *n k* - - Returns the binomial coefficient *C\(n, k\)* - - C(n,k) = n! / k! (n-k)! - - If both parameters are integers and the result fits in 32 bits, the result - is rounded to an integer\. - - Integer results are exact up to at least *n* = 34\. Floating point results - are precise to better than nine significant figures\. - - - __::math::Beta__ *z w* - - Returns the Beta function of the parameters *z* and *w*\. - - Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w) - - Results are returned as a floating point number precise to better than nine - significant digits provided that *w* and *z* are both at least 1\. - - - __::math::combinatorics::permutations__ *n* - - Return the number of permutations of n items\. The returned number is always - an integer, it is not limited by the range of 32\-or 64\-bits integers using - the arbitrary precision integers available in Tcl 8\.5 and later\. - - * int *n* - - The number of items to be permuted\. - - - __::math::combinatorics::variations__ *n* *k* - - Return the number of variations k items selected from the total of n items\. - The order of the items is taken into account\. - - * int *n* - - The number of items to be selected from\. - - * int *k* - - The number of items to be selected in each variation\. - - - __::math::combinatorics::combinations__ *n* *k* - - Return the number of combinations of k items selected from the total of n - items\. The order of the items is not important\. - - * int *n* - - The number of items to be selected from\. - - * int *k* - - The number of items to be selected in each combination\. - - - __::math::combinatorics::derangements__ *n* - - Return the number of derangements of n items\. A derangement is a permutation - where each item is displaced from the original position\. - - * int *n* - - The number of items to be rearranged\. - - - __::math::combinatorics::catalan__ *n* - - Return the n'th Catalan number\. The number n is expected to be 1 or larger\. - These numbers occur in various combinatorial problems\. - - * int *n* - - The index of the Catalan number - - - __::math::combinatorics::firstStirling__ *n* *m* - - Calculate a Stirling number of the first kind \(signed version, m cycles in a - permutation of n items\) - - * int *n* - - Number of items - - * int *m* - - Number of cycles - - - __::math::combinatorics::secondStirling__ *n* *m* - - Calculate a Stirling number of the second kind \(m non\-empty subsets from n - items\) - - * int *n* - - Number of items - - * int *m* - - Number of subsets - - - __::math::combinatorics::partitionP__ *n* - - Calculate the number of ways an integer n can be written as the sum of - positive integers\. - - * int *n* - - Number in question - - - __::math::combinatorics::list\-permutations__ *n* - - Return the list of permutations of the numbers 0, \.\.\., n\-1\. - - * int *n* - - The number of items to be permuted\. - - - __::math::combinatorics::list\-variations__ *n* *k* - - Return the list of variations of k numbers selected from the numbers 0, \.\.\., - n\-1\. The order of the items is taken into account\. - - * int *n* - - The number of items to be selected from\. - - * int *k* - - The number of items to be selected in each variation\. - - - __::math::combinatorics::list\-combinations__ *n* *k* - - Return the list of combinations of k numbers selected from the numbers 0, - \.\.\., n\-1\. The order of the items is ignored\. - - * int *n* - - The number of items to be selected from\. - - * int *k* - - The number of items to be selected in each combination\. - - - __::math::combinatorics::list\-derangements__ *n* - - Return the list of derangements of the numbers 0, \.\.\., n\-1\. - - * int *n* - - The number of items to be rearranged\. - - - __::math::combinatorics::list\-powerset__ *n* - - Return the list of all subsets of the numbers 0, \.\.\., n\-1\. - - * int *n* - - The number of items to be rearranged\. - - - __::math::combinatorics::permutationObj__ new/create NAME *n* - - Create a TclOO object for returning permutations one by one\. If the last - permutation has been reached an empty list is returned\. - - * int *n* - - The number of items to be rearranged\. - - - __$perm__ next - - Return the next permutation of n objects\. - - - __$perm__ reset - - Reset the object, so that the command *next* returns the complete list - again\. - - - __$perm__ setElements *elements* - - Register a list of items to be permuted, using the *nextElements* command\. - - * list *elements* - - The list of n items that will be permuted\. - - - __$perm__ setElements - - Return the next permulation of the registered items\. - - - __::math::combinatorics::combinationObj__ new/create NAME *n* *k* - - Create a TclOO object for returning combinations one by one\. If the last - combination has been reached an empty list is returned\. - - * int *n* - - The number of items to be rearranged\. - - - __$combin__ next - - Return the next combination of n objects\. - - - __$combin__ reset - - Reset the object, so that the command *next* returns the complete list - again\. - - - __$combin__ setElements *elements* - - Register a list of items to be permuted, using the *nextElements* command\. - - * list *elements* - - The list of n items that will be permuted\. - - - __$combin__ setElements - - Return the next combination of the registered items\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/constants.md Index: embedded/md/tcllib/files/modules/math/constants.md ================================================================== --- embedded/md/tcllib/files/modules/math/constants.md +++ embedded/md/tcllib/files/modules/math/constants.md @@ -1,207 +0,0 @@ - -[//000000001]: # (math::constants \- Tcl Math Library) -[//000000002]: # (Generated from file 'constants\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (math::constants\(n\) 1\.0\.2 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::constants \- Mathematical and numerical constants - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [Constants](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.3? -package require math::constants ?1\.0\.2? - -[__::math::constants::constants__ *args*](#1) -[__::math::constants::print\-constants__ *args*](#2) - -# DESCRIPTION - -This package defines some common mathematical and numerical constants\. By using -the package you get consistent values for numbers like pi and ln\(10\)\. - -It defines two commands: - - - One for importing the constants - - - One for reporting which constants are defined and what values they actually - have\. - -The motivation for this package is that quite often, with \(mathematical\) -computations, you need a good approximation to, say, the ratio of degrees to -radians\. You can, of course, define this like: - - variable radtodeg [expr {180.0/(4.0*atan(1.0))}] - -and use the variable radtodeg whenever you need the conversion\. - -This has two drawbacks: - - - You need to remember the proper formula or value and that is error\-prone\. - - - Especially with the use of mathematical functions like *atan* you assume - that they have been accurately implemented\. This is seldom or never the case - and for each platform you can get subtle differences\. - -Here is the way you can do it with the *math::constants* package: - - package require math::constants - ::math::constants::constants radtodeg degtorad - -which creates two variables, radtodeg and \(its reciprocal\) degtorad in the -calling namespace\. - -Constants that have been defined \(their values are mostly taken from -mathematical tables with more precision than usually can be handled\) include: - - - basic constants like pi, e, gamma \(Euler's constant\) - - - derived values like ln\(10\) and sqrt\(2\) - - - purely numerical values such as 1/3 that are included for convenience and - for the fact that certain seemingly trivial computations like: - - set value [expr {3.0*$onethird}] - - give *exactly* the value you expect \(if IEEE arithmetic is available\)\. - -The full set of named constants is listed in section -[Constants](#section3)\. - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::constants::constants__ *args* - - Import the constants whose names are given as arguments - - - __::math::constants::print\-constants__ *args* - - Print the constants whose names are given as arguments on the screen \(name, - value and description\) or, if no arguments are given, print all defined - constants\. This is mainly a convenience procedure\. - -# Constants - - - __pi__ - - Ratio of circle circumference to diameter - - - __e__ - - Base for natural logarithm - - - __ln10__ - - Natural logarithm of 10 - - - __phi__ - - Golden ratio - - - __gamma__ - - Euler's constant - - - __sqrt2__ - - Square root of 2 - - - __thirdrt2__ - - One\-third power of 2 - - - __sqrt3__ - - Square root of 3 - - - __radtodeg__ - - Conversion from radians to degrees - - - __degtorad__ - - Conversion from degrees to radians - - - __onethird__ - - One third \(0\.3333\.\.\.\.\) - - - __twothirds__ - - Two thirds \(0\.6666\.\.\.\.\) - - - __onesixth__ - - One sixth \(0\.1666\.\.\.\.\) - - - __huge__ - - \(Approximately\) largest number - - - __tiny__ - - \(Approximately\) smallest number not equal zero - - - __eps__ - - Smallest number such that 1\+eps \!= 1 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: constants* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[constants](\.\./\.\./\.\./\.\./index\.md\#constants), -[degrees](\.\./\.\./\.\./\.\./index\.md\#degrees), [e](\.\./\.\./\.\./\.\./index\.md\#e), -[math](\.\./\.\./\.\./\.\./index\.md\#math), [pi](\.\./\.\./\.\./\.\./index\.md\#pi), -[radians](\.\./\.\./\.\./\.\./index\.md\#radians) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/decimal.md Index: embedded/md/tcllib/files/modules/math/decimal.md ================================================================== --- embedded/md/tcllib/files/modules/math/decimal.md +++ embedded/md/tcllib/files/modules/math/decimal.md @@ -1,339 +0,0 @@ - -[//000000001]: # (math::decimal \- Tcl Decimal Arithmetic Library) -[//000000002]: # (Generated from file 'decimal\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Mark Alston ) -[//000000004]: # (math::decimal\(n\) 1\.0\.3 tcllib "Tcl Decimal Arithmetic Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::decimal \- General decimal arithmetic - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::decimal 1\.0\.3 - -[__::math::decimal::fromstr__ *string*](#1) -[__::math::decimal::tostr__ *decimal*](#2) -[__::math::decimal::setVariable__ *variable* *setting*](#3) -[__::math::decimal::add__ *a* *b*](#4) -[__::math::decimal::\+__ *a* *b*](#5) -[__::math::decimal::subtract__ *a* *b*](#6) -[__::math::decimal::\-__ *a* *b*](#7) -[__::math::decimal::multiply__ *a* *b*](#8) -[__::math::decimal::\*__ *a* *b*](#9) -[__::math::decimal::divide__ *a* *b*](#10) -[__::math::decimal::/__ *a* *b*](#11) -[__::math::decimal::divideint__ *a* *b*](#12) -[__::math::decimal::remainder__ *a* *b*](#13) -[__::math::decimal::abs__ *decimal*](#14) -[__::math::decimal::compare__ *a* *b*](#15) -[__::math::decimal::max__ *a* *b*](#16) -[__::math::decimal::maxmag__ *a* *b*](#17) -[__::math::decimal::min__ *a* *b*](#18) -[__::math::decimal::minmag__ *a* *b*](#19) -[__::math::decimal::plus__ *a*](#20) -[__::math::decimal::minus__ *a*](#21) -[__::math::decimal::copynegate__ *a*](#22) -[__::math::decimal::copysign__ *a* *b*](#23) -[__::math::decimal::is\-signed__ *decimal*](#24) -[__::math::decimal::is\-zero__ *decimal*](#25) -[__::math::decimal::is\-NaN__ *decimal*](#26) -[__::math::decimal::is\-infinite__ *decimal*](#27) -[__::math::decimal::is\-finite__ *decimal*](#28) -[__::math::decimal::fma__ *a* *b* *c*](#29) -[__::math::decimal::round\_half\_even__ *decimal* *digits*](#30) -[__::math::decimal::round\_half\_up__ *decimal* *digits*](#31) -[__::math::decimal::round\_half\_down__ *decimal* *digits*](#32) -[__::math::decimal::round\_down__ *decimal* *digits*](#33) -[__::math::decimal::round\_up__ *decimal* *digits*](#34) -[__::math::decimal::round\_floor__ *decimal* *digits*](#35) -[__::math::decimal::round\_ceiling__ *decimal* *digits*](#36) -[__::math::decimal::round\_05up__ *decimal* *digits*](#37) - -# DESCRIPTION - -The decimal package provides decimal arithmetic support for both limited -precision floating point and arbitrary precision floating point\. Additionally, -integer arithmetic is supported\. - -More information and the specifications on which this package depends can be -found on the general decimal arithmetic page at http://speleotrove\.com/decimal -This package provides for: - - - A new data type decimal which is represented as a list containing sign, - mantissa and exponent\. - - - Arithmetic operations on those decimal numbers such as addition, - subtraction, multiplication, etc\.\.\. - -Numbers are converted to decimal format using the operation -::math::decimal::fromstr\. - -Numbers are converted back to string format using the operation -::math::decimal::tostr\. - -# EXAMPLES - -This section shows some simple examples\. Since the purpose of this library is to -perform decimal math operations, examples may be the simplest way to learn how -to work with it and to see the difference between using this package and -sticking with expr\. Consult the API section of this man page for information -about individual procedures\. - - package require math::decimal - - # Various operations on two numbers. - # We first convert them to decimal format. - set a [::math::decimal::fromstr 8.2] - set b [::math::decimal::fromstr .2] - - # Then we perform our operations. Here we add - set c [::math::decimal::+ $a $b] - - # Finally we convert back to string format for presentation to the user. - puts [::math::decimal::tostr $c] ; # => will output 8.4 - - # Other examples - # - # Subtraction - set c [::math::decimal::- $a $b] - puts [::math::decimal::tostr $c] ; # => will output 8.0 - - # Why bother using this instead of simply expr? - puts [expr {8.2 + .2}] ; # => will output 8.399999999999999 - puts [expr {8.2 - .2}] ; # => will output 7.999999999999999 - # See http://speleotrove.com/decimal to learn more about why this happens. - -# API - - - __::math::decimal::fromstr__ *string* - - Convert *string* into a decimal\. - - - __::math::decimal::tostr__ *decimal* - - Convert *decimal* into a string representing the number in base 10\. - - - __::math::decimal::setVariable__ *variable* *setting* - - Sets the *variable* to *setting*\. Valid variables are: - - * *rounding* \- Method of rounding to use during rescale\. Valid methods - are round\_half\_even, round\_half\_up, round\_half\_down, round\_down, - round\_up, round\_floor, round\_ceiling\. - - * *precision* \- Maximum number of digits allowed in mantissa\. - - * *extended* \- Set to 1 for extended mode\. 0 for simplified mode\. - - * *maxExponent* \- Maximum value for the exponent\. Defaults to 999\. - - * *minExponent* \- Minimum value for the exponent\. Default to \-998\. - - - __::math::decimal::add__ *a* *b* - - - __::math::decimal::\+__ *a* *b* - - Return the sum of the two decimals *a* and *b*\. - - - __::math::decimal::subtract__ *a* *b* - - - __::math::decimal::\-__ *a* *b* - - Return the differnece of the two decimals *a* and *b*\. - - - __::math::decimal::multiply__ *a* *b* - - - __::math::decimal::\*__ *a* *b* - - Return the product of the two decimals *a* and *b*\. - - - __::math::decimal::divide__ *a* *b* - - - __::math::decimal::/__ *a* *b* - - Return the quotient of the division between the two decimals *a* and - *b*\. - - - __::math::decimal::divideint__ *a* *b* - - Return a the integer portion of the quotient of the division between - decimals *a* and *b* - - - __::math::decimal::remainder__ *a* *b* - - Return the remainder of the division between the two decimals *a* and - *b*\. - - - __::math::decimal::abs__ *decimal* - - Return the absolute value of the decimal\. - - - __::math::decimal::compare__ *a* *b* - - Compare the two decimals a and b, returning *0* if *a == b*, *1* if - *a > b*, and *\-1* if *a < b*\. - - - __::math::decimal::max__ *a* *b* - - Compare the two decimals a and b, and return *a* if *a >= b*, and *b* - if *a < b*\. - - - __::math::decimal::maxmag__ *a* *b* - - Compare the two decimals a and b while ignoring their signs, and return - *a* if *abs\(a\) >= abs\(b\)*, and *b* if *abs\(a\) < abs\(b\)*\. - - - __::math::decimal::min__ *a* *b* - - Compare the two decimals a and b, and return *a* if *a <= b*, and *b* - if *a > b*\. - - - __::math::decimal::minmag__ *a* *b* - - Compare the two decimals a and b while ignoring their signs, and return - *a* if *abs\(a\) <= abs\(b\)*, and *b* if *abs\(a\) > abs\(b\)*\. - - - __::math::decimal::plus__ *a* - - Return the result from *::math::decimal::\+ 0 $a*\. - - - __::math::decimal::minus__ *a* - - Return the result from *::math::decimal::\- 0 $a*\. - - - __::math::decimal::copynegate__ *a* - - Returns *a* with the sign flipped\. - - - __::math::decimal::copysign__ *a* *b* - - Returns *a* with the sign set to the sign of the *b*\. - - - __::math::decimal::is\-signed__ *decimal* - - Return the sign of the decimal\. The procedure returns 0 if the number is - positive, 1 if it's negative\. - - - __::math::decimal::is\-zero__ *decimal* - - Return true if *decimal* value is zero, otherwise false is returned\. - - - __::math::decimal::is\-NaN__ *decimal* - - Return true if *decimal* value is NaN \(not a number\), otherwise false is - returned\. - - - __::math::decimal::is\-infinite__ *decimal* - - Return true if *decimal* value is Infinite, otherwise false is returned\. - - - __::math::decimal::is\-finite__ *decimal* - - Return true if *decimal* value is finite, otherwise false is returned\. - - - __::math::decimal::fma__ *a* *b* *c* - - Return the result from first multiplying *a* by *b* and then adding - *c*\. Rescaling only occurs after completion of all operations\. In this way - the result may vary from that returned by performing the operations - individually\. - - - __::math::decimal::round\_half\_even__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round to the nearest\. If equidistant, round so the final digit is - even\. - - - __::math::decimal::round\_half\_up__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round to the nearest\. If equidistant, round up\. - - - __::math::decimal::round\_half\_down__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round to the nearest\. If equidistant, round down\. - - - __::math::decimal::round\_down__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round toward 0\. \(Truncate\) - - - __::math::decimal::round\_up__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round away from 0 - - - __::math::decimal::round\_floor__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round toward \-Infinity\. - - - __::math::decimal::round\_ceiling__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round toward Infinity - - - __::math::decimal::round\_05up__ *decimal* *digits* - - Rounds *decimal* to *digits* number of decimal points with the following - rules: Round zero or five away from 0\. The same as round\-up, except that - rounding up only occurs if the digit to be rounded up is 0 or 5, and after - overflow the result is the same as for round\-down\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *decimal* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[decimal](\.\./\.\./\.\./\.\./index\.md\#decimal), -[math](\.\./\.\./\.\./\.\./index\.md\#math), [tcl](\.\./\.\./\.\./\.\./index\.md\#tcl) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2011 Mark Alston DELETED embedded/md/tcllib/files/modules/math/exact.md Index: embedded/md/tcllib/files/modules/math/exact.md ================================================================== --- embedded/md/tcllib/files/modules/math/exact.md +++ embedded/md/tcllib/files/modules/math/exact.md @@ -1,265 +0,0 @@ - -[//000000001]: # (math::exact \- Tcl Math Library) -[//000000002]: # (Generated from file 'exact\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Kevin B\. Kenny ) -[//000000004]: # (Redistribution permitted under the terms of the Open Publication License ) -[//000000005]: # (math::exact\(n\) 1\.0\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::exact \- Exact Real Arithmetic - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Procedures](#section2) - - - [Parameters](#section3) - - - [Expressions](#section4) - - - [Functions](#section5) - - - [Summary](#section6) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require grammar::aycock 1\.0 -package require math::exact 1\.0\.1 - -[__::math::exact::exactexpr__ *expr*](#1) -[*number* __ref__](#2) -[*number* __unref__](#3) -[*number* __asPrint__ *precision*](#4) -[*number* __asFloat__ *precision*](#5) - -# DESCRIPTION - -The __exactexpr__ command in the __math::exact__ package allows for -exact computations over the computable real numbers\. These are not -arbitrary\-precision calculations; rather they are exact, with numbers -represented by algorithms that produce successive approximations\. At the end of -a calculation, the caller can request a given precision for the end result, and -intermediate results are computed to whatever precision is necessary to satisfy -the request\. - -# Procedures - -The following procedure is the primary entry into the __math::exact__ -package\. - - - __::math::exact::exactexpr__ *expr* - - Accepts a mathematical expression in Tcl syntax, and returns an object that - represents the program to calculate successive approximations to the - expression's value\. The result will be referred to as an exact real number\. - - - *number* __ref__ - - Increases the reference count of a given exact real number\. - - - *number* __unref__ - - Decreases the reference count of a given exact real number, and destroys the - number if the reference count is zero\. - - - *number* __asPrint__ *precision* - - Formats the given *number* for printing, with the specified *precision*\. - \(See below for how *precision* is interpreted\)\. Numbers that are known to - be rational are formatted as fractions\. - - - *number* __asFloat__ *precision* - - Formats the given *number* for printing, with the specified *precision*\. - \(See below for how *precision* is interpreted\)\. All numbers are formatted - in floating\-point E format\. - -# Parameters - - - *expr* - - Expression to evaluate\. The syntax for expressions is the same as it is in - Tcl, but the set of operations is smaller\. See [Expressions](#section4) - below for details\. - - - *number* - - The object returned by an earlier invocation of - __math::exact::exactexpr__ - - - *precision* - - The requested 'precision' of the result\. The precision is \(approximately\) - the absolute value of the binary exponent plus the number of bits of the - binary significand\. For instance, to return results to IEEE\-754 double - precision, 56 bits plus the exponent are required\. Numbers between 1/2 and 2 - will require a precision of 57; numbers between 1/4 and 1/2 or between 2 and - 4 will require 58; numbers between 1/8 and 1/4 or between 4 and 8 will - require 59; and so on\. - -# Expressions - -The __math::exact::exactexpr__ command accepts expressions in a subset of -Tcl's syntax\. The following components may be used in an expression\. - - - Decimal integers\. - - - Variable references with the dollar sign \(__$__\)\. The value of the - variable must be the result of another call to - __math::exact::exactexpr__\. The reference count of the value will be - increased by one for each position at which it appears in the expression\. - - - The exponentiation operator \(__\*\*__\)\. - - - Unary plus \(__\+__\) and minus \(__\-__\) operators\. - - - Multiplication \(__\*__\) and division \(__/__\) operators\. - - - Parentheses used for grouping\. - - - Functions\. See [Functions](#section5) below for the functions that are - available\. - -# Functions - -The following functions are available for use within exact real expressions\. - - - __acos\(__*x*__\)__ - - The inverse cosine of *x*\. The result is expressed in radians\. The - absolute value of *x* must be less than 1\. - - - __acosh\(__*x*__\)__ - - The inverse hyperbolic cosine of *x*\. *x* must be greater than 1\. - - - __asin\(__*x*__\)__ - - The inverse sine of *x*\. The result is expressed in radians\. The absolute - value of *x* must be less than 1\. - - - __asinh\(__*x*__\)__ - - The inverse hyperbolic sine of *x*\. - - - __atan\(__*x*__\)__ - - The inverse tangent of *x*\. The result is expressed in radians\. - - - __atanh\(__*x*__\)__ - - The inverse hyperbolic tangent of *x*\. The absolute value of *x* must be - less than 1\. - - - __cos\(__*x*__\)__ - - The cosine of *x*\. *x* is expressed in radians\. - - - __cosh\(__*x*__\)__ - - The hyperbolic cosine of *x*\. - - - __e\(\)__ - - The base of the natural logarithms = __2\.71828\.\.\.__ - - - __exp\(__*x*__\)__ - - The exponential function of *x*\. - - - __log\(__*x*__\)__ - - The natural logarithm of *x*\. *x* must be positive\. - - - __pi\(\)__ - - The value of pi = __3\.15159\.\.\.__ - - - __sin\(__*x*__\)__ - - The sine of *x*\. *x* is expressed in radians\. - - - __sinh\(__*x*__\)__ - - The hyperbolic sine of *x*\. - - - __sqrt\(__*x*__\)__ - - The square root of *x*\. *x* must be positive\. - - - __tan\(__*x*__\)__ - - The tangent of *x*\. *x* is expressed in radians\. - - - __tanh\(__*x*__\)__ - - The hyperbolic tangent of *x*\. - -# Summary - -The __math::exact::exactexpr__ command provides a system that performs exact -arithmetic over computable real numbers, representing the numbers as algorithms -for successive approximation\. An example, which implements the high\-school -quadratic formula, is shown below\. - - namespace import math::exact::exactexpr - proc exactquad {a b c} { - set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref] - set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref] - set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref] - $d unref - return [list $r0 $r1] - } - - set a [[exactexpr 1] ref] - set b [[exactexpr 200] ref] - set c [[exactexpr {(-3/2) * 10**-12}] ref] - lassign [exactquad $a $b $c] r0 r1 - $a unref; $b unref; $c unref - puts [list [$r0 asFloat 70] [$r1 asFloat 110]] - $r0 unref; $r1 unref - -The program prints the result: - - -2.000000000000000075e2 7.499999999999999719e-15 - -Note that if IEEE\-754 floating point had been used, a catastrophic roundoff -error would yield a smaller root that is a factor of two too high: - - -200.0 1.4210854715202004e-14 - -The invocations of __exactexpr__ should be fairly self\-explanatory\. The -other commands of note are __ref__ and __unref__\. It is necessary for -the caller to keep track of references to exact expressions \- to call -__ref__ every time an exact expression is stored in a variable and -__unref__ every time the variable goes out of scope or is overwritten\. The -__asFloat__ method emits decimal digits as long as the requested precision -supports them\. It terminates when the requested precision yields an uncertainty -of more than one unit in the least significant digit\. - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2015 Kevin B\. Kenny -Redistribution permitted under the terms of the Open Publication License DELETED embedded/md/tcllib/files/modules/math/filtergen.md Index: embedded/md/tcllib/files/modules/math/filtergen.md ================================================================== --- embedded/md/tcllib/files/modules/math/filtergen.md +++ embedded/md/tcllib/files/modules/math/filtergen.md @@ -1,132 +0,0 @@ - -[//000000001]: # (math::filters \- Tcl Math Library) -[//000000002]: # (Generated from file 'filtergen\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2020 by Arjen Markus) -[//000000004]: # (math::filters\(n\) 0\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::filters \- Digital filters - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::filters ?0\.1? - -[__::math::filters::filterButterworth__ *lowpass* *order* *samplefreq* *cutofffreq*](#1) -[__::math::filters::filter__ *coeffs* *data*](#2) -[__::math::filters::filterObj__ new *coeffs* *yinit*](#3) -[__$filterObj__ filter *x*](#4) -[__$filterObj__ reset](#5) - -# DESCRIPTION - -The __math::filters__ package implements digital filters, notably -Butterworth low\-pass and high\-pass filters\. The procedures allow to filter an -entire data series as well as filter data one by one\. - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::filters::filterButterworth__ *lowpass* *order* *samplefreq* *cutofffreq* - - Determine the coefficients for a Butterworth filter of given order\. The - coefficients are returned as a list of the x\-coefficients, the - y\-coefficients and the scale\. The formula is \(n is the filter order\): - - n n - scale * y_k = sum x_(k-i) + sum y_(k-i) - i=0 i=1 - - * bool *lowpass* - - Generate a low\-pass filter \(1\) or a high\-pass filter \(0\) - - * integer *lowpass* - - The order of the filter to be generated - - * double *samplefreq* - - Sampling frequency of the data series - - * double *cutofffreq* - - Cut\-off frequency for the filter - - - __::math::filters::filter__ *coeffs* *data* - - Filter the entire data series based on the filter coefficients\. - - * list *coeffs* - - List of coefficients as generated by *filterButterworth* \(or in fact - any similar list of coefficients\) - - * list *data* - - Data to be filtered - - - __::math::filters::filterObj__ new *coeffs* *yinit* - - Create a filter object\. The initial x data are taken as zero\. The initial y - data can be prescribed\. If they are not given, they are taken as zero as - well\. - - * list *coeffs* - - List of coefficients as generated by *filterButterworth* \(or in fact - any similar list of coefficients\) - - * list *yinit* - - \(Optional\) initial data for the filter result\. - - - __$filterObj__ filter *x* - - Filter a single value and return the result\. - - * double *x* - - The value to be filtered - - - __$filterObj__ reset - - Reset the filter object \(start anew\) - -# KEYWORDS - -[digital](\.\./\.\./\.\./\.\./index\.md\#digital), -[filtering](\.\./\.\./\.\./\.\./index\.md\#filtering) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2020 by Arjen Markus DELETED embedded/md/tcllib/files/modules/math/fourier.md Index: embedded/md/tcllib/files/modules/math/fourier.md ================================================================== --- embedded/md/tcllib/files/modules/math/fourier.md +++ embedded/md/tcllib/files/modules/math/fourier.md @@ -1,180 +0,0 @@ - -[//000000001]: # (math::fourier \- Tcl Math Library) -[//000000002]: # (Generated from file 'fourier\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::fourier\(n\) 1\.0\.2 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::fourier \- Discrete and fast fourier transforms - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [GENERAL INFORMATION](#section2) - - - [PROCEDURES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require math::fourier 1\.0\.2 - -[__::math::fourier::dft__ *in\_data*](#1) -[__::math::fourier::inverse\_dft__ *in\_data*](#2) -[__::math::fourier::lowpass__ *cutoff* *in\_data*](#3) -[__::math::fourier::highpass__ *cutoff* *in\_data*](#4) - -# DESCRIPTION - -The __math::fourier__ package implements two versions of discrete Fourier -transforms, the ordinary transform and the fast Fourier transform\. It also -provides a few simple filter procedures as an illustrations of how such filters -can be implemented\. - -The purpose of this document is to describe the implemented procedures and -provide some examples of their usage\. As there is ample literature on the -algorithms involved, we refer to relevant text books for more explanations\. We -also refer to the original Wiki page on the subject which describes some of the -considerations behind the current implementation\. - -# GENERAL INFORMATION - -The two top\-level procedures defined are - - - dft data\-list - - - inverse\_dft data\-list - -Both take a list of *complex numbers* and apply a Discrete Fourier Transform -\(DFT\) or its inverse respectively to these lists of numbers\. A "complex number" -in this case is either \(i\) a pair \(two element list\) of numbers, interpreted as -the real and imaginary parts of the complex number, or \(ii\) a single number, -interpreted as the real part of a complex number whose imaginary part is zero\. -The return value is always in the first format\. \(The DFT generally produces -complex results even if the input is purely real\.\) Applying first one and then -the other of these procedures to a list of complex numbers will \(modulo rounding -errors due to floating point arithmetic\) return the original list of numbers\. - -If the input length N is a power of two then these procedures will utilize the -O\(N log N\) Fast Fourier Transform algorithm\. If input length is not a power of -two then the DFT will instead be computed using a the naive quadratic algorithm\. - -Some examples: - - % dft {1 2 3 4} - {10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0} - % inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}} - {1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0} - % dft {1 2 3 4 5} - {15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118} - % inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}} - {1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17} - -In the last case, the imaginary parts <1e\-16 would have been zero in exact -arithmetic, but aren't here due to rounding errors\. - -Internally, the procedures use a flat list format where every even index element -of a list is a real part and every odd index element is an imaginary part\. This -is reflected in the variable names by Re\_ and Im\_ prefixes\. - -The package includes two simple filters\. They have an analogue equivalent in a -simple electronic circuit, a resistor and a capacitance in series\. Using these -filters requires the __[math::complexnumbers](qcomplex\.md)__ package\. - -# PROCEDURES - -The public Fourier transform procedures are: - - - __::math::fourier::dft__ *in\_data* - - Determine the *Fourier transform* of the given list of complex numbers\. - The result is a list of complex numbers representing the \(complex\) - amplitudes of the Fourier components\. - - * list *in\_data* - - List of data - - - __::math::fourier::inverse\_dft__ *in\_data* - - Determine the *inverse Fourier transform* of the given list of complex - numbers \(interpreted as amplitudes\)\. The result is a list of complex numbers - representing the original \(complex\) data - - * list *in\_data* - - List of data \(amplitudes\) - - - __::math::fourier::lowpass__ *cutoff* *in\_data* - - Filter the \(complex\) amplitudes so that high\-frequency components are - suppressed\. The implemented filter is a first\-order low\-pass filter, the - discrete equivalent of a simple electronic circuit with a resistor and a - capacitance\. - - * float *cutoff* - - Cut\-off frequency - - * list *in\_data* - - List of data \(amplitudes\) - - - __::math::fourier::highpass__ *cutoff* *in\_data* - - Filter the \(complex\) amplitudes so that low\-frequency components are - suppressed\. The implemented filter is a first\-order low\-pass filter, the - discrete equivalent of a simple electronic circuit with a resistor and a - capacitance\. - - * float *cutoff* - - Cut\-off frequency - - * list *in\_data* - - List of data \(amplitudes\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: fourier* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[FFT](\.\./\.\./\.\./\.\./index\.md\#fft), [Fourier -transform](\.\./\.\./\.\./\.\./index\.md\#fourier\_transform), [complex -numbers](\.\./\.\./\.\./\.\./index\.md\#complex\_numbers), -[mathematics](\.\./\.\./\.\./\.\./index\.md\#mathematics) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/fuzzy.md Index: embedded/md/tcllib/files/modules/math/fuzzy.md ================================================================== --- embedded/md/tcllib/files/modules/math/fuzzy.md +++ embedded/md/tcllib/files/modules/math/fuzzy.md @@ -1,190 +0,0 @@ - -[//000000001]: # (math::fuzzy \- Tcl Math Library) -[//000000002]: # (Generated from file 'fuzzy\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::fuzzy\(n\) 0\.2 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::fuzzy \- Fuzzy comparison of floating\-point numbers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [TEST CASES](#section3) - - - [REFERENCES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl ?8\.3? -package require math::fuzzy ?0\.2? - -[__::math::fuzzy::teq__ *value1* *value2*](#1) -[__::math::fuzzy::tne__ *value1* *value2*](#2) -[__::math::fuzzy::tge__ *value1* *value2*](#3) -[__::math::fuzzy::tle__ *value1* *value2*](#4) -[__::math::fuzzy::tlt__ *value1* *value2*](#5) -[__::math::fuzzy::tgt__ *value1* *value2*](#6) -[__::math::fuzzy::tfloor__ *value*](#7) -[__::math::fuzzy::tceil__ *value*](#8) -[__::math::fuzzy::tround__ *value*](#9) -[__::math::fuzzy::troundn__ *value* *ndigits*](#10) - -# DESCRIPTION - -The package Fuzzy is meant to solve common problems with floating\-point numbers -in a systematic way: - - - Comparing two numbers that are "supposed" to be identical, like 1\.0 and - 2\.1/\(1\.2\+0\.9\) is not guaranteed to give the intuitive result\. - - - Rounding a number that is halfway two integer numbers can cause strange - errors, like int\(100\.0\*2\.8\) \!= 28 but 27 - -The Fuzzy package is meant to help sorting out this type of problems by defining -"fuzzy" comparison procedures for floating\-point numbers\. It does so by allowing -for a small margin that is determined automatically \- the margin is three times -the "epsilon" value, that is three times the smallest number *eps* such that -1\.0 and 1\.0\+$eps canbe distinguished\. In Tcl, which uses double precision -floating\-point numbers, this is typically 1\.1e\-16\. - -# PROCEDURES - -Effectively the package provides the following procedures: - - - __::math::fuzzy::teq__ *value1* *value2* - - Compares two floating\-point numbers and returns 1 if their values fall - within a small range\. Otherwise it returns 0\. - - - __::math::fuzzy::tne__ *value1* *value2* - - Returns the negation, that is, if the difference is larger than the margin, - it returns 1\. - - - __::math::fuzzy::tge__ *value1* *value2* - - Compares two floating\-point numbers and returns 1 if their values either - fall within a small range or if the first number is larger than the second\. - Otherwise it returns 0\. - - - __::math::fuzzy::tle__ *value1* *value2* - - Returns 1 if the two numbers are equal according to \[teq\] or if the first is - smaller than the second\. - - - __::math::fuzzy::tlt__ *value1* *value2* - - Returns the opposite of \[tge\]\. - - - __::math::fuzzy::tgt__ *value1* *value2* - - Returns the opposite of \[tle\]\. - - - __::math::fuzzy::tfloor__ *value* - - Returns the integer number that is lower or equal to the given - floating\-point number, within a well\-defined tolerance\. - - - __::math::fuzzy::tceil__ *value* - - Returns the integer number that is greater or equal to the given - floating\-point number, within a well\-defined tolerance\. - - - __::math::fuzzy::tround__ *value* - - Rounds the floating\-point number off\. - - - __::math::fuzzy::troundn__ *value* *ndigits* - - Rounds the floating\-point number off to the specified number of decimals - \(Pro memorie\)\. - -Usage: - - if { [teq $x $y] } { puts "x == y" } - if { [tne $x $y] } { puts "x != y" } - if { [tge $x $y] } { puts "x >= y" } - if { [tgt $x $y] } { puts "x > y" } - if { [tlt $x $y] } { puts "x < y" } - if { [tle $x $y] } { puts "x <= y" } - - set fx [tfloor $x] - set fc [tceil $x] - set rounded [tround $x] - set roundn [troundn $x $nodigits] - -# TEST CASES - -The problems that can occur with floating\-point numbers are illustrated by the -test cases in the file "fuzzy\.test": - - - Several test case use the ordinary comparisons, and they fail invariably to - produce understandable results - - - One test case uses \[expr\] without braces \(\{ and \}\)\. It too fails\. - -The conclusion from this is that any expression should be surrounded by braces, -because otherwise very awkward things can happen if you need accuracy\. -Furthermore, accuracy and understandable results are enhanced by using these -"tolerant" or fuzzy comparisons\. - -Note that besides the Tcl\-only package, there is also a C\-based version\. - -# REFERENCES - -Original implementation in Fortran by dr\. H\.D\. Knoble \(Penn State University\)\. - -P\. E\. Hagerty, "More on Fuzzy Floor and Ceiling," APL QUOTE QUAD 8\(4\):20\-24, -June 1978\. Note that TFLOOR=FL5 took five years of refereed evolution -\(publication\)\. - -L\. M\. Breed, "Definitions for Fuzzy Floor and Ceiling", APL QUOTE QUAD -8\(3\):16\-23, March 1978\. - -D\. Knuth, Art of Computer Programming, Vol\. 1, Problem 1\.2\.4\-5\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: fuzzy* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[floating\-point](\.\./\.\./\.\./\.\./index\.md\#floating\_point), -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[rounding](\.\./\.\./\.\./\.\./index\.md\#rounding) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/interpolate.md Index: embedded/md/tcllib/files/modules/math/interpolate.md ================================================================== --- embedded/md/tcllib/files/modules/math/interpolate.md +++ embedded/md/tcllib/files/modules/math/interpolate.md @@ -1,350 +0,0 @@ - -[//000000001]: # (math::interpolate \- Tcl Math Library) -[//000000002]: # (Generated from file 'interpolate\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (Copyright © 2004 Kevn B\. Kenny ) -[//000000005]: # (math::interpolate\(n\) 1\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::interpolate \- Interpolation routines - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [INCOMPATIBILITY WITH VERSION 1\.0\.3](#section2) - - - [PROCEDURES](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require struct -package require math::interpolate ?1\.1? - -[__::math::interpolate::defineTable__ *name* *colnames* *values*](#1) -[__::math::interpolate::interp\-1d\-table__ *name* *xval*](#2) -[__::math::interpolate::interp\-table__ *name* *xval* *yval*](#3) -[__::math::interpolate::interp\-linear__ *xyvalues* *xval*](#4) -[__::math::interpolate::interp\-lagrange__ *xyvalues* *xval*](#5) -[__::math::interpolate::prepare\-cubic\-splines__ *xcoord* *ycoord*](#6) -[__::math::interpolate::interp\-cubic\-splines__ *coeffs* *x*](#7) -[__::math::interpolate::interp\-spatial__ *xyvalues* *coord*](#8) -[__::math::interpolate::interp\-spatial\-params__ *max\_search* *power*](#9) -[__::math::interpolate::neville__ *xlist* *ylist* *x*](#10) - -# DESCRIPTION - -This package implements several interpolation algorithms: - - - Interpolation into a table \(one or two independent variables\), this is - useful for example, if the data are static, like with tables of statistical - functions\. - - - Linear interpolation into a given set of data \(organised as \(x,y\) pairs\)\. - - - Lagrange interpolation\. This is mainly of theoretical interest, because - there is no guarantee about error bounds\. One possible use: if you need a - line or a parabola through given points \(it will calculate the values, but - not return the coefficients\)\. - - A variation is Neville's method which has better behaviour and error bounds\. - - - Spatial interpolation using a straightforward distance\-weight method\. This - procedure allows any number of spatial dimensions and any number of - dependent variables\. - - - Interpolation in one dimension using cubic splines\. - -This document describes the procedures and explains their usage\. - -# INCOMPATIBILITY WITH VERSION 1\.0\.3 - -The interpretation of the tables in the -__::math::interpolate::interpolate\-1d\-table__ command has been changed to be -compatible with the interpretation for 2D interpolation in the -__::math::interpolate::interpolate\-table__ command\. As a consequence this -version is incompatible with the previous versions of the command \(1\.0\.x\)\. - -# PROCEDURES - -The interpolation package defines the following public procedures: - - - __::math::interpolate::defineTable__ *name* *colnames* *values* - - Define a table with one or two independent variables \(the distinction is - implicit in the data\)\. The procedure returns the name of the table \- this - name is used whenever you want to interpolate the values\. *Note:* this - procedure is a convenient wrapper for the struct::matrix procedure\. - Therefore you can access the data at any location in your program\. - - * string *name* \(in\) - - Name of the table to be created - - * list *colnames* \(in\) - - List of column names - - * list *values* \(in\) - - List of values \(the number of elements should be a multiple of the - number of columns\. See [EXAMPLES](#section4) for more information - on the interpretation of the data\. - - The values must be sorted with respect to the independent variable\(s\)\. - - - __::math::interpolate::interp\-1d\-table__ *name* *xval* - - Interpolate into the one\-dimensional table "name" and return a list of - values, one for each dependent column\. - - * string *name* \(in\) - - Name of an existing table - - * float *xval* \(in\) - - Value of the independent *row* variable - - - __::math::interpolate::interp\-table__ *name* *xval* *yval* - - Interpolate into the two\-dimensional table "name" and return the - interpolated value\. - - * string *name* \(in\) - - Name of an existing table - - * float *xval* \(in\) - - Value of the independent *row* variable - - * float *yval* \(in\) - - Value of the independent *column* variable - - - __::math::interpolate::interp\-linear__ *xyvalues* *xval* - - Interpolate linearly into the list of x,y pairs and return the interpolated - value\. - - * list *xyvalues* \(in\) - - List of pairs of \(x,y\) values, sorted to increasing x\. They are used as - the breakpoints of a piecewise linear function\. - - * float *xval* \(in\) - - Value of the independent variable for which the value of y must be - computed\. - - - __::math::interpolate::interp\-lagrange__ *xyvalues* *xval* - - Use the list of x,y pairs to construct the unique polynomial of lowest - degree that passes through all points and return the interpolated value\. - - * list *xyvalues* \(in\) - - List of pairs of \(x,y\) values - - * float *xval* \(in\) - - Value of the independent variable for which the value of y must be - computed\. - - - __::math::interpolate::prepare\-cubic\-splines__ *xcoord* *ycoord* - - Returns a list of coefficients for the second routine - *interp\-cubic\-splines* to actually interpolate\. - - * list *xcoord* - - List of x\-coordinates for the value of the function to be interpolated - is known\. The coordinates must be strictly ascending\. At least three - points are required\. - - * list *ycoord* - - List of y\-coordinates \(the values of the function at the given - x\-coordinates\)\. - - - __::math::interpolate::interp\-cubic\-splines__ *coeffs* *x* - - Returns the interpolated value at coordinate x\. The coefficients are - computed by the procedure *prepare\-cubic\-splines*\. - - * list *coeffs* - - List of coefficients as returned by prepare\-cubic\-splines - - * float *x* - - x\-coordinate at which to estimate the function\. Must be between the - first and last x\-coordinate for which values were given\. - - - __::math::interpolate::interp\-spatial__ *xyvalues* *coord* - - Use a straightforward interpolation method with weights as function of the - inverse distance to interpolate in 2D and N\-dimensional space - - The list xyvalues is a list of lists: - - { {x1 y1 z1 {v11 v12 v13 v14}} - {x2 y2 z2 {v21 v22 v23 v24}} - ... - } - - The last element of each inner list is either a single number or a list in - itself\. In the latter case the return value is a list with the same number - of elements\. - - The method is influenced by the search radius and the power of the inverse - distance - - * list *xyvalues* \(in\) - - List of lists, each sublist being a list of coordinates and of dependent - values\. - - * list *coord* \(in\) - - List of coordinates for which the values must be calculated - - - __::math::interpolate::interp\-spatial\-params__ *max\_search* *power* - - Set the parameters for spatial interpolation - - * float *max\_search* \(in\) - - Search radius \(data points further than this are ignored\) - - * integer *power* \(in\) - - Power for the distance \(either 1 or 2; defaults to 2\) - - - __::math::interpolate::neville__ *xlist* *ylist* *x* - - Interpolates between the tabulated values of a function whose abscissae are - *xlist* and whose ordinates are *ylist* to produce an estimate for the - value of the function at *x*\. The result is a two\-element list; the first - element is the function's estimated value, and the second is an estimate of - the absolute error of the result\. Neville's algorithm for polynomial - interpolation is used\. Note that a large table of values will use an - interpolating polynomial of high degree, which is likely to result in - numerical instabilities; one is better off using only a few tabulated values - near the desired abscissa\. - -# EXAMPLES - -*Example of using one\-dimensional tables:* - -Suppose you have several tabulated functions of one variable: - - x y1 y2 - 0.0 0.0 0.0 - 1.0 1.0 1.0 - 2.0 4.0 8.0 - 3.0 9.0 27.0 - 4.0 16.0 64.0 - -Then to estimate the values at 0\.5, 1\.5, 2\.5 and 3\.5, you can use: - - set table [::math::interpolate::defineTable table1 {x y1 y2} { - 1 2 - 0.0 0.0 0.0 - 1.0 1.0 1.0 - 2.0 4.0 8.0 - 3.0 9.0 27.0 - 4.0 16.0 64.0}] - foreach x {0.5 1.5 2.5 3.5} { - puts "$x: [::math::interpolate::interp-1d-table $table $x]" - } - -For one\-dimensional tables the first row is not used\. For two\-dimensional -tables, the first row represents the values for the second independent variable\. - -*Example of using the cubic splines:* - -Suppose the following values are given: - - x y - 0.1 1.0 - 0.3 2.1 - 0.4 2.2 - 0.8 4.11 - 1.0 4.12 - -Then to estimate the values at 0\.1, 0\.2, 0\.3, \.\.\. 1\.0, you can use: - - set coeffs [::math::interpolate::prepare-cubic-splines {0.1 0.3 0.4 0.8 1.0} {1.0 2.1 2.2 4.11 4.12}] - foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} { - puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]" - } - -to get the following output: - - 0.1: 1.0 - 0.2: 1.68044117647 - 0.3: 2.1 - 0.4: 2.2 - 0.5: 3.11221507353 - 0.6: 4.25242647059 - 0.7: 5.41804227941 - 0.8: 4.11 - 0.9: 3.95675857843 - 1.0: 4.12 - -As you can see, the values at the abscissae are reproduced perfectly\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: interpolate* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[interpolation](\.\./\.\./\.\./\.\./index\.md\#interpolation), -[math](\.\./\.\./\.\./\.\./index\.md\#math), [spatial -interpolation](\.\./\.\./\.\./\.\./index\.md\#spatial\_interpolation) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus -Copyright © 2004 Kevn B\. Kenny DELETED embedded/md/tcllib/files/modules/math/linalg.md Index: embedded/md/tcllib/files/modules/math/linalg.md ================================================================== --- embedded/md/tcllib/files/modules/math/linalg.md +++ embedded/md/tcllib/files/modules/math/linalg.md @@ -1,1179 +0,0 @@ - -[//000000001]: # (math::linearalgebra \- Tcl Math Library) -[//000000002]: # (Generated from file 'linalg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008 Arjen Markus ) -[//000000004]: # (Copyright © 2004 Ed Hume ) -[//000000005]: # (Copyright © 2008 Michael Buadin ) -[//000000006]: # (math::linearalgebra\(n\) 1\.1\.5 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::linearalgebra \- Linear Algebra - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [STORAGE](#section3) - - - [REMARKS ON THE IMPLEMENTATION](#section4) - - - [TODO](#section5) - - - [NAMING CONFLICT](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require math::linearalgebra ?1\.1\.5? - -[__::math::linearalgebra::mkVector__ *ndim* *value*](#1) -[__::math::linearalgebra::mkUnitVector__ *ndim* *ndir*](#2) -[__::math::linearalgebra::mkMatrix__ *nrows* *ncols* *value*](#3) -[__::math::linearalgebra::getrow__ *matrix* *row* ?imin? ?imax?](#4) -[__::math::linearalgebra::setrow__ *matrix* *row* *newvalues* ?imin? ?imax?](#5) -[__::math::linearalgebra::getcol__ *matrix* *col* ?imin? ?imax?](#6) -[__::math::linearalgebra::setcol__ *matrix* *col* *newvalues* ?imin? ?imax?](#7) -[__::math::linearalgebra::getelem__ *matrix* *row* *col*](#8) -[__::math::linearalgebra::setelem__ *matrix* *row* ?col? *newvalue*](#9) -[__::math::linearalgebra::swaprows__ *matrix* *irow1* *irow2* ?imin? ?imax?](#10) -[__::math::linearalgebra::swapcols__ *matrix* *icol1* *icol2* ?imin? ?imax?](#11) -[__::math::linearalgebra::show__ *obj* ?format? ?rowsep? ?colsep?](#12) -[__::math::linearalgebra::dim__ *obj*](#13) -[__::math::linearalgebra::shape__ *obj*](#14) -[__::math::linearalgebra::conforming__ *type* *obj1* *obj2*](#15) -[__::math::linearalgebra::symmetric__ *matrix* ?eps?](#16) -[__::math::linearalgebra::norm__ *vector* *type*](#17) -[__::math::linearalgebra::norm\_one__ *vector*](#18) -[__::math::linearalgebra::norm\_two__ *vector*](#19) -[__::math::linearalgebra::norm\_max__ *vector* ?index?](#20) -[__::math::linearalgebra::normMatrix__ *matrix* *type*](#21) -[__::math::linearalgebra::dotproduct__ *vect1* *vect2*](#22) -[__::math::linearalgebra::unitLengthVector__ *vector*](#23) -[__::math::linearalgebra::normalizeStat__ *mv*](#24) -[__::math::linearalgebra::axpy__ *scale* *mv1* *mv2*](#25) -[__::math::linearalgebra::add__ *mv1* *mv2*](#26) -[__::math::linearalgebra::sub__ *mv1* *mv2*](#27) -[__::math::linearalgebra::scale__ *scale* *mv*](#28) -[__::math::linearalgebra::rotate__ *c* *s* *vect1* *vect2*](#29) -[__::math::linearalgebra::transpose__ *matrix*](#30) -[__::math::linearalgebra::matmul__ *mv1* *mv2*](#31) -[__::math::linearalgebra::angle__ *vect1* *vect2*](#32) -[__::math::linearalgebra::crossproduct__ *vect1* *vect2*](#33) -[__::math::linearalgebra::matmul__ *mv1* *mv2*](#34) -[__::math::linearalgebra::mkIdentity__ *size*](#35) -[__::math::linearalgebra::mkDiagonal__ *diag*](#36) -[__::math::linearalgebra::mkRandom__ *size*](#37) -[__::math::linearalgebra::mkTriangular__ *size* ?uplo? ?value?](#38) -[__::math::linearalgebra::mkHilbert__ *size*](#39) -[__::math::linearalgebra::mkDingdong__ *size*](#40) -[__::math::linearalgebra::mkOnes__ *size*](#41) -[__::math::linearalgebra::mkMoler__ *size*](#42) -[__::math::linearalgebra::mkFrank__ *size*](#43) -[__::math::linearalgebra::mkBorder__ *size*](#44) -[__::math::linearalgebra::mkWilkinsonW\+__ *size*](#45) -[__::math::linearalgebra::mkWilkinsonW\-__ *size*](#46) -[__::math::linearalgebra::solveGauss__ *matrix* *bvect*](#47) -[__::math::linearalgebra::solvePGauss__ *matrix* *bvect*](#48) -[__::math::linearalgebra::solveTriangular__ *matrix* *bvect* ?uplo?](#49) -[__::math::linearalgebra::solveGaussBand__ *matrix* *bvect*](#50) -[__::math::linearalgebra::solveTriangularBand__ *matrix* *bvect*](#51) -[__::math::linearalgebra::determineSVD__ *A* *eps*](#52) -[__::math::linearalgebra::eigenvectorsSVD__ *A* *eps*](#53) -[__::math::linearalgebra::leastSquaresSVD__ *A* *y* *qmin* *eps*](#54) -[__::math::linearalgebra::choleski__ *matrix*](#55) -[__::math::linearalgebra::orthonormalizeColumns__ *matrix*](#56) -[__::math::linearalgebra::orthonormalizeRows__ *matrix*](#57) -[__::math::linearalgebra::dger__ *matrix* *alpha* *x* *y* ?scope?](#58) -[__::math::linearalgebra::dgetrf__ *matrix*](#59) -[__::math::linearalgebra::det__ *matrix*](#60) -[__::math::linearalgebra::largesteigen__ *matrix* *tolerance* *maxiter*](#61) -[__::math::linearalgebra::to\_LA__ *mv*](#62) -[__::math::linearalgebra::from\_LA__ *mv*](#63) - -# DESCRIPTION - -This package offers both low\-level procedures and high\-level algorithms to deal -with linear algebra problems: - - - robust solution of linear equations or least squares problems - - - determining eigenvectors and eigenvalues of symmetric matrices - - - various decompositions of general matrices or matrices of a specific form - - - \(limited\) support for matrices in band storage, a common type of sparse - matrices - -It arose as a re\-implementation of Hume's LA package and the desire to offer -low\-level procedures as found in the well\-known BLAS library\. Matrices are -implemented as lists of lists rather linear lists with reserved elements, as in -the original LA package, as it was found that such an implementation is actually -faster\. - -It is advisable, however, to use the procedures that are offered, such as -*setrow* and *getrow*, rather than rely on this representation explicitly: -that way it is to switch to a possibly even faster compiled implementation that -supports the same API\. - -*Note:* When using this package in combination with Tk, there may be a naming -conflict, as both this package and Tk define a command *scale*\. See the -[NAMING CONFLICT](#section6) section below\. - -# PROCEDURES - -The package defines the following public procedures \(several exist as -specialised procedures, see below\): - -*Constructing matrices and vectors* - - - __::math::linearalgebra::mkVector__ *ndim* *value* - - Create a vector with ndim elements, each with the value *value*\. - - * integer *ndim* - - Dimension of the vector \(number of components\) - - * double *value* - - Uniform value to be used \(default: 0\.0\) - - - __::math::linearalgebra::mkUnitVector__ *ndim* *ndir* - - Create a unit vector in *ndim*\-dimensional space, along the *ndir*\-th - direction\. - - * integer *ndim* - - Dimension of the vector \(number of components\) - - * integer *ndir* - - Direction \(0, \.\.\., ndim\-1\) - - - __::math::linearalgebra::mkMatrix__ *nrows* *ncols* *value* - - Create a matrix with *nrows* rows and *ncols* columns\. All elements have - the value *value*\. - - * integer *nrows* - - Number of rows - - * integer *ncols* - - Number of columns - - * double *value* - - Uniform value to be used \(default: 0\.0\) - - - __::math::linearalgebra::getrow__ *matrix* *row* ?imin? ?imax? - - Returns a single row of a matrix as a list - - * list *matrix* - - Matrix in question - - * integer *row* - - Index of the row to return - - * integer *imin* - - Minimum index of the column \(default: 0\) - - * integer *imax* - - Maximum index of the column \(default: ncols\-1\) - - - __::math::linearalgebra::setrow__ *matrix* *row* *newvalues* ?imin? ?imax? - - Set a single row of a matrix to new values \(this list must have the same - number of elements as the number of *columns* in the matrix\) - - * list *matrix* - - *name* of the matrix in question - - * integer *row* - - Index of the row to update - - * list *newvalues* - - List of new values for the row - - * integer *imin* - - Minimum index of the column \(default: 0\) - - * integer *imax* - - Maximum index of the column \(default: ncols\-1\) - - - __::math::linearalgebra::getcol__ *matrix* *col* ?imin? ?imax? - - Returns a single column of a matrix as a list - - * list *matrix* - - Matrix in question - - * integer *col* - - Index of the column to return - - * integer *imin* - - Minimum index of the row \(default: 0\) - - * integer *imax* - - Maximum index of the row \(default: nrows\-1\) - - - __::math::linearalgebra::setcol__ *matrix* *col* *newvalues* ?imin? ?imax? - - Set a single column of a matrix to new values \(this list must have the same - number of elements as the number of *rows* in the matrix\) - - * list *matrix* - - *name* of the matrix in question - - * integer *col* - - Index of the column to update - - * list *newvalues* - - List of new values for the column - - * integer *imin* - - Minimum index of the row \(default: 0\) - - * integer *imax* - - Maximum index of the row \(default: nrows\-1\) - - - __::math::linearalgebra::getelem__ *matrix* *row* *col* - - Returns a single element of a matrix/vector - - * list *matrix* - - Matrix or vector in question - - * integer *row* - - Row of the element - - * integer *col* - - Column of the element \(not present for vectors\) - - - __::math::linearalgebra::setelem__ *matrix* *row* ?col? *newvalue* - - Set a single element of a matrix \(or vector\) to a new value - - * list *matrix* - - *name* of the matrix in question - - * integer *row* - - Row of the element - - * integer *col* - - Column of the element \(not present for vectors\) - - - __::math::linearalgebra::swaprows__ *matrix* *irow1* *irow2* ?imin? ?imax? - - Swap two rows in a matrix completely or only a selected part - - * list *matrix* - - *name* of the matrix in question - - * integer *irow1* - - Index of first row - - * integer *irow2* - - Index of second row - - * integer *imin* - - Minimum column index \(default: 0\) - - * integer *imin* - - Maximum column index \(default: ncols\-1\) - - - __::math::linearalgebra::swapcols__ *matrix* *icol1* *icol2* ?imin? ?imax? - - Swap two columns in a matrix completely or only a selected part - - * list *matrix* - - *name* of the matrix in question - - * integer *irow1* - - Index of first column - - * integer *irow2* - - Index of second column - - * integer *imin* - - Minimum row index \(default: 0\) - - * integer *imin* - - Maximum row index \(default: nrows\-1\) - -*Querying matrices and vectors* - - - __::math::linearalgebra::show__ *obj* ?format? ?rowsep? ?colsep? - - Return a string representing the vector or matrix, for easy printing\. \(There - is currently no way to print fixed sets of columns\) - - * list *obj* - - Matrix or vector in question - - * string *format* - - Format for printing the numbers \(default: %6\.4f\) - - * string *rowsep* - - String to use for separating rows \(default: newline\) - - * string *colsep* - - String to use for separating columns \(default: space\) - - - __::math::linearalgebra::dim__ *obj* - - Returns the number of dimensions for the object \(either 0 for a scalar, 1 - for a vector and 2 for a matrix\) - - * any *obj* - - Scalar, vector, or matrix - - - __::math::linearalgebra::shape__ *obj* - - Returns the number of elements in each dimension for the object \(either an - empty list for a scalar, a single number for a vector and a list of the - number of rows and columns for a matrix\) - - * any *obj* - - Scalar, vector, or matrix - - - __::math::linearalgebra::conforming__ *type* *obj1* *obj2* - - Checks if two objects \(vector or matrix\) have conforming shapes, that is if - they can be applied in an operation like addition or matrix multiplication\. - - * string *type* - - Type of check: - - + "shape" \- the two objects have the same shape \(for all element\-wise - operations\) - - + "rows" \- the two objects have the same number of rows \(for use as A - and b in a system of linear equations *Ax = b* - - + "matmul" \- the first object has the same number of columns as the - number of rows of the second object\. Useful for matrix\-matrix or - matrix\-vector multiplication\. - - * list *obj1* - - First vector or matrix \(left operand\) - - * list *obj2* - - Second vector or matrix \(right operand\) - - - __::math::linearalgebra::symmetric__ *matrix* ?eps? - - Checks if the given \(square\) matrix is symmetric\. The argument eps is the - tolerance\. - - * list *matrix* - - Matrix to be inspected - - * float *eps* - - Tolerance for determining approximate equality \(defaults to 1\.0e\-8\) - -*Basic operations* - - - __::math::linearalgebra::norm__ *vector* *type* - - Returns the norm of the given vector\. The type argument can be: 1, 2, inf or - max, respectively the sum of absolute values, the ordinary Euclidean norm or - the max norm\. - - * list *vector* - - Vector, list of coefficients - - * string *type* - - Type of norm \(default: 2, the Euclidean norm\) - - - __::math::linearalgebra::norm\_one__ *vector* - - Returns the L1 norm of the given vector, the sum of absolute values - - * list *vector* - - Vector, list of coefficients - - - __::math::linearalgebra::norm\_two__ *vector* - - Returns the L2 norm of the given vector, the ordinary Euclidean norm - - * list *vector* - - Vector, list of coefficients - - - __::math::linearalgebra::norm\_max__ *vector* ?index? - - Returns the Linf norm of the given vector, the maximum absolute coefficient - - * list *vector* - - Vector, list of coefficients - - * integer *index* - - \(optional\) if non zero, returns a list made of the maximum value and the - index where that maximum was found\. if zero, returns the maximum value\. - - - __::math::linearalgebra::normMatrix__ *matrix* *type* - - Returns the norm of the given matrix\. The type argument can be: 1, 2, inf or - max, respectively the sum of absolute values, the ordinary Euclidean norm or - the max norm\. - - * list *matrix* - - Matrix, list of row vectors - - * string *type* - - Type of norm \(default: 2, the Euclidean norm\) - - - __::math::linearalgebra::dotproduct__ *vect1* *vect2* - - Determine the inproduct or dot product of two vectors\. These must have the - same shape \(number of dimensions\) - - * list *vect1* - - First vector, list of coefficients - - * list *vect2* - - Second vector, list of coefficients - - - __::math::linearalgebra::unitLengthVector__ *vector* - - Return a vector in the same direction with length 1\. - - * list *vector* - - Vector to be normalized - - - __::math::linearalgebra::normalizeStat__ *mv* - - Normalize the matrix or vector in a statistical sense: the mean of the - elements of the columns of the result is zero and the standard deviation is - 1\. - - * list *mv* - - Vector or matrix to be normalized in the above sense - - - __::math::linearalgebra::axpy__ *scale* *mv1* *mv2* - - Return a vector or matrix that results from a "daxpy" operation, that is: - compute a\*x\+y \(a a scalar and x and y both vectors or matrices of the same - shape\) and return the result\. - - Specialised variants are: axpy\_vect and axpy\_mat \(slightly faster, but no - check on the arguments\) - - * double *scale* - - The scale factor for the first vector/matrix \(a\) - - * list *mv1* - - First vector or matrix \(x\) - - * list *mv2* - - Second vector or matrix \(y\) - - - __::math::linearalgebra::add__ *mv1* *mv2* - - Return a vector or matrix that is the sum of the two arguments \(x\+y\) - - Specialised variants are: add\_vect and add\_mat \(slightly faster, but no - check on the arguments\) - - * list *mv1* - - First vector or matrix \(x\) - - * list *mv2* - - Second vector or matrix \(y\) - - - __::math::linearalgebra::sub__ *mv1* *mv2* - - Return a vector or matrix that is the difference of the two arguments \(x\-y\) - - Specialised variants are: sub\_vect and sub\_mat \(slightly faster, but no - check on the arguments\) - - * list *mv1* - - First vector or matrix \(x\) - - * list *mv2* - - Second vector or matrix \(y\) - - - __::math::linearalgebra::scale__ *scale* *mv* - - Scale a vector or matrix and return the result, that is: compute a\*x\. - - Specialised variants are: scale\_vect and scale\_mat \(slightly faster, but no - check on the arguments\) - - * double *scale* - - The scale factor for the vector/matrix \(a\) - - * list *mv* - - Vector or matrix \(x\) - - - __::math::linearalgebra::rotate__ *c* *s* *vect1* *vect2* - - Apply a planar rotation to two vectors and return the result as a list of - two vectors: c\*x\-s\*y and s\*x\+c\*y\. In algorithms you can often easily - determine the cosine and sine of the angle, so it is more efficient to pass - that information directly\. - - * double *c* - - The cosine of the angle - - * double *s* - - The sine of the angle - - * list *vect1* - - First vector \(x\) - - * list *vect2* - - Seocnd vector \(x\) - - - __::math::linearalgebra::transpose__ *matrix* - - Transpose a matrix - - * list *matrix* - - Matrix to be transposed - - - __::math::linearalgebra::matmul__ *mv1* *mv2* - - Multiply a vector/matrix with another vector/matrix\. The result is a matrix, - if both x and y are matrices or both are vectors, in which case the "outer - product" is computed\. If one is a vector and the other is a matrix, then the - result is a vector\. - - * list *mv1* - - First vector/matrix \(x\) - - * list *mv2* - - Second vector/matrix \(y\) - - - __::math::linearalgebra::angle__ *vect1* *vect2* - - Compute the angle between two vectors \(in radians\) - - * list *vect1* - - First vector - - * list *vect2* - - Second vector - - - __::math::linearalgebra::crossproduct__ *vect1* *vect2* - - Compute the cross product of two \(three\-dimensional\) vectors - - * list *vect1* - - First vector - - * list *vect2* - - Second vector - - - __::math::linearalgebra::matmul__ *mv1* *mv2* - - Multiply a vector/matrix with another vector/matrix\. The result is a matrix, - if both x and y are matrices or both are vectors, in which case the "outer - product" is computed\. If one is a vector and the other is a matrix, then the - result is a vector\. - - * list *mv1* - - First vector/matrix \(x\) - - * list *mv2* - - Second vector/matrix \(y\) - -*Common matrices and test matrices* - - - __::math::linearalgebra::mkIdentity__ *size* - - Create an identity matrix of dimension *size*\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkDiagonal__ *diag* - - Create a diagonal matrix whose diagonal elements are the elements of the - vector *diag*\. - - * list *diag* - - Vector whose elements are used for the diagonal - - - __::math::linearalgebra::mkRandom__ *size* - - Create a square matrix whose elements are uniformly distributed random - numbers between 0 and 1 of dimension *size*\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkTriangular__ *size* ?uplo? ?value? - - Create a triangular matrix with non\-zero elements in the upper or lower - part, depending on argument *uplo*\. - - * integer *size* - - Dimension of the matrix - - * string *uplo* - - Fill the upper \(U\) or lower part \(L\) - - * double *value* - - Value to fill the matrix with - - - __::math::linearalgebra::mkHilbert__ *size* - - Create a Hilbert matrix of dimension *size*\. Hilbert matrices are very - ill\-conditioned with respect to eigenvalue/eigenvector problems\. Therefore - they are good candidates for testing the accuracy of algorithms and - implementations\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkDingdong__ *size* - - Create a "dingdong" matrix of dimension *size*\. Dingdong matrices are - imprecisely represented, but have the property of being very stable in such - algorithms as Gauss elimination\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkOnes__ *size* - - Create a square matrix of dimension *size* whose entries are all 1\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkMoler__ *size* - - Create a Moler matrix of size *size*\. \(Moler matrices have a very simple - Choleski decomposition\. It has one small eigenvalue and it can easily upset - elimination methods for systems of linear equations\.\) - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkFrank__ *size* - - Create a Frank matrix of size *size*\. \(Frank matrices are fairly - well\-behaved matrices\) - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkBorder__ *size* - - Create a bordered matrix of size *size*\. \(Bordered matrices have a very - low rank and can upset certain specialised algorithms\.\) - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkWilkinsonW\+__ *size* - - Create a Wilkinson W\+ of size *size*\. This kind of matrix has pairs of - eigenvalues that are very close together\. Usually the order \(size\) is odd\. - - * integer *size* - - Dimension of the matrix - - - __::math::linearalgebra::mkWilkinsonW\-__ *size* - - Create a Wilkinson W\- of size *size*\. This kind of matrix has pairs of - eigenvalues with opposite signs, when the order \(size\) is odd\. - - * integer *size* - - Dimension of the matrix - -*Common algorithms* - - - __::math::linearalgebra::solveGauss__ *matrix* *bvect* - - Solve a system of linear equations \(Ax=b\) using Gauss elimination\. Returns - the solution \(x\) as a vector or matrix of the same shape as bvect\. - - * list *matrix* - - Square matrix \(matrix A\) - - * list *bvect* - - Vector or matrix whose columns are the individual b\-vectors - - - __::math::linearalgebra::solvePGauss__ *matrix* *bvect* - - Solve a system of linear equations \(Ax=b\) using Gauss elimination with - partial pivoting\. Returns the solution \(x\) as a vector or matrix of the same - shape as bvect\. - - * list *matrix* - - Square matrix \(matrix A\) - - * list *bvect* - - Vector or matrix whose columns are the individual b\-vectors - - - __::math::linearalgebra::solveTriangular__ *matrix* *bvect* ?uplo? - - Solve a system of linear equations \(Ax=b\) by backward substitution\. The - matrix is supposed to be upper\-triangular\. - - * list *matrix* - - Lower or upper\-triangular matrix \(matrix A\) - - * list *bvect* - - Vector or matrix whose columns are the individual b\-vectors - - * string *uplo* - - Indicates whether the matrix is lower\-triangular \(L\) or upper\-triangular - \(U\)\. Defaults to "U"\. - - - __::math::linearalgebra::solveGaussBand__ *matrix* *bvect* - - Solve a system of linear equations \(Ax=b\) using Gauss elimination, where the - matrix is stored as a band matrix \(*cf\.* [STORAGE](#section3)\)\. - Returns the solution \(x\) as a vector or matrix of the same shape as bvect\. - - * list *matrix* - - Square matrix \(matrix A; in band form\) - - * list *bvect* - - Vector or matrix whose columns are the individual b\-vectors - - - __::math::linearalgebra::solveTriangularBand__ *matrix* *bvect* - - Solve a system of linear equations \(Ax=b\) by backward substitution\. The - matrix is supposed to be upper\-triangular and stored in band form\. - - * list *matrix* - - Upper\-triangular matrix \(matrix A\) - - * list *bvect* - - Vector or matrix whose columns are the individual b\-vectors - - - __::math::linearalgebra::determineSVD__ *A* *eps* - - Determines the Singular Value Decomposition of a matrix: A = U S Vtrans\. - Returns a list with the matrix U, the vector of singular values S and the - matrix V\. - - * list *A* - - Matrix to be decomposed - - * float *eps* - - Tolerance \(defaults to 2\.3e\-16\) - - - __::math::linearalgebra::eigenvectorsSVD__ *A* *eps* - - Determines the eigenvectors and eigenvalues of a real *symmetric* matrix, - using SVD\. Returns a list with the matrix of normalized eigenvectors and - their eigenvalues\. - - * list *A* - - Matrix whose eigenvalues must be determined - - * float *eps* - - Tolerance \(defaults to 2\.3e\-16\) - - - __::math::linearalgebra::leastSquaresSVD__ *A* *y* *qmin* *eps* - - Determines the solution to a least\-sqaures problem Ax ~ y via singular value - decomposition\. The result is the vector x\. - - Note that if you add a column of 1s to the matrix, then this column will - represent a constant like in: y = a\*x1 \+ b\*x2 \+ c\. To force the intercept to - be zero, simply leave it out\. - - * list *A* - - Matrix of independent variables - - * list *y* - - List of observed values - - * float *qmin* - - Minimum singular value to be considered \(defaults to 0\.0\) - - * float *eps* - - Tolerance \(defaults to 2\.3e\-16\) - - - __::math::linearalgebra::choleski__ *matrix* - - Determine the Choleski decomposition of a symmetric positive semidefinite - matrix \(this condition is not checked\!\)\. The result is the lower\-triangular - matrix L such that L Lt = matrix\. - - * list *matrix* - - Matrix to be decomposed - - - __::math::linearalgebra::orthonormalizeColumns__ *matrix* - - Use the modified Gram\-Schmidt method to orthogonalize and normalize the - *columns* of the given matrix and return the result\. - - * list *matrix* - - Matrix whose columns must be orthonormalized - - - __::math::linearalgebra::orthonormalizeRows__ *matrix* - - Use the modified Gram\-Schmidt method to orthogonalize and normalize the - *rows* of the given matrix and return the result\. - - * list *matrix* - - Matrix whose rows must be orthonormalized - - - __::math::linearalgebra::dger__ *matrix* *alpha* *x* *y* ?scope? - - Perform the rank 1 operation A \+ alpha\*x\*y' inline \(that is: the matrix A is - adjusted\)\. For convenience the new matrix is also returned as the result\. - - * list *matrix* - - Matrix whose rows must be adjusted - - * double *alpha* - - Scale factor - - * list *x* - - A column vector - - * list *y* - - A column vector - - * list *scope* - - If not provided, the operation is performed on all rows/columns of A if - provided, it is expected to be the list \{imin imax jmin jmax\} where: - - + *imin* Minimum row index - - + *imax* Maximum row index - - + *jmin* Minimum column index - - + *jmax* Maximum column index - - - __::math::linearalgebra::dgetrf__ *matrix* - - Computes an LU factorization of a general matrix, using partial, pivoting - with row interchanges\. Returns the permutation vector\. - - The factorization has the form - - P * A = L * U - - where P is a permutation matrix, L is lower triangular with unit diagonal - elements, and U is upper triangular\. Returns the permutation vector, as a - list of length n\-1\. The last entry of the permutation is not stored, since - it is implicitely known, with value n \(the last row is not swapped with any - other row\)\. At index \#i of the permutation is stored the index of the row \#j - which is swapped with row \#i at step \#i\. That means that each index of the - permutation gives the permutation at each step, not the cumulated - permutation matrix, which is the product of permutations\. - - * list *matrix* - - On entry, the matrix to be factored\. On exit, the factors L and U from - the factorization P\*A = L\*U; the unit diagonal elements of L are not - stored\. - - - __::math::linearalgebra::det__ *matrix* - - Returns the determinant of the given matrix, based on PA=LU decomposition, - i\.e\. Gauss partial pivotal\. - - * list *matrix* - - Square matrix \(matrix A\) - - * list *ipiv* - - The pivots \(optionnal\)\. If the pivots are not provided, a PA=LU - decomposition is performed\. If the pivots are provided, we assume that - it contains the pivots and that the matrix A contains the L and U - factors, as provided by dgterf\. b\-vectors - - - __::math::linearalgebra::largesteigen__ *matrix* *tolerance* *maxiter* - - Returns a list made of the largest eigenvalue \(in magnitude\) and associated - eigenvector\. Uses iterative Power Method as provided as algorithm \#7\.3\.3 of - Golub & Van Loan\. This algorithm is used here for a dense matrix \(but is - usually used for sparse matrices\)\. - - * list *matrix* - - Square matrix \(matrix A\) - - * double *tolerance* - - The relative tolerance of the eigenvalue \(default:1\.e\-8\)\. - - * integer *maxiter* - - The maximum number of iterations \(default:10\)\. - -*Compability with the LA package* Two procedures are provided for -compatibility with Hume's LA package: - - - __::math::linearalgebra::to\_LA__ *mv* - - Transforms a vector or matrix into the format used by the original LA - package\. - - * list *mv* - - Matrix or vector - - - __::math::linearalgebra::from\_LA__ *mv* - - Transforms a vector or matrix from the format used by the original LA - package into the format used by the present implementation\. - - * list *mv* - - Matrix or vector as used by the LA package - -# STORAGE - -While most procedures assume that the matrices are given in full form, the -procedures *solveGaussBand* and *solveTriangularBand* assume that the -matrices are stored as *band matrices*\. This common type of "sparse" matrices -is related to ordinary matrices as follows: - - - "A" is a full\-size matrix with N rows and M columns\. - - - "B" is a band matrix, with m upper and lower diagonals and n rows\. - - - "B" can be stored in an ordinary matrix of \(2m\+1\) columns \(one for each - off\-diagonal and the main diagonal\) and n rows\. - - - Element i,j \(i = \-m,\.\.\.,m; j =1,\.\.\.,n\) of "B" corresponds to element k,j of - "A" where k = M\+i\-1 and M is at least \(\!\) n, the number of rows in "B"\. - - - To set element \(i,j\) of matrix "B" use: - - setelem B $j [expr {$N+$i-1}] $value - -\(There is no convenience procedure for this yet\) - -# REMARKS ON THE IMPLEMENTATION - -There is a difference between the original LA package by Hume and the current -implementation\. Whereas the LA package uses a linear list, the current package -uses lists of lists to represent matrices\. It turns out that with this -representation, the algorithms are faster and easier to implement\. - -The LA package was used as a model and in fact the implementation of, for -instance, the SVD algorithm was taken from that package\. The set of procedures -was expanded using ideas from the well\-known BLAS library and some algorithms -were updated from the second edition of J\.C\. Nash's book, Compact Numerical -Methods for Computers, \(Adam Hilger, 1990\) that inspired the LA package\. - -Two procedures are provided to make the transition between the two -implementations easier: *to\_LA* and *from\_LA*\. They are described above\. - -# TODO - -Odds and ends: the following algorithms have not been implemented yet: - - - determineQR - - - certainlyPositive, diagonallyDominant - -# NAMING CONFLICT - -If you load this package in a Tk\-enabled shell like wish, then the command - - namespace import ::math::linearalgebra - -results in an error message about "scale"\. This is due to the fact that Tk -defines all its commands in the global namespace\. The solution is to import the -linear algebra commands in a namespace that is not the global one: - - package require math::linearalgebra - namespace eval compute { - namespace import ::math::linearalgebra::* - ... use the linear algebra version of scale ... - } - -To use Tk's scale command in that same namespace you can rename it: - - namespace eval compute { - rename ::scale scaleTk - scaleTk .scale ... - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: linearalgebra* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[least squares](\.\./\.\./\.\./\.\./index\.md\#least\_squares), [linear -algebra](\.\./\.\./\.\./\.\./index\.md\#linear\_algebra), [linear -equations](\.\./\.\./\.\./\.\./index\.md\#linear\_equations), -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[matrices](\.\./\.\./\.\./\.\./index\.md\#matrices), -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[vectors](\.\./\.\./\.\./\.\./index\.md\#vectors) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004\-2008 Arjen Markus -Copyright © 2004 Ed Hume -Copyright © 2008 Michael Buadin DELETED embedded/md/tcllib/files/modules/math/machineparameters.md Index: embedded/md/tcllib/files/modules/math/machineparameters.md ================================================================== --- embedded/md/tcllib/files/modules/math/machineparameters.md +++ embedded/md/tcllib/files/modules/math/machineparameters.md @@ -1,231 +0,0 @@ - -[//000000001]: # (math::machineparameters \- tclrep) -[//000000002]: # (Generated from file 'machineparameters\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Michael Baudin ) -[//000000004]: # (math::machineparameters\(n\) 1\.0 tcllib "tclrep") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::machineparameters \- Compute double precision machine parameters\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLE](#section2) - - - [REFERENCES](#section3) - - - [CLASS API](#section4) - - - [OBJECT API](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit -package require math::machineparameters 0\.1 - -[__machineparameters__ create *objectname* ?*options*\.\.\.?](#1) -[*objectname* __configure__ ?*options*\.\.\.?](#2) -[*objectname* __cget__ *opt*](#3) -[*objectname* __destroy__](#4) -[*objectname* __compute__](#5) -[*objectname* __get__ *key*](#6) -[*objectname* __tostring__](#7) -[*objectname* __print__](#8) - -# DESCRIPTION - -The *math::machineparameters* package is the Tcl equivalent of the DLAMCH -LAPACK function\. In floating point systems, a floating point number is -represented by - - x = +/- d1 d2 ... dt basis^e - -where digits satisfy - - 0 <= di <= basis - 1, i = 1, t - -with the convention : - - - t is the size of the mantissa - - - basis is the basis \(the "radix"\) - -The __compute__ method computes all machine parameters\. Then, the -__get__ method can be used to get each parameter\. The __print__ method -prints a report on standard output\. - -# EXAMPLE - -In the following example, one compute the parameters of a desktop under Linux -with the following Tcl 8\.4\.19 properties : - - % parray tcl_platform - tcl_platform(byteOrder) = littleEndian - tcl_platform(machine) = i686 - tcl_platform(os) = Linux - tcl_platform(osVersion) = 2.6.24-19-generic - tcl_platform(platform) = unix - tcl_platform(tip,268) = 1 - tcl_platform(tip,280) = 1 - tcl_platform(user) = - tcl_platform(wordSize) = 4 - -The following example creates a machineparameters object, computes the -properties and displays it\. - - set pp [machineparameters create %AUTO%] - $pp compute - $pp print - $pp destroy - -This prints out : - - Machine parameters - Epsilon : 1.11022302463e-16 - Beta : 2 - Rounding : proper - Mantissa : 53 - Maximum exponent : 1024 - Minimum exponent : -1021 - Overflow threshold : 8.98846567431e+307 - Underflow threshold : 2.22507385851e-308 - -That compares well with the results produced by Lapack 3\.1\.1 : - - Epsilon = 1.11022302462515654E-016 - Safe minimum = 2.22507385850720138E-308 - Base = 2.0000000000000000 - Precision = 2.22044604925031308E-016 - Number of digits in mantissa = 53.000000000000000 - Rounding mode = 1.00000000000000000 - Minimum exponent = -1021.0000000000000 - Underflow threshold = 2.22507385850720138E-308 - Largest exponent = 1024.0000000000000 - Overflow threshold = 1.79769313486231571E+308 - Reciprocal of safe minimum = 4.49423283715578977E+307 - -The following example creates a machineparameters object, computes the -properties and gets the epsilon for the machine\. - - set pp [machineparameters create %AUTO%] - $pp compute - set eps [$pp get -epsilon] - $pp destroy - -# REFERENCES - - - "Algorithms to Reveal Properties of Floating\-Point Arithmetic", Michael A\. - Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue - 11 \(November 1972\), Pages: 949 \- 951 - - - "More on Algorithms that Reveal Properties of Floating, Point Arithmetic - Units", W\. Morven Gentleman, University of Waterloo, Scott B\. Marovich, - Purdue University, Communications of the ACM, Volume 17 , Issue 5 \(May - 1974\), Pages: 276 \- 277 - -# CLASS API - - - __machineparameters__ create *objectname* ?*options*\.\.\.? - - The command creates a new machineparameters object and returns the fully - qualified name of the object command as its result\. - - * __\-verbose__ *verbose* - - Set this option to 1 to enable verbose logging\. This option is mainly - for debug purposes\. The default value of *verbose* is 0\. - -# OBJECT API - - - *objectname* __configure__ ?*options*\.\.\.? - - The command configure the options of the object *objectname*\. The options - are the same as the static method __create__\. - - - *objectname* __cget__ *opt* - - Returns the value of the option which name is *opt*\. The options are the - same as the method __create__ and __configure__\. - - - *objectname* __destroy__ - - Destroys the object *objectname*\. - - - *objectname* __compute__ - - Computes the machine parameters\. - - - *objectname* __get__ *key* - - Returns the value corresponding with given key\. The following is the list of - available keys\. - - * \-epsilon : smallest value so that 1\+epsilon>1 is false - - * \-rounding : The rounding mode used on the machine\. The rounding occurs - when more than t digits would be required to represent the number\. Two - modes can be determined with the current system : "chop" means than only - t digits are kept, no matter the value of the number "proper" means that - another rounding mode is used, be it "round to nearest", "round up", - "round down"\. - - * \-basis : the basis of the floating\-point representation\. The basis is - usually 2, i\.e\. binary representation \(for example IEEE 754 machines\), - but some machines \(like HP calculators for example\) uses 10, or 16, - etc\.\.\. - - * \-mantissa : the number of bits in the mantissa - - * \-exponentmax : the largest positive exponent before overflow occurs - - * \-exponentmin : the largest negative exponent before \(gradual\) underflow - occurs - - * \-vmax : largest positive value before overflow occurs - - * \-vmin : largest negative value before \(gradual\) underflow occurs - - - *objectname* __tostring__ - - Return a report for machine parameters\. - - - *objectname* __print__ - - Print machine parameters on standard output\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# COPYRIGHT - -Copyright © 2008 Michael Baudin DELETED embedded/md/tcllib/files/modules/math/math.md Index: embedded/md/tcllib/files/modules/math/math.md ================================================================== --- embedded/md/tcllib/files/modules/math/math.md +++ embedded/md/tcllib/files/modules/math/math.md @@ -1,180 +0,0 @@ - -[//000000001]: # (math \- Tcl Math Library) -[//000000002]: # (Generated from file 'math\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math\(n\) 1\.2\.5 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math \- Tcl Math Library - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [BASIC COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require math ?1\.2\.5? - -[__::math::cov__ *value* *value* ?*value \.\.\.*?](#1) -[__::math::integrate__ *list of xy value pairs*](#2) -[__::math::fibonacci__ *n*](#3) -[__::math::max__ *value* ?*value \.\.\.*?](#4) -[__::math::mean__ *value* ?*value \.\.\.*?](#5) -[__::math::min__ *value* ?*value \.\.\.*?](#6) -[__::math::product__ *value* ?*value \.\.\.*?](#7) -[__::math::random__ ?*value1*? ?*value2*?](#8) -[__::math::sigma__ *value* *value* ?*value \.\.\.*?](#9) -[__::math::stats__ *value* *value* ?*value \.\.\.*?](#10) -[__::math::sum__ *value* ?*value \.\.\.*?](#11) - -# DESCRIPTION - -The __math__ package provides utility math functions\. - -Besides a set of basic commands, available via the package *math*, there are -more specialised packages: - - - __[math::bigfloat](bigfloat\.md)__ \- Arbitrary\-precision - floating\-point arithmetic - - - __[math::bignum](bignum\.md)__ \- Arbitrary\-precision integer - arithmetic - - - __[math::calculus::romberg](romberg\.md)__ \- Robust integration - methods for functions of one variable, using Romberg integration - - - __[math::calculus](calculus\.md)__ \- Integration of functions, - solving ordinary differential equations - - - __[math::combinatorics](combinatorics\.md)__ \- Procedures for various - combinatorial functions \(for instance the Gamma function and "k out of n"\) - - - __[math::complexnumbers](qcomplex\.md)__ \- Complex number arithmetic - - - __[math::constants](constants\.md)__ \- A set of well\-known - mathematical constants, such as Pi, E, and the golden ratio - - - __[math::fourier](fourier\.md)__ \- Discrete Fourier transforms - - - __[math::fuzzy](fuzzy\.md)__ \- Fuzzy comparisons of floating\-point - numbers - - - __[math::geometry](math\_geometry\.md)__ \- 2D geometrical computations - - - __[math::interpolate](interpolate\.md)__ \- Various interpolation - methods - - - __[math::linearalgebra](linalg\.md)__ \- Linear algebra package - - - __[math::optimize](optimize\.md)__ \- Optimization methods - - - __[math::polynomials](polynomials\.md)__ \- Polynomial arithmetic - \(includes families of classical polynomials\) - - - __[math::rationalfunctions](rational\_funcs\.md)__ \- Arithmetic of - rational functions - - - __[math::roman](roman\.md)__ \- Manipulation \(including arithmetic\) of - Roman numerals - - - __[math::special](special\.md)__ \- Approximations of special - functions from mathematical physics - - - __[math::statistics](statistics\.md)__ \- Statistical operations and - tests - -# BASIC COMMANDS - - - __::math::cov__ *value* *value* ?*value \.\.\.*? - - Return the coefficient of variation expressed as percent of two or more - numeric values\. - - - __::math::integrate__ *list of xy value pairs* - - Return the area under a "curve" defined by a set of x,y pairs and the error - bound as a list\. - - - __::math::fibonacci__ *n* - - Return the *n*'th Fibonacci number\. - - - __::math::max__ *value* ?*value \.\.\.*? - - Return the maximum of one or more numeric values\. - - - __::math::mean__ *value* ?*value \.\.\.*? - - Return the mean, or "average" of one or more numeric values\. - - - __::math::min__ *value* ?*value \.\.\.*? - - Return the minimum of one or more numeric values\. - - - __::math::product__ *value* ?*value \.\.\.*? - - Return the product of one or more numeric values\. - - - __::math::random__ ?*value1*? ?*value2*? - - Return a random number\. If no arguments are given, the number is a floating - point value between 0 and 1\. If one argument is given, the number is an - integer value between 0 and *value1*\. If two arguments are given, the - number is an integer value between *value1* and *value2*\. - - - __::math::sigma__ *value* *value* ?*value \.\.\.*? - - Return the population standard deviation of two or more numeric values\. - - - __::math::stats__ *value* *value* ?*value \.\.\.*? - - Return the mean, standard deviation, and coefficient of variation \(as - percent\) as a list\. - - - __::math::sum__ *value* ?*value \.\.\.*? - - Return the sum of one or more numeric values\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[statistics](\.\./\.\./\.\./\.\./index\.md\#statistics) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/math_geometry.md Index: embedded/md/tcllib/files/modules/math/math_geometry.md ================================================================== --- embedded/md/tcllib/files/modules/math/math_geometry.md +++ embedded/md/tcllib/files/modules/math/math_geometry.md @@ -1,1050 +0,0 @@ - -[//000000001]: # (math::geometry \- Tcl Math Library) -[//000000002]: # (Generated from file 'math\_geometry\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2001 by Ideogramic ApS and other parties) -[//000000004]: # (Copyright © 2010 by Andreas Kupries) -[//000000005]: # (Copyright © 2010 by Kevin Kenny) -[//000000006]: # (Copyright © 2018 by Arjen Markus) -[//000000007]: # (Copyright © 2020 by Manfred Rosenberger) -[//000000008]: # (math::geometry\(n\) 1\.4\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::geometry \- Geometrical computations - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [COORDINATE SYSTEM](#section3) - - - [References](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::geometry ?1\.4\.1? - -[__::math::geometry::\+__ *point1* *point2*](#1) -[__::math::geometry::\-__ *point1* *point2*](#2) -[__::math::geometry::p__ *x* *y*](#3) -[__::math::geometry::distance__ *point1* *point2*](#4) -[__::math::geometry::length__ *point*](#5) -[__::math::geometry::s\*__ *factor* *point*](#6) -[__::math::geometry::direction__ *angle*](#7) -[__::math::geometry::h__ *length*](#8) -[__::math::geometry::v__ *length*](#9) -[__::math::geometry::between__ *point1* *point2* *s*](#10) -[__::math::geometry::octant__ *point*](#11) -[__::math::geometry::rect__ *nw* *se*](#12) -[__::math::geometry::nwse__ *rect*](#13) -[__::math::geometry::angle__ *line*](#14) -[__::math::geometry::angleBetween__ *vector1* *vector2*](#15) -[__::math::geometry::inproduct__ *vector1* *vector2*](#16) -[__::math::geometry::areaParallellogram__ *vector1* *vector2*](#17) -[__::math::geometry::calculateDistanceToLine__ *P* *line*](#18) -[__::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment*](#19) -[__::math::geometry::calculateDistanceToPolyline__ *P* *polyline*](#20) -[__::math::geometry::calculateDistanceToPolygon__ *P* *polygon*](#21) -[__::math::geometry::findClosestPointOnLine__ *P* *line*](#22) -[__::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment*](#23) -[__::math::geometry::findClosestPointOnPolyline__ *P* *polyline*](#24) -[__::math::geometry::lengthOfPolyline__ *polyline*](#25) -[__::math::geometry::movePointInDirection__ *P* *direction* *dist*](#26) -[__::math::geometry::lineSegmentsIntersect__ *linesegment1* *linesegment2*](#27) -[__::math::geometry::findLineSegmentIntersection__ *linesegment1* *linesegment2*](#28) -[__::math::geometry::findLineIntersection__ *line1* *line2*](#29) -[__::math::geometry::polylinesIntersect__ *polyline1* *polyline2*](#30) -[__::math::geometry::polylinesBoundingIntersect__ *polyline1* *polyline2* *granularity*](#31) -[__::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict*](#32) -[__::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict*](#33) -[__::math::geometry::bbox__ *polyline*](#34) -[__::math::geometry::overlapBBox__ *polyline1* *polyline2* ?strict?](#35) -[__::math::geometry::pointInsideBBox__ *bbox* *point*](#36) -[__::math::geometry::cathetusPoint__ *pa* *pb* *cathetusLength* ?location?](#37) -[__::math::geometry::parallel__ *line* *offset* ?orient?](#38) -[__::math::geometry::unitVector__ *line*](#39) -[__::math::geometry::pointInsidePolygon__ *P* *polyline*](#40) -[__::math::geometry::pointInsidePolygonAlt__ *P* *polyline*](#41) -[__::math::geometry::rectangleInsidePolygon__ *P1* *P2* *polyline*](#42) -[__::math::geometry::areaPolygon__ *polygon*](#43) -[__::math::geometry::translate__ *vector* *polyline*](#44) -[__::math::geometry::rotate__ *angle* *polyline*](#45) -[__::math::geometry::rotateAbout__ *p* *angle* *polyline*](#46) -[__::math::geometry::reflect__ *angle* *polyline*](#47) -[__::math::geometry::degToRad__ *angle*](#48) -[__::math::geometry::radToDeg__ *angle*](#49) -[__::math::geometry::circle__ *centre* *radius*](#50) -[__::math::geometry::circleTwoPoints__ *point1* *point2*](#51) -[__::math::geometry::pointInsideCircle__ *point* *circle*](#52) -[__::math::geometry::lineIntersectsCircle__ *line* *circle*](#53) -[__::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle*](#54) -[__::math::geometry::intersectionLineWithCircle__ *line* *circle*](#55) -[__::math::geometry::intersectionCircleWithCircle__ *circle1* *circle2*](#56) -[__::math::geometry::tangentLinesToCircle__ *point* *circle*](#57) -[__::math::geometry::intersectionPolylines__ *polyline1* *polyline2* ?mode? ?granularity?](#58) -[__::math::geometry::intersectionPolylineCircle__ *polyline* *circle* ?mode? ?granularity?](#59) -[__::math::geometry::polylineCutOrigin__ *polyline1* *polyline2* ?granularity?](#60) -[__::math::geometry::polylineCutEnd__ *polyline1* *polyline2* ?granularity?](#61) -[__::math::geometry::splitPolyline__ *polyline* *numberVertex*](#62) -[__::math::geometry::enrichPolyline__ *polyline* *accuracy*](#63) -[__::math::geometry::cleanupPolyline__ *polyline*](#64) - -# DESCRIPTION - -The __math::geometry__ package is a collection of functions for computations -and manipulations on two\-dimensional geometrical objects, such as points, lines -and polygons\. - -The geometrical objects are implemented as plain lists of coordinates\. For -instance a line is defined by a list of four numbers, the x\- and y\-coordinate of -a first point and the x\- and y\-coordinates of a second point on the line\. - -*Note:* In version 1\.4\.0 an inconsistency was repaired \- see -[https://core\.tcl\-lang\.org/tcllib/tktview?name=fb4812f82b](https://core\.tcl\-lang\.org/tcllib/tktview?name=fb4812f82b)\. -More in [COORDINATE SYSTEM](#section3) - -The various types of object are recognised by the number of coordinate pairs and -the context in which they are used: a list of four elements can be regarded as -an infinite line, a finite line segment but also as a polyline of one segment -and a point set of two points\. - -Currently the following types of objects are distinguished: - - - *point* \- a list of two coordinates representing the x\- and y\-coordinates - respectively\. - - - *line* \- a list of four coordinates, interpreted as the x\- and - y\-coordinates of two distinct points on the line\. - - - *line segment* \- a list of four coordinates, interpreted as the x\- and - y\-coordinates of the first and the last points on the line segment\. - - - *polyline* \- a list of an even number of coordinates, interpreted as the - x\- and y\-coordinates of an ordered set of points\. - - - *polygon* \- like a polyline, but the implicit assumption is that the - polyline is closed \(if the first and last points do not coincide, the - missing segment is automatically added\)\. - - - *point set* \- again a list of an even number of coordinates, but the - points are regarded without any ordering\. - - - *circle* \- a list of three numbers, the first two are the coordinates of - the centre and the third is the radius\. - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::geometry::\+__ *point1* *point2* - - Compute the sum of the two vectors given as points and return it\. The result - is a vector as well\. - - - __::math::geometry::\-__ *point1* *point2* - - Compute the difference \(point1 \- point2\) of the two vectors given as points - and return it\. The result is a vector as well\. - - - __::math::geometry::p__ *x* *y* - - Construct a point from its coordinates and return it as the result of the - command\. - - - __::math::geometry::distance__ *point1* *point2* - - Compute the distance between the two points and return it as the result of - the command\. This is in essence the same as - - math::geometry::length [math::geomtry::- point1 point2] - - - __::math::geometry::length__ *point* - - Compute the length of the vector and return it as the result of the command\. - - - __::math::geometry::s\*__ *factor* *point* - - Scale the vector by the factor and return it as the result of the command\. - This is a vector as well\. - - - __::math::geometry::direction__ *angle* - - Given the angle in degrees this command computes and returns the unit vector - pointing into this direction\. The vector for angle == 0 points to the right - \(east\), and for angle == 90 up \(north\)\. - - - __::math::geometry::h__ *length* - - Returns a horizontal vector on the X\-axis of the specified length\. Positive - lengths point to the right \(east\)\. - - - __::math::geometry::v__ *length* - - Returns a vertical vector on the Y\-axis of the specified length\. Positive - lengths point down \(south\)\. - - - __::math::geometry::between__ *point1* *point2* *s* - - Compute the point which is at relative distance *s* between the two points - and return it as the result of the command\. A relative distance of __0__ - returns *point1*, the distance __1__ returns *point2*\. Distances < 0 - or > 1 extrapolate along the line between the two point\. - - - __::math::geometry::octant__ *point* - - Compute the octant of the circle the point is in and return it as the result - of the command\. The possible results are - - 1. east - - 1. northeast - - 1. north - - 1. northwest - - 1. west - - 1. southwest - - 1. south - - 1. southeast - - Each octant is the arc of the circle \+/\- 22\.5 degrees from the cardinal - direction the octant is named for\. - - - __::math::geometry::rect__ *nw* *se* - - Construct a rectangle from its northwest and southeast corners and return it - as the result of the command\. - - - __::math::geometry::nwse__ *rect* - - Extract the northwest and southeast corners of the rectangle and return them - as the result of the command \(a 2\-element list containing the points, in the - named order\)\. - - - __::math::geometry::angle__ *line* - - Calculate the angle from the positive x\-axis to a given line \(in two - dimensions only\)\. - - * list *line* - - Coordinates of the line - - - __::math::geometry::angleBetween__ *vector1* *vector2* - - Calculate the angle between two vectors \(in degrees\) - - * list *vector1* - - First vector - - * list *vector2* - - Second vector - - - __::math::geometry::inproduct__ *vector1* *vector2* - - Calculate the inner product of two vectors - - * list *vector1* - - First vector - - * list *vector2* - - Second vector - - - __::math::geometry::areaParallellogram__ *vector1* *vector2* - - Calculate the area of the parallellogram with the two vectors as its sides - - * list *vector1* - - First vector - - * list *vector2* - - Second vector - - - __::math::geometry::calculateDistanceToLine__ *P* *line* - - Calculate the distance of point P to the \(infinite\) line and return the - result - - * list *P* - - List of two numbers, the coordinates of the point - - * list *line* - - List of four numbers, the coordinates of two points on the line - - - __::math::geometry::calculateDistanceToLineSegment__ *P* *linesegment* - - Calculate the distance of point P to the \(finite\) line segment and return - the result\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *linesegment* - - List of four numbers, the coordinates of the first and last points of - the line segment - - - __::math::geometry::calculateDistanceToPolyline__ *P* *polyline* - - Calculate the distance of point P to the polyline and return the result\. - Note that a polyline needs not to be closed\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *polyline* - - List of numbers, the coordinates of the vertices of the polyline - - - __::math::geometry::calculateDistanceToPolygon__ *P* *polygon* - - Calculate the distance of point P to the polygon and return the result\. If - the list of coordinates is not closed \(first and last points differ\), it is - automatically closed\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *polygon* - - List of numbers, the coordinates of the vertices of the polygon - - - __::math::geometry::findClosestPointOnLine__ *P* *line* - - Return the point on a line which is closest to a given point\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *line* - - List of four numbers, the coordinates of two points on the line - - - __::math::geometry::findClosestPointOnLineSegment__ *P* *linesegment* - - Return the point on a *line segment* which is closest to a given point\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *linesegment* - - List of four numbers, the first and last points on the line segment - - - __::math::geometry::findClosestPointOnPolyline__ *P* *polyline* - - Return the point on a *polyline* which is closest to a given point\. - - * list *P* - - List of two numbers, the coordinates of the point - - * list *polyline* - - List of numbers, the vertices of the polyline - - - __::math::geometry::lengthOfPolyline__ *polyline* - - Return the length of the *polyline* \(note: it not regarded as a polygon\) - - * list *polyline* - - List of numbers, the vertices of the polyline - - - __::math::geometry::movePointInDirection__ *P* *direction* *dist* - - Move a point over a given distance in a given direction and return the new - coordinates \(in two dimensions only\)\. - - * list *P* - - Coordinates of the point to be moved - - * double *direction* - - Direction \(in degrees; 0 is to the right, 90 upwards\) - - * list *dist* - - Distance over which to move the point - - - __::math::geometry::lineSegmentsIntersect__ *linesegment1* *linesegment2* - - Check if two line segments intersect or coincide\. Returns 1 if that is the - case, 0 otherwise \(in two dimensions only\)\. If an endpoint of one segment - lies on the other segment \(or is very close to the segment\), they are - considered to intersect - - * list *linesegment1* - - First line segment - - * list *linesegment2* - - Second line segment - - - __::math::geometry::findLineSegmentIntersection__ *linesegment1* *linesegment2* - - Find the intersection point of two line segments\. Return the coordinates or - the keywords "coincident" or "none" if the line segments coincide or have no - points in common \(in two dimensions only\)\. - - * list *linesegment1* - - First line segment - - * list *linesegment2* - - Second line segment - - - __::math::geometry::findLineIntersection__ *line1* *line2* - - Find the intersection point of two \(infinite\) lines\. Return the coordinates - or the keywords "coincident" or "none" if the lines coincide or have no - points in common \(in two dimensions only\)\. - - * list *line1* - - First line - - * list *line2* - - Second line - - See section [References](#section4) for details on the algorithm and - math behind it\. - - - __::math::geometry::polylinesIntersect__ *polyline1* *polyline2* - - Check if two polylines intersect or not \(in two dimensions only\)\. - - * list *polyline1* - - First polyline - - * list *polyline2* - - Second polyline - - - __::math::geometry::polylinesBoundingIntersect__ *polyline1* *polyline2* *granularity* - - Check whether two polylines intersect, but reduce the correctness of the - result to the given granularity\. Use this for faster, but weaker, - intersection checking\. - - How it works: - - Each polyline is split into a number of smaller polylines, consisting of - granularity points each\. If a pair of those smaller lines' bounding boxes - intersect, then this procedure returns 1, otherwise it returns 0\. - - * list *polyline1* - - First polyline - - * list *polyline2* - - Second polyline - - * int *granularity* - - Number of points in each part \(<=1 means check every edge\) - - - __::math::geometry::intervalsOverlap__ *y1* *y2* *y3* *y4* *strict* - - Check if two intervals overlap\. - - * double *y1,y2* - - Begin and end of first interval - - * double *y3,y4* - - Begin and end of second interval - - * logical *strict* - - Check for strict or non\-strict overlap - - - __::math::geometry::rectanglesOverlap__ *P1* *P2* *Q1* *Q2* *strict* - - Check if two rectangles overlap\. - - * list *P1* - - upper\-left corner of the first rectangle - - * list *P2* - - lower\-right corner of the first rectangle - - * list *Q1* - - upper\-left corner of the second rectangle - - * list *Q2* - - lower\-right corner of the second rectangle - - * list *strict* - - choosing strict or non\-strict interpretation - - - __::math::geometry::bbox__ *polyline* - - Calculate the bounding box of a polyline\. Returns a list of four - coordinates: the upper\-left and the lower\-right corner of the box\. - - * list *polyline* - - The polyline to be examined - - - __::math::geometry::overlapBBox__ *polyline1* *polyline2* ?strict? - - Check if the bounding boxes of two polylines overlap or not\. - - Arguments: - - * list *polyline1* - - The first polyline - - * list *polyline1* - - The second polyline - - * int *strict* - - Whether strict overlap is to checked \(1\) or if the bounding boxes may - touch \(0, default\) - - - __::math::geometry::pointInsideBBox__ *bbox* *point* - - Check if the point is inside or on the bounding box or not\. Arguments: - - * list *bbox* - - The bounding box given as a list of x/y coordinates - - * list *point* - - The point to be checked - - - __::math::geometry::cathetusPoint__ *pa* *pb* *cathetusLength* ?location? - - Return the third point of the rectangular triangle defined by the two given - end points of the hypothenusa\. The triangle's side from point A \(or B, if - the location is given as "b"\) to the third point is the cathetus length\. If - the cathetus' length is lower than the length of the hypothenusa, an empty - list is returned\. - - Arguments: - - * list *pa* - - The starting point on hypotenuse - - * list *pb* - - The ending point on hypotenuse - - * float *cathetusLength* - - The length of the cathetus of the triangle - - * string *location* - - The location of the given cathetus, "a" means given cathetus shares - point pa \(default\) "b" means given cathetus shares point pb - - - __::math::geometry::parallel__ *line* *offset* ?orient? - - Return a line parallel to the given line, with a distance "offset"\. The - orientation is determined by the two points defining the line\. - - Arguments: - - * list *line* - - The given line - - * float *offset* - - The distance to the given line - - * string *orient* - - Orientation of the new line with respect to the given line \(defaults to - "right"\) - - - __::math::geometry::unitVector__ *line* - - Return a unit vector from the given line or direction, if the - *[line](\.\./\.\./\.\./\.\./index\.md\#line)* argument is a single point \(then a - line through the origin is assumed\) Arguments: - - * list *line* - - The line in question \(or a single point, implying a line through the - origin\) - - - __::math::geometry::pointInsidePolygon__ *P* *polyline* - - Determine if a point is completely inside a polygon\. If the point touches - the polygon, then the point is not completely inside the polygon\. - - * list *P* - - Coordinates of the point - - * list *polyline* - - The polyline to be examined - - - __::math::geometry::pointInsidePolygonAlt__ *P* *polyline* - - Determine if a point is completely inside a polygon\. If the point touches - the polygon, then the point is not completely inside the polygon\. *Note:* - this alternative procedure uses the so\-called winding number to determine - this\. It handles self\-intersecting polygons in a "natural" way\. - - * list *P* - - Coordinates of the point - - * list *polyline* - - The polyline to be examined - - - __::math::geometry::rectangleInsidePolygon__ *P1* *P2* *polyline* - - Determine if a rectangle is completely inside a polygon\. If polygon touches - the rectangle, then the rectangle is not complete inside the polygon\. - - * list *P1* - - Upper\-left corner of the rectangle - - * list *P2* - - Lower\-right corner of the rectangle - - * list *polygon* - - The polygon in question - - - __::math::geometry::areaPolygon__ *polygon* - - Calculate the area of a polygon\. - - * list *polygon* - - The polygon in question - - - __::math::geometry::translate__ *vector* *polyline* - - Translate a polyline over a given vector - - * list *vector* - - Translation vector - - * list *polyline* - - The polyline to be translated - - - __::math::geometry::rotate__ *angle* *polyline* - - Rotate a polyline over a given angle \(degrees\) around the origin - - * list *angle* - - Angle over which to rotate the polyline \(degrees\) - - * list *polyline* - - The polyline to be rotated - - - __::math::geometry::rotateAbout__ *p* *angle* *polyline* - - Rotate a polyline around a given point p and return the new polyline\. - - Arguments: - - * list *p* - - The point of rotation - - * float *angle* - - The angle over which to rotate the polyline \(degrees\) - - * list *polyline* - - The polyline to be rotated - - - __::math::geometry::reflect__ *angle* *polyline* - - Reflect a polyline in a line through the origin at a given angle \(degrees\) - to the x\-axis - - * list *angle* - - Angle of the line of reflection \(degrees\) - - * list *polyline* - - The polyline to be reflected - - - __::math::geometry::degToRad__ *angle* - - Convert from degrees to radians - - * list *angle* - - Angle in degrees - - - __::math::geometry::radToDeg__ *angle* - - Convert from radians to degrees - - * list *angle* - - Angle in radians - - - __::math::geometry::circle__ *centre* *radius* - - Convenience procedure to create a circle from a point and a radius\. - - * list *centre* - - Coordinates of the circle centre - - * list *radius* - - Radius of the circle - - - __::math::geometry::circleTwoPoints__ *point1* *point2* - - Convenience procedure to create a circle from two points on its - circumference The centre is the point between the two given points, the - radius is half the distance between them\. - - * list *point1* - - First point - - * list *point2* - - Second point - - - __::math::geometry::pointInsideCircle__ *point* *circle* - - Determine if the given point is inside the circle or on the circumference - \(1\) or outside \(0\)\. - - * list *point* - - Point to be checked - - * list *circle* - - Circle that may or may not contain the point - - - __::math::geometry::lineIntersectsCircle__ *line* *circle* - - Determine if the given line intersects the circle or touches it \(1\) or does - not \(0\)\. - - * list *line* - - Line to be checked - - * list *circle* - - Circle that may or may not be intersected - - - __::math::geometry::lineSegmentIntersectsCircle__ *segment* *circle* - - Determine if the given line segment intersects the circle or touches it \(1\) - or does not \(0\)\. - - * list *segment* - - Line segment to be checked - - * list *circle* - - Circle that may or may not be intersected - - - __::math::geometry::intersectionLineWithCircle__ *line* *circle* - - Determine the points at which the given line intersects the circle\. There - can be zero, one or two points\. \(If the line touches the circle or is close - to it, then one point is returned\. An arbitrary margin of 1\.0e\-10 times the - radius is used to determine this situation\.\) - - * list *line* - - Line to be checked - - * list *circle* - - Circle that may or may not be intersected - - - __::math::geometry::intersectionCircleWithCircle__ *circle1* *circle2* - - Determine the points at which the given two circles intersect\. There can be - zero, one or two points\. \(If the two circles touch the circle or are very - close, then one point is returned\. An arbitrary margin of 1\.0e\-10 times the - mean of the radii of the two circles is used to determine this situation\.\) - - * list *circle1* - - First circle - - * list *circle2* - - Second circle - - - __::math::geometry::tangentLinesToCircle__ *point* *circle* - - Determine the tangent lines from the given point to the circle\. There can be - zero, one or two lines\. \(If the point is on the cirucmference or very close - to the circle, then one line is returned\. An arbitrary margin of 1\.0e\-10 - times the radius of the circle is used to determine this situation\.\) - - * list *point* - - Point in question - - * list *circle* - - Circle to which the tangent lines are to be determined - - - __::math::geometry::intersectionPolylines__ *polyline1* *polyline2* ?mode? ?granularity? - - Return the first point or all points where the two polylines intersect\. If - the number of points in the polylines is large, you can use the granularity - to get an approximate answer faster\. - - Arguments: - - * list *polyline1* - - The first polyline - - * list *polyline2* - - The second polyline - - * string *mode* - - Whether to return only the first \(default\) or to return all intersection - points \("all"\) - - * int *granularity* - - The number of points that will be skipped plus 1 in the search for - intersection points \(1 or smaller means an exact answer is returned\) - - - __::math::geometry::intersectionPolylineCircle__ *polyline* *circle* ?mode? ?granularity? - - Return the first point or all points where the polyline intersects the - circle\. If the number of points in the polyline is large, you can use the - granularity to get an approximate answer faster\. - - Arguments: - - * list *polyline* - - The polyline that may intersect the circle - - * list *circle* - - The circle in question - - * string *mode* - - Whether to return only the first \(default\) or to return all intersection - points \("all"\) - - * int *granularity* - - The number of points that will be skipped plus 1 in the search for - intersection points \(1 or smaller means an exact answer is returned\) - - - __::math::geometry::polylineCutOrigin__ *polyline1* *polyline2* ?granularity? - - Return the part of the first polyline from the origin up to the first - intersection with the second\. If the number of points in the polyline is - large, you can use the granularity to get an approximate answer faster\. - - Arguments: - - * list *polyline1* - - The first polyline \(from which a part is to be returned\) - - * list *polyline2* - - The second polyline - - * int *granularity* - - The number of points that will be skipped plus 1 in the search for - intersection points \(1 or smaller means an exact answer is returned\) - - - __::math::geometry::polylineCutEnd__ *polyline1* *polyline2* ?granularity? - - Return the part of the first polyline from the last intersection point with - the second to the end\. If the number of points in the polyline is large, you - can use the granularity to get an approximate answer faster\. - - Arguments: - - * list *polyline1* - - The first polyline \(from which a part is to be returned\) - - * list *polyline2* - - The second polyline - - * int *granularity* - - The number of points that will be skipped plus 1 in the search for - intersection points \(1 or smaller means an exact answer is returned\) - - - __::math::geometry::splitPolyline__ *polyline* *numberVertex* - - Split the poyline into a set of polylines where each separate polyline holds - "numberVertex" vertices between the two end points\. - - Arguments: - - * list *polyline* - - The polyline to be split up - - * int *numberVertex* - - The number of "internal" vertices - - - __::math::geometry::enrichPolyline__ *polyline* *accuracy* - - Split up each segment of a polyline into a number of smaller segments and - return the result\. - - Arguments: - - * list *polyline* - - The polyline to be refined - - * int *accuracy* - - The number of subsegments to be created - - - __::math::geometry::cleanupPolyline__ *polyline* - - Remove duplicate neighbouring vertices and return the result\. - - Arguments: - - * list *polyline* - - The polyline to be cleaned up - -# COORDINATE SYSTEM - -The coordinate system used by the package is the ordinary cartesian system, -where the positive x\-axis is directed to the right and the positive y\-axis is -directed upwards\. Angles and directions are defined with respect to the positive -x\-axis in a counter\-clockwise direction, so that an angle of 90 degrees is the -direction of the positive y\-axis\. Note that the Tk canvas coordinates differ -from this, as there the origin is located in the upper left corner of the -window\. Up to and including version 1\.3, the direction and octant procedures of -this package used this convention inconsistently\. - -# References - - 1. [Polygon Intersection](http:/wiki\.tcl\.tk/12070) - - 1. [http://en\.wikipedia\.org/wiki/Line\-line\_intersection](http://en\.wikipedia\.org/wiki/Line\-line\_intersection) - - 1. [http://local\.wasp\.uwa\.edu\.au/~pbourke/geometry/lineline2d/](http://local\.wasp\.uwa\.edu\.au/~pbourke/geometry/lineline2d/) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: geometry* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[angle](\.\./\.\./\.\./\.\./index\.md\#angle), -[distance](\.\./\.\./\.\./\.\./index\.md\#distance), -[line](\.\./\.\./\.\./\.\./index\.md\#line), [math](\.\./\.\./\.\./\.\./index\.md\#math), -[plane geometry](\.\./\.\./\.\./\.\./index\.md\#plane\_geometry), -[point](\.\./\.\./\.\./\.\./index\.md\#point) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2001 by Ideogramic ApS and other parties -Copyright © 2010 by Andreas Kupries -Copyright © 2010 by Kevin Kenny -Copyright © 2018 by Arjen Markus -Copyright © 2020 by Manfred Rosenberger DELETED embedded/md/tcllib/files/modules/math/numtheory.md Index: embedded/md/tcllib/files/modules/math/numtheory.md ================================================================== --- embedded/md/tcllib/files/modules/math/numtheory.md +++ embedded/md/tcllib/files/modules/math/numtheory.md @@ -1,278 +0,0 @@ - -[//000000001]: # (math::numtheory \- Tcl Math Library) -[//000000002]: # (Generated from file 'numtheory\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010 Lars Hellström ) -[//000000004]: # (math::numtheory\(n\) 1\.1\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::numtheory \- Number Theory - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::numtheory ?1\.1\.1? - -[__math::numtheory::isprime__ *N* ?*option* *value* \.\.\.?](#1) -[__math::numtheory::firstNprimes__ *N*](#2) -[__math::numtheory::primesLowerThan__ *N*](#3) -[__math::numtheory::primeFactors__ *N*](#4) -[__math::numtheory::primesLowerThan__ *N*](#5) -[__math::numtheory::primeFactors__ *N*](#6) -[__math::numtheory::uniquePrimeFactors__ *N*](#7) -[__math::numtheory::factors__ *N*](#8) -[__math::numtheory::totient__ *N*](#9) -[__math::numtheory::moebius__ *N*](#10) -[__math::numtheory::legendre__ *a* *p*](#11) -[__math::numtheory::jacobi__ *a* *b*](#12) -[__math::numtheory::gcd__ *m* *n*](#13) -[__math::numtheory::lcm__ *m* *n*](#14) -[__math::numtheory::numberPrimesGauss__ *N*](#15) -[__math::numtheory::numberPrimesLegendre__ *N*](#16) -[__math::numtheory::numberPrimesLegendreModified__ *N*](#17) -[__math::numtheory::differenceNumberPrimesLegendreModified__ *lower* *upper*](#18) - -# DESCRIPTION - -This package is for collecting various number\-theoretic operations, with a -slight bias to prime numbers\. - - - __math::numtheory::isprime__ *N* ?*option* *value* \.\.\.? - - The __isprime__ command tests whether the integer *N* is a prime, - returning a boolean true value for prime *N* and a boolean false value for - non\-prime *N*\. The formal definition of 'prime' used is the conventional, - that the number being tested is greater than 1 and only has trivial - divisors\. - - To be precise, the return value is one of __0__ \(if *N* is definitely - not a prime\), __1__ \(if *N* is definitely a prime\), and __on__ \(if - *N* is probably prime\); the latter two are both boolean true values\. The - case that an integer may be classified as "probably prime" arises because - the Miller\-Rabin algorithm used in the test implementation is basically - probabilistic, and may if we are unlucky fail to detect that a number is in - fact composite\. Options may be used to select the risk of such "false - positives" in the test\. __1__ is returned for "small" *N* \(which - currently means *N* < 118670087467\), where it is known that no false - positives are possible\. - - The only option currently defined is: - - * __\-randommr__ *repetitions* - - which controls how many times the Miller\-Rabin test should be repeated - with randomly chosen bases\. Each repetition reduces the probability of a - false positive by a factor at least 4\. The default for *repetitions* - is 4\. - - Unknown options are silently ignored\. - - - __math::numtheory::firstNprimes__ *N* - - Return the first N primes - - * integer *N* \(in\) - - Number of primes to return - - - __math::numtheory::primesLowerThan__ *N* - - Return the prime numbers lower/equal to N - - * integer *N* \(in\) - - Maximum number to consider - - - __math::numtheory::primeFactors__ *N* - - Return a list of the prime numbers in the number N - - * integer *N* \(in\) - - Number to be factorised - - - __math::numtheory::primesLowerThan__ *N* - - Return the prime numbers lower/equal to N - - * integer *N* \(in\) - - Maximum number to consider - - - __math::numtheory::primeFactors__ *N* - - Return a list of the prime numbers in the number N - - * integer *N* \(in\) - - Number to be factorised - - - __math::numtheory::uniquePrimeFactors__ *N* - - Return a list of the *unique* prime numbers in the number N - - * integer *N* \(in\) - - Number to be factorised - - - __math::numtheory::factors__ *N* - - Return a list of all *unique* factors in the number N, including 1 and N - itself - - * integer *N* \(in\) - - Number to be factorised - - - __math::numtheory::totient__ *N* - - Evaluate the Euler totient function for the number N \(number of numbers - relatively prime to N\) - - * integer *N* \(in\) - - Number in question - - - __math::numtheory::moebius__ *N* - - Evaluate the Moebius function for the number N - - * integer *N* \(in\) - - Number in question - - - __math::numtheory::legendre__ *a* *p* - - Evaluate the Legendre symbol \(a/p\) - - * integer *a* \(in\) - - Upper number in the symbol - - * integer *p* \(in\) - - Lower number in the symbol \(must be non\-zero\) - - - __math::numtheory::jacobi__ *a* *b* - - Evaluate the Jacobi symbol \(a/b\) - - * integer *a* \(in\) - - Upper number in the symbol - - * integer *b* \(in\) - - Lower number in the symbol \(must be odd\) - - - __math::numtheory::gcd__ *m* *n* - - Return the greatest common divisor of *m* and *n* - - * integer *m* \(in\) - - First number - - * integer *n* \(in\) - - Second number - - - __math::numtheory::lcm__ *m* *n* - - Return the lowest common multiple of *m* and *n* - - * integer *m* \(in\) - - First number - - * integer *n* \(in\) - - Second number - - - __math::numtheory::numberPrimesGauss__ *N* - - Estimate the number of primes according the formula by Gauss\. - - * integer *N* \(in\) - - Number in question, should be larger than 0 - - - __math::numtheory::numberPrimesLegendre__ *N* - - Estimate the number of primes according the formula by Legendre\. - - * integer *N* \(in\) - - Number in question, should be larger than 0 - - - __math::numtheory::numberPrimesLegendreModified__ *N* - - Estimate the number of primes according the modified formula by Legendre\. - - * integer *N* \(in\) - - Number in question, should be larger than 0 - - - __math::numtheory::differenceNumberPrimesLegendreModified__ *lower* *upper* - - Estimate the number of primes between tow limits according the modified - formula by Legendre\. - - * integer *lower* \(in\) - - Lower limit for the primes, should be larger than 0 - - * integer *upper* \(in\) - - Upper limit for the primes, should be larger than 0 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: numtheory* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[number theory](\.\./\.\./\.\./\.\./index\.md\#number\_theory), -[prime](\.\./\.\./\.\./\.\./index\.md\#prime) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2010 Lars Hellström DELETED embedded/md/tcllib/files/modules/math/optimize.md Index: embedded/md/tcllib/files/modules/math/optimize.md ================================================================== --- embedded/md/tcllib/files/modules/math/optimize.md +++ embedded/md/tcllib/files/modules/math/optimize.md @@ -1,374 +0,0 @@ - -[//000000001]: # (math::optimize \- Tcl Math Library) -[//000000002]: # (Generated from file 'optimize\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (Copyright © 2004,2005 Kevn B\. Kenny ) -[//000000005]: # (math::optimize\(n\) 1\.0 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::optimize \- Optimisation routines - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [NOTES](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require math::optimize ?1\.0? - -[__::math::optimize::minimum__ *begin* *end* *func* *maxerr*](#1) -[__::math::optimize::maximum__ *begin* *end* *func* *maxerr*](#2) -[__::math::optimize::min\_bound\_1d__ *func* *begin* *end* ?__\-relerror__ *reltol*? ?__\-abserror__ *abstol*? ?__\-maxiter__ *maxiter*? ?__\-trace__ *traceflag*?](#3) -[__::math::optimize::min\_unbound\_1d__ *func* *begin* *end* ?__\-relerror__ *reltol*? ?__\-abserror__ *abstol*? ?__\-maxiter__ *maxiter*? ?__\-trace__ *traceflag*?](#4) -[__::math::optimize::solveLinearProgram__ *objective* *constraints*](#5) -[__::math::optimize::linearProgramMaximum__ *objective* *result*](#6) -[__::math::optimize::nelderMead__ *objective* *xVector* ?__\-scale__ *xScaleVector*? ?__\-ftol__ *epsilon*? ?__\-maxiter__ *count*? ??\-trace? *flag*?](#7) - -# DESCRIPTION - -This package implements several optimisation algorithms: - - - Minimize or maximize a function over a given interval - - - Solve a linear program \(maximize a linear function subject to linear - constraints\) - - - Minimize a function of several variables given an initial guess for the - location of the minimum\. - -The package is fully implemented in Tcl\. No particular attention has been paid -to the accuracy of the calculations\. Instead, the algorithms have been used in a -straightforward manner\. - -This document describes the procedures and explains their usage\. - -# PROCEDURES - -This package defines the following public procedures: - - - __::math::optimize::minimum__ *begin* *end* *func* *maxerr* - - Minimize the given \(continuous\) function by examining the values in the - given interval\. The procedure determines the values at both ends and in the - centre of the interval and then constructs a new interval of 1/2 length that - includes the minimum\. No guarantee is made that the *global* minimum is - found\. - - The procedure returns the "x" value for which the function is minimal\. - - *This procedure has been deprecated \- use min\_bound\_1d instead* - - *begin* \- Start of the interval - - *end* \- End of the interval - - *func* \- Name of the function to be minimized \(a procedure taking one - argument\)\. - - *maxerr* \- Maximum relative error \(defaults to 1\.0e\-4\) - - - __::math::optimize::maximum__ *begin* *end* *func* *maxerr* - - Maximize the given \(continuous\) function by examining the values in the - given interval\. The procedure determines the values at both ends and in the - centre of the interval and then constructs a new interval of 1/2 length that - includes the maximum\. No guarantee is made that the *global* maximum is - found\. - - The procedure returns the "x" value for which the function is maximal\. - - *This procedure has been deprecated \- use max\_bound\_1d instead* - - *begin* \- Start of the interval - - *end* \- End of the interval - - *func* \- Name of the function to be maximized \(a procedure taking one - argument\)\. - - *maxerr* \- Maximum relative error \(defaults to 1\.0e\-4\) - - - __::math::optimize::min\_bound\_1d__ *func* *begin* *end* ?__\-relerror__ *reltol*? ?__\-abserror__ *abstol*? ?__\-maxiter__ *maxiter*? ?__\-trace__ *traceflag*? - - Miminizes a function of one variable in the given interval\. The procedure - uses Brent's method of parabolic interpolation, protected by golden\-section - subdivisions if the interpolation is not converging\. No guarantee is made - that a *global* minimum is found\. The function to evaluate, *func*, must - be a single Tcl command; it will be evaluated with an abscissa appended as - the last argument\. - - *x1* and *x2* are the two bounds of the interval in which the minimum is - to be found\. They need not be in increasing order\. - - *reltol*, if specified, is the desired upper bound on the relative error - of the result; default is 1\.0e\-7\. The given value should never be smaller - than the square root of the machine's floating point precision, or else - convergence is not guaranteed\. *abstol*, if specified, is the desired - upper bound on the absolute error of the result; default is 1\.0e\-10\. Caution - must be used with small values of *abstol* to avoid overflow/underflow - conditions; if the minimum is expected to lie about a small but non\-zero - abscissa, you consider either shifting the function or changing its length - scale\. - - *maxiter* may be used to constrain the number of function evaluations to - be performed; default is 100\. If the command evaluates the function more - than *maxiter* times, it returns an error to the caller\. - - *traceFlag* is a Boolean value\. If true, it causes the command to print a - message on the standard output giving the abscissa and ordinate at each - function evaluation, together with an indication of what type of - interpolation was chosen\. Default is 0 \(no trace\)\. - - - __::math::optimize::min\_unbound\_1d__ *func* *begin* *end* ?__\-relerror__ *reltol*? ?__\-abserror__ *abstol*? ?__\-maxiter__ *maxiter*? ?__\-trace__ *traceflag*? - - Miminizes a function of one variable over the entire real number line\. The - procedure uses parabolic extrapolation combined with golden\-section - dilatation to search for a region where a minimum exists, followed by - Brent's method of parabolic interpolation, protected by golden\-section - subdivisions if the interpolation is not converging\. No guarantee is made - that a *global* minimum is found\. The function to evaluate, *func*, must - be a single Tcl command; it will be evaluated with an abscissa appended as - the last argument\. - - *x1* and *x2* are two initial guesses at where the minimum may lie\. - *x1* is the starting point for the minimization, and the difference - between *x2* and *x1* is used as a hint at the characteristic length - scale of the problem\. - - *reltol*, if specified, is the desired upper bound on the relative error - of the result; default is 1\.0e\-7\. The given value should never be smaller - than the square root of the machine's floating point precision, or else - convergence is not guaranteed\. *abstol*, if specified, is the desired - upper bound on the absolute error of the result; default is 1\.0e\-10\. Caution - must be used with small values of *abstol* to avoid overflow/underflow - conditions; if the minimum is expected to lie about a small but non\-zero - abscissa, you consider either shifting the function or changing its length - scale\. - - *maxiter* may be used to constrain the number of function evaluations to - be performed; default is 100\. If the command evaluates the function more - than *maxiter* times, it returns an error to the caller\. - - *traceFlag* is a Boolean value\. If true, it causes the command to print a - message on the standard output giving the abscissa and ordinate at each - function evaluation, together with an indication of what type of - interpolation was chosen\. Default is 0 \(no trace\)\. - - - __::math::optimize::solveLinearProgram__ *objective* *constraints* - - Solve a *linear program* in standard form using a straightforward - implementation of the Simplex algorithm\. \(In the explanation below: The - linear program has N constraints and M variables\)\. - - The procedure returns a list of M values, the values for which the objective - function is maximal or a single keyword if the linear program is not - feasible or unbounded \(either "unfeasible" or "unbounded"\) - - *objective* \- The M coefficients of the objective function - - *constraints* \- Matrix of coefficients plus maximum values that implement - the linear constraints\. It is expected to be a list of N lists of M\+1 - numbers each, M coefficients and the maximum value\. - - - __::math::optimize::linearProgramMaximum__ *objective* *result* - - Convenience function to return the maximum for the solution found by the - solveLinearProgram procedure\. - - *objective* \- The M coefficients of the objective function - - *result* \- The result as returned by solveLinearProgram - - - __::math::optimize::nelderMead__ *objective* *xVector* ?__\-scale__ *xScaleVector*? ?__\-ftol__ *epsilon*? ?__\-maxiter__ *count*? ??\-trace? *flag*? - - Minimizes, in unconstrained fashion, a function of several variable over all - of space\. The function to evaluate, *objective*, must be a single Tcl - command\. To it will be appended as many elements as appear in the initial - guess at the location of the minimum, passed in as a Tcl list, *xVector*\. - - *xScaleVector* is an initial guess at the problem scale; the first - function evaluations will be made by varying the co\-ordinates in *xVector* - by the amounts in *xScaleVector*\. If *xScaleVector* is not supplied, the - co\-ordinates will be varied by a factor of 1\.0001 \(if the co\-ordinate is - non\-zero\) or by a constant 0\.0001 \(if the co\-ordinate is zero\)\. - - *epsilon* is the desired relative error in the value of the function - evaluated at the minimum\. The default is 1\.0e\-7, which usually gives three - significant digits of accuracy in the values of the x's\. - - pp *count* is a limit on the number of trips through the main loop of the - optimizer\. The number of function evaluations may be several times this - number\. If the optimizer fails to find a minimum to within *ftol* in - *maxiter* iterations, it returns its current best guess and an error - status\. Default is to allow 500 iterations\. - - *flag* is a flag that, if true, causes a line to be written to the - standard output for each evaluation of the objective function, giving the - arguments presented to the function and the value returned\. Default is - false\. - - The __nelderMead__ procedure returns a list of alternating keywords and - values suitable for use with __array set__\. The meaning of the keywords - is: - - *x* is the approximate location of the minimum\. - - *y* is the value of the function at *x*\. - - *yvec* is a vector of the best N\+1 function values achieved, where N is - the dimension of *x* - - *vertices* is a list of vectors giving the function arguments - corresponding to the values in *yvec*\. - - *nIter* is the number of iterations required to achieve convergence or - fail\. - - *status* is 'ok' if the operation succeeded, or 'too\-many\-iterations' if - the maximum iteration count was exceeded\. - - __nelderMead__ minimizes the given function using the downhill simplex - method of Nelder and Mead\. This method is quite slow \- much faster methods - for minimization are known \- but has the advantage of being extremely robust - in the face of problems where the minimum lies in a valley of complex - topology\. - - __nelderMead__ can occasionally find itself "stuck" at a point where it - can make no further progress; it is recommended that the caller run it at - least a second time, passing as the initial guess the result found by the - previous call\. The second run is usually very fast\. - - __nelderMead__ can be used in some cases for constrained optimization\. - To do this, add a large value to the objective function if the parameters - are outside the feasible region\. To work effectively in this mode, - __nelderMead__ requires that the initial guess be feasible and usually - requires that the feasible region be convex\. - -# NOTES - -Several of the above procedures take the *names* of procedures as arguments\. -To avoid problems with the *visibility* of these procedures, the -fully\-qualified name of these procedures is determined inside the optimize -routines\. For the user this has only one consequence: the named procedure must -be visible in the calling procedure\. For instance: - - namespace eval ::mySpace { - namespace export calcfunc - proc calcfunc { x } { return $x } - } - # - # Use a fully-qualified name - # - namespace eval ::myCalc { - puts [min_bound_1d ::myCalc::calcfunc $begin $end] - } - # - # Import the name - # - namespace eval ::myCalc { - namespace import ::mySpace::calcfunc - puts [min_bound_1d calcfunc $begin $end] - } - -The simple procedures *minimum* and *maximum* have been deprecated: the -alternatives are much more flexible, robust and require less function -evaluations\. - -# EXAMPLES - -Let us take a few simple examples: - -Determine the maximum of f\(x\) = x^3 exp\(\-3x\), on the interval \(0,10\): - - proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} } - puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]" - -The maximum allowed error determines the number of steps taken \(with each step -in the iteration the interval is reduced with a factor 1/2\)\. Hence, a maximum -error of 0\.0001 is achieved in approximately 14 steps\. - -An example of a *linear program* is: - -Optimise the expression 3x\+2y, where: - - x >= 0 and y >= 0 (implicit constraints, part of the - definition of linear programs) - - x + y <= 1 (constraints specific to the problem) - 2x + 5y <= 10 - -This problem can be solved as follows: - - set solution [::math::optimize::solveLinearProgram { 3.0 2.0 } { { 1.0 1.0 1.0 } - { 2.0 5.0 10.0 } } ] - -Note, that a constraint like: - - x + y >= 1 - -can be turned into standard form using: - - -x -y <= -1 - -The theory of linear programming is the subject of many a text book and the -Simplex algorithm that is implemented here is the best\-known method to solve -this type of problems, but it is not the only one\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: optimize* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[linear program](\.\./\.\./\.\./\.\./index\.md\#linear\_program), -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum), -[minimum](\.\./\.\./\.\./\.\./index\.md\#minimum), -[optimization](\.\./\.\./\.\./\.\./index\.md\#optimization) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus -Copyright © 2004,2005 Kevn B\. Kenny DELETED embedded/md/tcllib/files/modules/math/pca.md Index: embedded/md/tcllib/files/modules/math/pca.md ================================================================== --- embedded/md/tcllib/files/modules/math/pca.md +++ embedded/md/tcllib/files/modules/math/pca.md @@ -1,199 +0,0 @@ - -[//000000001]: # (math::PCA \- Principal Components Analysis) -[//000000002]: # (Generated from file 'pca\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::PCA\(n\) 1\.0 tcllib "Principal Components Analysis") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::PCA \- Package for Principal Component Analysis - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [EXAMPLE](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl ?8\.6? -package require math::linearalgebra 1\.0 - -[__::math::PCA::createPCA__ *data* ?args?](#1) -[__$pca using__ ?number?|?\-minproportion value?](#2) -[__$pca eigenvectors__ ?option?](#3) -[__$pca eigenvalues__ ?option?](#4) -[__$pca proportions__ ?option?](#5) -[__$pca approximate__ *observation*](#6) -[__$pca approximatOriginal__](#7) -[__$pca scores__ *observation*](#8) -[__$pca distance__ *observation*](#9) -[__$pca qstatistic__ *observation* ?option?](#10) - -# DESCRIPTION - -The PCA package provides a means to perform principal components analysis in -Tcl, using an object\-oriented technique as facilitated by TclOO\. It actually -defines a single public method, *::math::PCA::createPCA*, which constructs an -object based on the data that are passed to perform the actual analysis\. - -The methods of the PCA objects that are created with this command allow one to -examine the principal components, to approximate \(new\) observations using all or -a selected number of components only and to examine the properties of the -components and the statistics of the approximations\. - -The package has been modelled after the PCA example provided by the original -linear algebra package by Ed Hume\. - -# Commands - -The *math::PCA* package provides one public command: - - - __::math::PCA::createPCA__ *data* ?args? - - Create a new object, based on the data that are passed via the *data* - argument\. The principal components may be based on either correlations or - covariances\. All observations will be normalised according to the mean and - standard deviation of the original data\. - - * list *data* - - \- A list of observations \(see the example below\)\. - - * list *args* - - \- A list of key\-value pairs defining the options\. Currently there is - only one key: *\-covariances*\. This indicates if covariances are to be - used \(if the value is 1\) or instead correlations \(value is 0\)\. The - default is to use correlations\. - -The PCA object that is created has the following methods: - - - __$pca using__ ?number?|?\-minproportion value? - - Set the number of components to be used in the analysis \(the number of - retained components\)\. Returns the number of components, also if no argument - is given\. - - * int *number* - - \- The number of components to be retained - - * double *value* - - \- Select the number of components based on the minimum proportion of - variation that is retained by them\. Should be a value between 0 and 1\. - - - __$pca eigenvectors__ ?option? - - Return the eigenvectors as a list of lists\. - - * string *option* - - \- By default only the *retained* components are returned\. If all - eigenvectors are required, use the option *\-all*\. - - - __$pca eigenvalues__ ?option? - - Return the eigenvalues as a list of lists\. - - * string *option* - - \- By default only the eigenvalues of the *retained* components are - returned\. If all eigenvalues are required, use the option *\-all*\. - - - __$pca proportions__ ?option? - - Return the proportions for all components, that is, the amount of variations - that each components can explain\. - - - __$pca approximate__ *observation* - - Return an approximation of the observation based on the retained components - - * list *observation* - - \- The values for the observation\. - - - __$pca approximatOriginal__ - - Return an approximation of the original data, using the retained components\. - It is a convenience method that works on the complete set of original data\. - - - __$pca scores__ *observation* - - Return the scores per retained component for the given observation\. - - * list *observation* - - \- The values for the observation\. - - - __$pca distance__ *observation* - - Return the distance between the given observation and its approximation\. - \(Note: this distance is based on the normalised vectors\.\) - - * list *observation* - - \- The values for the observation\. - - - __$pca qstatistic__ *observation* ?option? - - Return the Q statistic, basically the square of the distance, for the given - observation\. - - * list *observation* - - \- The values for the observation\. - - * string *option* - - \- If the observation is part of the original data, you may want to use - the corrected Q statistic\. This is achieved with the option "\-original"\. - -# EXAMPLE - -TODO: NIST example - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *PCA* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[PCA](\.\./\.\./\.\./\.\./index\.md\#pca), [math](\.\./\.\./\.\./\.\./index\.md\#math), -[statistics](\.\./\.\./\.\./\.\./index\.md\#statistics), -[tcl](\.\./\.\./\.\./\.\./index\.md\#tcl) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/polynomials.md Index: embedded/md/tcllib/files/modules/math/polynomials.md ================================================================== --- embedded/md/tcllib/files/modules/math/polynomials.md +++ embedded/md/tcllib/files/modules/math/polynomials.md @@ -1,253 +0,0 @@ - -[//000000001]: # (math::polynomials \- Tcl Math Library) -[//000000002]: # (Generated from file 'polynomials\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (math::polynomials\(n\) 1\.0\.1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::polynomials \- Polynomial functions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [REMARKS ON THE IMPLEMENTATION](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.3? -package require math::polynomials ?1\.0\.1? - -[__::math::polynomials::polynomial__ *coeffs*](#1) -[__::math::polynomials::polynCmd__ *coeffs*](#2) -[__::math::polynomials::evalPolyn__ *polynomial* *x*](#3) -[__::math::polynomials::addPolyn__ *polyn1* *polyn2*](#4) -[__::math::polynomials::subPolyn__ *polyn1* *polyn2*](#5) -[__::math::polynomials::multPolyn__ *polyn1* *polyn2*](#6) -[__::math::polynomials::divPolyn__ *polyn1* *polyn2*](#7) -[__::math::polynomials::remainderPolyn__ *polyn1* *polyn2*](#8) -[__::math::polynomials::derivPolyn__ *polyn*](#9) -[__::math::polynomials::primitivePolyn__ *polyn*](#10) -[__::math::polynomials::degreePolyn__ *polyn*](#11) -[__::math::polynomials::coeffPolyn__ *polyn* *index*](#12) -[__::math::polynomials::allCoeffsPolyn__ *polyn*](#13) - -# DESCRIPTION - -This package deals with polynomial functions of one variable: - - - the basic arithmetic operations are extended to polynomials - - - computing the derivatives and primitives of these functions - - - evaluation through a general procedure or via specific procedures\) - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::polynomials::polynomial__ *coeffs* - - Return an \(encoded\) list that defines the polynomial\. A polynomial - - f(x) = a + b.x + c.x**2 + d.x**3 - - can be defined via: - - set f [::math::polynomials::polynomial [list $a $b $c $d] - - * list *coeffs* - - Coefficients of the polynomial \(in ascending order\) - - - __::math::polynomials::polynCmd__ *coeffs* - - Create a new procedure that evaluates the polynomial\. The name of the - polynomial is automatically generated\. Useful if you need to evualuate the - polynomial many times, as the procedure consists of a single \[expr\] command\. - - * list *coeffs* - - Coefficients of the polynomial \(in ascending order\) or the polynomial - definition returned by the *polynomial* command\. - - - __::math::polynomials::evalPolyn__ *polynomial* *x* - - Evaluate the polynomial at x\. - - * list *polynomial* - - The polynomial's definition \(as returned by the polynomial command\)\. - order\) - - * float *x* - - The coordinate at which to evaluate the polynomial - - - __::math::polynomials::addPolyn__ *polyn1* *polyn2* - - Return a new polynomial which is the sum of the two others\. - - * list *polyn1* - - The first polynomial operand - - * list *polyn2* - - The second polynomial operand - - - __::math::polynomials::subPolyn__ *polyn1* *polyn2* - - Return a new polynomial which is the difference of the two others\. - - * list *polyn1* - - The first polynomial operand - - * list *polyn2* - - The second polynomial operand - - - __::math::polynomials::multPolyn__ *polyn1* *polyn2* - - Return a new polynomial which is the product of the two others\. If one of - the arguments is a scalar value, the other polynomial is simply scaled\. - - * list *polyn1* - - The first polynomial operand or a scalar - - * list *polyn2* - - The second polynomial operand or a scalar - - - __::math::polynomials::divPolyn__ *polyn1* *polyn2* - - Divide the first polynomial by the second polynomial and return the result\. - The remainder is dropped - - * list *polyn1* - - The first polynomial operand - - * list *polyn2* - - The second polynomial operand - - - __::math::polynomials::remainderPolyn__ *polyn1* *polyn2* - - Divide the first polynomial by the second polynomial and return the - remainder\. - - * list *polyn1* - - The first polynomial operand - - * list *polyn2* - - The second polynomial operand - - - __::math::polynomials::derivPolyn__ *polyn* - - Differentiate the polynomial and return the result\. - - * list *polyn* - - The polynomial to be differentiated - - - __::math::polynomials::primitivePolyn__ *polyn* - - Integrate the polynomial and return the result\. The integration constant is - set to zero\. - - * list *polyn* - - The polynomial to be integrated - - - __::math::polynomials::degreePolyn__ *polyn* - - Return the degree of the polynomial\. - - * list *polyn* - - The polynomial to be examined - - - __::math::polynomials::coeffPolyn__ *polyn* *index* - - Return the coefficient of the term of the index'th degree of the polynomial\. - - * list *polyn* - - The polynomial to be examined - - * int *index* - - The degree of the term - - - __::math::polynomials::allCoeffsPolyn__ *polyn* - - Return the coefficients of the polynomial \(in ascending order\)\. - - * list *polyn* - - The polynomial in question - -# REMARKS ON THE IMPLEMENTATION - -The implementation for evaluating the polynomials at some point uses Horn's -rule, which guarantees numerical stability and a minimum of arithmetic -operations\. To recognise that a polynomial definition is indeed a correct -definition, it consists of a list of two elements: the keyword "POLYNOMIAL" and -the list of coefficients in descending order\. The latter makes it easier to -implement Horner's rule\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: polynomials* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), [polynomial -functions](\.\./\.\./\.\./\.\./index\.md\#polynomial\_functions) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/probopt.md Index: embedded/md/tcllib/files/modules/math/probopt.md ================================================================== --- embedded/md/tcllib/files/modules/math/probopt.md +++ embedded/md/tcllib/files/modules/math/probopt.md @@ -1,293 +0,0 @@ - -[//000000001]: # (math::probopt \- Tcl Math Library) -[//000000002]: # (Generated from file 'probopt\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::probopt\(n\) 1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::probopt \- Probabilistic optimisation methods - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [DETAILS ON THE ALGORITHMS](#section2) - - - [References](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require math::probopt 1 - -[__::math::probopt::pso__ *function* *bounds* *args*](#1) -[__::math::probopt::sce__ *function* *bounds* *args*](#2) -[__::math::probopt::diffev__ *function* *bounds* *args*](#3) -[__::math::probopt::lipoMax__ *function* *bounds* *args*](#4) -[__::math::probopt::adaLipoMax__ *function* *bounds* *args*](#5) - -# DESCRIPTION - -The purpose of the __math::probopt__ package is to provide various -optimisation algorithms that are based on probabilistic techniques\. The results -of these algorithms may therefore vary from one run to the next\. The algorithms -are all well\-known and well described and proponents generally claim they are -efficient and reliable\. - -As most of these algorithms have one or more tunable parameters or even -variations, the interface to each accepts options to set these parameters or the -select the variation\. These take the form of key\-value pairs, for instance, -*\-iterations 100*\. - -This manual does not offer any recommendations with regards to these algorithms, -nor does it provide much in the way of guidelines for the parameters\. For this -we refer to online articles on the algorithms in question\. - -A few notes, however: - - - With the exception of LIPO, the algorithms are capable of dealing with - irregular \(non\-smooth\) and even discontinuous functions\. - - - The results depend on the random number seeding and are likely not to be - very accurate, especially if the function varies slowly in the vicinty of - the optimum\. They do give a good starting point for a deterministic - algorithm\. - -The collection consists of the following algorithms: - - - PSO \- particle swarm optimisation - - - SCE \- shuffled complexes evolution - - - DE \- differential evolution - - - LIPO \- Lipschitz optimisation - -The various procedures have a uniform interface: - - set result [::math::probopt::algorithm function bounds args] - -The arguments have the following meaning: - - - The argument *function* is the name of the procedure that evaluates the - function\. Its interface is: - - set value [function coords] - - where *coords* is a list of coordinates at which to evaluate the function\. - It is supposed to return the function value\. - - - The argument *bounds* is a list of pairs of minimum and maximum for each - coordinate\. This list implicitly determines the dimension of the coordinate - space in which the optimum is to be sought, for instance for a function like - *x\*\*2 \+ \(y\-1\)\*\*4*, you may specify the bounds as *\{\{\-1 1\} \{\-1 1\}\}*, that - is, two pairs for the two coordinates\. - - - The rest \(*args*\) consists of zero or more key\-value pairs to specify the - options\. Which options are supported by which algorithm, is documented - below\. - -The result of the various optimisation procedures is a dictionary containing at -least the following elements: - - - *optimum\-coordinates* is a list containing the coordinates of the optimum - that was found\. - - - *optimum\-value* is the function value at those coordinates\. - - - *evaluations* is the number of function evaluations\. - - - *best\-values* is a list of successive best values, obtained as part of the - iterations\. - -# DETAILS ON THE ALGORITHMS - -The algorithms in the package are the following: - - - __::math::probopt::pso__ *function* *bounds* *args* - - The "particle swarm optimisation" algorithm uses the idea that the candidate - optimum points should swarm around the best point found so far, with - variations to allow for improvements\. - - It recognises the following options: - - * *\-swarmsize number*: Number of particles to consider \(default: 50\) - - * *\-vweight value*: Weight for the current "velocity" \(0\-1, default: - 0\.5\) - - * *\-pweight value*: Weight for the individual particle's best position - \(0\-1, default: 0\.3\) - - * *\-gweight value*: Weight for the "best" overall position as per - particle \(0\-1, default: 0\.3\) - - * *\-type local/global*: Type of optimisation - - * *\-neighbours number*: Size of the neighbourhood \(default: 5, used if - "local"\) - - * *\-iterations number*: Maximum number of iterations - - * *\-tolerance value*: Absolute minimal improvement for minimum value - - - __::math::probopt::sce__ *function* *bounds* *args* - - The "shuffled complex evolution" algorithm is an extension of the - Nelder\-Mead algorithm that uses multiple complexes and reorganises these - complexes to find the "global" optimum\. - - It recognises the following options: - - * *\-complexes number*: Number of particles to consider \(default: 2\) - - * *\-mincomplexes number*: Minimum number of complexes \(default: 2; not - currently used\) - - * *\-newpoints number*: Number of new points to be generated \(default: 1\) - - * *\-shuffle number*: Number of iterations after which to reshuffle the - complexes \(if set to 0, the default, a number will be calculated from - the number of dimensions\) - - * *\-pointspercomplex number*: Number of points per complex \(if set to 0, - the default, a number will be calculated from the number of dimensions\) - - * *\-pointspersubcomplex number*: Number of points per subcomplex \(used - to select the best points in each complex; if set to 0, the default, a - number will be calculated from the number of dimensions\) - - * *\-iterations number*: Maximum number of iterations \(default: 100\) - - * *\-maxevaluations number*: Maximum number of function evaluations \(when - this number is reached the iteration is broken off\. Default: 1000 - million\) - - * *\-abstolerance value*: Absolute minimal improvement for minimum value - \(default: 0\.0\) - - * *\-reltolerance value*: Relative minimal improvement for minimum value - \(default: 0\.001\) - - - __::math::probopt::diffev__ *function* *bounds* *args* - - The "differential evolution" algorithm uses a number of initial points that - are then updated using randomly selected points\. It is more or less akin to - genetic algorithms\. It is controlled by two parameters, factor and lambda, - where the first determines the update via random points and the second the - update with the best point found sofar\. - - It recognises the following options: - - * *\-iterations number*: Maximum number of iterations \(default: 100\) - - * *\-number number*: Number of point to work with \(if set to 0, the - default, it is calculated from the number of dimensions\) - - * *\-factor value*: Weight of randomly selected points in the updating - \(0\-1, default: 0\.6\) - - * *\-lambda value*: Weight of the best point found so far in the updating - \(0\-1, default: 0\.0\) - - * *\-crossover value*: Fraction of new points to be considered for - replacing the old ones \(0\-1, default: 0\.5\) - - * *\-maxevaluations number*: Maximum number of function evaluations \(when - this number is reached the iteration is broken off\. Default: 1000 - million\) - - * *\-abstolerance value*: Absolute minimal improvement for minimum value - \(default: 0\.0\) - - * *\-reltolerance value*: Relative minimal improvement for minimum value - \(default: 0\.001\) - - - __::math::probopt::lipoMax__ *function* *bounds* *args* - - The "Lipschitz optimisation" algorithm uses the "Lipschitz" property of the - given function to find a *maximum* in the given bounding box\. There are - two variants, *lipoMax* assumes a fixed estimate for the Lipschitz - parameter\. - - It recognises the following options: - - * *\-iterations number*: Number of iterations \(equals the actual number - of function evaluations, default: 100\) - - * *\-lipschitz value*: Estimate of the Lipschitz parameter \(default: - 10\.0\) - - - __::math::probopt::adaLipoMax__ *function* *bounds* *args* - - The "adaptive Lipschitz optimisation" algorithm uses the "Lipschitz" - property of the given function to find a *maximum* in the given bounding - box\. The adaptive variant actually uses two phases to find a suitable - estimate for the Lipschitz parameter\. This is controlled by the "Bernoulli" - parameter\. - - When you specify a large number of iterations, the algorithm may take a very - long time to complete as it is trying to improve on the Lipschitz parameter - and the chances of hitting a better estimate diminish fast\. - - It recognises the following options: - - * *\-iterations number*: Number of iterations \(equals the actual number - of function evaluations, default: 100\) - - * *\-bernoulli value*: Parameter for random decisions \(exploration versus - exploitation, default: 0\.1\) - -# References - -The various algorithms have been described in on\-line publications\. Here are a -few: - - - *PSO*: Maurice Clerc, Standard Particle Swarm Optimisation \(2012\) - [https://hal\.archives\-ouvertes\.fr/file/index/docid/764996/filename/SPSO\_descriptions\.pdf](https://hal\.archives\-ouvertes\.fr/file/index/docid/764996/filename/SPSO\_descriptions\.pdf) - - Alternatively: - [https://en\.wikipedia\.org/wiki/Particle\_swarm\_optimization](https://en\.wikipedia\.org/wiki/Particle\_swarm\_optimization) - - - *SCE*: Qingyuan Duan, Soroosh Sorooshian, Vijai K\. Gupta, Optimal use offo - the SCE\-UA global optimization method for calibrating watershed models - \(1994\), Journal of Hydrology 158, pp 265\-284 - - [https://www\.researchgate\.net/publication/223408756\_Optimal\_Use\_of\_the\_SCE\-UA\_Global\_Optimization\_Method\_for\_Calibrating\_Watershed\_Models](https://www\.researchgate\.net/publication/223408756\_Optimal\_Use\_of\_the\_SCE\-UA\_Global\_Optimization\_Method\_for\_Calibrating\_Watershed\_Models) - - - *[DE](\.\./\.\./\.\./\.\./index\.md\#de)*: Rainer Storn and Kenneth Price, - Differential Evolution \- A simple and efficient adaptivescheme for - globaloptimization over continuous spaces \(1996\) - - [http://www1\.icsi\.berkeley\.edu/~storn/TR\-95\-012\.pdf](http://www1\.icsi\.berkeley\.edu/~storn/TR\-95\-012\.pdf) - - - *LIPO*: Cedric Malherbe and Nicolas Vayatis, Global optimization of - Lipschitz functions, \(june 2017\) - - [https://arxiv\.org/pdf/1703\.02628\.pdf](https://arxiv\.org/pdf/1703\.02628\.pdf) - -# KEYWORDS - -[mathematics](\.\./\.\./\.\./\.\./index\.md\#mathematics), -[optimisation](\.\./\.\./\.\./\.\./index\.md\#optimisation), [probabilistic -calculations](\.\./\.\./\.\./\.\./index\.md\#probabilistic\_calculations) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/qcomplex.md Index: embedded/md/tcllib/files/modules/math/qcomplex.md ================================================================== --- embedded/md/tcllib/files/modules/math/qcomplex.md +++ embedded/md/tcllib/files/modules/math/qcomplex.md @@ -1,299 +0,0 @@ - -[//000000001]: # (math::complexnumbers \- Tcl Math Library) -[//000000002]: # (Generated from file 'qcomplex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (math::complexnumbers\(n\) 1\.0\.2 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::complexnumbers \- Straightforward complex number package - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [AVAILABLE PROCEDURES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require math::complexnumbers ?1\.0\.2? - -[__::math::complexnumbers::\+__ *z1* *z2*](#1) -[__::math::complexnumbers::\-__ *z1* *z2*](#2) -[__::math::complexnumbers::\*__ *z1* *z2*](#3) -[__::math::complexnumbers::/__ *z1* *z2*](#4) -[__::math::complexnumbers::conj__ *z1*](#5) -[__::math::complexnumbers::real__ *z1*](#6) -[__::math::complexnumbers::imag__ *z1*](#7) -[__::math::complexnumbers::mod__ *z1*](#8) -[__::math::complexnumbers::arg__ *z1*](#9) -[__::math::complexnumbers::complex__ *real* *imag*](#10) -[__::math::complexnumbers::tostring__ *z1*](#11) -[__::math::complexnumbers::exp__ *z1*](#12) -[__::math::complexnumbers::sin__ *z1*](#13) -[__::math::complexnumbers::cos__ *z1*](#14) -[__::math::complexnumbers::tan__ *z1*](#15) -[__::math::complexnumbers::log__ *z1*](#16) -[__::math::complexnumbers::sqrt__ *z1*](#17) -[__::math::complexnumbers::pow__ *z1* *z2*](#18) - -# DESCRIPTION - -The mathematical module *complexnumbers* provides a straightforward -implementation of complex numbers in pure Tcl\. The philosophy is that the user -knows he or she is dealing with complex numbers in an abstract way and wants as -high a performance as can be had within the limitations of an interpreted -language\. - -Therefore the procedures defined in this package assume that the arguments are -valid \(representations of\) "complex numbers", that is, lists of two numbers -defining the real and imaginary part of a complex number \(though this is a mere -detail: rely on the *complex* command to construct a valid number\.\) - -Most procedures implement the basic arithmetic operations or elementary -functions whereas several others convert to and from different representations: - - set z [complex 0 1] - puts "z = [tostring $z]" - puts "z**2 = [* $z $z] - -would result in: - - z = i - z**2 = -1 - -# AVAILABLE PROCEDURES - -The package implements all or most basic operations and elementary functions\. - -*The arithmetic operations are:* - - - __::math::complexnumbers::\+__ *z1* *z2* - - Add the two arguments and return the resulting complex number - - * complex *z1* \(in\) - - First argument in the summation - - * complex *z2* \(in\) - - Second argument in the summation - - - __::math::complexnumbers::\-__ *z1* *z2* - - Subtract the second argument from the first and return the resulting complex - number\. If there is only one argument, the opposite of z1 is returned \(i\.e\. - \-z1\) - - * complex *z1* \(in\) - - First argument in the subtraction - - * complex *z2* \(in\) - - Second argument in the subtraction \(optional\) - - - __::math::complexnumbers::\*__ *z1* *z2* - - Multiply the two arguments and return the resulting complex number - - * complex *z1* \(in\) - - First argument in the multiplication - - * complex *z2* \(in\) - - Second argument in the multiplication - - - __::math::complexnumbers::/__ *z1* *z2* - - Divide the first argument by the second and return the resulting complex - number - - * complex *z1* \(in\) - - First argument \(numerator\) in the division - - * complex *z2* \(in\) - - Second argument \(denominator\) in the division - - - __::math::complexnumbers::conj__ *z1* - - Return the conjugate of the given complex number - - * complex *z1* \(in\) - - Complex number in question - -*Conversion/inquiry procedures:* - - - __::math::complexnumbers::real__ *z1* - - Return the real part of the given complex number - - * complex *z1* \(in\) - - Complex number in question - - - __::math::complexnumbers::imag__ *z1* - - Return the imaginary part of the given complex number - - * complex *z1* \(in\) - - Complex number in question - - - __::math::complexnumbers::mod__ *z1* - - Return the modulus of the given complex number - - * complex *z1* \(in\) - - Complex number in question - - - __::math::complexnumbers::arg__ *z1* - - Return the argument \("angle" in radians\) of the given complex number - - * complex *z1* \(in\) - - Complex number in question - - - __::math::complexnumbers::complex__ *real* *imag* - - Construct the complex number "real \+ imag\*i" and return it - - * float *real* \(in\) - - The real part of the new complex number - - * float *imag* \(in\) - - The imaginary part of the new complex number - - - __::math::complexnumbers::tostring__ *z1* - - Convert the complex number to the form "real \+ imag\*i" and return the string - - * float *complex* \(in\) - - The complex number to be converted - -*Elementary functions:* - - - __::math::complexnumbers::exp__ *z1* - - Calculate the exponential for the given complex argument and return the - result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::sin__ *z1* - - Calculate the sine function for the given complex argument and return the - result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::cos__ *z1* - - Calculate the cosine function for the given complex argument and return the - result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::tan__ *z1* - - Calculate the tangent function for the given complex argument and return the - result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::log__ *z1* - - Calculate the \(principle value of the\) logarithm for the given complex - argument and return the result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::sqrt__ *z1* - - Calculate the \(principle value of the\) square root for the given complex - argument and return the result - - * complex *z1* \(in\) - - The complex argument for the function - - - __::math::complexnumbers::pow__ *z1* *z2* - - Calculate "z1 to the power of z2" and return the result - - * complex *z1* \(in\) - - The complex number to be raised to a power - - * complex *z2* \(in\) - - The complex power to be used - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: complexnumbers* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[complex numbers](\.\./\.\./\.\./\.\./index\.md\#complex\_numbers), -[math](\.\./\.\./\.\./\.\./index\.md\#math) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/quasirandom.md Index: embedded/md/tcllib/files/modules/math/quasirandom.md ================================================================== --- embedded/md/tcllib/files/modules/math/quasirandom.md +++ embedded/md/tcllib/files/modules/math/quasirandom.md @@ -1,167 +0,0 @@ - -[//000000001]: # (math::quasirandom \- Tcl Math Library) -[//000000002]: # (Generated from file 'quasirandom\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::quasirandom\(n\) 1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::quasirandom \- Quasi\-random points for integration and Monte Carlo type -methods - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [TODO](#section3) - - - [References](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require math::quasirandom 1 - -[__::math::quasirandom::qrpoint create__ *NAME* *DIM* ?ARGS?](#1) -[__gen next__](#2) -[__gen set\-start__ *index*](#3) -[__gen set\-evaluations__ *number*](#4) -[__gen integral__ *func* *minmax* *args*](#5) - -# DESCRIPTION - -In many applications pseudo\-random numbers and pseudo\-random points in a -\(limited\) sample space play an important role\. For instance in any type of Monte -Carlo simulation\. Pseudo\-random numbers, however, may be too random and as a -consequence a large number of data points is required to reduce the error or -fluctuation in the results to the desired value\. - -Quasi\-random numbers can be used as an alternative: instead of "completely" -arbitrary points, points are generated that are diverse enough to cover the -entire sample space in a more or less uniform way\. As a consequence convergence -to the limit can be much faster, when such quasi\-random numbers are well\-chosen\. - -The package defines a *[class](\.\./\.\./\.\./\.\./index\.md\#class)* "qrpoint" that -creates a command to generate quasi\-random points in 1, 2 or more dimensions\. -The command can either generate separate points, so that they can be used in a -user\-defined algorithm or use these points to calculate integrals of functions -defined over 1, 2 or more dimensions\. It also holds several other common -algorithms\. \(NOTE: these are not implemented yet\) - -One particular characteristic of the generators is that there are no tuning -parameters involved, which makes the use particularly simple\. - -# COMMANDS - -A quasi\-random point generator is created using the *qrpoint* class: - - - __::math::quasirandom::qrpoint create__ *NAME* *DIM* ?ARGS? - - This command takes the following arguments: - - * string *NAME* - - The name of the command to be created \(alternatively: the *new* - subcommand will generate a unique name\) - - * integer/string *DIM* - - The number of dimensions or one of: "circle", "disk", "sphere" or "ball" - - * strings *ARGS* - - Zero or more key\-value pairs\. The supported options are: - - + *\-start index*: The index for the next point to be generated - \(default: 1\) - - + *\-evaluations number*: The number of evaluations to be used by - default \(default: 100\) - -The points that are returned lie in the hyperblock \[0,1\[^n \(n the number of -dimensions\) or on the unit circle, within the unit disk, on the unit sphere or -within the unit ball\. - -Each generator supports the following subcommands: - - - __gen next__ - - Return the coordinates of the next quasi\-random point - - - __gen set\-start__ *index* - - Reset the index for the next quasi\-random point\. This is useful to control - which list of points is returned\. Returns the new or the current value, if - no value is given\. - - - __gen set\-evaluations__ *number* - - Reset the default number of evaluations in compound algorithms\. Note that - the actual number is the smallest 4\-fold larger or equal to the given - number\. \(The 4\-fold plays a role in the detailed integration routine\.\) - - - __gen integral__ *func* *minmax* *args* - - Calculate the integral of the given function over the block \(or the circle, - sphere etc\.\) - - * string *func* - - The name of the function to be integrated - - * list *minmax* - - List of pairs of minimum and maximum coordinates\. This can be used to - map the quasi\-random coordinates to the desired hyper\-block\. - - If the space is a circle, disk etc\. then this argument should be a - single value, the radius\. The circle, disk, etc\. is centred at the - origin\. If this is not what is required, then a coordinate - transformation should be made within the function\. - - * strings *args* - - Zero or more key\-value pairs\. The following options are supported: - - + *\-evaluations number*: The number of evaluations to be used\. If - not specified use the default of the generator object\. - -# TODO - -Implement other algorithms and variants - -Implement more unit tests\. - -Comparison to pseudo\-random numbers for integration\. - -# References - -Various algorithms exist for generating quasi\-random numbers\. The generators -created in this package are based on: -[http://extremelearning\.com\.au/unreasonable\-effectiveness\-of\-quasirandom\-sequences/](http://extremelearning\.com\.au/unreasonable\-effectiveness\-of\-quasirandom\-sequences/) - -# KEYWORDS - -[mathematics](\.\./\.\./\.\./\.\./index\.md\#mathematics), -[quasi\-random](\.\./\.\./\.\./\.\./index\.md\#quasi\_random) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/rational_funcs.md Index: embedded/md/tcllib/files/modules/math/rational_funcs.md ================================================================== --- embedded/md/tcllib/files/modules/math/rational_funcs.md +++ embedded/md/tcllib/files/modules/math/rational_funcs.md @@ -1,227 +0,0 @@ - -[//000000001]: # (math::rationalfunctions \- Math) -[//000000002]: # (Generated from file 'rational\_funcs\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Arjen Markus ) -[//000000004]: # (math::rationalfunctions\(n\) 1\.0\.1 tcllib "Math") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::rationalfunctions \- Polynomial functions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [REMARKS ON THE IMPLEMENTATION](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require math::rationalfunctions ?1\.0\.1? - -[__::math::rationalfunctions::rationalFunction__ *num* *den*](#1) -[__::math::rationalfunctions::ratioCmd__ *num* *den*](#2) -[__::math::rationalfunctions::evalRatio__ *rational* *x*](#3) -[__::math::rationalfunctions::addRatio__ *ratio1* *ratio2*](#4) -[__::math::rationalfunctions::subRatio__ *ratio1* *ratio2*](#5) -[__::math::rationalfunctions::multRatio__ *ratio1* *ratio2*](#6) -[__::math::rationalfunctions::divRatio__ *ratio1* *ratio2*](#7) -[__::math::rationalfunctions::derivPolyn__ *ratio*](#8) -[__::math::rationalfunctions::coeffsNumerator__ *ratio*](#9) -[__::math::rationalfunctions::coeffsDenominator__ *ratio*](#10) - -# DESCRIPTION - -This package deals with rational functions of one variable: - - - the basic arithmetic operations are extended to rational functions - - - computing the derivatives of these functions - - - evaluation through a general procedure or via specific procedures\) - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::rationalfunctions::rationalFunction__ *num* *den* - - Return an \(encoded\) list that defines the rational function\. A rational - function - - 1 + x^3 - f(x) = ------------ - 1 + 2x + x^2 - - can be defined via: - - set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1] [list 1 2 1]] - - * list *num* - - Coefficients of the numerator of the rational function \(in ascending - order\) - - * list *den* - - Coefficients of the denominator of the rational function \(in ascending - order\) - - - __::math::rationalfunctions::ratioCmd__ *num* *den* - - Create a new procedure that evaluates the rational function\. The name of the - function is automatically generated\. Useful if you need to evaluate the - function many times, as the procedure consists of a single \[expr\] command\. - - * list *num* - - Coefficients of the numerator of the rational function \(in ascending - order\) - - * list *den* - - Coefficients of the denominator of the rational function \(in ascending - order\) - - - __::math::rationalfunctions::evalRatio__ *rational* *x* - - Evaluate the rational function at x\. - - * list *rational* - - The rational function's definition \(as returned by the rationalFunction - command\)\. order\) - - * float *x* - - The coordinate at which to evaluate the function - - - __::math::rationalfunctions::addRatio__ *ratio1* *ratio2* - - Return a new rational function which is the sum of the two others\. - - * list *ratio1* - - The first rational function operand - - * list *ratio2* - - The second rational function operand - - - __::math::rationalfunctions::subRatio__ *ratio1* *ratio2* - - Return a new rational function which is the difference of the two others\. - - * list *ratio1* - - The first rational function operand - - * list *ratio2* - - The second rational function operand - - - __::math::rationalfunctions::multRatio__ *ratio1* *ratio2* - - Return a new rational function which is the product of the two others\. If - one of the arguments is a scalar value, the other rational function is - simply scaled\. - - * list *ratio1* - - The first rational function operand or a scalar - - * list *ratio2* - - The second rational function operand or a scalar - - - __::math::rationalfunctions::divRatio__ *ratio1* *ratio2* - - Divide the first rational function by the second rational function and - return the result\. The remainder is dropped - - * list *ratio1* - - The first rational function operand - - * list *ratio2* - - The second rational function operand - - - __::math::rationalfunctions::derivPolyn__ *ratio* - - Differentiate the rational function and return the result\. - - * list *ratio* - - The rational function to be differentiated - - - __::math::rationalfunctions::coeffsNumerator__ *ratio* - - Return the coefficients of the numerator of the rational function\. - - * list *ratio* - - The rational function to be examined - - - __::math::rationalfunctions::coeffsDenominator__ *ratio* - - Return the coefficients of the denominator of the rational function\. - - * list *ratio* - - The rational function to be examined - -# REMARKS ON THE IMPLEMENTATION - -The implementation of the rational functions relies on the math::polynomials -package\. For further remarks see the documentation on that package\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: rationalfunctions* -of the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), [rational -functions](\.\./\.\./\.\./\.\./index\.md\#rational\_functions) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2005 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/roman.md Index: embedded/md/tcllib/files/modules/math/roman.md ================================================================== --- embedded/md/tcllib/files/modules/math/roman.md +++ embedded/md/tcllib/files/modules/math/roman.md @@ -1,110 +0,0 @@ - -[//000000001]: # (math::roman \- Tcl Math Library) -[//000000002]: # (Generated from file 'roman\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Kenneth Green ) -[//000000004]: # (math::roman\(\) 1\.0 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::roman \- Tools for creating and manipulating roman numerals - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require math::roman ?1\.0? - -[__::math::roman::toroman__ *i*](#1) -[__::math::roman::tointeger__ *r*](#2) -[__::math::roman::sort__ *list*](#3) -[__::math::roman::expr__ *args*](#4) - -# DESCRIPTION - -__::math::roman__ is a pure\-Tcl library for converting between integers and -roman numerals\. It also provides utility functions for sorting and performing -arithmetic on roman numerals\. - -This code was originally harvested from the Tcler's wiki at -http://wiki\.tcl\.tk/1823 and as such is free for any use for any purpose\. Many -thanks to the ingeneous folk who devised these clever routines and generously -contributed them to the Tcl community\. - -While written and tested under Tcl 8\.3, I expect this library will work under -all 8\.x versions of Tcl\. - -# COMMANDS - - - __::math::roman::toroman__ *i* - - Convert an integer to roman numerals\. The result is always in upper case\. - The value zero is converted to an empty string\. - - - __::math::roman::tointeger__ *r* - - Convert a roman numeral into an integer\. - - - __::math::roman::sort__ *list* - - Sort a list of roman numerals from smallest to largest\. - - - __::math::roman::expr__ *args* - - Evaluate an expression where the operands are all roman numerals\. - -Of these commands both *toroman* and *tointeger* are exported for easier -use\. The other two are not, as they could interfer or be confused with existing -Tcl commands\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: roman* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[integer](\.\./\.\./\.\./\.\./index\.md\#integer), [roman -numeral](\.\./\.\./\.\./\.\./index\.md\#roman\_numeral) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2005 Kenneth Green DELETED embedded/md/tcllib/files/modules/math/romberg.md Index: embedded/md/tcllib/files/modules/math/romberg.md ================================================================== --- embedded/md/tcllib/files/modules/math/romberg.md +++ embedded/md/tcllib/files/modules/math/romberg.md @@ -1,345 +0,0 @@ - -[//000000001]: # (math::calculus::romberg \- Tcl Math Library) -[//000000002]: # (Generated from file 'romberg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Kevin B\. Kenny \. All rights reserved\. Redistribution permitted under the terms of the Open Publication License ) -[//000000004]: # (math::calculus::romberg\(n\) 0\.6 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::calculus::romberg \- Romberg integration - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [PARAMETERS](#section3) - - - [OPTIONS](#section4) - - - [DESCRIPTION](#section5) - - - [IMPROPER INTEGRALS](#section6) - - - [OTHER CHANGES OF VARIABLE](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require math::calculus 0\.6 - -[__::math::calculus::romberg__ *f* *a* *b* ?*\-option value*\.\.\.?](#1) -[__::math::calculus::romberg\_infinity__ *f* *a* *b* ?*\-option value*\.\.\.?](#2) -[__::math::calculus::romberg\_sqrtSingLower__ *f* *a* *b* ?*\-option value*\.\.\.?](#3) -[__::math::calculus::romberg\_sqrtSingUpper__ *f* *a* *b* ?*\-option value*\.\.\.?](#4) -[__::math::calculus::romberg\_powerLawLower__ *gamma* *f* *a* *b* ?*\-option value*\.\.\.?](#5) -[__::math::calculus::romberg\_powerLawUpper__ *gamma* *f* *a* *b* ?*\-option value*\.\.\.?](#6) -[__::math::calculus::romberg\_expLower__ *f* *a* *b* ?*\-option value*\.\.\.?](#7) -[__::math::calculus::romberg\_expUpper__ *f* *a* *b* ?*\-option value*\.\.\.?](#8) - -# DESCRIPTION - -The __romberg__ procedures in the __[math::calculus](calculus\.md)__ -package perform numerical integration of a function of one variable\. They are -intended to be of "production quality" in that they are robust, precise, and -reasonably efficient in terms of the number of function evaluations\. - -# PROCEDURES - -The following procedures are available for Romberg integration: - - - __::math::calculus::romberg__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates an analytic function over a given interval\. - - - __::math::calculus::romberg\_infinity__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates an analytic function over a half\-infinite interval\. - - - __::math::calculus::romberg\_sqrtSingLower__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates a function that is expected to be analytic over an interval - except for the presence of an inverse square root singularity at the lower - limit\. - - - __::math::calculus::romberg\_sqrtSingUpper__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates a function that is expected to be analytic over an interval - except for the presence of an inverse square root singularity at the upper - limit\. - - - __::math::calculus::romberg\_powerLawLower__ *gamma* *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates a function that is expected to be analytic over an interval - except for the presence of a power law singularity at the lower limit\. - - - __::math::calculus::romberg\_powerLawUpper__ *gamma* *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates a function that is expected to be analytic over an interval - except for the presence of a power law singularity at the upper limit\. - - - __::math::calculus::romberg\_expLower__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates an exponentially growing function; the lower limit of the region - of integration may be arbitrarily large and negative\. - - - __::math::calculus::romberg\_expUpper__ *f* *a* *b* ?*\-option value*\.\.\.? - - Integrates an exponentially decaying function; the upper limit of the region - of integration may be arbitrarily large\. - -# PARAMETERS - - - *f* - - Function to integrate\. Must be expressed as a single Tcl command, to which - will be appended a single argument, specifically, the abscissa at which the - function is to be evaluated\. The first word of the command will be processed - with __namespace which__ in the caller's scope prior to any evaluation\. - Given this processing, the command may local to the calling namespace rather - than needing to be global\. - - - *a* - - Lower limit of the region of integration\. - - - *b* - - Upper limit of the region of integration\. For the - __romberg\_sqrtSingLower__, __romberg\_sqrtSingUpper__, - __romberg\_powerLawLower__, __romberg\_powerLawUpper__, - __romberg\_expLower__, and __romberg\_expUpper__ procedures, the lower - limit must be strictly less than the upper\. For the other procedures, the - limits may appear in either order\. - - - *gamma* - - Power to use for a power law singularity; see section [IMPROPER - INTEGRALS](#section6) for details\. - -# OPTIONS - - - __\-abserror__ *epsilon* - - Requests that the integration machinery proceed at most until the estimated - absolute error of the integral is less than *epsilon*\. The error may be - seriously over\- or underestimated if the function \(or any of its - derivatives\) contains singularities; see section [IMPROPER - INTEGRALS](#section6) for details\. Default is 1\.0e\-08\. - - - __\-relerror__ *epsilon* - - Requests that the integration machinery proceed at most until the estimated - relative error of the integral is less than *epsilon*\. The error may be - seriously over\- or underestimated if the function \(or any of its - derivatives\) contains singularities; see section [IMPROPER - INTEGRALS](#section6) for details\. Default is 1\.0e\-06\. - - - __\-maxiter__ *m* - - Requests that integration terminate after at most *n* triplings of the - number of evaluations performed\. In other words, given *n* for - __\-maxiter__, the integration machinery will make at most 3\*\**n* - evaluations of the function\. Default is 14, corresponding to a limit - approximately 4\.8 million evaluations\. \(Well\-behaved functions will seldom - require more than a few hundred evaluations\.\) - - - __\-degree__ *d* - - Requests that an extrapolating polynomial of degree *d* be used in Romberg - integration; see section [DESCRIPTION](#section5) for details\. Default - is 4\. Can be at most *m*\-1\. - -# DESCRIPTION - -The __romberg__ procedure performs Romberg integration using the modified -midpoint rule\. Romberg integration is an iterative process\. At the first step, -the function is evaluated at the midpoint of the region of integration, and the -value is multiplied by the width of the interval for the coarsest possible -estimate\. At the second step, the interval is divided into three parts, and the -function is evaluated at the midpoint of each part; the sum of the values is -multiplied by three\. At the third step, nine parts are used, at the fourth -twenty\-seven, and so on, tripling the number of subdivisions at each step\. - -Once the interval has been divided at least *d* times, a polynomial is fitted -to the integrals estimated in the last *d*\+1 divisions\. The integrals are -considered to be a function of the square of the width of the subintervals \(any -good numerical analysis text will discuss this process under "Romberg -integration"\)\. The polynomial is extrapolated to a step size of zero, computing -a value for the integral and an estimate of the error\. - -This process will be well\-behaved only if the function is analytic over the -region of integration; there may be removable singularities at either end of the -region provided that the limit of the function \(and of all its derivatives\) -exists as the ends are approached\. Thus, __romberg__ may be used to -integrate a function like f\(x\)=sin\(x\)/x over an interval beginning or ending at -zero\. - -Note that __romberg__ will either fail to converge or else return incorrect -error estimates if the function, or any of its derivatives, has a singularity -anywhere in the region of integration \(except for the case mentioned above\)\. -Care must be used, therefore, in integrating a function like 1/\(1\-x\*\*2\) to avoid -the places where the derivative is singular\. - -# IMPROPER INTEGRALS - -Romberg integration is also useful for integrating functions over half\-infinite -intervals or functions that have singularities\. The trick is to make a change of -variable to eliminate the singularity, and to put the singularity at one end or -the other of the region of integration\. The -__[math::calculus](calculus\.md)__ package supplies a number of -__romberg__ procedures to deal with the commoner cases\. - - - __romberg\_infinity__ - - Integrates a function over a half\-infinite interval; either *a* or *b* - may be infinite\. *a* and *b* must be of the same sign; if you need to - integrate across the axis, say, from a negative value to positive infinity, - use __romberg__ to integrate from the negative value to a small positive - value, and then __romberg\_infinity__ to integrate from the positive - value to positive infinity\. The __romberg\_infinity__ procedure works by - making the change of variable u=1/x, so that the integral from a to b of - f\(x\) is evaluated as the integral from 1/a to 1/b of f\(1/u\)/u\*\*2\. - - - __romberg\_powerLawLower__ and __romberg\_powerLawUpper__ - - Integrate a function that has an integrable power law singularity at either - the lower or upper bound of the region of integration \(or has a derivative - with a power law singularity there\)\. These procedures take a first - parameter, *gamma*, which gives the power law\. The function or its first - derivative are presumed to diverge as \(x\-*a*\)\*\*\(\-*gamma*\) or - \(*b*\-x\)\*\*\(\-*gamma*\)\. *gamma* must be greater than zero and less than - 1\. - - These procedures are useful not only in integrating functions that go to - infinity at one end of the region of integration, but also functions whose - derivatives do not exist at the end of the region\. For instance, integrating - f\(x\)=pow\(x,0\.25\) with the origin as one end of the region will result in the - __romberg__ procedure greatly underestimating the error in the integral\. - The problem can be fixed by observing that the first derivative of f\(x\), - f'\(x\)=x\*\*\(\-3/4\)/4, goes to infinity at the origin\. Integrating using - __romberg\_powerLawLower__ with *gamma* set to 0\.75 gives much more - orderly convergence\. - - These procedures operate by making the change of variable u=\(x\-a\)\*\*\(1\-gamma\) - \(__romberg\_powerLawLower__\) or u=\(b\-x\)\*\*\(1\-gamma\) - \(__romberg\_powerLawUpper__\)\. - - To summarize the meaning of gamma: - - * If f\(x\) ~ x\*\*\(\-a\) \(0 < a < 1\), use gamma = a - - * If f'\(x\) ~ x\*\*\(\-b\) \(0 < b < 1\), use gamma = b - - - __romberg\_sqrtSingLower__ and __romberg\_sqrtSingUpper__ - - These procedures behave identically to __romberg\_powerLawLower__ and - __romberg\_powerLawUpper__ for the common case of *gamma*=0\.5; that is, - they integrate a function with an inverse square root singularity at one end - of the interval\. They have a simpler implementation involving square roots - rather than arbitrary powers\. - - - __romberg\_expLower__ and __romberg\_expUpper__ - - These procedures are for integrating a function that grows or decreases - exponentially over a half\-infinite interval\. __romberg\_expLower__ - handles exponentially growing functions, and allows the lower limit of - integration to be an arbitrarily large negative number\. - __romberg\_expUpper__ handles exponentially decaying functions and allows - the upper limit of integration to be an arbitrary large positive number\. The - functions make the change of variable u=exp\(\-x\) and u=exp\(x\) respectively\. - -# OTHER CHANGES OF VARIABLE - -If you need an improper integral other than the ones listed here, a change of -variable can be written in very few lines of Tcl\. Because the Tcl coding that -does it is somewhat arcane, we offer a worked example here\. - -Let's say that the function that we want to integrate is f\(x\)=exp\(x\)/sqrt\(1\-x\*x\) -\(not a very natural function, but a good example\), and we want to integrate it -over the interval \(\-1,1\)\. The denominator falls to zero at both ends of the -interval\. We wish to make a change of variable from x to u so that -dx/sqrt\(1\-x\*\*2\) maps to du\. Choosing x=sin\(u\), we can find that dx=cos\(u\)\*du, -and sqrt\(1\-x\*\*2\)=cos\(u\)\. The integral from a to b of f\(x\) is the integral from -asin\(a\) to asin\(b\) of f\(sin\(u\)\)\*cos\(u\)\. - -We can make a function __g__ that accepts an arbitrary function __f__ -and the parameter u, and computes this new integrand\. - - proc g { f u } { - set x [expr { sin($u) }] - set cmd $f; lappend cmd $x; set y [eval $cmd] - return [expr { $y / cos($u) }] - } - -Now integrating __f__ from *a* to *b* is the same as integrating -__g__ from *asin\(a\)* to *asin\(b\)*\. It's a little tricky to get __f__ -consistently evaluated in the caller's scope; the following procedure does it\. - - proc romberg_sine { f a b args } { - set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]] - set f [list g $f] - return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]] - } - -This __romberg\_sine__ procedure will do any function with sqrt\(1\-x\*x\) in the -denominator\. Our sample function is f\(x\)=exp\(x\)/sqrt\(1\-x\*x\): - - proc f { x } { - expr { exp($x) / sqrt( 1. - $x*$x ) } - } - -Integrating it is a matter of applying __romberg\_sine__ as we would any of -the other __romberg__ procedures: - - foreach { value error } [romberg_sine f -1.0 1.0] break - puts [format "integral is %.6g +/- %.6g" $value $error] - - integral is 3.97746 +/- 2.3557e-010 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: calculus* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[math::calculus](calculus\.md), [math::interpolate](interpolate\.md) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Kevin B\. Kenny \. All rights reserved\. Redistribution permitted under the terms of the Open Publication License DELETED embedded/md/tcllib/files/modules/math/special.md Index: embedded/md/tcllib/files/modules/math/special.md ================================================================== --- embedded/md/tcllib/files/modules/math/special.md +++ embedded/md/tcllib/files/modules/math/special.md @@ -1,595 +0,0 @@ - -[//000000001]: # (math::special \- Tcl Math Library) -[//000000002]: # (Generated from file 'special\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (math::special\(n\) 0\.4 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::special \- Special mathematical functions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [PROCEDURES](#section3) - - - [THE ORTHOGONAL POLYNOMIALS](#section4) - - - [REMARKS ON THE IMPLEMENTATION](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.5? -package require math::special ?0\.5? - -[__::math::special::eulerNumber__ *index*](#1) -[__::math::special::bernoulliNumber__ *index*](#2) -[__::math::special::Beta__ *x* *y*](#3) -[__::math::special::incBeta__ *a* *b* *x*](#4) -[__::math::special::regIncBeta__ *a* *b* *x*](#5) -[__::math::special::Gamma__ *x*](#6) -[__::math::special::digamma__ *x*](#7) -[__::math::special::erf__ *x*](#8) -[__::math::special::erfc__ *x*](#9) -[__::math::special::invnorm__ *p*](#10) -[__::math::special::J0__ *x*](#11) -[__::math::special::J1__ *x*](#12) -[__::math::special::Jn__ *n* *x*](#13) -[__::math::special::J1/2__ *x*](#14) -[__::math::special::J\-1/2__ *x*](#15) -[__::math::special::I\_n__ *x*](#16) -[__::math::special::cn__ *u* *k*](#17) -[__::math::special::dn__ *u* *k*](#18) -[__::math::special::sn__ *u* *k*](#19) -[__::math::special::elliptic\_K__ *k*](#20) -[__::math::special::elliptic\_E__ *k*](#21) -[__::math::special::exponential\_Ei__ *x*](#22) -[__::math::special::exponential\_En__ *n* *x*](#23) -[__::math::special::exponential\_li__ *x*](#24) -[__::math::special::exponential\_Ci__ *x*](#25) -[__::math::special::exponential\_Si__ *x*](#26) -[__::math::special::exponential\_Chi__ *x*](#27) -[__::math::special::exponential\_Shi__ *x*](#28) -[__::math::special::fresnel\_C__ *x*](#29) -[__::math::special::fresnel\_S__ *x*](#30) -[__::math::special::sinc__ *x*](#31) -[__::math::special::legendre__ *n*](#32) -[__::math::special::chebyshev__ *n*](#33) -[__::math::special::laguerre__ *alpha* *n*](#34) -[__::math::special::hermite__ *n*](#35) - -# DESCRIPTION - -This package implements several so\-called special functions, like the Gamma -function, the Bessel functions and such\. - -Each function is implemented by a procedure that bears its name \(well, in close -approximation\): - - - J0 for the zeroth\-order Bessel function of the first kind - - - J1 for the first\-order Bessel function of the first kind - - - Jn for the nth\-order Bessel function of the first kind - - - J1/2 for the half\-order Bessel function of the first kind - - - J\-1/2 for the minus\-half\-order Bessel function of the first kind - - - I\_n for the modified Bessel function of the first kind of order n - - - Gamma for the Gamma function, erf and erfc for the error function and the - complementary error function - - - fresnel\_C and fresnel\_S for the Fresnel integrals - - - elliptic\_K and elliptic\_E \(complete elliptic integrals\) - - - exponent\_Ei and other functions related to the so\-called exponential - integrals - - - legendre, hermite: some of the classical orthogonal polynomials\. - -# OVERVIEW - -In the following table several characteristics of the functions in this package -are summarized: the domain for the argument, the values for the parameters and -error bounds\. - - Family | Function | Domain x | Parameter | Error bound - -------------+-------------+-------------+-------------+-------------- - Bessel | J0, J1, | all of R | n = integer | < 1.0e-8 - | Jn | | | (|x|<20, n<20) - Bessel | J1/2, J-1/2,| x > 0 | n = integer | exact - Bessel | I_n | all of R | n = integer | < 1.0e-6 - | | | | - Elliptic | cn | 0 <= x <= 1 | -- | < 1.0e-10 - functions | dn | 0 <= x <= 1 | -- | < 1.0e-10 - | sn | 0 <= x <= 1 | -- | < 1.0e-10 - Elliptic | K | 0 <= x < 1 | -- | < 1.0e-6 - integrals | E | 0 <= x < 1 | -- | < 1.0e-6 - | | | | - Error | erf | | -- | - functions | erfc | | | - | | | | - Inverse | invnorm | 0 < x < 1 | -- | < 1.2e-9 - normal | | | | - distribution | | | | - | | | | - Exponential | Ei | x != 0 | -- | < 1.0e-10 (relative) - integrals | En | x > 0 | -- | as Ei - | li | x > 0 | -- | as Ei - | Chi | x > 0 | -- | < 1.0e-8 - | Shi | x > 0 | -- | < 1.0e-8 - | Ci | x > 0 | -- | < 2.0e-4 - | Si | x > 0 | -- | < 2.0e-4 - | | | | - Fresnel | C | all of R | -- | < 2.0e-3 - integrals | S | all of R | -- | < 2.0e-3 - | | | | - general | Beta | (see Gamma) | -- | < 1.0e-9 - | Gamma | x != 0,-1, | -- | < 1.0e-9 - | | -2, ... | | - | incBeta | | a, b > 0 | < 1.0e-9 - | regIncBeta | | a, b > 0 | < 1.0e-9 - | digamma | x != 0,-1 | | < 1.0e-9 - | | -2, ... | | - | | | | - | sinc | all of R | -- | exact - | | | | - orthogonal | Legendre | all of R | n = 0,1,... | exact - polynomials | Chebyshev | all of R | n = 0,1,... | exact - | Laguerre | all of R | n = 0,1,... | exact - | | | alpha el. R | - | Hermite | all of R | n = 0,1,... | exact - -*Note:* Some of the error bounds are estimated, as no "formal" bounds were -available with the implemented approximation method, others hold for the -auxiliary functions used for estimating the primary functions\. - -The following well\-known functions are currently missing from the package: - - - Bessel functions of the second kind \(Y\_n, K\_n\) - - - Bessel functions of arbitrary order \(and hence the Airy functions\) - - - Chebyshev polynomials of the second kind \(U\_n\) - - - The incomplete gamma function - -# PROCEDURES - -The package defines the following public procedures: - - - __::math::special::eulerNumber__ *index* - - Return the index'th Euler number \(note: these are integer values\)\. As the - size of these numbers grows very fast, only a limited number are available\. - - * int *index* - - Index of the number to be returned \(should be between 0 and 54\) - - - __::math::special::bernoulliNumber__ *index* - - Return the index'th Bernoulli number\. As the size of the numbers grows very - fast, only a limited number are available\. - - * int *index* - - Index of the number to be returned \(should be between 0 and 52\) - - - __::math::special::Beta__ *x* *y* - - Compute the Beta function for arguments "x" and "y" - - * float *x* - - First argument for the Beta function - - * float *y* - - Second argument for the Beta function - - - __::math::special::incBeta__ *a* *b* *x* - - Compute the incomplete Beta function for argument "x" with parameters "a" - and "b" - - * float *a* - - First parameter for the incomplete Beta function, a > 0 - - * float *b* - - Second parameter for the incomplete Beta function, b > 0 - - * float *x* - - Argument for the incomplete Beta function - - - __::math::special::regIncBeta__ *a* *b* *x* - - Compute the regularized incomplete Beta function for argument "x" with - parameters "a" and "b" - - * float *a* - - First parameter for the incomplete Beta function, a > 0 - - * float *b* - - Second parameter for the incomplete Beta function, b > 0 - - * float *x* - - Argument for the regularized incomplete Beta function - - - __::math::special::Gamma__ *x* - - Compute the Gamma function for argument "x" - - * float *x* - - Argument for the Gamma function - - - __::math::special::digamma__ *x* - - Compute the digamma function \(psi\) for argument "x" - - * float *x* - - Argument for the digamma function - - - __::math::special::erf__ *x* - - Compute the error function for argument "x" - - * float *x* - - Argument for the error function - - - __::math::special::erfc__ *x* - - Compute the complementary error function for argument "x" - - * float *x* - - Argument for the complementary error function - - - __::math::special::invnorm__ *p* - - Compute the inverse of the normal distribution function for argument "p" - - * float *p* - - Argument for the inverse normal distribution function \(p must be greater - than 0 and lower than 1\) - - - __::math::special::J0__ *x* - - Compute the zeroth\-order Bessel function of the first kind for the argument - "x" - - * float *x* - - Argument for the Bessel function - - - __::math::special::J1__ *x* - - Compute the first\-order Bessel function of the first kind for the argument - "x" - - * float *x* - - Argument for the Bessel function - - - __::math::special::Jn__ *n* *x* - - Compute the nth\-order Bessel function of the first kind for the argument "x" - - * integer *n* - - Order of the Bessel function - - * float *x* - - Argument for the Bessel function - - - __::math::special::J1/2__ *x* - - Compute the half\-order Bessel function of the first kind for the argument - "x" - - * float *x* - - Argument for the Bessel function - - - __::math::special::J\-1/2__ *x* - - Compute the minus\-half\-order Bessel function of the first kind for the - argument "x" - - * float *x* - - Argument for the Bessel function - - - __::math::special::I\_n__ *x* - - Compute the modified Bessel function of the first kind of order n for the - argument "x" - - * int *x* - - Positive integer order of the function - - * float *x* - - Argument for the function - - - __::math::special::cn__ *u* *k* - - Compute the elliptic function *cn* for the argument "u" and parameter "k"\. - - * float *u* - - Argument for the function - - * float *k* - - Parameter - - - __::math::special::dn__ *u* *k* - - Compute the elliptic function *dn* for the argument "u" and parameter "k"\. - - * float *u* - - Argument for the function - - * float *k* - - Parameter - - - __::math::special::sn__ *u* *k* - - Compute the elliptic function *sn* for the argument "u" and parameter "k"\. - - * float *u* - - Argument for the function - - * float *k* - - Parameter - - - __::math::special::elliptic\_K__ *k* - - Compute the complete elliptic integral of the first kind for the argument - "k" - - * float *k* - - Argument for the function - - - __::math::special::elliptic\_E__ *k* - - Compute the complete elliptic integral of the second kind for the argument - "k" - - * float *k* - - Argument for the function - - - __::math::special::exponential\_Ei__ *x* - - Compute the exponential integral of the second kind for the argument "x" - - * float *x* - - Argument for the function \(x \!= 0\) - - - __::math::special::exponential\_En__ *n* *x* - - Compute the exponential integral of the first kind for the argument "x" and - order n - - * int *n* - - Order of the integral \(n >= 0\) - - * float *x* - - Argument for the function \(x >= 0\) - - - __::math::special::exponential\_li__ *x* - - Compute the logarithmic integral for the argument "x" - - * float *x* - - Argument for the function \(x > 0\) - - - __::math::special::exponential\_Ci__ *x* - - Compute the cosine integral for the argument "x" - - * float *x* - - Argument for the function \(x > 0\) - - - __::math::special::exponential\_Si__ *x* - - Compute the sine integral for the argument "x" - - * float *x* - - Argument for the function \(x > 0\) - - - __::math::special::exponential\_Chi__ *x* - - Compute the hyperbolic cosine integral for the argument "x" - - * float *x* - - Argument for the function \(x > 0\) - - - __::math::special::exponential\_Shi__ *x* - - Compute the hyperbolic sine integral for the argument "x" - - * float *x* - - Argument for the function \(x > 0\) - - - __::math::special::fresnel\_C__ *x* - - Compute the Fresnel cosine integral for real argument x - - * float *x* - - Argument for the function - - - __::math::special::fresnel\_S__ *x* - - Compute the Fresnel sine integral for real argument x - - * float *x* - - Argument for the function - - - __::math::special::sinc__ *x* - - Compute the sinc function for real argument x - - * float *x* - - Argument for the function - - - __::math::special::legendre__ *n* - - Return the Legendre polynomial of degree n \(see [THE ORTHOGONAL - POLYNOMIALS](#section4)\) - - * int *n* - - Degree of the polynomial - - - __::math::special::chebyshev__ *n* - - Return the Chebyshev polynomial of degree n \(of the first kind\) - - * int *n* - - Degree of the polynomial - - - __::math::special::laguerre__ *alpha* *n* - - Return the Laguerre polynomial of degree n with parameter alpha - - * float *alpha* - - Parameter of the Laguerre polynomial - - * int *n* - - Degree of the polynomial - - - __::math::special::hermite__ *n* - - Return the Hermite polynomial of degree n - - * int *n* - - Degree of the polynomial - -# THE ORTHOGONAL POLYNOMIALS - -For dealing with the classical families of orthogonal polynomials, the package -relies on the *math::polynomials* package\. To evaluate the polynomial at some -coordinate, use the *evalPolyn* command: - - set leg2 [::math::special::legendre 2] - puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]" - -The return value from the *legendre* and other commands is actually the -definition of the corresponding polynomial as used in that package\. - -# REMARKS ON THE IMPLEMENTATION - -It should be noted, that the actual implementation of J0 and J1 depends on -straightforward Gaussian quadrature formulas\. The \(absolute\) accuracy of the -results is of the order 1\.0e\-4 or better\. The main reason to implement them like -that was that it was fast to do \(the formulas are simple\) and the computations -are fast too\. - -The implementation of J1/2 does not suffer from this: this function can be -expressed exactly in terms of elementary functions\. - -The functions J0 and J1 are the ones you will encounter most frequently in -practice\. - -The computation of I\_n is based on Miller's algorithm for computing the minimal -function from recurrence relations\. - -The computation of the Gamma and Beta functions relies on the combinatorics -package, whereas that of the error functions relies on the statistics package\. - -The computation of the complete elliptic integrals uses the AGM algorithm\. - -Much information about these functions can be found in: - -Abramowitz and Stegun: *Handbook of Mathematical Functions* \(Dover, ISBN -486\-61272\-4\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: special* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Bessel functions](\.\./\.\./\.\./\.\./index\.md\#bessel\_functions), [error -function](\.\./\.\./\.\./\.\./index\.md\#error\_function), -[math](\.\./\.\./\.\./\.\./index\.md\#math), [special -functions](\.\./\.\./\.\./\.\./index\.md\#special\_functions) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/math/statistics.md Index: embedded/md/tcllib/files/modules/math/statistics.md ================================================================== --- embedded/md/tcllib/files/modules/math/statistics.md +++ embedded/md/tcllib/files/modules/math/statistics.md @@ -1,2571 +0,0 @@ - -[//000000001]: # (math::statistics \- Tcl Math Library) -[//000000002]: # (Generated from file 'statistics\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (math::statistics\(n\) 1 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::statistics \- Basic statistical functions and procedures - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [GENERAL PROCEDURES](#section2) - - - [MULTIVARIATE LINEAR REGRESSION](#section3) - - - [STATISTICAL DISTRIBUTIONS](#section4) - - - [DATA MANIPULATION](#section5) - - - [PLOT PROCEDURES](#section6) - - - [THINGS TO DO](#section7) - - - [EXAMPLES](#section8) - - - [Bugs, Ideas, Feedback](#section9) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require math::statistics 1 - -[__::math::statistics::mean__ *data*](#1) -[__::math::statistics::min__ *data*](#2) -[__::math::statistics::max__ *data*](#3) -[__::math::statistics::number__ *data*](#4) -[__::math::statistics::stdev__ *data*](#5) -[__::math::statistics::var__ *data*](#6) -[__::math::statistics::pstdev__ *data*](#7) -[__::math::statistics::pvar__ *data*](#8) -[__::math::statistics::median__ *data*](#9) -[__::math::statistics::basic\-stats__ *data*](#10) -[__::math::statistics::histogram__ *limits* *values* ?weights?](#11) -[__::math::statistics::histogram\-alt__ *limits* *values* ?weights?](#12) -[__::math::statistics::corr__ *data1* *data2*](#13) -[__::math::statistics::interval\-mean\-stdev__ *data* *confidence*](#14) -[__::math::statistics::t\-test\-mean__ *data* *est\_mean* *est\_stdev* *alpha*](#15) -[__::math::statistics::test\-normal__ *data* *significance*](#16) -[__::math::statistics::lillieforsFit__ *data*](#17) -[__::math::statistics::test\-Duckworth__ *list1* *list2* *significance*](#18) -[__::math::statistics::test\-anova\-F__ *alpha* *args*](#19) -[__::math::statistics::test\-Tukey\-range__ *alpha* *args*](#20) -[__::math::statistics::test\-Dunnett__ *alpha* *control* *args*](#21) -[__::math::statistics::quantiles__ *data* *confidence*](#22) -[__::math::statistics::quantiles__ *limits* *counts* *confidence*](#23) -[__::math::statistics::autocorr__ *data*](#24) -[__::math::statistics::crosscorr__ *data1* *data2*](#25) -[__::math::statistics::mean\-histogram\-limits__ *mean* *stdev* *number*](#26) -[__::math::statistics::minmax\-histogram\-limits__ *min* *max* *number*](#27) -[__::math::statistics::linear\-model__ *xdata* *ydata* *intercept*](#28) -[__::math::statistics::linear\-residuals__ *xdata* *ydata* *intercept*](#29) -[__::math::statistics::test\-2x2__ *n11* *n21* *n12* *n22*](#30) -[__::math::statistics::print\-2x2__ *n11* *n21* *n12* *n22*](#31) -[__::math::statistics::control\-xbar__ *data* ?nsamples?](#32) -[__::math::statistics::control\-Rchart__ *data* ?nsamples?](#33) -[__::math::statistics::test\-xbar__ *control* *data*](#34) -[__::math::statistics::test\-Rchart__ *control* *data*](#35) -[__::math::statistics::test\-Kruskal\-Wallis__ *confidence* *args*](#36) -[__::math::statistics::analyse\-Kruskal\-Wallis__ *args*](#37) -[__::math::statistics::test\-Levene__ *groups*](#38) -[__::math::statistics::test\-Brown\-Forsythe__ *groups*](#39) -[__::math::statistics::group\-rank__ *args*](#40) -[__::math::statistics::test\-Wilcoxon__ *sample\_a* *sample\_b*](#41) -[__::math::statistics::spearman\-rank__ *sample\_a* *sample\_b*](#42) -[__::math::statistics::spearman\-rank\-extended__ *sample\_a* *sample\_b*](#43) -[__::math::statistics::kernel\-density__ *data* opt *\-option value* \.\.\.](#44) -[__::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples?](#45) -[__::math::statistics::wasserstein\-distance__ *prob1* *prob2*](#46) -[__::math::statistics::kl\-divergence__ *prob1* *prob2*](#47) -[__::math::statistics::logistic\-model__ *xdata* *ydata*](#48) -[__::math::statistics::logistic\-probability__ *coeffs* *x*](#49) -[__::math::statistics::tstat__ *dof* ?alpha?](#50) -[__::math::statistics::mv\-wls__ *wt1* *weights\_and\_values*](#51) -[__::math::statistics::mv\-ols__ *values*](#52) -[__::math::statistics::pdf\-normal__ *mean* *stdev* *value*](#53) -[__::math::statistics::pdf\-lognormal__ *mean* *stdev* *value*](#54) -[__::math::statistics::pdf\-exponential__ *mean* *value*](#55) -[__::math::statistics::pdf\-uniform__ *xmin* *xmax* *value*](#56) -[__::math::statistics::pdf\-triangular__ *xmin* *xmax* *value*](#57) -[__::math::statistics::pdf\-symmetric\-triangular__ *xmin* *xmax* *value*](#58) -[__::math::statistics::pdf\-gamma__ *alpha* *beta* *value*](#59) -[__::math::statistics::pdf\-poisson__ *mu* *k*](#60) -[__::math::statistics::pdf\-chisquare__ *df* *value*](#61) -[__::math::statistics::pdf\-student\-t__ *df* *value*](#62) -[__::math::statistics::pdf\-gamma__ *a* *b* *value*](#63) -[__::math::statistics::pdf\-beta__ *a* *b* *value*](#64) -[__::math::statistics::pdf\-weibull__ *scale* *shape* *value*](#65) -[__::math::statistics::pdf\-gumbel__ *location* *scale* *value*](#66) -[__::math::statistics::pdf\-pareto__ *scale* *shape* *value*](#67) -[__::math::statistics::pdf\-cauchy__ *location* *scale* *value*](#68) -[__::math::statistics::pdf\-laplace__ *location* *scale* *value*](#69) -[__::math::statistics::pdf\-kumaraswamy__ *a* *b* *value*](#70) -[__::math::statistics::pdf\-negative\-binomial__ *r* *p* *value*](#71) -[__::math::statistics::cdf\-normal__ *mean* *stdev* *value*](#72) -[__::math::statistics::cdf\-lognormal__ *mean* *stdev* *value*](#73) -[__::math::statistics::cdf\-exponential__ *mean* *value*](#74) -[__::math::statistics::cdf\-uniform__ *xmin* *xmax* *value*](#75) -[__::math::statistics::cdf\-triangular__ *xmin* *xmax* *value*](#76) -[__::math::statistics::cdf\-symmetric\-triangular__ *xmin* *xmax* *value*](#77) -[__::math::statistics::cdf\-students\-t__ *degrees* *value*](#78) -[__::math::statistics::cdf\-gamma__ *alpha* *beta* *value*](#79) -[__::math::statistics::cdf\-poisson__ *mu* *k*](#80) -[__::math::statistics::cdf\-beta__ *a* *b* *value*](#81) -[__::math::statistics::cdf\-weibull__ *scale* *shape* *value*](#82) -[__::math::statistics::cdf\-gumbel__ *location* *scale* *value*](#83) -[__::math::statistics::cdf\-pareto__ *scale* *shape* *value*](#84) -[__::math::statistics::cdf\-cauchy__ *location* *scale* *value*](#85) -[__::math::statistics::cdf\-F__ *nf1* *nf2* *value*](#86) -[__::math::statistics::cdf\-laplace__ *location* *scale* *value*](#87) -[__::math::statistics::cdf\-kumaraswamy__ *a* *b* *value*](#88) -[__::math::statistics::cdf\-negative\-binomial__ *r* *p* *value*](#89) -[__::math::statistics::empirical\-distribution__ *values*](#90) -[__::math::statistics::random\-normal__ *mean* *stdev* *number*](#91) -[__::math::statistics::random\-lognormal__ *mean* *stdev* *number*](#92) -[__::math::statistics::random\-exponential__ *mean* *number*](#93) -[__::math::statistics::random\-uniform__ *xmin* *xmax* *number*](#94) -[__::math::statistics::random\-triangular__ *xmin* *xmax* *number*](#95) -[__::math::statistics::random\-symmetric\-triangular__ *xmin* *xmax* *number*](#96) -[__::math::statistics::random\-gamma__ *alpha* *beta* *number*](#97) -[__::math::statistics::random\-poisson__ *mu* *number*](#98) -[__::math::statistics::random\-chisquare__ *df* *number*](#99) -[__::math::statistics::random\-student\-t__ *df* *number*](#100) -[__::math::statistics::random\-beta__ *a* *b* *number*](#101) -[__::math::statistics::random\-weibull__ *scale* *shape* *number*](#102) -[__::math::statistics::random\-gumbel__ *location* *scale* *number*](#103) -[__::math::statistics::random\-pareto__ *scale* *shape* *number*](#104) -[__::math::statistics::random\-cauchy__ *location* *scale* *number*](#105) -[__::math::statistics::random\-laplace__ *location* *scale* *number*](#106) -[__::math::statistics::random\-kumaraswamy__ *a* *b* *number*](#107) -[__::math::statistics::random\-negative\-binomial__ *r* *p* *number*](#108) -[__::math::statistics::histogram\-uniform__ *xmin* *xmax* *limits* *number*](#109) -[__::math::statistics::incompleteGamma__ *x* *p* ?tol?](#110) -[__::math::statistics::incompleteBeta__ *a* *b* *x* ?tol?](#111) -[__::math::statistics::estimate\-pareto__ *values*](#112) -[__::math::statistics::estimate\-exponential__ *values*](#113) -[__::math::statistics::estimate\-laplace__ *values*](#114) -[__::math::statistics::estimante\-negative\-binomial__ *r* *values*](#115) -[__::math::statistics::filter__ *varname* *data* *expression*](#116) -[__::math::statistics::map__ *varname* *data* *expression*](#117) -[__::math::statistics::samplescount__ *varname* *list* *expression*](#118) -[__::math::statistics::subdivide__](#119) -[__::math::statistics::plot\-scale__ *canvas* *xmin* *xmax* *ymin* *ymax*](#120) -[__::math::statistics::plot\-xydata__ *canvas* *xdata* *ydata* *tag*](#121) -[__::math::statistics::plot\-xyline__ *canvas* *xdata* *ydata* *tag*](#122) -[__::math::statistics::plot\-tdata__ *canvas* *tdata* *tag*](#123) -[__::math::statistics::plot\-tline__ *canvas* *tdata* *tag*](#124) -[__::math::statistics::plot\-histogram__ *canvas* *counts* *limits* *tag*](#125) - -# DESCRIPTION - -The __math::statistics__ package contains functions and procedures for basic -statistical data analysis, such as: - - - Descriptive statistical parameters \(mean, minimum, maximum, standard - deviation\) - - - Estimates of the distribution in the form of histograms and quantiles - - - Basic testing of hypotheses - - - Probability and cumulative density functions - -It is meant to help in developing data analysis applications or doing ad hoc -data analysis, it is not in itself a full application, nor is it intended to -rival with full \(non\-\)commercial statistical packages\. - -The purpose of this document is to describe the implemented procedures and -provide some examples of their usage\. As there is ample literature on the -algorithms involved, we refer to relevant text books for more explanations\. The -package contains a fairly large number of public procedures\. They can be -distinguished in three sets: general procedures, procedures that deal with -specific statistical distributions, list procedures to select or transform data -and simple plotting procedures \(these require Tk\)\. *Note:* The data that need -to be analyzed are always contained in a simple list\. Missing values are -represented as empty list elements\. *Note:* With version 1\.0\.1 a mistake in -the procs *pdf\-lognormal*, *cdf\-lognormal* and *random\-lognormal* has been -corrected\. In previous versions the argument for the standard deviation was -actually used as if it was the variance\. - -# GENERAL PROCEDURES - -The general statistical procedures are: - - - __::math::statistics::mean__ *data* - - Determine the *mean* value of the given list of data\. - - * list *data* - - \- List of data - - - __::math::statistics::min__ *data* - - Determine the *[minimum](\.\./\.\./\.\./\.\./index\.md\#minimum)* value of the - given list of data\. - - * list *data* - - \- List of data - - - __::math::statistics::max__ *data* - - Determine the *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* value of the - given list of data\. - - * list *data* - - \- List of data - - - __::math::statistics::number__ *data* - - Determine the *number* of non\-missing data in the given list - - * list *data* - - \- List of data - - - __::math::statistics::stdev__ *data* - - Determine the *sample standard deviation* of the data in the given list - - * list *data* - - \- List of data - - - __::math::statistics::var__ *data* - - Determine the *sample variance* of the data in the given list - - * list *data* - - \- List of data - - - __::math::statistics::pstdev__ *data* - - Determine the *population standard deviation* of the data in the given - list - - * list *data* - - \- List of data - - - __::math::statistics::pvar__ *data* - - Determine the *population variance* of the data in the given list - - * list *data* - - \- List of data - - - __::math::statistics::median__ *data* - - Determine the *median* of the data in the given list \(Note that this - requires sorting the data, which may be a costly operation\) - - * list *data* - - \- List of data - - - __::math::statistics::basic\-stats__ *data* - - Determine a list of all the descriptive parameters: mean, minimum, maximum, - number of data, sample standard deviation, sample variance, population - standard deviation and population variance\. - - \(This routine is called whenever either or all of the basic statistical - parameters are required\. Hence all calculations are done and the relevant - values are returned\.\) - - * list *data* - - \- List of data - - - __::math::statistics::histogram__ *limits* *values* ?weights? - - Determine histogram information for the given list of data\. Returns a list - consisting of the number of values that fall into each interval\. \(The first - interval consists of all values lower than the first limit, the last - interval consists of all values greater than the last limit\. There is one - more interval than there are limits\.\) - - Optionally, you can use weights to influence the histogram\. - - * list *limits* - - \- List of upper limits \(in ascending order\) for the intervals of the - histogram\. - - * list *values* - - \- List of data - - * list *weights* - - \- List of weights, one weight per value - - - __::math::statistics::histogram\-alt__ *limits* *values* ?weights? - - Alternative implementation of the histogram procedure: the open end of the - intervals is at the lower bound instead of the upper bound\. - - * list *limits* - - \- List of upper limits \(in ascending order\) for the intervals of the - histogram\. - - * list *values* - - \- List of data - - * list *weights* - - \- List of weights, one weight per value - - - __::math::statistics::corr__ *data1* *data2* - - Determine the correlation coefficient between two sets of data\. - - * list *data1* - - \- First list of data - - * list *data2* - - \- Second list of data - - - __::math::statistics::interval\-mean\-stdev__ *data* *confidence* - - Return the interval containing the mean value and one containing the - standard deviation with a certain level of confidence \(assuming a normal - distribution\) - - * list *data* - - \- List of raw data values \(small sample\) - - * float *confidence* - - \- Confidence level \(0\.95 or 0\.99 for instance\) - - - __::math::statistics::t\-test\-mean__ *data* *est\_mean* *est\_stdev* *alpha* - - Test whether the mean value of a sample is in accordance with the estimated - normal distribution with a certain probability\. Returns 1 if the test - succeeds or 0 if the mean is unlikely to fit the given distribution\. - - * list *data* - - \- List of raw data values \(small sample\) - - * float *est\_mean* - - \- Estimated mean of the distribution - - * float *est\_stdev* - - \- Estimated stdev of the distribution - - * float *alpha* - - \- Probability level \(0\.95 or 0\.99 for instance\) - - - __::math::statistics::test\-normal__ *data* *significance* - - Test whether the given data follow a normal distribution with a certain - level of significance\. Returns 1 if the data are normally distributed within - the level of significance, returns 0 if not\. The underlying test is the - Lilliefors test\. Smaller values of the significance mean a stricter testing\. - - * list *data* - - \- List of raw data values - - * float *significance* - - \- Significance level \(one of 0\.01, 0\.05, 0\.10, 0\.15 or 0\.20\)\. For - compatibility reasons the values "1\-significance", 0\.80, 0\.85, 0\.90, - 0\.95 or 0\.99 are also accepted\. - - Compatibility issue: the original implementation and documentation used the - term "confidence" and used a value 1\-significance \(see ticket 2812473fff\)\. - This has been corrected as of version 0\.9\.3\. - - - __::math::statistics::lillieforsFit__ *data* - - Returns the goodness of fit to a normal distribution according to - Lilliefors\. The higher the number, the more likely the data are indeed - normally distributed\. The test requires at least *five* data points\. - - * list *data* - - \- List of raw data values - - - __::math::statistics::test\-Duckworth__ *list1* *list2* *significance* - - Determine if two data sets have the same median according to the - Tukey\-Duckworth test\. The procedure returns 0 if the medians are unequal, 1 - if they are equal, \-1 if the test can not be conducted \(the smallest value - must be in a different set than the greatest value\)\. \# \# Arguments: \# list1 - Values in the first data set \# list2 Values in the second data set \# - significance Significance level \(either 0\.05, 0\.01 or 0\.001\) \# \# Returns: - Test whether the given data follow a normal distribution with a certain - level of significance\. Returns 1 if the data are normally distributed within - the level of significance, returns 0 if not\. The underlying test is the - Lilliefors test\. Smaller values of the significance mean a stricter testing\. - - * list *list1* - - \- First list of data - - * list *list2* - - \- Second list of data - - * float *significance* - - \- Significance level \(either 0\.05, 0\.01 or 0\.001\) - - - __::math::statistics::test\-anova\-F__ *alpha* *args* - - Determine if two or more groups with normally distributed data have the same - means\. The procedure returns 0 if the means are likely unequal, 1 if they - are\. This is a one\-way ANOVA test\. The groups may also be stored in a nested - list: The procedure returns a list of the comparison results for each pair - of groups\. Each element of this list contains: the index of the first group - and that of the second group, whether the means are likely to be different - \(1\) or not \(0\) and the confidence interval the conclusion is based on\. The - groups may also be stored in a nested list: - - test-anova-F 0.05 $A $B $C - # - # Or equivalently: - # - test-anova-F 0.05 [list $A $B $C] - - * float *alpha* - - \- Significance level - - * list *args* - - \- Two or more groups of data to be checked - - - __::math::statistics::test\-Tukey\-range__ *alpha* *args* - - Determine if two or more groups with normally distributed data have the same - means, using Tukey's range test\. It is complementary to the ANOVA test\. The - procedure returns a list of the comparison results for each pair of groups\. - Each element of this list contains: the index of the first group and that of - the second group, whether the means are likely to be different \(1\) or not - \(0\) and the confidence interval the conclusion is based on\. The groups may - also be stored in a nested list, just as with the ANOVA test\. - - * float *alpha* - - \- Significance level \- either 0\.05 or 0\.01 - - * list *args* - - \- Two or more groups of data to be checked - - - __::math::statistics::test\-Dunnett__ *alpha* *control* *args* - - Determine if one or more groups with normally distributed data have the same - means as the group of control data, using Dunnett's test\. It is - complementary to the ANOVA test\. The procedure returns a list of the - comparison results for each group with the control group\. Each element of - this list contains: whether the means are likely to be different \(1\) or not - \(0\) and the confidence interval the conclusion is based on\. The groups may - also be stored in a nested list, just as with the ANOVA test\. - - Note: some care is required if there is only one group to compare the - control with: - - test-Dunnett-F 0.05 $control [list $A] - - Otherwise the group A is split up into groups of one element \- this is due - to an ambiguity\. - - * float *alpha* - - \- Significance level \- either 0\.05 or 0\.01 - - * list *args* - - \- One or more groups of data to be checked - - - __::math::statistics::quantiles__ *data* *confidence* - - Return the quantiles for a given set of data - - * list *data* - - \- List of raw data values - - * float *confidence* - - \- Confidence level \(0\.95 or 0\.99 for instance\) or a list of confidence - levels\. - - - __::math::statistics::quantiles__ *limits* *counts* *confidence* - - Return the quantiles based on histogram information \(alternative to the call - with two arguments\) - - * list *limits* - - \- List of upper limits from histogram - - * list *counts* - - \- List of counts for for each interval in histogram - - * float *confidence* - - \- Confidence level \(0\.95 or 0\.99 for instance\) or a list of confidence - levels\. - - - __::math::statistics::autocorr__ *data* - - Return the autocorrelation function as a list of values \(assuming - equidistance between samples, about 1/2 of the number of raw data\) - - The correlation is determined in such a way that the first value is always 1 - and all others are equal to or smaller than 1\. The number of values involved - will diminish as the "time" \(the index in the list of returned values\) - increases - - * list *data* - - \- Raw data for which the autocorrelation must be determined - - - __::math::statistics::crosscorr__ *data1* *data2* - - Return the cross\-correlation function as a list of values \(assuming - equidistance between samples, about 1/2 of the number of raw data\) - - The correlation is determined in such a way that the values can never exceed - 1 in magnitude\. The number of values involved will diminish as the "time" - \(the index in the list of returned values\) increases\. - - * list *data1* - - \- First list of data - - * list *data2* - - \- Second list of data - - - __::math::statistics::mean\-histogram\-limits__ *mean* *stdev* *number* - - Determine reasonable limits based on mean and standard deviation for a - histogram Convenience function \- the result is suitable for the histogram - function\. - - * float *mean* - - \- Mean of the data - - * float *stdev* - - \- Standard deviation - - * int *number* - - \- Number of limits to generate \(defaults to 8\) - - - __::math::statistics::minmax\-histogram\-limits__ *min* *max* *number* - - Determine reasonable limits based on a minimum and maximum for a histogram - - Convenience function \- the result is suitable for the histogram function\. - - * float *min* - - \- Expected minimum - - * float *max* - - \- Expected maximum - - * int *number* - - \- Number of limits to generate \(defaults to 8\) - - - __::math::statistics::linear\-model__ *xdata* *ydata* *intercept* - - Determine the coefficients for a linear regression between two series of - data \(the model: Y = A \+ B\*X\)\. Returns a list of parameters describing the - fit - - * list *xdata* - - \- List of independent data - - * list *ydata* - - \- List of dependent data to be fitted - - * boolean *intercept* - - \- \(Optional\) compute the intercept \(1, default\) or fit to a line through - the origin \(0\) - - The result consists of the following list: - - + \(Estimate of\) Intercept A - - + \(Estimate of\) Slope B - - + Standard deviation of Y relative to fit - - + Correlation coefficient R2 - - + Number of degrees of freedom df - - + Standard error of the intercept A - - + Significance level of A - - + Standard error of the slope B - - + Significance level of B - - - __::math::statistics::linear\-residuals__ *xdata* *ydata* *intercept* - - Determine the difference between actual data and predicted from the linear - model\. - - Returns a list of the differences between the actual data and the predicted - values\. - - * list *xdata* - - \- List of independent data - - * list *ydata* - - \- List of dependent data to be fitted - - * boolean *intercept* - - \- \(Optional\) compute the intercept \(1, default\) or fit to a line through - the origin \(0\) - - - __::math::statistics::test\-2x2__ *n11* *n21* *n12* *n22* - - Determine if two set of samples, each from a binomial distribution, differ - significantly or not \(implying a different parameter\)\. - - Returns the "chi\-square" value, which can be used to the determine the - significance\. - - * int *n11* - - \- Number of outcomes with the first value from the first sample\. - - * int *n21* - - \- Number of outcomes with the first value from the second sample\. - - * int *n12* - - \- Number of outcomes with the second value from the first sample\. - - * int *n22* - - \- Number of outcomes with the second value from the second sample\. - - - __::math::statistics::print\-2x2__ *n11* *n21* *n12* *n22* - - Determine if two set of samples, each from a binomial distribution, differ - significantly or not \(implying a different parameter\)\. - - Returns a short report, useful in an interactive session\. - - * int *n11* - - \- Number of outcomes with the first value from the first sample\. - - * int *n21* - - \- Number of outcomes with the first value from the second sample\. - - * int *n12* - - \- Number of outcomes with the second value from the first sample\. - - * int *n22* - - \- Number of outcomes with the second value from the second sample\. - - - __::math::statistics::control\-xbar__ *data* ?nsamples? - - Determine the control limits for an xbar chart\. The number of data in each - subsample defaults to 4\. At least 20 subsamples are required\. - - Returns the mean, the lower limit, the upper limit and the number of data - per subsample\. - - * list *data* - - \- List of observed data - - * int *nsamples* - - \- Number of data per subsample - - - __::math::statistics::control\-Rchart__ *data* ?nsamples? - - Determine the control limits for an R chart\. The number of data in each - subsample \(nsamples\) defaults to 4\. At least 20 subsamples are required\. - - Returns the mean range, the lower limit, the upper limit and the number of - data per subsample\. - - * list *data* - - \- List of observed data - - * int *nsamples* - - \- Number of data per subsample - - - __::math::statistics::test\-xbar__ *control* *data* - - Determine if the data exceed the control limits for the xbar chart\. - - Returns a list of subsamples \(their indices\) that indeed violate the limits\. - - * list *control* - - \- Control limits as returned by the "control\-xbar" procedure - - * list *data* - - \- List of observed data - - - __::math::statistics::test\-Rchart__ *control* *data* - - Determine if the data exceed the control limits for the R chart\. - - Returns a list of subsamples \(their indices\) that indeed violate the limits\. - - * list *control* - - \- Control limits as returned by the "control\-Rchart" procedure - - * list *data* - - \- List of observed data - - - __::math::statistics::test\-Kruskal\-Wallis__ *confidence* *args* - - Check if the population medians of two or more groups are equal with a given - confidence level, using the Kruskal\-Wallis test\. - - * float *confidence* - - \- Confidence level to be used \(0\-1\) - - * list *args* - - \- Two or more lists of data - - - __::math::statistics::analyse\-Kruskal\-Wallis__ *args* - - Compute the statistical parameters for the Kruskal\-Wallis test\. Returns the - Kruskal\-Wallis statistic and the probability that that value would occur - assuming the medians of the populations are equal\. - - * list *args* - - \- Two or more lists of data - - - __::math::statistics::test\-Levene__ *groups* - - Compute the Levene statistic to determine if groups of data have the same - variance \(are homoscadastic\) or not\. The data are organised in groups\. This - version uses the mean of the data as the measure to determine the - deviations\. The statistic is equivalent to an F statistic with degrees of - freedom k\-1 and N\-k, k being the number of groups and N the total number of - data\. - - * list *groups* - - \- List of groups of data - - - __::math::statistics::test\-Brown\-Forsythe__ *groups* - - Compute the Brown\-Forsythe statistic to determine if groups of data have the - same variance \(are homoscadastic\) or not\. Like the Levene test, but this - version uses the median of the data\. - - * list *groups* - - \- List of groups of data - - - __::math::statistics::group\-rank__ *args* - - Rank the groups of data with respect to the complete set\. Returns a list - consisting of the group ID, the value and the rank \(possibly a rational - number, in case of ties\) for each data item\. - - * list *args* - - \- Two or more lists of data - - - __::math::statistics::test\-Wilcoxon__ *sample\_a* *sample\_b* - - Compute the Wilcoxon test statistic to determine if two samples have the - same median or not\. \(The statistic can be regarded as standard normal, if - the sample sizes are both larger than 10\.\) Returns the value of this - statistic\. - - * list *sample\_a* - - \- List of data comprising the first sample - - * list *sample\_b* - - \- List of data comprising the second sample - - - __::math::statistics::spearman\-rank__ *sample\_a* *sample\_b* - - Return the Spearman rank correlation as an alternative to the ordinary - \(Pearson's\) correlation coefficient\. The two samples should have the same - number of data\. - - * list *sample\_a* - - \- First list of data - - * list *sample\_b* - - \- Second list of data - - - __::math::statistics::spearman\-rank\-extended__ *sample\_a* *sample\_b* - - Return the Spearman rank correlation as an alternative to the ordinary - \(Pearson's\) correlation coefficient as well as additional data\. The two - samples should have the same number of data\. The procedure returns the - correlation coefficient, the number of data pairs used and the z\-score, an - approximately standard normal statistic, indicating the significance of the - correlation\. - - * list *sample\_a* - - \- First list of data - - * list *sample\_b* - - \- Second list of data - - - __::math::statistics::kernel\-density__ *data* opt *\-option value* \.\.\. - - Return the density function based on kernel density estimation\. The - procedure is controlled by a small set of options, each of which is given a - reasonable default\. - - The return value consists of three lists: the centres of the bins, the - associated probability density and a list of computational parameters \(begin - and end of the interval, mean and standard deviation and the used - bandwidth\)\. The computational parameters can be used for further analysis\. - - * list *data* - - \- The data to be examined - - * list *args* - - \- Option\-value pairs: - - + __\-weights__ *weights* - - Per data point the weight \(default: 1 for all data\) - - + __\-bandwidth__ *value* - - Bandwidth to be used for the estimation \(default: determined from - standard deviation\) - - + __\-number__ *value* - - Number of bins to be returned \(default: 100\) - - + __\-interval__ *\{begin end\}* - - Begin and end of the interval for which the density is returned - \(default: mean \+/\- 3\*standard deviation\) - - + __\-kernel__ *function* - - Kernel to be used \(One of: gaussian, cosine, epanechnikov, uniform, - triangular, biweight, logistic; default: gaussian\) - - - __::math::statistics::bootstrap__ *data* *sampleSize* ?numberSamples? - - Create a subsample or subsamples from a given list of data\. The data in the - samples are chosen from this list \- multiples may occur\. If there is only - one subsample, the sample itself is returned \(as a list of "sampleSize" - values\), otherwise a list of samples is returned\. - - * list *data* - - List of values to chose from - - * int *sampleSize* - - Number of values per sample - - * int *numberSamples* - - Number of samples \(default: 1\) - - - __::math::statistics::wasserstein\-distance__ *prob1* *prob2* - - Compute the Wasserstein distance or earth mover's distance for two - equidstantly spaced histograms or probability densities\. The histograms need - not to be normalised to sum to one, but they must have the same number of - entries\. - - Note: the histograms are assumed to be based on the same equidistant - intervals\. As the bounds are not passed, the value is expressed in the - length of the intervals\. - - * list *prob1* - - List of values for the first histogram/probability density - - * list *prob2* - - List of values for the second histogram/probability density - - - __::math::statistics::kl\-divergence__ *prob1* *prob2* - - Compute the Kullback\-Leibler \(KL\) divergence for two equidstantly spaced - histograms or probability densities\. The histograms need not to be - normalised to sum to one, but they must have the same number of entries\. - - Note: the histograms are assumed to be based on the same equidistant - intervals\. As the bounds are not passed, the value is expressed in the - length of the intervals\. - - Note also that the KL divergence is not symmetric and that the second - histogram should not contain zeroes in places where the first histogram has - non\-zero values\. - - * list *prob1* - - List of values for the first histogram/probability density - - * list *prob2* - - List of values for the second histogram/probability density - - - __::math::statistics::logistic\-model__ *xdata* *ydata* - - Estimate the coefficients of the logistic model that fits the data best\. The - data consist of independent x\-values and the outcome 0 or 1 for each of the - x\-values\. The result can be used to estimate the probability that a certain - x\-value gives 1\. - - * list *xdata* - - List of values for which the success \(1\) or failure \(0\) is known - - * list *ydata* - - List of successes or failures corresponding to each value in *xdata*\. - - - __::math::statistics::logistic\-probability__ *coeffs* *x* - - Calculate the probability of success for the value *x* given the - coefficients of the logistic model\. - - * list *coeffs* - - List of coefficients as determine by the __logistic\-model__ command - - * float *x* - - X\-value for which the probability needs to be determined - -# MULTIVARIATE LINEAR REGRESSION - -Besides the linear regression with a single independent variable, the statistics -package provides two procedures for doing ordinary least squares \(OLS\) and -weighted least squares \(WLS\) linear regression with several variables\. They were -written by Eric Kemp\-Benedict\. - -In addition to these two, it provides a procedure \(tstat\) for calculating the -value of the t\-statistic for the specified number of degrees of freedom that is -required to demonstrate a given level of significance\. - -Note: These procedures depend on the math::linearalgebra package\. - -*Description of the procedures* - - - __::math::statistics::tstat__ *dof* ?alpha? - - Returns the value of the t\-distribution t\* satisfying - - P(t*) = 1 - alpha/2 - P(-t*) = alpha/2 - - for the number of degrees of freedom dof\. - - Given a sample of normally\-distributed data x, with an estimate xbar for the - mean and sbar for the standard deviation, the alpha confidence interval for - the estimate of the mean can be calculated as - - ( xbar - t* sbar , xbar + t* sbar) - - The return values from this procedure can be compared to an estimated - t\-statistic to determine whether the estimated value of a parameter is - significantly different from zero at the given confidence level\. - - * int *dof* - - Number of degrees of freedom - - * float *alpha* - - Confidence level of the t\-distribution\. Defaults to 0\.05\. - - - __::math::statistics::mv\-wls__ *wt1* *weights\_and\_values* - - Carries out a weighted least squares linear regression for the data points - provided, with weights assigned to each point\. - - The linear model is of the form - - y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error - - and each point satisfies - - yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i - - The procedure returns a list with the following elements: - - * The r\-squared statistic - - * The adjusted r\-squared statistic - - * A list containing the estimated coefficients b1, \.\.\. bN, b0 \(The - constant b0 comes last in the list\.\) - - * A list containing the standard errors of the coefficients - - * A list containing the 95% confidence bounds of the coefficients, with - each set of bounds returned as a list with two values - - Arguments: - - * list *weights\_and\_values* - - A list consisting of: the weight for the first observation, the data for - the first observation \(as a sublist\), the weight for the second - observation \(as a sublist\) and so on\. The sublists of data are organised - as lists of the value of the dependent variable y and the independent - variables x1, x2 to xN\. - - - __::math::statistics::mv\-ols__ *values* - - Carries out an ordinary least squares linear regression for the data points - provided\. - - This procedure simply calls ::mvlinreg::wls with the weights set to 1\.0, and - returns the same information\. - -*Example of the use:* - - # Store the value of the unicode value for the "+/-" character - set pm "\u00B1" - - # Provide some data - set data {{ -.67 14.18 60.03 -7.5 } - { 36.97 15.52 34.24 14.61 } - {-29.57 21.85 83.36 -7. } - {-16.9 11.79 51.67 -6.56 } - { 14.09 16.24 36.97 -12.84} - { 31.52 20.93 45.99 -25.4 } - { 24.05 20.69 50.27 17.27} - { 22.23 16.91 45.07 -4.3 } - { 40.79 20.49 38.92 -.73 } - {-10.35 17.24 58.77 18.78}} - - # Call the ols routine - set results [::math::statistics::mv-ols $data] - - # Pretty-print the results - puts "R-squared: [lindex $results 0]" - puts "Adj R-squared: [lindex $results 1]" - puts "Coefficients $pm s.e. -- \[95% confidence interval\]:" - foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] { - set lb [lindex $bounds 0] - set ub [lindex $bounds 1] - puts " $val $pm $se -- \[$lb to $ub\]" - } - -# STATISTICAL DISTRIBUTIONS - -In the literature a large number of probability distributions can be found\. The -statistics package supports: - - - The normal or Gaussian distribution as well as the log\-normal distribution - - - The uniform distribution \- equal probability for all data within a given - interval - - - The exponential distribution \- useful as a model for certain extreme\-value - distributions\. - - - The gamma distribution \- based on the incomplete Gamma integral - - - The beta distribution - - - The chi\-square distribution - - - The student's T distribution - - - The Poisson distribution - - - The Pareto distribution - - - The Gumbel distribution - - - The Weibull distribution - - - The Cauchy distribution - - - The F distribution \(only the cumulative density function\) - - - PM \- binomial\. - -In principle for each distribution one has procedures for: - - - The probability density \(pdf\-\*\) - - - The cumulative density \(cdf\-\*\) - - - Quantiles for the given distribution \(quantiles\-\*\) - - - Histograms for the given distribution \(histogram\-\*\) - - - List of random values with the given distribution \(random\-\*\) - -The following procedures have been implemented: - - - __::math::statistics::pdf\-normal__ *mean* *stdev* *value* - - Return the probability of a given value for a normal distribution with given - mean and standard deviation\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-lognormal__ *mean* *stdev* *value* - - Return the probability of a given value for a log\-normal distribution with - given mean and standard deviation\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-exponential__ *mean* *value* - - Return the probability of a given value for an exponential distribution with - given mean\. - - * float *mean* - - \- Mean value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-uniform__ *xmin* *xmax* *value* - - Return the probability of a given value for a uniform distribution with - given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-triangular__ *xmin* *xmax* *value* - - Return the probability of a given value for a triangular distribution with - given extremes\. If the argument min is lower than the argument max, then - smaller values have higher probability and vice versa\. In the first case the - probability density function is of the form *f\(x\) = 2\(1\-x\)* and the other - case it is of the form *f\(x\) = 2x*\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-symmetric\-triangular__ *xmin* *xmax* *value* - - Return the probability of a given value for a symmetric triangular - distribution with given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-gamma__ *alpha* *beta* *value* - - Return the probability of a given value for a Gamma distribution with given - shape and rate parameters - - * float *alpha* - - \- Shape parameter - - * float *beta* - - \- Rate parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-poisson__ *mu* *k* - - Return the probability of a given number of occurrences in the same interval - \(k\) for a Poisson distribution with given mean \(mu\) - - * float *mu* - - \- Mean number of occurrences - - * int *k* - - \- Number of occurences - - - __::math::statistics::pdf\-chisquare__ *df* *value* - - Return the probability of a given value for a chi square distribution with - given degrees of freedom - - * float *df* - - \- Degrees of freedom - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-student\-t__ *df* *value* - - Return the probability of a given value for a Student's t distribution with - given degrees of freedom - - * float *df* - - \- Degrees of freedom - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-gamma__ *a* *b* *value* - - Return the probability of a given value for a Gamma distribution with given - shape and rate parameters - - * float *a* - - \- Shape parameter - - * float *b* - - \- Rate parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-beta__ *a* *b* *value* - - Return the probability of a given value for a Beta distribution with given - shape parameters - - * float *a* - - \- First shape parameter - - * float *b* - - \- Second shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-weibull__ *scale* *shape* *value* - - Return the probability of a given value for a Weibull distribution with - given scale and shape parameters - - * float *location* - - \- Scale parameter - - * float *scale* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-gumbel__ *location* *scale* *value* - - Return the probability of a given value for a Gumbel distribution with given - location and shape parameters - - * float *location* - - \- Location parameter - - * float *scale* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-pareto__ *scale* *shape* *value* - - Return the probability of a given value for a Pareto distribution with given - scale and shape parameters - - * float *scale* - - \- Scale parameter - - * float *shape* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-cauchy__ *location* *scale* *value* - - Return the probability of a given value for a Cauchy distribution with given - location and shape parameters\. Note that the Cauchy distribution has no - finite higher\-order moments\. - - * float *location* - - \- Location parameter - - * float *scale* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-laplace__ *location* *scale* *value* - - Return the probability of a given value for a Laplace distribution with - given location and shape parameters\. The Laplace distribution consists of - two exponential functions, is peaked and has heavier tails than the normal - distribution\. - - * float *location* - - \- Location parameter \(mean\) - - * float *scale* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-kumaraswamy__ *a* *b* *value* - - Return the probability of a given value for a Kumaraswamy distribution with - given parameters a and b\. The Kumaraswamy distribution is related to the - Beta distribution, but has a tractable cumulative distribution function\. - - * float *a* - - \- Parameter a - - * float *b* - - \- Parameter b - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::pdf\-negative\-binomial__ *r* *p* *value* - - Return the probability of a given value for a negative binomial distribution - with an allowed number of failures and the probability of success\. - - * int *r* - - \- Allowed number of failures \(at least 1\) - - * float *p* - - \- Probability of success - - * int *value* - - \- Number of successes for which the probability is to be returned - - - __::math::statistics::cdf\-normal__ *mean* *stdev* *value* - - Return the cumulative probability of a given value for a normal distribution - with given mean and standard deviation, that is the probability for values - up to the given one\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-lognormal__ *mean* *stdev* *value* - - Return the cumulative probability of a given value for a log\-normal - distribution with given mean and standard deviation, that is the probability - for values up to the given one\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-exponential__ *mean* *value* - - Return the cumulative probability of a given value for an exponential - distribution with given mean\. - - * float *mean* - - \- Mean value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-uniform__ *xmin* *xmax* *value* - - Return the cumulative probability of a given value for a uniform - distribution with given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-triangular__ *xmin* *xmax* *value* - - Return the cumulative probability of a given value for a triangular - distribution with given extremes\. If xmin < xmax, then lower values have a - higher probability and vice versa, see also *pdf\-triangular* - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-symmetric\-triangular__ *xmin* *xmax* *value* - - Return the cumulative probability of a given value for a symmetric - triangular distribution with given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmin* - - \- Maximum value of the distribution - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-students\-t__ *degrees* *value* - - Return the cumulative probability of a given value for a Student's t - distribution with given number of degrees\. - - * int *degrees* - - \- Number of degrees of freedom - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-gamma__ *alpha* *beta* *value* - - Return the cumulative probability of a given value for a Gamma distribution - with given shape and rate parameters\. - - * float *alpha* - - \- Shape parameter - - * float *beta* - - \- Rate parameter - - * float *value* - - \- Value for which the cumulative probability is required - - - __::math::statistics::cdf\-poisson__ *mu* *k* - - Return the cumulative probability of a given number of occurrences in the - same interval \(k\) for a Poisson distribution with given mean \(mu\)\. - - * float *mu* - - \- Mean number of occurrences - - * int *k* - - \- Number of occurences - - - __::math::statistics::cdf\-beta__ *a* *b* *value* - - Return the cumulative probability of a given value for a Beta distribution - with given shape parameters - - * float *a* - - \- First shape parameter - - * float *b* - - \- Second shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-weibull__ *scale* *shape* *value* - - Return the cumulative probability of a given value for a Weibull - distribution with given scale and shape parameters\. - - * float *scale* - - \- Scale parameter - - * float *shape* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-gumbel__ *location* *scale* *value* - - Return the cumulative probability of a given value for a Gumbel distribution - with given location and scale parameters\. - - * float *location* - - \- Location parameter - - * float *scale* - - \- Scale parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-pareto__ *scale* *shape* *value* - - Return the cumulative probability of a given value for a Pareto distribution - with given scale and shape parameters - - * float *scale* - - \- Scale parameter - - * float *shape* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-cauchy__ *location* *scale* *value* - - Return the cumulative probability of a given value for a Cauchy distribution - with given location and scale parameters\. - - * float *location* - - \- Location parameter - - * float *scale* - - \- Scale parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-F__ *nf1* *nf2* *value* - - Return the cumulative probability of a given value for an F distribution - with nf1 and nf2 degrees of freedom\. - - * float *nf1* - - \- Degrees of freedom for the numerator - - * float *nf2* - - \- Degrees of freedom for the denominator - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-laplace__ *location* *scale* *value* - - Return the cumulative probability of a given value for a Laplace - distribution with given location and shape parameters\. The Laplace - distribution consists of two exponential functions, is peaked and has - heavier tails than the normal distribution\. - - * float *location* - - \- Location parameter \(mean\) - - * float *scale* - - \- Shape parameter - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-kumaraswamy__ *a* *b* *value* - - Return the cumulative probability of a given value for a Kumaraswamy - distribution with given parameters a and b\. The Kumaraswamy distribution is - related to the Beta distribution, but has a tractable cumulative - distribution function\. - - * float *a* - - \- Parameter a - - * float *b* - - \- Parameter b - - * float *value* - - \- Value for which the probability is required - - - __::math::statistics::cdf\-negative\-binomial__ *r* *p* *value* - - Return the cumulative probability of a given value for a negative binomial - distribution with an allowed number of failures and the probability of - success\. - - * int *r* - - \- Allowed number of failures \(at least 1\) - - * float *p* - - \- Probability of success - - * int *value* - - \- Greatest number of successes - - - __::math::statistics::empirical\-distribution__ *values* - - Return a list of values and their empirical probability\. The values are - sorted in increasing order\. \(The implementation follows the description at - the corresponding Wikipedia page\) - - * list *values* - - \- List of data to be examined - - - __::math::statistics::random\-normal__ *mean* *stdev* *number* - - Return a list of "number" random values satisfying a normal distribution - with given mean and standard deviation\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-lognormal__ *mean* *stdev* *number* - - Return a list of "number" random values satisfying a log\-normal distribution - with given mean and standard deviation\. - - * float *mean* - - \- Mean value of the distribution - - * float *stdev* - - \- Standard deviation of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-exponential__ *mean* *number* - - Return a list of "number" random values satisfying an exponential - distribution with given mean\. - - * float *mean* - - \- Mean value of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-uniform__ *xmin* *xmax* *number* - - Return a list of "number" random values satisfying a uniform distribution - with given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmax* - - \- Maximum value of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-triangular__ *xmin* *xmax* *number* - - Return a list of "number" random values satisfying a triangular distribution - with given extremes\. If xmin < xmax, then lower values have a higher - probability and vice versa \(see also *pdf\-triangular*\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmax* - - \- Maximum value of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-symmetric\-triangular__ *xmin* *xmax* *number* - - Return a list of "number" random values satisfying a symmetric triangular - distribution with given extremes\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmax* - - \- Maximum value of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-gamma__ *alpha* *beta* *number* - - Return a list of "number" random values satisfying a Gamma distribution with - given shape and rate parameters\. - - * float *alpha* - - \- Shape parameter - - * float *beta* - - \- Rate parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-poisson__ *mu* *number* - - Return a list of "number" random values satisfying a Poisson distribution - with given mean\. - - * float *mu* - - \- Mean of the distribution - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-chisquare__ *df* *number* - - Return a list of "number" random values satisfying a chi square distribution - with given degrees of freedom\. - - * float *df* - - \- Degrees of freedom - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-student\-t__ *df* *number* - - Return a list of "number" random values satisfying a Student's t - distribution with given degrees of freedom\. - - * float *df* - - \- Degrees of freedom - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-beta__ *a* *b* *number* - - Return a list of "number" random values satisfying a Beta distribution with - given shape parameters\. - - * float *a* - - \- First shape parameter - - * float *b* - - \- Second shape parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-weibull__ *scale* *shape* *number* - - Return a list of "number" random values satisfying a Weibull distribution - with given scale and shape parameters\. - - * float *scale* - - \- Scale parameter - - * float *shape* - - \- Shape parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-gumbel__ *location* *scale* *number* - - Return a list of "number" random values satisfying a Gumbel distribution - with given location and scale parameters\. - - * float *location* - - \- Location parameter - - * float *scale* - - \- Scale parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-pareto__ *scale* *shape* *number* - - Return a list of "number" random values satisfying a Pareto distribution - with given scale and shape parameters\. - - * float *scale* - - \- Scale parameter - - * float *shape* - - \- Shape parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-cauchy__ *location* *scale* *number* - - Return a list of "number" random values satisfying a Cauchy distribution - with given location and scale parameters\. - - * float *location* - - \- Location parameter - - * float *scale* - - \- Scale parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-laplace__ *location* *scale* *number* - - Return a list of "number" random values satisfying a Laplace distribution - with given location and shape parameters\. The Laplace distribution consists - of two exponential functions, is peaked and has heavier tails than the - normal distribution\. - - * float *location* - - \- Location parameter \(mean\) - - * float *scale* - - \- Shape parameter - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-kumaraswamy__ *a* *b* *number* - - Return a list of "number" random values satisying a Kumaraswamy distribution - with given parameters a and b\. The Kumaraswamy distribution is related to - the Beta distribution, but has a tractable cumulative distribution function\. - - * float *a* - - \- Parameter a - - * float *b* - - \- Parameter b - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::random\-negative\-binomial__ *r* *p* *number* - - Return a list of "number" random values satisying a negative binomial - distribution\. - - * int *r* - - \- Allowed number of failures \(at least 1\) - - * float *p* - - \- Probability of success - - * int *number* - - \- Number of values to be returned - - - __::math::statistics::histogram\-uniform__ *xmin* *xmax* *limits* *number* - - Return the expected histogram for a uniform distribution\. - - * float *xmin* - - \- Minimum value of the distribution - - * float *xmax* - - \- Maximum value of the distribution - - * list *limits* - - \- Upper limits for the buckets in the histogram - - * int *number* - - \- Total number of "observations" in the histogram - - - __::math::statistics::incompleteGamma__ *x* *p* ?tol? - - Evaluate the incomplete Gamma integral - - 1 / x p-1 - P(p,x) = -------- | dt exp(-t) * t - Gamma(p) / 0 - - * float *x* - - \- Value of x \(limit of the integral\) - - * float *p* - - \- Value of p in the integrand - - * float *tol* - - \- Required tolerance \(default: 1\.0e\-9\) - - - __::math::statistics::incompleteBeta__ *a* *b* *x* ?tol? - - Evaluate the incomplete Beta integral - - * float *a* - - \- First shape parameter - - * float *b* - - \- Second shape parameter - - * float *x* - - \- Value of x \(limit of the integral\) - - * float *tol* - - \- Required tolerance \(default: 1\.0e\-9\) - - - __::math::statistics::estimate\-pareto__ *values* - - Estimate the parameters for the Pareto distribution that comes closest to - the given values\. Returns the estimated scale and shape parameters, as well - as the standard error for the shape parameter\. - - * list *values* - - \- List of values, assumed to be distributed according to a Pareto - distribution - - - __::math::statistics::estimate\-exponential__ *values* - - Estimate the parameter for the exponential distribution that comes closest - to the given values\. Returns an estimate of the one parameter and of the - standard error\. - - * list *values* - - \- List of values, assumed to be distributed according to an exponential - distribution - - - __::math::statistics::estimate\-laplace__ *values* - - Estimate the parameters for the Laplace distribution that comes closest to - the given values\. Returns an estimate of respectively the location and scale - parameters, based on maximum likelihood\. - - * list *values* - - \- List of values, assumed to be distributed according to an exponential - distribution - - - __::math::statistics::estimante\-negative\-binomial__ *r* *values* - - Estimate the probability of success for the negative binomial distribution - that comes closest to the given values\. The allowed number of failures must - be given\. - - * int *r* - - \- Allowed number of failures \(at least 1\) - - * int *number* - - \- List of values, assumed to be distributed according to a negative - binomial distribution\. - -TO DO: more function descriptions to be added - -# DATA MANIPULATION - -The data manipulation procedures act on lists or lists of lists: - - - __::math::statistics::filter__ *varname* *data* *expression* - - Return a list consisting of the data for which the logical expression is - true \(this command works analogously to the command - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__\)\. - - * string *varname* - - \- Name of the variable used in the expression - - * list *data* - - \- List of data - - * string *expression* - - \- Logical expression using the variable name - - - __::math::statistics::map__ *varname* *data* *expression* - - Return a list consisting of the data that are transformed via the - expression\. - - * string *varname* - - \- Name of the variable used in the expression - - * list *data* - - \- List of data - - * string *expression* - - \- Expression to be used to transform \(map\) the data - - - __::math::statistics::samplescount__ *varname* *list* *expression* - - Return a list consisting of the *counts* of all data in the sublists of - the "list" argument for which the expression is true\. - - * string *varname* - - \- Name of the variable used in the expression - - * list *data* - - \- List of sublists, each containing the data - - * string *expression* - - \- Logical expression to test the data \(defaults to "true"\)\. - - - __::math::statistics::subdivide__ - - Routine *PM* \- not implemented yet - -# PLOT PROCEDURES - -The following simple plotting procedures are available: - - - __::math::statistics::plot\-scale__ *canvas* *xmin* *xmax* *ymin* *ymax* - - Set the scale for a plot in the given canvas\. All plot routines expect this - function to be called first\. There is no automatic scaling provided\. - - * widget *canvas* - - \- Canvas widget to use - - * float *xmin* - - \- Minimum x value - - * float *xmax* - - \- Maximum x value - - * float *ymin* - - \- Minimum y value - - * float *ymax* - - \- Maximum y value - - - __::math::statistics::plot\-xydata__ *canvas* *xdata* *ydata* *tag* - - Create a simple XY plot in the given canvas \- the data are shown as a - collection of dots\. The tag can be used to manipulate the appearance\. - - * widget *canvas* - - \- Canvas widget to use - - * float *xdata* - - \- Series of independent data - - * float *ydata* - - \- Series of dependent data - - * string *tag* - - \- Tag to give to the plotted data \(defaults to xyplot\) - - - __::math::statistics::plot\-xyline__ *canvas* *xdata* *ydata* *tag* - - Create a simple XY plot in the given canvas \- the data are shown as a line - through the data points\. The tag can be used to manipulate the appearance\. - - * widget *canvas* - - \- Canvas widget to use - - * list *xdata* - - \- Series of independent data - - * list *ydata* - - \- Series of dependent data - - * string *tag* - - \- Tag to give to the plotted data \(defaults to xyplot\) - - - __::math::statistics::plot\-tdata__ *canvas* *tdata* *tag* - - Create a simple XY plot in the given canvas \- the data are shown as a - collection of dots\. The horizontal coordinate is equal to the index\. The tag - can be used to manipulate the appearance\. This type of presentation is - suitable for autocorrelation functions for instance or for inspecting the - time\-dependent behaviour\. - - * widget *canvas* - - \- Canvas widget to use - - * list *tdata* - - \- Series of dependent data - - * string *tag* - - \- Tag to give to the plotted data \(defaults to xyplot\) - - - __::math::statistics::plot\-tline__ *canvas* *tdata* *tag* - - Create a simple XY plot in the given canvas \- the data are shown as a line\. - See plot\-tdata for an explanation\. - - * widget *canvas* - - \- Canvas widget to use - - * list *tdata* - - \- Series of dependent data - - * string *tag* - - \- Tag to give to the plotted data \(defaults to xyplot\) - - - __::math::statistics::plot\-histogram__ *canvas* *counts* *limits* *tag* - - Create a simple histogram in the given canvas - - * widget *canvas* - - \- Canvas widget to use - - * list *counts* - - \- Series of bucket counts - - * list *limits* - - \- Series of upper limits for the buckets - - * string *tag* - - \- Tag to give to the plotted data \(defaults to xyplot\) - -# THINGS TO DO - -The following procedures are yet to be implemented: - - - F\-test\-stdev - - - interval\-mean\-stdev - - - histogram\-normal - - - histogram\-exponential - - - test\-histogram - - - test\-corr - - - quantiles\-\* - - - fourier\-coeffs - - - fourier\-residuals - - - onepar\-function\-fit - - - onepar\-function\-residuals - - - plot\-linear\-model - - - subdivide - -# EXAMPLES - -The code below is a small example of how you can examine a set of data: - - # Simple example: - # - Generate data (as a cheap way of getting some) - # - Perform statistical analysis to describe the data - # - package require math::statistics - - # - # Two auxiliary procs - # - proc pause {time} { - set wait 0 - after [expr {$time*1000}] {set ::wait 1} - vwait wait - } - - proc print-histogram {counts limits} { - foreach count $counts limit $limits { - if { $limit != {} } { - puts [format "<%12.4g\t%d" $limit $count] - set prev_limit $limit - } else { - puts [format ">%12.4g\t%d" $prev_limit $count] - } - } - } - - # - # Our source of arbitrary data - # - proc generateData { data1 data2 } { - upvar 1 $data1 _data1 - upvar 1 $data2 _data2 - - set d1 0.0 - set d2 0.0 - for { set i 0 } { $i < 100 } { incr i } { - set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}] - set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}] - lappend _data1 $d1 - lappend _data2 $d2 - } - return {} - } - - # - # The analysis session - # - package require Tk - console show - canvas .plot1 - canvas .plot2 - pack .plot1 .plot2 -fill both -side top - - generateData data1 data2 - - puts "Basic statistics:" - set b1 [::math::statistics::basic-stats $data1] - set b2 [::math::statistics::basic-stats $data2] - foreach label {mean min max number stdev var} v1 $b1 v2 $b2 { - puts "$label\t$v1\t$v2" - } - puts "Plot the data as function of \"time\" and against each other" - ::math::statistics::plot-scale .plot1 0 100 0 20 - ::math::statistics::plot-scale .plot2 0 20 0 20 - ::math::statistics::plot-tline .plot1 $data1 - ::math::statistics::plot-tline .plot1 $data2 - ::math::statistics::plot-xydata .plot2 $data1 $data2 - - puts "Correlation coefficient:" - puts [::math::statistics::corr $data1 $data2] - - pause 2 - puts "Plot histograms" - .plot2 delete all - ::math::statistics::plot-scale .plot2 0 20 0 100 - set limits [::math::statistics::minmax-histogram-limits 7 16] - set histogram_data [::math::statistics::histogram $limits $data1] - ::math::statistics::plot-histogram .plot2 $histogram_data $limits - - puts "First series:" - print-histogram $histogram_data $limits - - pause 2 - set limits [::math::statistics::minmax-histogram-limits 0 15 10] - set histogram_data [::math::statistics::histogram $limits $data2] - ::math::statistics::plot-histogram .plot2 $histogram_data $limits d2 - .plot2 itemconfigure d2 -fill red - - puts "Second series:" - print-histogram $histogram_data $limits - - puts "Autocorrelation function:" - set autoc [::math::statistics::autocorr $data1] - puts [::math::statistics::map $autoc {[format "%.2f" $x]}] - puts "Cross-correlation function:" - set crossc [::math::statistics::crosscorr $data1 $data2] - puts [::math::statistics::map $crossc {[format "%.2f" $x]}] - - ::math::statistics::plot-scale .plot1 0 100 -1 4 - ::math::statistics::plot-tline .plot1 $autoc "autoc" - ::math::statistics::plot-tline .plot1 $crossc "crossc" - .plot1 itemconfigure autoc -fill green - .plot1 itemconfigure crossc -fill yellow - - puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9" - puts "First: [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]" - puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]" - -If you run this example, then the following should be clear: - - - There is a strong correlation between two time series, as displayed by the - raw data and especially by the correlation functions\. - - - Both time series show a significant periodic component - - - The histograms are not very useful in identifying the nature of the time - series \- they do not show the periodic nature\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: statistics* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[data analysis](\.\./\.\./\.\./\.\./index\.md\#data\_analysis), -[mathematics](\.\./\.\./\.\./\.\./index\.md\#mathematics), -[statistics](\.\./\.\./\.\./\.\./index\.md\#statistics) - -# CATEGORY - -Mathematics DELETED embedded/md/tcllib/files/modules/math/symdiff.md Index: embedded/md/tcllib/files/modules/math/symdiff.md ================================================================== --- embedded/md/tcllib/files/modules/math/symdiff.md +++ embedded/md/tcllib/files/modules/math/symdiff.md @@ -1,135 +0,0 @@ - -[//000000001]: # (math::calculus::symdiff \- Symbolic differentiation for Tcl) -[//000000002]: # (Generated from file 'symdiff\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010 by Kevin B\. Kenny ) -[//000000004]: # (Redistribution permitted under the terms of the Open Publication License ) -[//000000005]: # (math::calculus::symdiff\(n\) 1\.0\.1 tcllib "Symbolic differentiation for Tcl") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::calculus::symdiff \- Symbolic differentiation for Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Procedures](#section2) - - - [Expressions](#section3) - - - [Examples](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require grammar::aycock 1\.0 -package require math::calculus::symdiff 1\.0\.1 - -[__math::calculus::symdiff::symdiff__ *expression* *variable*](#1) -[__math::calculus::jacobian__ *variableDict*](#2) - -# DESCRIPTION - -The __math::calculus::symdiff__ package provides a symbolic differentiation -facility for Tcl math expressions\. It is useful for providing derivatives to -packages that either require the Jacobian of a set of functions or else are more -efficient or stable when the Jacobian is provided\. - -# Procedures - -The __math::calculus::symdiff__ package exports the two procedures: - - - __math::calculus::symdiff::symdiff__ *expression* *variable* - - Differentiates the given *expression* with respect to the specified - *variable*\. \(See [Expressions](#section3) below for a discussion of - the subset of Tcl math expressions that are acceptable to - __math::calculus::symdiff__\.\) The result is a Tcl expression that - evaluates the derivative\. Returns an error if *expression* is not a - well\-formed expression or is not differentiable\. - - - __math::calculus::jacobian__ *variableDict* - - Computes the Jacobian of a system of equations\. The system is given by the - dictionary *variableDict*, whose keys are the names of variables in the - system, and whose values are Tcl expressions giving the values of those - variables\. \(See [Expressions](#section3) below for a discussion of the - subset of Tcl math expressions that are acceptable to - __math::calculus::symdiff__\. The result is a list of lists: the i'th - element of the j'th sublist is the partial derivative of the i'th variable - with respect to the j'th variable\. Returns an error if any of the - expressions cannot be differentiated, or if *variableDict* is not a - well\-formed dictionary\. - -# Expressions - -The __math::calculus::symdiff__ package accepts only a small subset of the -expressions that are acceptable to Tcl commands such as __expr__ or -__if__\. Specifically, the only constructs accepted are: - - - Floating\-point constants such as __5__ or __3\.14159e\+00__\. - - - References to Tcl variable using $\-substitution\. The variable names must - consist of alphanumerics and underscores: the __$\{\.\.\.\}__ notation is not - accepted\. - - - Parentheses\. - - - The __\+__, __\-__, __\*__, __/__\. and __\*\*__ operators\. - - - Calls to the functions __acos__, __asin__, __atan__, - __atan2__, __cos__, __cosh__, __exp__, __hypot__, - __[log](\.\./log/log\.md)__, __log10__, __pow__, __sin__, - __sinh__\. __sqrt__, __tan__, and __tanh__\. - -Command substitution, backslash substitution, and argument expansion are not -accepted\. - -# Examples - - math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x - ==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d))) - math::calculus::symdiff::jacobian {x {$a * $x + $b * $y} - y {$c * $x + $d * $y}} - ==> {{$a} {$b}} {{$c} {$d}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: calculus* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[math::calculus](calculus\.md), [math::interpolate](interpolate\.md) - -# COPYRIGHT - -Copyright © 2010 by Kevin B\. Kenny -Redistribution permitted under the terms of the Open Publication License DELETED embedded/md/tcllib/files/modules/math/trig.md Index: embedded/md/tcllib/files/modules/math/trig.md ================================================================== --- embedded/md/tcllib/files/modules/math/trig.md +++ embedded/md/tcllib/files/modules/math/trig.md @@ -1,299 +0,0 @@ - -[//000000001]: # (math::trig \- Tcl Math Library) -[//000000002]: # (Generated from file 'trig\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2018 Arjen Markus) -[//000000004]: # (math::trig\(n\) 1\.0\.0 tcllib "Tcl Math Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -math::trig \- Trigonometric anf hyperbolic functions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [FUNCTIONS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require math::trig 1\.0\.0 - -[__::math::trig::radian\_reduced__ *angle*](#1) -[__::math::trig::degree\_reduced__ *angle*](#2) -[__::math::trig::cosec__ *angle*](#3) -[__::math::trig::sec__ *angle*](#4) -[__::math::trig::cotan__ *angle*](#5) -[__::math::trig::acosec__ *value*](#6) -[__::math::trig::asec__ *value*](#7) -[__::math::trig::acotan__ *value*](#8) -[__::math::trig::cosech__ *value*](#9) -[__::math::trig::sech__ *value*](#10) -[__::math::trig::cotanh__ *value*](#11) -[__::math::trig::asinh__ *value*](#12) -[__::math::trig::acosh__ *value*](#13) -[__::math::trig::atanh__ *value*](#14) -[__::math::trig::acosech__ *value*](#15) -[__::math::trig::asech__ *value*](#16) -[__::math::trig::acotanh__ *value*](#17) -[__::math::trig::sind__ *angle*](#18) -[__::math::trig::cosd__ *angle*](#19) -[__::math::trig::tand__ *angle*](#20) -[__::math::trig::cosecd__ *angle*](#21) -[__::math::trig::secd__ *angle*](#22) -[__::math::trig::cotand__ *angle*](#23) - -# DESCRIPTION - -The *math::trig* package defines a set of trigonomic and hyperbolic functions -and their inverses\. In addition it defines versions of the trigonomic functions -that take arguments in degrees instead of radians\. - -For easy use these functions may be imported into the *tcl::mathfunc* -namespace, so that they can be used directly in the *expr* command\. - -# FUNCTIONS - -The functions *radian\_reduced* and *degree\_reduced* return a reduced angle, -in respectively radians and degrees, in the intervals \[0, 2pi\) and \[0, 360\): - - - __::math::trig::radian\_reduced__ *angle* - - Return the equivalent angle in the interval \[0, 2pi\)\. - - * float *angle* - - Angle \(in radians\) - - - __::math::trig::degree\_reduced__ *angle* - - Return the equivalent angle in the interval \[0, 360\)\. - - * float *angle* - - Angle \(in degrees\) - -The following trigonomic functions are defined in addition to the ones defined -in the *expr* command: - - - __::math::trig::cosec__ *angle* - - Calculate the cosecant of the angle \(1/cos\(angle\)\) - - * float *angle* - - Angle \(in radians\) - - - __::math::trig::sec__ *angle* - - Calculate the secant of the angle \(1/sin\(angle\)\) - - * float *angle* - - Angle \(in radians\) - - - __::math::trig::cotan__ *angle* - - Calculate the cotangent of the angle \(1/tan\(angle\)\) - - * float *angle* - - Angle \(in radians\) - -For these functions also the inverses are defined: - - - __::math::trig::acosec__ *value* - - Calculate the arc cosecant of the value - - * float *value* - - Value of the argument - - - __::math::trig::asec__ *value* - - Calculate the arc secant of the value - - * float *value* - - Value of the argument - - - __::math::trig::acotan__ *value* - - Calculate the arc cotangent of the value - - * float *value* - - Value of the argument - -The following hyperbolic and inverse hyperbolic functions are defined: - - - __::math::trig::cosech__ *value* - - Calculate the hyperbolic cosecant of the value \(1/sinh\(value\)\) - - * float *value* - - Value of the argument - - - __::math::trig::sech__ *value* - - Calculate the hyperbolic secant of the value \(1/cosh\(value\)\) - - * float *value* - - Value of the argument - - - __::math::trig::cotanh__ *value* - - Calculate the hyperbolic cotangent of the value \(1/tanh\(value\)\) - - * float *value* - - Value of the argument - - - __::math::trig::asinh__ *value* - - Calculate the arc hyperbolic sine of the value - - * float *value* - - Value of the argument - - - __::math::trig::acosh__ *value* - - Calculate the arc hyperbolic cosine of the value - - * float *value* - - Value of the argument - - - __::math::trig::atanh__ *value* - - Calculate the arc hyperbolic tangent of the value - - * float *value* - - Value of the argument - - - __::math::trig::acosech__ *value* - - Calculate the arc hyperbolic cosecant of the value - - * float *value* - - Value of the argument - - - __::math::trig::asech__ *value* - - Calculate the arc hyperbolic secant of the value - - * float *value* - - Value of the argument - - - __::math::trig::acotanh__ *value* - - Calculate the arc hyperbolic cotangent of the value - - * float *value* - - Value of the argument - -The following versions of the common trigonometric functions and their inverses -are defined: - - - __::math::trig::sind__ *angle* - - Calculate the sine of the angle \(in degrees\) - - * float *angle* - - Angle \(in degrees\) - - - __::math::trig::cosd__ *angle* - - Calculate the cosine of the angle \(in degrees\) - - * float *angle* - - Angle \(in radians\) - - - __::math::trig::tand__ *angle* - - Calculate the cotangent of the angle \(in degrees\) - - * float *angle* - - Angle \(in degrees\) - - - __::math::trig::cosecd__ *angle* - - Calculate the cosecant of the angle \(in degrees\) - - * float *angle* - - Angle \(in degrees\) - - - __::math::trig::secd__ *angle* - - Calculate the secant of the angle \(in degrees\) - - * float *angle* - - Angle \(in degrees\) - - - __::math::trig::cotand__ *angle* - - Calculate the cotangent of the angle \(in degrees\) - - * float *angle* - - Angle \(in degrees\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *math :: trig* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[trigonometry](\.\./\.\./\.\./\.\./index\.md\#trigonometry) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2018 Arjen Markus DELETED embedded/md/tcllib/files/modules/md4/md4.md Index: embedded/md/tcllib/files/modules/md4/md4.md ================================================================== --- embedded/md/tcllib/files/modules/md4/md4.md +++ embedded/md/tcllib/files/modules/md4/md4.md @@ -1,201 +0,0 @@ - -[//000000001]: # (md4 \- MD4 Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'md4\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003, Pat Thoyts ) -[//000000004]: # (md4\(n\) 1\.0\.7 tcllib "MD4 Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -md4 \- MD4 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require md4 ?1\.0\.7? - -[__::md4::md4__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \]](#1) -[__::md4::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \]](#2) -[__::md4::MD4Init__](#3) -[__::md4::MD4Update__ *token* *data*](#4) -[__::md4::MD4Final__ *token*](#5) -[__::md4::HMACInit__ *key*](#6) -[__::md4::HMACUpdate__ *token* *data*](#7) -[__::md4::HMACFinal__ *token*](#8) - -# DESCRIPTION - -This package is an implementation in Tcl of the MD4 message\-digest algorithm as -described in RFC 1320 \(1\) and \(2\)\. This algorithm takes an arbitrary quantity of -data and generates a 128\-bit message digest from the input\. The MD4 algorithm is -faster but potentially weaker than the related MD5 algorithm \(3\)\. - -If you have __critcl__ and have built the __tcllibc__ package then the -implementation of the hashing function will be performed by compiled code\. -Alternatively if __cryptkit__ is available this will be used\. If no -accelerator package can be found then the pure\-tcl implementation is used\. The -programming interface remains the same in all cases\. - -# COMMANDS - - - __::md4::md4__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate the MD4 digest of the data given in string\. This is returned as a - binary string by default\. Giving the *\-hex* option will return a - hexadecimal encoded version of the digest\. - - The data to be hashed can be specified either as a string argument to the - md4 command, or as a filename or a pre\-opened channel\. If the *\-filename* - argument is given then the file is opened, the data read and hashed and the - file is closed\. If the *\-channel* argument is given then data is read from - the channel until the end of file\. The channel is not closed\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - - __::md4::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the MD4 - digest algorithm\. HMACs are described in RFC 2104 \(4\) and provide an MD4 - digest that includes a key\. All options other than *\-key* are as for the - __::md4::md4__ command\. - -# PROGRAMMING INTERFACE - -For the programmer, the MD4 hash can be viewed as a bucket into which one pours -data\. When you have finished, you extract a value that is derived from the data -that was poured into the bucket\. The programming interface to the MD4 hash -operates on a token \(equivalent to the bucket\)\. You call __MD4Init__ to -obtain a token and then call __MD4Update__ as many times as required to add -data to the hash\. To release any resources and obtain the hash value, you then -call __MD4Final__\. An equivalent set of functions gives you a keyed digest -\(HMAC\)\. - - - __::md4::MD4Init__ - - Begins a new MD4 hash\. Returns a token ID that must be used for the - remaining functions\. - - - __::md4::MD4Update__ *token* *data* - - Add data to the hash identified by token\. Calling *MD4Update $token - "abcd"* is equivalent to calling *MD4Update $token "ab"* followed by - *MD4Update $token "cb"*\. See [EXAMPLES](#section4)\. - - - __::md4::MD4Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 16 bytes representing the 128 bit MD4 digest value\. - - - __::md4::HMACInit__ *key* - - This is equivalent to the __::md4::MD4Init__ command except that it - requires the key that will be included in the HMAC\. - - - __::md4::HMACUpdate__ *token* *data* - - - __::md4::HMACFinal__ *token* - - These commands are identical to the MD4 equivalent commands\. - -# EXAMPLES - - % md4::md4 -hex "Tcl does MD4" - 858da9b31f57648a032230447bd15f25 - - % md4::hmac -hex -key Sekret "Tcl does MD4" - c324088e5752872689caedf2a0464758 - - % set tok [md4::MD4Init] - ::md4::1 - % md4::MD4Update $tok "Tcl " - % md4::MD4Update $tok "does " - % md4::MD4Update $tok "MD4" - % md4::Hex [md4::MD4Final $tok] - 858da9b31f57648a032230447bd15f25 - -# REFERENCES - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Rivest, R\., "The MD4 message digest algorithm", in A\.J\. Menezes and S\.A\. - Vanstone, editors, Advances in Cryptology \- CRYPTO '90 Proceedings, pages - 303\-311, Springer\-Verlag, 1991\. - - 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data - Security, Inc, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1321\.txt](http://www\.rfc\-editor\.org/rfc/rfc1321\.txt)\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *md4* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md5](\.\./md5/md5\.md), [sha1](\.\./sha1/sha1\.md) - -# KEYWORDS - -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[md4](\.\./\.\./\.\./\.\./index\.md\#md4), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -1320](\.\./\.\./\.\./\.\./index\.md\#rfc\_1320), [rfc -1321](\.\./\.\./\.\./\.\./index\.md\#rfc\_1321), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2003, Pat Thoyts DELETED embedded/md/tcllib/files/modules/md5/md5.md Index: embedded/md/tcllib/files/modules/md5/md5.md ================================================================== --- embedded/md/tcllib/files/modules/md5/md5.md +++ embedded/md/tcllib/files/modules/md5/md5.md @@ -1,207 +0,0 @@ - -[//000000001]: # (md5 \- MD5 Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'md5\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003, Pat Thoyts ) -[//000000004]: # (md5\(n\) 2\.0\.8 tcllib "MD5 Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -md5 \- MD5 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require md5 ?2\.0\.7? - -[__::md5::md5__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \]](#1) -[__::md5::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \]](#2) -[__::md5::MD5Init__](#3) -[__::md5::MD5Update__ *token* *data*](#4) -[__::md5::MD5Final__ *token*](#5) -[__::md5::HMACInit__ *key*](#6) -[__::md5::HMACUpdate__ *token* *data*](#7) -[__::md5::HMACFinal__ *token*](#8) - -# DESCRIPTION - -This package is an implementation in Tcl of the MD5 message\-digest algorithm as -described in RFC 1321 \(1\)\. This algorithm takes an arbitrary quantity of data -and generates a 128\-bit message digest from the input\. The MD5 algorithm is -related to the MD4 algorithm \(2\) but has been strengthened against certain types -of potential attack\. MD5 should be used in preference to MD4 for new -applications\. - -If you have __critcl__ and have built the __tcllibc__ package then the -implementation of the hashing function will be performed by compiled code\. -Alternatively if you have either __cryptkit__ or __Trf__ then either of -these can be used to accelerate the digest computation\. If no suitable compiled -package is available then the pure\-Tcl implementation wil be used\. The -programming interface remains the same in all cases\. - -*Note* the previous version of this package always returned a hex encoded -string\. This has been changed to simplify the programming interface and to make -this version more compatible with other implementations\. To obtain the previous -usage, either explicitly specify package version 1 or use the *\-hex* option to -the __md5__ command\. - -# COMMANDS - - - __::md5::md5__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate the MD5 digest of the data given in string\. This is returned as a - binary string by default\. Giving the *\-hex* option will return a - hexadecimal encoded version of the digest\. - - The data to be hashed can be specified either as a string argument to the - __md5__ command, or as a filename or a pre\-opened channel\. If the - *\-filename* argument is given then the file is opened, the data read and - hashed and the file is closed\. If the *\-channel* argument is given then - data is read from the channel until the end of file\. The channel is not - closed\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - - __::md5::hmac__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the MD5 - digest algorithm\. HMACs are described in RFC 2104 \(3\) and provide an MD5 - digest that includes a key\. All options other than *\-key* are as for the - __::md5::md5__ command\. - -# PROGRAMMING INTERFACE - -For the programmer, the MD5 hash can be viewed as a bucket into which one pours -data\. When you have finished, you extract a value that is derived from the data -that was poured into the bucket\. The programming interface to the MD5 hash -operates on a token \(equivalent to the bucket\)\. You call __MD5Init__ to -obtain a token and then call __MD5Update__ as many times as required to add -data to the hash\. To release any resources and obtain the hash value, you then -call __MD5Final__\. An equivalent set of functions gives you a keyed digest -\(HMAC\)\. - - - __::md5::MD5Init__ - - Begins a new MD5 hash\. Returns a token ID that must be used for the - remaining functions\. - - - __::md5::MD5Update__ *token* *data* - - Add data to the hash identified by token\. Calling *MD5Update $token - "abcd"* is equivalent to calling *MD5Update $token "ab"* followed by - *MD5Update $token "cb"*\. See [EXAMPLES](#section4)\. - - - __::md5::MD5Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 16 bytes representing the 128 bit MD5 digest value\. - - - __::md5::HMACInit__ *key* - - This is equivalent to the __::md5::MD5Init__ command except that it - requires the key that will be included in the HMAC\. - - - __::md5::HMACUpdate__ *token* *data* - - - __::md5::HMACFinal__ *token* - - These commands are identical to the MD5 equivalent commands\. - -# EXAMPLES - - % md5::md5 -hex "Tcl does MD5" - 8AAC1EE01E20BB347104FABB90310433 - - % md5::hmac -hex -key Sekret "Tcl does MD5" - 35BBA244FD56D3EDF5F3C47474DACB5D - - % set tok [md5::MD5Init] - ::md5::1 - % md5::MD5Update $tok "Tcl " - % md5::MD5Update $tok "does " - % md5::MD5Update $tok "MD5" - % md5::Hex [md5::MD5Final $tok] - 8AAC1EE01E20BB347104FABB90310433 - -# REFERENCES - - 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data - Security, Inc, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1321\.txt](http://www\.rfc\-editor\.org/rfc/rfc1321\.txt)\) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *md5* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md4](\.\./md4/md4\.md), [sha1](\.\./sha1/sha1\.md) - -# KEYWORDS - -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[md5](\.\./\.\./\.\./\.\./index\.md\#md5), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -1320](\.\./\.\./\.\./\.\./index\.md\#rfc\_1320), [rfc -1321](\.\./\.\./\.\./\.\./index\.md\#rfc\_1321), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2003, Pat Thoyts DELETED embedded/md/tcllib/files/modules/md5crypt/md5crypt.md Index: embedded/md/tcllib/files/modules/md5crypt/md5crypt.md ================================================================== --- embedded/md/tcllib/files/modules/md5crypt/md5crypt.md +++ embedded/md/tcllib/files/modules/md5crypt/md5crypt.md @@ -1,135 +0,0 @@ - -[//000000001]: # (md5crypt \- MD5\-based password encryption) -[//000000002]: # (Generated from file 'md5crypt\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003, Pat Thoyts ) -[//000000004]: # (md5crypt\(n\) 1\.1\.0 tcllib "MD5\-based password encryption") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -md5crypt \- MD5\-based password encryption - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [SALT](#section3) - - - [EXAMPLES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require md5 2\.0 -package require md5crypt ?1\.1\.0? - -[__::md5crypt::md5crypt__ *password* *salt*](#1) -[__::md5crypt::aprcrypt__ *password* *salt*](#2) -[__::md5crypt::salt__ ?*length*?](#3) - -# DESCRIPTION - -This package provides an implementation of the MD5\-crypt password encryption -algorithm as pioneered by FreeBSD and currently in use as a replacement for the -unix crypt\(3\) function in many modern systems\. An implementation of the closely -related Apache MD5\-crypt is also available\. The output of these commands are -compatible with the BSD and OpenSSL implementation of md5crypt and the Apache 2 -htpasswd program\. - -# COMMANDS - - - __::md5crypt::md5crypt__ *password* *salt* - - Generate a BSD compatible md5\-encoded password hash from the plaintext - password and a random salt \(see SALT\)\. - - - __::md5crypt::aprcrypt__ *password* *salt* - - Generate an Apache compatible md5\-encoded password hash from the plaintext - password and a random salt \(see SALT\)\. - - - __::md5crypt::salt__ ?*length*? - - Generate a random salt string suitable for use with the __md5crypt__ and - __aprcrypt__ commands\. - -# SALT - -The salt passed to either of the encryption schemes implemented here is checked -to see if it begins with the encryption scheme magic string \(either "$1$" for -MD5\-crypt or "$apr1$" for Apache crypt\)\. If so, this is removed\. The remaining -characters up to the next $ and up to a maximum of 8 characters are then used as -the salt\. The salt text should probably be restricted the set of ASCII -alphanumeric characters plus "\./" \(dot and forward\-slash\) \- this is to preserve -maximum compatability with the unix password file format\. - -If a password is being generated rather than checked from a password file then -the __salt__ command may be used to generate a random salt\. - -# EXAMPLES - - % md5crypt::md5crypt password 01234567 - $1$01234567$b5lh2mHyD2PdJjFfALlEz1 - - % md5crypt::aprcrypt password 01234567 - $apr1$01234567$IXBaQywhAhc0d75ZbaSDp/ - - % md5crypt::md5crypt password [md5crypt::salt] - $1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *md5crypt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md5](\.\./md5/md5\.md) - -# KEYWORDS - -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[md5](\.\./\.\./\.\./\.\./index\.md\#md5), -[md5crypt](\.\./\.\./\.\./\.\./index\.md\#md5crypt), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2003, Pat Thoyts DELETED embedded/md/tcllib/files/modules/mime/mime.md Index: embedded/md/tcllib/files/modules/mime/mime.md ================================================================== --- embedded/md/tcllib/files/modules/mime/mime.md +++ embedded/md/tcllib/files/modules/mime/mime.md @@ -1,390 +0,0 @@ - -[//000000001]: # (mime \- Mime) -[//000000002]: # (Generated from file 'mime\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 1999\-2000 Marshall T\. Rose) -[//000000004]: # (mime\(n\) 1\.6\.3 tcllib "Mime") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -mime \- Manipulation of MIME body parts - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [KNOWN BUGS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require mime ?1\.6\.3? - -[__::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* | __\-string__ *value* | __\-parts__ \{*token1* \.\.\. *tokenN*\}\)](#1) -[__::mime::finalize__ *token* ?__\-subordinates__ __all__ | __dynamic__ | __none__?](#2) -[__::mime::getproperty__ *token* ?*property* | __\-names__?](#3) -[__::mime::getheader__ *token* ?*key* | __\-names__?](#4) -[__::mime::setheader__ *token* *key value* ?__\-mode__ __write__ | __append__ | __delete__?](#5) -[__::mime::getbody__ *token* ?__\-decode__? ?__\-command__ *callback* ?__\-blocksize__ *octets*??](#6) -[__::mime::copymessage__ *token* *channel*](#7) -[__::mime::buildmessage__ *token*](#8) -[__::mime::parseaddress__ *string*](#9) -[__::mime::parsedatetime__ \(*string* | __\-now__\) *property*](#10) -[__::mime::mapencoding__ *encoding\_name*](#11) -[__::mime::reversemapencoding__ *charset\_type*](#12) - -# DESCRIPTION - -The __mime__ library package provides the commands to create and manipulate -MIME body parts\. - - - __::mime::initialize__ ?__\-canonical__ *type/subtype* ?__\-param__ \{*key value*\}\.\.\.? ?__\-encoding__ *value*? ?__\-header__ \{*key value*\}\.\.\.?? \(__\-file__ *name* | __\-string__ *value* | __\-parts__ \{*token1* \.\.\. *tokenN*\}\) - - This command creates a MIME part and returns a token representing it\. - - * If the __\-canonical__ option is present, then the body is in - canonical \(raw\) form and is found by consulting either the - __\-file__, __\-string__, or __\-parts__ option\. - - In addition, both the __\-param__ and __\-header__ options may - occur zero or more times to specify __Content\-Type__ parameters - \(e\.g\., __charset__\) and header keyword/values \(e\.g\., - __Content\-Disposition__\), respectively\. - - Also, __\-encoding__, if present, specifies the - __Content\-Transfer\-Encoding__ when copying the body\. - - * If the __\-canonical__ option is not present, then the MIME part - contained in either the __\-file__ or the __\-string__ option is - parsed, dynamically generating subordinates as appropriate\. - - - __::mime::finalize__ *token* ?__\-subordinates__ __all__ | __dynamic__ | __none__? - - This command destroys the MIME part represented by *token*\. It returns an - empty string\. - - If the __\-subordinates__ option is present, it specifies which - subordinates should also be destroyed\. The default value is __dynamic__, - destroying all subordinates which were created by __::mime::initialize__ - together with the containing body part\. - - - __::mime::getproperty__ *token* ?*property* | __\-names__? - - This command returns a string or a list of strings containing the properties - of a MIME part\. If the command is invoked with the name of a specific - property, then the corresponding value is returned; instead, if - __\-names__ is specified, a list of all properties is returned; - otherwise, a serialized array of properties and values is returned\. - - The possible properties are: - - * __content__ - - The type/subtype describing the content - - * __encoding__ - - The "Content\-Transfer\-Encoding" - - * __params__ - - A list of "Content\-Type" parameters - - * __parts__ - - A list of tokens for the part's subordinates\. This property is present - only if the MIME part has subordinates\. - - * __size__ - - The approximate size of the content \(unencoded\) - - - __::mime::getheader__ *token* ?*key* | __\-names__? - - This command returns the header of a MIME part, as a list of strings\. - - A header consists of zero or more key/value pairs\. Each value is a list - containing one or more strings\. - - If this command is invoked with the name of a specific *key*, then a list - containing the corresponding value\(s\) is returned; instead, if \-names is - specified, a list of all keys is returned; otherwise, a serialized array of - keys and values is returned\. Note that when a key is specified \(e\.g\., - "Subject"\), the list returned usually contains exactly one string; however, - some keys \(e\.g\., "Received"\) often occur more than once in the header, - accordingly the list returned usually contains more than one string\. - - - __::mime::setheader__ *token* *key value* ?__\-mode__ __write__ | __append__ | __delete__? - - This command writes, appends to, or deletes the *value* associated with a - *key* in the header\. It returns a list of strings containing the previous - value associated with the key\. - - The value for __\-mode__ is one of: - - * __write__ - - The *key*/*value* is either created or overwritten \(the default\)\. - - * __append__ - - A new *value* is appended for the *key* \(creating it as necessary\)\. - - * __delete__ - - All values associated with the key are removed \(the *value* parameter - is ignored\)\. - - - __::mime::getbody__ *token* ?__\-decode__? ?__\-command__ *callback* ?__\-blocksize__ *octets*?? - - This command returns a string containing the body of the leaf MIME part - represented by *token* in canonical form\. - - If the __\-command__ option is present, then it is repeatedly invoked - with a fragment of the body as this: - - uplevel #0 $callback [list "data" $fragment] - - \(The __\-blocksize__ option, if present, specifies the maximum size of - each fragment passed to the callback\.\) - - When the end of the body is reached, the callback is invoked as: - - uplevel #0 $callback "end" - - Alternatively, if an error occurs, the callback is invoked as: - - uplevel #0 $callback [list "error" reason] - - Regardless, the return value of the final invocation of the callback is - propagated upwards by __::mime::getbody__\. - - If the __\-command__ option is absent, then the return value of - __::mime::getbody__ is a string containing the MIME part's entire body\. - - If the option __\-decode__ is absent the return value computed above is - returned as is\. This means that it will be in the charset specified for the - token and not the usual utf\-8\. If the option __\-decode__ is present - however the command will use the charset information associated with the - token to convert the string from its encoding into utf\-8 before returning - it\. - - - __::mime::copymessage__ *token* *channel* - - This command copies the MIME represented by *token* part to the specified - *channel*\. The command operates synchronously, and uses fileevent to allow - asynchronous operations to proceed independently\. It returns an empty - string\. - - - __::mime::buildmessage__ *token* - - This command returns the MIME part represented by *token* as a string\. It - is similar to __::mime::copymessage__, only it returns the data as a - return string instead of writing to a channel\. - - - __::mime::parseaddress__ *string* - - This command takes a string containing one or more 822\-style address - specifications and returns a list of serialized arrays, one element for each - address specified in the argument\. If the string contains more than one - address they will be separated by commas\. - - Each serialized array contains the properties below\. Note that one or more - of these properties may be empty\. - - * __address__ - - local@domain - - * __comment__ - - 822\-style comment - - * __domain__ - - the domain part \(rhs\) - - * __error__ - - non\-empty on a parse error - - * __group__ - - this address begins a group - - * __friendly__ - - user\-friendly rendering - - * __local__ - - the local part \(lhs\) - - * __memberP__ - - this address belongs to a group - - * __phrase__ - - the phrase part - - * __proper__ - - 822\-style address specification - - * __route__ - - 822\-style route specification \(obsolete\) - - - __::mime::parsedatetime__ \(*string* | __\-now__\) *property* - - This command takes a string containing an 822\-style date\-time specification - and returns the specified property as a serialized array\. - - The list of properties and their ranges are: - - * __hour__ - - 0 \.\. 23 - - * __lmonth__ - - January, February, \.\.\., December - - * __lweekday__ - - Sunday, Monday, \.\.\. Saturday - - * __mday__ - - 1 \.\. 31 - - * __min__ - - 0 \.\. 59 - - * __mon__ - - 1 \.\. 12 - - * __month__ - - Jan, Feb, \.\.\., Dec - - * __proper__ - - 822\-style date\-time specification - - * __rclock__ - - elapsed seconds between then and now - - * __sec__ - - 0 \.\. 59 - - * __wday__ - - 0 \.\. 6 \(Sun \.\. Mon\) - - * __weekday__ - - Sun, Mon, \.\.\., Sat - - * __yday__ - - 1 \.\. 366 - - * __year__ - - 1900 \.\.\. - - * __zone__ - - \-720 \.\. 720 \(minutes east of GMT\) - - - __::mime::mapencoding__ *encoding\_name* - - This commansd maps tcl encodings onto the proper names for their MIME - charset type\. This is only done for encodings whose charset types were - known\. The remaining encodings return "" for now\. - - - __::mime::reversemapencoding__ *charset\_type* - - This command maps MIME charset types onto tcl encoding names\. Those that are - unknown return ""\. - -# KNOWN BUGS - - - Tcllib Bug \#447037 - - This problem affects only people which are using Tcl and Mime on a 64\-bit - system\. The currently recommended fix for this problem is to upgrade to Tcl - version 8\.4\. This version has extended 64 bit support and the bug does not - appear anymore\. - - The problem could have been generally solved by requiring the use of Tcl 8\.4 - for this package\. We decided against this solution as it would force a large - number of unaffected users to upgrade their Tcl interpreter for no reason\. - - See [Ticket 447037](/tktview?name=447037) for additional information\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *mime* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[ftp](\.\./ftp/ftp\.md), [http](\.\./\.\./\.\./\.\./index\.md\#http), -[pop3](\.\./pop3/pop3\.md), [smtp](smtp\.md) - -# KEYWORDS - -[email](\.\./\.\./\.\./\.\./index\.md\#email), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[mail](\.\./\.\./\.\./\.\./index\.md\#mail), [mime](\.\./\.\./\.\./\.\./index\.md\#mime), -[net](\.\./\.\./\.\./\.\./index\.md\#net), [rfc -2045](\.\./\.\./\.\./\.\./index\.md\#rfc\_2045), [rfc -2046](\.\./\.\./\.\./\.\./index\.md\#rfc\_2046), [rfc -2049](\.\./\.\./\.\./\.\./index\.md\#rfc\_2049), [rfc -821](\.\./\.\./\.\./\.\./index\.md\#rfc\_821), [rfc -822](\.\./\.\./\.\./\.\./index\.md\#rfc\_822), [smtp](\.\./\.\./\.\./\.\./index\.md\#smtp) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 1999\-2000 Marshall T\. Rose DELETED embedded/md/tcllib/files/modules/mime/smtp.md Index: embedded/md/tcllib/files/modules/mime/smtp.md ================================================================== --- embedded/md/tcllib/files/modules/mime/smtp.md +++ embedded/md/tcllib/files/modules/mime/smtp.md @@ -1,277 +0,0 @@ - -[//000000001]: # (smtp \- smtp client) -[//000000002]: # (Generated from file 'smtp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 1999\-2000 Marshall T\. Rose and others) -[//000000004]: # (smtp\(n\) 1\.5 tcllib "smtp client") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -smtp \- Client\-side tcl implementation of the smtp protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Authentication](#section2) - - - [EXAMPLE](#section3) - - - [TLS Security Considerations](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl -package require mime ?1\.5\.4? -package require smtp ?1\.5? - -[__::smtp::sendmessage__ *token* *option*\.\.\.](#1) - -# DESCRIPTION - -The __smtp__ library package provides the client side of the Simple Mail -Transfer Protocol \(SMTP\) \(1\) \(2\)\. - - - __::smtp::sendmessage__ *token* *option*\.\.\. - - This command sends the MIME part \(see package __[mime](mime\.md)__\) - represented by *token* to an SMTP server\. *options* is a list of options - and their associated values\. The recognized options are: - - * __\-servers__ - - A list of SMTP servers\. The default is __localhost__\. - - If multiple servers are specified they are tried in sequence\. Note that - the __\-ports__ are iterated over in tandem with the servers\. If - there are not enough ports for the number of servers the default port - \(see below\) is used\. If there are more ports than servers the - superfluous ports are ignored\. - - * __\-ports__ - - A list of SMTP ports\. The default is __25__\. - - See option __\-servers__ above regardig the behaviour for then - multiple servers and ports are specified\. - - * __\-client__ - - The name to use as our hostname when connecting to the server\. By - default this is either localhost if one of the servers is localhost, or - is set to the string returned by __info hostname__\. - - * __\-queue__ - - Indicates that the SMTP server should be asked to queue the message for - later processing\. A boolean value\. - - * __\-atleastone__ - - Indicates that the SMTP server must find at least one recipient - acceptable for the message to be sent\. A boolean value\. - - * __\-originator__ - - A string containing an 822\-style address specification\. If present the - header isn't examined for an originator address\. - - * __\-recipients__ - - A string containing one or more 822\-style address specifications\. If - present the header isn't examined for recipient addresses\)\. If the - string contains more than one address they will be separated by commas\. - - * __\-header__ - - A list containing two elements, an smtp header and its associated value - \(the \-header option may occur zero or more times\)\. - - * __\-usetls__ - - This package supports the RFC 3207 TLS extension \(3\) by default provided - the tls package is available\. You can turn this off with this boolean - option\. - - * __\-tlsimport__ - - This boolean flag is __false__ by default\. When this flag is set the - package will import TLS on a sucessfully opened channel\. This is needed - for connections using native TLS negotiation instead of - __STARTTLS__\. The __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ - package is automatically required when needed\. - - * __\-tlspolicy__ - - This option lets you specify a command to be called if an error occurs - during TLS setup\. The command is called with the SMTP code and - diagnostic message appended\. The command should return 'secure' or - 'insecure' where insecure will cause the package to continue on the - unencrypted channel\. Returning 'secure' will cause the socket to be - closed and the next server in the __\-servers__ list to be tried\. - - * __\-username__ - - * __\-password__ - - If your SMTP server requires authentication \(RFC 2554 \(4\)\) before - accepting mail you can use __\-username__ and __\-password__ to - provide your authentication details to the server\. Currently this - package supports DIGEST\-MD5, CRAM\-MD5, LOGIN and PLAIN authentication - methods\. The most secure method will be tried first and each method - tried in turn until we are either authorized or we run out of methods\. - Note that if the server permits a TLS connection, then the authorization - will occur after we begin using the secure channel\. - - Please also read the section on [Authentication](#section2), it - details the necessary prequisites, i\.e\. packages needed to support these - options and authentication\. - - If the __\-originator__ option is not present, the originator address is - taken from __From__ \(or __Resent\-From__\); similarly, if the - __\-recipients__ option is not present, recipient addresses are taken - from __To__, __cc__, and __Bcc__ \(or __Resent\-To__, and so - on\)\. Note that the header key/values supplied by the __\-header__ option - \(not those present in the MIME part\) are consulted\. Regardless, header - key/values are added to the outgoing message as necessary to ensure that a - valid 822\-style message is sent\. - - The command returns a list indicating which recipients were unacceptable to - the SMTP server\. Each element of the list is another list, containing the - address, an SMTP error code, and a textual diagnostic\. Depending on the - __\-atleastone__ option and the intended recipients, a non\-empty list may - still indicate that the message was accepted by the server\. - -# Authentication - -Beware\. SMTP authentication uses __[SASL](\.\./sasl/sasl\.md)__\. I\.e\. if -the user has to authenticate a connection, i\.e\. use the options __\-user__ -and __\-password__ \(see above\) it is necessary to have the __sasl__ -package available so that __smtp__ can load it\. - -This is a soft dependency because not everybody requires authentication, and -__sasl__ depends on a lot of the cryptographic \(secure\) hashes, i\.e\. all of -__[md5](\.\./md5/md5\.md)__, __[otp](\.\./otp/otp\.md)__, -__[md4](\.\./md4/md4\.md)__, __[sha1](\.\./sha1/sha1\.md)__, and -__[ripemd160](\.\./ripemd/ripemd160\.md)__\. - -# EXAMPLE - - proc send_simple_message {recipient email_server subject body} { - package require smtp - package require mime - - set token [mime::initialize -canonical text/plain \ - -string $body] - mime::setheader $token Subject $subject - smtp::sendmessage $token \ - -recipients $recipient -servers $email_server - mime::finalize $token - } - - send_simple_message someone@somewhere.com localhost \ - "This is the subject." "This is the message." - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# REFERENCES - - 1. Jonathan B\. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982\. - \([http://www\.rfc\-editor\.org/rfc/rfc821\.txt](http://www\.rfc\-editor\.org/rfc/rfc821\.txt)\) - - 1. J\. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001\. - \([http://www\.rfc\-editor\.org/rfc/rfc2821\.txt](http://www\.rfc\-editor\.org/rfc/rfc2821\.txt)\) - - 1. P\. Hoffman, "SMTP Service Extension for Secure SMTP over Transport Layer - Security", RFC 3207, February 2002\. - \([http://www\.rfc\-editor\.org/rfc/rfc3207\.txt](http://www\.rfc\-editor\.org/rfc/rfc3207\.txt)\) - - 1. J\. Myers, "SMTP Service Extension for Authentication", RFC 2554, March - 1999\. - \([http://www\.rfc\-editor\.org/rfc/rfc2554\.txt](http://www\.rfc\-editor\.org/rfc/rfc2554\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *smtp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[ftp](\.\./ftp/ftp\.md), [http](\.\./\.\./\.\./\.\./index\.md\#http), -[mime](mime\.md), [pop3](\.\./pop3/pop3\.md) - -# KEYWORDS - -[email](\.\./\.\./\.\./\.\./index\.md\#email), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[mail](\.\./\.\./\.\./\.\./index\.md\#mail), [mime](\.\./\.\./\.\./\.\./index\.md\#mime), -[net](\.\./\.\./\.\./\.\./index\.md\#net), [rfc -2554](\.\./\.\./\.\./\.\./index\.md\#rfc\_2554), [rfc -2821](\.\./\.\./\.\./\.\./index\.md\#rfc\_2821), [rfc -3207](\.\./\.\./\.\./\.\./index\.md\#rfc\_3207), [rfc -821](\.\./\.\./\.\./\.\./index\.md\#rfc\_821), [rfc -822](\.\./\.\./\.\./\.\./index\.md\#rfc\_822), [smtp](\.\./\.\./\.\./\.\./index\.md\#smtp), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 1999\-2000 Marshall T\. Rose and others DELETED embedded/md/tcllib/files/modules/multiplexer/multiplexer.md Index: embedded/md/tcllib/files/modules/multiplexer/multiplexer.md ================================================================== --- embedded/md/tcllib/files/modules/multiplexer/multiplexer.md +++ embedded/md/tcllib/files/modules/multiplexer/multiplexer.md @@ -1,157 +0,0 @@ - -[//000000001]: # (multiplexer \- One\-to\-many communication with sockets\.) -[//000000002]: # (Generated from file 'multiplexer\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (multiplexer\(n\) 0\.2 tcllib "One\-to\-many communication with sockets\.") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -multiplexer \- One\-to\-many communication with sockets\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require logger -package require multiplexer ?0\.2? - -[__::multiplexer::create__](#1) -[__$\{multiplexer\_instance\}::Init__ *port*](#2) -[__$\{multiplexer\_instance\}::Config__ *key* *value*](#3) -[__$\{multiplexer\_instance\}::AddFilter__ *cmdprefix*](#4) -[__cmdprefix__ *data* *chan* *clientaddress* *clientport*](#5) -[__$\{multiplexer\_instance\}::AddAccessFilter__ *cmdprefix*](#6) -[__cmdprefix__ *chan* *clientaddress* *clientport*](#7) -[__$\{multiplexer\_instance\}::AddExitFilter__ *cmdprefix*](#8) -[__cmdprefix__ *chan* *clientaddress* *clientport*](#9) - -# DESCRIPTION - -The __multiplexer__ package provides a generic system for one\-to\-many -communication utilizing sockets\. For example, think of a chat system where one -user sends a message which is then broadcast to all the other connected users\. - -It is possible to have different multiplexers running concurrently\. - - - __::multiplexer::create__ - - The __create__ command creates a new multiplexer 'instance'\. For - example: - - set mp [::multiplexer::create] - - This instance can then be manipulated like so: - - ${mp}::Init 35100 - - - __$\{multiplexer\_instance\}::Init__ *port* - - This starts the multiplexer listening on the specified port\. - - - __$\{multiplexer\_instance\}::Config__ *key* *value* - - Use __Config__ to configure the multiplexer instance\. Configuration - options currently include: - - * __sendtoorigin__ - - A boolean flag\. If __true__, the sender will receive a copy of the - sent message\. Defaults to __false__\. - - * __debuglevel__ - - Sets the debug level to use for the multiplexer instance, according to - those specified by the __[logger](\.\./log/logger\.md)__ package - \(debug, info, notice, warn, error, critical\)\. - - - __$\{multiplexer\_instance\}::AddFilter__ *cmdprefix* - - Command to add a filter for data that passes through the multiplexer - instance\. The registered *cmdprefix* is called when data arrives at a - multiplexer instance\. If there is more than one filter command registered at - the instance they will be called in the order of registristation, and each - filter will get the result of the preceding filter as its argument\. The - first filter gets the incoming data as its argument\. The result returned by - the last filter is the data which will be broadcast to all clients of the - multiplexer instance\. The command prefix is called as - - * __cmdprefix__ *data* *chan* *clientaddress* *clientport* - - Takes the incoming *data*, modifies it, and returns that as its - result\. The last three arguments contain information about the client - which sent the data to filter: The channel connecting us to the client, - its ip\-address, and its ip\-port\. - - - __$\{multiplexer\_instance\}::AddAccessFilter__ *cmdprefix* - - Command to add an access filter\. The registered *cmdprefix* is called when - a new client socket tries to connect to the multixer instance\. If there is - more than one access filter command registered at the instance they will be - called in the order of registristation\. If any of the called commands - returns __\-1__ the access to the multiplexer instance is denied and the - client channel is closed immediately\. Any other result grants the client - access to the multiplexer instance\. The command prefix is called as - - * __cmdprefix__ *chan* *clientaddress* *clientport* - - The arguments contain information about the client which tries to - connected to the instance: The channel connecting us to the client, its - ip\-address, and its ip\-port\. - - - __$\{multiplexer\_instance\}::AddExitFilter__ *cmdprefix* - - Adds filter to be run when client socket generates an EOF condition\. The - registered *cmdprefix* is called when a client socket of the multixer - signals EOF\. If there is more than one exit filter command registered at the - instance they will be called in the order of registristation\. Errors thrown - by an exit filter are ignored, but logged\. Any result returned by an exit - filter is ignored\. The command prefix is called as - - * __cmdprefix__ *chan* *clientaddress* *clientport* - - The arguments contain information about the client which signaled the - EOF: The channel connecting us to the client, its ip\-address, and its - ip\-port\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *multiplexer* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[chat](\.\./\.\./\.\./\.\./index\.md\#chat), -[multiplexer](\.\./\.\./\.\./\.\./index\.md\#multiplexer) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/namespacex/namespacex.md Index: embedded/md/tcllib/files/modules/namespacex/namespacex.md ================================================================== --- embedded/md/tcllib/files/modules/namespacex/namespacex.md +++ embedded/md/tcllib/files/modules/namespacex/namespacex.md @@ -1,207 +0,0 @@ - -[//000000001]: # (namespacex \- Namespace utility commands) -[//000000002]: # (Generated from file 'namespacex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 200? Neil Madden \(http://wiki\.tcl\.tk/12790\)) -[//000000004]: # (Copyright © 200? Various \(http://wiki\.tcl\.tk/1489\)) -[//000000005]: # (Copyright © 2010 Documentation, Andreas Kupries) -[//000000006]: # (namespacex\(n\) 0\.2 tcllib "Namespace utility commands") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -namespacex \- Namespace utility commands - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require namespacex ?0\.2? - -[__::namespacex hook add__ ?*namespace*? *cmdprefix*](#1) -[__::namespacex hook proc__ ?*namespace*? *arguments* *body*](#2) -[__::namespacex hook on__ ?*namespace*? *guardcmdprefix* *actioncmdprefix*](#3) -[__::namespacex hook next__ *arg*\.\.\.](#4) -[__::namespacex import fromns__ *cmdname ?*newname* \.\.\.?*](#5) -[__::namespacex info allchildren__ *namespace*](#6) -[__::namespacex info allvars__ *namespace*](#7) -[__::namespacex normalize__ *namespace*](#8) -[__::namespacex info vars__ *namespace* ?*pattern*?](#9) -[__::namespacex state get__ *namespace*](#10) -[__::namespacex state set__ *namespace* *dict*](#11) -[__::namespacex state drop__ *namespace*](#12) -[__::namespacex strip__ *prefix* *namespaces*](#13) - -# DESCRIPTION - -This package provides a number of utility commands for working with namespaces\. -The commands fall into four categories: - - 1. Hook commands provide and manipulate a chain of commands which replaces the - single regular __[namespace - unknown](\.\./\.\./\.\./\.\./index\.md\#namespace\_unknown)__ handler\. - - 1. An import command provides the ability to import any command from another - namespace\. - - 1. Information commands allow querying of variables and child namespaces\. - - 1. State commands provide a means to serialize variable values in a namespace\. - -# Commands - - - __::namespacex hook add__ ?*namespace*? *cmdprefix* - - Adds the *cmdprefix* to the chain of unknown command handlers that are - invoked when the *namespace* would otherwise invoke its unknown handler\. - If *namespace* is not specified, then *cmdprefix* is added to the chain - of handlers for the namespace of the caller\. - - The chain of *cmdprefix* are executed in reverse order of addition, - *i\.e\.* the most recently added *cmdprefix* is executed first\. When - executed, *cmdprefix* has additional arguments appended to it as would any - namespace unknown handler\. - - - __::namespacex hook proc__ ?*namespace*? *arguments* *body* - - Adds an anonymous procedure to the chain of namespace unknown handlers for - the *namespace*\. - - If *namespace* is not specified, then the handler is added to the chain of - handlers for the namespace of the caller\. - - The *arguments* and *body* are specified as for the core - __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ command\. - - - __::namespacex hook on__ ?*namespace*? *guardcmdprefix* *actioncmdprefix* - - Adds a guarded action to the chain of namespace unknown handlers for the - *namespace*\. - - If *namespace* is not specified, then the handler is added to the chain of - handlers for the namespace of the caller\. - - The *guardcmdprefix* is executed first\. If it returns a value that can be - interpreted as false, then the next unknown hander in the chain is executed\. - Otherwise, *actioncmdprefix* is executed and the return value of the - handler is the value returned by *actioncmdprefix*\. - - When executed, both *guardcmdprefix* and *actioncmdprefix* have the same - additional arguments appended as for any namespace unknown handler\. - - - __::namespacex hook next__ *arg*\.\.\. - - This command is available to namespace hooks to execute the next hook in the - chain of handlers for the namespace\. - - - __::namespacex import fromns__ *cmdname ?*newname* \.\.\.?* - - Imports the command *cmdname* from the *fromns* namespace into the - namespace of the caller\. The *cmdname* command is imported even if the - *fromns* did not originally export the command\. - - If *newname* is specified, then the imported command will be known by that - name\. Otherwise, the command retains is original name as given by - *cmdname*\. - - Additional pairs of *cmdname* / *newname* arguments may also be - specified\. - - - __::namespacex info allchildren__ *namespace* - - Returns a list containing the names of all child namespaces in the specified - *namespace* and its children\. The names are all fully qualified\. - - - __::namespacex info allvars__ *namespace* - - Returns a list containing the names of all variables in the specified - *namespace* and its children\. The names are all given relative to - *namespace*, and *not* fully qualified\. - - - __::namespacex normalize__ *namespace* - - Returns the absolute name of *namespace*, which is resolved relative to - the namespace of the caller, with all unneeded colon characters removed\. - - - __::namespacex info vars__ *namespace* ?*pattern*? - - Returns a list containing the names of all variables in the specified - *namespace*\. If the *pattern* argument is specified, then only variables - matching *pattern* are returned\. Matching is determined using the same - rules as for __string match__\. - - - __::namespacex state get__ *namespace* - - Returns a dictionary holding the names and values of all variables in the - specified *namespace* and its child namespaces\. - - Note that the names are all relative to *namespace*, and *not* fully - qualified\. - - - __::namespacex state set__ *namespace* *dict* - - Takes a dictionary holding the names and values for a set of variables and - replaces the current state of the specified *namespace* and its child - namespaces with this state\. The result of the command is the empty string\. - - - __::namespacex state drop__ *namespace* - - Unsets all variables in the specified *namespace* and its child - namespaces\. The result of the command is the empty string\. - - - __::namespacex strip__ *prefix* *namespaces* - - Each item in *namespaces* must be the absolute normalized name of a child - namespace of namespace *prefix*\. Returns the corresponding list of - relative names of child namespaces\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *namespacex* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[extended namespace](\.\./\.\./\.\./\.\./index\.md\#extended\_namespace), -[info](\.\./\.\./\.\./\.\./index\.md\#info), [namespace -unknown](\.\./\.\./\.\./\.\./index\.md\#namespace\_unknown), [namespace -utilities](\.\./\.\./\.\./\.\./index\.md\#namespace\_utilities), [state -\(de\)serialization](\.\./\.\./\.\./\.\./index\.md\#state\_de\_serialization), [unknown -hooking](\.\./\.\./\.\./\.\./index\.md\#unknown\_hooking), -[utilities](\.\./\.\./\.\./\.\./index\.md\#utilities) - -# COPYRIGHT - -Copyright © 200? Neil Madden \(http://wiki\.tcl\.tk/12790\) -Copyright © 200? Various \(http://wiki\.tcl\.tk/1489\) -Copyright © 2010 Documentation, Andreas Kupries DELETED embedded/md/tcllib/files/modules/ncgi/ncgi.md Index: embedded/md/tcllib/files/modules/ncgi/ncgi.md ================================================================== --- embedded/md/tcllib/files/modules/ncgi/ncgi.md +++ embedded/md/tcllib/files/modules/ncgi/ncgi.md @@ -1,353 +0,0 @@ - -[//000000001]: # (ncgi \- CGI Support) -[//000000002]: # (Generated from file 'ncgi\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (ncgi\(n\) 1\.4\.4 tcllib "CGI Support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ncgi \- Procedures to manipulate CGI values\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require ncgi ?1\.4\.4? - -[__::ncgi::cookie__ *cookie*](#1) -[__::ncgi::decode__ *str*](#2) -[__::ncgi::empty__ *name*](#3) -[__::ncgi::exists__ *name*](#4) -[__::ncgi::encode__ *string*](#5) -[__::ncgi::header__ ?*type*? *args*](#6) -[__::ncgi::import__ *cginame* ?*tclname*?](#7) -[__::ncgi::importAll__ *args*](#8) -[__::ncgi::importFile__ *cmd* *cginame* ?*filename*?](#9) -[__::ncgi::input__ ?*fakeinput*? ?*fakecookie*?](#10) -[__::ncgi::multipart__ *type query*](#11) -[__::ncgi::nvlist__](#12) -[__::ncgi::names__](#13) -[__::ncgi::parse__](#14) -[__::ncgi::parseMimeValue__ *value*](#15) -[__::ncgi::query__](#16) -[__::ncgi::redirect__ *url*](#17) -[__::ncgi::reset__ *query type*](#18) -[__::ncgi::setCookie__ *args*](#19) -[__::ncgi::setDefaultValue__ *key defvalue*](#20) -[__::ncgi::setDefaultValueList__ *key defvaluelist*](#21) -[__::ncgi::setValue__ *key value*](#22) -[__::ncgi::setValueList__ *key valuelist*](#23) -[__::ncgi::type__](#24) -[__::ncgi::urlStub__ ?*url*?](#25) -[__::ncgi::value__ *key* ?*default*?](#26) -[__::ncgi::valueList__ *key* ?*default*?](#27) - -# DESCRIPTION - -The __ncgi__ package provides commands that manipulate CGI values\. These are -values that come from Web forms and are processed either by CGI scripts or web -pages with embedded Tcl code\. Use the __ncgi__ package to query these -values, set and get cookies, and encode and decode www\-url\-encoded values\. - -In the simplest case, a CGI script first calls __::ncgi::parse__ and then -calls __::ncgi::value__ to get different form values\. If a CGI value is -repeated, you should use __::ncgi::valueList__ to get back the complete list -of values\. - -An alternative to __::ncgi::parse__ is __::ncgi::input__, which has -semantics similar to Don Libes' __cgi\_input__ procedure\. -__::ncgi::input__ restricts repeated CGI values to have names that end with -"List"\. In this case, __::ncgi::value__ will return the complete list of -values, and __::ncgi::input__ will raise errors if it find repeated form -elements without the right name\. - -The __::ncgi::reset__ procedure can be used in test suites and Web servers -to initialize the source of the CGI values\. Otherwise the values are read in -from the CGI environment\. - -The complete set of procedures is described below\. - - - __::ncgi::cookie__ *cookie* - - Return a list of values for *cookie*, if any\. It is possible that more - than one cookie with the same name can be present, so this procedure returns - a list\. - - - __::ncgi::decode__ *str* - - Decode strings in www\-url\-encoding, which represents special characters with - a %xx sequence, where xx is the character code in hex\. - - - __::ncgi::empty__ *name* - - Returns 1 if the CGI variable *name* is not present or has the empty - string as its value\. - - - __::ncgi::exists__ *name* - - The return value is a boolean\. It returns __0__ if the CGI variable - *name* is not present, and __1__ otherwise\. - - - __::ncgi::encode__ *string* - - Encode *string* into www\-url\-encoded format\. - - - __::ncgi::header__ ?*type*? *args* - - Output the CGI header to standard output\. This emits a Content\-Type: header - and additional headers based on *args*, which is a list of header names - and header values\. The *type* defaults to "text/html"\. - - - __::ncgi::import__ *cginame* ?*tclname*? - - This creates a variable in the current scope with the value of the CGI - variable *cginame*\. The name of the variable is *tclname*, or - *cginame* if *tclname* is empty \(default\)\. - - - __::ncgi::importAll__ *args* - - This imports several CGI variables as Tcl variables\. If *args* is empty, - then every CGI value is imported\. Otherwise each CGI variable listed in - *args* is imported\. - - - __::ncgi::importFile__ *cmd* *cginame* ?*filename*? - - This provides information about an uploaded file from a form input field of - type __file__ with name *cginame*\. *cmd* can be one of - __\-server__ __\-client__, __\-type__ or __\-data__\. - - * __\-client__ *cginame* - - returns the filename as sent by the client\. - - * __\-type__ *cginame* - - returns the mime type of the uploaded file\. - - * __\-data__ *cginame* - - returns the contents of the file\. - - * __\-server__ *cginame* *filename* - - writes the file contents to a local temporary file \(or *filename* if - supplied\) and returns the name of the file\. The caller is responsible - for deleting this file after use\. - - - __::ncgi::input__ ?*fakeinput*? ?*fakecookie*? - - This reads and decodes the CGI values from the environment\. It restricts - repeated form values to have a trailing "List" in their name\. The CGI values - are obtained later with the __::ncgi::value__ procedure\. - - - __::ncgi::multipart__ *type query* - - This procedure parses a multipart/form\-data *query*\. This is used by - __::ncgi::nvlist__ and not normally called directly\. It returns an - alternating list of names and structured values\. Each structure value is in - turn a list of two elements\. The first element is meta\-data from the - multipart/form\-data structure\. The second element is the form value\. If you - use __::ncgi::value__ you just get the form value\. If you use - __::ncgi::valueList__ you get the structured value with meta data and - the value\. - - The *type* is the whole Content\-Type, including the parameters like - *boundary*\. This returns a list of names and values that describe the - multipart data\. The values are a nested list structure that has some - descriptive information first, and the actual form value second\. The - descriptive information is list of header names and values that describe the - content\. - - - __::ncgi::nvlist__ - - This returns all the query data as a name, value list\. In the case of - multipart/form\-data, the values are structured as described in - __::ncgi::multipart__\. - - - __::ncgi::names__ - - This returns all names found in the query data, as a list\. - __::ncgi::multipart__\. - - - __::ncgi::parse__ - - This reads and decodes the CGI values from the environment\. The CGI values - are obtained later with the __::ncgi::value__ procedure\. IF a CGI value - is repeated, then you should use __::ncgi::valueList__ to get the - complete list of values\. - - - __::ncgi::parseMimeValue__ *value* - - This decodes the Content\-Type and other MIME headers that have the form of - "primary value; param=val; p2=v2" It returns a list, where the first element - is the primary value, and the second element is a list of parameter names - and values\. - - - __::ncgi::query__ - - This returns the raw query data\. - - - __::ncgi::redirect__ *url* - - Generate a response that causes a 302 redirect by the Web server\. The - *url* is the new URL that is the target of the redirect\. The URL will be - qualified with the current server and current directory, if necessary, to - convert it into a full URL\. - - - __::ncgi::reset__ *query type* - - Set the query data and Content\-Type for the current CGI session\. This is - used by the test suite and by Web servers to initialize the ncgi module so - it does not try to read standard input or use environment variables to get - its data\. If neither *query* or *type* are specified, then the - __ncgi__ module will look in the standard CGI environment for its data\. - - - __::ncgi::setCookie__ *args* - - Set a cookie value that will be returned as part of the reply\. This must be - done before __::ncgi::header__ or __::ncgi::redirect__ is called in - order for the cookie to be returned properly\. The *args* are a set of - flags and values: - - * __\-name__ *name* - - * __\-value__ *value* - - * __\-expires__ *date* - - * __\-path__ *path restriction* - - * __\-domain__ *domain restriction* - - - __::ncgi::setDefaultValue__ *key defvalue* - - Set a CGI value if it does not already exists\. This affects future calls to - __::ncgi::value__ \(but not future calls to __::ncgi::nvlist__\)\. If - the CGI value already is present, then this procedure has no side effects\. - - - __::ncgi::setDefaultValueList__ *key defvaluelist* - - Like __::ncgi::setDefaultValue__ except that the value already has list - structure to represent multiple checkboxes or a multi\-selection\. - - - __::ncgi::setValue__ *key value* - - Set a CGI value, overriding whatever was present in the CGI environment - already\. This affects future calls to __::ncgi::value__ \(but not future - calls to __::ncgi::nvlist__\)\. - - - __::ncgi::setValueList__ *key valuelist* - - Like __::ncgi::setValue__ except that the value already has list - structure to represent multiple checkboxes or a multi\-selection\. - - - __::ncgi::type__ - - Returns the Content\-Type of the current CGI values\. - - - __::ncgi::urlStub__ ?*url*? - - Returns the current URL, but without the protocol, server, and port\. If - *url* is specified, then it defines the URL for the current session\. That - value will be returned by future calls to __::ncgi::urlStub__ - - - __::ncgi::value__ *key* ?*default*? - - Return the CGI value identified by *key*\. If the CGI value is not present, - then the *default* value is returned instead\. This value defaults to the - empty string\. - - If the form value *key* is repeated, then there are two cases: if - __::ncgi::parse__ was called, then __::ncgi::value__ only returns - the first value associated with *key*\. If __::ncgi::input__ was - called, then __::ncgi::value__ returns a Tcl list value and *key* must - end in "List" \(e\.g\., "skuList"\)\. In the case of multipart/form\-data, this - procedure just returns the value of the form element\. If you want the - meta\-data associated with each form value, then use - __::ncgi::valueList__\. - - - __::ncgi::valueList__ *key* ?*default*? - - Like __::ncgi::value__, but this always returns a list of values \(even - if there is only one value\)\. In the case of multipart/form\-data, this - procedure returns a list of two elements\. The first element is meta\-data in - the form of a parameter, value list\. The second element is the form value\. - -# EXAMPLES - -Uploading a file - - HTML: - - - Path:
- Name:
- - - - - TCL: upload.cgi - #!/usr/local/bin/tclsh - - ::ncgi::parse - set filedata [::ncgi::value filedata] - set filedesc [::ncgi::value filedesc] - - puts " File uploaded at $filedesc " - - set filename /www/images/$filedesc - - set fh [open $filename w] - puts -nonewline $fh $filedata - close $fh - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ncgi* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[html](\.\./html/html\.md) - -# KEYWORDS - -[CGI](\.\./\.\./\.\./\.\./index\.md\#cgi), [cookie](\.\./\.\./\.\./\.\./index\.md\#cookie), -[form](\.\./\.\./\.\./\.\./index\.md\#form), [html](\.\./\.\./\.\./\.\./index\.md\#html) - -# CATEGORY - -CGI programming DELETED embedded/md/tcllib/files/modules/nettool/nettool.md Index: embedded/md/tcllib/files/modules/nettool/nettool.md ================================================================== --- embedded/md/tcllib/files/modules/nettool/nettool.md +++ embedded/md/tcllib/files/modules/nettool/nettool.md @@ -1,227 +0,0 @@ - -[//000000001]: # (nettool \- nettool) -[//000000002]: # (Generated from file 'nettool\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015\-2018 Sean Woods ) -[//000000004]: # (nettool\(n\) 0\.5\.2 tcllib "nettool") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nettool \- Tools for networked applications - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require nettool ?0\.5\.2? -package require twapi 3\.1 -package require ip 0\.1 -package require platform 0\.1 - -[__::cat__ *filename*](#1) -[__::nettool::allocate\_port__ *startingport*](#2) -[__::nettool::arp\_table__](#3) -[__::nettool::broadcast\_list__](#4) -[__::nettool::claim\_port__ *port* ?*protocol*?](#5) -[__::nettool::cpuinfo__ *args*](#6) -[__::nettool::find\_port__ *startingport*](#7) -[__::nettool::hwid\_list__](#8) -[__::nettool::ip\_list__](#9) -[__::nettool::mac\_list__](#10) -[__::nettool::network\_list__](#11) -[__::nettool::port\_busy__ *port*](#12) -[__::nettool::release\_port__ *port* ?*protocol*?](#13) -[__::nettool::status__](#14) -[__::nettool::user\_data\_root__ *appname*](#15) - -# DESCRIPTION - -The __nettool__ package consists of a Pure\-tcl set of tools to perform -common network functions that would normally require different packages or calls -to exec, in a standard Tcl interface\. At present nettool has reference -implementations for the following operating systems: Windows, MacOSX, and Linux -\(debian\)\. - -# Commands - - - __::cat__ *filename* - - Dump the contents of a file as a result\. - - - __::nettool::allocate\_port__ *startingport* - - Attempt to allocate *startingport*, or, if busy, advance the port number - sequentially until a free port is found, and claim that port\. This command - uses a built\-in database of known ports to avoid returning a port which is - in common use\. \(For example: http \(80\)\) - - - __::nettool::arp\_table__ - - Dump the contents of this computer's Address Resolution Protocol \(ARP\) - table\. The result will be a Tcl formatted list: *macid* *ipaddrlist* \.\.\. - - - __::nettool::broadcast\_list__ - - Returns a list of broadcast addresses \(suitable for UDP multicast\) that this - computer is associated with\. - - - __::nettool::claim\_port__ *port* ?*protocol*? - - Mark *port* as busy, optionally as either __tcp__ \(default\) or - __udp__\. - - - __::nettool::cpuinfo__ *args* - - If no arguments are given, return a key/value list describing the CPU of the - present machine\. Included in the matrix is info on the number of - cores/processors that are available for parallel tasking, installed physical - RAM, and processor family\. - - The exact contents are platform specific\. - - For Linux, information is drawn from /proc/cpuinfo and /proc/meminfo\. - - For MacOSX, information is drawn from sysctl - - For Windows, information is draw from TWAPI\. - - If arguments are given, the result with be a key/value list limited to the - fields requested\. - - Canonical fields for all platforms: - - * cpus - - Count of CPUs/cores/execution units - - * speed - - Clock speed of processor\(s\) in Mhz - - * memory - - Installed RAM \(in MB\) - - * vendor - - Manufacturer - - - __::nettool::find\_port__ *startingport* - - Return *startingport* if it is available, or the next free port after - *startingport*\. Note: Unlike __::nettool::allocate\_port__, this - command does not claim the port\. - - This command uses a built\-in database of known ports to avoid returning a - port which is in common use\. \(For example: http \(80\)\) - - - __::nettool::hwid\_list__ - - Return a list of hardware specific identifiers from this computer\. The - source and content will vary by platform\. - - For MacOSX, the motherboard serial number and macids for all network devices - is returned\. - - For Windows, the volume serial number of C and macids for all network - devices is returned\. - - For Linux, macids for all network devices is returned\. - - - __::nettool::ip\_list__ - - Return a list of IP addresses associated with this computer\. - - - __::nettool::mac\_list__ - - Return a list of MACIDs for the network cards attached to this machine\. The - MACID of the primary network card is returned first\. - - - __::nettool::network\_list__ - - Return a list of networks associated with this computer\. Networks are - formated with __ip::nativeToPrefix__\. - - - __::nettool::port\_busy__ *port* - - Return true if *port* is claimed, false otherwise\. - - - __::nettool::release\_port__ *port* ?*protocol*? - - Mark *port* as not busy, optionally as either __tcp__ \(default\) or - __udp__\. - - - __::nettool::status__ - - Return a key/value list describing the status of the computer\. The output is - designed to be comparable to the output of __top__ for all platforms\. - - Common fields include: - - * load - - Processes per processing unit - - * memory\_total - - Total physical RAM \(MB\) - - * memory\_free - - Total physical RAM unused \(MB\) - - - __::nettool::user\_data\_root__ *appname* - - Return a fully qualified path to a folder where *appname* should store - it's data\. The path is not created, only computed, by this command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *odie* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[nettool](\.\./\.\./\.\./\.\./index\.md\#nettool), -[odie](\.\./\.\./\.\./\.\./index\.md\#odie) - -# CATEGORY - -System - -# COPYRIGHT - -Copyright © 2015\-2018 Sean Woods DELETED embedded/md/tcllib/files/modules/nmea/nmea.md Index: embedded/md/tcllib/files/modules/nmea/nmea.md ================================================================== --- embedded/md/tcllib/files/modules/nmea/nmea.md +++ embedded/md/tcllib/files/modules/nmea/nmea.md @@ -1,182 +0,0 @@ - -[//000000001]: # (nmea \- NMEA protocol implementation) -[//000000002]: # (Generated from file 'nmea\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009, Aaron Faupell ) -[//000000004]: # (nmea\(n\) 1\.0\.0 tcllib "NMEA protocol implementation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nmea \- Process NMEA data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require nmea ?1\.0\.0? - -[__::nmea::input__ *sentence*](#1) -[__::nmea::open\_port__ *port* ?speed?](#2) -[__::nmea::close\_port__](#3) -[__::nmea::configure\_port__ *settings*](#4) -[__::nmea::open\_file__ *file* ?rate?](#5) -[__::nmea::close\_file__](#6) -[__::nmea::do\_line__](#7) -[__::nmea::rate__](#8) -[__::nmea::log__ ?file?](#9) -[__::nmea::checksum__ *data*](#10) -[__::nmea::write__ *sentence* *data*](#11) -[__::nmea::event__ *setence* ?command?](#12) - -# DESCRIPTION - -This package provides a standard interface for writing software which recieves -NMEA standard input data\. It allows for reading data from COM ports, files, or -programmatic input\. It also supports the checksumming and logging of incoming -data\. After parsing, input is dispatched to user defined handler commands for -processing\. To define a handler, see the -__[event](\.\./\.\./\.\./\.\./index\.md\#event)__ command\. There are no GPS -specific functions in this package\. NMEA data consists of a sentence type, -followed by a list of data\. - -# COMMANDS - - - __::nmea::input__ *sentence* - - Processes and dispatches the supplied sentence\. If *sentence* contains no - commas it is treated as a Tcl list, otherwise it must be standard comma - delimited NMEA data, with an optional checksum and leading __$__\. - - nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39} - nmea::input [list GPGSA A 3 04 05 09 12 "" "" 24 "" "" "" 2.5 1.3 2.1] - - - __::nmea::open\_port__ *port* ?speed? - - Open the specified COM port and read NMEA sentences when available\. Port - speed is set to 4800bps by default or to *speed*\. - - - __::nmea::close\_port__ - - Close the com port connection if one is open\. - - - __::nmea::configure\_port__ *settings* - - Changes the current port settings\. *settings* has the same format as - fconfigure \-mode\. - - - __::nmea::open\_file__ *file* ?rate? - - Open file *file* and read NMEA sentences, one per line, at the rate - specified by ?rate? in milliseconds\. The file format may omit the leading - __$__ and/or the checksum\. If rate is <= 0 \(the default\) then lines will - only be processed when a call to __do\_line__ is made\. - - - __::nmea::close\_file__ - - Close the open file if one exists\. - - - __::nmea::do\_line__ - - If there is a currently open file, this command will read and process a - single line from it\. Returns the number of lines read\. - - - __::nmea::rate__ - - Sets the rate at which lines are processed from the open file, in - milliseconds\. The rate remains consistant across files, there does not need - to be a file currently open to use this command\. Set to 0 to disable - automatic line processing\. - - - __::nmea::log__ ?file? - - Starts or stops input logging\. If a file name is specified then all NMEA - data recieved on the open port will be logged to the ?file? in append mode\. - If file is an empty string then any logging will be stopped\. If no file is - specified then returns a boolean value indicating if logging is currently - enabled\. Data written to the port by __write__, data read from files, or - input made using __input__, is not logged\. - - - __::nmea::checksum__ *data* - - Returns the checksum of the supplied data\. - - - __::nmea::write__ *sentence* *data* - - If there is a currently open port, this command will write the specified - sentence and data to the port in proper NMEA checksummed format\. - - - __::nmea::event__ *setence* ?command? - - Registers a handler proc for a given NMEA *sentence*\. There may be at most - one handler per sentence, any existing handler is replaced\. If no command is - specified, returns the name of the current handler for the given *setence* - or an empty string if none exists\. In addition to the incoming sentences - there are 2 builtin types, EOF and DEFAULT\. The handler for the DEFAULT - setence is invoked if there is not a specific handler for that sentence\. The - EOF handler is invoked when End Of File is reached on the open file or port\. - - The handler procedures, with the exception of the builtin types,must take - exactly one argument, which is a list of the data values\. The DEFAULT - handler should have two arguments, the sentence type and the data values\. - The EOF handler has no arguments\. - - nmea::event gpgsa parse_sat_detail - nmea::event default handle_unknown - - proc parse_sat_detail {data} { - puts [lindex $data 1] - } - - proc handle_unknown {name data} { - puts "unknown data type $name" - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nmea* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[gps](\.\./\.\./\.\./\.\./index\.md\#gps), [nmea](\.\./\.\./\.\./\.\./index\.md\#nmea) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2006\-2009, Aaron Faupell DELETED embedded/md/tcllib/files/modules/nns/nns_auto.md Index: embedded/md/tcllib/files/modules/nns/nns_auto.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_auto.md +++ embedded/md/tcllib/files/modules/nns/nns_auto.md @@ -1,162 +0,0 @@ - -[//000000001]: # (nameserv::auto \- Name service facility) -[//000000002]: # (Generated from file 'nns\_auto\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nameserv::auto\(n\) 0\.3 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nameserv::auto \- Name service facility, Client Extension - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [OPTIONS](#section3) - - - [EVENTS](#section4) - - - [DESIGN](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require nameserv::auto ?0\.3? -package require nameserv - -# DESCRIPTION - -Please read the document *[Name service facility, -introduction](nns\_intro\.md)* first\. - -This package provides the *exact* same API as is provided by package -__[nameserv](nns\_client\.md)__, i\.e\. the regular name service client\. It -differs from the former by taking measures to ensure that longer\-lived data, -i\.e\. bound names, continuous and unfullfilled async searches, survive the loss -of the connection to the name server as much as is possible\. - -This means that the bound names and continuous and unfullfilled async searches -are remembered client\-side and automatically re\-entered into the server when the -connection comes back after its loss\. For bound names there is one important -limitation to such restoration: It is possible that a name of this client was -bound by a different client while the connection was gone\. Such names are fully -lost, and the best the package can and will do is to inform the user of this\. - -# API - -The user\-visible API is mainly identical to the API of -__[nameserv](nns\_client\.md)__ and is therefore not described here\. -Please read the documentation of __[nameserv](nns\_client\.md)__\. - -The differences are explained below, in the sections [OPTIONS](#section3) -and [EVENTS](#section4)\. - -# OPTIONS - -This package supports all the options of package -__[nameserv](nns\_client\.md)__, plus one more\. The additional option -allows the user to specify the time interval between attempts to restore a lost -connection\. - - - __\-delay__ *milliseconds* - - The value of this option is an integer value > 0 which specifies the - interval to wait between attempts to restore a lost connection, in - milliseconds\. The default value is __1000__, i\.e\. one second\. - -# EVENTS - -This package generates all of the events of package -__[nameserv](nns\_client\.md)__, plus two more\. Both events are generated -for the tag *[nameserv](nns\_client\.md)*\. - - - *lost\-name* - - This event is generated when a bound name is truly lost, i\.e\. could not be - restored after the temporary loss of the connection to the name server\. It - indicates that a different client took ownership of the name while this - client was out of contact\. - - The detail information of the event will be a Tcl dictionary containing two - keys, __name__, and __data__\. Their values hold all the information - about the lost name\. - - - *re\-connection* - - This event is generated when the connection to the server is restored\. The - remembered data has been restored when the event is posted\. - - The event has no detail information\. - -# DESIGN - -The package is implemented on top of the regular nameservice client, i\.e\. -package __[nameserv](nns\_client\.md)__\. It detects the loss of the -connection by listening for *lost\-connection* events, on the tag -*[nameserv](nns\_client\.md)*\. - -It reacts to such events by starting a periodic timer and trying to reconnect to -the server whenver this timer triggers\. On success the timer is canceled, a -*re\-connection* event generated, and the package proceeds to re\-enter the -remembered bound names and continuous searches\. - -Another loss of the connection, be it during or after re\-entering the remembered -information simply restarts the timer and subsequent reconnection attempts\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv\(n\)](nns\_client\.md) - -# KEYWORDS - -[automatic](\.\./\.\./\.\./\.\./index\.md\#automatic), -[client](\.\./\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[reconnect](\.\./\.\./\.\./\.\./index\.md\#reconnect), -[restore](\.\./\.\./\.\./\.\./index\.md\#restore) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nns/nns_client.md Index: embedded/md/tcllib/files/modules/nns/nns_client.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_client.md +++ embedded/md/tcllib/files/modules/nns/nns_client.md @@ -1,373 +0,0 @@ - -[//000000001]: # (nameserv \- Name service facility) -[//000000002]: # (Generated from file 'nns\_client\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nameserv\(n\) 0\.4\.2 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nameserv \- Name service facility, Client - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [CONNECTION HANDLING](#section3) - - - [EVENTS](#section4) - - - [OPTIONS](#section5) - - - [ASYNCHRONOUS AND CONTINUOUS SEARCHES](#section6) - - - [HISTORY](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require nameserv ?0\.4\.2? -package require comm -package require logger - -[__::nameserv::bind__ *name* *data*](#1) -[__::nameserv::release__](#2) -[__::nameserv::search__ ?__\-async__|__\-continuous__? ?*pattern*?](#3) -[__::nameserv::protocol__](#4) -[__::nameserv::server\_protocol__](#5) -[__::nameserv::server\_features__](#6) -[__::nameserv::cget__ __\-option__](#7) -[__::nameserv::configure__](#8) -[__::nameserv::configure__ __\-option__](#9) -[__::nameserv::configure__ __\-option__ *value*\.\.\.](#10) -[__$result__ __destroy__](#11) -[__$result__ __filled__](#12) -[__$result__ __get__ *name*](#13) -[__$result__ __names__](#14) -[__$result__ __size__](#15) -[__$result__ __getall__ ?*pattern*?](#16) - -# DESCRIPTION - -Please read *[Name service facility, introduction](nns\_intro\.md)* first\. - -This package provides a client for the name service facility implemented by the -package __[nameserv::server](nns\_server\.md)__\. - -This service is built in top of and for the package -__[comm](\.\./comm/comm\.md)__\. It has nothing to do with the Internet's -Domain Name System\. If the reader is looking for a package dealing with that -please see Tcllib's packages __[dns](\.\./dns/tcllib\_dns\.md)__ and -__resolv__\. - -# API - -The package exports eight commands, as specified below: - - - __::nameserv::bind__ *name* *data* - - The caller of this command registers the given *name* as its name in the - configured name service, and additionally associates a piece of *data* - with it\. The service does nothing with this information beyond storing it - and delivering it as part of search results\. The meaning is entirely up to - the applications using the name service\. - - A generally useful choice would for example be an identifier for a - communication endpoint managed by the package - __[comm](\.\./comm/comm\.md)__\. Anybody retrieving the name becomes - immediately able to talk to this endpoint, i\.e\. the registering application\. - - Of further importance is that a caller can register itself under more than - one name, and each name can have its own piece of *data*\. - - Note that the name service, and thwerefore this command, will throw an error - if the chosen name is already registered\. - - - __::nameserv::release__ - - Invoking this command releases all names \(and their data\) registered by all - previous calls to __::nameserv::bind__ of this client\. Note that the - name service will run this command implicitly when it loses the connection - to this client\. - - - __::nameserv::search__ ?__\-async__|__\-continuous__? ?*pattern*? - - This command searches the name service for all registered names matching the - specified glob\-*pattern*\. If not specified the pattern defaults to - __\*__, matching everything\. The result of the command is a dictionary - mapping the matching names to the data associated with them at - *[bind](\.\./\.\./\.\./\.\./index\.md\#bind)*\-time\. - - If either option __\-async__ or __\-continuous__ were specified the - result of this command changes and becomes the Tcl command of an object - holding the actual result\. These two options are supported if and only if - the service the client is connected to supports the protocol feature - *Search/Continuous*\. - - For __\-async__ the result object is asynchronously filled with the - entries matching the pattern at the time of the search and then not modified - any more\. The option __\-continuous__ extends this behaviour by - additionally continuously monitoring the service for the addition and - removal of entries which match the pattern, and updating the object's - contents appropriately\. - - *Note* that the caller is responsible for configuring the object with a - callback for proper notification when the current result \(or further - changes\) arrive\. - - For more information about this object see section [ASYNCHRONOUS AND - CONTINUOUS SEARCHES](#section6)\. - - - __::nameserv::protocol__ - - This command returns the highest version of the name service protocol - supported by the package\. - - - __::nameserv::server\_protocol__ - - This command returns the highest version of the name service protocol - supported by the name service the client is currently connected to\. - - - __::nameserv::server\_features__ - - This command returns a list containing the names of the features of the name - service protocol which are supported by the name service the client is - currently connected to\. - - - __::nameserv::cget__ __\-option__ - - This command returns the currently configured value for the specified - __\-option__\. The list of supported options and their meaning can be - found in section [OPTIONS](#section5)\. - - - __::nameserv::configure__ - - In this form the command returns a dictionary of all supported options, and - their current values\. The list of supported options and their meaning can be - found in section [OPTIONS](#section5)\. - - - __::nameserv::configure__ __\-option__ - - In this form the command is an alias for "__::nameserv::cget__ - __\-option__"\. The list of supported options and their meaning can be - found in section [OPTIONS](#section5)\. - - - __::nameserv::configure__ __\-option__ *value*\.\.\. - - In this form the command is used to configure one or more of the supported - options\. At least one option has to be specified, and each option is - followed by its new value\. The list of supported options and their meaning - can be found in section [OPTIONS](#section5)\. - - This form can be used only as long as the client has not contacted the name - service yet\. After contact has been made reconfiguration is not possible - anymore\. This means that this form of the command is for the initalization - of the client before it use\. The command forcing a contact with the name - service are - - * __[bind](\.\./\.\./\.\./\.\./index\.md\#bind)__ - - * __release__ - - * __search__ - - * __server\_protocol__ - - * __server\_features__ - -# CONNECTION HANDLING - -The client automatically connects to the service when one of the commands below -is run for the first time, or whenever one of the commands is run after the -connection was lost, when it was lost\. - - - __[bind](\.\./\.\./\.\./\.\./index\.md\#bind)__ - - - __release__ - - - __search__ - - - __server\_protocol__ - - - __server\_features__ - -Since version 0\.2 of the client it will generate an event when the connection is -lost, allowing higher layers to perform additional actions\. This is done via the -support package __[uevent](\.\./uev/uevent\.md)__\. This and all other name -service related packages hereby reserve the uevent\-tag *nameserv*\. All their -events will be posted to that tag\. - -# EVENTS - -This package generates only one event, *lost\-connection*\. The detail -information provided to that event is a Tcl dictionary\. The only key contained -in the dictionnary is __reason__, and its value will be a string describing -why the connection was lost\. This string is supplied by the underlying -communication package, i\.e\. __[comm](\.\./comm/comm\.md)__\. - -# OPTIONS - -The options supported by the client are for the specification of which name -service to contact, i\.e\. of the location of the name service\. They are: - - - __\-host__ *name*|*ipaddress* - - This option specifies the host name service to contact is running on, either - by *name*, or by *ipaddress*\. The initial default is __localhost__, - i\.e\. it is expected to contact a name service running on the same host as - the application using this package\. - - - __\-port__ *number* - - This option specifies the port the name service to contact is listening on\. - It has to be a positive integer number \(> 0\) not greater than 65536 - \(unsigned short\)\. The initial default is the number returned by the command - __::nameserv::common::port__, as provided by the package - __::nameserv::common__\. - -# ASYNCHRONOUS AND CONTINUOUS SEARCHES - -Asynchronous and continuous searches are invoked by using either option -__\-async__ or __\-continuous__ as argument to the command -__::nameserv::search__\. - -*Note* that these two options are supported if and only if the service the -client is connected to supports the protocol feature *Search/Continuous*\. The -service provided by the package __::nameserv::server__ does this since -version 0\.3\. - -For such searches the result of the search command is the Tcl command of an -object holding the actual result\. The API provided by these objects is: - - - Options: - - * __\-command__ *command\_prefix* - - This option has to be set if a user of the result object wishes to get - asynchronous notifications when the search result or changes to it - arrive\. - - *Note* that while it is possible to poll for the arrival of the - initial search result via the method __filled__, and for subsequent - changes by comparing the output of method __getall__ against a saved - copy, this is not the recommended behaviour\. Setting the - __\-command__ callback and processing the notifications as they - arrive is much more efficient\. - - The *command\_prefix* is called with two arguments, the type of change, - and the data of the change\. The type is either __add__ or - __remove__, indicating new data, or deleted data, respectively\. The - data of the change is always a dictionary listing the added/removed - names and their associated data\. - - The first change reported for a search is always the set of matching - entries at the time of the search\. - - - Methods: - - * __$result__ __destroy__ - - Destroys the object and cancels any continuous monitoring of the service - the object may have had active\. - - * __$result__ __filled__ - - The result is a boolean value indicating whether the search result has - already arrived \(__True__\), or not \(__False__\)\. - - * __$result__ __get__ *name* - - Returns the data associated with the given *name* at - *[bind](\.\./\.\./\.\./\.\./index\.md\#bind)*\-time\. - - * __$result__ __names__ - - Returns a list containing all names known to the object at the time of - the invokation\. - - * __$result__ __size__ - - Returns an integer value specifying the size of the result at the time - of the invokation\. - - * __$result__ __getall__ ?*pattern*? - - Returns a dictionary containing the search result at the time of the - invokation, mapping the matching names to the data associated with them - at *[bind](\.\./\.\./\.\./\.\./index\.md\#bind)*\-time\. - -# HISTORY - - - 0\.3\.1 - - Fixed SF Bug 1954771\. - - - 0\.3 - - Extended the client with the ability to perform asynchronous and continuous - searches\. - - - 0\.2 - - Extended the client with the ability to generate events when it loses its - connection to the name service\. Based on package - __[uevent](\.\./uev/uevent\.md)__\. - - - 0\.1 - - Initial implementation of the client\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv::common\(n\)](nns\_common\.md), -[nameserv::server\(n\)](nns\_server\.md) - -# KEYWORDS - -[client](\.\./\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./\.\./index\.md\#name\_service) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nns/nns_common.md Index: embedded/md/tcllib/files/modules/nns/nns_common.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_common.md +++ embedded/md/tcllib/files/modules/nns/nns_common.md @@ -1,101 +0,0 @@ - -[//000000001]: # (nameserv::common \- Name service facility) -[//000000002]: # (Generated from file 'nns\_common\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nameserv::common\(n\) 0\.1 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nameserv::common \- Name service facility, shared definitions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8 -package require nameserv::common ?0\.1? - -[__::nameserv::common::port__](#1) - -# DESCRIPTION - -Please read *[Name service facility, introduction](nns\_intro\.md)* first\. - -This package is internal and of no interest to users\. It provides the commands -of the name service facility which are shared by the client and server -implemented by the packages __[nameserv::server](nns\_server\.md)__ and -__[nameserv](nns\_client\.md)__ \(the client\)\. - -This service is built in top of and for the package -__[comm](\.\./comm/comm\.md)__\. It has nothing to do with the Internet's -Domain Name System\. If the reader is looking for a package dealing with that -please see Tcllib's packages __[dns](\.\./dns/tcllib\_dns\.md)__ and -__resolv__\. - -# API - -The package exports a single command, as specified below: - - - __::nameserv::common::port__ - - The result returned by the command is the id of the default TCP/IP port a - nameservice server will listen on, and a name service client will try to - connect to\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -nameserv::client\(n\), [nameserv::server\(n\)](nns\_server\.md) - -# KEYWORDS - -[client](\.\./\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[server](\.\./\.\./\.\./\.\./index\.md\#server) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nns/nns_intro.md Index: embedded/md/tcllib/files/modules/nns/nns_intro.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_intro.md +++ embedded/md/tcllib/files/modules/nns/nns_intro.md @@ -1,158 +0,0 @@ - -[//000000001]: # (nns\_intro \- Name service facility) -[//000000002]: # (Generated from file 'nns\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Andreas Kupries ) -[//000000004]: # (nns\_intro\(n\) 1\.0 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nns\_intro \- Name service facility, introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Applications](#section2) - - - [Packages](#section3) - - - [Internals](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -*[nns](\.\./\.\./apps/nns\.md)* \(short for *nano nameservice*\) is a facility -built for the package __[comm](\.\./comm/comm\.md)__, adding a simple name -service to it\. It is also built on top of __[comm](\.\./comm/comm\.md)__, -using it for the exchange of messages between the client and server parts\. - -This name service facility has nothing to do with the Internet's *Domain Name -System*, otherwise known as *[DNS](\.\./\.\./\.\./\.\./index\.md\#dns)*\. If the -reader is looking for a package dealing with that please see either of the -packages __[dns](\.\./dns/tcllib\_dns\.md)__ and __resolv__, both found -in Tcllib too\. - -Tcllib provides 2 applications and 4 packages which are working together and -provide access to the facility at different levels\. - -# Applications - -The application __[nnsd](\.\./\.\./apps/nnsd\.md)__ provides a simple name -server which can be run by anybody anywhere on their system, as they see fit\. It -is also an example on the use of the server\-side package -__[nameserv::server](nns\_server\.md)__\. - -Complementing this server is the __[nns](\.\./\.\./apps/nns\.md)__ client -application\. A possible, but no very sensible use would be to enter name/port -bindings into a server from a shell script\. Not sensible, as shell scripts -normally do not provide a __[comm](\.\./comm/comm\.md)__\-based service\. - -The only case for this to make some sense would be in a shell script wrapped -around a Tcl script FOO which is using comm, to register the listening port used -by FOO\. However even there it would much more sensible to extend FOO to use the -nameservice directly\. And in regard on how to that -__[nns](\.\./\.\./apps/nns\.md)__ can be used as both example and template\. -Beyond that it may also be useful to perform nameservice queries from shell -scripts\. - -The third application, __[nnslog](\.\./\.\./apps/nnslog\.md)__ is a stripped -down form of the __[nns](\.\./\.\./apps/nns\.md)__ client application\. It is -reduced to perform a continuous search for all changes and logs all received -events to stdout\. - -Both clients use the __[nameserv::auto](nns\_auto\.md)__ package to -automatically hande the loss and restoration of the connection to the server\. - -# Packages - -The two main packages implementing the service are -__[nameserv](nns\_client\.md)__ and -__[nameserv::server](nns\_server\.md)__, i\.e\. client and server\. The -latter has not much of an API, just enough to start, stop, and configure it\. See -the application __[nnsd](\.\./\.\./apps/nnsd\.md)__ on how to use it\. - -The basic client, in package __[nameserv](nns\_client\.md)__, provides the -main API to manipulate and query the service\. An example of its use is the -application __[nns](\.\./\.\./apps/nns\.md)__\. - -The second client package, __[nameserv::auto](nns\_auto\.md)__ is API -compatible to the basic client, but provides the additional functionality that -it will automatically restore data like bound names when the connection to the -name service was lost and then reestablished\. I\.e\. it automatically detects the -loss of the server and re\-enters the data when the server comes back\. - -The package __[nameserv::common](nns\_common\.md)__ is of no interest to -users\. It is an internal package containing code and definitions common to the -packages __[nameserv](nns\_client\.md)__ and -__[nameserv::server](nns\_server\.md)__\. - -All packages use the __[uevent](\.\./uev/uevent\.md)__ package for the -reporting of special circumstances via events, and reserve the uevent\-tag -*[nameserv](nns\_client\.md)* for their exclusive use\. All their events will -be posted to that tag\. - -# Internals - -The document *[Name service facility, client/server -protocol](nns\_protocol\.md)* specifies the protocol used by the packages -__[nameserv](nns\_client\.md)__ and -__[nameserv::server](nns\_server\.md)__ to talk to each other\. It is of no -interest to users of either the packages or applications\. - -Developers wishing to modify and/or extend or to just understand the internals -of the nameservice facility however are strongly advised to read it\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[nameserv\(n\)](nns\_client\.md), [nameserv::auto\(n\)](nns\_auto\.md), -[nameserv::common\(n\)](nns\_common\.md), -[nameserv::protocol\(n\)](nns\_protocol\.md), -[nameserv::server\(n\)](nns\_server\.md), [nnsd\(n\)](\.\./\.\./apps/nnsd\.md), -nss\(n\) - -# KEYWORDS - -[client](\.\./\.\./\.\./\.\./index\.md\#client), [name -service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[server](\.\./\.\./\.\./\.\./index\.md\#server) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nns/nns_protocol.md Index: embedded/md/tcllib/files/modules/nns/nns_protocol.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_protocol.md +++ embedded/md/tcllib/files/modules/nns/nns_protocol.md @@ -1,216 +0,0 @@ - -[//000000001]: # (nameserv::protocol \- Name service facility) -[//000000002]: # (Generated from file 'nns\_protocol\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nameserv::protocol\(n\) 0\.1 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nameserv::protocol \- Name service facility, client/server protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Nano Name Service Protocol Version 1](#section2) - - - [Basic Layer](#subsection1) - - - [Message Layer](#subsection2) - - - [Nano Name Service Protocol Extension: Continuous Search](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__Bind__ *name* *data*](#1) -[__Release__](#2) -[__Search__ *pattern*](#3) -[__ProtocolVersion__](#4) -[__ProtocolFeatures__](#5) -[__Search/Continuous/Start__ *tag* *pattern*](#6) -[__Search/Continuous/Stop__ *tag*](#7) -[__Search/Continuous/Change__ *tag* __add__|__remove__ *response*](#8) - -# DESCRIPTION - -The packages __[nameserv::server](nns\_server\.md)__, -__[nameserv](nns\_client\.md)__, and -__[nameserv::common](nns\_common\.md)__ provide a simple unprotected name -service facility for use in small trusted environments\. - -Please read *[Name service facility, introduction](nns\_intro\.md)* first\. - -This document contains the specification of the network protocol which is used -by client and server to talk to each other, enabling implementations of the same -protocol in other languages\. - -# Nano Name Service Protocol Version 1 - -This protocol defines the basic set of messages to be supported by a name -service, also called the *Core* feature\. - -## Basic Layer - -The basic communication between client and server is done using the -remote\-execution protocol specified by the Tcl package -__[comm](\.\./comm/comm\.md)__\. The relevant document specifying its -on\-the\-wire protocol can be found in *[comm\_wire](\.\./comm/comm\_wire\.md)*\. - -All the scripts exchanged via this protocol are single commands in list form and -thus can be interpreted as plain messages instead of as Tcl commands\. The -commands/messages specified in the next section are the only commands understood -by the server\-side\. Command and variable substitutions are not allowed within -the messages, i\.e\. arguments have to be literal values\. - -The protocol is synchronous\. I\.e\. for each message sent a response is expected, -and has to be generated\. All messages are sent by the client\. The server does -not sent messages, only responses to messages\. - -## Message Layer - - - __Bind__ *name* *data* - - The client sends this message when it registers itself at the service with a - *name* and some associated *data*\. The server has to send an error - response if the *name* is already in use\. Otherwise the response has to be - an empty string\. - - The server has to accept multiple names for the same client\. - - - __Release__ - - The client sends this message to unregister all names it is known under at - the service\. The response has to be an empty string, always\. - - - __Search__ *pattern* - - The client sends this message to search the service for names matching the - glob\-*pattern*\. The response has to be a dictionary containing the - matching names as keys, and mapping them to the data associated with it at - __Bind__\-time\. - - - __ProtocolVersion__ - - The client sends this message to query the service for the highest version - of the name service protocol it supports\. The response has to be a positive - integer number\. - - Servers supporting only *Nano Name Service Protocol Version 1* have to - return __1__\. - - - __ProtocolFeatures__ - - The client sends this message to query the service for the features of the - name service protocol it supports\. The response has to be a list containing - feature names\. - - Servers supporting only *Nano Name Service Protocol Version 1* have to - return __\{Core\}__\. - -# Nano Name Service Protocol Extension: Continuous Search - -This protocol defines an extended set of messages to be supported by a name -service, also called the *Search/Continuous* feature\. This feature defines -additional messages between client and server, and is otherwise identical to -version 1 of the protocol\. See the last section for the details of our -foundation\. - -A service supporting this feature has to put the feature name -__Search/Continuous__ into the list of features returned by the message -*ProtocolFeatures*\. - -For this extension the protocol is asynchronous\. No direct response is expected -for any of the messages in the extension\. Furthermore the server will start -sending messages on its own, instead of only responses to messages, and the -client has to be able to handle these notifications\. - - - __Search/Continuous/Start__ *tag* *pattern* - - The client sends this message to start searching the service for names - matching the glob\-*pattern*\. In contrast to the regular *Search* request - this one asks the server to continuously monitor the database for the - addition and removal of matching entries and to notify the client of all - such changes\. The particular search is identified by the *tag*\. - - No direct response is expected, rather the clients expect to be notified of - changes via explicit *Search/Continuous/Result* messages generated by the - service\. - - It is further expected that the *tag* information is passed unchanged to - the *Search/Continuous/Result* messages\. This tagging of the results - enables clients to start multiple searches and distinguish between the - different results\. - - - __Search/Continuous/Stop__ *tag* - - The client sends this message to stop the continuous search identified by - the *tag*\. - - - __Search/Continuous/Change__ *tag* __add__|__remove__ *response* - - This message is sent by the service to clients with active continuous - searches to transfer found changes\. The first such message for a new - continuous search has to contains the current set of matching entries\. - - To ensure this a service has to generate an __add__\-message with an - empty *response* if there were no matching entries at the time\. - - The *response* has to be a dictionary containing the matching names as - keys, and mapping them to the data associated with it at __Bind__\-time\. - The argument coming before the response tells the client whether the names - in the response were added or removed from the service\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[comm\_wire\(n\)](\.\./comm/comm\_wire\.md), [nameserv\(n\)](nns\_client\.md), -[nameserv::server\(n\)](nns\_server\.md) - -# KEYWORDS - -[comm](\.\./\.\./\.\./\.\./index\.md\#comm), [name -service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nns/nns_server.md Index: embedded/md/tcllib/files/modules/nns/nns_server.md ================================================================== --- embedded/md/tcllib/files/modules/nns/nns_server.md +++ embedded/md/tcllib/files/modules/nns/nns_server.md @@ -1,194 +0,0 @@ - -[//000000001]: # (nameserv::server \- Name service facility) -[//000000002]: # (Generated from file 'nns\_server\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2008 Andreas Kupries ) -[//000000004]: # (nameserv::server\(n\) 0\.3\.2 tcllib "Name service facility") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nameserv::server \- Name service facility, Server - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [OPTIONS](#section3) - - - [HISTORY](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require nameserv::server ?0\.3\.2? -package require comm -package require interp -package require logger - -[__::nameserv::server::start__](#1) -[__::nameserv::server::stop__](#2) -[__::nameserv::server::active?__](#3) -[__::nameserv::server::cget__ __\-option__](#4) -[__::nameserv::server::configure__](#5) -[__::nameserv::server::configure__ __\-option__](#6) -[__::nameserv::server::configure__ __\-option__ *value*\.\.\.](#7) - -# DESCRIPTION - -Please read *[Name service facility, introduction](nns\_intro\.md)* first\. - -This package provides an implementation of the serviver side of the name service -facility queried by the client provided by the package -__[nameserv](nns\_client\.md)__\. All information required by the server -will be held in memory\. There is no persistent state\. - -This service is built in top of and for the package -__[comm](\.\./comm/comm\.md)__\. It has nothing to do with the Internet's -Domain Name System\. If the reader is looking for a package dealing with that -please see Tcllib's packages __[dns](\.\./dns/tcllib\_dns\.md)__ and -__resolv__\. - -This server supports the *Core* protocol feature, and since version 0\.3 the -*Search/Continuous* feature as well\. - -# API - -The package exports five commands, as specified below: - - - __::nameserv::server::start__ - - This command starts the server and causes it to listen on the configured - port\. From now on clients are able to connect and make requests\. The result - of the command is the empty string\. - - Note that any incoming requests will only be handled if the application the - server is part of does enter an event loop after this command has been run\. - - - __::nameserv::server::stop__ - - Invoking this command stops the server and releases all information it had\. - Existing connections are shut down, and no new connections will be accepted - any longer\. The result of the command is the empty string\. - - - __::nameserv::server::active?__ - - This command returns a boolean value indicating the state of the server\. The - result will be __true__ if the server is active, i\.e\. has been started, - and __false__ otherwise\. - - - __::nameserv::server::cget__ __\-option__ - - This command returns the currently configured value for the specified - __\-option__\. The list of supported options and their meaning can be - found in section [OPTIONS](#section3)\. - - - __::nameserv::server::configure__ - - In this form the command returns a dictionary of all supported options, and - their current values\. The list of supported options and their meaning can be - found in section [OPTIONS](#section3)\. - - - __::nameserv::server::configure__ __\-option__ - - In this form the command is an alias for "__::nameserv::server::cget__ - __\-option__"\. The list of supported options and their meaning can be - found in section [OPTIONS](#section3)\. - - - __::nameserv::server::configure__ __\-option__ *value*\.\.\. - - In this form the command is used to configure one or more of the supported - options\. At least one option has to be specified, and each option is - followed by its new value\. The list of supported options and their meaning - can be found in section [OPTIONS](#section3)\. - - This form can be used only if the server is not active, i\.e\. has not been - started yet, or has been stopped\. While the server is active it cannot be - reconfigured\. - -# OPTIONS - -The options supported by the server are for the specification of the TCP port to -listen on, and whether to accept non\-local connections or not\. They are: - - - __\-localonly__ *bool* - - This option specifies whether to accept only local connections \(\-localonly - 1\) or remote connections as well \(\-localonly 0\)\. The default is to accept - only local connections\. - - - __\-port__ *number* - - This option specifies the port the name service will listen on after it has - been started\. It has to be a positive integer number \(> 0\) not greater than - 65536 \(unsigned short\)\. The initial default is the number returned by the - command __::nameserv::server::common::port__, as provided by the package - __::nameserv::server::common__\. - -# HISTORY - - - 0\.3 - - Extended the server with the ability to perform asynchronous and continuous - searches\. - - - 0\.2 - - Changed name of \-local switch to \-localonly\. - - - 0\.1 - - Initial implementation of the server\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -nameserv::client\(n\), [nameserv::common\(n\)](nns\_common\.md) - -# KEYWORDS - -[name service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[server](\.\./\.\./\.\./\.\./index\.md\#server) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2007\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/nntp/nntp.md Index: embedded/md/tcllib/files/modules/nntp/nntp.md ================================================================== --- embedded/md/tcllib/files/modules/nntp/nntp.md +++ embedded/md/tcllib/files/modules/nntp/nntp.md @@ -1,391 +0,0 @@ - -[//000000001]: # (nntp \- Tcl NNTP Client Library) -[//000000002]: # (Generated from file 'nntp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (nntp\(n\) 1\.5\.1 tcllib "Tcl NNTP Client Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -nntp \- Tcl client for the NNTP protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLE](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require nntp ?0\.2\.1? - -[__::nntp::nntp__ ?*host*? ?*port*? ?*nntpName*?](#1) -[*nntpName* __method__ ?*arg arg \.\.\.*?](#2) -[*nntpName* __article__ ?*msgid*?](#3) -[*nntpName* __authinfo__ ?*user*? ?*pass*?](#4) -[*nntpName* __body__ ?*msgid*?](#5) -[*nntpName* __configure__](#6) -[*nntpName* __configure__ *option*](#7) -[*nntpName* __configure__ *option* *value* \.\.\.](#8) -[*nntpName* __cget__ *option*](#9) -[*nntpName* __date__](#10) -[*nntpName* __group__ ?*group*?](#11) -[*nntpName* __head__ ?*msgid*?](#12) -[*nntpName* __help__](#13) -[*nntpName* __last__](#14) -[*nntpName* __list__](#15) -[*nntpName* __listgroup__ ?*group*?](#16) -[*nntpName* __mode\_reader__](#17) -[*nntpName* __newgroups__ *since*](#18) -[*nntpName* __newnews__](#19) -[*nntpName* __newnews__ *since*](#20) -[*nntpName* __newnews__ *group* ?*since*?](#21) -[*nntpName* __next__](#22) -[*nntpName* __post__ *article*](#23) -[*nntpName* __slave__](#24) -[*nntpName* __stat__ ?*msgid*?](#25) -[*nntpName* __quit__](#26) -[*nntpName* __xgtitle__ ?*group\_pattern*?](#27) -[*nntpName* __xhdr__ *field* ?*range*?](#28) -[*nntpName* __xover__ ?*range*?](#29) -[*nntpName* __xpat__ *field* *range* ?*pattern\_list*?](#30) - -# DESCRIPTION - -The package __nntp__ provides a simple Tcl\-only client library for the NNTP -protocol\. It works by opening the standard NNTP socket on the server, and then -providing a Tcl API to access the NNTP protocol commands\. All server errors are -returned as Tcl errors \(thrown\) which must be caught with the Tcl __catch__ -command\. - -# COMMANDS - - - __::nntp::nntp__ ?*host*? ?*port*? ?*nntpName*? - - The command opens a socket connection to the specified NNTP server and - creates a new nntp object with an associated global Tcl command whose name - is *nntpName*\. This command may be used to access the various NNTP - protocol commands for the new connection\. The default *port* number is - "119" and the default *host* is "news"\. These defaults can be overridden - with the environment variables __NNTPPORT__ and __NNTPHOST__ - respectively\. - - Some of the commands supported by this package are not part of the nntp rfc - 977 - \([http://www\.rfc\-editor\.org/rfc/rfc977\.txt](http://www\.rfc\-editor\.org/rfc/rfc977\.txt)\) - and will not be available \(or implemented\) on all nntp servers\. - - The access command *nntpName* has the following general form: - - * *nntpName* __method__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - - *nntpName* __article__ ?*msgid*? - - Query the server for article *msgid* from the current group\. The article - is returned as a valid tcl list which contains the headers, followed by a - blank line, and then followed by the body of the article\. Each element in - the list is one line of the article\. - - - *nntpName* __authinfo__ ?*user*? ?*pass*? - - Send authentication information \(username and password\) to the server\. - - - *nntpName* __body__ ?*msgid*? - - Query the server for the body of the article *msgid* from the current - group\. The body of the article is returned as a valid tcl list\. Each element - in the list is one line of the body of the article\. - - - *nntpName* __configure__ - - - *nntpName* __configure__ *option* - - - *nntpName* __configure__ *option* *value* \.\.\. - - - *nntpName* __cget__ *option* - - Query and configure options of the nntp connection object\. Currently only - one option is supported, __\-binary__\. When set articles are retrieved as - binary data instead of text\. The only methods affected by this are - __article__ and __body__\. - - One application of this option would be the download of articles containing - yEnc encoded images\. Although encoded the data is still mostly binary and - retrieving it as text will corrupt the information\. - - See package __[yencode](\.\./base64/yencode\.md)__ for both encoder and - decoder of such data\. - - - *nntpName* __date__ - - Query the server for the servers current date\. The date is returned in the - format *YYYYMMDDHHMMSS*\. - - - *nntpName* __group__ ?*group*? - - Optionally set the current group, and retrieve information about the - currently selected group\. Returns the estimated number of articles in the - group followed by the number of the first article in the group, followed by - the last article in the group, followed by the name of the group\. - - - *nntpName* __head__ ?*msgid*? - - Query the server for the headers of the article *msgid* from the current - group\. The headers of the article are returned as a valid tcl list\. Each - element in the list is one line of the headers of the article\. - - - *nntpName* __help__ - - Retrieves a list of the commands that are supported by the news server that - is currently attached to\. - - - *nntpName* __last__ - - Sets the current article pointer to point to the previous message \(if there - is one\) and returns the msgid of that message\. - - - *nntpName* __list__ - - Returns a tcl list of valid newsgroups and associated information\. Each - newsgroup is returned as an element in the tcl list with the following - format: - - group last first p - - where is the name of the newsgroup, is the number of the last - known article currently in that newsgroup, is the number of the - first article currently in the newsgroup, and

is either 'y' or 'n' - indicating whether posting to this newsgroup is allowed \('y'\) or prohibited - \('n'\)\. - - The and fields will always be numeric\. They may have leading - zeros\. If the field evaluates to less than the field, there - are no articles currently on file in the newsgroup\. - - - *nntpName* __listgroup__ ?*group*? - - Query the server for a list of all the messages \(message numbers\) in the - group specified by the argument *group* or by the current group if the - *group* argument was not passed\. - - - *nntpName* __mode\_reader__ - - Query the server for its nntp 'MODE READER' response string\. - - - *nntpName* __newgroups__ *since* - - Query the server for a list of all the new newsgroups created since the time - specified by the argument *since*\. The argument *since* can be any time - string that is understood by __clock scan__\. The tcl list of newsgroups - is returned in a similar form to the list of groups returned by the - __nntpName list__ command\. Each element of the list has the form: - - group last first p - - where is the name of the newsgroup, is the number of the last - known article currently in that newsgroup, is the number of the - first article currently in the newsgroup, and

is either 'y' or 'n' - indicating whether posting to this newsgroup is allowed \('y'\) or prohibited - \('n'\)\. - - - *nntpName* __newnews__ - - Query the server for a list of new articles posted to the current group in - the last day\. - - - *nntpName* __newnews__ *since* - - Query the server for a list of new articles posted to the current group - since the time specified by the argument *since*\. The argument *since* - can be any time string that is understood by __clock scan__\. - - - *nntpName* __newnews__ *group* ?*since*? - - Query the server for a list of new articles posted to the group specified by - the argument *group* since the time specified by the argument *since* - \(or in the past day if no *since* argument is passed\. The argument - *since* can be any time string that is understood by __clock scan__\. - - - *nntpName* __next__ - - Sets the current article pointer to point to the next message \(if there is - one\) and returns the msgid of that message\. - - - *nntpName* __post__ *article* - - Posts an article of the form specified in RFC 1036 - \([http://www\.rfc\-editor\.org/rfc/rfc1036\.txt](http://www\.rfc\-editor\.org/rfc/rfc1036\.txt), - successor to RFC 850\) to the current news group\. - - - *nntpName* __slave__ - - Identifies a connection as being made from a slave nntp server\. This might - be used to indicate that the connection is serving multiple people and - should be given priority\. Actual use is entirely implementation dependent - and may vary from server to server\. - - - *nntpName* __stat__ ?*msgid*? - - The stat command is similar to the article command except that no text is - returned\. When selecting by message number within a group, the stat command - serves to set the current article pointer without sending text\. The returned - acknowledgment response will contain the message\-id, which may be of some - value\. Using the stat command to select by message\-id is valid but of - questionable value, since a selection by message\-id does NOT alter the - "current article pointer" - - - *nntpName* __quit__ - - Gracefully close the connection after sending a NNTP QUIT command down the - socket\. - - - *nntpName* __xgtitle__ ?*group\_pattern*? - - Returns a tcl list where each element is of the form: - - newsgroup description - - If a *group\_pattern* is specified then only newsgroups that match the - pattern will have their name and description returned\. - - - *nntpName* __xhdr__ *field* ?*range*? - - Returns the specified header field value for the current message or for a - list of messages from the current group\. *field* is the title of a field - in the header such as from, subject, date, etc\. If *range* is not - specified or is "" then the current message is queried\. The command returns - a list of elements where each element has the form of: - - msgid value - - Where msgid is the number of the message and value is the value set for the - queried field\. The *range* argument can be in any of the following forms: - - * __""__ - - The current message is queried\. - - * *msgid1*\-*msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - - * *msgid1* *msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - - - *nntpName* __xover__ ?*range*? - - Returns header information for the current message or for a range of - messages from the current group\. The information is returned in a tcl list - where each element is of the form: - - msgid subject from date idstring bodysize headersize xref - - If *range* is not specified or is "" then the current message is queried\. - The *range* argument can be in any of the following forms: - - * __""__ - - The current message is queried\. - - * *msgid1*\-*msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - - * *msgid1* *msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - - - *nntpName* __xpat__ *field* *range* ?*pattern\_list*? - - Returns the specified header field value for a specified message or for a - list of messages from the current group where the messages match the - pattern\(s\) given in the pattern\_list\. *field* is the title of a field in - the header such as from, subject, date, etc\. The information is returned in - a tcl list where each element is of the form: - - msgid value - - Where msgid is the number of the message and value is the value set for the - queried field\. The *range* argument can be in any of the following forms: - - * *msgid* - - The message specified by *msgid* is queried\. - - * *msgid1*\-*msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - - * *msgid1* *msgid2* - - All messages between *msgid1* and *msgid2* \(including *msgid1* and - *msgid2*\) are queried\. - -# EXAMPLE - -A bigger example for posting a single article\. - - package require nntp - set n [nntp::nntp NNTP_SERVER] - $n post "From: USER@DOMAIN.EXT (USER_FULL) - Path: COMPUTERNAME!USERNAME - Newsgroups: alt.test - Subject: Tcl test post -ignore - Message-ID: <[pid][clock seconds] - @COMPUTERNAME> - Date: [clock format [clock seconds] -format "%a, %d % - b %y %H:%M:%S GMT" -gmt true] - - Test message body" - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nntp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[news](\.\./\.\./\.\./\.\./index\.md\#news), [nntp](\.\./\.\./\.\./\.\./index\.md\#nntp), -[nntpclient](\.\./\.\./\.\./\.\./index\.md\#nntpclient), [rfc -1036](\.\./\.\./\.\./\.\./index\.md\#rfc\_1036), [rfc -977](\.\./\.\./\.\./\.\./index\.md\#rfc\_977) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/ntp/ntp_time.md Index: embedded/md/tcllib/files/modules/ntp/ntp_time.md ================================================================== --- embedded/md/tcllib/files/modules/ntp/ntp_time.md +++ embedded/md/tcllib/files/modules/ntp/ntp_time.md @@ -1,204 +0,0 @@ - -[//000000001]: # (ntp\_time \- Network Time Facilities) -[//000000002]: # (Generated from file 'ntp\_time\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Pat Thoyts ) -[//000000004]: # (ntp\_time\(n\) 1\.2\.1 tcllib "Network Time Facilities") - -

[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ntp\_time \- Tcl Time Service Client - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.0 -package require time ?1\.2\.1? - -[__::time::gettime__ ?*options*? *timeserver* ?*port*?](#1) -[__::time::getsntp__ ?*options*? *timeserver* ?*port*?](#2) -[__::time::configure__ ?*options*?](#3) -[__::time::cget__ *name*](#4) -[__::time::unixtime__ *token*](#5) -[__::time::status__ *token*](#6) -[__::time::error__ *token*](#7) -[__::time::reset__ *token* *?reason?*](#8) -[__::time::wait__ *token*](#9) -[__::time::cleanup__ *token*](#10) - -# DESCRIPTION - -This package implements a client for the RFC 868 TIME protocol -\([http://www\.rfc\-editor\.org/rfc/rfc868\.txt](http://www\.rfc\-editor\.org/rfc/rfc868\.txt)\) -and also a minimal client for the RFC 2030 Simple Network Time Protocol -\([http://www\.rfc\-editor\.org/rfc/rfc2030\.txt](http://www\.rfc\-editor\.org/rfc/rfc2030\.txt)\)\. -RFC 868 returns the time in seconds since 1 January 1900 to either tcp or udp -clients\. RFC 2030 also gives this time but also provides a fractional part which -is not used in this client\. - -# COMMANDS - - - __::time::gettime__ ?*options*? *timeserver* ?*port*? - - Get the time from *timeserver*\. You may specify any of the options listed - for the __configure__ command here\. This command returns a token which - must then be used with the remaining commands in this package\. Once you have - finished, you should use __[cleanup](\.\./\.\./\.\./\.\./index\.md\#cleanup)__ - to release all resources\. The default port is __37__\. - - - __::time::getsntp__ ?*options*? *timeserver* ?*port*? - - Get the time from an SNTP server\. This accepts exactly the same arguments as - __::time::gettime__ except that the default port is __123__\. The - result is a token as per __::time::gettime__ and should be handled in - the same way\. - - Note that it is unlikely that any SNTP server will reply using tcp so you - will require the __tcludp__ or the __ceptcl__ package\. If a suitable - package can be loaded then the udp protocol will be used by default\. - - - __::time::configure__ ?*options*? - - Called with no arguments this command returns all the current configuration - options and values\. Otherwise it should be called with pairs of option name - and value\. - - * __\-protocol__ *number* - - Set the default network protocol\. This defaults to udp if the tcludp - package is available\. Otherwise it will use tcp\. - - * __\-port__ *number* - - Set the default port to use\. RFC 868 uses port __37__, RFC 2030 uses - port __123__\. - - * __\-timeout__ *number* - - Set the default timeout value in milliseconds\. The default is 10 - seconds\. - - * __\-command__ *number* - - Set a command procedure to be run when a reply is received\. The - procedure is called with the time token appended to the argument list\. - - * __\-loglevel__ *number* - - Set the logging level\. The default is 'warning'\. - - - __::time::cget__ *name* - - Get the current value for the named configuration option\. - - - __::time::unixtime__ *token* - - Format the returned time for the unix epoch\. RFC 868 time defines time 0 as - 1 Jan 1900, while unix time defines time 0 as 1 Jan 1970\. This command - converts the reply to unix time\. - - - __::time::status__ *token* - - Returns the status flag\. For a successfully completed query this will be - *ok*\. May be *error* or *timeout* or *eof*\. See also - __::time::error__ - - - __::time::error__ *token* - - Returns the error message provided for requests whose status is *error*\. - If there is no error message then an empty string is returned\. - - - __::time::reset__ *token* *?reason?* - - Reset or cancel the query optionally specfying the reason to record for the - __[error](\.\./\.\./\.\./\.\./index\.md\#error)__ command\. - - - __::time::wait__ *token* - - Wait for a query to complete and return the status upon completion\. - - - __::time::cleanup__ *token* - - Remove all state variables associated with the request\. - - % set tok [::time::gettime ntp2a.mcc.ac.uk] - % set t [::time::unixtime $tok] - % ::time::cleanup $tok - - % set tok [::time::getsntp pool.ntp.org] - % set t [::time::unixtime $tok] - % ::time::cleanup $tok - - proc on_time {token} { - if {[time::status $token] eq "ok"} { - puts [clock format [time::unixtime $token]] - } else { - puts [time::error $token] - } - time::cleanup $token - } - time::getsntp -command on_time pool.ntp.org - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ntp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -ntp - -# KEYWORDS - -[NTP](\.\./\.\./\.\./\.\./index\.md\#ntp), [SNTP](\.\./\.\./\.\./\.\./index\.md\#sntp), -[rfc 2030](\.\./\.\./\.\./\.\./index\.md\#rfc\_2030), [rfc -868](\.\./\.\./\.\./\.\./index\.md\#rfc\_868), [time](\.\./\.\./\.\./\.\./index\.md\#time) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2002, Pat Thoyts DELETED embedded/md/tcllib/files/modules/oauth/oauth.md Index: embedded/md/tcllib/files/modules/oauth/oauth.md ================================================================== --- embedded/md/tcllib/files/modules/oauth/oauth.md +++ embedded/md/tcllib/files/modules/oauth/oauth.md @@ -1,265 +0,0 @@ - -[//000000001]: # (oauth \- oauth) -[//000000002]: # (Generated from file 'oauth\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2014 Javi P\. ) -[//000000004]: # (oauth\(n\) 1\.0\.3 tcllib "oauth") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -oauth \- oauth API base signature - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TLS Security Considerations](#section2) - - - [Commands](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require oauth ?1\.0\.3? - -[__::oauth::config__](#1) -[__::oauth::config__ ?*options*\.\.\.?](#2) -[__::oauth::header__ *baseURL* ?*postQuery*?](#3) -[__::oauth::query__ *baseURL* ?*postQuery*?](#4) - -# DESCRIPTION - -The __oauth__ package provides a simple Tcl\-only library for communication -with [oauth](http://oauth\.net) APIs\. This current version of the package -supports the Oauth 1\.0 Protocol, as specified in [RFC -5849](http://tools\.ietf\.org/rfc/rfc5849\.txt)\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Commands - - - __::oauth::config__ - - When this command is invoked without arguments it returns a dictionary - containing the current values of all options\. - - - __::oauth::config__ ?*options*\.\.\.? - - When invoked with arguments, options followed by their values, it is used to - set and query various parameters of application and client, like proxy host - and user agent for the HTTP requests\. The detailed list of options is below: - - * __\-accesstoken__ *string* - - This is the user's token\. - - * __\-accesstokensecret__ *string* - - This is the user's secret token\. - - * __\-consumerkey__ *string* - - This is the public token of your app\. - - * __\-consumersecret__ *string* - - This is the private token of your app\. - - * __\-debug__ *bool* - - The default value is __off__\. If you change this option to - __on__, the basic signature just created will be printed to stdout, - among other debug output\. - - * __\-oauthversion__ *version* - - This is the version of the OAuth protocol to use\. At the moment only - __1\.0__ is supported, the default\. - - * __\-proxyhost__ *hostname* - - You can set up a proxy host for send contact the oauth's api server\. - - * __\-proxyport__ *port\-number* - - Port number of your proxy\. - - * __\-signmethod__ *method* - - The signature method to use\. OAuth 1\.0 only supports __HMAC\-SHA1__, - the default\. - - * __\-timeout__ *milliseconds* - - Timeout in milliseconds for your query\. The default value is - __6000__, i\.e\. 6 seconds\. - - * __\-urlencoding__ *encoding* - - The encoding used for creating the x\-url\-encoded URLs with - __::http::formatQuery__\. The default is __utf\-8__, as specified - by [RFC 2718](http://tools\.ietf\.org/rfc/rfc2718\.txt)\. - - - __::oauth::header__ *baseURL* ?*postQuery*? - - This command is the base signature creator\. With proper settings for various - tokens and secrets \(See __::oauth::config__\) the result is the base - authentication string to send to the server\. - - You do not need to call this procedure to create the query because - __::oauth::query__ \(see below\) will do for it for you\. Doing so is - useful for debugging purposes, though\. - - * url *baseURL* - - This argument is the URI path to the OAuth API server\. If you plan send - a GET query, you should provide a full path\. - - HTTP GET - ::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente} - - * url\-encoded\-string *postQuery* - - When you have to send a header in POST format, you have to put the query - string into this argument\. - - ::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true} - - - __::oauth::query__ *baseURL* ?*postQuery*? - - This procedure will use the settings made with __::oauth::config__ to - create the basic authentication and then send the command to the server API\. - It takes the same arguments as __::oauth::header__\. - - The returned result will be a list containing 2 elements\. The first element - will be a dictionary containing the HTTP header data response\. This allows - you, for example, to check the X\-Rate\-Limit from OAuth\. The second element - will be the raw data returned from API server\. This string is usually a json - object which can be further decoded with the functions of package - __[json](\.\./json/json\.md)__, or any other json\-parser for Tcl\. - - Here is an example of how it would work in Twitter\. Do not forget to replace - the placeholder tokens and keys of the example with your own tokens and keys - when trying it out\. - - % package require oauth - % package require json - % oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret} - - % set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente] - % set jsondata [lindex $response 1] - % set data [json::json2dict $jsondata] - $ set data [lindex $data 0] - % dict for {key val} $data {puts "$key => $val"} - id => 158812437 - id_str => 158812437 - name => Un Librepensador - screen_name => AbiertaMente - location => Explico mis tuits ahí → - description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q - url => http://t.co/SGs3k9odBn - entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}} - protected => false - followers_count => 72705 - friends_count => 53099 - listed_count => 258 - created_at => Wed Jun 23 18:29:58 +0000 2010 - favourites_count => 297 - utc_offset => 7200 - time_zone => Madrid - geo_enabled => false - verified => false - statuses_count => 8996 - lang => es - status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {Twitter Web Client} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name Ἑλένη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und - contributors_enabled => false - is_translator => true - is_translation_enabled => false - profile_background_color => 709397 - profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg - profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg - profile_background_tile => true - profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg - profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg - profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874 - profile_link_color => FF3300 - profile_sidebar_border_color => FFFFFF - profile_sidebar_fill_color => A0C5C7 - profile_text_color => 333333 - profile_use_background_image => true - default_profile => false - default_profile_image => false - following => true - follow_request_sent => false - notifications => false - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *oauth* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[RFC 2718](\.\./\.\./\.\./\.\./index\.md\#rfc\_2718), [RFC -5849](\.\./\.\./\.\./\.\./index\.md\#rfc\_5849), -[oauth](\.\./\.\./\.\./\.\./index\.md\#oauth), -[twitter](\.\./\.\./\.\./\.\./index\.md\#twitter) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2014 Javi P\. DELETED embedded/md/tcllib/files/modules/oometa/oometa.md Index: embedded/md/tcllib/files/modules/oometa/oometa.md ================================================================== --- embedded/md/tcllib/files/modules/oometa/oometa.md +++ embedded/md/tcllib/files/modules/oometa/oometa.md @@ -1,214 +0,0 @@ - -[//000000001]: # (oometa \- Data registry for TclOO frameworks) -[//000000002]: # (Generated from file 'oometa\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Sean Woods ) -[//000000004]: # (oometa\(n\) 0\.7\.1 tcllib "Data registry for TclOO frameworks") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -oometa \- oo::meta A data registry for classess - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Usage](#section2) - - - [Concept](#section3) - - - [COMMANDS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -[__oo::meta::info__](#1) -[__oo::meta::info branchget__ ?*key*? ?\.\.\.?](#2) -[__oo::meta::info branchset__ ?*key\.\.\.*? *key* *value*](#3) -[__oo::meta::info dump__ *class*](#4) -[__oo::meta::info__ *class* __is__ *type* ?*args*?](#5) -[__oo::meta::info__ *class* __[merge](\.\./\.\./\.\./\.\./index\.md\#merge)__ ?*dict*? ?*dict*? ?*\.\.\.*?](#6) -[__oo::meta::info__ *class* __rebuild__](#7) -[__oo::meta::metadata__ *class*](#8) -[__oo::define meta__](#9) -[__oo::class method meta__](#10) -[__oo::object method meta__](#11) -[__oo::object method meta cget__ ?*field*? ?*\.\.\.*? *field*](#12) - -# DESCRIPTION - -The __oo::meta__ package provides a data registry service for TclOO classes\. - -# Usage - - oo::class create animal { - meta set biodata animal: 1 - } - oo::class create mammal { - superclass animal - meta set biodata mammal: 1 - } - oo::class create cat { - superclass mammal - meta set biodata diet: carnivore - } - - cat create felix - puts [felix meta dump biodata] - > animal: 1 mammal: 1 diet: carnivore - - felix meta set biodata likes: {birds mice} - puts [felix meta get biodata] - > animal: 1 mammal: 1 diet: carnivore likes: {bird mice} - - # Modify a class - mammal meta set biodata metabolism: warm-blooded - puts [felix meta get biodata] - > animal: 1 mammal: 1 metabolism: warm-blooded diet: carnivore likes: {birds mice} - - # Overwrite class info - felix meta set biodata mammal: yes - puts [felix meta get biodata] - > animal: 1 mammal: yes metabolism: warm-blooded diet: carnivore likes: {birds mice} - -# Concept - -The concept behind __oo::meta__ is that each class contributes a snippet of -*local* data\. When __oo::meta::metadata__ is called, the system walks -through the linear ancestry produced by __oo::meta::ancestors__, and -recursively combines all of that local data for all of a class' ancestors into a -single dict\. Instances of oo::object can also combine class data with a local -dict stored in the *meta* variable\. - -# COMMANDS - - - __oo::meta::info__ - - __oo::meta::info__ is intended to work on the metadata of a class in a - manner similar to if the aggregate pieces where assembled into a single - dict\. The system mimics all of the standard dict commands, and addes the - following: - - - __oo::meta::info branchget__ ?*key*? ?\.\.\.? - - Returns a dict representation of the element at *args*, but with any - trailing : removed from field names\. - - ::oo::meta::info $myclass set option color {default: green widget: colorselect} - puts [::oo::meta::info $myclass get option color] - > {default: green widget: color} - puts [::oo::meta::info $myclass branchget option color] - > {default green widget color} - - - __oo::meta::info branchset__ ?*key\.\.\.*? *key* *value* - - Merges *dict* with any other information contaned at node ?*key\.\.\.*?, - and adding a trailing : to all field names\. - - ::oo::meta::info $myclass branchset option color {default green widget colorselect} - puts [::oo::meta::info $myclass get option color] - > {default: green widget: color} - - - __oo::meta::info dump__ *class* - - Returns the complete snapshot of a class metadata, as producted by - __oo::meta::metadata__ - - - __oo::meta::info__ *class* __is__ *type* ?*args*? - - Returns a boolean true or false if the element ?*args*? would match - __string is__ *type* *value* - - ::oo::meta::info $myclass set constant mammal 1 - puts [::oo::meta::info $myclass is true constant mammal] - > 1 - - - __oo::meta::info__ *class* __[merge](\.\./\.\./\.\./\.\./index\.md\#merge)__ ?*dict*? ?*dict*? ?*\.\.\.*? - - Combines all of the arguments into a single dict, which is then stored as - the new local representation for this class\. - - - __oo::meta::info__ *class* __rebuild__ - - Forces the meta system to destroy any cached representation of a class' - metadata before the next access to __oo::meta::metadata__ - - - __oo::meta::metadata__ *class* - - Returns an aggregate picture of the metadata for *class*, combining its - *local* data with the *local* data from its ancestors\. - - - __oo::define meta__ - - The package injects a command __oo::define::meta__ which works to - provide a class in the process of definition access to - __oo::meta::info__, but without having to look the name up\. - - oo::define myclass { - meta set foo bar: baz - } - - - __oo::class method meta__ - - The package injects a new method __meta__ into __oo::class__ which - works to provide a class instance access to __oo::meta::info__\. - - - __oo::object method meta__ - - The package injects a new method __meta__ into __oo::object__\. - __oo::object__ combines the data for its class \(as provided by - __oo::meta::metadata__\), with a local variable *meta* to produce a - local picture of metadata\. This method provides the following additional - commands: - - - __oo::object method meta cget__ ?*field*? ?*\.\.\.*? *field* - - Attempts to locate a singlar leaf, and return its value\. For single option - lookups, this is faster than __my meta getnull__ ?*field*? ?*\.\.\.*? - *field*\], because it performs a search instead directly instead of - producing the recursive merge product between the class metadata, the local - *meta* variable, and THEN performing the search\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tcloo* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[TOOL](\.\./\.\./\.\./\.\./index\.md\#tool), [TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo) - -# CATEGORY - -TclOO - -# COPYRIGHT - -Copyright © 2015 Sean Woods DELETED embedded/md/tcllib/files/modules/ooutil/ooutil.md Index: embedded/md/tcllib/files/modules/ooutil/ooutil.md ================================================================== --- embedded/md/tcllib/files/modules/ooutil/ooutil.md +++ embedded/md/tcllib/files/modules/ooutil/ooutil.md @@ -1,219 +0,0 @@ - -[//000000001]: # (oo::util \- Utility commands for TclOO) -[//000000002]: # (Generated from file 'ooutil\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011\-2015 Andreas Kupries, BSD licensed) -[//000000004]: # (oo::util\(n\) 1\.2\.2 tcllib "Utility commands for TclOO") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -oo::util \- Utility commands for TclOO - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require oo::util ?1\.2\.2? - -[__mymethod__ *method* ?*arg*\.\.\.?](#1) -[__classmethod__ *name* *arguments* *body*](#2) -[__classvariable__ ?*arg*\.\.\.?](#3) -[__link__ *method*\.\.\.](#4) -[__link__ \{*alias* *method*\}\.\.\.](#5) -[__ooutil::singleton__ ?*arg*\.\.\.?](#6) - -# DESCRIPTION - -This package provides a convenience command for the easy specification of -instance methods as callback commands, like timers, file events, Tk bindings, -etc\. - -# COMMANDS - - - __mymethod__ *method* ?*arg*\.\.\.? - - This command is available within instance methods\. It takes a method name - and, possibly, arguments for the method and returns a command prefix which, - when executed, will invoke the named method of the object we are in, with - the provided arguments, and any others supplied at the time of actual - invokation\. - - Note: The command is equivalent to and named after the command provided by - the OO package __[snit](\.\./snit/snit\.md)__ for the same purpose\. - - - __classmethod__ *name* *arguments* *body* - - This command is available within class definitions\. It takes a method name - and, possibly, arguments for the method and creates a method on the class, - available to a user of the class and of derived classes\. - - Note: The command is equivalent to the command __typemethod__ provided - by the OO package __[snit](\.\./snit/snit\.md)__ for the same purpose\. - - Example - - oo::class create ActiveRecord { - classmethod find args { puts "[self] called with arguments: $args" } - } - oo::class create Table { - superclass ActiveRecord - } - puts [Table find foo bar] - # ====== - # which will write - # ====== - # ::Table called with arguments: foo bar - - - __classvariable__ ?*arg*\.\.\.? - - This command is available within instance methods\. It takes a series of - variable names and makes them available in the method's scope\. The - originating scope for the variables is the class \(instance\) the object - instance belongs to\. In other words, the referenced variables are shared - between all instances of their class\. - - Note: The command is roughly equivalent to the command __typevariable__ - provided by the OO package __[snit](\.\./snit/snit\.md)__ for the same - purpose\. The difference is that it cannot be used in the class definition - itself\. - - Example: - - % oo::class create Foo { - method bar {z} { - classvariable x y - return [incr x $z],[incr y] - } - } - ::Foo - % Foo create a - ::a - % Foo create b - ::b - % a bar 2 - 2,1 - % a bar 3 - 5,2 - % b bar 7 - 12,3 - % b bar -1 - 11,4 - % a bar 0 - 11,5 - - - __link__ *method*\.\.\. - - - __link__ \{*alias* *method*\}\.\.\. - - This command is available within instance methods\. It takes a list of method - names and/or pairs of alias\- and method\-name and makes the named methods - available to all instance methods without requiring the __my__ command\. - - The alias name under which the method becomes available defaults to the - method name, except where explicitly specified through an alias/method pair\. - - Examples: - - link foo - # The method foo is now directly accessible as foo instead of my foo. - - link {bar foo} - # The method foo is now directly accessible as bar. - - link a b c - # The methods a, b, and c all become directly acessible under their - # own names. - - The main use of this command is expected to be in instance constructors, for - convenience, or to set up some methods for use in a mini DSL\. - - - __ooutil::singleton__ ?*arg*\.\.\.? - - This command is a meta\-class, i\.e\. a variant of the builtin - __oo::class__ which ensures that it creates only a single instance of - the classes defined with it\. - - Syntax and results are like for __oo::class__\. - - Example: - - % oo::class create example { - self mixin singleton - method foo {} {self} - } - ::example - % [example new] foo - ::oo::Obj22 - % [example new] foo - ::oo::Obj22 - -# AUTHORS - -Donal Fellows, Andreas Kupries - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *oo::util* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[snit\(n\)](\.\./snit/snit\.md) - -# KEYWORDS - -[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), [class -methods](\.\./\.\./\.\./\.\./index\.md\#class\_methods), [class -variables](\.\./\.\./\.\./\.\./index\.md\#class\_variables), [command -prefix](\.\./\.\./\.\./\.\./index\.md\#command\_prefix), -[currying](\.\./\.\./\.\./\.\./index\.md\#currying), [method -reference](\.\./\.\./\.\./\.\./index\.md\#method\_reference), [my -method](\.\./\.\./\.\./\.\./index\.md\#my\_method), -[singleton](\.\./\.\./\.\./\.\./index\.md\#singleton) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2011\-2015 Andreas Kupries, BSD licensed DELETED embedded/md/tcllib/files/modules/otp/otp.md Index: embedded/md/tcllib/files/modules/otp/otp.md ================================================================== --- embedded/md/tcllib/files/modules/otp/otp.md +++ embedded/md/tcllib/files/modules/otp/otp.md @@ -1,137 +0,0 @@ - -[//000000001]: # (otp \- RFC 2289 A One\-Time Password System) -[//000000002]: # (Generated from file 'otp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006, Pat Thoyts ) -[//000000004]: # (otp\(n\) 1\.0\.0 tcllib "RFC 2289 A One\-Time Password System") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -otp \- One\-Time Passwords - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require otp ?1\.0\.0? - -[__::otp::otp\-md4__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data*](#1) -[__::otp::otp\-md5__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data*](#2) -[__::otp::otp\-sha1__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data*](#3) -[__::otp::otp\-rmd160__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data*](#4) - -# DESCRIPTION - -This package is an implementation in Tcl of the One\-Time Password system as -described in RFC 2289 \(1\)\. This system uses message\-digest algorithms to -sequentially hash a passphrase to create single\-use passwords\. The resulting -data is then provided to the user as either hexadecimal digits or encoded using -a dictionary of 2048 words\. This system is used by OpenBSD for secure login and -can be used as a SASL mechanism for authenticating users\. - -In this implementation we provide support for four algorithms that are included -in the tcllib distribution: MD5 \(2\), MD4 \(3\), RIPE\-MD160 \(4\) and SHA\-1 \(5\)\. - -# COMMANDS - - - __::otp::otp\-md4__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data* - - - __::otp::otp\-md5__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data* - - - __::otp::otp\-sha1__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data* - - - __::otp::otp\-rmd160__ ?*\-hex*? ?*\-words*? *\-seed seed* *\-count count* *data* - -# EXAMPLES - - % otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase" - (binary gibberish) - % otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase" - SOON ARAB BURG LIMB FILE WAD - % otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase" - e249b58257c80087 - -# REFERENCES - - 1. Haller, N\. et al\., "A One\-Time Password System", RFC 2289, February 1998\. - [http://www\.rfc\-editor\.org/rfc/rfc2289\.txt](http://www\.rfc\-editor\.org/rfc/rfc2289\.txt) - - 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data - Security, Inc, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1321\.txt](http://www\.rfc\-editor\.org/rfc/rfc1321\.txt)\) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. H\. Dobbertin, A\. Bosselaers, B\. Preneel, "RIPEMD\-160, a strengthened - version of RIPEMD" - [http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf](http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf) - - 1. "Secure Hash Standard", National Institute of Standards and Technology, - U\.S\. Department Of Commerce, April 1995\. - \([http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm](http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *otp* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[SASL](\.\./sasl/sasl\.md), [md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), -[ripemd160](\.\./ripemd/ripemd160\.md), [sha1](\.\./sha1/sha1\.md) - -# KEYWORDS - -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), -[password](\.\./\.\./\.\./\.\./index\.md\#password), [rfc -2289](\.\./\.\./\.\./\.\./index\.md\#rfc\_2289), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2006, Pat Thoyts DELETED embedded/md/tcllib/files/modules/page/page_intro.md Index: embedded/md/tcllib/files/modules/page/page_intro.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_intro.md +++ embedded/md/tcllib/files/modules/page/page_intro.md @@ -1,77 +0,0 @@ - -[//000000001]: # (page\_intro \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_intro\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_intro\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_intro \- page introduction - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -*[page](\.\./\.\./\.\./\.\./index\.md\#page)* \(short for *parser generator*\) -stands for a set of related packages which help in the construction of parser -generators, and other utilities doing text processing\. - -They are mainly geared towards supporting the Tcllib application -__[page](\.\./\.\./apps/page\.md)__, with the package __page::pluginmgr__ -in a central role as the plugin management for the application\. The other -packages are performing low\-level text processing and utility tasks geared -towards parser generation and mainly accessed by -__[page](\.\./\.\./apps/page\.md)__ through plugins\. - -The packages implementing the plugins are not documented as regular packages, as -they cannot be loaded into a general interpreter, like tclsh, without extensive -preparation of the interpreter\. Preparation which is done for them by the plugin -manager\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_pluginmgr.md Index: embedded/md/tcllib/files/modules/page/page_pluginmgr.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_pluginmgr.md +++ embedded/md/tcllib/files/modules/page/page_pluginmgr.md @@ -1,814 +0,0 @@ - -[//000000001]: # (page\_pluginmgr \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_pluginmgr\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_pluginmgr\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_pluginmgr \- page plugin manager - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [CONFIG PLUGIN API](#section3) - - - [READER PLUGIN API](#section4) - - - [WRITER PLUGIN API](#section5) - - - [TRANSFORM PLUGIN API](#section6) - - - [PREDEFINED PLUGINS](#section7) - - - [FEATURES](#section8) - - - [Bugs, Ideas, Feedback](#section9) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::pluginmgr ?0\.2? -package require fileutil - -[__::page::pluginmgr::reportvia__ *cmd*](#1) -[__::page::pluginmgr::report__ *level* *text* ?*from* ?*to*??](#2) -[__::page::pluginmgr::log__ *cmd*](#3) -[__::page::pluginmgr::configuration__ *name*](#4) -[__::page::pluginmgr::reader__ *name*](#5) -[__::page::pluginmgr::rconfigure__ *dict*](#6) -[__::page::pluginmgr::rtimeable__](#7) -[__::page::pluginmgr::rtime__](#8) -[__::page::pluginmgr::rgettime__](#9) -[__::page::pluginmgr::rhelp__](#10) -[__::page::pluginmgr::rlabel__](#11) -[__::page::pluginmgr::read__ *read* *eof* ?*complete*?](#12) -[*read* *num*](#13) -[*eof*](#14) -[*done*](#15) -[__::page::pluginmgr::writer__ *name*](#16) -[__::page::pluginmgr::wconfigure__ *dict*](#17) -[__::page::pluginmgr::wtimeable__](#18) -[__::page::pluginmgr::wtime__](#19) -[__::page::pluginmgr::wgettime__](#20) -[__::page::pluginmgr::whelp__](#21) -[__::page::pluginmgr::wlabel__](#22) -[__::page::pluginmgr::write__ *chan* *data*](#23) -[__::page::pluginmgr::transform__ *name*](#24) -[__::page::pluginmgr::tconfigure__ *id* *dict*](#25) -[__::page::pluginmgr::ttimeable__ *id*](#26) -[__::page::pluginmgr::ttime__ *id*](#27) -[__::page::pluginmgr::tgettime__ *id*](#28) -[__::page::pluginmgr::thelp__ *id*](#29) -[__::page::pluginmgr::tlabel__ *id*](#30) -[__::page::pluginmgr::transform\_do__ *id* *data*](#31) -[__page\_cdefinition__](#32) -[__page\_rfeature__ *name*](#33) -[__page\_rtime__](#34) -[__page\_rgettime__](#35) -[__page\_rlabel__](#36) -[__page\_rhelp__](#37) -[__page\_roptions__](#38) -[__page\_rconfigure__ *option* *value*](#39) -[__page\_rrun__](#40) -[__page\_read__ *num*](#41) -[__page\_read\_done__](#42) -[__page\_eof__](#43) -[__page\_info__ *text* ?*from* ?*to*??](#44) -[__page\_warning__ *text* ?*from* ?*to*??](#45) -[__page\_error__ *text* ?*from* ?*to*??](#46) -[__page\_log\_info__ *text*](#47) -[__page\_log\_warning__ *text*](#48) -[__page\_log\_error__ *text*](#49) -[__page\_wfeature__](#50) -[__page\_wtime__](#51) -[__page\_wgettime__](#52) -[__page\_wlabel__](#53) -[__page\_whelp__](#54) -[__page\_woptions__](#55) -[__page\_wconfigure__ *option* *value*](#56) -[__page\_wrun__ *chan* *data*](#57) -[__page\_info__ *text* ?*from* ?*to*??](#58) -[__page\_warning__ *text* ?*from* ?*to*??](#59) -[__page\_error__ *text* ?*from* ?*to*??](#60) -[__page\_log\_info__ *text*](#61) -[__page\_log\_warning__ *text*](#62) -[__page\_log\_error__ *text*](#63) -[__page\_tfeature__](#64) -[__page\_ttime__](#65) -[__page\_tgettime__](#66) -[__page\_tlabel__](#67) -[__page\_thelp__](#68) -[__page\_toptions__](#69) -[__page\_tconfigure__ *option* *value*](#70) -[__page\_trun__ *chan* *data*](#71) -[__page\_info__ *text* ?*from* ?*to*??](#72) -[__page\_warning__ *text* ?*from* ?*to*??](#73) -[__page\_error__ *text* ?*from* ?*to*??](#74) -[__page\_log\_info__ *text*](#75) -[__page\_log\_warning__ *text*](#76) -[__page\_log\_error__ *text*](#77) - -# DESCRIPTION - -This package provides the plugin manager central to the -__[page](\.\./\.\./apps/page\.md)__ application\. It manages the various -reader, writer, configuration, and transformation plugins which actually process -the text \(read, transform, and write\)\. - -All plugins are loaded into slave interpreters specially prepared for them\. -While implemented using packages they need this special environment and are not -usable in a plain interpreter, like tclsh\. Because of that they are only -described in general terms in section [PREDEFINED PLUGINS](#section7), and -not documented as regular packages\. It is expected that they follow the APIs -specified in the sections - - 1. [CONFIG PLUGIN API](#section3) - - 1. [READER PLUGIN API](#section4) - - 1. [WRITER PLUGIN API](#section5) - - 1. [TRANSFORM PLUGIN API](#section6) - -as per their type\. - -# API - - - __::page::pluginmgr::reportvia__ *cmd* - - This command defines the callback command used by - __::page::pluginmgr::report__ \(see below\) to report input errors and - warnings\. The default is to write such reports to the standard error - channel\. - - - __::page::pluginmgr::report__ *level* *text* ?*from* ?*to*?? - - This command is used to report input errors and warnings\. By default such - reports are written to the standard error\. This can be changed by setting a - user\-specific callback command with __::page::pluginmgr::reportvia__ - \(see above\)\. - - The arguments *level* and *text* specify both the importance of the - message, and the message itself\. For the former see the package - __[logger](\.\./log/logger\.md)__ for the allowed values\. - - The optional argument *from* and *to* can be used by the caller to - indicate the location \(or range\) in the input where the reported problem - occured\. Each is a list containing two elements, the line and the column in - the input, in this order\. - - - __::page::pluginmgr::log__ *cmd* - - This command defines a log callback command to be used by loaded plugins for - the reporting of internal errors, warnings, and general information\. - Specifying the empty string as callback disables logging\. - - Note: The *cmd* has to be created by the - __[logger](\.\./log/logger\.md)__ package, or follow the same API as - such\. - - The command returns the empty string as its result\. - - - __::page::pluginmgr::configuration__ *name* - - This command loads the named configuration plugin, retrieves the options - encoded in it, and then immediately unloads it again\. - - If the *name* is the path to a file, then this files will be tried to be - loaded as a plugin first, and, if that fails, opened and its contents read - as a list of options and their arguments, separated by spaces, tabs and - newlines, possibly quotes with single and double quotes\. - - See section [CONFIG PLUGIN API](#section3) for the API expected of - configuration plugins\. - - The result of the command is the list of options retrieved\. - - - __::page::pluginmgr::reader__ *name* - - This command loads the named reader plugin and initializes it\. The result of - the command 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 section [READER PLUGIN API](#section4) for the API expected of - reader plugins\. - - - __::page::pluginmgr::rconfigure__ *dict* - - This commands configures the loaded reader plugin\. The options and their - values are provided as a Tcl dictionary\. The result of the command is the - empty string\. - - - __::page::pluginmgr::rtimeable__ - - This commands checks if the loaded reader plugin is able to collect timing - statistics\. The result of the command is a boolean flag\. The result is - __true__ if the plugin can be timed, and __false__ otherwise\. - - - __::page::pluginmgr::rtime__ - - This command activates the collection of timing statistics in the loaded - reader plugin\. - - - __::page::pluginmgr::rgettime__ - - This command retrieves the collected timing statistics of the loaded reader - plugin after it was executed\. - - - __::page::pluginmgr::rhelp__ - - This command retrieves the help string of the loaded reader plugin\. This is - expected to be in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __::page::pluginmgr::rlabel__ - - This command retrieves the human\-readable name of the loaded reader plugin\. - - - __::page::pluginmgr::read__ *read* *eof* ?*complete*? - - This command invokes the loaded reader plugin to process the input, and - returns the results of the plugin as its own result\. The input is accessible - through the callback commands *read*, and *eof*\. The optional *done* - can be used to intrecept when the plugin has completed its processing\. All - arguments are command prefixes\. - - The plugin will invoke the various callbacks in the following situations: - - * *read* *num* - - is invoked whenever input to process is needed, with the number of - characters/bytes it asks for\. The result is expected to be the input the - plugin is in need of\. - - * *eof* - - is invoked by the plugin to check if the input has reached the of the - stream\. The result is expected to be a boolean flag, __true__ when - the input has hit EOF, and __false__ otherwise\. - - * *done* - - is invoked when the plugin has completed the processing of the input\. - - - __::page::pluginmgr::writer__ *name* - - This command loads the named writer plugin and initializes it\. The result of - the command 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 section [WRITER PLUGIN API](#section5) for the API expected of - writer plugins\. - - - __::page::pluginmgr::wconfigure__ *dict* - - This commands configures the loaded writer plugin\. The options and their - values are provided as a Tcl dictionary\. The result of the command is the - empty string\. - - - __::page::pluginmgr::wtimeable__ - - This commands checks if the loaded writer plugin is able to measure - execution times\. The result of the command is a boolean flag\. The result is - __true__ if the plugin can be timed, and __false__ otherwise\. - - - __::page::pluginmgr::wtime__ - - This command activates the collection of timing statistics in the loaded - writer plugin\. - - - __::page::pluginmgr::wgettime__ - - This command retrieves the collected timing statistics of the loaded writer - plugin after it was executed\. - - - __::page::pluginmgr::whelp__ - - This command retrieves the help string of the loaded writer plugin\. This is - expected to be in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __::page::pluginmgr::wlabel__ - - This command retrieves the human\-readable name of the loaded writer plugin\. - - - __::page::pluginmgr::write__ *chan* *data* - - The loaded writer plugin is invoked to generate the output\. It is given the - *data* to generate the outpout from, and the Tcl handle *chan* of the - channel to write the generated output to\. The command returns th empty - string as its result\. - - - __::page::pluginmgr::transform__ *name* - - This command loads the named transformation plugin and initializes it\. The - result of the command is a 2\-element list containing the plugin id and a - list of options the plugin understands, in this order\. - - Multiple transformations plugins can be loaded and are identified by - handles\. - - See section [TRANSFORM PLUGIN API](#section6) for the API expected of - transformation plugins\. - - - __::page::pluginmgr::tconfigure__ *id* *dict* - - This commands configures the identified transformation plugin\. The options - and their values are provided as a Tcl dictionary\. The result of the command - is the empty string\. - - - __::page::pluginmgr::ttimeable__ *id* - - This commands checks if the identified transformation plugin is able to - collect timing statistics\. The result of the command is a boolean flag\. The - result is __true__ if the plugin can be timed, and __false__ - otherwise\. - - - __::page::pluginmgr::ttime__ *id* - - This command activates the collection of timing statistics in the identified - transformation plugin\. - - - __::page::pluginmgr::tgettime__ *id* - - This command retrieves the collected timing statistics of the identified - transformation plugin after it was executed\. - - - __::page::pluginmgr::thelp__ *id* - - This command retrieves the help string of the identified transformation - plugin\. This is expected to be in - *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __::page::pluginmgr::tlabel__ *id* - - This command retrieves the human\-readable name of the identified - transformation plugin\. - - - __::page::pluginmgr::transform\_do__ *id* *data* - - The identified transformation plugin is invoked 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\. - - - __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 is 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 - -Reader plugins are expected to provide the following commands, described below\. - - - __page\_rfeature__ *name* - - 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 section [FEATURES](#section8) for the possible features the plugin - manager will ask for\. - - - __page\_rtime__ - - This command is invoked to activate the collection of timing statistics\. - - - __page\_rgettime__ - - This command is invoked to retrieve the collected timing statistics\. - - - __page\_rlabel__ - - This command is invoked to retrieve a human\-readable label for the plugin\. - - - __page\_rhelp__ - - This command is invoked to retrieve a help text for plugin\. The text is - expected to be in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __page\_roptions__ - - This command is invoked to retrieve the options understood by the plugin\. - - - __page\_rconfigure__ *option* *value* - - This command is invoked to reconfigure the plugin, specifically the given - *option* is set to the new *value*\. - - - __page\_rrun__ - - This command is invoked to process the input stream per the current plugin - configuration\. The result of the command is the result of the processing\. - -Reader plugins expect the environment to provide the following special commands\. - - - __page\_read__ *num* - - This command is invoked to read *num* characters/bytes from the input\. Its - result has to be read characters/bytes\. - - - __page\_read\_done__ - - This command is invoked to signal that the plugin has completed the - processing of the input\. - - - __page\_eof__ - - This command is 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\. - -It is expected that a reader plugin __FOO__ is implemented by the package -__page::reader::__FOO____\. - -Reader plugins are loaded by the command __::page::pluginmgr::reader__\. At -most one reader plugin can be kept in memory\. - -# WRITER PLUGIN API - -Writer plugins are expected to provide the following commands, described below\. - - - __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\. - - See section [FEATURES](#section8) for the possible features the plugin - manager will ask for\. - - - __page\_wtime__ - - This command is invoked to activate the collection of timing statistics\. - - - __page\_wgettime__ - - This command is invoked to retrieve the collected timing statistics\. - - - __page\_wlabel__ - - This command is invoked to retrieve a human\-readable label for the plugin\. - - - __page\_whelp__ - - This command is invoked to retrieve a help text for plugin\. The text is - expected to be in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __page\_woptions__ - - This command is invoked to retrieve the options understood by the plugin\. - - - __page\_wconfigure__ *option* *value* - - This command is invoked to reconfigure the plugin, specifically the given - *option* is set to the new *value*\. - - - __page\_wrun__ *chan* *data* - - This command is invoked to process the specified *data* and write it to - the output stream *chan*\. The latter is a Tcl channel handle opened for - writing\. The result of the command is the empty string\. - -Writer plugins expect the environment to provide the following 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\. - -It is expected that a writer plugin __FOO__ is implemented by the package -__page::writer::__FOO____\. - -Writer plugins are loaded by the command __::page::pluginmgr::writer__\. At -most one writer plugin can be kept in memory\. - -# TRANSFORM PLUGIN API - -page::transform::\* Transformation plugins are expected to provide the following -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 section [FEATURES](#section8) for the possible features the plugin - manager will ask for\. - - - __page\_ttime__ - - This command is invoked to activate the collection of timing statistics\. - - - __page\_tgettime__ - - This command is invoked to retrieve the collected timing statistics\. - - - __page\_tlabel__ - - This command is invoked to retrieve a human\-readable label for the plugin\. - - - __page\_thelp__ - - This command is invoked to retrieve a help text for plugin\. The text is - expected to be in *[doctools](\.\./\.\./\.\./\.\./index\.md\#doctools)* format\. - - - __page\_toptions__ - - This command is invoked to retrieve the options understood by the plugin\. - - - __page\_tconfigure__ *option* *value* - - This command is invoked to reconfigure the plugin, specifically the given - *option* is set to the new *value*\. - - - __page\_trun__ *chan* *data* - - This command is invoked to process the specified *data* and write it to - the output stream *chan*\. The latter is a Tcl channel handle opened for - writing\. The result of the command is the empty string\. - -Transformation plugins expect the environment to provide the following 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\. - -It is expected that a transformation plugin __FOO__ is implemented by the -package __page::transform::__FOO____\. - -Transformation plugins are loaded by the command -__::page::pluginmgr::transform__\. More than one transformation plugin can be -kept in memory\. - -# PREDEFINED PLUGINS - -The following predefined plugins are known, i\.e\. provided by the page module\. - - - Configuration - - * peg - - Returns a set of options to configure the - __[page](\.\./\.\./apps/page\.md)__ application for the processing of - a PEG grammar and the generation of ME code\. See the packages - __grammar\_peg__, __grammar\_me__ and relations for more details\. - - - Reader - - * hb - - Expects a so\-called *half\-baked PEG container* as input and returns - the equivalent abstract syntax tree\. See the writer plugin *hb* for - the plugin generating this type of input\. - - * lemon - - Expects a grammar specification as understood by Richar Hipp's LEMON - parser generator and returns an abstract syntax tree for it\. - - * peg - - Expects a grammar specification in the form of a parsing expression - grammar \(PEG\) and returns an abstract syntax tree for it\. - - * ser - - Expect the serialized form of a parsing expression grammar as generated - by the package __[grammar::peg](\.\./grammar\_peg/peg\.md)__ as - input, converts it into an equivalent abstract syntax tree and returns - that\. - - * treeser - - Expects the serialized form of a tree as generated by the package - __[struct::tree](\.\./struct/struct\_tree\.md)__ as input and - returns it, after validation\. - - - Writer - - * hb - - Expects an abstract syntax tree for a parsing expression grammar as - input and writes it out in the form of a so\-called *half\-baked PEG - container*\. - - * identity - - Takes any input and writes it as is\. - - * mecpu - - Expects symbolic assembler code for the MatchEngine CPU \(See the package - __[grammar::me::cpu](\.\./grammar\_me/me\_cpu\.md)__ 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 parses input in that grammar\. - - * null - - Takes any input and writes nothing\. The logical equivalent of /dev/null\. - - * peg - - Expects an abstract syntax tree for a parsing expression grammar as - input and writes it out in the form of a canonical PEG which can be read - by the reader plugin *peg*\. - - * ser - - Expects an abstract syntax tree for a parsing expression grammar as - input and writes it out as a serialized PEG container which can be read - by the reader plugin *ser*\. - - * tpc - - Expects an abstract syntax tree for a parsing expression grammar as - input and writes it out as Tcl code initializing a PEG container as - provided by the package - __[grammar::peg](\.\./grammar\_peg/peg\.md)__\. - - * tree - - Takes any serialized tree \(per package - __[struct::tree](\.\./struct/struct\_tree\.md)__\) 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](\.\./grammar\_me/me\_cpu\.md)__ and relatives\)\. - - * reachable - - Takes an abstract syntax tree for a parsing expression grammer as input, - performs a reachability analysis, and returns the modified and annotated - tree\. - - * realizable - - Takes an abstract syntax tree for a parsing expression grammer as input, - performs an analysis of realizability, and returns the modified and - annotated tree\. - -# FEATURES - -The plugin manager currently checks the plugins for only one feature, -__timeable__\. A plugin supporting this feature is assumed to be able to -collect timing statistics on request\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_util_flow.md Index: embedded/md/tcllib/files/modules/page/page_util_flow.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_util_flow.md +++ embedded/md/tcllib/files/modules/page/page_util_flow.md @@ -1,135 +0,0 @@ - -[//000000001]: # (page\_util\_flow \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_util\_flow\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_util\_flow\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_util\_flow \- page dataflow/treewalker utility - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [FLOW API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::util::flow ?0\.1? -package require snit - -[__::page::util::flow__ *start* *flowvar* *nodevar* *script*](#1) -[*flow* __visit__ *node*](#2) -[*flow* __visitl__ *nodelist*](#3) -[*flow* __visita__ *node*\.\.\.](#4) - -# DESCRIPTION - -This package provides a single utility command for easy dataflow based -manipulation of arbitrary data structures, especially abstract syntax trees\. - -# API - - - __::page::util::flow__ *start* *flowvar* *nodevar* *script* - - This command contains the core logic to drive the walking of an arbitrary - data structure which can partitioned into separate parts\. Examples of such - structures are trees and graphs\. - - The command makes no assumptions at all about the API of the structure to be - walked, except that that its parts, here called *nodes*, are identified by - strings\. These strings are taken as is, from the arguments, and the body, - and handed back to the body, without modification\. - - Access to the actual data structure, and all decisions regarding which nodes - to visit in what order are delegated to the body of the loop, i\.e\. the - *script*\. - - The body is invoked first for the nodes in the start\-set specified via - *start*\), and from then on for the nodes the body has requested to be - visited\. The command stops when the set of nodes to visit becomes empty\. - Note that a node can be visited more than once\. The body has complete - control about this\. - - The body is invoked in the context of the caller\. The variable named by - *nodevar* will be set to the current node, and the variable named by - *flowvar* will be set to the command of the flow object through which the - body can request the nodes to visit next\. The API provided by this object is - described in the next section, [FLOW API](#section3)\. - - Note that the command makes no promises regarding the order in which nodes - are visited, excpt that the nodes requested to be visited by the current - iteration will be visited afterward, in some order\. - -# FLOW API - -This section describes the API provided by the flow object made accessible to -the body script of __::page::util::flow__\. - - - *flow* __visit__ *node* - - Invoking this method requests that the node *n* is visited after the - current iteration\. - - - *flow* __visitl__ *nodelist* - - Invoking this method requests that all the nodes found in the list - *nodelist* are visited after the current iteration\. - - - *flow* __visita__ *node*\.\.\. - - This is the variadic arguments form of the method __visitl__, see above\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[dataflow](\.\./\.\./\.\./\.\./index\.md\#dataflow), [graph -walking](\.\./\.\./\.\./\.\./index\.md\#graph\_walking), -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), [tree -walking](\.\./\.\./\.\./\.\./index\.md\#tree\_walking) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md Index: embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md +++ embedded/md/tcllib/files/modules/page/page_util_norm_lemon.md @@ -1,93 +0,0 @@ - -[//000000001]: # (page\_util\_norm\_lemon \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_util\_norm\_lemon\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_util\_norm\_lemon\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_util\_norm\_lemon \- page AST normalization, LEMON - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::util::norm\_lemon ?0\.1? -package require snit - -[__::page::util::norm::lemon__ *tree*](#1) - -# DESCRIPTION - -This package provides a single utility command which takes an AST for a lemon -grammar and normalizes it in various ways\. The result is called a *Normalized -Lemon Grammar Tree*\. - -*Note* that this package can only be used from within a plugin managed by the -package __page::pluginmgr__\. - -# API - - - __::page::util::norm::lemon__ *tree* - - This command assumes the *tree* object contains for a lemon grammar\. It - normalizes this tree in place\. The result is called a *Normalized Lemon - Grammar Tree*\. - - The exact operations performed are left undocumented for the moment\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[graph walking](\.\./\.\./\.\./\.\./index\.md\#graph\_walking), -[lemon](\.\./\.\./\.\./\.\./index\.md\#lemon), -[normalization](\.\./\.\./\.\./\.\./index\.md\#normalization), -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), [tree -walking](\.\./\.\./\.\./\.\./index\.md\#tree\_walking) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_util_norm_peg.md Index: embedded/md/tcllib/files/modules/page/page_util_norm_peg.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_util_norm_peg.md +++ embedded/md/tcllib/files/modules/page/page_util_norm_peg.md @@ -1,140 +0,0 @@ - -[//000000001]: # (page\_util\_norm\_peg \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_util\_norm\_peg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_util\_norm\_peg\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_util\_norm\_peg \- page AST normalization, PEG - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::util::norm\_peg ?0\.1? -package require snit - -[__::page::util::norm::peg__ *tree*](#1) - -# DESCRIPTION - -This package provides a single utility command which takes an AST for a parsing -expression grammar and normalizes it in various ways\. The result is called a -*Normalized PE Grammar Tree*\. - -*Note* that this package can only be used from within a plugin managed by the -package __page::pluginmgr__\. - -# API - - - __::page::util::norm::peg__ *tree* - - This command assumes the *tree* object contains for a parsing expression - grammar\. It normalizes this tree in place\. The result is called a - *Normalized PE Grammar Tree*\. - - The following operations are performd - - 1. The data for all terminals is stored in their grandparental nodes\. The - terminal nodes and their parents are removed\. Type information is - dropped\. - - 1. All nodes which have exactly one child are irrelevant and are removed, - with the exception of the root node\. The immediate child of the root is - irrelevant as well, and removed as well\. - - 1. The name of the grammar is moved from the tree node it is stored in to - an attribute of the root node, and the tree node removed\. - - The node keeping the start expression separate is removed as irrelevant - and the root node of the start expression tagged with a marker - attribute, and its handle saved in an attribute of the root node for - quick access\. - - 1. Nonterminal hint information is moved from nodes into attributes, and - the now irrelevant nodes are deleted\. - - *Note:* This transformation is dependent on the removal of all nodes - with exactly one child, as it removes the all 'Attribute' nodes - already\. Otherwise this transformation would have to put the - information into the grandparental node\. - - The default mode given to the nonterminals is __value__\. - - Like with the global metadata definition specific information is moved - out out of nodes into attributes, the now irrelevant nodes are deleted, - and the root nodes of all definitions are tagged with marker - attributes\. This provides us with a mapping from nonterminal names to - their defining nodes as well, which is saved in an attribute of the - root node for quick reference\. - - At last the range in the input covered by a definition is computed\. The - left extent comes from the terminal for the nonterminal symbol it - defines\. The right extent comes from the rightmost child under the - definition\. While this not an expression tree yet the location data is - sound already\. - - 1. The remaining nodes under all definitions are transformed into proper - expression trees\. First character ranges, followed by unary operations, - characters, and nonterminals\. At last the tree is flattened by the - removal of superfluous inner nodes\. - - The order matters, to shed as much nodes as possible early, and to - avoid unnecessary work later\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [graph -walking](\.\./\.\./\.\./\.\./index\.md\#graph\_walking), -[normalization](\.\./\.\./\.\./\.\./index\.md\#normalization), -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), [tree -walking](\.\./\.\./\.\./\.\./index\.md\#tree\_walking) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_util_peg.md Index: embedded/md/tcllib/files/modules/page/page_util_peg.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_util_peg.md +++ embedded/md/tcllib/files/modules/page/page_util_peg.md @@ -1,154 +0,0 @@ - -[//000000001]: # (page\_util\_peg \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_util\_peg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_util\_peg\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_util\_peg \- page PEG transformation utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::util::peg ?0\.1? -package require snit - -[__::page::util::peg::symbolNodeOf__ *tree* *node*](#1) -[__::page::util::peg::symbolOf__ *tree* *node*](#2) -[__::page::util::peg::updateUndefinedDueRemoval__ *tree*](#3) -[__::page::util::peg::flatten__ *treequery* *tree*](#4) -[__::page::util::peg::getWarnings__ *tree*](#5) -[__::page::util::peg::printWarnings__ *msg*](#6) -[__::page::util::peg::peOf__ *tree* *eroot*](#7) -[__::page::util::peg::printTclExpr__ *pe*](#8) - -# DESCRIPTION - -This package provides a few common operations to PEG transformations\. They -assume a *Normalized PE Grammar Tree* as input, see the package -__page::util::norm::peg__, possibly augmented with attributes coming from -transformations not in conflict with the base definition\. - -# API - - - __::page::util::peg::symbolNodeOf__ *tree* *node* - - Given an arbitrary expression *node* in the AST *tree* it determines the - node \(itself or an ancestor\) containing the name of the nonterminal symbol - the node belongs to, and returns its id\. The result is either the root of - the tree \(for the start expression\), or a definition node\. - - - __::page::util::peg::symbolOf__ *tree* *node* - - As __::page::util::peg::symbolNodeOf__, but returns the symbol name - instead of the node\. - - - __::page::util::peg::updateUndefinedDueRemoval__ *tree* - - The removal of nodes in the AST *tree* can cause symbols to lose one or - more users\. - - A used by B and C, - B is reachable, - C is not, - - so A now loses the node in the expression for C calling it, - or rather, not calling it anymore. - - This command updates the cross\-references and which nonterminals are now - undefined\. - - - __::page::util::peg::flatten__ *treequery* *tree* - - This commands flattens nested sequence and choice operators in the AST - *tree*, re\-using the __[treeql](\.\./treeql/treeql\.md)__ object - *treequery* to run the query determining which nodes to cut\. - - - __::page::util::peg::getWarnings__ *tree* - - This command looks at the attributes of the AST *tree* for problems with - the grammar and issues warnings\. They do not prevent us from writing the - grammar, but still represent problems with it the user should be made aware - of\. - - The result of the command is a dictionary mapping nonterminal names to their - associated warnings\. - - - __::page::util::peg::printWarnings__ *msg* - - The argument of the command is a dictionary mapping nonterminal names to - their associated warnings, as generated by, for example, the command - __::page::util::peg::getWarnings__\. - - The warnings contained therein are formatted and then printed via the log - command __page\_info__\. This means that this command can be used only - from within a plugin managed by the package __page::pluginmgr__\. - - - __::page::util::peg::peOf__ *tree* *eroot* - - This command converts the parsing expression starting at the node *eroot* - in the AST *tree* into a nested list\. The exact syntax of this list - specified by the package __[grammar::peg](\.\./grammar\_peg/peg\.md)__\. - - - __::page::util::peg::printTclExpr__ *pe* - - This command converts the parsing expression contained in the nested list - *pe* into a Tcl string which can be placed into a Tcl script\. See the - package __[grammar::peg](\.\./grammar\_peg/peg\.md)__ for the exact - syntax of *pe*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [page](\.\./\.\./\.\./\.\./index\.md\#page), -[parser generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), [parsing -expression grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/page/page_util_quote.md Index: embedded/md/tcllib/files/modules/page/page_util_quote.md ================================================================== --- embedded/md/tcllib/files/modules/page/page_util_quote.md +++ embedded/md/tcllib/files/modules/page/page_util_quote.md @@ -1,113 +0,0 @@ - -[//000000001]: # (page\_util\_quote \- Parser generator tools) -[//000000002]: # (Generated from file 'page\_util\_quote\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007 Andreas Kupries ) -[//000000004]: # (page\_util\_quote\(n\) 1\.0 tcllib "Parser generator tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -page\_util\_quote \- page character quoting utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require page::util::quote ?0\.1? -package require snit - -[__::page::util::quote::unquote__ *char*](#1) -[__::page::util::quote::quote'tcl__ *char*](#2) -[__::page::util::quote::quote'tclstr__ *char*](#3) -[__::page::util::quote::quote'tclcom__ *char*](#4) - -# DESCRIPTION - -This package provides a few utility commands to convert characters into various -forms\. - -# API - - - __::page::util::quote::unquote__ *char* - - A character, as stored in an abstract syntax tree by a PEG processor \(See - the packages __grammar::peg::interpreter__, __grammar::me__, and - their relations\), i\.e\. in some quoted form, is converted into the equivalent - Tcl character\. The character is returned as the result of the command\. - - - __::page::util::quote::quote'tcl__ *char* - - This command takes a Tcl character \(internal representation\) and converts it - into a string which is accepted by the Tcl parser, will regenerate the - character in question and is 7bit ASCII\. The string is returned as the - result of this command\. - - - __::page::util::quote::quote'tclstr__ *char* - - This command takes a Tcl character \(internal representation\) and converts it - into a string which is accepted by the Tcl parser and will generate a human - readable representation of the character in question\. The string is returned - as the result of this command\. - - The string does not use any unprintable characters\. It may use - backslash\-quoting\. High UTF characters are quoted to avoid problems with the - still prevalent ascii terminals\. It is assumed that the string will be used - in a double\-quoted environment\. - - - __::page::util::quote::quote'tclcom__ *char* - - This command takes a Tcl character \(internal representation\) and converts it - into a string which is accepted by the Tcl parser when used within a Tcl - comment\. The string is returned as the result of this command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *page* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[page](\.\./\.\./\.\./\.\./index\.md\#page), [parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator), -[quoting](\.\./\.\./\.\./\.\./index\.md\#quoting), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing) - -# CATEGORY - -Page Parser Generator - -# COPYRIGHT - -Copyright © 2007 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pki/pki.md Index: embedded/md/tcllib/files/modules/pki/pki.md ================================================================== --- embedded/md/tcllib/files/modules/pki/pki.md +++ embedded/md/tcllib/files/modules/pki/pki.md @@ -1,271 +0,0 @@ - -[//000000001]: # (pki \- public key encryption) -[//000000002]: # (Generated from file 'pki\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries) -[//000000004]: # (pki\(n\) 0\.10 tcllib "public key encryption") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pki \- Implementation of the public key cipher - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pki ?0\.10? - -[__::pki::encrypt__ ?*\-binary*? ?*\-hex*? ?*\-pad*? ?*\-nopad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key*](#1) -[__::pki::decrypt__ ?*\-binary*? ?*\-hex*? ?*\-unpad*? ?*\-nounpad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key*](#2) -[__::pki::sign__ *input* *key* ?*algo*?](#3) -[__::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*?](#4) -[__::pki::key__ *key* ?*password*? ?*encodePem*?](#5) -[__::pki::pkcs::parse\_key__ *key* ?*password*?](#6) -[__::pki::x509::parse\_cert__ *cert*](#7) -[__::pki::rsa::generate__ *bitlength* ?*exponent*?](#8) -[__::pki::x509::verify\_cert__ *cert* *trustedcerts* ?*intermediatecerts*?](#9) -[__::pki::x509::validate\_cert__ *cert* ?__\-sign\_message__ *dn\_of\_signer*? ?__\-encrypt\_message__ *dn\_of\_signer*? ?__\-sign\_cert__ *dn\_to\_be\_signed* *ca\_depth*? ?__\-ssl__ *dn*?](#10) -[__::pki::pkcs::create\_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*?](#11) -[__::pki::pkcs::parse\_csr__ *csr*](#12) -[__::pki::x509::create\_cert__ *signreqlist* *cakeylist* *serial\_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*?](#13) - -# DESCRIPTION - -# COMMANDS - - - __::pki::encrypt__ ?*\-binary*? ?*\-hex*? ?*\-pad*? ?*\-nopad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key* - - Encrypt a message using PKI \(probably RSA\)\. Requires the caller to specify - either __\-priv__ to encrypt with the private key or __\-pub__ to - encrypt with the public key\. The default option is to pad and return in hex\. - One of __\-pub__ or __\-priv__ must be specified\. The __\-hex__ - option causes the data to be returned in encoded as a hexidecimal string, - while the __\-binary__ option causes the data to be returned as a binary - string\. If they are specified multiple times, the last one specified is - used\. The __\-pad__ option causes the data to be padded per PKCS\#1 prior - to being encrypted\. The __\-nopad__ inhibits this behaviour\. If they are - specified multiple times, the last one specified is used\. The input to - encrypt is specified as *input*\. The *key* parameter, holding the key to - use, is a return value from either __::pki::pkcs::parse\_key__, - __::pki::x509::parse\_cert__, or __::pki::rsa::generate__\. - - Mapping to OpenSSL's __openssl__ application: - - 1. "openssl rsautl \-encrypt" == "::pki::encrypt \-binary \-pub" - - 1. "openssl rsautl \-sign" == "::pki::encrypt \-binary \-priv" - - - __::pki::decrypt__ ?*\-binary*? ?*\-hex*? ?*\-unpad*? ?*\-nounpad*? ?*\-priv*? ?*\-pub*? ?*\-\-*? *input* *key* - - Decrypt a message using PKI \(probably RSA\)\. See __::pki::encrypt__ for - option handling\. - - Mapping to OpenSSL's __openssl__ application: - - 1. "openssl rsautl \-decrypt" == "::pki::decrypt \-binary \-priv" - - 1. "openssl rsautl \-verify" == "::pki::decrypt \-binary \-pub" - - - __::pki::sign__ *input* *key* ?*algo*? - - Digitally sign message *input* using the private *key*\. - - If *algo* is ommited "sha1" is assumed\. Possible values for *algo* - include "__md5__", "__sha1__", "__sha256__", and "__raw__"\. - - Specifying "__raw__" for *algo* will inhibit the building of an ASN\.1 - structure to encode which hashing algorithm was chosen\. *Attention*: In - this case the corresponding __pkgi::verify__ must be called __with__ - algorithm information\. Conversely, specifying a non\-"__raw__" algorithm - here means that the corresponding __pkgi::verify__ invokation has to be - made *without* algorithm information\. - - The *input* should be the plain text, hashing will be performed on it\. - - The *key* should include the private key\. - - - __::pki::verify__ *signedmessage* *plaintext* *key* ?*algo*? - - Verify a digital signature using a public *key*\. Returns true or false\. - - *Attention*: The algorithm information *algo* has to be specified if and - only if the __pki::sign__ which generated the *signedmessage* was - called with algorithm "__raw__"\. This inhibited the building of the - ASN\.1 structure encoding the chosen hashing algorithm\. Conversely, if a - proper algorithm was specified during signing then you *must not* specify - an algorithm here\. - - - __::pki::key__ *key* ?*password*? ?*encodePem*? - - Convert a key structure into a serialized PEM \(default\) or DER encoded - private key suitable for other applications\. For RSA keys this means PKCS\#1\. - - - __::pki::pkcs::parse\_key__ *key* ?*password*? - - Convert a PKCS\#1 private *key* into a usable key, i\.e\. one which can be - used as argument for __::pki::encrypt__, __::pki::decrypt__, - __::pki::sign__, and __::pki::verify__\. - - - __::pki::x509::parse\_cert__ *cert* - - Convert an X\.509 certificate to a usable \(public\) key, i\.e\. one which can be - used as argument for __::pki:encrypt__, __::pki::decrypt__, and - __::pki::verify__\. The *cert* argument can be either PEM or DER - encoded\. - - - __::pki::rsa::generate__ *bitlength* ?*exponent*? - - Generate a new RSA key pair, the parts of which can be used as argument for - __::pki::encrypt__, __::pki::decrypt__, __::pki::sign__, and - __::pki::verify__\. The *bitlength* argument is the length of the - public key modulus\. The *exponent* argument should generally not be - specified unless you really know what you are doing\. - - - __::pki::x509::verify\_cert__ *cert* *trustedcerts* ?*intermediatecerts*? - - Verify that a trust can be found between the certificate specified in the - *cert* argument and one of the certificates specified in the list of - certificates in the *trustedcerts* argument\. \(Eventually the chain can be - through untrusted certificates listed in the *intermediatecerts* argument, - but this is currently unimplemented\)\. The certificates specified in the - *cert* and *trustedcerts* option should be parsed \(from - __::pki::x509::parse\_cert__\)\. - - - __::pki::x509::validate\_cert__ *cert* ?__\-sign\_message__ *dn\_of\_signer*? ?__\-encrypt\_message__ *dn\_of\_signer*? ?__\-sign\_cert__ *dn\_to\_be\_signed* *ca\_depth*? ?__\-ssl__ *dn*? - - Validate that a certificate is valid to be used in some capacity\. If - multiple options are specified they must all be met for this procedure to - return "true"\. Currently, only the __\-sign\_cert__ option is functional\. - Arguments for the __\-sign\_cert__ option are *dn\_to\_be\_signed* and - *ca\_depth*\. The *dn\_to\_be\_signed* is the distinguished from the subject - of a certificate to verify that the certificate specified in the *cert* - argument can sign\. The *ca\_depth* argument is used to indicate at which - depth the verification should be done at\. Some certificates are limited to - how far down the chain they can be used to verify a given certificate\. - - - __::pki::pkcs::create\_csr__ *keylist* *namelist* ?*encodePem*? ?*algo*? - - Generate a certificate signing request from a key pair specified in the - *keylist* argument\. The *namelist* argument is a list of "name" followed - by "value" pairs to encoding as the requested distinguished name in the CSR\. - The *encodePem* option specifies whether or not the result should be PEM - encoded or DER encoded\. A "true" value results in the result being PEM - encoded, while any other value 9results in the the result being DER encoded\. - DER encoding is the default\. The *algo* argument specifies the hashing - algorithm we should use to sign this certificate signing request with\. The - default is "sha1"\. Other possible values include "md5" and "sha256"\. - - - __::pki::pkcs::parse\_csr__ *csr* - - Parse a Certificate Signing Request\. The *csr* argument can be either PEM - or DER encoded\. - - - __::pki::x509::create\_cert__ *signreqlist* *cakeylist* *serial\_number* *notBefore* *notAfter* *isCA* *extensions* ?*encodePem*? ?*algo*? - - Sign a signing request \(usually from __::pki::pkcs::create\_csr__ or - __::pki::pkcs::parse\_csr__\) with a Certificate Authority \(CA\) - certificate\. The *signreqlist* argument should be the parsed signing - request\. The *cakeylist* argument should be the parsed CA certificate\. The - *serial\_number* argument should be a serial number unique to this - certificate from this certificate authority\. The *notBefore* and - *notAfter* arguments should contain the time before and after which - \(respectively\) the certificate should be considered invalid\. The time should - be encoded as something __clock format__ will accept \(i\.e\., the results - of __clock seconds__ and __clock add__\)\. The *isCA* argument is a - boolean argumen describing whether or not the signed certificate should be a - a CA certificate\. If specified as true the "id\-ce\-basicConstraints" - extension is added with the arguments of "critical" being true, "allowCA" - being true, and caDepth being \-1 \(infinite\)\. The *extensions* argument is - a list of extensions and their parameters that should be encoded into the - created certificate\. Currently only one extension is understood - \("id\-ce\-basicConstraints"\)\. It accepts three arguments *critical* - *allowCA* *caDepth*\. The *critical* argument to this extension \(and - any extension\) whether or not the validator should reject the certificate as - invalid if it does not understand the extension \(if set to "true"\) or should - ignore the extension \(if set to "false"\)\. The *allowCA* argument is used - to specify as a boolean value whether or not we can be used a certificate - authority \(CA\)\. The *caDepth* argument indicates how many children CAs can - be children of this CA in a depth\-wise fashion\. A value of "0" for the - *caDepth* argument means that this CA cannot sign a CA certificate and - have the result be valid\. A value of "\-1" indicates infinite depth\. - -# EXAMPLES - - - - - -# REFERENCES - -# AUTHORS - -Roy Keene - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *rsa* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[aes\(n\)](\.\./aes/aes\.md), [blowfish\(n\)](\.\./blowfish/blowfish\.md), -[des\(n\)](\.\./des/des\.md), [md5\(n\)](\.\./md5/md5\.md), -[sha1\(n\)](\.\./sha1/sha1\.md) - -# KEYWORDS - -[cipher](\.\./\.\./\.\./\.\./index\.md\#cipher), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), [public key -cipher](\.\./\.\./\.\./\.\./index\.md\#public\_key\_cipher), -[rsa](\.\./\.\./\.\./\.\./index\.md\#rsa), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries DELETED embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md Index: embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md ================================================================== --- embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md +++ embedded/md/tcllib/files/modules/pluginmgr/pluginmgr.md @@ -1,399 +0,0 @@ - -[//000000001]: # (pluginmgr \- Plugin management) -[//000000002]: # (Generated from file 'pluginmgr\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005 Andreas Kupries ) -[//000000004]: # (pluginmgr\(n\) 0\.3 tcllib "Plugin management") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pluginmgr \- Manage a plugin - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PUBLIC API](#section2) - - - [PACKAGE COMMANDS](#subsection1) - - - [OBJECT COMMAND](#subsection2) - - - [OBJECT METHODS](#subsection3) - - - [OBJECT CONFIGURATION](#subsection4) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require pluginmgr ?0\.3? - -[__::pluginmgr__ *objectName* ?*option value*\.\.\.?](#1) -[__::pluginmgr::paths__ *objectName* *name*\.\.\.](#2) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#3) -[*objectName* __clone__](#4) -[*objectName* __configure__](#5) -[*objectName* __configure__ *option*](#6) -[*objectName* __configure__ __\-option__ *value*\.\.\.](#7) -[*objectName* __cget__ __\-option__](#8) -[*objectName* __destroy__](#9) -[*objectName* __do__ *arg*\.\.\.](#10) -[*objectName* __interpreter__](#11) -[*objectName* __plugin__](#12) -[*objectName* __load__ *string*](#13) -[*objectName* __unload__](#14) -[*objectName* __list__](#15) -[*objectName* __path__ *path*](#16) -[*objectName* __paths__](#17) - -# DESCRIPTION - -This package provides commands and objects for the generic management of plugins -which can be loaded into an application\. - -To avoid the implementation of yet another system to locate Tcl code the system -provides by this package is built on top of the regular package management -system\. Each plugin is considered as a package and a simple invokation of -__package require__ is enough to locate and load it, if it exists\. The only -time we will need additional paths is when a plugin manager is part of a wrapped -application and has to be able to search for plugins existing outside of that -application\. For this situation the package provides a command to create a -general set of such paths based on names for the plugin manager and/or -application in question\. - -The main contribution of this package is a generic framework which allows the -easy declaration of - - 1. How to translate a plugin name to the name of the package implementing it, - and vice versa\. - - 1. The list of commands a plugin has to provide as API, and also of more - complex checks as code\. - - 1. The list of commands expected by the plugin from the environment\. - -This then allows the easy generation of plugin managers customized to particular -types of plugins for an application\. - -It should be noted that all plugin code is considered untrusted and will always -be executed within a safe interpreter\. The interpreter is enabled enough to -allow plugins the loading of all additional packages they may need\. - -# PUBLIC API - -## PACKAGE COMMANDS - - - __::pluginmgr__ *objectName* ?*option value*\.\.\.? - - This command creates a new plugin manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [OBJECT COMMAND](#subsection2) and [OBJECT - METHODS](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - - The options and their values coming after the name of the object are used to - set the initial configuration of the mamager object, specifying the - applicable plugins and their API\. - - - __::pluginmgr::paths__ *objectName* *name*\.\.\. - - This utility command adds a set of paths to the specified object, based on - the given *name*s\. It will search for: - - 1. The environment variable __*name*\_PLUGINS__\. Its contents will be - interpreted as a list of package paths\. The entries have to be - separated by either __:__ \(unix\) or __;__ \(windows\)\. - - The name will be converted to upper\-case letters\. - - 1. The registry entry "HKEY\_LOCAL\_MACHINE\\SOFTWARE\\*name*\\PLUGINS"\. Its - contents will be interpreted as a list of package paths\. The entries - have to be separated by __;__\. This item is considered only when on - Windows \(tm\)\. - - The casing of letters is not changed\. - - 1. The registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\*name*\\PLUGINS"\. Its - contents will be interpreted as a list of package paths\. The entries - have to be separated by __;__\. This item is considered only when on - Windows \(tm\)\. - - The casing of letters is not changed\. - - 1. The directory "~/\.*name*/plugin"\. - - 1. The directory "~/\.*name*/plugins"\. - - The casing of letters is not changed\. - - and add all the paths found that way to the list of package paths maintained - by the object\. - - If *name* is namespaced each item in the list will be repeated per prefix - of *name*, with conversion of :\-sequences into the proper separator - \(underscore for environment variables, backslash for registry entries, and / - for directories\)\. - - Examples: - - ::pluginmgr::paths ::obj docidx - - => env DOCIDX_PLUGINS - reg HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS - reg HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS - path ~/.docidx/plugins - - ::pluginmgr::paths ::obj doctools::idx - - => env DOCTOOLS_PLUGINS - env DOCTOOLS_IDX_PLUGINS - reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS - reg HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS - reg HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS - reg HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS - path ~/.doctools/plugin - path ~/.doctools/idx/plugin - -## OBJECT COMMAND - -All commands created by the command __::pluginmgr__ \(See section [PACKAGE -COMMANDS](#subsection1)\) have the following general form and may be used to -invoke various operations on their plugin manager object\. - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [OBJECT METHODS](#subsection3) for - the detailed specifications\. - -## OBJECT METHODS - - - *objectName* __clone__ - - This method creates a new plugin management object and returns the - associated object command\. The generated object is a clone of the object the - method was invoked on\. I\.e\. the new object will have the same configuration - as the current object\. With regard to state, if the current object has a - plugin loaded then this plugin and all associated state is moved to the - generated clone and the current object is reset into the base state \(no - plugin loaded\)\. In this manner a configured plugin manager is also a factory - for loaded plugins\. - - - *objectName* __configure__ - - The method returns a list of all known options and their current values when - called without any arguments\. - - - *objectName* __configure__ *option* - - The method behaves like the method __cget__ when called with a single - argument and returns the value of the option specified by said argument\. - - - *objectName* __configure__ __\-option__ *value*\.\.\. - - The method reconfigures the specified __option__s of the object, setting - them to the associated *value*s, when called with an even number of - arguments, at least two\. - - The legal options are described in the section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __cget__ __\-option__ - - This method expects a legal configuration option as argument and will return - the current value of that option for the object the method was invoked for\. - - The legal configuration options are described in section [OBJECT - CONFIGURATION](#subsection4)\. - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __do__ *arg*\.\.\. - - This method interprets its list of arguments as the words of a command and - invokes this command in the execution context of the plugin\. The result of - the invoked command is made the result of the method\. The call will fail - with an error if no valid plugin has been loaded into the manager object\. - - - *objectName* __interpreter__ - - This method returns the handle of the safe interpreter the current plugin is - loaded into\. An empty string as return value signals that the manager - currently has no valid plugin loaded\. - - - *objectName* __plugin__ - - This method returns the name of the plugin currently loaded\. An empty string - as return value signals that the manager currently has no valid plugin - loaded\. - - - *objectName* __load__ *string* - - This method loads, validates, and initializes a named plugin into the - manager object\. - - The algorithm to locate and load the plugin employed is: - - 1. If the *string* contains the path to an existing file then this file - is taken as the implementation of the plugin\. - - 1. Otherwise the plugin name is translated into a package name via the - value of the option __\-pattern__ and then loaded through the - regular package management\. - - 1. The load fails\. - - The algorithm to validate and initialize the loaded code is: - - 1. If the option __\-api__ is non\-empty introspection commands are used - to ascertain that the plugin provides the listed commands\. - - 1. If the option __\-check__ is non\-empty the specified command prefix - is called\. - - 1. If either of the above fails the candidate plugin is unloaded again - - 1. Otherwise all the commands specified via the option __\-cmds__ are - installed in the plugin\. - - A previously loaded plugin is discarded, but only if the new plugin was - found and sucessfully validated and initialized\. Note that there will be no - intereference between old and new plugin as both will be put into separate - safe interpreters\. - - - *objectName* __unload__ - - This method unloads the currently loaded plugin\. It returns the empty - string\. The call will be silently ignored if no plugin is loaded at all\. - - - *objectName* __list__ - - This method uses the contents of the option __\-pattern__ to find all - packages which can be plugins under the purview of this manager object\. It - translates their names into plugin names and returns a list containing them\. - - - *objectName* __path__ *path* - - This methods adds the specified *path* to the list of additional package - paths to look at when searching for a plugin\. It returns the empty string\. - Duplicate paths are ignored, i\.e\. each path is added only once\. Paths are - made absolute, but are not normalized\. - - - *objectName* __paths__ - - This method returns a list containing all additional paths which have been - added to the plugin manager object since its creation\. - -## OBJECT CONFIGURATION - -All plugin manager objects understand the following configuration options: - - - __\-pattern__ *string* - - The value of this option is a glob pattern which has to contain exactly one - '\*'\-operator\. All packages whose names match this pattern are the plugins - recognized by the manager object\. And vice versa, the replacement of the - '\*'\-operator with a plugin name will yield the name of the package - implementing that plugin\. - - This option has no default, except if option __\-name__ was set\. It has - to be set before attempting to load a plugin, either directly, or through - option __\-name__\. - - - __\-api__ *list* - - The value of this option is a list of command names, and any plugin loaded - has to provide these commands\. Names which are not fully qualified are - considered to be rooted in the global namespace\. If empty no expectations - are made on the plugin\. The default value is the empty list\. - - - __\-check__ *cmdprefix* - - The value of this option is interpreted as a command prefix\. Its purpose is - to perform complex checks on a loaded plugin package to validate it, which - go beyond a simple list of provided commands\. - - It is called with the manager object command as the only argument and has to - return a boolean value\. A value of __true__ will be interpreted to mean - that the candidate plugin passed the test\. The call will happen if and only - if the candidate plugin already passed the basic API check specified through - the option __\-api__\. - - The default value is the empty list, which causes the manager object to - suppress the call and to assume the candidate plugin passes\. - - - __\-cmds__ *dict* - - The value of this option is a dictionary\. It specifies the commands which - will be made available to the plugin \(as keys\), and the trusted commands in - the environment which implement them \(as values\)\. The trusted commands will - be executed in the interpreter specified by the option __\-cmdip__\. The - default value is the empty dictionary\. - - - __\-cmdip__ *ipspec* - - The value of this option is the path of the interpreter where the trusted - commands given to the plugin will be executed in\. The default is the empty - string, referring to the current interpreter\. - - - __\-setup__ *cmdprefix* - - The value of this option is interpreted as a command prefix\. - - It is called whenever a new safe interpreter for a plugin has been created, - but before a plugin is loaded\. It is provided with the manager object - command and the interpreter handle as its only arguments\. Any return value - will be ignored\. - - Its purpose is give a user of the plugin management the ability to define - commands, packages, etc\. a chosen plugin may need while being loaded\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pluginmgr* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[plugin management](\.\./\.\./\.\./\.\./index\.md\#plugin\_management), [plugin -search](\.\./\.\./\.\./\.\./index\.md\#plugin\_search) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2005 Andreas Kupries DELETED embedded/md/tcllib/files/modules/png/png.md Index: embedded/md/tcllib/files/modules/png/png.md ================================================================== --- embedded/md/tcllib/files/modules/png/png.md +++ embedded/md/tcllib/files/modules/png/png.md @@ -1,217 +0,0 @@ - -[//000000001]: # (png \- Image manipulation) -[//000000002]: # (Generated from file 'png\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Code: Aaron Faupell ) -[//000000004]: # (Copyright © 2004, Doc: Andreas Kupries ) -[//000000005]: # (png\(n\) 0\.3 tcllib "Image manipulation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -png \- PNG querying and manipulation of meta data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require crc32 -package require png ?0\.3? - -[__::png::validate__ *file*](#1) -[__::png::isPNG__ *file*](#2) -[__::png::imageInfo__ *file*](#3) -[__::png::getTimestamp__ *file*](#4) -[__::png::setTimestamp__ *file* *time*](#5) -[__::png::getComments__ *file*](#6) -[__::png::removeComments__ *file*](#7) -[__::png::addComment__ *file* *keyword* *text*](#8) -[__::png::addComment__ *file* *keyword* *lang* *keyword2* *text*](#9) -[__::png::getPixelDimension__ *file*](#10) -[__::png::image__ *file*](#11) -[__::png::write__ *file* *data*](#12) - -# DESCRIPTION - -This package provides commands to query and modify PNG images\. PNG stands for -*Portable Network Graphics* and is specified at -[http://www\.libpng\.org/pub/png/spec/1\.2](http://www\.libpng\.org/pub/png/spec/1\.2)\. - -# COMMANDS - - - __::png::validate__ *file* - - Returns a value indicating if *file* is a valid PNG file\. The file is - checked for PNG signature, each chunks checksum is verified, existence of a - data chunk is verified, first chunk is checked for header, last chunk is - checked for ending\. Things *not* checked for are: validity of values - within a chunk, multiple header chunks, noncontiguous data chunks, end chunk - before actual eof\. This procedure can take lots of time\. - - Possible return values: - - * OK - - File is a valid PNG file\. - - * SIG - - no/broken PNG signature\. - - * BADLEN - - corrupt chunk length\. - - * EOF - - premature end of file\. - - * NOHDR - - missing header chunk\. - - * CKSUM - - crc mismatch\. - - * NODATA - - missing data chunk\(s\)\. - - * NOEND - - missing end marker\. - - - __::png::isPNG__ *file* - - Returns a boolean value indicating if the file *file* starts with a PNG - signature\. This is a much faster and less intensive check than - __::png::validate__ as it does not check if the PNG data is valid\. - - - __::png::imageInfo__ *file* - - Returns a dictionary with keys __width__, __height__, __depth__, - __color__, __compression__, __filter__, and __interlace__\. - The values are the associated properties of the PNG image in *file*\. - Throws an error if file is not a PNG image, or if the checksum of the header - is invalid\. For information on interpreting the values for the returned - properties see - [http://www\.libpng\.org/pub/png/spec/1\.2/PNG\-Chunks\.html](http://www\.libpng\.org/pub/png/spec/1\.2/PNG\-Chunks\.html)\. - - - __::png::getTimestamp__ *file* - - Returns the epoch time if a timestamp chunk is found in the PNG image - contained in the *file*, otherwise returns the empty string\. Does not - attempt to verify the checksum of the timestamp chunk\. Throws an error if - the *file* is not a valid PNG image\. - - - __::png::setTimestamp__ *file* *time* - - Writes a new timestamp to the *file*, either replacing the old timestamp, - or adding one just before the data chunks if there was no previous - timestamp\. *time* is the new time in the gmt epoch format\. Throws an error - if *file* is not a valid PNG image\. - - - __::png::getComments__ *file* - - Currently supports only uncompressed comments\. Does not attempt to verify - the checksums of the comment chunks\. Returns a list where each element is a - comment\. Each comment is itself a list\. The list for a plain text comment - consists of 2 elements: the human readable keyword, and the text data\. A - unicode \(international\) comment consists of 4 elements: the human readable - keyword, the language identifier, the translated keyword, and the unicode - text data\. Throws an error if *file* is not a valid PNG image\. - - - __::png::removeComments__ *file* - - Removes all comments from the PNG image in *file*\. Beware \- This uses - memory equal to the file size minus comments, to hold the intermediate - result\. Throws an error if *file* is not a valid PNG image\. - - - __::png::addComment__ *file* *keyword* *text* - - Adds a plain *text* comment to the PNG image in *file*, just before the - first data chunk\. Will throw an error if no data chunk is found\. *keyword* - has to be less than 80 characters long to conform to the PNG specification\. - - - __::png::addComment__ *file* *keyword* *lang* *keyword2* *text* - - Adds a unicode \(international\) comment to the PNG image in *file*, just - before the first data chunk\. Will throw an error if no data chunk is found\. - *keyword* has to be less than 80 characters long to conform to the PNG - specification\. *keyword2* is the translated *keyword*, in the language - specified by the language identifier *lang*\. - - - __::png::getPixelDimension__ *file* - - Returns a dictionary with keys __ppux__, __ppuy__ and __unit__ - if the information is present\. Otherwise, it returns the empty string\. - - The values of __ppux__ and __ppuy__ return the pixel per unit value - in X or Y direction\. - - The allowed values for key __unit__ are __meter__ and - __unknown__\. In the case of meter, the dpi value can be calculated by - multiplying with the conversion factor __0\.0254__\. - - - __::png::image__ *file* - - Given a PNG file returns the image in the list of scanlines format used by - Tk\_GetColor\. - - - __::png::write__ *file* *data* - - Takes a list of scanlines in the Tk\_GetColor format and writes the - represented image to *file*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *png* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[comment](\.\./\.\./\.\./\.\./index\.md\#comment), -[image](\.\./\.\./\.\./\.\./index\.md\#image), [png](\.\./\.\./\.\./\.\./index\.md\#png), -[timestamp](\.\./\.\./\.\./\.\./index\.md\#timestamp) - -# CATEGORY - -File formats - -# COPYRIGHT - -Copyright © 2004, Code: Aaron Faupell -Copyright © 2004, Doc: Andreas Kupries DELETED embedded/md/tcllib/files/modules/pop3/pop3.md Index: embedded/md/tcllib/files/modules/pop3/pop3.md ================================================================== --- embedded/md/tcllib/files/modules/pop3/pop3.md +++ embedded/md/tcllib/files/modules/pop3/pop3.md @@ -1,309 +0,0 @@ - -[//000000001]: # (pop3 \- Tcl POP3 Client Library) -[//000000002]: # (Generated from file 'pop3\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (pop3\(n\) 1\.9 tcllib "Tcl POP3 Client Library") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pop3 \- Tcl client for POP3 email protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TLS Security Considerations](#section2) - - - [API](#section3) - - - [Secure mail transfer](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require pop3 ?1\.9? - -[__::pop3::open__ ?__\-msex__ 0|1? ?__\-retr\-mode__ retr|list|slow? ?__\-socketcmd__ cmdprefix? ?__\-stls__ 0|1? ?__\-tls\-callback__ stls\-callback\-command? *host username password* ?*port*?](#1) -[__::pop3::config__ *chan*](#2) -[__::pop3::status__ *chan*](#3) -[__::pop3::last__ *chan*](#4) -[__::pop3::retrieve__ *chan startIndex* ?*endIndex*?](#5) -[__::pop3::delete__ *chan startIndex* ?*endIndex*?](#6) -[__::pop3::list__ *chan* ?*msg*?](#7) -[__::pop3::top__ *chan* *msg* *n*](#8) -[__::pop3::uidl__ *chan* ?*msg*?](#9) -[__::pop3::capa__ *chan*](#10) -[__::pop3::close__ *chan*](#11) - -# DESCRIPTION - -The __pop3__ package provides a simple Tcl\-only client library for the POP3 -email protocol as specified in [RFC -1939](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt)\. It works by opening the -standard POP3 socket on the server, transmitting the username and password, then -providing a Tcl API to access the POP3 protocol commands\. All server errors are -returned as Tcl errors \(thrown\) which must be caught with the Tcl __catch__ -command\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# API - - - __::pop3::open__ ?__\-msex__ 0|1? ?__\-retr\-mode__ retr|list|slow? ?__\-socketcmd__ cmdprefix? ?__\-stls__ 0|1? ?__\-tls\-callback__ stls\-callback\-command? *host username password* ?*port*? - - Open a socket connection to the server specified by *host*, transmit the - *username* and *password* as login information to the server\. The - default port number is __110__, which can be overridden using the - optional *port* argument\. The return value is a channel used by all of the - other ::pop3 functions\. - - The command recognizes three options - - * __\-msex__ boolean - - Setting this option tells the package that the server we are talking to - is an MS Exchange server \(which has some oddities we have to work - around\)\. The default is __False__\. - - * __\-retr\-mode__ retr|list|slow - - The retrieval mode determines how exactly messages are read from the - server\. The allowed values are __retr__, __list__ and - __slow__\. The default is __retr__\. See __::pop3::retrieve__ - for more information\. - - * __\-socketcmd__ cmdprefix - - This option allows the user to overide the use of the builtin - __[socket](\.\./\.\./\.\./\.\./index\.md\#socket)__ command with any - API\-compatible command\. The envisioned main use is the securing of the - new connection via SSL, through the specification of the command - __tls::socket__\. This command is specially recognized as well, - changing the default port of the connection to __995__\. - - * __\-stls__ boolean - - Setting this option tells the package to secure the connection using SSL - or TLS\. It performs STARTTLS as described in IETF RFC 2595, it first - opens a normal, unencrypted connection and then negotiates a SSLv3 or - TLSv1 connection\. If the connection cannot be secured, the connection - will be closed and an error will be returned - - * __\-tls\-callback__ stls\-callback\-command - - This option allows the user to overide the __tls::callback__ used - during the __\-stls__ SSL/TLS handshake\. See the TLS manual for - details on how to implement this callback\. - - - __::pop3::config__ *chan* - - Returns the configuration of the pop3 connection identified by the channel - handle *chan* as a serialized array\. - - - __::pop3::status__ *chan* - - Query the server for the status of the mail spool\. The status is returned as - a list containing two elements, the first is the number of email messages on - the server and the second is the size \(in octets, 8 bit blocks\) of the - entire mail spool\. - - - __::pop3::last__ *chan* - - Query the server for the last email message read from the spool\. This value - includes all messages read from all clients connecting to the login account\. - This command may not be supported by the email server, in which case the - server may return 0 or an error\. - - - __::pop3::retrieve__ *chan startIndex* ?*endIndex*? - - Retrieve a range of messages from the server\. If the *endIndex* is not - specified, only one message will be retrieved\. The return value is a list - containing each message as a separate element\. See the *startIndex* and - *endIndex* descriptions below\. - - The retrieval mode determines how exactly messages are read from the server\. - The mode __retr__ assumes that the RETR command delivers the size of the - message as part of the command status and uses this to read the message - efficiently\. In mode __list__ RETR does not deliver the size, but the - LIST command does and we use this to retrieve the message size before the - actual retrieval, which can then be done efficiently\. In the last mode, - __slow__, the system is unable to obtain the size of the message to - retrieve in any manner and falls back to reading the message from the server - line by line\. - - It should also be noted that the system checks upon the configured mode and - falls back to the slower modes if the above assumptions are not true\. - - - __::pop3::delete__ *chan startIndex* ?*endIndex*? - - Delete a range of messages from the server\. If the *endIndex* is not - specified, only one message will be deleted\. Note, the indices are not - reordered on the server, so if you delete message 1, then the first message - in the queue is message 2 \(message index 1 is no longer valid\)\. See the - *startIndex* and *endIndex* descriptions below\. - - * *startIndex* - - The *startIndex* may be an index of a specific message starting with - the index 1, or it have any of the following values: - - + __start__ - - This is a logical value for the first message in the spool, - equivalent to the value 1\. - - + __next__ - - The message immediately following the last message read, see - __::pop3::last__\. - - + __end__ - - The most recent message in the spool \(the end of the spool\)\. This is - useful to retrieve only the most recent message\. - - * *endIndex* - - The *endIndex* is an optional parameter and defaults to the value - "\-1", which indicates to only retrieve the one message specified by - *startIndex*\. If specified, it may be an index of a specific message - starting with the index "1", or it may have any of the following values: - - + __last__ - - The message is the last message read by a POP3 client, see - __::pop3::last__\. - - + __end__ - - The most recent message in the spool \(the end of the spool\)\. - - - __::pop3::list__ *chan* ?*msg*? - - Returns the scan listing of the mailbox\. If parameter *msg* is given, then - the listing only for that message is returned\. - - - __::pop3::top__ *chan* *msg* *n* - - Optional POP3 command, not all servers may support this\. __::pop3::top__ - retrieves headers of a message, specified by parameter *msg*, and number - of *n* lines from the message body\. - - - __::pop3::uidl__ *chan* ?*msg*? - - Optional POP3 command, not all servers may support this\. - __::pop3::uidl__ returns the uid listing of the mailbox\. If the - parameter *msg* is specified, then the listing only for that message is - returned\. - - - __::pop3::capa__ *chan* - - Optional POP3 command, not all servers may support this\. - __::pop3::capa__ returns a list of the capabilities of the server\. TOP, - SASL, UIDL, LOGIN\-DELAY and STLS are typical capabilities\. See IETF RFC - 2449\. - - - __::pop3::close__ *chan* - - Gracefully close the connect after sending a POP3 QUIT command down the - socket\. - -# Secure mail transfer - -A pop3 connection can be secured with SSL/TLS by requiring the package -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ and then using either the option -__\-socketcmd__ or the option __\-stls__ of the command -__pop3::open__\. The first method, option __\-socketcmd__, will force the -use of the __tls::socket__ command when opening the connection\. This is -suitable for POP3 servers which expect SSL connections only\. These will -generally be listening on port 995\. - - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create secured pop3 channel - pop3::open -socketcmd tls::socket \ - $thehost $theuser $thepassword - - ... - -The second method, option __\-stls__, will connect to the standard POP3 port -and then perform an STARTTLS handshake\. This will only work for POP3 servers -which have this capability\. The package will confirm that the server supports -STARTTLS and the handshake was performed correctly before proceeding with -authentication\. - - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create secured pop3 channel - pop3::open -stls 1 \ - $thehost $theuser $thepassword - - ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pop3* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[email](\.\./\.\./\.\./\.\./index\.md\#email), [mail](\.\./\.\./\.\./\.\./index\.md\#mail), -[pop](\.\./\.\./\.\./\.\./index\.md\#pop), [pop3](\.\./\.\./\.\./\.\./index\.md\#pop3), -[rfc 1939](\.\./\.\./\.\./\.\./index\.md\#rfc\_1939), -[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/pop3d/pop3d.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d.md ================================================================== --- embedded/md/tcllib/files/modules/pop3d/pop3d.md +++ embedded/md/tcllib/files/modules/pop3d/pop3d.md @@ -1,309 +0,0 @@ - -[//000000001]: # (pop3d \- Tcl POP3 Server Package) -[//000000002]: # (Generated from file 'pop3d\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2009 Andreas Kupries ) -[//000000004]: # (Copyright © 2005 Reinhard Max ) -[//000000005]: # (pop3d\(n\) 1\.1\.0 tcllib "Tcl POP3 Server Package") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pop3d \- Tcl POP3 server implementation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Options](#section2) - - - [Authentication](#section3) - - - [Mailboxes](#section4) - - - [Secure mail transfer](#section5) - - - [References](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require pop3d ?1\.1\.0? - -[__::pop3d::new__ ?*serverName*?](#1) -[__serverName__ *option* ?*arg arg \.\.\.*?](#2) -[*serverName* __up__](#3) -[*serverName* __down__](#4) -[*serverName* __destroy__ ?*mode*?](#5) -[*serverName* __configure__](#6) -[*serverName* __configure__ *\-option*](#7) -[*serverName* __configure__ *\-option value*\.\.\.](#8) -[*serverName* __cget__ *\-option*](#9) -[*serverName* __conn__ list](#10) -[*serverName* __conn__ state *id*](#11) -[*authCmd* __exists__ *name*](#12) -[*authCmd* __lookup__ *name*](#13) -[*storageCmd* __dele__ *mbox* *msgList*](#14) -[*storageCmd* __lock__ *mbox*](#15) -[*storageCmd* __unlock__ *mbox*](#16) -[*storageCmd* __size__ *mbox* ?*msgId*?](#17) -[*storageCmd* __stat__ *mbox*](#18) -[*storageCmd* __get__ *mbox* *msgId*](#19) - -# DESCRIPTION - - - __::pop3d::new__ ?*serverName*? - - This command creates a new server object with an associated global Tcl - command whose name is *serverName*\. - -The command __serverName__ may be used to invoke various operations on the -server\. It has the following general form: - - - __serverName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -A pop3 server can be started on any port the caller has permission for from the -operating system\. The default port will be 110, which is the port defined by the -standard specified in RFC 1939 -\([http://www\.rfc\-editor\.org/rfc/rfc1939\.txt](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt)\)\. -After creating, configuring and starting a the server object will listen for and -accept connections on that port and handle them according to the POP3 protocol\. - -*Note:* The server provided by this module will handle only the basic protocol -by itself\. For the higher levels of user authentication and handling of the -actual mailbox contents callbacks will be invoked\. - -The following commands are possible for server objects: - - - *serverName* __up__ - - After this call the server will listen for connections on its configured - port\. - - - *serverName* __down__ - - After this call the server will stop listening for connections\. This does - not affect existing connections\. - - - *serverName* __destroy__ ?*mode*? - - Destroys the server object\. Currently open connections are handled depending - on the chosen mode\. The provided *mode*s are: - - * __kill__ - - Destroys the server immediately, and forcefully closes all currently - open connections\. This is the default mode\. - - * __defer__ - - Stops the server from accepting new connections and will actually - destroy it only after the last of the currently open connections for the - server is closed\. - - - *serverName* __configure__ - - Returns a list containing all options and their current values in a format - suitable for use by the command __array set__\. The options themselves - are described in section [Options](#section2)\. - - - *serverName* __configure__ *\-option* - - Returns the current value of the specified option\. This is an alias for the - method __cget__\. The options themselves are described in section - [Options](#section2)\. - - - *serverName* __configure__ *\-option value*\.\.\. - - Sets the specified option to the provided value\. The options themselves are - described in section [Options](#section2)\. - - - *serverName* __cget__ *\-option* - - Returns the current value of the specified option\. The options themselves - are described in section [Options](#section2)\. - - - *serverName* __conn__ list - - Returns a list containing the ids of all connections currently open\. - - - *serverName* __conn__ state *id* - - Returns a list suitable for \[__array set__\] containing the state of the - connection referenced by *id*\. - -# Options - -The following options are available to pop3 server objects\. - - - __\-port__ *port* - - Defines the *port* to listen on for new connections\. Default is 110\. This - option is a bit special\. If *port* is set to "0" the server, or rather the - operating system, will select a free port on its own\. When querying - __\-port__ the id of this chosen port will be returned\. Changing the port - while the server is up will neither change the returned value, nor will it - change on which port the server is listening on\. Only after resetting the - server via a call to __down__ followed by a call to __up__ will the - new port take effect\. It is at that time that the value returned when - querying __\-port__ will change too\. - - - __\-auth__ *command* - - Defines a *command* prefix to call whenever the authentication of a user - is required\. If no such command is specified the server will reject all - users\. The interface which has to be provided by the command prefix is - described in section [Authentication](#section3)\. - - - __\-storage__ *command* - - Defines a *command* prefix to call whenever the handling of mailbox - contents is required\. If no such command is specified the server will claim - that all mailboxes are empty\. The interface which has to be provided by the - command prefix is described in section [Mailboxes](#section4)\. - - - __\-socket__ *command* - - Defines a *command* prefix to call for opening the listening socket\. This - can be used to make the pop3 server listen on a SSL socket as provided by - the __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package, see the command - __tls::socket__\. - -# Authentication - -Here we describe the interface which has to be provided by the authentication -callback so that pop3 servers following the interface of this module are able to -use it\. - - - *authCmd* __exists__ *name* - - This method is given a user*name* and has to return a boolean value - telling whether or not the specified user exists\. - - - *authCmd* __lookup__ *name* - - This method is given a user*name* and has to return a two\-element list - containing the password for this user and a storage reference, in this - order\. - - The storage reference is passed unchanged to the storage callback, see - sections [Options](#section2) and [Mailboxes](#section4) for - either the option defining it and or the interface to provide, respectively\. - -# Mailboxes - -Here we describe the interface which has to be provided by the storage callback -so that pop3 servers following the interface of this module are able to use it\. -The *mbox* argument is the storage reference as returned by the __lookup__ -method of the authentication command, see section -[Authentication](#section3)\. - - - *storageCmd* __dele__ *mbox* *msgList* - - Deletes the messages whose numeric ids are contained in the *msgList* from - the mailbox specified via *mbox*\. - - - *storageCmd* __lock__ *mbox* - - This method locks the specified mailbox for use by a single connection to - the server\. This is necessary to prevent havoc if several connections to the - same mailbox are open\. The complementary method is __unlock__\. The - command will return true if the lock could be set successfully or false if - not\. - - - *storageCmd* __unlock__ *mbox* - - This is the complementary method to __lock__, it revokes the lock on the - specified mailbox\. - - - *storageCmd* __size__ *mbox* ?*msgId*? - - Determines the size of the message specified through its id in *msgId*, in - bytes, and returns this number\. The command will return the size of the - whole maildrop if no message id was specified\. - - - *storageCmd* __stat__ *mbox* - - Determines the number of messages in the specified mailbox and returns this - number\. - - - *storageCmd* __get__ *mbox* *msgId* - - Returns a handle for the specified message\. This handle is a mime token - following the interface described in the documentation of package - __[mime](\.\./mime/mime\.md)__\. The pop3 server will use the - functionality of the mime token to send the mail to the requestor at the - other end of a pop3 connection\. - -# Secure mail transfer - -The option __\-socket__ \(see [Options](#section2)\) enables users of the -package to override how the server opens its listening socket\. The envisioned -main use is the specification of the __tls::socket__ command, see package -__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\. - - package require tls - tls::init \ - ... - - pop3d::new S -socket tls::socket - ... - -# References - - 1. [RFC 1939](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt) - - 1. [RFC 2449](http://www\.rfc\-editor\.org/rfc/rfc2449\.txt) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pop3d* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[network](\.\./\.\./\.\./\.\./index\.md\#network), -[pop3](\.\./\.\./\.\./\.\./index\.md\#pop3), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), [rfc -1939](\.\./\.\./\.\./\.\./index\.md\#rfc\_1939), -[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2002\-2009 Andreas Kupries -Copyright © 2005 Reinhard Max DELETED embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md ================================================================== --- embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md +++ embedded/md/tcllib/files/modules/pop3d/pop3d_dbox.md @@ -1,201 +0,0 @@ - -[//000000001]: # (pop3d::dbox \- Tcl POP3 Server Package) -[//000000002]: # (Generated from file 'pop3d\_dbox\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (pop3d::dbox\(n\) 1\.0\.2 tcllib "Tcl POP3 Server Package") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pop3d::dbox \- Simple mailbox database for pop3d - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require pop3d::dbox ?1\.0\.2? - -[__::pop3d::dbox::new__ ?*dbName*?](#1) -[__dbName__ *option* ?*arg arg \.\.\.*?](#2) -[*dbName* __destroy__](#3) -[*dbName* __base__ *base*](#4) -[*dbName* __add__ *mbox*](#5) -[*dbName* __remove__ *mbox*](#6) -[*dbName* __move__ *old new*](#7) -[*dbName* __list__](#8) -[*dbName* __exists__ *mbox*](#9) -[*dbName* __locked__ *mbox*](#10) -[*dbName* __lock__ *mbox*](#11) -[*dbName* __unlock__ *mbox*](#12) -[*dbName* __stat__ *mbox*](#13) -[*dbName* __size__ *mbox* ?*msgId*?](#14) -[*dbName* __dele__ *mbox msgList*](#15) -[*storageCmd* __get__ *mbox* *msgId*](#16) - -# DESCRIPTION - -The package __pop3d::dbox__ provides simple/basic mailbox management -facilities\. Each mailbox object manages a single base directory whose -subdirectories represent the managed mailboxes\. Mails in a mailbox are -represented by files in a mailbox directory, where each of these files contains -a single mail, both headers and body, in RFC 822 -\([http://www\.rfc\-editor\.org/rfc/rfc822\.txt](http://www\.rfc\-editor\.org/rfc/rfc822\.txt)\) -conformant format\. - -Any mailbox object following the interface described below can be used in -conjunction with the pop3 server core provided by the package -__[pop3d](pop3d\.md)__\. It is especially possible to directly use the -objects created by this package in the storage callback of pop3 servers -following the same interface as servers created by the package -__[pop3d](pop3d\.md)__\. - - - __::pop3d::dbox::new__ ?*dbName*? - - This command creates a new database object with an associated global Tcl - command whose name is *dbName*\. - -The command __dbName__ may be used to invoke various operations on the -database\. It has the following general form: - - - __dbName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -The following commands are possible for database objects: - - - *dbName* __destroy__ - - Destroys the mailbox database and all transient data\. The directory - associated with the object is not destroyed\. - - - *dbName* __base__ *base* - - Defines the base directory containing the mailboxes to manage\. If this - method is not called none of the following methods will work\. - - - *dbName* __add__ *mbox* - - Adds a mailbox of name *mbox* to the database\. The name must be a valid - path component\. - - - *dbName* __remove__ *mbox* - - Removes the mailbox specified through *mbox*, and the mails contained - therein, from the database\. This method will fail if the specified mailbox - is locked\. - - - *dbName* __move__ *old new* - - Changes the name of the mailbox *old* to *new*\. - - - *dbName* __list__ - - Returns a list containing the names of all mailboxes in the directory - associated with the database\. - - - *dbName* __exists__ *mbox* - - Returns true if the mailbox with name *mbox* exists in the database, or - false if not\. - - - *dbName* __locked__ *mbox* - - Checks if the mailbox specified through *mbox* is currently locked\. - - - *dbName* __lock__ *mbox* - - This method locks the specified mailbox for use by a single connection to - the server\. This is necessary to prevent havoc if several connections to the - same mailbox are open\. The complementary method is __unlock__\. The - command will return true if the lock could be set successfully or false if - not\. - - - *dbName* __unlock__ *mbox* - - This is the complementary method to __lock__, it revokes the lock on the - specified mailbox\. - - - *dbName* __stat__ *mbox* - - Determines the number of messages in the specified mailbox and returns this - number\. This method fails if the mailbox *mbox* is not locked\. - - - *dbName* __size__ *mbox* ?*msgId*? - - Determines the size of the message specified through its id in *msgId*, in - bytes, and returns this number\. The command will return the size of the - whole maildrop if no message id was specified\. If specified the *msgId* - has to be in the range "1 \.\.\. \[*dbName* __stat__\]" or this call will - fail\. If __stat__ was not called before this call, __size__ will - assume that there are zero messages in the mailbox\. - - - *dbName* __dele__ *mbox msgList* - - Deletes the messages whose numeric ids are contained in the *msgList* from - the mailbox specified via *mbox*\. The *msgList* must not be empty or - this call will fail\. The numeric ids in *msgList* have to be in the range - "1 \.\.\. \[*dbName* __stat__\]" or this call will fail\. If __stat__ - was not called before this call, __dele__ will assume that there are - zero messages in the mailbox\. - - - *storageCmd* __get__ *mbox* *msgId* - - Returns a handle for the specified message\. This handle is a mime token - following the interface described in the documentation of package - __[mime](\.\./mime/mime\.md)__\. The token is *read\-only*\. In other - words, the caller is allowed to do anything with the token except to modify - it\. The *msgId* has to be in the range "1 \.\.\. \[*dbName* __stat__\]" - or this call will fail\. If __stat__ was not called before this call, - __get__ will assume that there are zero messages in the mailbox\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pop3d* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[network](\.\./\.\./\.\./\.\./index\.md\#network), -[pop3](\.\./\.\./\.\./\.\./index\.md\#pop3), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), [rfc -822](\.\./\.\./\.\./\.\./index\.md\#rfc\_822) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2002 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md Index: embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md ================================================================== --- embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md +++ embedded/md/tcllib/files/modules/pop3d/pop3d_udb.md @@ -1,154 +0,0 @@ - -[//000000001]: # (pop3d::udb \- Tcl POP3 Server Package) -[//000000002]: # (Generated from file 'pop3d\_udb\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (pop3d::udb\(n\) 1\.0\.1 tcllib "Tcl POP3 Server Package") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pop3d::udb \- Simple user database for pop3d - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require pop3d::udb ?1\.0\.1? - -[__::pop3d::udb::new__ ?*dbName*?](#1) -[__dbName__ *option* ?*arg arg \.\.\.*?](#2) -[*dbName* __destroy__](#3) -[*dbName* __add__ *user pwd storage*](#4) -[*dbName* __remove__ *user*](#5) -[*dbName* __rename__ *user newName*](#6) -[*dbName* __lookup__ *user*](#7) -[*dbName* __exists__ *user*](#8) -[*dbName* __who__](#9) -[*dbName* __save__ ?*file*?](#10) -[*dbName* __read__ *file*](#11) - -# DESCRIPTION - -The package __pop3d::udb__ provides simple in memory databases which can be -used in conjunction with the pop3 server core provided by the package -__[pop3d](pop3d\.md)__\. The databases will use the names of users as keys -and associates passwords and storage references with them\. - -Objects created by this package can be directly used in the authentication -callback of pop3 servers following the same interface as servers created by the -package __[pop3d](pop3d\.md)__\. - - - __::pop3d::udb::new__ ?*dbName*? - - This command creates a new database object with an associated global Tcl - command whose name is *dbName*\. - -The command __dbName__ may be used to invoke various operations on the -database\. It has the following general form: - - - __dbName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -The following commands are possible for database objects: - - - *dbName* __destroy__ - - Destroys the database object\. - - - *dbName* __add__ *user pwd storage* - - Add a new user or changes the data of an existing user\. Stores *password* - and *storage* reference for the given *user*\. - - - *dbName* __remove__ *user* - - Removes the specified *user* from the database\. - - - *dbName* __rename__ *user newName* - - Changes the name of the specified *user* to *newName*\. - - - *dbName* __lookup__ *user* - - Searches the database for the specified *user* and returns a two\-element - list containing the associated password and storage reference, in this - order\. Throws an error if the user could not be found\. This is the interface - as expected by the authentication callback of package - __[pop3d](pop3d\.md)__\. - - - *dbName* __exists__ *user* - - Returns true if the specified *user* is known to the database, else false\. - - - *dbName* __who__ - - Returns a list of users known to the database\. - - - *dbName* __save__ ?*file*? - - Saves the contents of the database into the given *file*\. If the file is - not specified the system will use the path last used in a call to *dbName* - __read__\. The generated file can be read by the __read__ method\. - - - *dbName* __read__ *file* - - Reads the specified *file* and adds the contained user definitions to the - database\. As the file is actually - __[source](\.\./\.\./\.\./\.\./index\.md\#source)__'d a safe interpreter is - employed to safeguard against malicious code\. This interpreter knows the - __add__ command for adding users and their associated data to this - database\. This command has the same argument signature as the method - __add__\. The path of the *file* is remembered internally so that it - can be used in the next call of *dbName* __save__ without an argument\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pop3d* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[network](\.\./\.\./\.\./\.\./index\.md\#network), -[pop3](\.\./\.\./\.\./\.\./index\.md\#pop3), -[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2002 Andreas Kupries DELETED embedded/md/tcllib/files/modules/practcl/practcl.md Index: embedded/md/tcllib/files/modules/practcl/practcl.md ================================================================== --- embedded/md/tcllib/files/modules/practcl/practcl.md +++ embedded/md/tcllib/files/modules/practcl/practcl.md @@ -1,1744 +0,0 @@ - -[//000000001]: # (practcl \- The The Proper Rational API for C to Tool Command Language Module) -[//000000002]: # (Generated from file 'practcl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2016\-2018 Sean Woods ) -[//000000004]: # (practcl\(n\) 0\.16\.4 tcllib "The The Proper Rational API for C to Tool Command Language Module") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -practcl \- The Practcl Module - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Classes](#section3) - - - [Class practcl::doctool](#subsection1) - - - [Class practcl::metaclass](#subsection2) - - - [Class practcl::toolset](#subsection3) - - - [Class practcl::toolset\.gcc](#subsection4) - - - [Class practcl::toolset\.msvc](#subsection5) - - - [Class practcl::make\_obj](#subsection6) - - - [Class practcl::object](#subsection7) - - - [Class practcl::dynamic](#subsection8) - - - [Class practcl::product](#subsection9) - - - [Class practcl::product\.cheader](#subsection10) - - - [Class practcl::product\.csource](#subsection11) - - - [Class practcl::product\.clibrary](#subsection12) - - - [Class practcl::product\.dynamic](#subsection13) - - - [Class practcl::product\.critcl](#subsection14) - - - [Class practcl::module](#subsection15) - - - [Class practcl::project](#subsection16) - - - [Class practcl::library](#subsection17) - - - [Class practcl::tclkit](#subsection18) - - - [Class practcl::distribution](#subsection19) - - - [Class practcl::distribution\.snapshot](#subsection20) - - - [Class practcl::distribution\.fossil](#subsection21) - - - [Class practcl::distribution\.git](#subsection22) - - - [Class practcl::subproject](#subsection23) - - - [Class practcl::subproject\.source](#subsection24) - - - [Class practcl::subproject\.teapot](#subsection25) - - - [Class practcl::subproject\.kettle](#subsection26) - - - [Class practcl::subproject\.critcl](#subsection27) - - - [Class practcl::subproject\.sak](#subsection28) - - - [Class practcl::subproject\.practcl](#subsection29) - - - [Class practcl::subproject\.binary](#subsection30) - - - [Class practcl::subproject\.tea](#subsection31) - - - [Class practcl::subproject\.library](#subsection32) - - - [Class practcl::subproject\.external](#subsection33) - - - [Class practcl::subproject\.core](#subsection34) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require TclOO 1\.0 - -[proc __practcl::cat__ *fname*](#1) -[proc __practcl::docstrip__ *text*](#2) -[proc __putb__ ?*map*? *text*](#3) -[proc __[Proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *arglist* *body*](#4) -[proc __noop__ ?*args*?](#5) -[proc __practcl::debug__ ?*args*?](#6) -[proc __practcl::doexec__ ?*args*?](#7) -[proc __practcl::doexec\_in__ *path* ?*args*?](#8) -[proc __practcl::dotclexec__ ?*args*?](#9) -[proc __practcl::domake__ *path* ?*args*?](#10) -[proc __practcl::domake\.tcl__ *path* ?*args*?](#11) -[proc __practcl::fossil__ *path* ?*args*?](#12) -[proc __practcl::fossil\_status__ *dir*](#13) -[proc __practcl::os__](#14) -[proc __practcl::mkzip__ *exename* *barekit* *vfspath*](#15) -[proc __practcl::sort\_dict__ *list*](#16) -[proc __practcl::local\_os__](#17) -[proc __practcl::config\.tcl__ *path*](#18) -[proc __practcl::read\_configuration__ *path*](#19) -[proc __practcl::tcllib\_require__ *pkg* ?*args*?](#20) -[proc __practcl::platform::tcl\_core\_options__ *os*](#21) -[proc __practcl::platform::tk\_core\_options__ *os*](#22) -[proc __practcl::read\_rc\_file__ *filename* ?*localdat* ____?](#23) -[proc __practcl::read\_sh\_subst__ *line* *info*](#24) -[proc __practcl::read\_sh\_file__ *filename* ?*localdat* ____?](#25) -[proc __practcl::read\_Config\.sh__ *filename*](#26) -[proc __practcl::read\_Makefile__ *filename*](#27) -[proc __practcl::cputs__ *varname* ?*args*?](#28) -[proc __practcl::tcl\_to\_c__ *body*](#29) -[proc __practcl::\_tagblock__ *text* ?*style* __tcl__? ?*note* ____?](#30) -[proc __practcl::de\_shell__ *data*](#31) -[proc __practcl::grep__ *pattern* ?*files* ____?](#32) -[proc __practcl::file\_lexnormalize__ *sp*](#33) -[proc __practcl::file\_relative__ *base* *dst*](#34) -[proc __practcl::findByPattern__ *basedir* *patterns*](#35) -[proc __practcl::log__ *fname* *comment*](#36) -[proc __practcl::\_pkgindex\_simpleIndex__ *path*](#37) -[proc __practcl::\_pkgindex\_directory__ *path*](#38) -[proc __practcl::\_pkgindex\_path\_subdir__ *path*](#39) -[proc __practcl::pkgindex\_path__ ?*args*?](#40) -[proc __practcl::installDir__ *d1* *d2*](#41) -[proc __practcl::copyDir__ *d1* *d2* ?*toplevel* __1__?](#42) -[proc __practcl::buildModule__ *modpath*](#43) -[proc __practcl::installModule__ *modpath* *DEST*](#44) -[proc __practcl::trigger__ ?*args*?](#45) -[proc __practcl::depends__ ?*args*?](#46) -[proc __practcl::target__ *name* *info* ?*action* ____?](#47) -[method __constructor__](#48) -[method __argspec__ *argspec*](#49) -[method __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *block*](#50) -[method __keyword\.Annotation__ *resultvar* *commentblock* *type* *name* *body*](#51) -[method __keyword\.Class__ *resultvar* *commentblock* *name* *body*](#52) -[method __keyword\.class__ *resultvar* *commentblock* *name* *body*](#53) -[method __keyword\.Class\_Method__ *resultvar* *commentblock* *name* ?*args*?](#54) -[method __keyword\.method__ *resultvar* *commentblock* *name* ?*args*?](#55) -[method __keyword\.proc__ *commentblock* *name* *argspec*](#56) -[method __reset__](#57) -[method __Main__](#58) -[method __section\.method__ *keyword* *method* *minfo*](#59) -[method __section\.annotation__ *type* *name* *iinfo*](#60) -[method __section\.class__ *class\_name* *class\_info*](#61) -[method __section\.command__ *procinfo*](#62) -[method __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ ?__header *value*__? ?__footer *value*__? ?__authors *list*__?](#63) -[method __scan\_text__ *text*](#64) -[method __scan\_file__ *filename*](#65) -[method __\_MorphPatterns__](#66) -[method __[define](\.\./\.\./\.\./\.\./index\.md\#define)__ *submethod* ?*args*?](#67) -[method __graft__ ?*args*?](#68) -[method __initialize__](#69) -[method __link__ *command* ?*args*?](#70) -[method __morph__ *classname*](#71) -[method __script__ *script*](#72) -[method __select__](#73) -[method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename*](#74) -[classmethod __select__ *object*](#75) -[method __config\.sh__](#76) -[method __BuildDir__ *PWD*](#77) -[method __MakeDir__ *srcdir*](#78) -[method __read\_configuration__](#79) -[method __build\-cflags__ *PROJECT* *DEFS* *namevar* *versionvar* *defsvar*](#80) -[method __critcl__ ?*args*?](#81) -[method __Autoconf__](#82) -[method __BuildDir__ *PWD*](#83) -[method __ConfigureOpts__](#84) -[method __MakeDir__ *srcdir*](#85) -[method __make \{\} autodetect__](#86) -[method __make \{\} clean__](#87) -[method __make \{\} compile__](#88) -[method __make \{\} install__ *DEST*](#89) -[method __build\-compile\-sources__ *PROJECT* *COMPILE* *CPPCOMPILE* *INCLUDES*](#90) -[method __build\-Makefile__ *path* *PROJECT*](#91) -[method __build\-library__ *outfile* *PROJECT*](#92) -[method __build\-tclsh__ *outfile* *PROJECT* ?*path* __auto__?](#93) -[method __BuildDir__ *PWD*](#94) -[method __make \{\} autodetect__](#95) -[method __make \{\} clean__](#96) -[method __make \{\} compile__](#97) -[method __make \{\} install__ *DEST*](#98) -[method __MakeDir__ *srcdir*](#99) -[method __NmakeOpts__](#100) -[method __constructor__ *module\_object* *name* *info* ?*action\_body* ____?](#101) -[method __[do](\.\./\.\./\.\./\.\./index\.md\#do)__](#102) -[method __check__](#103) -[method __output__](#104) -[method __reset__](#105) -[method __triggers__](#106) -[method __constructor__ *parent* ?*args*?](#107) -[method __child__ *method*](#108) -[method __go__](#109) -[method __cstructure__ *name* *definition* ?*argdat* ____?](#110) -[method __include__ *header*](#111) -[method __include\_dir__ ?*args*?](#112) -[method __include\_directory__ ?*args*?](#113) -[method __c\_header__ *body*](#114) -[method __c\_code__ *body*](#115) -[method __c\_function__ *header* *body* ?*info* ____?](#116) -[method __c\_tcloomethod__ *name* *body* ?*arginfo* ____?](#117) -[method __cmethod__ *name* *body* ?*arginfo* ____?](#118) -[method __c\_tclproc\_nspace__ *nspace*](#119) -[method __c\_tclcmd__ *name* *body* ?*arginfo* ____?](#120) -[method __c\_tclproc\_raw__ *name* *body* ?*arginfo* ____?](#121) -[method __tcltype__ *name* *argdat*](#122) -[method __project\-compile\-products__](#123) -[method __implement__ *path*](#124) -[method __initialize__](#125) -[method __linktype__](#126) -[method __generate\-cfile\-constant__](#127) -[method __generate\-cfile\-header__](#128) -[method __generate\-cfile\-tclapi__](#129) -[method __generate\-loader\-module__](#130) -[method __Collate\_Source__ *CWD*](#131) -[method __select__](#132) -[classmethod __select__ *object*](#133) -[method __code__ *section* *body*](#134) -[method __Collate\_Source__ *CWD*](#135) -[method __project\-compile\-products__](#136) -[method __generate\-debug__ ?*spaces* ____?](#137) -[method __generate\-cfile\-constant__](#138) -[method __generate\-cfile\-public\-structure__](#139) -[method __generate\-cfile\-header__](#140) -[method __generate\-cfile\-global__](#141) -[method __generate\-cfile\-private\-typedef__](#142) -[method __generate\-cfile\-private\-structure__](#143) -[method __generate\-cfile\-functions__](#144) -[method __generate\-cfile\-tclapi__](#145) -[method __generate\-hfile\-public\-define__](#146) -[method __generate\-hfile\-public\-macro__](#147) -[method __generate\-hfile\-public\-typedef__](#148) -[method __generate\-hfile\-public\-structure__](#149) -[method __generate\-hfile\-public\-headers__](#150) -[method __generate\-hfile\-public\-function__](#151) -[method __generate\-hfile\-public\-includes__](#152) -[method __generate\-hfile\-public\-verbatim__](#153) -[method __generate\-loader\-external__](#154) -[method __generate\-loader\-module__](#155) -[method __generate\-stub\-function__](#156) -[method __IncludeAdd__ *headervar* ?*args*?](#157) -[method __generate\-tcl\-loader__](#158) -[method __generate\-tcl\-pre__](#159) -[method __generate\-tcl\-post__](#160) -[method __linktype__](#161) -[method __Ofile__ *filename*](#162) -[method __project\-static\-packages__](#163) -[method __toolset\-include\-directory__](#164) -[method __target__ *method* ?*args*?](#165) -[method __project\-compile\-products__](#166) -[method __generate\-loader\-module__](#167) -[method __project\-compile\-products__](#168) -[method __linker\-products__ *configdict*](#169) -[method __initialize__](#170) -[variable __make\_object__](#171) -[method __\_MorphPatterns__](#172) -[method __add__ ?*args*?](#173) -[method __install\-headers__ ?*args*?](#174) -[method __make \{\} \_preamble__](#175) -[method __make \{\} pkginfo__](#176) -[method __make \{\} objects__](#177) -[method __make \{\} object__ *name*](#178) -[method __make \{\} reset__](#179) -[method __make \{\} trigger__ ?*args*?](#180) -[method __make \{\} depends__ ?*args*?](#181) -[method __make \{\} filename__ *name*](#182) -[method __make \{\} target__ *name* *Info* *body*](#183) -[method __make \{\} todo__](#184) -[method __make \{\} do__](#185) -[method __child__ *which*](#186) -[method __generate\-c__](#187) -[method __generate\-h__](#188) -[method __generate\-loader__](#189) -[method __initialize__](#190) -[method __implement__ *path*](#191) -[method __linktype__](#192) -[method __\_MorphPatterns__](#193) -[method __constructor__ ?*args*?](#194) -[method __add\_object__ *object*](#195) -[method __add\_project__ *pkg* *info* ?*oodefine* ____?](#196) -[method __add\_tool__ *pkg* *info* ?*oodefine* ____?](#197) -[method __build\-tclcore__](#198) -[method __child__ *which*](#199) -[method __linktype__](#200) -[method __project__ *pkg* ?*args*?](#201) -[method __tclcore__](#202) -[method __tkcore__](#203) -[method __[tool](\.\./tool/tool\.md)__ *pkg* ?*args*?](#204) -[method __clean__ *PATH*](#205) -[method __project\-compile\-products__](#206) -[method __go__](#207) -[method __generate\-decls__ *pkgname* *path*](#208) -[method __implement__ *path*](#209) -[method __generate\-make__ *path*](#210) -[method __linktype__](#211) -[method __package\-ifneeded__ ?*args*?](#212) -[method __shared\_library__ ?*filename* ____?](#213) -[method __static\_library__ ?*filename* ____?](#214) -[method __build\-tclkit\_main__ *PROJECT* *PKG\_OBJS*](#215) -[method __Collate\_Source__ *CWD*](#216) -[method __wrap__ *PWD* *exename* *vfspath* ?*args*?](#217) -[classmethod __Sandbox__ *object*](#218) -[classmethod __select__ *object*](#219) -[classmethod __claim\_option__](#220) -[classmethod __claim\_object__ *object*](#221) -[classmethod __claim\_path__ *path*](#222) -[method __scm\_info__](#223) -[method __DistroMixIn__](#224) -[method __Sandbox__](#225) -[method __SrcDir__](#226) -[method __ScmTag__](#227) -[method __ScmClone__](#228) -[method __ScmUnpack__](#229) -[method __ScmUpdate__](#230) -[method __Unpack__](#231) -[classmethod __claim\_object__ *object*](#232) -[classmethod __claim\_option__](#233) -[classmethod __claim\_path__ *path*](#234) -[method __ScmUnpack__](#235) -[classmethod __claim\_object__ *obj*](#236) -[classmethod __claim\_option__](#237) -[classmethod __claim\_path__ *path*](#238) -[method __scm\_info__](#239) -[method __ScmClone__](#240) -[method __ScmTag__](#241) -[method __ScmUnpack__](#242) -[method __ScmUpdate__](#243) -[classmethod __claim\_object__ *obj*](#244) -[classmethod __claim\_option__](#245) -[classmethod __claim\_path__ *path*](#246) -[method __ScmTag__](#247) -[method __ScmUnpack__](#248) -[method __ScmUpdate__](#249) -[method __\_MorphPatterns__](#250) -[method __BuildDir__ *PWD*](#251) -[method __child__ *which*](#252) -[method __compile__](#253) -[method __go__](#254) -[method __install__ ?*args*?](#255) -[method __linktype__](#256) -[method __linker\-products__ *configdict*](#257) -[method __linker\-external__ *configdict*](#258) -[method __linker\-extra__ *configdict*](#259) -[method __env\-bootstrap__](#260) -[method __env\-exec__](#261) -[method __env\-install__](#262) -[method __env\-load__](#263) -[method __env\-present__](#264) -[method __sources__](#265) -[method __[update](\.\./\.\./\.\./\.\./index\.md\#update)__](#266) -[method __unpack__](#267) -[method __env\-bootstrap__](#268) -[method __env\-present__](#269) -[method __linktype__](#270) -[method __env\-bootstrap__](#271) -[method __env\-install__](#272) -[method __env\-present__](#273) -[method __install__ *DEST*](#274) -[method __kettle__ *path* ?*args*?](#275) -[method __install__ *DEST*](#276) -[method __install__ *DEST*](#277) -[method __env\-bootstrap__](#278) -[method __env\-install__](#279) -[method __env\-present__](#280) -[method __install__ *DEST*](#281) -[method __install\-module__ *DEST* ?*args*?](#282) -[method __env\-bootstrap__](#283) -[method __env\-install__](#284) -[method __install__ *DEST*](#285) -[method __install\-module__ *DEST* ?*args*?](#286) -[method __clean__](#287) -[method __env\-install__](#288) -[method __project\-compile\-products__](#289) -[method __ComputeInstall__](#290) -[method __go__](#291) -[method __linker\-products__ *configdict*](#292) -[method __project\-static\-packages__](#293) -[method __BuildDir__ *PWD*](#294) -[method __compile__](#295) -[method __Configure__](#296) -[method __install__ *DEST*](#297) -[method __install__ *DEST*](#298) -[method __install__ *DEST*](#299) -[method __env\-bootstrap__](#300) -[method __env\-present__](#301) -[method __env\-install__](#302) -[method __go__](#303) -[method __linktype__](#304) - -# DESCRIPTION - -The Practcl module is a tool for integrating large modules for C API Tcl code -that requires custom Tcl types and TclOO objects\. - -The concept with Practcl is that is a single file package that can assist any -tcl based project with distribution, compilation, linking, VFS preparation, -executable assembly, and installation\. Practcl also allows one project to invoke -the build system from another project, allowing complex projects such as a -statically linked basekit to be assembled with relative ease\. - -Practcl ships as a single file, and aside from a Tcl 8\.6 interpreter, has no -external dependencies\. - -Making a practcl project - -# Commands - - - proc __practcl::cat__ *fname* - - Concatenate a file - - - proc __practcl::docstrip__ *text* - - Strip the global comments from tcl code\. Used to prevent the documentation - markup comments from clogging up files intended for distribution in machine - readable format\. - - - proc __putb__ ?*map*? *text* - - Append a line of text to a variable\. Optionally apply a string mapping\. - - - proc __[Proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *arglist* *body* - - Generate a proc if no command already exists by that name - - - proc __noop__ ?*args*? - - A command to do nothing\. A handy way of negating an instruction without - having to comment it completely out\. It's also a handy attachment point for - an object to be named later - - - proc __practcl::debug__ ?*args*? - - - proc __practcl::doexec__ ?*args*? - - Drop in a static copy of Tcl - - - proc __practcl::doexec\_in__ *path* ?*args*? - - - proc __practcl::dotclexec__ ?*args*? - - - proc __practcl::domake__ *path* ?*args*? - - - proc __practcl::domake\.tcl__ *path* ?*args*? - - - proc __practcl::fossil__ *path* ?*args*? - - - proc __practcl::fossil\_status__ *dir* - - - proc __practcl::os__ - - - proc __practcl::mkzip__ *exename* *barekit* *vfspath* - - Build a zipfile\. On tcl8\.6 this invokes the native Zip implementation on - older interpreters this invokes zip via exec - - - proc __practcl::sort\_dict__ *list* - - Dictionary sort a key/value list\. Needed because pre tcl8\.6 does not have - *lsort \-stride 2* - - - proc __practcl::local\_os__ - - Returns a dictionary describing the local operating system\. Fields return - include: - - * download \- Filesystem path where fossil repositories and source tarballs - are downloaded for the current user - - * EXEEXT \- The extension to give to executables\. \(i\.e\. \.exe on windows\) - - * fossil\_mirror \- A URI for a local network web server who acts as a - fossil repository mirror - - * local\_install \- Filesystem path where packages for local consumption by - the current user are installed - - * prefix \- The prefix as given to the Tcl core/TEA for installation to - local\_install in \./configure - - * sandbox \- The file location where this project unpacks external projects - - * TEACUP\_PROFILE \- The ActiveState/Teacup canonical name for this platform - \(i\.e\. win32\-ix86 macosx10\.5\-i386\-x86\_84\) - - * TEACUP\_OS \- The local operating system \(windows, macosx, openbsd, etc\)\. - Gives the same answer as tcl\.m4, except that macosx is given as macosx - instead of Darwin\. - - * TEA\_PLATFORM \- The platform returned by uname \-s\-uname \-r \(on Unix\), or - "windows" on Windows - - * TEACUP\_ARCH \- The processor architecture for the local os \(i\.e\. ix86, - x86\_64\) - - * TEACUP\_ARCH \- The processor architecture for the local os \(i\.e\. ix86, - x86\_64\) - - * teapot \- Filesystem path where teapot package files are downloaded for - the current user - - * userhome \- File path to store localized preferences, cache download - files, etc for the current user - - This command uses a combination of local checks with Exec, any tclConfig\.sh - file that is resident, autoconf data where already computed, and data - gleaned from a file named practcl\.rc in userhome\. The location for userhome - varies by platform and operating system: - - * Windows: ::env\(LOCALAPPDATA\)/Tcl - - * Macos: ~/Library/Application Support/Tcl - - * Other: ~/tcl - - - proc __practcl::config\.tcl__ *path* - - A transparent call to ::practcl::read\_configuration to preserve backward - compadibility with older copies of Practcl - - - proc __practcl::read\_configuration__ *path* - - Detect local platform\. This command looks for data gleaned by autoconf or - autosetup in the path specified, or perform its own logic tests if neither - has been run\. A file named config\.site present in the location indicates - that this project is cross compiling, and the data stored in that file is - used for the compiler and linker\. - - This command looks for information from the following files, in the - following order: - - * config\.tcl \- A file generated by autoconf/configure in newer editions of - TEA, encoded as a Tcl script\. - - * config\.site \- A file containing cross compiler information, encoded as a - SH script - - * ::env\(VisualStudioVersion\) \- On Windows, and environmental value that - indicates MS Visual Studio is installed - - This command returns a dictionary containing all of the data cleaned from - the sources above\. In the absence of any guidance this command returns the - same output as ::practcl::local\_os\. In this mode, if the environmental - variable VisualStudioVersion exists, this command will provide a template of - fields that are appropriate for compiling on Windows under Microsoft Visual - Studio\. The USEMSVC flag in the dictionary is a boolean flag to indicate if - this is indeed the case\. - - - proc __practcl::tcllib\_require__ *pkg* ?*args*? - - Try to load a package, and failing that retrieve tcllib - - - proc __practcl::platform::tcl\_core\_options__ *os* - - Return the string to pass to \./configure to compile the Tcl core for the - given OS\. - - * windows: \-\-with\-tzdata \-\-with\-encoding utf\-8 - - * macosx: \-\-enable\-corefoundation=yes \-\-enable\-framework=no \-\-with\-tzdata - \-\-with\-encoding utf\-8 - - * other: \-\-with\-tzdata \-\-with\-encoding utf\-8 - - - proc __practcl::platform::tk\_core\_options__ *os* - - - proc __practcl::read\_rc\_file__ *filename* ?*localdat* ____? - - Read a stylized key/value list stored in a file - - - proc __practcl::read\_sh\_subst__ *line* *info* - - Converts a XXX\.sh file into a series of Tcl variables - - - proc __practcl::read\_sh\_file__ *filename* ?*localdat* ____? - - - proc __practcl::read\_Config\.sh__ *filename* - - A simpler form of read\_sh\_file tailored to pulling data from - \(tcl|tk\)Config\.sh - - - proc __practcl::read\_Makefile__ *filename* - - A simpler form of read\_sh\_file tailored to pulling data from a Makefile - - - proc __practcl::cputs__ *varname* ?*args*? - - Append arguments to a buffer The command works like puts in that each call - will also insert a line feed\. Unlike puts, blank links in the interstitial - are suppressed - - - proc __practcl::tcl\_to\_c__ *body* - - - proc __practcl::\_tagblock__ *text* ?*style* __tcl__? ?*note* ____? - - - proc __practcl::de\_shell__ *data* - - - proc __practcl::grep__ *pattern* ?*files* ____? - - Search for the pattern *pattern* amongst $files - - - proc __practcl::file\_lexnormalize__ *sp* - - - proc __practcl::file\_relative__ *base* *dst* - - Calculate a relative path between base and dst - - Example: - - ::practcl::file_relative ~/build/tcl/unix ~/build/tcl/library - > ../library - - - proc __practcl::findByPattern__ *basedir* *patterns* - - - proc __practcl::log__ *fname* *comment* - - Record an event in the practcl log - - - proc __practcl::\_pkgindex\_simpleIndex__ *path* - - - proc __practcl::\_pkgindex\_directory__ *path* - - Return true if the pkgindex file contains any statement other than "package - ifneeded" and/or if any package ifneeded loads a DLL - - - proc __practcl::\_pkgindex\_path\_subdir__ *path* - - Helper function for ::practcl::pkgindex\_path - - - proc __practcl::pkgindex\_path__ ?*args*? - - Index all paths given as though they will end up in the same virtual file - system - - - proc __practcl::installDir__ *d1* *d2* - - Delete the contents of *d2*, and then recusively Ccopy the contents of - *d1* to *d2*\. - - - proc __practcl::copyDir__ *d1* *d2* ?*toplevel* __1__? - - Recursively copy the contents of *d1* to *d2* - - - proc __practcl::buildModule__ *modpath* - - - proc __practcl::installModule__ *modpath* *DEST* - - Install a module from MODPATH to the directory specified\. *dpath* is - assumed to be the fully qualified path where module is to be placed\. Any - existing files will be deleted at that path\. If the path is symlink the - process will return with no error and no action\. If the module has contents - in the build/ directory that are newer than the \.tcl files in the module - source directory, and a build/build\.tcl file exists, the build/build\.tcl - file is run\. If the source directory includes a file named index\.tcl, the - directory is assumed to be in the tao style of modules, and the entire - directory \(and all subdirectories\) are copied verbatim\. If no index\.tcl file - is present, all \.tcl files are copied from the module source directory, and - a pkgIndex\.tcl file is generated if non yet exists\. I a folder named htdocs - exists in the source directory, that directory is copied verbatim to the - destination\. - - - proc __practcl::trigger__ ?*args*? - - Trigger build targets, and recompute dependencies - - Internals: - - ::practcl::LOCAL make trigger {*}$args - foreach {name obj} [::practcl::LOCAL make objects] { - set ::make($name) [$obj do] - } - - - proc __practcl::depends__ ?*args*? - - Calculate if a dependency for any of the arguments needs to be fulfilled or - rebuilt\. - - Internals: - - ::practcl::LOCAL make depends {*}$args - - - proc __practcl::target__ *name* *info* ?*action* ____? - - Declare a build product\. This proc is just a shorthand for - *::practcl::LOCAL make task $name $info $action* - - Registering a build product with this command will create an entry in the - global array, and populate a value in the global array\. - - Internals: - - set obj [::practcl::LOCAL make task $name $info $action] - set ::make($name) 0 - set filename [$obj define get filename] - if {$filename ne {}} { - set ::target($name) $filename - } - -# Classes - -## Class practcl::doctool - - { set authors { - {John Doe} {jdoe@illustrious.edu} - {Tom RichardHarry} {tomdickharry@illustrius.edu} - } - # Create the object - ::practcl::doctool create AutoDoc - set fout [open [file join $moddir module.tcl] w] - foreach file [glob [file join $srcdir *.tcl]] { - set content [::practcl::cat [file join $srcdir $file]] - # Scan the file - AutoDoc scan_text $content - # Strip the comments from the distribution - puts $fout [::practcl::docstrip $content] - } - # Write out the manual page - set manout [open [file join $moddir module.man] w] - dict set args header [string map $modmap [::practcl::cat [file join $srcdir manual.txt]]] - dict set args footer [string map $modmap [::practcl::cat [file join $srcdir footer.txt]]] - dict set args authors $authors - puts $manout [AutoDoc manpage {*}$args] - close $manout - - - } - -Tool for build scripts to dynamically generate manual files from comments in -source code files - -__Methods__ - - - method __constructor__ - - - method __argspec__ *argspec* - - Process an argument list into an informational dict\. This method also - understands non\-positional arguments expressed in the notation of Tip 471 - [https://core\.tcl\-lang\.org/tips/doc/trunk/tip/479\.md](https://core\.tcl\-lang\.org/tips/doc/trunk/tip/479\.md)\. - - The output will be a dictionary of all of the fields and whether the fields - are __positional__, __mandatory__, and whether they have a - __default__ value\. - - Example: - - my argspec {a b {c 10}} - - > a {positional 1 mandatory 1} b {positional 1 mandatory 1} c {positional 1 mandatory 0 default 10} - - - method __[comment](\.\./\.\./\.\./\.\./index\.md\#comment)__ *block* - - Convert a block of comments into an informational dictionary\. If lines in - the comment start with a single word ending in a colon, all subsequent lines - are appended to a dictionary field of that name\. If no fields are given, all - of the text is appended to the __description__ field\. - - Example: - - my comment {Does something cool} - > description {Does something cool} - - my comment { - title : Something really cool - author : Sean Woods - author : John Doe - description : - This does something really cool! - } - > description {This does something really cool!} - title {Something really cool} - author {Sean Woods - John Doe} - - - method __keyword\.Annotation__ *resultvar* *commentblock* *type* *name* *body* - - - method __keyword\.Class__ *resultvar* *commentblock* *name* *body* - - Process an oo::objdefine call that modifies the class object itself - - - method __keyword\.class__ *resultvar* *commentblock* *name* *body* - - Process an oo::define, clay::define, etc statement\. - - - method __keyword\.Class\_Method__ *resultvar* *commentblock* *name* ?*args*? - - Process a statement for a clay style class method - - - method __keyword\.method__ *resultvar* *commentblock* *name* ?*args*? - - Process a statement for a tcloo style object method - - - method __keyword\.proc__ *commentblock* *name* *argspec* - - Process a proc statement - - - method __reset__ - - Reset the state of the object and its embedded coroutine - - - method __Main__ - - Main body of the embedded coroutine for the object - - - method __section\.method__ *keyword* *method* *minfo* - - Generate the manual page text for a method or proc - - - method __section\.annotation__ *type* *name* *iinfo* - - - method __section\.class__ *class\_name* *class\_info* - - Generate the manual page text for a class - - - method __section\.command__ *procinfo* - - Generate the manual page text for the commands section - - - method __[manpage](\.\./\.\./\.\./\.\./index\.md\#manpage)__ ?__header *value*__? ?__footer *value*__? ?__authors *list*__? - - Generate the manual page\. Returns the completed text suitable for saving in - \.man file\. The header argument is a block of doctools text to go in before - the machine generated section\. footer is a block of doctools text to go in - after the machine generated section\. authors is a list of individual authors - and emails in the form of AUTHOR EMAIL ?AUTHOR EMAIL?\.\.\. - - - method __scan\_text__ *text* - - Scan a block of text - - - method __scan\_file__ *filename* - - Scan a file of text - -## Class practcl::metaclass - -The metaclass for all practcl objects - -__Methods__ - - - method __\_MorphPatterns__ - - - method __[define](\.\./\.\./\.\./\.\./index\.md\#define)__ *submethod* ?*args*? - - - method __graft__ ?*args*? - - - method __initialize__ - - - method __link__ *command* ?*args*? - - - method __morph__ *classname* - - - method __script__ *script* - - - method __select__ - - - method __[source](\.\./\.\./\.\./\.\./index\.md\#source)__ *filename* - -## Class practcl::toolset - -Ancestor\-less class intended to be a mixin which defines a family of build -related behaviors that are modified when targetting either gcc or msvc - -__Class Methods__ - - - classmethod __select__ *object* - - Perform the selection for the toolset mixin - -__Methods__ - - - method __config\.sh__ - - find or fake a key/value list describing this project - - - method __BuildDir__ *PWD* - - Compute the location where the product will be built - - - method __MakeDir__ *srcdir* - - Return where the Makefile is located relative to *srcdir*\. For this - implementation the MakeDir is always srcdir\. - - - method __read\_configuration__ - - Read information about the build process for this package\. For this - implementation, data is sought in the following locations in the following - order: config\.tcl \(generated by practcl\.\) PKGConfig\.sh\. The Makefile - - If the Makefile needs to be consulted, but does not exist, the Configure - method is invoked - - - method __build\-cflags__ *PROJECT* *DEFS* *namevar* *versionvar* *defsvar* - - method DEFS This method populates 4 variables: name \- The name of the - package version \- The version of the package defs \- C flags passed to the - compiler includedir \- A list of paths to feed to the compiler for finding - headers - - - method __critcl__ ?*args*? - - Invoke critcl in an external process - -## Class practcl::toolset\.gcc - -*ancestors*: __practcl::toolset__ - -__Methods__ - - - method __Autoconf__ - - - method __BuildDir__ *PWD* - - - method __ConfigureOpts__ - - - method __MakeDir__ *srcdir* - - Detect what directory contains the Makefile template - - - method __make \{\} autodetect__ - - - method __make \{\} clean__ - - - method __make \{\} compile__ - - - method __make \{\} install__ *DEST* - - - method __build\-compile\-sources__ *PROJECT* *COMPILE* *CPPCOMPILE* *INCLUDES* - - - method __build\-Makefile__ *path* *PROJECT* - - - method __build\-library__ *outfile* *PROJECT* - - Produce a static or dynamic library - - - method __build\-tclsh__ *outfile* *PROJECT* ?*path* __auto__? - - Produce a static executable - -## Class practcl::toolset\.msvc - -*ancestors*: __practcl::toolset__ - -__Methods__ - - - method __BuildDir__ *PWD* - - MSVC always builds in the source directory - - - method __make \{\} autodetect__ - - Do nothing - - - method __make \{\} clean__ - - - method __make \{\} compile__ - - - method __make \{\} install__ *DEST* - - - method __MakeDir__ *srcdir* - - Detect what directory contains the Makefile template - - - method __NmakeOpts__ - -## Class practcl::make\_obj - -*ancestors*: __practcl::metaclass__ - -A build deliverable object\. Normally an object file, header, or tcl script which -must be compiled or generated in some way - -__Methods__ - - - method __constructor__ *module\_object* *name* *info* ?*action\_body* ____? - - - method __[do](\.\./\.\./\.\./\.\./index\.md\#do)__ - - - method __check__ - - - method __output__ - - - method __reset__ - - - method __triggers__ - -## Class practcl::object - -*ancestors*: __practcl::metaclass__ - -A generic Practcl object - -__Methods__ - - - method __constructor__ *parent* ?*args*? - - - method __child__ *method* - - - method __go__ - -## Class practcl::dynamic - -Dynamic blocks do not generate their own \.c files, instead the contribute to the -amalgamation of the main library file - -__Methods__ - - - method __cstructure__ *name* *definition* ?*argdat* ____? - - Parser functions - - - method __include__ *header* - - - method __include\_dir__ ?*args*? - - - method __include\_directory__ ?*args*? - - - method __c\_header__ *body* - - - method __c\_code__ *body* - - - method __c\_function__ *header* *body* ?*info* ____? - - - method __c\_tcloomethod__ *name* *body* ?*arginfo* ____? - - - method __cmethod__ *name* *body* ?*arginfo* ____? - - Alias to classic name - - - method __c\_tclproc\_nspace__ *nspace* - - - method __c\_tclcmd__ *name* *body* ?*arginfo* ____? - - - method __c\_tclproc\_raw__ *name* *body* ?*arginfo* ____? - - Alias to classic name - - - method __tcltype__ *name* *argdat* - - - method __project\-compile\-products__ - - Module interactions - - - method __implement__ *path* - - - method __initialize__ - - Practcl internals - - - method __linktype__ - - - method __generate\-cfile\-constant__ - - - method __generate\-cfile\-header__ - - - method __generate\-cfile\-tclapi__ - - Generate code that provides implements Tcl API calls - - - method __generate\-loader\-module__ - - Generate code that runs when the package/module is initialized into the - interpreter - - - method __Collate\_Source__ *CWD* - - - method __select__ - - Once an object marks itself as some flavor of dynamic, stop trying to morph - it into something else - -## Class practcl::product - -A deliverable for the build system - -__Class Methods__ - - - classmethod __select__ *object* - -__Methods__ - - - method __code__ *section* *body* - - - method __Collate\_Source__ *CWD* - - - method __project\-compile\-products__ - - - method __generate\-debug__ ?*spaces* ____? - - - method __generate\-cfile\-constant__ - - - method __generate\-cfile\-public\-structure__ - - Populate const static data structures - - - method __generate\-cfile\-header__ - - - method __generate\-cfile\-global__ - - - method __generate\-cfile\-private\-typedef__ - - - method __generate\-cfile\-private\-structure__ - - - method __generate\-cfile\-functions__ - - Generate code that provides subroutines called by Tcl API methods - - - method __generate\-cfile\-tclapi__ - - Generate code that provides implements Tcl API calls - - - method __generate\-hfile\-public\-define__ - - - method __generate\-hfile\-public\-macro__ - - - method __generate\-hfile\-public\-typedef__ - - - method __generate\-hfile\-public\-structure__ - - - method __generate\-hfile\-public\-headers__ - - - method __generate\-hfile\-public\-function__ - - - method __generate\-hfile\-public\-includes__ - - - method __generate\-hfile\-public\-verbatim__ - - - method __generate\-loader\-external__ - - - method __generate\-loader\-module__ - - - method __generate\-stub\-function__ - - - method __IncludeAdd__ *headervar* ?*args*? - - - method __generate\-tcl\-loader__ - - - method __generate\-tcl\-pre__ - - This methods generates any Tcl script file which is required to - pre\-initialize the C library - - - method __generate\-tcl\-post__ - - - method __linktype__ - - - method __Ofile__ *filename* - - - method __project\-static\-packages__ - - Methods called by the master project - - - method __toolset\-include\-directory__ - - Methods called by the toolset - - - method __target__ *method* ?*args*? - -## Class practcl::product\.cheader - -*ancestors*: __practcl::product__ - -A product which generated from a C header file\. Which is to say, nothing\. - -__Methods__ - - - method __project\-compile\-products__ - - - method __generate\-loader\-module__ - -## Class practcl::product\.csource - -*ancestors*: __practcl::product__ - -A product which generated from a C source file\. Normally an object \(\.o\) file\. - -__Methods__ - - - method __project\-compile\-products__ - -## Class practcl::product\.clibrary - -*ancestors*: __practcl::product__ - -A product which is generated from a compiled C library\. Usually a \.a or a \.dylib -file, but in complex cases may actually just be a conduit for one project to -integrate the source code of another - -__Methods__ - - - method __linker\-products__ *configdict* - -## Class practcl::product\.dynamic - -*ancestors*: __practcl::dynamic__ __practcl::product__ - -A product which is generated from C code that itself is generated by practcl or -some other means\. This C file may or may not produce its own \.o file, depending -on whether it is eligible to become part of an amalgamation - -__Methods__ - - - method __initialize__ - -## Class practcl::product\.critcl - -*ancestors*: __practcl::dynamic__ __practcl::product__ - -A binary product produced by critcl\. Note: The implementation is not written -yet, this class does nothing\. - -## Class practcl::module - -*ancestors*: __practcl::object__ __practcl::product\.dynamic__ - -In the end, all C code must be loaded into a module This will either be a -dynamically loaded library implementing a tcl extension, or a compiled in -segment of a custom shell/app - -__Variable__ - - - variable __make\_object__ - -__Methods__ - - - method __\_MorphPatterns__ - - - method __add__ ?*args*? - - - method __install\-headers__ ?*args*? - - - method __make \{\} \_preamble__ - - - method __make \{\} pkginfo__ - - - method __make \{\} objects__ - - Return a dictionary of all handles and associated objects - - - method __make \{\} object__ *name* - - Return the object associated with handle *name* - - - method __make \{\} reset__ - - Reset all deputy objects - - - method __make \{\} trigger__ ?*args*? - - Exercise the triggers method for all handles listed - - - method __make \{\} depends__ ?*args*? - - Exercise the check method for all handles listed - - - method __make \{\} filename__ *name* - - Return the file name of the build product for the listed handle - - - method __make \{\} target__ *name* *Info* *body* - - - method __make \{\} todo__ - - Return a list of handles for object which return true for the do method - - - method __make \{\} do__ - - For each target exercise the action specified in the *action* definition - if the *do* method returns true - - - method __child__ *which* - - - method __generate\-c__ - - This methods generates the contents of an amalgamated \.c file which - implements the loader for a batch of tools - - - method __generate\-h__ - - This methods generates the contents of an amalgamated \.h file which - describes the public API of this module - - - method __generate\-loader__ - - - method __initialize__ - - - method __implement__ *path* - - - method __linktype__ - -## Class practcl::project - -*ancestors*: __practcl::module__ - -A toplevel project that is a collection of other projects - -__Methods__ - - - method __\_MorphPatterns__ - - - method __constructor__ ?*args*? - - - method __add\_object__ *object* - - - method __add\_project__ *pkg* *info* ?*oodefine* ____? - - - method __add\_tool__ *pkg* *info* ?*oodefine* ____? - - - method __build\-tclcore__ - - Compile the Tcl core\. If the define *tk* is true, compile the Tk core as - well - - - method __child__ *which* - - - method __linktype__ - - - method __project__ *pkg* ?*args*? - - Exercise the methods of a sub\-object - - - method __tclcore__ - - - method __tkcore__ - - - method __[tool](\.\./tool/tool\.md)__ *pkg* ?*args*? - -## Class practcl::library - -*ancestors*: __practcl::project__ - -A toplevel project that produces a library - -__Methods__ - - - method __clean__ *PATH* - - - method __project\-compile\-products__ - - - method __go__ - - - method __generate\-decls__ *pkgname* *path* - - - method __implement__ *path* - - - method __generate\-make__ *path* - - Backward compadible call - - - method __linktype__ - - - method __package\-ifneeded__ ?*args*? - - Create a "package ifneeded" Args are a list of aliases for which this - package will answer to - - - method __shared\_library__ ?*filename* ____? - - - method __static\_library__ ?*filename* ____? - -## Class practcl::tclkit - -*ancestors*: __practcl::library__ - -A toplevel project that produces a self\-contained executable - -__Methods__ - - - method __build\-tclkit\_main__ *PROJECT* *PKG\_OBJS* - - - method __Collate\_Source__ *CWD* - - - method __wrap__ *PWD* *exename* *vfspath* ?*args*? - - Wrap an executable - -## Class practcl::distribution - -Standalone class to manage code distribution This class is intended to be mixed -into another class \(Thus the lack of ancestors\) - -__Class Methods__ - - - classmethod __Sandbox__ *object* - - - classmethod __select__ *object* - - - classmethod __claim\_option__ - - - classmethod __claim\_object__ *object* - - - classmethod __claim\_path__ *path* - -__Methods__ - - - method __scm\_info__ - - - method __DistroMixIn__ - - - method __Sandbox__ - - - method __SrcDir__ - - - method __ScmTag__ - - - method __ScmClone__ - - - method __ScmUnpack__ - - - method __ScmUpdate__ - - - method __Unpack__ - -## Class practcl::distribution\.snapshot - -*ancestors*: __practcl::distribution__ - -A file distribution from zip, tarball, or other non\-scm archive format - -__Class Methods__ - - - classmethod __claim\_object__ *object* - - - classmethod __claim\_option__ - - - classmethod __claim\_path__ *path* - -__Methods__ - - - method __ScmUnpack__ - -## Class practcl::distribution\.fossil - -*ancestors*: __practcl::distribution__ - -A file distribution based on fossil - -__Class Methods__ - - - classmethod __claim\_object__ *obj* - - Check for markers in the metadata - - - classmethod __claim\_option__ - - - classmethod __claim\_path__ *path* - - Check for markers in the source root - -__Methods__ - - - method __scm\_info__ - - - method __ScmClone__ - - Clone the source - - - method __ScmTag__ - - - method __ScmUnpack__ - - - method __ScmUpdate__ - -## Class practcl::distribution\.git - -*ancestors*: __practcl::distribution__ - -A file distribution based on git - -__Class Methods__ - - - classmethod __claim\_object__ *obj* - - - classmethod __claim\_option__ - - - classmethod __claim\_path__ *path* - -__Methods__ - - - method __ScmTag__ - - - method __ScmUnpack__ - - - method __ScmUpdate__ - -## Class practcl::subproject - -*ancestors*: __practcl::module__ - -A subordinate project - -__Methods__ - - - method __\_MorphPatterns__ - - - method __BuildDir__ *PWD* - - - method __child__ *which* - - - method __compile__ - - - method __go__ - - - method __install__ ?*args*? - - Install project into the local build system - - - method __linktype__ - - - method __linker\-products__ *configdict* - - - method __linker\-external__ *configdict* - - - method __linker\-extra__ *configdict* - - - method __env\-bootstrap__ - - Methods for packages/tools that can be downloaded possibly built and used - internally by this Practcl process Load the facility into the interpreter - - - method __env\-exec__ - - Return a file path that exec can call - - - method __env\-install__ - - Install the tool into the local environment - - - method __env\-load__ - - Do whatever is necessary to get the tool into the local environment - - - method __env\-present__ - - Check if tool is available for load/already loaded - - - method __sources__ - - - method __[update](\.\./\.\./\.\./\.\./index\.md\#update)__ - - - method __unpack__ - -## Class practcl::subproject\.source - -*ancestors*: __practcl::subproject__ __practcl::library__ - -A project which the kit compiles and integrates the source for itself - -__Methods__ - - - method __env\-bootstrap__ - - - method __env\-present__ - - - method __linktype__ - -## Class practcl::subproject\.teapot - -*ancestors*: __practcl::subproject__ - -a copy from the teapot - -__Methods__ - - - method __env\-bootstrap__ - - - method __env\-install__ - - - method __env\-present__ - - - method __install__ *DEST* - -## Class practcl::subproject\.kettle - -*ancestors*: __practcl::subproject__ - -__Methods__ - - - method __kettle__ *path* ?*args*? - - - method __install__ *DEST* - -## Class practcl::subproject\.critcl - -*ancestors*: __practcl::subproject__ - -__Methods__ - - - method __install__ *DEST* - -## Class practcl::subproject\.sak - -*ancestors*: __practcl::subproject__ - -__Methods__ - - - method __env\-bootstrap__ - - - method __env\-install__ - - - method __env\-present__ - - - method __install__ *DEST* - - - method __install\-module__ *DEST* ?*args*? - -## Class practcl::subproject\.practcl - -*ancestors*: __practcl::subproject__ - -__Methods__ - - - method __env\-bootstrap__ - - - method __env\-install__ - - - method __install__ *DEST* - - - method __install\-module__ *DEST* ?*args*? - -## Class practcl::subproject\.binary - -*ancestors*: __practcl::subproject__ - -A subordinate binary package - -__Methods__ - - - method __clean__ - - - method __env\-install__ - - - method __project\-compile\-products__ - - - method __ComputeInstall__ - - - method __go__ - - - method __linker\-products__ *configdict* - - - method __project\-static\-packages__ - - - method __BuildDir__ *PWD* - - - method __compile__ - - - method __Configure__ - - - method __install__ *DEST* - -## Class practcl::subproject\.tea - -*ancestors*: __practcl::subproject\.binary__ - -A subordinate TEA based binary package - -## Class practcl::subproject\.library - -*ancestors*: __practcl::subproject\.binary__ __practcl::library__ - -A subordinate C library built by this project - -__Methods__ - - - method __install__ *DEST* - -## Class practcl::subproject\.external - -*ancestors*: __practcl::subproject\.binary__ - -A subordinate external C library - -__Methods__ - - - method __install__ *DEST* - -## Class practcl::subproject\.core - -*ancestors*: __practcl::subproject\.binary__ - -__Methods__ - - - method __env\-bootstrap__ - - - method __env\-present__ - - - method __env\-install__ - - - method __go__ - - - method __linktype__ - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *practcl* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[practcl](\.\./\.\./\.\./\.\./index\.md\#practcl) - -# CATEGORY - -TclOO - -# COPYRIGHT - -Copyright © 2016\-2018 Sean Woods DELETED embedded/md/tcllib/files/modules/processman/processman.md Index: embedded/md/tcllib/files/modules/processman/processman.md ================================================================== --- embedded/md/tcllib/files/modules/processman/processman.md +++ embedded/md/tcllib/files/modules/processman/processman.md @@ -1,133 +0,0 @@ - -[//000000001]: # (processman \- processman) -[//000000002]: # (Generated from file 'processman\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Sean Woods ) -[//000000004]: # (processman\(n\) 0\.1 tcllib "processman") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -processman \- Tool for automating the period callback of commands - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Commands](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require twapi 3\.1 -package require cron 1\.1 -package require processman ?0\.1? - -[__::processman::find\_exe__ *name*](#1) -[__::processman::kill__ *id*](#2) -[__::processman::kill\_all__](#3) -[__::processman::killexe__ *name*](#4) -[__::processman::onexit__ *id* *cmd*](#5) -[__::processman::priority__ *id* *level*](#6) -[__::processman::process\_list__](#7) -[__::processman::process\_list__ *id*](#8) -[__::processman::spawn__ *id* *cmd* *args*](#9) - -# DESCRIPTION - -The __processman__ package provides a Pure\-tcl set of utilities to manage -child processes in a platform\-generic nature\. - -# Commands - - - __::processman::find\_exe__ *name* - - Locate an executable by the name of *name* in the system path\. On windows, - also add the \.exe extention if not given\. - - - __::processman::kill__ *id* - - Kill a child process *id*\. - - - __::processman::kill\_all__ - - Kill all processes spawned by this program - - - __::processman::killexe__ *name* - - Kill a process identified by the executable\. On Unix, this triggers a - killall\. On windows, __twapi::get\_process\_ids__ is used to map a name - one or more IDs, which are then killed\. - - - __::processman::onexit__ *id* *cmd* - - Arrange to execute the script *cmd* when this programe detects that - process *id* as terminated\. - - - __::processman::priority__ *id* *level* - - Mark process *id* with the priorty *level*\. Valid levels: low, high, - default\. - - On Unix, the process is tagged using the __nice__ command\. - - On Windows, the process is modifed via the __twapi::set\_priority\_class__ - - - __::processman::process\_list__ - - Return a list of processes that have been triggered by this program, as well - as a boolean flag to indicate if the process is still running\. - - - __::processman::process\_list__ *id* - - Return true if process *id* is still running, false otherwise\. - - - __::processman::spawn__ *id* *cmd* *args* - - Start a child process, identified by *id*\. *cmd* is the name of the - command to execute\. *args* are arguments to pass to that command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *odie* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[odie](\.\./\.\./\.\./\.\./index\.md\#odie), -[processman](\.\./\.\./\.\./\.\./index\.md\#processman) - -# CATEGORY - -System - -# COPYRIGHT - -Copyright © 2015 Sean Woods DELETED embedded/md/tcllib/files/modules/profiler/profiler.md Index: embedded/md/tcllib/files/modules/profiler/profiler.md ================================================================== --- embedded/md/tcllib/files/modules/profiler/profiler.md +++ embedded/md/tcllib/files/modules/profiler/profiler.md @@ -1,173 +0,0 @@ - -[//000000001]: # (profiler \- Tcl Profiler) -[//000000002]: # (Generated from file 'profiler\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (profiler\(n\) 0\.5 tcllib "Tcl Profiler") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -profiler \- Tcl source code profiler - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.3 -package require profiler ?0\.5? - -[__::profiler::init__](#1) -[__::profiler::dump__ *pattern*](#2) -[__::profiler::print__ ?*pattern*?](#3) -[__::profiler::reset__ ?*pattern*?](#4) -[__::profiler::suspend__ ?*pattern*?](#5) -[__::profiler::resume__ ?*pattern*?](#6) -[__::profiler::new\-disabled__](#7) -[__::profiler::new\-enabled__](#8) -[__::profiler::sortFunctions__ *key*](#9) - -# DESCRIPTION - -The __profiler__ package provides a simple Tcl source code profiler\. It is a -function\-level profiler; that is, it collects only function\-level information, -not the more detailed line\-level information\. It operates by redefining the Tcl -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ command\. Profiling is initiated -via the __::profiler::init__ command\. - -# COMMANDS - - - __::profiler::init__ - - Initiate profiling\. All procedures created after this command is called will - be profiled\. To profile an entire application, this command must be called - before any other commands\. - - - __::profiler::dump__ *pattern* - - Dump profiling information for the all functions matching *pattern*\. If no - pattern is specified, information for all functions will be returned\. The - result is a list of key/value pairs that maps function names to information - about that function\. The information about each function is in turn a list - of key/value pairs\. The keys used and their values are: - - * __totalCalls__ - - The total number of times *functionName* was called\. - - * __callerDist__ - - A list of key/value pairs mapping each calling function that called - *functionName* to the number of times it called *functionName*\. - - * __compileTime__ - - The runtime, in clock clicks, of *functionName* the first time that it - was called\. - - * __totalRuntime__ - - The sum of the runtimes of all calls of *functionName*\. - - * __averageRuntime__ - - Average runtime of *functionName*\. - - * __descendantTime__ - - Sum of the time spent in descendants of *functionName*\. - - * __averageDescendantTime__ - - Average time spent in descendants of *functionName*\. - - - __::profiler::print__ ?*pattern*? - - Print profiling information for all functions matching *pattern*\. If no - pattern is specified, information about all functions will be displayed\. The - return result is a human readable display of the profiling information\. - - - __::profiler::reset__ ?*pattern*? - - Reset profiling information for all functions matching *pattern*\. If no - pattern is specified, information will be reset for all functions\. - - - __::profiler::suspend__ ?*pattern*? - - Suspend profiling for all functions matching *pattern*\. If no pattern is - specified, profiling will be suspended for all functions\. It stops gathering - profiling information after this command is issued\. However, it does not - erase any profiling information that has been gathered previously\. Use - resume command to re\-enable profiling\. - - - __::profiler::resume__ ?*pattern*? - - Resume profiling for all functions matching *pattern*\. If no pattern is - specified, profiling will be resumed for all functions\. This command should - be invoked after suspending the profiler in the code\. - - - __::profiler::new\-disabled__ - - Change the initial profiling state for new procedures\. Invoking this command - disables profiling for all procedures created after this command until - __new\-enabled__ is invoked\. Activate profiling of specific procedures - via __resume__\. - - - __::profiler::new\-enabled__ - - Change the initial profiling state for new procedures\. Invoking this command - enables profiling for all procedures created after this command until - __new\-disabled__ is invoked\. Prevent profiling of specific procedures - via __suspend__\. - - - __::profiler::sortFunctions__ *key* - - Return a list of functions sorted by a particular profiling statistic\. - Supported values for *key* are: __calls__, __exclusiveTime__, - __compileTime__, __nonCompileTime__, __totalRuntime__, - __avgExclusiveTime__, and __avgRuntime__\. The return result is a - list of lists, where each sublist consists of a function name and the value - of *key* for that function\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *profiler* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[performance](\.\./\.\./\.\./\.\./index\.md\#performance), -[profile](\.\./\.\./\.\./\.\./index\.md\#profile), -[speed](\.\./\.\./\.\./\.\./index\.md\#speed) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/pt/pt_astree.md Index: embedded/md/tcllib/files/modules/pt/pt_astree.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_astree.md +++ embedded/md/tcllib/files/modules/pt/pt_astree.md @@ -1,312 +0,0 @@ - -[//000000001]: # (pt::ast \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_astree\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::ast\(n\) 1\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::ast \- Abstract Syntax Tree Serialization - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [AST serialization format](#section3) - - - [Example](#subsection1) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::ast ?1\.1? - -[__::pt::ast__ __verify__ *serial* ?*canonvar*?](#1) -[__::pt::ast__ __verify\-as\-canonical__ *serial*](#2) -[__::pt::ast__ __canonicalize__ *serial*](#3) -[__::pt::ast__ __print__ *serial*](#4) -[__::pt::ast__ __bottomup__ *cmdprefix* *ast*](#5) -[__cmdprefix__ *ast*](#6) -[__::pt::ast__ __topdown__ *cmdprefix* *pe*](#7) -[__::pt::ast__ __equal__ *seriala* *serialb*](#8) -[__::pt::ast__ __new0__ *s* *loc* ?*child*\.\.\.?](#9) -[__::pt::ast__ __new__ *s* *start* *end* ?*child*\.\.\.?](#10) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides commands to work with the serializations of abstract -syntax trees as managed by the Parser Tools, and specified in section [AST -serialization format](#section3)\. - -This is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::ast__ __verify__ *serial* ?*canonvar*? - - This command verifies that the content of *serial* is a valid - serialization of an abstract syntax tree and will throw an error if that is - not the case\. The result of the command is the empty string\. - - If the argument *canonvar* is specified it is interpreted as the name of a - variable in the calling context\. This variable will be written to if and - only if *serial* is a valid regular serialization\. Its value will be a - boolean, with __True__ indicating that the serialization is not only - valid, but also *canonical*\. __False__ will be written for a valid, - but non\-canonical serialization\. - - For the specification of serializations see the section [AST serialization - format](#section3)\. - - - __::pt::ast__ __verify\-as\-canonical__ *serial* - - This command verifies that the content of *serial* is a valid - *canonical* serialization of an abstract syntax tree and will throw an - error if that is not the case\. The result of the command is the empty - string\. - - For the specification of canonical serializations see the section [AST - serialization format](#section3)\. - - - __::pt::ast__ __canonicalize__ *serial* - - This command assumes that the content of *serial* is a valid *regular* - serialization of an abstract syntax and will throw an error if that is not - the case\. - - It will then convert the input into the *canonical* serialization of the - contained tree and return it as its result\. If the input is already - canonical it will be returned unchanged\. - - For the specification of regular and canonical serializations see the - section [AST serialization format](#section3)\. - - - __::pt::ast__ __print__ *serial* - - This command assumes that the argument *serial* contains a valid - serialization of an abstract syntax tree and returns a string containing - that tree in a human readable form\. - - The exact format of this form is not specified and cannot be relied on for - parsing or other machine\-based activities\. - - For the specification of serializations see the section [AST serialization - format](#section3)\. - - - __::pt::ast__ __bottomup__ *cmdprefix* *ast* - - This command walks the abstract syntax tree *ast* from the bottom up to - the root, invoking the command prefix *cmdprefix* for each node\. This - implies that the children of a node N are handled before N\. - - The command prefix has the signature - - * __cmdprefix__ *ast* - - I\.e\. it is invoked with the ast node the walk is currently at\. - - The result returned by the command prefix replaces *ast* in the node - it was a child of, allowing transformations of the tree\. - - This also means that for all inner node the contents of the children - elements are the results of the command prefix invoked for the children - of this node\. - - - __::pt::ast__ __topdown__ *cmdprefix* *pe* - - This command walks the abstract syntax tree *ast* from the root down to - the leaves, invoking the command prefix *cmdprefix* for each node\. This - implies that the children of a node N are handled after N\. - - The command prefix has the same signature as for __bottomup__, see - above\. - - The result returned by the command prefix is *ignored*\. - - - __::pt::ast__ __equal__ *seriala* *serialb* - - This command tests the two sbstract syntax trees *seriala* and *serialb* - for structural equality\. The result of the command is a boolean value\. It - will be set to __true__ if the trees are identical, and __false__ - otherwise\. - - String equality is usable only if we can assume that the two trees are pure - Tcl lists\. - - - __::pt::ast__ __new0__ *s* *loc* ?*child*\.\.\.? - - This command command constructs the ast for a nonterminal node refering - refering to the symbol *s* at position *loc* in the input, and the set - of child nodes *child* \.\.\., from left right\. The latter may be empty\. The - constructed node is returned as the result of the command\. The end position - is *loc*\-1, i\.e\. one character before the start\. This type of node is - possible for rules containing optional parts\. - - - __::pt::ast__ __new__ *s* *start* *end* ?*child*\.\.\.? - - This command command constructs the ast for a nonterminal node refering to - the symbol *s* covering the range of positions *start* to *end* in the - input, and the set of child nodes *child* \.\.\., from left right\. The latter - may be empty\. The constructed node is returned as the result of the command\. - -# AST serialization format - -Here we specify the format used by the Parser Tools to serialize Abstract Syntax -Trees \(ASTs\) as immutable values for transport, comparison, etc\. - -Each node in an AST represents a nonterminal symbol of a grammar, and the range -of tokens/characters in the input covered by it\. ASTs do not contain terminal -symbols, i\.e\. tokens/characters\. These can be recovered from the input given a -symbol's location\. - -We distinguish between *regular* and *canonical* serializations\. While a -tree may have more than one regular serialization only exactly one of them will -be *canonical*\. - - - Regular serialization - - 1. The serialization of any AST is the serialization of its root node\. - - 1. The serialization of any node is a Tcl list containing at least three - elements\. - - 1) The first element is the name of the nonterminal symbol stored in - the node\. - - 1) The second and third element are the locations of the first and - last token in the token stream the node represents \(covers\)\. - - 1. Locations are provided as non\-negative integer offsets from - the beginning of the token stream, with the first token found - in the stream located at offset 0 \(zero\)\. - - 1. The end location has to be equal to or larger than the start - location\. - - 1) All elements after the first three represent the children of the - node, which are themselves nodes\. This means that the - serializations of nodes without children, i\.e\. leaf nodes, have - exactly three elements\. The children are stored in the list with - the leftmost child first, and the rightmost child last\. - - - Canonical serialization - - The canonical serialization of an abstract syntax tree has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this tree\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the parsing expression grammar below - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -and the input string - - 120+5 - -then a parser should deliver the abstract syntax tree below \(except for -whitespace\) - - set ast {Expression 0 4 - {Factor 0 4 - {Term 0 2 - {Number 0 2 - {Digit 0 0} - {Digit 1 1} - {Digit 2 2} - } - } - {AddOp 3 3} - {Term 4 4 - {Number 4 4 - {Digit 4 4} - } - } - } - } - -Or, more graphical - -![](\.\./\.\./\.\./\.\./image/expr\_ast\.png) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md Index: embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md +++ embedded/md/tcllib/files/modules/pt/pt_cparam_config_critcl.md @@ -1,115 +0,0 @@ - -[//000000001]: # (pt::cparam::configuration::critcl \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_cparam\_config\_critcl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::cparam::configuration::critcl\(n\) 1\.0\.2 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::cparam::configuration::critcl \- C/PARAM, Canned configuration, Critcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::cparam::configuration::critcl ?1\.0\.2? - -[__::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package is an adjunct to -__[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__, to make the use of this -highly configurable package easier by providing a canned configuration\. When -applied this configuration causes the package -__[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ to generate -__critcl__\-based parser packages\. - -It is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::cparam::configuration::critcl__ __def__ *name* *pkg* *version* *cmdprefix* - - The command applies the configuration provided by this package to the - *cmdprefix*, causing the creation of __critcl__\-based parsers whose - class is *name*, in package *pkg* with *version*\. - - The use of a command prefix as API allows application of the configuration - to not only __[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ - \(__pt::peg::to::cparam configure__\), but also export manager instances - and PEG containers \(__$export configuration set__ and __\[$container - exporter\] configuration set__ respectively\)\. - - Or anything other command prefix accepting two arguments, option and value\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md Index: embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md +++ embedded/md/tcllib/files/modules/pt/pt_cparam_config_tea.md @@ -1,115 +0,0 @@ - -[//000000001]: # (pt::cparam::configuration::tea \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_cparam\_config\_tea\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::cparam::configuration::tea\(n\) 0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::cparam::configuration::tea \- C/PARAM, Canned configuration, TEA - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::cparam::configuration::tea ?0\.1? - -[__::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package is an adjunct to -__[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__, to make the use of this -highly configurable package easier by providing a canned configuration\. When -applied this configuration causes the package -__[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ to generate plain parser -code ready for inclusion into a *TEA*\-based C extension\. - -It is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::cparam::configuration::tea__ __def__ *name* *pkg* *version* *cmdprefix* - - The command applies the configuration provided by this package to the - *cmdprefix*, causing the creation of __tea__\-based parsers whose class - is *name*, in package *pkg* with *version*\. - - The use of a command prefix as API allows application of the configuration - to not only __[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ - \(__pt::peg::to::cparam configure__\), but also export manager instances - and PEG containers \(__$export configuration set__ and __\[$container - exporter\] configuration set__ respectively\)\. - - Or anything other command prefix accepting two arguments, option and value\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_from_api.md Index: embedded/md/tcllib/files/modules/pt/pt_from_api.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_from_api.md +++ embedded/md/tcllib/files/modules/pt/pt_from_api.md @@ -1,506 +0,0 @@ - -[//000000001]: # (pt\_import\_api \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_from\_api\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_import\_api\(i\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_import\_api \- Parser Tools Import API - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Converter API](#section2) - - - [Plugin API](#section3) - - - [Usage](#section4) - - - [PEG serialization format](#section5) - - - [Example](#subsection1) - - - [PE serialization format](#section6) - - - [Example](#subsection2) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -[__CONVERTER__ __convert__ *text*](#1) -[__IncludeFile__ *currentfile* *path*](#2) -[__::import__ *text*](#3) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This document describes two APIs\. First the API shared by all packages for the -conversion of some other format into Parsing Expression Grammars , and then the -API shared by the packages which implement the import plugins sitting on top of -the conversion packages\. - -Its intended audience are people who wish to create their own converter for some -type of input, and/or an import plugin for their or some other converter\. - -It resides in the Import section of the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_import\.png) - -# Converter API - -Any \(grammar\) import converter has to follow the rules set out below: - - 1. A converter is a package\. Its name is arbitrary, however it is recommended - to put it under the __::pt::peg::from__ namespace\. - - 1. The package provides either a single Tcl command following the API outlined - below, or a class command whose instances follow the same API\. The commands - which follow the API are called *converter commands*\. - - 1. A converter command has to provide the following single method with the - given signature and semantic\. Converter commands are allowed to provide - more methods of their own, but not less, and they may not provide different - semantics for the standardized method\. - - - __CONVERTER__ __convert__ *text* - - This method has to accept some *text*, a parsing expression grammar - in some format\. The result of the method has to be the canonical - serialization of a parsing expression grammar, as specified in section - [PEG serialization format](#section5), the result of reading and - converting the input text\. - -# Plugin API - -Any \(grammar\) import plugin has to follow the rules set out below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form pt::peg::import::__FOO__, - where __FOO__ is the name of the format the plugin will accept input - for\. - - 1. The plugin can expect that the package __pt::peg::import::plugin__ is - present, as indicator that it was invoked from a genuine plugin manager\. - - It is recommended that a plugin does check for the presence of this - package\. - - 1. The plugin can expect that a command named __IncludeFile__ is present, - with the signature - - - __IncludeFile__ *currentfile* *path* - - This command has to be invoked by the plugin when it has to process an - included file, if the format has the concept of such\. - - The plugin has to supply the following arguments - - * string *currentfile* - - The path of the file it is currently processing\. This may be the - empty string if no such is known\. - - * string *path* - - The path of the include file as specified in the include directive - being processed\. - - The result of the command will be a 5\-element list containing - - 1) A boolean flag indicating the success \(__True__\) or failure - \(__False__\) of the operation\. - - 1) In case of success the contents of the included file, and the - empty string otherwise\. - - 1) The resolved, i\.e\. absolute path of the included file, if - possible, or the unchanged *path* argument\. This is for display - in an error message, or as the *currentfile* argument of another - call to __IncludeFile__ should this file contain more files\. - - 1) In case of success an empty string, and for failure a code - indicating the reason for it, one of - - * notfound - - The specified file could not be found\. - - * notread - - The specified file was found, but not be read into memory\. - - 1) An empty string in case of success of a __notfound__ failure, - and an additional error message describing the reason for a - __notread__ error in more detail\. - - 1. A plugin has to provide a single command, in the global namespace, with the - signature shown below\. Plugins are allowed to provide more commands of - their own, but not less, and they may not provide different semantics for - the standardized command\. - - - __::import__ *text* - - This command has to accept the a text containing a parsing expression - grammar in some format\. The result of the command has to be the result - of the converter invoked by the plugin for the input grammar, the - canonical serialization of the parsing expression grammar contained in - the input\. - - * string *text* - - This argument will contain the parsing expression grammar for which - to generate the serialization\. The specification of what a - *canonical* serialization is can be found in the section [PEG - serialization format](#section5)\. - - 1. A single usage cycle of a plugin consists of an invokation of the command - __[import](\.\./\.\./\.\./\.\./index\.md\#import)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# Usage - -To use a converter do - - # Get the converter (single command here, not class) - package require the-converter-package - - # Perform the conversion - set serial [theconverter convert $thegrammartext] - - ... process the result ... - -To use a plugin __FOO__ do - - # Get an import plugin manager - package require pt::peg::import - pt::peg::import I - - # Run the plugin, and the converter inside. - set serial [I import serial $thegrammartext FOO] - - ... process the result ... - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_introduction.md Index: embedded/md/tcllib/files/modules/pt/pt_introduction.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_introduction.md +++ embedded/md/tcllib/files/modules/pt/pt_introduction.md @@ -1,223 +0,0 @@ - -[//000000001]: # (pt\_introduction \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_introduction\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_introduction\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_introduction \- Introduction to Parser Tools - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Parser Tools Architecture](#section2) - - - [User Packages](#subsection1) - - - [Core Packages](#subsection2) - - - [Support Packages](#subsection3) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Welcome to the Parser Tools, a system for the creation and manipulation of -parsers and the grammars driving them\. - -What are your goals which drove you here ? - - 1. Do you simply wish to create a parser for some language ? - - In that case have a look at our parser generator application, - __[pt](\.\./\.\./apps/pt\.md)__, or, for a slightly deeper access, the - package underneath it, __[pt::pgen](pt\_pgen\.md)__\. - - 1. Do you wish to know more about the architecture of the system ? - - This is described in the section [Parser Tools - Architecture](#section2), below - - 1. Is your interest in the theoretical background upon which the packages and - tools are build ? - - See the *[Introduction to Parsing Expression - Grammars](pt\_peg\_introduction\.md)*\. - -# Parser Tools Architecture - -The system can be split into roughly three layers, as seen in the figure below - -![](\.\./\.\./\.\./\.\./image/architecture\.png) These layers are, from high to low: - - 1. At the top we have the application and the packages using the packages of - the layer below to implement common usecases\. One example is the - aforementioned __[pt::pgen](pt\_pgen\.md)__ which provides a parser - generator\. - - The list of packages belonging to this layer can be found in section [User - Packages](#subsection1) - - 1. In this layer we have the packages which provide the core of the - functionality for the whole system\. They are, in essence, a set of blocks - which can be combined in myriad ways, like Lego \(tm\)\. The packages in the - previous level are 'just' pre\-fabricated combinations to cover the most - important use cases\. - - The list of packages belonging to this layer can be found in section [Core - Packages](#subsection2) - - 1. Last, but not least is the layer containing support packages providing - generic functionality which not necessarily belong into the module\. - - The list of packages belonging to this layer can be found in section - [Support Packages](#subsection3) - -## User Packages - - - __[pt::pgen](pt\_pgen\.md)__ - -## Core Packages - -This layer is further split into six sections handling the storage, import, -export, transformation, and execution of grammars, plus grammar specific support -packages\. - - - Storage - - * __[pt::peg::container](pt\_peg\_container\.md)__ - - - Export - - * __[pt::peg::export](pt\_peg\_export\.md)__ - - * __[pt::peg::export::container](pt\_peg\_export\_container\.md)__ - - * __[pt::peg::export::json](pt\_peg\_export\_json\.md)__ - - * __[pt::peg::export::peg](pt\_peg\_export\_peg\.md)__ - - * __[pt::peg::to::container](pt\_peg\_to\_container\.md)__ - - * __[pt::peg::to::json](pt\_peg\_to\_json\.md)__ - - * __[pt::peg::to::peg](pt\_peg\_to\_peg\.md)__ - - * __[pt::peg::to::param](pt\_peg\_to\_param\.md)__ - - * __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ - - * __[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ - - - Import - - * __[pt::peg::import](pt\_peg\_import\.md)__ - - * __[pt::peg::import::container](pt\_peg\_import\_container\.md)__ - - * __[pt::peg::import::json](pt\_peg\_import\_json\.md)__ - - * __[pt::peg::import::peg](pt\_peg\_import\_peg\.md)__ - - * __[pt::peg::from::container](pt\_peg\_from\_container\.md)__ - - * __[pt::peg::from::json](pt\_peg\_from\_json\.md)__ - - * __[pt::peg::from::peg](pt\_peg\_from\_peg\.md)__ - - - Transformation - - - Execution - - * __[pt::peg::interp](pt\_peg\_interp\.md)__ - - * __[pt::rde](pt\_rdengine\.md)__ - - - Support - - * __[pt::tclparam::configuration::snit](pt\_tclparam\_config\_snit\.md)__ - - * __[pt::tclparam::configuration::tcloo](pt\_tclparam\_config\_tcloo\.md)__ - - * __[pt::cparam::configuration::critcl](pt\_cparam\_config\_critcl\.md)__ - - * __[pt::ast](pt\_astree\.md)__ - - * __[pt::pe](pt\_pexpression\.md)__ - - * __[pt::peg](pt\_pegrammar\.md)__ - -## Support Packages - - - __[pt::peg::container::peg](pt\_peg\_container\_peg\.md)__ - - - __text::write__ - - - __configuration__ - - - __paths__ - - - __char__ - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_json_language.md Index: embedded/md/tcllib/files/modules/pt/pt_json_language.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_json_language.md +++ embedded/md/tcllib/files/modules/pt/pt_json_language.md @@ -1,501 +0,0 @@ - -[//000000001]: # (pt::json\_language \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_json\_language\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::json\_language\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::json\_language \- The JSON Grammar Exchange Format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Example](#subsection1) - - - [PEG serialization format](#section2) - - - [Example](#subsection2) - - - [PE serialization format](#section3) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -It is formally specified by the rules below: - - 1. The JSON of any PEG is a JSON object\. - - 1. This object holds a single key, __pt::grammar::peg__, and its value\. - This value holds the contents of the grammar\. - - 1. The contents of the grammar are a JSON object holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - - __rules__ - - The value is a JSON object whose keys are the names of the nonterminal - symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a JSON object itself\. The relevant - keys and their values in this dictionary are - - * __is__ - - The value is a JSON string holding the Tcl serialization of - the parsing expression describing the symbols sentennial - structure, as specified in the section [PE serialization - format](#section3)\. - - * __mode__ - - The value is a JSON holding holding one of three values - specifying how a parser should handle the semantic value - produced by the symbol\. - - + __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal itself, which has the ASTs of the symbol's - right hand side as its children\. - - + __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal, without any children\. Any ASTs generated - by the symbol's right hand side are discarded\. - - + __void__ - - The nonterminal has no semantic value\. Any ASTs generated - by the symbol's right hand side are discarded \(as well\)\. - - - __start__ - - The value is a JSON string holding the Tcl serialization of the start - parsing expression of the grammar, as specified in the section [PE - serialization format](#section3)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set of - all terminal symbols used in the start expression and on the RHS of the - grammar rules\. - -As an aside to the advanced reader, this is pretty much the same as the Tcl -serialization of PE grammars, as specified in section [PEG serialization -format](#section2), except that the Tcl dictionaries and lists of that -format are mapped to JSON objects and arrays\. Only the parsing expressions -themselves are not translated further, but kept as JSON strings containing a -nested Tcl list, and there is no concept of canonicity for the JSON either\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -a JSON serialization for it is - - { - "pt::grammar::peg" : { - "rules" : { - "AddOp" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Digit" : { - "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", - "mode" : "value" - }, - "Expression" : { - "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", - "mode" : "value" - }, - "Factor" : { - "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", - "mode" : "value" - }, - "MulOp" : { - "is" : "\/ {t *} {t \/}", - "mode" : "value" - }, - "Number" : { - "is" : "x {? {n Sign}} {+ {n Digit}}", - "mode" : "value" - }, - "Sign" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Term" : { - "is" : "n Number", - "mode" : "value" - } - }, - "start" : "n Expression" - } - } - -and a Tcl serialization of the same is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -The similarity of the latter to the JSON should be quite obvious\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section3)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section3)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_param.md Index: embedded/md/tcllib/files/modules/pt/pt_param.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_param.md +++ embedded/md/tcllib/files/modules/pt/pt_param.md @@ -1,644 +0,0 @@ - -[//000000001]: # (pt::param \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_param\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::param\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::param \- PackRat Machine Specification - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Architectural State](#section2) - - - [Instruction Set](#section3) - - - [Input Handling](#subsection1) - - - [Character Processing](#subsection2) - - - [Error Handling](#subsection3) - - - [Status Control](#subsection4) - - - [Location Handling](#subsection5) - - - [Nonterminal Execution](#subsection6) - - - [Value Construction](#subsection7) - - - [AST Construction](#subsection8) - - - [Control Flow](#subsection9) - - - [Interaction of the Instructions with the Architectural - State](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -Welcome to the PackRat Machine \(short: -*[PARAM](\.\./\.\./\.\./\.\./index\.md\#param)*\), a virtual machine geared towards -the support of recursive descent parsers, especially packrat parsers\. Towards -this end it has features like the caching and reuse of partial results, the -caching of the encountered input, and the ability to backtrack in both input and -AST creation\. - -This document specifies the machine in terms of its architectural state and -instruction set\. - -# Architectural State - -Any PARAM implementation has to manage at least the following state: - - - *Input* \(IN\) - - This is the channel the characters to process are read from\. - - This part of the machine's state is used and modified by the instructions - defined in the section [Input Handling](#subsection1)\. - - - *Current Character* \(CC\) - - The character from the *input* currently tested against its possible - alternatives\. - - This part of the machine's state is used and modified by the instructions - defined in the section [Character Processing](#subsection2)\. - - - *Current Location* \(CL\) - - The location of the *current character* in the *input*, as offset - relative to the beginning of the input\. Character offsets are counted from - __0__\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Character Processing](#subsection2), - [Location Handling](#subsection5), and [Nonterminal - Execution](#subsection6)\. - - - *Location Stack* \(LS\) - - A stack of locations in the *input*, saved for possible backtracking\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Character Processing](#subsection2), - [Location Handling](#subsection5), and [Nonterminal - Execution](#subsection6)\. - - - *Status* \(ST\) - - The status of the last attempt of testing the *input*, indicating either - success or failure\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Status Control](#subsection4), [Character - Processing](#subsection2), and [Nonterminal - Execution](#subsection6)\. - - - *Semantic Value* \(SV\) - - The current semantic value, either empty, or a node for AST constructed from - the input\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Value Construction](#subsection7), and [AST - Construction](#subsection8)\. - - - *AST Reduction Stack* \(ARS\) - - The stack of partial ASTs constructed during the processing of nonterminal - symbols\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Value Construction](#subsection7), and [AST - Construction](#subsection8)\. - - - *AST Stack* \(AS\) - - The stack of reduction stacks, saved for possible backtracking\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Value Construction](#subsection7), and [AST - Construction](#subsection8)\. - - - *Error Status* \(ER\) - - The machine's current knowledge of errors\. This is either empty, or set to a - pair of location in the input and the set of messages for that location\. - - *Note* that this part of the machine's state can be set even if the last - test of the *current character* was successful\. For example, the - \*\-operator \(matching a sub\-expression zero or more times\) in a PEG is always - successful, even if it encounters a problem further in the input and has to - backtrack\. Such problems must not be forgotten when continuing the parsing\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Error Handling](#subsection3), [Character - Processing](#subsection2), and [Nonterminal - Execution](#subsection6)\. - - - *Error Stack* \(ES\) - - The stack of error stati, saved for backtracking\. This enables the machine - to merge current and older error stati when performing backtracking in - choices after an failed match\. - - This part of the machine's state is used and modified by the instructions - defined in the sections [Error Handling](#subsection3), [Character - Processing](#subsection2), and [Nonterminal - Execution](#subsection6)\. - - - *Nonterminal Cache* \(NC\) - - A cache of machine states keyed by pairs name of nonterminal symbol and - location in the input\. Each pair \(N, L\) is associated with a 4\-tuple holding - the values to use for CL, ST, SV, and ER after the nonterminal N was parsed - starting from the location L\. It is a performance aid for backtracking - parsers, allowing them to avoid an expensive reparsing of complex - nonterminal symbols if they have been encountered before at a given - location\. - - The key location is where machine started the attempt to match the named - nonterminal symbol, and the location in the saved 4\-tuple is where machine - ended up after the attempt completed, independent of the success of the - attempt\. - - This part of the machine's state is used and modified by the instructions - defined in the section [Nonterminal Execution](#subsection6)\. - - - *Terminal Cache* \(TC\) - - A cache of characters read from IN, with their location in IN as pair of - line and column, keyed by the location in IN, this time as character offset - from the beginning of IN\. It is a performance aid for backtracking parsers, - allowing them to avoid a possibly expensive rereading of characters from IN, - or even enabling backtracking at, i\.e\. in the case of IN not randomly - seekable\. - - This part of the machine's state is used and modified by the instructions - defined in the section [Input Handling](#subsection1)\. - -# Instruction Set - -With the machine's architectural state specified it is now possible to specify -the instruction set operating on that state and to be implemented by any -realization of the PARAM\. The 37 instructions are grouped roughly by the state -they influence and/or query during their execution\. - -## Input Handling - -The instructions in this section mainly access IN, pulling the characters to -process into the machine\. - - - __input\_next__ *msg* - - This method reads the next character, i\.e\. the character after CL, from IN\. - If successful this character becomes CC, CL is advanced by one, ES is - cleared, and the operation is recorded as a success in ST\. - - The operation may read the character from IN if the next character is not - yet known to TC\. If successful the new character is stored in TC, with its - location \(line, column\), and the operation otherwise behaves as specified - above\. Future reads from the same location, possible due to backtracking, - will then be satisfied from TC instead of IN\. - - If, on the other hand, the end of IN was reached, the operation is recorded - as failed in ST, CL is left unchanged, and the pair of CL and *msg* - becomes the new ES\. - -## Character Processing - -The instructions in this section mainly access CC, testing it against character -classes, ranges, and individual characters\. - - - __test\_alnum__ - - This instruction implements the special PE operator "alnum", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_alpha__ - - This instruction implements the special PE operator "alpha", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_ascii__ - - This instruction implements the special PE operator "ascii", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_char__ *char* - - This instruction implements the character matching operator, i\.e\. it checks - if CC is *char*\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_ddigit__ - - This instruction implements the special PE operator "ddigit", which checks - if CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_digit__ - - This instruction implements the special PE operator "digit", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_graph__ - - This instruction implements the special PE operator "graph", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_lower__ - - This instruction implements the special PE operator "lower", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_print__ - - This instruction implements the special PE operator "print", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_punct__ - - This instruction implements the special PE operator "punct", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_range__ *chars* *chare* - - This instruction implements the range matching operator, i\.e\. it checks if - CC falls into the interval of characters spanned up by the two characters - from *chars* to *chare*, both inclusive\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_space__ - - This instruction implements the special PE operator "space", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_upper__ - - This instruction implements the special PE operator "upper", which checks if - CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_wordchar__ - - This instruction implements the special PE operator "wordchar", which checks - if CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - - - __test\_xdigit__ - - This instruction implements the special PE operator "xdigit", which checks - if CC falls into the character class of the same name, or not\. - - Success and failure of the test are both recorded directly in ST\. Success - further clears ES, wheras failure sets the pair of CL and expected input - \(encoded as a leaf parsing expression\) as the new ES and then rewinds CL by - one character, preparing the machine for another parse attempt by a possible - alternative\. - -## Error Handling - -The instructions in this section mainly access ER and ES\. - - - __error\_clear__ - - This instruction clears ER\. - - - __error\_push__ - - This instruction makes a copy of ER and pushes it on ES\. - - - __error\_pop\_merge__ - - This instruction takes the topmost entry of ES and merges the error status - it contains with ES, making the result the new ES\. - - The merge is governed by four rules, with the merge result - - 1. Empty if both states are empty\. - - 1. The non\-empty state if only one of the two states is non\-empty\. - - 1. The state with the larger location, if the two states specify different - locations\. - - 1. The pair of the location shared by the two states, and the set\-union of - their messages for states at the same location\. - - - __error\_nonterminal__ *symbol* - - This is a guarded instruction\. It does nothing if either ES is empty, or if - the location in ES is not just past the last location saved in LS\. Otherwise - it sets the pair of that location and the nonterminal *symbol* as the new - ES\. - - *Note*: In the above "just past" means "that location plus one", or also - "the location of the next character after that location"\. - -## Status Control - -The instructions in this section directly manipulate ST\. - - - __status\_ok__ - - This instruction sets ST to __true__, recording a success\. - - - __status\_fail__ - - This instruction sets ST to __false__, recording a failure\. - - - __status\_negate__ - - This instruction negates ST, turning a failure into a success and vice - versa\. - -## Location Handling - -The instructions in this section access CL and LS\. - - - __loc\_push__ - - This instruction makes a copy of CL and pushes it on LS\. - - - __loc\_pop\_discard__ - - This instructions pops the last saved location from LS\. - - - __loc\_pop\_rewind__ - - This instruction pops the last saved location from LS and restores it as CL\. - -## Nonterminal Execution - -The instructions in this section access and manipulate NC\. - - - __symbol\_restore__ *symbol* - - This instruction checks if NC contains data for the nonterminal *symbol* - at CL, or not\. The result of the instruction is a boolean flag, with - __True__ indicating that data was found in the cache\. In that case the - instruction has further updated the architectural state of the machine with - the cached information, namely CL, ST, ER, and SV\. - - The method with which the instruction's result is transformed into control - flow is left undefined and the responsibility of the implementation\. - - - __symbol\_save__ *symbol* - - This instructions saves the current settings of CL, ST, ER, and SV in NC, - using the pair of nonterminal *symbol* and the last location saved in LS - as key\. - -## Value Construction - -The instructions in this section manipulate SV\. - - - __value\_clear__ - - This instruction clears SV\. - - - __value\_leaf__ *symbol* - - This instruction constructs an AST node for *symbol* covering the range of - IN from one character after the last location saved on LS to CL and stores - it in SV\. \.\.\. - - - __value\_reduce__ *symbol* - - This instruction generally behaves like __value\_nonterminal\_leaf__, - except that it takes all AST nodes on ARS, if any, and makes them the - children of the new node, with the last node saved on ARS becoming the - right\-most / last child\. Note that ARS is not modfied by this operation\. - -## AST Construction - -The instructions in this section manipulate ARS and AS\. - - - __ast\_value\_push__ - - This instruction makes a copy of SV and pushes it on ARS\. - - - __ast\_push__ - - This instruction pushes the current state of ARS on AS and then clears ARS\. - - - __ast\_pop\_rewind__ - - This instruction pops the last entry saved on AS and restores it as the new - state of ARS\. - - - __ast\_pop\_discard__ - - This instruction pops the last entry saved on AS\. - -## Control Flow - -Normally this section would contain the specifications of the control flow -instructions of the PARAM, i\.e\. \(un\)conditional jumps and the like\. However, -this part of the PARAM is intentionally left unspecified\. This allows the -implementations to freely choose how to implement control flow\. - -The implementation of this machine in Parser Tools, i\.e the package -__[pt::rde](pt\_rdengine\.md)__, is not only coded in Tcl, but also relies -on Tcl commands to provide it with control flow \(instructions\)\. - -# Interaction of the Instructions with the Architectural State - - Instruction Inputs Outputs - ======================= ======================= ==================== - ast_pop_discard AS -> AS - ast_pop_rewind AS -> AS, ARS - ast_push ARS, AS -> AS - ast_value_push SV, ARS -> ARS - ======================= ======================= ==================== - error_clear - -> ER - error_nonterminal sym ER, LS -> ER - error_pop_merge ES, ER -> ER - error_push ES, ER -> ES - ======================= ======================= ==================== - input_next msg IN -> TC, CL, CC, ST, ER - ======================= ======================= ==================== - loc_pop_discard LS -> LS - loc_pop_rewind LS -> LS, CL - loc_push CL, LS -> LS - ======================= ======================= ==================== - status_fail - -> ST - status_negate ST -> ST - status_ok - -> ST - ======================= ======================= ==================== - symbol_restore sym NC -> CL, ST, ER, SV - symbol_save sym CL, ST, ER, SV LS -> NC - ======================= ======================= ==================== - test_alnum CC -> ST, ER - test_alpha CC -> ST, ER - test_ascii CC -> ST, ER - test_char char CC -> ST, ER - test_ddigit CC -> ST, ER - test_digit CC -> ST, ER - test_graph CC -> ST, ER - test_lower CC -> ST, ER - test_print CC -> ST, ER - test_punct CC -> ST, ER - test_range chars chare CC -> ST, ER - test_space CC -> ST, ER - test_upper CC -> ST, ER - test_wordchar CC -> ST, ER - test_xdigit CC -> ST, ER - ======================= ======================= ==================== - value_clear - -> SV - value_leaf symbol LS, CL -> SV - value_reduce symbol ARS, LS, CL -> SV - ======================= ======================= ==================== - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer), [virtual -machine](\.\./\.\./\.\./\.\./index\.md\#virtual\_machine) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_parse_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_parse_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_parse_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_parse_peg.md @@ -1,168 +0,0 @@ - -[//000000001]: # (pt\_parse\_peg \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_parse\_peg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_parse\_peg\(i\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_parse\_peg \- Parser Tools PEG Parser - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instances API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::parse::peg 1 - -[__pt::parse::peg__ ?*objectName*?](#1) -[*objectName* __destroy__](#2) -[*objectName* __parse__ *chan*](#3) -[*objectName* __parset__ *text*](#4) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a class whose instances are parsers for parsing expression -grammars in textual form\. - -# Class API - - - __pt::parse::peg__ ?*objectName*? - - The class command constructs parser instances, i\.e\. objects\. The result of - the command is the fully\-qualified name of the instance command\. - - If no *objectName* is specified the class will generate and use an - automatic name\. If the *objectName* was specified, but is not fully - qualified the command will be created in the current namespace\. - -# Instances API - -All parser instances provide at least the methods shown below: - - - *objectName* __destroy__ - - This method destroys the parser instance, releasing all claimed memory and - other resources, and deleting the instance command\. - - The result of the command is the empty string\. - - - *objectName* __parse__ *chan* - - This method runs the parser using the contents of *chan* as input - \(starting at the current location in the channel\), until parsing is not - possible anymore, either because parsing has completed, or run into a syntax - error\. - - Note here that the Parser Tools are based on Tcl 8\.5\+\. In other words, the - channel argument is not restricted to files, sockets, etc\. We have the full - power of *reflected channels* available\. - - It should also be noted that the parser pulls the characters from the input - stream as it needs them\. If a parser created by this package has to be - operated in a push aka event\-driven manner it will be necessary to go to Tcl - 8\.6\+ and use the __[coroutine::auto](\.\./coroutine/coro\_auto\.md)__ to - wrap it into a coroutine where __[read](\.\./\.\./\.\./\.\./index\.md\#read)__ - is properly changed for push\-operation\. - - Upon successful completion the command returns an abstract syntax tree as - its result\. This AST is in the form specified in section __AST - serialization format__\. As a plain nested Tcl\-list it can then be - processed with any Tcl commands the user likes, doing transformations, - semantic checks, etc\. To help in this the package - __[pt::ast](pt\_astree\.md)__ provides a set of convenience commands - for validation of the tree's basic structure, printing it for debugging, and - walking it either from the bottom up, or top down\. - - When encountering a syntax error the command will throw an error instead\. - This error will be a 4\-element Tcl\-list, containing, in the order listed - below: - - 1. The string __pt::rde__ identifying it as parser runtime error\. - - 1. The location of the parse error, as character offset from the beginning - of the parsed input\. - - 1. The location of parse error, now as a 2\-element list containing - line\-number and column in the line\. - - 1. A set of atomic parsing expressions indicating encoding the characters - and/or nonterminal symbols the parser expected to see at the location - of the parse error, but did not get\. For the specification of atomic - parsing expressions please see the section __PE serialization - format__\. - - - *objectName* __parset__ *text* - - This method runs the parser using the string in *text* as input\. In all - other ways it behaves like the method __parse__, shown above\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_parser_api.md Index: embedded/md/tcllib/files/modules/pt/pt_parser_api.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_parser_api.md +++ embedded/md/tcllib/files/modules/pt/pt_parser_api.md @@ -1,444 +0,0 @@ - -[//000000001]: # (pt\_parser\_api \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_parser\_api\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_parser\_api\(i\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_parser\_api \- Parser API - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instance API](#section3) - - - [Usage](#section4) - - - [AST serialization format](#section5) - - - [Example](#subsection1) - - - [PE serialization format](#section6) - - - [Example](#subsection2) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -[__className__ ?*objectName*?](#1) -[*objectName* __destroy__](#2) -[*objectName* __parse__ *chan*](#3) -[*objectName* __parset__ *text*](#4) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This document describes the API shared by the grammar interpreter provided by -the package __[pt::peg::interp](pt\_peg\_interp\.md)__ and the parsers -generated by the __[pt](\.\./\.\./apps/pt\.md)__ application for the result -formats __critcl__, __snit__, and __oo__ regarding access to the -actual parsing functionality\. - -Its intended audience are people who wish to create a parser for some language -of theirs and then use that parser within a Tcl\-based package or application\. - -It resides in the User Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_user\_pkg\.png) - -# Class API - - - __className__ ?*objectName*? - - The class command constructs parser instances, i\.e\. objects\. The result of - the command is the fully\-qualified name of the instance command\. - - If no *objectName* is specified the class will generate and use an - automatic name\. If the *objectName* was specified, but is not fully - qualified the command will be created in the current namespace\. - -# Instance API - -All parser instances provide at least the methods shown below: - - - *objectName* __destroy__ - - This method destroys the parser instance, releasing all claimed memory and - other resources, and deleting the instance command\. - - The result of the command is the empty string\. - - - *objectName* __parse__ *chan* - - This method runs the parser using the contents of *chan* as input - \(starting at the current location in the channel\), until parsing is not - possible anymore, either because parsing has completed, or run into a syntax - error\. - - Note here that the Parser Tools are based on Tcl 8\.5\+\. In other words, the - channel argument is not restricted to files, sockets, etc\. We have the full - power of *reflected channels* available\. - - It should also be noted that the parser pulls the characters from the input - stream as it needs them\. If a parser created by this package has to be - operated in a push aka event\-driven manner it will be necessary to go to Tcl - 8\.6\+ and use the __[coroutine::auto](\.\./coroutine/coro\_auto\.md)__ to - wrap it into a coroutine where __[read](\.\./\.\./\.\./\.\./index\.md\#read)__ - is properly changed for push\-operation\. - - Upon successful completion the command returns an abstract syntax tree as - its result\. This AST is in the form specified in section [AST serialization - format](#section5)\. As a plain nested Tcl\-list it can then be processed - with any Tcl commands the user likes, doing transformations, semantic - checks, etc\. To help in this the package __[pt::ast](pt\_astree\.md)__ - provides a set of convenience commands for validation of the tree's basic - structure, printing it for debugging, and walking it either from the bottom - up, or top down\. - - When encountering a syntax error the command will throw an error instead\. - This error will be a 4\-element Tcl\-list, containing, in the order listed - below: - - 1. The string __pt::rde__ identifying it as parser runtime error\. - - 1. The location of the parse error, as character offset from the beginning - of the parsed input\. - - 1. The location of parse error, now as a 2\-element list containing - line\-number and column in the line\. - - 1. A set of atomic parsing expressions indicating encoding the characters - and/or nonterminal symbols the parser expected to see at the location - of the parse error, but did not get\. For the specification of atomic - parsing expressions please see the section [PE serialization - format](#section6)\. - - - *objectName* __parset__ *text* - - This method runs the parser using the string in *text* as input\. In all - other ways it behaves like the method __parse__, shown above\. - -# Usage - -A generated parser is used like this - - package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'. - set parser [the-parser-class] - - set ast [$parser parse $channel] - ... process the abstract syntax tree ... - -When using a grammar interpreter for parsing some differences creep in - - package require the-grammar-package ;# Generated by result-format 'container' of 'pt'. - set grammar [the-grammar-class] - - package require pt::peg::interp - set parser [pt::peg::interp] - - $parser use $grammar - - set ast [$parser parse $channel] - $parser destroy - - ... process the abstract syntax tree ... - -# AST serialization format - -Here we specify the format used by the Parser Tools to serialize Abstract Syntax -Trees \(ASTs\) as immutable values for transport, comparison, etc\. - -Each node in an AST represents a nonterminal symbol of a grammar, and the range -of tokens/characters in the input covered by it\. ASTs do not contain terminal -symbols, i\.e\. tokens/characters\. These can be recovered from the input given a -symbol's location\. - -We distinguish between *regular* and *canonical* serializations\. While a -tree may have more than one regular serialization only exactly one of them will -be *canonical*\. - - - Regular serialization - - 1. The serialization of any AST is the serialization of its root node\. - - 1. The serialization of any node is a Tcl list containing at least three - elements\. - - 1) The first element is the name of the nonterminal symbol stored in - the node\. - - 1) The second and third element are the locations of the first and - last token in the token stream the node represents \(covers\)\. - - 1. Locations are provided as non\-negative integer offsets from - the beginning of the token stream, with the first token found - in the stream located at offset 0 \(zero\)\. - - 1. The end location has to be equal to or larger than the start - location\. - - 1) All elements after the first three represent the children of the - node, which are themselves nodes\. This means that the - serializations of nodes without children, i\.e\. leaf nodes, have - exactly three elements\. The children are stored in the list with - the leftmost child first, and the rightmost child last\. - - - Canonical serialization - - The canonical serialization of an abstract syntax tree has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this tree\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the parsing expression grammar below - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -and the input string - - 120+5 - -then a parser should deliver the abstract syntax tree below \(except for -whitespace\) - - set ast {Expression 0 4 - {Factor 0 4 - {Term 0 2 - {Number 0 2 - {Digit 0 0} - {Digit 1 1} - {Digit 2 2} - } - } - {AddOp 3 3} - {Term 4 4 - {Number 4 4 - {Digit 4 4} - } - } - } - } - -Or, more graphical - -![](\.\./\.\./\.\./\.\./image/expr\_ast\.png) - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_container.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_container.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_container.md @@ -1,681 +0,0 @@ - -[//000000001]: # (pt::peg::container \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_container\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::container\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::container \- PEG Storage - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#subsection1) - - - [Object API](#subsection2) - - - [PEG serialization format](#section2) - - - [Example](#subsection3) - - - [PE serialization format](#section3) - - - [Example](#subsection4) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit -package require pt::peg::container ?1? - -[__::pt::peg__ *objectName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*?](#1) -[*objectName* __destroy__](#2) -[*objectName* __clear__](#3) -[*objectName* __importer__](#4) -[*objectName* __importer__ *object*](#5) -[*objectName* __exporter__](#6) -[*objectName* __exporter__ *object*](#7) -[*objectName* __=__ *source*](#8) -[*objectName* __\-\->__ *destination*](#9) -[*objectName* __serialize__ ?*format*?](#10) -[*objectName* __deserialize =__ *data* ?*format*?](#11) -[*objectName* __deserialize \+=__ *data* ?*format*?](#12) -[*objectName* __start__](#13) -[*objectName* __start__ *pe*](#14) -[*objectName* __nonterminals__](#15) -[*objectName* __modes__](#16) -[*objectName* __modes__ *dict*](#17) -[*objectName* __rules__](#18) -[*objectName* __rules__ *dict*](#19) -[*objectName* __add__ ?*nt*\.\.\.?](#20) -[*objectName* __remove__ ?*nt*\.\.\.?](#21) -[*objectName* __exists__ *nt*](#22) -[*objectName* __rename__ *ntold* *ntnew*](#23) -[*objectName* __mode__ *nt*](#24) -[*objectName* __mode__ *nt* *mode*](#25) -[*objectName* __rule__ *nt*](#26) -[*objectName* __rule__ *nt* *pe*](#27) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a container class for parsing expression grammars, with -each instance storing a single grammar and allowing the user to manipulate and -query its definition\. - -It resides in the Storage section of the Core Layer of Parser Tools, and is one -of the three pillars the management of parsing expression grammars resides on\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_container\.png) The other two pillars are, -as shown above - - 1. *[PEG Import](pt\_peg\_import\.md)*, and - - 1. *[PEG Export](pt\_peg\_export\.md)* - -Packages related to this are: - - - __[pt::rde](pt\_rdengine\.md)__ - - This package provides an implementation of PARAM, a virtual machine for the - parsing of a channel, geared towards the needs of handling PEGs\. - - - __[pt::peg::interp](pt\_peg\_interp\.md)__ - - This package implements an interpreter for PEGs on top of the virtual - machine provided by __pt::peg::rde__ - -## Class API - -The package exports the API described here\. - - - __::pt::peg__ *objectName* ?__=__|__:=__|__<\-\-__|__as__|__deserialize__ *src*? - - The command creates a new container object for a parsing expression grammar - and returns the fully qualified name of the object command as its result\. - The API of this object command is described in the section [Object - API](#subsection2)\. It may be used to invoke various operations on the - object\. - - The new container will be empty if no *src* is specified\. Otherwise it - will contain a copy of the grammar contained in the *src*\. All operators - except __deserialize__ interpret *src* as a container object command\. - The __deserialize__ operator interprets *src* as the serialization of - a parsing expression grammar instead, as specified in section [PEG - serialization format](#section2)\. - - An empty grammar has no nonterminal symbols, and the start expression is the - empty expression, i\.e\. epsilon\. It is *valid*, but not *useful*\. - -## Object API - -All objects created by this package provide the following methods for the -manipulation and querying of their contents: - - - *objectName* __destroy__ - - This method destroys the object, releasing all claimed memory, and deleting - the associated object command\. - - - *objectName* __clear__ - - This method resets the object to contain the empty grammar\. It does *not* - destroy the object itself\. - - - *objectName* __importer__ - - This method returns the import manager object currently attached to the - container, if any\. - - - *objectName* __importer__ *object* - - This method attaches the *object* as import manager to the container, and - returns it as the result of the command\. Note that the *object* is *not* - put into ownership of the container\. I\.e\., destruction of the container will - *not* destroy the *object*\. - - It is expected that *object* provides a method named __import text__ - which takes a text and a format name, and returns the canonical - serialization of the table of contents contained in the text, assuming the - given format\. - - - *objectName* __exporter__ - - This method returns the export manager object currently attached to the - container, if any\. - - - *objectName* __exporter__ *object* - - This method attaches the *object* as export manager to the container, and - returns it as the result of the command\. Note that the *object* is *not* - put into ownership of the container\. I\.e\., destruction of the container will - *not* destroy the *object*\. - - It is expected that *object* provides a method named __export object__ - which takes the container and a format name, and returns a text encoding - table of contents stored in the container, in the given format\. It is - further expected that the *object* will use the container's method - __serialize__ to obtain the serialization of the table of contents from - which to generate the text\. - - - *objectName* __=__ *source* - - This method assigns the contents of the PEG object *source* to ourselves, - overwriting the existing definition\. This is the assignment operator for - grammars\. - - This operation is in effect equivalent to - - > *objectName* __deserialize =__ \[*source* __serialize__\] - - - *objectName* __\-\->__ *destination* - - This method assigns our contents to the PEG object *destination*, - overwriting the existing definition\. This is the reverse assignment operator - for grammars\. - - This operation is in effect equivalent to - - > *destination* __deserialize =__ \[*objectName* __serialize__\] - - - *objectName* __serialize__ ?*format*? - - This method returns our grammar in some textual form usable for transfer, - persistent storage, etc\. If no *format* is not specified the returned - result is the canonical serialization of the grammar, as specified in the - section [PEG serialization format](#section2)\. - - Otherwise the object will use the attached export manager to convert the - data to the specified format\. In that case the method will fail with an - error if the container has no export manager attached to it\. - - - *objectName* __deserialize =__ *data* ?*format*? - - This is the complementary method to __serialize__\. It replaces the - current definition with the grammar contained in the *data*\. If no - *format* was specified it is assumed to be the regular serialization of a - grammar, as specified in the section [PEG serialization - format](#section2) - - Otherwise the object will use the attached import manager to convert the - data from the specified format to a serialization it can handle\. In that - case the method will fail with an error if the container has no import - manager attached to it\. - - The result of the method is the empty string\. - - - *objectName* __deserialize \+=__ *data* ?*format*? - - This method behaves like __deserialize =__ in its essentials, except - that it merges the grammar in the *data* to its contents instead of - replacing it\. The method will fail with an error and leave the grammar - unchanged if merging is not possible, i\.e\. would produce an invalid grammar\. - - The result of the method is the empty string\. - - - *objectName* __start__ - - This method returns the current start expression of the grammar\. - - - *objectName* __start__ *pe* - - This method defines the *start expression* of the grammar\. It replaces the - current start expression with the parsing expression *pe*, and returns the - new start expression\. - - The method will fail with an error and leave the grammar unchanged if *pe* - does not contain a valid parsing expression as specified in the section [PE - serialization format](#section3)\. - - - *objectName* __nonterminals__ - - This method returns the set of all nonterminal symbols known to the grammar\. - - - *objectName* __modes__ - - This method returns a dictionary mapping the set of all nonterminal symbols - known to the grammar to their semantic modes\. - - - *objectName* __modes__ *dict* - - This method takes a dictionary mapping a set of nonterminal symbols known to - the grammar to their semantic modes, and returns the new full mapping of - nonterminal symbols to semantic modes\. - - The method will fail with an error if any of the nonterminal symbols in the - dictionary is not known to the grammar, or the empty string, i\.e\. an invalid - nonterminal symbol, or if any the chosen *mode*s is not one of the legal - values\. - - - *objectName* __rules__ - - This method returns a dictionary mapping the set of all nonterminal symbols - known to the grammar to their parsing expressions \(right\-hand sides\)\. - - - *objectName* __rules__ *dict* - - This method takes a dictionary mapping a set of nonterminal symbols known to - the grammar to their parsing expressions \(right\-hand sides\), and returns the - new full mapping of nonterminal symbols to parsing expressions\. - - The method will fail with an error any of the nonterminal symbols in the - dictionary is not known to the grammar, or the empty string, i\.e\. an invalid - nonterminal symbol, or any of the chosen parsing expressions is not a valid - parsing expression as specified in the section [PE serialization - format](#section3)\. - - - *objectName* __add__ ?*nt*\.\.\.? - - This method adds the nonterminal symbols *nt*, etc\. to the grammar, and - defines default semantic mode and expression for it \(__value__ and - __epsilon__ respectively\)\. The method returns the empty string as its - result\. - - The method will fail with an error and leaves the grammar unchanged if any - of the nonterminal symbols are either already defined in our grammar, or are - the empty string \(an invalid nonterminal symbol\)\. - - The method does nothing if no symbol was specified as argument\. - - - *objectName* __remove__ ?*nt*\.\.\.? - - This method removes the named nonterminal symbols *nt*, etc\. from the set - of nonterminal symbols known to our grammar\. The method returns the empty - string as its result\. - - The method will fail with an error and leave the grammar unchanged if any of - the nonterminal symbols is not known to the grammar, or is the empty string, - i\.e\. an invalid nonterminal symbol\. - - - *objectName* __exists__ *nt* - - This method tests whether the nonterminal symbol *nt* is known to our - grammar or not\. The result is a boolean value\. It will be set to - __true__ if *nt* is known, and __false__ otherwise\. - - The method will fail with an error if *nt* is the empty string, i\.e\. an - invalid nonterminal symbol\. - - - *objectName* __rename__ *ntold* *ntnew* - - This method renames the nonterminal symbol *ntold* to *ntnew*\. The - method returns the empty string as its result\. - - The method will fail with an error and leave the grammar unchanged if either - *ntold* is not known to the grammar, or *ntnew* is already known, or any - of them is the empty string, i\.e\. an invalid nonterminal symbol\. - - - *objectName* __mode__ *nt* - - This method returns the current semantic mode for the nonterminal symbol - *nt*\. - - The method will fail with an error if *nt* is not known to the grammar, or - the empty string, i\.e\. an invalid nonterminal symbol\. - - - *objectName* __mode__ *nt* *mode* - - This mode sets the semantic mode for the nonterminal symbol *nt*, and - returns the new mode\. The method will fail with an error if *nt* is not - known to the grammar, or the empty string, i\.e\. an invalid nonterminal - symbol, or the chosen *mode* is not one of the legal values\. - - The following modes are legal: - - * __value__ - - The semantic value of the nonterminal symbol is an abstract syntax tree - consisting of a single node node for the nonterminal itself, which has - the ASTs of the symbol's right hand side as its children\. - - * __leaf__ - - The semantic value of the nonterminal symbol is an abstract syntax tree - consisting of a single node node for the nonterminal, without any - children\. Any ASTs generated by the symbol's right hand side are - discarded\. - - * __void__ - - The nonterminal has no semantic value\. Any ASTs generated by the - symbol's right hand side are discarded \(as well\)\. - - - *objectName* __rule__ *nt* - - This method returns the current parsing expression \(right\-hand side\) for the - nonterminal symbol *nt*\. - - The method will fail with an error if *nt* is not known to the grammar, or - the empty string, i\.e\. an invalid nonterminal symbol\. - - - *objectName* __rule__ *nt* *pe* - - This method set the parsing expression \(right\-hand side\) of the nonterminal - *nt* to *pe*, and returns the new parsing expression\. - - The method will fail with an error if *nt* is not known to the grammar, or - the empty string, i\.e\. an invalid nonterminal symbol, or *pe* does not - contain a valid parsing expression as specified in the section [PE - serialization format](#section3)\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section3)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section3)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_container_peg.md @@ -1,95 +0,0 @@ - -[//000000001]: # (pt::peg::container::peg \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_container\_peg\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::container::peg\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::container::peg \- PEG Storage\. Canned PEG grammar specification - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit -package require pt::peg::container::peg ?1? -package require pt::peg::container - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a sub\-type of -__[pt::peg::container](pt\_peg\_container\.md)__ which is preloaded with a -parsing expression grammar describing a textual format for parsing expression -grammars\. - -The sub\-type provides the exact same API as -__[pt::peg::container](pt\_peg\_container\.md)__\. Instead of duplicating -its contents the reader is asked to read the referenced document\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_export.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_export.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_export.md @@ -1,524 +0,0 @@ - -[//000000001]: # (pt::peg::export \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_export\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::export\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::export \- PEG Export - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [PEG serialization format](#section3) - - - [Example](#subsection4) - - - [PE serialization format](#section4) - - - [Example](#subsection5) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit -package require struct::map -package require pt::peg -package require pluginmgr -package require pt::peg::export ?1\.0\.1? - -[__::pt::peg::export__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __export serial__ *serial* ?*format*?](#4) -[*objectName* __export object__ *object* ?*format*?](#5) -[*objectName* __configuration names__](#6) -[*objectName* __configuration get__](#7) -[*objectName* __configuration set__ *name* ?*value*?](#8) -[*objectName* __configuration unset__ *pattern*\.\.\.](#9) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a manager for parsing expression grammars, with each -instance handling a set of plugins for the export of them to other formats, i\.e\. -their conversion to, for example *[nroff](\.\./\.\./\.\./\.\./index\.md\#nroff)*, -*[HTML](\.\./\.\./\.\./\.\./index\.md\#html)*, etc\. - -It resides in the Export section of the Core Layer of Parser Tools, and is one -of the three pillars the management of parsing expression grammars resides on\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_export\.png) The other two pillars are, as -shown above - - 1. *[PEG Import](pt\_peg\_import\.md)*, and - - 1. *[PEG Storage](pt\_peg\_container\.md)* - -For information about the data structure which is the major input to the manager -objects provided by this package see the section [PEG serialization -format](#section3)\. - -The plugin system of this class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __GRAMMAR\_PEG\_EXPORT\_PLUGINS__, - - 1. the environment variable __GRAMMAR\_PEG\_PLUGINS__, - - 1. the environment variable __GRAMMAR\_PLUGINS__, - - 1. the path "~/\.grammar/peg/export/plugin" - - 1. the path "~/\.grammar/peg/plugin" - - 1. the path "~/\.grammar/plugin" - - 1. the path "~/\.grammar/peg/export/plugins" - - 1. the path "~/\.grammar/peg/plugins" - - 1. the path "~/\.grammar/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PEG\\EXPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PEG\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PLUGINS" - -The last three are used only when the package is run on a machine using the -Windows\(tm\) operating system\. - -The whole system is delivered with three predefined export plugins, namely - - - container - - See *PEG Export Plugin\. To CONTAINER format* for details\. - - - json - - See *PEG Export Plugin\. To JSON format* for details\. - - - peg - - See *PEG Export Plugin\. To PEG format* for details\. - -For readers wishing to write their own export plugin for some format, i\.e\. -*plugin writer*s, reading and understanding the *[Parser Tools Export -API](pt\_to\_api\.md)* specification is an absolute necessity, as it documents -the interaction between this package and its plugins in detail\. - -# API - -## Package commands - - - __::pt::peg::export__ *objectName* - - This command creates a new export manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## Object command - -All objects created by the __::pt::peg::export__ command have the following -general form: - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __export serial__ *serial* ?*format*? - - This method takes the canonical serialization of a parsing expression - grammar stored in *serial* and converts it to the specified *format*, - using the export plugin for the format\. This will fail with an error if no - plugin could be found for the format\. The string generated by the conversion - process is returned as the result of this method\. - - If no format is specified the method defaults to __text__\. - - The specification of what a *canonical* serialization is can be found in - the section [PEG serialization format](#section3)\. - - The plugin has to conform to the interface documented in the *[Parser - Tools Export API](pt\_to\_api\.md)* specification\. - - - *objectName* __export object__ *object* ?*format*? - - This method is a convenient wrapper around the __export serial__ method - described by the previous item\. It expects that *object* is an object - command supporting a __serialize__ method returning the canonical - serialization of a parsing expression grammar\. It invokes that method, feeds - the result into __export serial__ and returns the resulting string as - its own result\. - - - *objectName* __configuration names__ - - This method returns a list containing the names of all configuration options - currently known to the object\. - - - *objectName* __configuration get__ - - This method returns a dictionary containing the names and values of all - configuration options currently known to the object\. - - - *objectName* __configuration set__ *name* ?*value*? - - This method sets the configuration option *name* to the specified - *value* and returns the new value of the option\. - - If no value is specified it simply returns the current value, without - changing it\. - - Note that these configuration options and their values are simply passed to - a plugin when the actual export is performed\. It is the plugin which checks - the validity, not the manager\. - - - *objectName* __configuration unset__ *pattern*\.\.\. - - This method unsets all configuration options matching the specified glob - *pattern*s\. If no pattern is specified it will unset all currently defined - configuration options\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section4)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section4)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_container.md @@ -1,535 +0,0 @@ - -[//000000001]: # (pt::peg::export::container \- Parser Tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::export::container\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::export::container \- PEG Export Plugin\. Write CONTAINER format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [Grammar Container](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::export::container ?1? -package require pt::peg::to::container - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the parsing expression grammar export plugin for the -generation of CONTAINER markup\. - -It resides in the Export section of the Core Layer of Parser Tools and is -intended to be used by __[pt::peg::export](pt\_peg\_export\.md)__, the -export manager, sitting between it and the corresponding core conversion -functionality provided by -__[pt::peg::to::container](pt\_peg\_to\_container\.md)__\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -While the direct use of this package with a regular interpreter is possible, -this is strongly disrecommended and requires a number of contortions to provide -the expected environment\. The proper way to use this functionality depends on -the situation: - - 1. In an untrusted environment the proper access is through the package - __[pt::peg::export](pt\_peg\_export\.md)__ and the export manager - objects it provides\. - - 1. In a trusted environment however simply use the package - __[pt::peg::to::container](pt\_peg\_to\_container\.md)__ and access the - core conversion functionality directly\. - -# API - -The API provided by this package satisfies the specification of the Plugin API -found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates CONTAINER markup encoding the grammar\. The created string is then - returned as the result of the command\. - -# Configuration - -The CONTAINER export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - enum *mode* - - The value of this configuration variable controls which methods of - __[pt::peg](pt\_pegrammar\.md)__ instances the plugin will use to - specify the grammar\. There are two legal values - - * __bulk__ - - In this mode the methods __start__, __add__, __modes__, and - __rules__ are used to specify the grammar in a bulk manner, i\.e\. as - a set of nonterminal symbols, and two dictionaries mapping from the - symbols to their semantic modes and parsing expressions\. - - This mode is the default\. - - * __incremental__ - - In this mode the methods __start__, __add__, __mode__, and - __rule__ are used to specify the grammar piecemal, with each - nonterminal having its own block of defining commands\. - - - string *template* - - If this configuration variable is set it is assumed to contain a string into - which to put the generated code and other configuration data\. The various - locations are expected to be specified with the following placeholders: - - * __@user@__ - - To be replaced with the value of the configuration variable - __user__\. - - * __@format@__ - - To be replaced with the the constant __CONTAINER__\. - - * __@file@__ - - To be replaced with the value of the configuration variable - __file__\. - - * __@name@__ - - To be replaced with the value of the configuration variable - __name__\. - - * __@mode@__ - - To be replaced with the value of the configuration variable - __mode__\. - - * __@code@__ - - To be replaced with the generated code\. - - If this configuration variable is not set, or empty, then the plugin falls - back to a standard template, which is defined as "__@code@__"\. - -*Note* that this plugin may ignore the standard configuration variables -__user__, __format__, __file__, and their values, depending on the -chosen template\. - -The content of the standard configuration variable __name__, if set, is used -as name of the grammar in the output\. Otherwise the plugin falls back to the -default name __a\_pe\_grammar__\. - -# Grammar Container - -The __container__ format is another form of describing parsing expression -grammars\. While data in this format is executable it does not constitute a -parser for the grammar\. It always has to be used in conjunction with the package -__[pt::peg::interp](pt\_peg\_interp\.md)__, a grammar interpreter\. - -The format represents grammars by a __snit::type__, i\.e\. class, whose -instances are API\-compatible to the instances of the -__[pt::peg::container](pt\_peg\_container\.md)__ package, and which are -preloaded with the grammar in question\. - -It has no direct formal specification beyond what was said above\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -one possible CONTAINER serialization for it is - - snit::type a_pe_grammar { - constructor {} { - install myg using pt::peg::container ${selfns}::G - $myg start {n Expression} - $myg add AddOp Digit Expression Factor MulOp Number Sign Term - $myg modes { - AddOp value - Digit value - Expression value - Factor value - MulOp value - Number value - Sign value - Term value - } - $myg rules { - AddOp {/ {t -} {t +}} - Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} - Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}} - Factor {x {n Term} {* {x {n AddOp} {n Term}}}} - MulOp {/ {t *} {t /}} - Number {x {? {n Sign}} {+ {n Digit}}} - Sign {/ {t -} {t +}} - Term {n Number} - } - return - } - - component myg - delegate method * to myg - } - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[CONTAINER](\.\./\.\./\.\./\.\./index\.md\#container), -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_json.md @@ -1,580 +0,0 @@ - -[//000000001]: # (pt::peg::export::json \- Parser Tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::export::json\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::export::json \- PEG Export Plugin\. Write JSON format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [JSON Grammar Exchange Format](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::export::json ?1? -package require pt::peg::to::json - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the parsing expression grammar export plugin for the -generation of JSON markup\. - -It resides in the Export section of the Core Layer of Parser Tools and is -intended to be used by __[pt::peg::export](pt\_peg\_export\.md)__, the -export manager, sitting between it and the corresponding core conversion -functionality provided by __[pt::peg::to::json](pt\_peg\_to\_json\.md)__\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -While the direct use of this package with a regular interpreter is possible, -this is strongly disrecommended and requires a number of contortions to provide -the expected environment\. The proper way to use this functionality depends on -the situation: - - 1. In an untrusted environment the proper access is through the package - __[pt::peg::export](pt\_peg\_export\.md)__ and the export manager - objects it provides\. - - 1. In a trusted environment however simply use the package - __[pt::peg::to::json](pt\_peg\_to\_json\.md)__ and access the core - conversion functionality directly\. - -# API - -The API provided by this package satisfies the specification of the Plugin API -found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates JSON markup encoding the grammar\. The created string is then - returned as the result of the command\. - -# Configuration - -The JSON export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - boolean *indented* - - If this flag is set the plugin will break the generated JSON code across - lines and indent it according to its inner structure, with each key of a - dictionary on a separate line\. - - If this flag is not set \(the default\), the whole JSON object will be written - on a single line, with minimum spacing between all elements\. - - - boolean *aligned* - - If this flag is set the generator ensures that the values for the keys in a - dictionary are vertically aligned with each other, for a nice table effect\. - To make this work this also implies that __indented__ is set\. - - If this flag is not set \(the default\), the output is formatted as per the - value of __indented__, without trying to align the values for dictionary - keys\. - -*Note* that this plugin ignores the standard configuration variables -__user__, __format__, __file__, and __name__, and their values\. - -# JSON Grammar Exchange Format - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -It is formally specified by the rules below: - - 1. The JSON of any PEG is a JSON object\. - - 1. This object holds a single key, __pt::grammar::peg__, and its value\. - This value holds the contents of the grammar\. - - 1. The contents of the grammar are a JSON object holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - - __rules__ - - The value is a JSON object whose keys are the names of the nonterminal - symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a JSON object itself\. The relevant - keys and their values in this dictionary are - - * __is__ - - The value is a JSON string holding the Tcl serialization of - the parsing expression describing the symbols sentennial - structure, as specified in the section [PE serialization - format](#section6)\. - - * __mode__ - - The value is a JSON holding holding one of three values - specifying how a parser should handle the semantic value - produced by the symbol\. - - + __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal itself, which has the ASTs of the symbol's - right hand side as its children\. - - + __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal, without any children\. Any ASTs generated - by the symbol's right hand side are discarded\. - - + __void__ - - The nonterminal has no semantic value\. Any ASTs generated - by the symbol's right hand side are discarded \(as well\)\. - - - __start__ - - The value is a JSON string holding the Tcl serialization of the start - parsing expression of the grammar, as specified in the section [PE - serialization format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set of - all terminal symbols used in the start expression and on the RHS of the - grammar rules\. - -As an aside to the advanced reader, this is pretty much the same as the Tcl -serialization of PE grammars, as specified in section [PEG serialization -format](#section5), except that the Tcl dictionaries and lists of that -format are mapped to JSON objects and arrays\. Only the parsing expressions -themselves are not translated further, but kept as JSON strings containing a -nested Tcl list, and there is no concept of canonicity for the JSON either\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -a JSON serialization for it is - - { - "pt::grammar::peg" : { - "rules" : { - "AddOp" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Digit" : { - "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", - "mode" : "value" - }, - "Expression" : { - "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", - "mode" : "value" - }, - "Factor" : { - "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", - "mode" : "value" - }, - "MulOp" : { - "is" : "\/ {t *} {t \/}", - "mode" : "value" - }, - "Number" : { - "is" : "x {? {n Sign}} {+ {n Digit}}", - "mode" : "value" - }, - "Sign" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Term" : { - "is" : "n Number", - "mode" : "value" - } - }, - "start" : "n Expression" - } - } - -and a Tcl serialization of the same is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -The similarity of the latter to the JSON should be quite obvious\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_export_peg.md @@ -1,576 +0,0 @@ - -[//000000001]: # (pt::peg::export::peg \- Parser Tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::export::peg\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::export::peg \- PEG Export Plugin\. Write PEG format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Configuration](#section3) - - - [PEG Specification Language](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::export::peg ?1? -package require pt::peg::to::peg - -[__[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the parsing expression grammar export plugin for the -generation of PEG markup\. - -It resides in the Export section of the Core Layer of Parser Tools and is -intended to be used by __[pt::peg::export](pt\_peg\_export\.md)__, the -export manager, sitting between it and the corresponding core conversion -functionality provided by __[pt::peg::to::peg](pt\_peg\_to\_peg\.md)__\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -While the direct use of this package with a regular interpreter is possible, -this is strongly disrecommended and requires a number of contortions to provide -the expected environment\. The proper way to use this functionality depends on -the situation: - - 1. In an untrusted environment the proper access is through the package - __[pt::peg::export](pt\_peg\_export\.md)__ and the export manager - objects it provides\. - - 1. In a trusted environment however simply use the package - __[pt::peg::to::peg](pt\_peg\_to\_peg\.md)__ and access the core - conversion functionality directly\. - -# API - -The API provided by this package satisfies the specification of the Plugin API -found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__ *serial* *configuration* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, the *configuration*, a dictionary, and - generates PEG markup encoding the grammar\. The created string is then - returned as the result of the command\. - -# Configuration - -The PEG export plugin recognizes the following configuration variables and -changes its behaviour as they specify\. - - - string *template* - - If this configuration variable is set it is assumed to contain a string into - which to put the generated text and other configuration data\. The various - locations are expected to be specified with the following placeholders: - - * __@user@__ - - To be replaced with the value of the configuration variable - __user__\. - - * __@format@__ - - To be replaced with the the constant __PEG__\. - - * __@file@__ - - To be replaced with the value of the configuration variable - __file__\. - - * __@name@__ - - To be replaced with the value of the configuration variable - __name__\. - - * __@code@__ - - To be replaced with the generated text\. - - If this configuration variable is not set, or empty, then the plugin falls - back to a standard template, which is defined as "__@code@__"\. - -*Note* that this plugin may ignore the standard configuration variables -__user__, __format__, __file__, and their values, depending on the -chosen template\. - -The content of the standard configuration variable __name__, if set, is used -as name of the grammar in the output\. Otherwise the plugin falls back to the -default name __a\_pe\_grammar__\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -It is formally specified by the grammar shown below, written in itself\. For a -tutorial / introduction to the language please go and read the *[PEG Language -Tutorial](pt\_peg\_language\.md)*\. - - PEG pe-grammar-for-peg (Grammar) - - # -------------------------------------------------------------------- - # Syntactical constructs - - Grammar <- WHITESPACE Header Definition* Final EOF ; - - Header <- PEG Identifier StartExpr ; - Definition <- Attribute? Identifier IS Expression SEMICOLON ; - Attribute <- (VOID / LEAF) COLON ; - Expression <- Sequence (SLASH Sequence)* ; - Sequence <- Prefix+ ; - Prefix <- (AND / NOT)? Suffix ; - Suffix <- Primary (QUESTION / STAR / PLUS)? ; - Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT - / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER - / WORDCHAR / XDIGIT - / Identifier - / OPEN Expression CLOSE - / Literal - / Class - / DOT - ; - Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE - / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; - Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; - Range <- Char TO Char / Char ; - - StartExpr <- OPEN Expression CLOSE ; - void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; - - # -------------------------------------------------------------------- - # Lexing constructs - - Identifier <- Ident WHITESPACE ; - leaf: Ident <- ([_:] / ) ([_:] / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - - leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; - leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; - leaf: CharOctalPart <- "\\" [0-7][0-7]? ; - leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; - leaf: CharUnescaped <- !"\\" . ; - - void: HexDigit <- [0-9a-fA-F] ; - - void: TO <- '-' ; - void: OPENB <- "[" ; - void: CLOSEB <- "]" ; - void: APOSTROPH <- "'" ; - void: DAPOSTROPH <- '"' ; - void: PEG <- "PEG" !([_:] / ) WHITESPACE ; - void: IS <- "<-" WHITESPACE ; - leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. - leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. - void: SEMICOLON <- ";" WHITESPACE ; - void: COLON <- ":" WHITESPACE ; - void: SLASH <- "/" WHITESPACE ; - leaf: AND <- "&" WHITESPACE ; - leaf: NOT <- "!" WHITESPACE ; - leaf: QUESTION <- "?" WHITESPACE ; - leaf: STAR <- "*" WHITESPACE ; - leaf: PLUS <- "+" WHITESPACE ; - void: OPEN <- "(" WHITESPACE ; - void: CLOSE <- ")" WHITESPACE ; - leaf: DOT <- "." WHITESPACE ; - - leaf: ALNUM <- "" WHITESPACE ; - leaf: ALPHA <- "" WHITESPACE ; - leaf: ASCII <- "" WHITESPACE ; - leaf: CONTROL <- "" WHITESPACE ; - leaf: DDIGIT <- "" WHITESPACE ; - leaf: DIGIT <- "" WHITESPACE ; - leaf: GRAPH <- "" WHITESPACE ; - leaf: LOWER <- "" WHITESPACE ; - leaf: PRINTABLE <- "" WHITESPACE ; - leaf: PUNCT <- "" WHITESPACE ; - leaf: SPACE <- "" WHITESPACE ; - leaf: UPPER <- "" WHITESPACE ; - leaf: WORDCHAR <- "" WHITESPACE ; - leaf: XDIGIT <- "" WHITESPACE ; - - void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; - void: COMMENT <- '#' (!EOL .)* EOL ; - void: EOL <- "\n\r" / "\n" / "\r" ; - void: EOF <- !. ; - - # -------------------------------------------------------------------- - END; - -## Example - -Our example specifies the grammar for a basic 4\-operation calculator\. - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -Using higher\-level features of the notation, i\.e\. the character classes -\(predefined and custom\), this example can be rewritten as - - PEG calculator (Expression) - Sign <- [-+] ; - Number <- Sign? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; - END; - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[export](\.\./\.\./\.\./\.\./index\.md\#export), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_container.md @@ -1,88 +0,0 @@ - -[//000000001]: # (pt::peg::from::container \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_from\_container\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::from::container\(n\) 0 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::from::container \- PEG Conversion\. From CONTAINER format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package does not exist\. There is no need for it\. The CONTAINER format for -parsing expression grammars is a piece of Tcl code which, then sourced, provides -a class whose instances have the grammar we wish to import loaded\. Another way -of looking at this is, the CONTAINER output is its own import package\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_json.md @@ -1,542 +0,0 @@ - -[//000000001]: # (pt::peg::from::json \- Parser Tools) -[//000000002]: # (Generated from file 'from\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::from::json\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::from::json \- PEG Conversion\. Read JSON format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON Grammar Exchange Format](#section3) - - - [Example](#subsection1) - - - [PEG serialization format](#section4) - - - [Example](#subsection2) - - - [PE serialization format](#section5) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::from::json ?1? -package require pt::peg -package require json - -[__pt::peg::from::json__ __convert__ *text*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from JSON markup to parsing expression -grammars\. - -It resides in the Import section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the import manager provided by -__[pt::peg::import](pt\_peg\_import\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding import plugin -__[pt::peg::import::json](pt\_peg\_import\_json\.md)__ sitting between -converter and import manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_iplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Import API](pt\_from\_api\.md)* -specification\. - - - __pt::peg::from::json__ __convert__ *text* - - This command takes the JSON markup encoding a parsing expression grammar and - contained in *text*, and generates the canonical serialization of said - grammar, as specified in section [PEG serialization format](#section4)\. - The created value is then returned as the result of the command\. - -# JSON Grammar Exchange Format - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -It is formally specified by the rules below: - - 1. The JSON of any PEG is a JSON object\. - - 1. This object holds a single key, __pt::grammar::peg__, and its value\. - This value holds the contents of the grammar\. - - 1. The contents of the grammar are a JSON object holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - - __rules__ - - The value is a JSON object whose keys are the names of the nonterminal - symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a JSON object itself\. The relevant - keys and their values in this dictionary are - - * __is__ - - The value is a JSON string holding the Tcl serialization of - the parsing expression describing the symbols sentennial - structure, as specified in the section [PE serialization - format](#section5)\. - - * __mode__ - - The value is a JSON holding holding one of three values - specifying how a parser should handle the semantic value - produced by the symbol\. - - + __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal itself, which has the ASTs of the symbol's - right hand side as its children\. - - + __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal, without any children\. Any ASTs generated - by the symbol's right hand side are discarded\. - - + __void__ - - The nonterminal has no semantic value\. Any ASTs generated - by the symbol's right hand side are discarded \(as well\)\. - - - __start__ - - The value is a JSON string holding the Tcl serialization of the start - parsing expression of the grammar, as specified in the section [PE - serialization format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set of - all terminal symbols used in the start expression and on the RHS of the - grammar rules\. - -As an aside to the advanced reader, this is pretty much the same as the Tcl -serialization of PE grammars, as specified in section [PEG serialization -format](#section4), except that the Tcl dictionaries and lists of that -format are mapped to JSON objects and arrays\. Only the parsing expressions -themselves are not translated further, but kept as JSON strings containing a -nested Tcl list, and there is no concept of canonicity for the JSON either\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -a JSON serialization for it is - - { - "pt::grammar::peg" : { - "rules" : { - "AddOp" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Digit" : { - "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", - "mode" : "value" - }, - "Expression" : { - "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", - "mode" : "value" - }, - "Factor" : { - "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", - "mode" : "value" - }, - "MulOp" : { - "is" : "\/ {t *} {t \/}", - "mode" : "value" - }, - "Number" : { - "is" : "x {? {n Sign}} {+ {n Digit}}", - "mode" : "value" - }, - "Sign" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Term" : { - "is" : "n Number", - "mode" : "value" - } - }, - "start" : "n Expression" - } - } - -and a Tcl serialization of the same is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -The similarity of the latter to the JSON should be quite obvious\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section5)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_from_peg.md @@ -1,518 +0,0 @@ - -[//000000001]: # (pt::peg::from::peg \- Parser Tools) -[//000000002]: # (Generated from file 'from\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::from::peg\(n\) 1\.0\.3 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::from::peg \- PEG Conversion\. Read PEG format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [PEG Specification Language](#section3) - - - [Example](#subsection1) - - - [PEG serialization format](#section4) - - - [Example](#subsection2) - - - [PE serialization format](#section5) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::from::peg ?1\.0\.3? - -[__pt::peg::from::peg__ __convert__ *text*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from PEG markup to parsing expression -grammars\. - -It resides in the Import section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the import manager provided by -__[pt::peg::import](pt\_peg\_import\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding import plugin -__[pt::peg::import::peg](pt\_peg\_import\_peg\.md)__ sitting between -converter and import manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_iplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Import API](pt\_from\_api\.md)* -specification\. - - - __pt::peg::from::peg__ __convert__ *text* - - This command takes the PEG markup encoding a parsing expression grammar and - contained in *text*, and generates the canonical serialization of said - grammar, as specified in section [PEG serialization format](#section4)\. - The created value is then returned as the result of the command\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -It is formally specified by the grammar shown below, written in itself\. For a -tutorial / introduction to the language please go and read the *[PEG Language -Tutorial](pt\_peg\_language\.md)*\. - - PEG pe-grammar-for-peg (Grammar) - - # -------------------------------------------------------------------- - # Syntactical constructs - - Grammar <- WHITESPACE Header Definition* Final EOF ; - - Header <- PEG Identifier StartExpr ; - Definition <- Attribute? Identifier IS Expression SEMICOLON ; - Attribute <- (VOID / LEAF) COLON ; - Expression <- Sequence (SLASH Sequence)* ; - Sequence <- Prefix+ ; - Prefix <- (AND / NOT)? Suffix ; - Suffix <- Primary (QUESTION / STAR / PLUS)? ; - Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT - / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER - / WORDCHAR / XDIGIT - / Identifier - / OPEN Expression CLOSE - / Literal - / Class - / DOT - ; - Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE - / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; - Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; - Range <- Char TO Char / Char ; - - StartExpr <- OPEN Expression CLOSE ; - void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; - - # -------------------------------------------------------------------- - # Lexing constructs - - Identifier <- Ident WHITESPACE ; - leaf: Ident <- ([_:] / ) ([_:] / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - - leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; - leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; - leaf: CharOctalPart <- "\\" [0-7][0-7]? ; - leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; - leaf: CharUnescaped <- !"\\" . ; - - void: HexDigit <- [0-9a-fA-F] ; - - void: TO <- '-' ; - void: OPENB <- "[" ; - void: CLOSEB <- "]" ; - void: APOSTROPH <- "'" ; - void: DAPOSTROPH <- '"' ; - void: PEG <- "PEG" !([_:] / ) WHITESPACE ; - void: IS <- "<-" WHITESPACE ; - leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. - leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. - void: SEMICOLON <- ";" WHITESPACE ; - void: COLON <- ":" WHITESPACE ; - void: SLASH <- "/" WHITESPACE ; - leaf: AND <- "&" WHITESPACE ; - leaf: NOT <- "!" WHITESPACE ; - leaf: QUESTION <- "?" WHITESPACE ; - leaf: STAR <- "*" WHITESPACE ; - leaf: PLUS <- "+" WHITESPACE ; - void: OPEN <- "(" WHITESPACE ; - void: CLOSE <- ")" WHITESPACE ; - leaf: DOT <- "." WHITESPACE ; - - leaf: ALNUM <- "" WHITESPACE ; - leaf: ALPHA <- "" WHITESPACE ; - leaf: ASCII <- "" WHITESPACE ; - leaf: CONTROL <- "" WHITESPACE ; - leaf: DDIGIT <- "" WHITESPACE ; - leaf: DIGIT <- "" WHITESPACE ; - leaf: GRAPH <- "" WHITESPACE ; - leaf: LOWER <- "" WHITESPACE ; - leaf: PRINTABLE <- "" WHITESPACE ; - leaf: PUNCT <- "" WHITESPACE ; - leaf: SPACE <- "" WHITESPACE ; - leaf: UPPER <- "" WHITESPACE ; - leaf: WORDCHAR <- "" WHITESPACE ; - leaf: XDIGIT <- "" WHITESPACE ; - - void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; - void: COMMENT <- '#' (!EOL .)* EOL ; - void: EOL <- "\n\r" / "\n" / "\r" ; - void: EOF <- !. ; - - # -------------------------------------------------------------------- - END; - -## Example - -Our example specifies the grammar for a basic 4\-operation calculator\. - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -Using higher\-level features of the notation, i\.e\. the character classes -\(predefined and custom\), this example can be rewritten as - - PEG calculator (Expression) - Sign <- [-+] ; - Number <- Sign? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; - END; - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section5)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_import.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_import.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_import.md @@ -1,543 +0,0 @@ - -[//000000001]: # (pt::peg::import \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_import\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::import\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::import \- PEG Import - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [PEG serialization format](#section3) - - - [Example](#subsection4) - - - [PE serialization format](#section4) - - - [Example](#subsection5) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require Tcl 8\.5 -package require snit -package require fileutil::paths -package require pt::peg -package require pluginmgr -package require pt::peg::import ?1\.0\.1? - -[__::pt::peg::import__ *objectName*](#1) -[__objectName__ __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __import text__ *text* ?*format*?](#4) -[*objectName* __import file__ *path* ?*format*?](#5) -[*objectName* __import object text__ *object* *text* ?*format*?](#6) -[*objectName* __import object file__ *object* *path* ?*format*?](#7) -[*objectName* __includes__](#8) -[*objectName* __include add__ *path*](#9) -[*objectName* __include remove__ *path*](#10) -[*objectName* __include clear__](#11) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a manager for parsing expression grammars, with each -instance handling a set of plugins for the import of them from other formats, -i\.e\. their conversion from, for example *peg*, *container*, -*[json](\.\./\.\./\.\./\.\./index\.md\#json)*, etc\. - -It resides in the Import section of the Core Layer of Parser Tools, and is one -of the three pillars the management of parsing expression grammars resides on\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_import\.png) The other two pillars are, as -shown above - - 1. *[PEG Export](pt\_peg\_export\.md)*, and - - 1. *[PEG Storage](pt\_peg\_container\.md)* - -For information about the data structure which is the major output of the -manager objects provided by this package see the section [PEG serialization -format](#section3)\. - -The plugin system of our class is based on the package -__[pluginmgr](\.\./pluginmgr/pluginmgr\.md)__, and configured to look for -plugins using - - 1. the environment variable __GRAMMAR\_PEG\_IMPORT\_PLUGINS__, - - 1. the environment variable __GRAMMAR\_PEG\_PLUGINS__, - - 1. the environment variable __GRAMMAR\_PLUGINS__, - - 1. the path "~/\.grammar/peg/import/plugin" - - 1. the path "~/\.grammar/peg/plugin" - - 1. the path "~/\.grammar/plugin" - - 1. the path "~/\.grammar/peg/import/plugins" - - 1. the path "~/\.grammar/peg/plugins" - - 1. the path "~/\.grammar/plugins" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PEG\\IMPORT\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PEG\\PLUGINS" - - 1. the registry entry "HKEY\_CURRENT\_USER\\SOFTWARE\\GRAMMAR\\PLUGINS" - -The last three are used only when the package is run on a machine using the -Windows\(tm\) operating system\. - -The whole system is delivered with three predefined import plugins, namely - - - container - - See *[PEG Import Plugin\. From CONTAINER - format](pt\_peg\_import\_container\.md)* for details\. - - - json - - See *PEG Import Plugin\. From JSON format* for details\. - - - peg - - See *PEG Import Plugin\. From PEG format* for details\. - -For readers wishing to write their own import plugin for some format, i\.e\. -*plugin writer*s, reading and understanding the *Parser Tools Impport API* -specification is an absolute necessity, as it documents the interaction between -this package and its plugins in detail\. - -# API - -## Package commands - - - __::pt::peg::import__ *objectName* - - This command creates a new import manager object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The object command will be created under the - current namespace if the *objectName* is not fully qualified, and in the - specified namespace otherwise\. - -## Object command - -All objects created by the __::pt::peg::import__ command have the following -general form: - - - __objectName__ __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object it is invoked for\. - - - *objectName* __import text__ *text* ?*format*? - - This method takes the *text* and converts it from the specified *format* - to the canonical serialization of a parsing expression grammar using the - import plugin for the format\. An error is thrown if no plugin could be found - for the format\. The serialization generated by the conversion process is - returned as the result of this method\. - - If no format is specified the method defaults to __text__\. - - The specification of what a *canonical* serialization is can be found in - the section [PEG serialization format](#section3)\. - - The plugin has to conform to the interface documented in the *[Parser - Tools Import API](pt\_from\_api\.md)* specification\. - - - *objectName* __import file__ *path* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It reads the contents of the specified file - into memory, feeds the result into __import text__ and returns the - resulting serialization as its own result\. - - - *objectName* __import object text__ *object* *text* ?*format*? - - This method is a convenient wrapper around the __import text__ method - described by the previous item\. It expects that *object* is an object - command supporting a __deserialize__ method expecting the canonical - serialization of a parsing expression grammar\. It imports the text using - __import text__ and then feeds the resulting serialization into the - *object* via __deserialize__\. This method returns the empty string as - it result\. - - - *objectName* __import object file__ *object* *path* ?*format*? - - This method behaves like __import object text__, except that it reads - the text to convert from the specified file instead of being given it as - argument\. - - - *objectName* __includes__ - - This method returns a list containing the currently specified paths to use - to search for include files when processing input\. The order of paths in the - list corresponds to the order in which they are used, from first to last, - and also corresponds to the order in which they were added to the object\. - - - *objectName* __include add__ *path* - - This methods adds the specified *path* to the list of paths to use to - search for include files when processing input\. The path is added to the end - of the list, causing it to be searched after all previously added paths\. The - result of the command is the empty string\. - - The method does nothing if the path is already known\. - - - *objectName* __include remove__ *path* - - This methods removes the specified *path* from the list of paths to use to - search for include files when processing input\. The result of the command is - the empty string\. - - The method does nothing if the path is not known\. - - - *objectName* __include clear__ - - This method clears the list of paths to use to search for include files when - processing input\. The result of the command is the empty string\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section4)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section4)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_container.md @@ -1,88 +0,0 @@ - -[//000000001]: # (pt::peg::import::container \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_import\_container\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::import::container\(n\) 0 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::import::container \- PEG Import Plugin\. From CONTAINER format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package does not exist\. There is no need for it\. The CONTAINER format for -parsing expression grammars is a piece of Tcl code which, then sourced, provides -a class whose instances have the grammar we wish to import loaded\. Another way -of looking at this is, the CONTAINER output is its own import package\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_json.md @@ -1,551 +0,0 @@ - -[//000000001]: # (pt::peg::import::json \- Parser Tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::import::json\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::import::json \- PEG Import Plugin\. Read JSON format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [JSON Grammar Exchange Format](#section3) - - - [Example](#subsection1) - - - [PEG serialization format](#section4) - - - [Example](#subsection2) - - - [PE serialization format](#section5) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::import::json ?1? -package require pt::peg::to::json - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the parsing expression grammar import plugin processing -JSON markup\. - -It resides in the Import section of the Core Layer of Parser Tools and is -intended to be used by __[pt::peg::import](pt\_peg\_import\.md)__, the -import manager, sitting between it and the corresponding core conversion -functionality provided by -__[pt::peg::from::json](pt\_peg\_from\_json\.md)__\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_iplugins\.png) - -While the direct use of this package with a regular interpreter is possible, -this is strongly disrecommended and requires a number of contortions to provide -the expected environment\. The proper way to use this functionality depends on -the situation: - - 1. In an untrusted environment the proper access is through the package - __[pt::peg::import](pt\_peg\_import\.md)__ and the import manager - objects it provides\. - - 1. In a trusted environment however simply use the package - __[pt::peg::from::json](pt\_peg\_from\_json\.md)__ and access the core - conversion functionality directly\. - -# API - -The API provided by this package satisfies the specification of the Plugin API -found in the *[Parser Tools Import API](pt\_from\_api\.md)* specification\. - - - __[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* - - This command takes the JSON markup encoding a parsing expression grammar and - contained in *text*, and generates the canonical serialization of said - grammar, as specified in section [PEG serialization format](#section4)\. - The created value is then returned as the result of the command\. - -# JSON Grammar Exchange Format - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -It is formally specified by the rules below: - - 1. The JSON of any PEG is a JSON object\. - - 1. This object holds a single key, __pt::grammar::peg__, and its value\. - This value holds the contents of the grammar\. - - 1. The contents of the grammar are a JSON object holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - - __rules__ - - The value is a JSON object whose keys are the names of the nonterminal - symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a JSON object itself\. The relevant - keys and their values in this dictionary are - - * __is__ - - The value is a JSON string holding the Tcl serialization of - the parsing expression describing the symbols sentennial - structure, as specified in the section [PE serialization - format](#section5)\. - - * __mode__ - - The value is a JSON holding holding one of three values - specifying how a parser should handle the semantic value - produced by the symbol\. - - + __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal itself, which has the ASTs of the symbol's - right hand side as its children\. - - + __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal, without any children\. Any ASTs generated - by the symbol's right hand side are discarded\. - - + __void__ - - The nonterminal has no semantic value\. Any ASTs generated - by the symbol's right hand side are discarded \(as well\)\. - - - __start__ - - The value is a JSON string holding the Tcl serialization of the start - parsing expression of the grammar, as specified in the section [PE - serialization format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set of - all terminal symbols used in the start expression and on the RHS of the - grammar rules\. - -As an aside to the advanced reader, this is pretty much the same as the Tcl -serialization of PE grammars, as specified in section [PEG serialization -format](#section4), except that the Tcl dictionaries and lists of that -format are mapped to JSON objects and arrays\. Only the parsing expressions -themselves are not translated further, but kept as JSON strings containing a -nested Tcl list, and there is no concept of canonicity for the JSON either\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -a JSON serialization for it is - - { - "pt::grammar::peg" : { - "rules" : { - "AddOp" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Digit" : { - "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", - "mode" : "value" - }, - "Expression" : { - "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", - "mode" : "value" - }, - "Factor" : { - "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", - "mode" : "value" - }, - "MulOp" : { - "is" : "\/ {t *} {t \/}", - "mode" : "value" - }, - "Number" : { - "is" : "x {? {n Sign}} {+ {n Digit}}", - "mode" : "value" - }, - "Sign" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Term" : { - "is" : "n Number", - "mode" : "value" - } - }, - "start" : "n Expression" - } - } - -and a Tcl serialization of the same is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -The similarity of the latter to the JSON should be quite obvious\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section5)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_import_peg.md @@ -1,528 +0,0 @@ - -[//000000001]: # (pt::peg::import::peg \- Parser Tools) -[//000000002]: # (Generated from file 'plugin\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::import::peg\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::import::peg \- PEG Import Plugin\. Read PEG format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [PEG Specification Language](#section3) - - - [Example](#subsection1) - - - [PEG serialization format](#section4) - - - [Example](#subsection2) - - - [PE serialization format](#section5) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::import::peg ?1? -package require pt::peg::to::peg - -[__[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the parsing expression grammar import plugin processing -PEG markup\. - -It resides in the Import section of the Core Layer of Parser Tools and is -intended to be used by __[pt::peg::import](pt\_peg\_import\.md)__, the -import manager, sitting between it and the corresponding core conversion -functionality provided by __[pt::peg::from::peg](pt\_peg\_from\_peg\.md)__\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_iplugins\.png) - -While the direct use of this package with a regular interpreter is possible, -this is strongly disrecommended and requires a number of contortions to provide -the expected environment\. The proper way to use this functionality depends on -the situation: - - 1. In an untrusted environment the proper access is through the package - __[pt::peg::import](pt\_peg\_import\.md)__ and the import manager - objects it provides\. - - 1. In a trusted environment however simply use the package - __[pt::peg::from::peg](pt\_peg\_from\_peg\.md)__ and access the core - conversion functionality directly\. - -# API - -The API provided by this package satisfies the specification of the Plugin API -found in the *[Parser Tools Import API](pt\_from\_api\.md)* specification\. - - - __[import](\.\./\.\./\.\./\.\./index\.md\#import)__ *text* - - This command takes the PEG markup encoding a parsing expression grammar and - contained in *text*, and generates the canonical serialization of said - grammar, as specified in section [PEG serialization format](#section4)\. - The created value is then returned as the result of the command\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -It is formally specified by the grammar shown below, written in itself\. For a -tutorial / introduction to the language please go and read the *[PEG Language -Tutorial](pt\_peg\_language\.md)*\. - - PEG pe-grammar-for-peg (Grammar) - - # -------------------------------------------------------------------- - # Syntactical constructs - - Grammar <- WHITESPACE Header Definition* Final EOF ; - - Header <- PEG Identifier StartExpr ; - Definition <- Attribute? Identifier IS Expression SEMICOLON ; - Attribute <- (VOID / LEAF) COLON ; - Expression <- Sequence (SLASH Sequence)* ; - Sequence <- Prefix+ ; - Prefix <- (AND / NOT)? Suffix ; - Suffix <- Primary (QUESTION / STAR / PLUS)? ; - Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT - / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER - / WORDCHAR / XDIGIT - / Identifier - / OPEN Expression CLOSE - / Literal - / Class - / DOT - ; - Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE - / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; - Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; - Range <- Char TO Char / Char ; - - StartExpr <- OPEN Expression CLOSE ; - void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; - - # -------------------------------------------------------------------- - # Lexing constructs - - Identifier <- Ident WHITESPACE ; - leaf: Ident <- ([_:] / ) ([_:] / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - - leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; - leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; - leaf: CharOctalPart <- "\\" [0-7][0-7]? ; - leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; - leaf: CharUnescaped <- !"\\" . ; - - void: HexDigit <- [0-9a-fA-F] ; - - void: TO <- '-' ; - void: OPENB <- "[" ; - void: CLOSEB <- "]" ; - void: APOSTROPH <- "'" ; - void: DAPOSTROPH <- '"' ; - void: PEG <- "PEG" !([_:] / ) WHITESPACE ; - void: IS <- "<-" WHITESPACE ; - leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. - leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. - void: SEMICOLON <- ";" WHITESPACE ; - void: COLON <- ":" WHITESPACE ; - void: SLASH <- "/" WHITESPACE ; - leaf: AND <- "&" WHITESPACE ; - leaf: NOT <- "!" WHITESPACE ; - leaf: QUESTION <- "?" WHITESPACE ; - leaf: STAR <- "*" WHITESPACE ; - leaf: PLUS <- "+" WHITESPACE ; - void: OPEN <- "(" WHITESPACE ; - void: CLOSE <- ")" WHITESPACE ; - leaf: DOT <- "." WHITESPACE ; - - leaf: ALNUM <- "" WHITESPACE ; - leaf: ALPHA <- "" WHITESPACE ; - leaf: ASCII <- "" WHITESPACE ; - leaf: CONTROL <- "" WHITESPACE ; - leaf: DDIGIT <- "" WHITESPACE ; - leaf: DIGIT <- "" WHITESPACE ; - leaf: GRAPH <- "" WHITESPACE ; - leaf: LOWER <- "" WHITESPACE ; - leaf: PRINTABLE <- "" WHITESPACE ; - leaf: PUNCT <- "" WHITESPACE ; - leaf: SPACE <- "" WHITESPACE ; - leaf: UPPER <- "" WHITESPACE ; - leaf: WORDCHAR <- "" WHITESPACE ; - leaf: XDIGIT <- "" WHITESPACE ; - - void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; - void: COMMENT <- '#' (!EOL .)* EOL ; - void: EOL <- "\n\r" / "\n" / "\r" ; - void: EOF <- !. ; - - # -------------------------------------------------------------------- - END; - -## Example - -Our example specifies the grammar for a basic 4\-operation calculator\. - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -Using higher\-level features of the notation, i\.e\. the character classes -\(predefined and custom\), this example can be rewritten as - - PEG calculator (Expression) - Sign <- [-+] ; - Number <- Sign? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; - END; - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section5)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section5)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[import](\.\./\.\./\.\./\.\./index\.md\#import), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), -[plugin](\.\./\.\./\.\./\.\./index\.md\#plugin), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_interp.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_interp.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_interp.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_interp.md @@ -1,441 +0,0 @@ - -[//000000001]: # (pt::peg::interp \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_interp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::interp\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::interp \- Interpreter for parsing expression grammars - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#subsection1) - - - [Object API](#subsection2) - - - [AST serialization format](#section2) - - - [Example](#subsection3) - - - [PE serialization format](#section3) - - - [Example](#subsection4) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::interp ?1\.0\.1? -package require pt::rde ?1? -package require snit - -[__::pt::peg::interp__ *objectName* *grammar*](#1) -[*objectName* __use__ *grammar*](#2) -[*objectName* __destroy__](#3) -[*objectName* __parse__ *chan*](#4) -[*objectName* __parset__ *text*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a class whose instances are Packrat parsers configurable -with a parsing expression grammar\. The grammar is executed directly, i\.e\. -interpreted, with the underlying runtime provided by the package -__[pt::rde](pt\_rdengine\.md)__, basing everything on the PARAM\. - -Like the supporting runtime this package resides in the Execution section of the -Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_transform\.png) - -The interpreted grammar is copied from an instance of -__[pt::peg::container](pt\_peg\_container\.md)__, or anything providing the -same API, like the container classes created by -__[pt::peg::to::container](pt\_peg\_to\_container\.md)__ or the associated -export plugin -__[pt::peg::export::container](pt\_peg\_export\_container\.md)__\. - -## Class API - -The package exports the API described here\. - - - __::pt::peg::interp__ *objectName* *grammar* - - The command creates a new parser object and returns the fully qualified name - of the object command as its result\. The API of this object command is - described in the section [Object API](#subsection2)\. It may be used to - invoke various operations on the object\. - - This new parser is configured for the execution of an empty PEG\. To - configure the object for any other PEG use the method __use__ of the - [Object API](#subsection2)\. - -## Object API - -All objects created by this package provide the following methods\. - - - *objectName* __use__ *grammar* - - This method configures the grammar interpreter / parser for the execution of - the PEG stored in *grammar*, an object which is API\-compatible to - instances of __[pt::peg::container](pt\_peg\_container\.md)__\. The - parser copies the relevant information of the grammar, and does *not* take - ownership of the object\. - - The information of any previously used grammar is overwritten\. - - The result of the method the empty string\. - - - *objectName* __destroy__ - - This method destroys the parser instance, releasing all claimed memory and - other resources, and deleting the instance command\. - - The result of the command is the empty string\. - - - *objectName* __parse__ *chan* - - This method runs the parser using the contents of *chan* as input - \(starting at the current location in the channel\), until parsing is not - possible anymore, either because parsing has completed, or run into a syntax - error\. - - Note here that the Parser Tools are based on Tcl 8\.5\+\. In other words, the - channel argument is not restricted to files, sockets, etc\. We have the full - power of *reflected channels* available\. - - It should also be noted that the parser pulls the characters from the input - stream as it needs them\. If a parser created by this package has to be - operated in a push aka event\-driven manner it will be necessary to go to Tcl - 8\.6\+ and use the __[coroutine::auto](\.\./coroutine/coro\_auto\.md)__ to - wrap it into a coroutine where __[read](\.\./\.\./\.\./\.\./index\.md\#read)__ - is properly changed for push\-operation\. - - Upon successful completion the command returns an abstract syntax tree as - its result\. This AST is in the form specified in section [AST serialization - format](#section2)\. As a plain nested Tcl\-list it can then be processed - with any Tcl commands the user likes, doing transformations, semantic - checks, etc\. To help in this the package __[pt::ast](pt\_astree\.md)__ - provides a set of convenience commands for validation of the tree's basic - structure, printing it for debugging, and walking it either from the bottom - up, or top down\. - - When encountering a syntax error the command will throw an error instead\. - This error will be a 4\-element Tcl\-list, containing, in the order listed - below: - - 1. The string __pt::rde__ identifying it as parser runtime error\. - - 1. The location of the parse error, as character offset from the beginning - of the parsed input\. - - 1. The location of parse error, now as a 2\-element list containing - line\-number and column in the line\. - - 1. A set of atomic parsing expressions indicating encoding the characters - and/or nonterminal symbols the parser expected to see at the location - of the parse error, but did not get\. For the specification of atomic - parsing expressions please see the section [PE serialization - format](#section3)\. - - - *objectName* __parset__ *text* - - This method runs the parser using the string in *text* as input\. In all - other ways it behaves like the method __parse__, shown above\. - -# AST serialization format - -Here we specify the format used by the Parser Tools to serialize Abstract Syntax -Trees \(ASTs\) as immutable values for transport, comparison, etc\. - -Each node in an AST represents a nonterminal symbol of a grammar, and the range -of tokens/characters in the input covered by it\. ASTs do not contain terminal -symbols, i\.e\. tokens/characters\. These can be recovered from the input given a -symbol's location\. - -We distinguish between *regular* and *canonical* serializations\. While a -tree may have more than one regular serialization only exactly one of them will -be *canonical*\. - - - Regular serialization - - 1. The serialization of any AST is the serialization of its root node\. - - 1. The serialization of any node is a Tcl list containing at least three - elements\. - - 1) The first element is the name of the nonterminal symbol stored in - the node\. - - 1) The second and third element are the locations of the first and - last token in the token stream the node represents \(covers\)\. - - 1. Locations are provided as non\-negative integer offsets from - the beginning of the token stream, with the first token found - in the stream located at offset 0 \(zero\)\. - - 1. The end location has to be equal to or larger than the start - location\. - - 1) All elements after the first three represent the children of the - node, which are themselves nodes\. This means that the - serializations of nodes without children, i\.e\. leaf nodes, have - exactly three elements\. The children are stored in the list with - the leftmost child first, and the rightmost child last\. - - - Canonical serialization - - The canonical serialization of an abstract syntax tree has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this tree\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the parsing expression grammar below - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -and the input string - - 120+5 - -then a parser should deliver the abstract syntax tree below \(except for -whitespace\) - - set ast {Expression 0 4 - {Factor 0 4 - {Term 0 2 - {Number 0 2 - {Digit 0 0} - {Digit 1 1} - {Digit 2 2} - } - } - {AddOp 3 3} - {Term 4 4 - {Number 4 4 - {Digit 4 4} - } - } - } - } - -Or, more graphical - -![](\.\./\.\./\.\./\.\./image/expr\_ast\.png) - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_introduction.md @@ -1,218 +0,0 @@ - -[//000000001]: # (pt::pegrammar \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_introduction\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::pegrammar\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::pegrammar \- Introduction to Parsing Expression Grammars - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Formal definition](#section2) - - - [References](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -Welcome to the introduction to *[Parsing Expression -Grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar)*s \(short: -*[PEG](\.\./\.\./\.\./\.\./index\.md\#peg)*\), the formalism used by the Parser -Tools\. It is assumed that the reader has a basic knowledge of parsing theory, -i\.e\. *Context\-Free Grammars* \(short: *[CFG](\.\./\.\./\.\./\.\./index\.md\#cfg)*\), -*languages*, and associated terms like -*[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_)*, *LR\(k\)*, -*[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal)* and *nonterminal* -*symbols*, etc\. We do not intend to recapitulate such basic definitions or -terms like *useful*, *reachable*, \(left/right\) *recursive*, *nullable*, -first/last/follow sets, etc\. Please see the [References](#section3) at the -end instead if you are in need of places and books which provide such background -information\. - -PEGs are formally very similar to CFGs, with terminal and nonterminal symbols, -start symbol, and rules defining the structure of each nonterminal symbol\. The -main difference lies in the choice\(sic\!\) of *choice* operators\. Where CFGs use -an *unordered choice* to represent alternatives PEGs use *prioritized -choice*\. Which is fancy way of saying that a parser has to try the first -alternative first and can try the other alternatives if only if it fails for the -first, and so on\. - -On the CFG side this gives rise to LL\(k\) and LR\(k\) for making the choice -*deterministic* with a bounded *lookahead* of k terminal symbols, where LL -is in essence *topdown* aka *[recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent)* parsing, and LR -*bottomup* aka *shift reduce* parsing\. - -On the PEG side we can parse input with recursive descent and *backtracking* -of failed choices, the latter of which amounts to unlimited lookahead\. By -additionally recording the success or failure of nonterminals at the specific -locations they were tried at and reusing this information after backtracking we -can avoid the exponential blowup of running time usually associated with -backtracking and keep the parsing linear\. The memory requirements are of course -higher due to this cache, as we are trading space for time\. - -This is the basic concept behind *packrat parsers*\. - -A limitation pure PEGs share with LL\(k\) CFGs is that *left\-recursive* grammars -cannot be parsed, with the associated recursive descent parser entering an -infinite recursion\. This limitation is usually overcome by extending pure PEGs -with explicit operators to specify repetition, zero or more, and one or more, -or, formally spoken, for the *kleene closure* and *positive kleene closure*\. -This is what the Parser Tools are doing\. - -Another extension, specific to Parser Tools, is a set of operators which map -more or less directly to various character classes built into Tcl, i\.e\. the -classes reachable via __string is__\. - -The remainder of this document consists of the formal definition of PEGs for the -mathematically inclined, and an appendix listing references to places with more -information on PEGs specifically, and parsing in general\. - -# Formal definition - -For the mathematically inclined, a Parsing Expression Grammar is a 4\-tuple -\(VN,VT,R,eS\) where - - - VN is a set of *nonterminal symbols*, - - - VT is a set of *terminal symbols*, - - - R is a finite set of rules, where each rule is a pair \(A,e\), A in VN, and - *[e](\.\./\.\./\.\./\.\./index\.md\#e)* a *[parsing - expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression)*\. - - - eS is a parsing expression, the *start expression*\. - -Further constraints are - - - The intersection of VN and VT is empty\. - - - For all A in VT exists exactly one pair \(A,e\) in R\. In other words, R is a - function from nonterminal symbols to parsing expressions\. - -Parsing expressions are inductively defined via - - - The empty string \(epsilon\) is a parsing expression\. - - - A terminal symbol *a* is a parsing expression\. - - - A nonterminal symbol *A* is a parsing expression\. - - - *e1**e2* is a parsing expression for parsing expressions *e1* and - *2*\. This is called *sequence*\. - - - *e1*/*e2* is a parsing expression for parsing expressions *e1* and - *2*\. This is called *ordered choice*\. - - - *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\* is a parsing expression for parsing - expression *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\. This is called - *zero\-or\-more repetitions*, also known as *kleene closure*\. - - - *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\+ is a parsing expression for parsing - expression *[e](\.\./\.\./\.\./\.\./index\.md\#e)*\. This is called *one\-or\-more - repetitions*, also known as *positive kleene closure*\. - - - \!*[e](\.\./\.\./\.\./\.\./index\.md\#e)* is a parsing expression for parsing - expression *e1*\. This is called a *not lookahead predicate*\. - - - &*[e](\.\./\.\./\.\./\.\./index\.md\#e)* is a parsing expression for parsing - expression *e1*\. This is called an *and lookahead predicate*\. - -PEGs are used to define a grammatical structure for streams of symbols over VT\. -They are a modern phrasing of older formalisms invented by Alexander Birham\. -These formalisms were called TS \(TMG recognition scheme\), and gTS \(generalized -TS\)\. Later they were renamed to TPDL \(Top\-Down Parsing Languages\) and gTPDL -\(generalized TPDL\)\. - -They can be easily implemented by recursive descent parsers with backtracking\. -This makes them relatives of LL\(k\) Context\-Free Grammars\. - -# References - - 1. [The Packrat Parsing and Parsing Expression Grammars - Page](http://www\.pdos\.lcs\.mit\.edu/~baford/packrat/), by Bryan Ford, - Massachusetts Institute of Technology\. This is the main entry page to PEGs, - and their realization through Packrat Parsers\. - - 1. [http://en\.wikipedia\.org/wiki/Parsing\_expression\_grammar](http://en\.wikipedia\.org/wiki/Parsing\_expression\_grammar) - Wikipedia's entry about Parsing Expression Grammars\. - - 1. [Parsing Techniques \- A Practical Guide - ](http://www\.cs\.vu\.nl/~dick/PTAPG\.html), an online book offering a - clear, accessible, and thorough discussion of many different parsing - techniques with their interrelations and applicabilities, including error - recovery techniques\. - - 1. [Compilers and Compiler Generators](http://scifac\.ru\.ac\.za/compilers/), - an online book using CoCo/R, a generator for recursive descent parsers\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_language.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_language.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_language.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_language.md @@ -1,496 +0,0 @@ - -[//000000001]: # (pt::peg\_language \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_language\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg\_language\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg\_language \- PEG Language Tutorial - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [What is it?](#section2) - - - [The elements of the language](#section3) - - - [Basic structure](#subsection1) - - - [Names](#subsection2) - - - [Rules](#subsection3) - - - [Expressions](#subsection4) - - - [Whitespace and comments](#subsection5) - - - [Nonterminal attributes](#subsection6) - - - [PEG Specification Language](#section4) - - - [Example](#subsection7) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -Welcome to the tutorial / introduction for the [PEG Specification -Language](#section4)\. If you are already familiar with the language we are -about to discuss, and only wish to refresh your memory you can, of course, skip -ahead to the aforementioned section and just read the full formal specification\. - -# What is it? - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -# The elements of the language - -## Basic structure - -The general outline of a textual PEG is - - PEG <> (<>) - <> - END; - -*Note*: We are using text in double angle\-brackets as place\-holders for things -not yet explained\. - -## Names - -Names are mostly used to identify the nonterminal symbols of the grammar, i\.e\. -that which occurs on the left\-hand side of a \. The exception to that is -the name given after the keyword __PEG__ \(see previous section\), which is -the name of the whole grammar itself\. - -The structure of a name is simple: - - 1. It begins with a letter, underscore, or colon, followed by - - 1. zero or more letters, digits, underscores, or colons\. - -Or, in formal textual notation: - - ([_:] / ) ([_:] / )* - -Examples of names: - - Hello - ::world - _:submarine55_ - -Examples of text which are *not* names: - - 12 - .bogus - 0wrong - @location - -## Rules - -The main body of the text of a grammar specification is taken up by the rules\. -Each rule defines the sentence structure of one nonterminal symbol\. Their basic -structure is - - <> <- <> ; - -The specifies the nonterminal symbol to be defined, the -after the arrow \(<\-\) then declares its structure\. - -Note that each rule ends in a single semicolon, even the last\. I\.e\. the -semicolon is a rule *terminator*, not a separator\. - -We can have as many rules as we like, as long as we define each nonterminal -symbol at most once, and have at least one rule for each nonterminal symbol -which occured in an expression, i\.e\. in either the start expression of the -grammar, or the right\-hande side of a rule\. - -## Expressions - -The *parsing* expressions are the meat of any specification\. They declare the -structure of the whole document \(<>\), and of all nonterminal -symbols\. - -All expressions are made up out of *atomic expressions* and *operators* -combining them\. We have operators for choosing between alternatives, repetition -of parts, and for look\-ahead constraints\. There is no explicit operator for the -sequencing \(also known as *concatenation*\) of parts however\. This is specified -by simply placing the parts adjacent to each other\. - -Here are the operators, from highest to lowest priority \(i\.e\. strength of -binding\): - - # Binary operators. - - <> <> # sequence. parse 1, then 2. - <> / <> # alternative. try to parse 1, and parse 2 if 1 failed to parse. - - # Prefix operators. Lookahead constraints. Same priority. - - & <> # Parse expression, ok on successful parse. - ! <> # Ditto, except ok on failure to parse. - - # Suffix operators. Repetition. Same priority. - - <> ? # Parse expression none, or once (repeat 0 or 1). - <> * # Parse expression zero or more times. - <> + # Parse expression one or more times. - - # Expression nesting - - ( <> ) # Put an expression in parens to change its priority. - -With this we can now deconstruct the formal expression for names given in -section [Names](#subsection2): - - ([_:] / ) ([_:] / )* - -It is a sequence of two parts, - - [_:] / - -and - - ([_:] / )* - -The parentheses around the parts kept their inner alternatives bound together -against the normally higher priority of the sequence\. Each of the two parts is -an alternative, with the second part additionally repeated zero or more times, -leaving us with the three atomic expressions - - [_:] - - - -And *atomic expressions* are our next topic\. They fall into three classes: - - 1. names, i\.e\. nonterminal symbols, - - 1. string literals, and - - 1. character classes\. - -Names we know about already, or see section [Names](#subsection2) for a -refresher\. - -String literals are simple\. They are delimited by \(i\.e\. start and end with\) -either a single or double\-apostroph, and in between the delimiters we can have -any character but the delimiter itself\. They can be empty as well\. Examples of -strings are - - '' - "" - 'hello' - "umbra" - "'" - '"' - -The last two examples show how to place any of the delimiters into a string\. - -For the last, but not least of our atomic expressions, character classes, we -have a number of predefined classes, shown below, and the ability to construct -or own\. The predefined classes are: - - # Any unicode alphabet or digit character (string is alnum). - # Any unicode alphabet character (string is alpha). - # Any unicode character below codepoint 0x80 (string is ascii). - # Any unicode control character (string is control). - # The digit characters [0-9]. - # Any unicode digit character (string is digit). - # Any unicode printing character, except space (string is graph). - # Any unicode lower-case alphabet character (string is lower). - # Any unicode printing character, incl. space (string is print). - # Any unicode punctuation character (string is punct). - # Any unicode space character (string is space). - # Any unicode upper-case alphabet character (string is upper). - # Any unicode word character (string is wordchar). - # The hexadecimal digit characters [0-9a-fA-F]. - . # Any character, except end of input. - -And the syntax of custom\-defined character classes is - - [ <>* ] - -where each range is either a single character, or of the form - - <> - > - -Examples for character classes we have seen already in the course of this -introduction are - - [_:] - [0-9] - [0-9a-fA-F] - -We are nearly done with expressions\. The only piece left is to tell how the -characters in character classes and string literals are specified\. - -Basically characters in the input stand for themselves, and in addition to that -we several types of escape syntax to to repesent control characters, or -characters outside of the encoding the text is in\. - -All the escaped forms are started with a backslash character \('\\', unicode -codepoint 0x5C\)\. This is then followed by a series of octal digits, or 'u' and -hexedecimal digits, or a regular character from a fixed set for various control -characters\. Some examples: - - \n \r \t \' \" \[ \] \\ # - \000 up to \277 # octal escape, all ascii character, leading 0's can be removed. - \u2CA7 # hexadecimal escape, all unicode characters. - # # Here 2ca7 <=> Koptic Small Letter Tau - -## Whitespace and comments - -One issue not touched upon so far is whitespace and comments\. - -Whitespace is any unicode space character, i\.e\. anything in the character class -, and comments\. The latter are sequences of characters starting with a -'\#' \(hash, unicode codepoint 0x23\) and ending at the next end\-of\-line\. - -Whitespace can be freely used between all syntactical elements of a grammar -specification\. It cannot be used inside of syntactical elements, like names, -string literals, predefined character classes, etc\. - -## Nonterminal attributes - -Lastly, a more advanced topic\. In the section [Rules](#subsection3) we gave -the structure of a rule as - - <> <- <> ; - -This is not quite true\. It is possible to associate a semantic mode with the -nonterminal in the rule, by writing it before the name, separated from it by a -colon, i\.e\. writing - - <> : <> <- <> ; - -is also allowed\. This mode is optional\. The known modes and their meanings are: - - - __value__ - - The semantic value of the nonterminal symbol is an abstract syntax tree - consisting of a single node node for the nonterminal itself, which has the - ASTs of the symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an abstract syntax tree - consisting of a single node node for the nonterminal, without any children\. - Any ASTs generated by the symbol's right hand side are discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs generated by the symbol's - right hand side are discarded \(as well\)\. - -Of these three modes only __leaf__ and __void__ can be specified -directly\. __value__ is implicitly specified by the absence of a mode before -the nonterminal\. - -Now, with all the above under our belt it should be possible to not only read, -but understand the formal specification of the text representation shown in the -next section, written in itself\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -It is formally specified by the grammar shown below, written in itself\. For a -tutorial / introduction to the language please go and read the *PEG Language -Tutorial*\. - - PEG pe-grammar-for-peg (Grammar) - - # -------------------------------------------------------------------- - # Syntactical constructs - - Grammar <- WHITESPACE Header Definition* Final EOF ; - - Header <- PEG Identifier StartExpr ; - Definition <- Attribute? Identifier IS Expression SEMICOLON ; - Attribute <- (VOID / LEAF) COLON ; - Expression <- Sequence (SLASH Sequence)* ; - Sequence <- Prefix+ ; - Prefix <- (AND / NOT)? Suffix ; - Suffix <- Primary (QUESTION / STAR / PLUS)? ; - Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT - / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER - / WORDCHAR / XDIGIT - / Identifier - / OPEN Expression CLOSE - / Literal - / Class - / DOT - ; - Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE - / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; - Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; - Range <- Char TO Char / Char ; - - StartExpr <- OPEN Expression CLOSE ; - void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; - - # -------------------------------------------------------------------- - # Lexing constructs - - Identifier <- Ident WHITESPACE ; - leaf: Ident <- ([_:] / ) ([_:] / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - - leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; - leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; - leaf: CharOctalPart <- "\\" [0-7][0-7]? ; - leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; - leaf: CharUnescaped <- !"\\" . ; - - void: HexDigit <- [0-9a-fA-F] ; - - void: TO <- '-' ; - void: OPENB <- "[" ; - void: CLOSEB <- "]" ; - void: APOSTROPH <- "'" ; - void: DAPOSTROPH <- '"' ; - void: PEG <- "PEG" !([_:] / ) WHITESPACE ; - void: IS <- "<-" WHITESPACE ; - leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. - leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. - void: SEMICOLON <- ";" WHITESPACE ; - void: COLON <- ":" WHITESPACE ; - void: SLASH <- "/" WHITESPACE ; - leaf: AND <- "&" WHITESPACE ; - leaf: NOT <- "!" WHITESPACE ; - leaf: QUESTION <- "?" WHITESPACE ; - leaf: STAR <- "*" WHITESPACE ; - leaf: PLUS <- "+" WHITESPACE ; - void: OPEN <- "(" WHITESPACE ; - void: CLOSE <- ")" WHITESPACE ; - leaf: DOT <- "." WHITESPACE ; - - leaf: ALNUM <- "" WHITESPACE ; - leaf: ALPHA <- "" WHITESPACE ; - leaf: ASCII <- "" WHITESPACE ; - leaf: CONTROL <- "" WHITESPACE ; - leaf: DDIGIT <- "" WHITESPACE ; - leaf: DIGIT <- "" WHITESPACE ; - leaf: GRAPH <- "" WHITESPACE ; - leaf: LOWER <- "" WHITESPACE ; - leaf: PRINTABLE <- "" WHITESPACE ; - leaf: PUNCT <- "" WHITESPACE ; - leaf: SPACE <- "" WHITESPACE ; - leaf: UPPER <- "" WHITESPACE ; - leaf: WORDCHAR <- "" WHITESPACE ; - leaf: XDIGIT <- "" WHITESPACE ; - - void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; - void: COMMENT <- '#' (!EOL .)* EOL ; - void: EOL <- "\n\r" / "\n" / "\r" ; - void: EOF <- !. ; - - # -------------------------------------------------------------------- - END; - -## Example - -Our example specifies the grammar for a basic 4\-operation calculator\. - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -Using higher\-level features of the notation, i\.e\. the character classes -\(predefined and custom\), this example can be rewritten as - - PEG calculator (Expression) - Sign <- [-+] ; - Number <- Sign? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; - END; - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_op.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_op.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_op.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_op.md @@ -1,248 +0,0 @@ - -[//000000001]: # (pt\_peg\_op \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_peg\_op\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_peg\_op\(i\) 1\.1\.0 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_peg\_op \- Parser Tools PE Grammar Utility Operations - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::op ?1\.1\.0? - -[__::peg::peg::op__ __called__ *container*](#1) -[__::peg::peg::op__ __dechain__ *container*](#2) -[__::peg::peg::op__ __drop unreachable__ *container*](#3) -[__::peg::peg::op__ __drop unrealizable__ *container*](#4) -[__::peg::peg::op__ __flatten__ *container*](#5) -[__::peg::peg::op__ __minimize__ *container*](#6) -[__::peg::peg::op__ __modeopt__ *container*](#7) -[__::peg::peg::op__ __reachable__ *container*](#8) -[__::peg::peg::op__ __realizable__ *container*](#9) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a number of utility commands manipulating a PE grammar -\(container\) in various ways\. - -# API - - - __::peg::peg::op__ __called__ *container* - - This command determines the static call structure for the nonterminal - symbols of the grammar stored in the *container*\. - - The result of the command is a dictionary mapping from each symbol to the - symbols it calls\. The empty string is the key used to represent the start - expression of the grammar\. - - The grammar in the container is not modified\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __dechain__ *container* - - This command simplifies all symbols which just chain to a different symbol - by inlining the right hand side of the called symbol in its callers\. This - works if and only the modes match properly, per the decision table below\. - - caller called | dechain | notes - --------------+---------+----------------------- - value value | yes | value is passed - value leaf | yes | value is passed - value void | yes | caller is implied void - leaf value | no | generated value was discarded, inlined would not. called may be implied void. - leaf leaf | no | s.a. - leaf void | no | s.a. - void value | no | caller drops value, inlined would not. - void leaf | no | s.a. - void void | yes | - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __drop unreachable__ *container* - - This command removes all symbols from the grammar which are not - __reachable__\. - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __drop unrealizable__ *container* - - This command removes all symbols from the grammar which are not - __realizable__\. - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __flatten__ *container* - - This command flattens \(see __[pt::pe::op](pt\_pexpr\_op\.md)__\) all - expressions in the grammar, i\.e\. the start expression and the right hand - sides of all nonterminal symbols\. - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __minimize__ *container* - - This command reduces the provided grammar by applying most of the other - methods of this package\. - - After flattening the expressions it removes unreachable and unrealizable - symbols, flattens the expressions again, then optimizes the symbol modes - before collapsing symbol chains as much as possible\. - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __modeopt__ *container* - - This command optimizes the semantic modes of non\-terminal symbols according - to the two rules below\. - - 1. If a symbol X with mode __value__ calls no other symbols, i\.e\. uses - only terminal symbols in whatever combination, then this can be - represented simpler by using mode __leaf__\. - - 1. If a symbol X is only called from symbols with modes __leaf__ or - __void__ then this symbol should have mode __void__ also, as - any AST it could generate will be discarded anyway\. - - The result of the command is the empty string\. - - The grammar in the container is directly modified\. If that is not wanted, a - copy of the original container has to be used\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __reachable__ *container* - - This command computes the set of all nonterminal symbols which are reachable - from the start expression of the grammar\. This is essentially the transitive - closure over __called__ and the symbol's right hand sides, beginning - with the start expression\. - - The result of the command is the list of reachable symbols\. - - The grammar in the container is not modified\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - - - __::peg::peg::op__ __realizable__ *container* - - This command computes the set of all nonterminal symbols which are - realizable, i\.e\. can derive pure terminal phrases\. This is done iteratively, - starting with state unrealizable for all and any, and then updating all - symbols which are realizable, propagating changes, until nothing changes any - more\. - - The result of the command is the list of realizable symbols\. - - The grammar in the container is not modified\. - - The *container* instance has to expose a method API as is provided by the - package __[pt::peg::container](pt\_peg\_container\.md)__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_container.md @@ -1,555 +0,0 @@ - -[//000000001]: # (pt::peg::to::container \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::container\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::container \- PEG Conversion\. Write CONTAINER format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [Grammar Container](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::container ?1? -package require pt::peg -package require text::write -package require char - -[__pt::peg::to::container__ __reset__](#1) -[__pt::peg::to::container__ __configure__](#2) -[__pt::peg::to::container__ __configure__ *option*](#3) -[__pt::peg::to::container__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::container__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to -CONTAINER markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__[pt::peg::export::container](pt\_peg\_export\_container\.md)__ sitting -between converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::container__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::container__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::container__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::container__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::container__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates CONTAINER markup encoding the - grammar, per the current package configuration\. The created string is then - returned as the result of the command\. - -# Options - -The converter to the CONTAINER format recognizes the following options and -changes its behaviour as they specify\. - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-mode__ __bulk__|__incremental__ - - The value of this option controls which methods of - __[pt::peg::container](pt\_peg\_container\.md)__ instances are used to - specify the grammar, i\.e\. preload it into the container\. There are two legal - values, as listed below\. The default is __bulk__\. - - * __bulk__ - - In this mode the methods __start__, __add__, __modes__, and - __rules__ are used to specify the grammar in a bulk manner, i\.e\. as - a set of nonterminal symbols, and two dictionaries mapping from the - symbols to their semantic modes and parsing expressions\. - - This mode is the default\. - - * __incremental__ - - In this mode the methods __start__, __add__, __mode__, and - __rule__ are used to specify the grammar piecemal, with each - nonterminal having its own block of defining commands\. - - - __\-template__ string - - The value of this option is a string into which to put the generated code - and the other configuration settings\. The various locations for user\-data - are expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __CONTAINER__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@mode@__ - - To be replaced with the value of the option __\-mode__\. - - * __@code@__ - - To be replaced with the generated code\. - -# Grammar Container - -The __container__ format is another form of describing parsing expression -grammars\. While data in this format is executable it does not constitute a -parser for the grammar\. It always has to be used in conjunction with the package -__[pt::peg::interp](pt\_peg\_interp\.md)__, a grammar interpreter\. - -The format represents grammars by a __snit::type__, i\.e\. class, whose -instances are API\-compatible to the instances of the -__[pt::peg::container](pt\_peg\_container\.md)__ package, and which are -preloaded with the grammar in question\. - -It has no direct formal specification beyond what was said above\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -one possible CONTAINER serialization for it is - - snit::type a_pe_grammar { - constructor {} { - install myg using pt::peg::container ${selfns}::G - $myg start {n Expression} - $myg add AddOp Digit Expression Factor MulOp Number Sign Term - $myg modes { - AddOp value - Digit value - Expression value - Factor value - MulOp value - Number value - Sign value - Term value - } - $myg rules { - AddOp {/ {t -} {t +}} - Digit {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} - Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}} - Factor {x {n Term} {* {x {n AddOp} {n Term}}}} - MulOp {/ {t *} {t /}} - Number {x {? {n Sign}} {+ {n Digit}}} - Sign {/ {t -} {t +}} - Term {n Number} - } - return - } - - component myg - delegate method * to myg - } - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[CONTAINER](\.\./\.\./\.\./\.\./index\.md\#container), -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_cparam.md @@ -1,611 +0,0 @@ - -[//000000001]: # (pt::peg::to::cparam \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::cparam\(n\) 1\.1\.2 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::cparam \- PEG Conversion\. Write CPARAM format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [C/PARAM code representation of parsing expression grammars](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::cparam ?1\.1\.2? - -[__pt::peg::to::cparam__ __reset__](#1) -[__pt::peg::to::cparam__ __configure__](#2) -[__pt::peg::to::cparam__ __configure__ *option*](#3) -[__pt::peg::to::cparam__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::cparam__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to CPARAM -markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__pt::peg::export::cparam__ sitting between converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::cparam__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::cparam__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::cparam__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::cparam__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::cparam__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates CPARAM markup encoding the - grammar, per the current package configuration\. The created string is then - returned as the result of the command\. - -# Options - -The converter to C code recognizes the following configuration variables and -changes its behaviour as they specify\. - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-template__ string - - The value of this option is a string into which to put the generated text - and the other configuration settings\. The various locations for user\-data - are expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __C/PARAM__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@code@__ - - To be replaced with the generated Tcl code\. - - The following options are special, in that they will occur within the - generated code, and are replaced there as well\. - - * __@statedecl@__ - - To be replaced with the value of the option __state\-decl__\. - - * __@stateref@__ - - To be replaced with the value of the option __state\-ref__\. - - * __@strings@__ - - To be replaced with the value of the option __string\-varname__\. - - * __@self@__ - - To be replaced with the value of the option __self\-command__\. - - * __@def@__ - - To be replaced with the value of the option __fun\-qualifier__\. - - * __@ns@__ - - To be replaced with the value of the option __namespace__\. - - * __@main@__ - - To be replaced with the value of the option __main__\. - - * __@prelude@__ - - To be replaced with the value of the option __prelude__\. - - - __\-state\-decl__ string - - A C string representing the argument declaration to use in the generated - parsing functions to refer to the parsing state\. In essence type and - argument name\. The default value is the string __RDE\_PARAM p__\. - - - __\-state\-ref__ string - - A C string representing the argument named used in the generated parsing - functions to refer to the parsing state\. The default value is the string - __p__\. - - - __\-self\-command__ string - - A C string representing the reference needed to call the generated parser - function \(methods \.\.\.\) from another parser fonction, per the chosen - framework \(template\)\. The default value is the empty string\. - - - __\-fun\-qualifier__ string - - A C string containing the attributes to give to the generated functions - \(methods \.\.\.\), per the chosen framework \(template\)\. The default value is - __static__\. - - - __\-namespace__ string - - The name of the C namespace the parser functions \(methods, \.\.\.\) shall reside - in, or a general prefix to add to the function names\. The default value is - the empty string\. - - - __\-main__ string - - The name of the main function \(method, \.\.\.\) to be called by the chosen - framework \(template\) to start parsing input\. The default value is - __\_\_main__\. - - - __\-string\-varname__ string - - The name of the variable used for the table of strings used by the generated - parser, i\.e\. error messages, symbol names, etc\. The default value is - __p\_string__\. - - - __\-prelude__ string - - A snippet of code to be inserted at the head of each generated parsing - function\. The default value is the empty string\. - - - __\-indent__ integer - - The number of characters to indent each line of the generated code by\. The - default value is __0__\. - - - __\-comments__ boolean - - A flag controlling the generation of code comments containing the original - parsing expression a parsing function is for\. The default value is - __on__\. - -While the high parameterizability of this converter, as shown by the multitude -of options it supports, is an advantage to the advanced user, allowing her to -customize the output of the converter as needed, a novice user will likely not -see the forest for the trees\. - -To help these latter users an adjunct package is provided, containing a canned -configuration which will generate immediately useful full parsers\. It is - - - __[pt::cparam::configuration::critcl](pt\_cparam\_config\_critcl\.md)__ - - Generated parsers are embedded into a __Critcl__\-based framework\. - -# C/PARAM code representation of parsing expression grammars - -The __c__ format is executable code, a parser for the grammar\. The parser -implementation is written in C and can be tweaked to the users' needs through a -multitude of options\. - -The __critcl__ format, for example, is implemented as a canned configuration -of these options on top of the generator for __c__\. - -The bulk of such a framework has to be specified through the option -__\-template__\. The additional options - - - __\-fun\-qualifier__ string - - - __\-main__ string - - - __\-namespace__ string - - - __\-prelude__ string - - - __\-self\-command__ string - - - __\-state\-decl__ string - - - __\-state\-ref__ string - - - __\-string\-varname__ string - -provide code snippets which help to glue framework and generated code together\. -Their placeholders are in the *generated* code\. Further the options - - - __\-indent__ integer - - - __\-comments__ boolean - -allow for the customization of the code indent \(default none\), and whether to -generate comments showing the parsing expressions a function is for \(default -on\)\. - -## Example - -We are forgoing an example of this representation, with apologies\. It would be -way to large for this document\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[CPARAM](\.\./\.\./\.\./\.\./index\.md\#cparam), -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_json.md @@ -1,610 +0,0 @@ - -[//000000001]: # (pt::peg::to::json \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::json\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::json \- PEG Conversion\. Write JSON format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [JSON Grammar Exchange Format](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::json ?1? -package require pt::peg -package require json::write - -[__pt::peg::to::json__ __reset__](#1) -[__pt::peg::to::json__ __configure__](#2) -[__pt::peg::to::json__ __configure__ *option*](#3) -[__pt::peg::to::json__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::json__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to JSON -markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__[pt::peg::export::json](pt\_peg\_export\_json\.md)__ sitting between -converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::json__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::json__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::json__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::json__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::json__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates JSON markup encoding the grammar, - per the current package configuration\. The created string is then returned - as the result of the command\. - -# Options - -The converter to the JSON grammar exchange format recognizes the following -configuration variables and changes its behaviour as they specify\. - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-indented__ boolean - - If this option is set the system will break the generated JSON across lines - and indent it according to its inner structure, with each key of a - dictionary on a separate line\. - - If the option is not set \(the default\), the whole JSON object will be - written on a single line, with minimum spacing between all elements\. - - - __\-aligned__ boolean - - If this option is set the system will ensure that the values for the keys in - a dictionary are vertically aligned with each other, for a nice table - effect\. To make this work this also implies that __\-indented__ is set\. - - If the option is not set \(the default\), the output is formatted as per the - value of __indented__, without trying to align the values for dictionary - keys\. - -# JSON Grammar Exchange Format - -The __json__ format for parsing expression grammars was written as a data -exchange format not bound to Tcl\. It was defined to allow the exchange of -grammars with PackRat/PEG based parser generators for other languages\. - -It is formally specified by the rules below: - - 1. The JSON of any PEG is a JSON object\. - - 1. This object holds a single key, __pt::grammar::peg__, and its value\. - This value holds the contents of the grammar\. - - 1. The contents of the grammar are a JSON object holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - - __rules__ - - The value is a JSON object whose keys are the names of the nonterminal - symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a JSON object itself\. The relevant - keys and their values in this dictionary are - - * __is__ - - The value is a JSON string holding the Tcl serialization of - the parsing expression describing the symbols sentennial - structure, as specified in the section [PE serialization - format](#section6)\. - - * __mode__ - - The value is a JSON holding holding one of three values - specifying how a parser should handle the semantic value - produced by the symbol\. - - + __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal itself, which has the ASTs of the symbol's - right hand side as its children\. - - + __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node for - the nonterminal, without any children\. Any ASTs generated - by the symbol's right hand side are discarded\. - - + __void__ - - The nonterminal has no semantic value\. Any ASTs generated - by the symbol's right hand side are discarded \(as well\)\. - - - __start__ - - The value is a JSON string holding the Tcl serialization of the start - parsing expression of the grammar, as specified in the section [PE - serialization format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set of - all terminal symbols used in the start expression and on the RHS of the - grammar rules\. - -As an aside to the advanced reader, this is pretty much the same as the Tcl -serialization of PE grammars, as specified in section [PEG serialization -format](#section5), except that the Tcl dictionaries and lists of that -format are mapped to JSON objects and arrays\. Only the parsing expressions -themselves are not translated further, but kept as JSON strings containing a -nested Tcl list, and there is no concept of canonicity for the JSON either\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -a JSON serialization for it is - - { - "pt::grammar::peg" : { - "rules" : { - "AddOp" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Digit" : { - "is" : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}", - "mode" : "value" - }, - "Expression" : { - "is" : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}", - "mode" : "value" - }, - "Factor" : { - "is" : "x {n Term} {* {x {n AddOp} {n Term}}}", - "mode" : "value" - }, - "MulOp" : { - "is" : "\/ {t *} {t \/}", - "mode" : "value" - }, - "Number" : { - "is" : "x {? {n Sign}} {+ {n Digit}}", - "mode" : "value" - }, - "Sign" : { - "is" : "\/ {t -} {t +}", - "mode" : "value" - }, - "Term" : { - "is" : "n Number", - "mode" : "value" - } - }, - "start" : "n Expression" - } - } - -and a Tcl serialization of the same is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -The similarity of the latter to the JSON should be quite obvious\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [JSON](\.\./\.\./\.\./\.\./index\.md\#json), -[LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_param.md @@ -1,1255 +0,0 @@ - -[//000000001]: # (pt::peg::to::param \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::param\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::param \- PEG Conversion\. Write PARAM format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [PARAM code representation of parsing expression grammars](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::param ?1? -package require pt::peg -package require pt::pe - -[__pt::peg::to::param__ __reset__](#1) -[__pt::peg::to::param__ __configure__](#2) -[__pt::peg::to::param__ __configure__ *option*](#3) -[__pt::peg::to::param__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::param__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to PARAM -markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__pt::peg::export::param__ sitting between converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::param__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::param__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::param__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::param__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::param__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates PARAM markup encoding the - grammar, per the current package configuration\. The created string is then - returned as the result of the command\. - -# Options - -The converter to PARAM markup recognizes the following configuration variables -and changes its behaviour as they specify\. - - - __\-template__ string - - The value of this configuration variable is a string into which to put the - generated text and the other configuration settings\. The various locations - for user\-data are expected to be specified with the placeholders listed - below\. The default value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the configuration variable - __\-user__\. - - * __@format@__ - - To be replaced with the the constant __PARAM__\. - - * __@file@__ - - To be replaced with the value of the configuration variable - __\-file__\. - - * __@name@__ - - To be replaced with the value of the configuration variable - __\-name__\. - - * __@code@__ - - To be replaced with the generated text\. - - - __\-name__ string - - The value of this configuration variable is the name of the grammar for - which the conversion is run\. The default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this configuration variable is the name of the user for which - the conversion is run\. The default value is __unknown__\. - - - __\-file__ string - - The value of this configuration variable is the name of the file or other - entity from which the grammar came, for which the conversion is run\. The - default value is __unknown__\. - -# PARAM code representation of parsing expression grammars - -The PARAM code representation of parsing expression grammars is assembler\-like -text using the instructions of the virtual machine documented in the *[PackRat -Machine Specification](pt\_param\.md)*, plus a few more for control flow \(jump -ok, jump fail, call symbol, return\)\. - -It is not really useful, except possibly as a tool demonstrating how a grammar -is compiled in general, without getting distracted by the incidentials of a -framework, i\.e\. like the supporting C and Tcl code generated by the other -PARAM\-derived formats\. - -It has no direct formal specification beyond what was said above\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -one possible PARAM serialization for it is - - # -*- text -*- - # Parsing Expression Grammar 'TEMPLATE'. - # Generated for unknown, from file 'TEST' - - # - # Grammar Start Expression - # - - <
>: - call sym_Expression - halt - - # - # value Symbol 'AddOp' - # - - sym_AddOp: - # / - # '-' - # '+' - - symbol_restore AddOp - found! jump found_7 - loc_push - - call choice_5 - - fail! value_clear - ok! value_leaf AddOp - symbol_save AddOp - error_nonterminal AddOp - loc_pop_discard - - found_7: - ok! ast_value_push - return - - choice_5: - # / - # '-' - # '+' - - error_clear - - loc_push - error_push - - input_next "t -" - ok! test_char "-" - - error_pop_merge - ok! jump oknoast_4 - - loc_pop_rewind - loc_push - error_push - - input_next "t +" - ok! test_char "+" - - error_pop_merge - ok! jump oknoast_4 - - loc_pop_rewind - status_fail - return - - oknoast_4: - loc_pop_discard - return - # - # value Symbol 'Digit' - # - - sym_Digit: - # / - # '0' - # '1' - # '2' - # '3' - # '4' - # '5' - # '6' - # '7' - # '8' - # '9' - - symbol_restore Digit - found! jump found_22 - loc_push - - call choice_20 - - fail! value_clear - ok! value_leaf Digit - symbol_save Digit - error_nonterminal Digit - loc_pop_discard - - found_22: - ok! ast_value_push - return - - choice_20: - # / - # '0' - # '1' - # '2' - # '3' - # '4' - # '5' - # '6' - # '7' - # '8' - # '9' - - error_clear - - loc_push - error_push - - input_next "t 0" - ok! test_char "0" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 1" - ok! test_char "1" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 2" - ok! test_char "2" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 3" - ok! test_char "3" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 4" - ok! test_char "4" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 5" - ok! test_char "5" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 6" - ok! test_char "6" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 7" - ok! test_char "7" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 8" - ok! test_char "8" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - loc_push - error_push - - input_next "t 9" - ok! test_char "9" - - error_pop_merge - ok! jump oknoast_19 - - loc_pop_rewind - status_fail - return - - oknoast_19: - loc_pop_discard - return - # - # value Symbol 'Expression' - # - - sym_Expression: - # / - # x - # '\(' - # (Expression) - # '\)' - # x - # (Factor) - # * - # x - # (MulOp) - # (Factor) - - symbol_restore Expression - found! jump found_46 - loc_push - ast_push - - call choice_44 - - fail! value_clear - ok! value_reduce Expression - symbol_save Expression - error_nonterminal Expression - ast_pop_rewind - loc_pop_discard - - found_46: - ok! ast_value_push - return - - choice_44: - # / - # x - # '\(' - # (Expression) - # '\)' - # x - # (Factor) - # * - # x - # (MulOp) - # (Factor) - - error_clear - - ast_push - loc_push - error_push - - call sequence_27 - - error_pop_merge - ok! jump ok_43 - - ast_pop_rewind - loc_pop_rewind - ast_push - loc_push - error_push - - call sequence_40 - - error_pop_merge - ok! jump ok_43 - - ast_pop_rewind - loc_pop_rewind - status_fail - return - - ok_43: - ast_pop_discard - loc_pop_discard - return - - sequence_27: - # x - # '\(' - # (Expression) - # '\)' - - loc_push - error_clear - - error_push - - input_next "t (" - ok! test_char "(" - - error_pop_merge - fail! jump failednoast_29 - ast_push - error_push - - call sym_Expression - - error_pop_merge - fail! jump failed_28 - error_push - - input_next "t )" - ok! test_char ")" - - error_pop_merge - fail! jump failed_28 - - ast_pop_discard - loc_pop_discard - return - - failed_28: - ast_pop_rewind - - failednoast_29: - loc_pop_rewind - return - - sequence_40: - # x - # (Factor) - # * - # x - # (MulOp) - # (Factor) - - ast_push - loc_push - error_clear - - error_push - - call sym_Factor - - error_pop_merge - fail! jump failed_41 - error_push - - call kleene_37 - - error_pop_merge - fail! jump failed_41 - - ast_pop_discard - loc_pop_discard - return - - failed_41: - ast_pop_rewind - loc_pop_rewind - return - - kleene_37: - # * - # x - # (MulOp) - # (Factor) - - loc_push - error_push - - call sequence_34 - - error_pop_merge - fail! jump failed_38 - loc_pop_discard - jump kleene_37 - - failed_38: - loc_pop_rewind - status_ok - return - - sequence_34: - # x - # (MulOp) - # (Factor) - - ast_push - loc_push - error_clear - - error_push - - call sym_MulOp - - error_pop_merge - fail! jump failed_35 - error_push - - call sym_Factor - - error_pop_merge - fail! jump failed_35 - - ast_pop_discard - loc_pop_discard - return - - failed_35: - ast_pop_rewind - loc_pop_rewind - return - # - # value Symbol 'Factor' - # - - sym_Factor: - # x - # (Term) - # * - # x - # (AddOp) - # (Term) - - symbol_restore Factor - found! jump found_60 - loc_push - ast_push - - call sequence_57 - - fail! value_clear - ok! value_reduce Factor - symbol_save Factor - error_nonterminal Factor - ast_pop_rewind - loc_pop_discard - - found_60: - ok! ast_value_push - return - - sequence_57: - # x - # (Term) - # * - # x - # (AddOp) - # (Term) - - ast_push - loc_push - error_clear - - error_push - - call sym_Term - - error_pop_merge - fail! jump failed_58 - error_push - - call kleene_54 - - error_pop_merge - fail! jump failed_58 - - ast_pop_discard - loc_pop_discard - return - - failed_58: - ast_pop_rewind - loc_pop_rewind - return - - kleene_54: - # * - # x - # (AddOp) - # (Term) - - loc_push - error_push - - call sequence_51 - - error_pop_merge - fail! jump failed_55 - loc_pop_discard - jump kleene_54 - - failed_55: - loc_pop_rewind - status_ok - return - - sequence_51: - # x - # (AddOp) - # (Term) - - ast_push - loc_push - error_clear - - error_push - - call sym_AddOp - - error_pop_merge - fail! jump failed_52 - error_push - - call sym_Term - - error_pop_merge - fail! jump failed_52 - - ast_pop_discard - loc_pop_discard - return - - failed_52: - ast_pop_rewind - loc_pop_rewind - return - # - # value Symbol 'MulOp' - # - - sym_MulOp: - # / - # '*' - # '/' - - symbol_restore MulOp - found! jump found_67 - loc_push - - call choice_65 - - fail! value_clear - ok! value_leaf MulOp - symbol_save MulOp - error_nonterminal MulOp - loc_pop_discard - - found_67: - ok! ast_value_push - return - - choice_65: - # / - # '*' - # '/' - - error_clear - - loc_push - error_push - - input_next "t *" - ok! test_char "*" - - error_pop_merge - ok! jump oknoast_64 - - loc_pop_rewind - loc_push - error_push - - input_next "t /" - ok! test_char "/" - - error_pop_merge - ok! jump oknoast_64 - - loc_pop_rewind - status_fail - return - - oknoast_64: - loc_pop_discard - return - # - # value Symbol 'Number' - # - - sym_Number: - # x - # ? - # (Sign) - # + - # (Digit) - - symbol_restore Number - found! jump found_80 - loc_push - ast_push - - call sequence_77 - - fail! value_clear - ok! value_reduce Number - symbol_save Number - error_nonterminal Number - ast_pop_rewind - loc_pop_discard - - found_80: - ok! ast_value_push - return - - sequence_77: - # x - # ? - # (Sign) - # + - # (Digit) - - ast_push - loc_push - error_clear - - error_push - - call optional_70 - - error_pop_merge - fail! jump failed_78 - error_push - - call poskleene_73 - - error_pop_merge - fail! jump failed_78 - - ast_pop_discard - loc_pop_discard - return - - failed_78: - ast_pop_rewind - loc_pop_rewind - return - - optional_70: - # ? - # (Sign) - - loc_push - error_push - - call sym_Sign - - error_pop_merge - fail! loc_pop_rewind - ok! loc_pop_discard - status_ok - return - - poskleene_73: - # + - # (Digit) - - loc_push - - call sym_Digit - - fail! jump failed_74 - - loop_75: - loc_pop_discard - loc_push - error_push - - call sym_Digit - - error_pop_merge - ok! jump loop_75 - status_ok - - failed_74: - loc_pop_rewind - return - # - # value Symbol 'Sign' - # - - sym_Sign: - # / - # '-' - # '+' - - symbol_restore Sign - found! jump found_86 - loc_push - - call choice_5 - - fail! value_clear - ok! value_leaf Sign - symbol_save Sign - error_nonterminal Sign - loc_pop_discard - - found_86: - ok! ast_value_push - return - # - # value Symbol 'Term' - # - - sym_Term: - # (Number) - - symbol_restore Term - found! jump found_89 - loc_push - ast_push - - call sym_Number - - fail! value_clear - ok! value_reduce Term - symbol_save Term - error_nonterminal Term - ast_pop_rewind - loc_pop_discard - - found_89: - ok! ast_value_push - return - - # - # - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PARAM](\.\./\.\./\.\./\.\./index\.md\#param), [PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_peg.md @@ -1,597 +0,0 @@ - -[//000000001]: # (pt::peg::to::peg \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::peg\(n\) 1\.0\.2 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::peg \- PEG Conversion\. Write PEG format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [PEG Specification Language](#section4) - - - [Example](#subsection1) - - - [PEG serialization format](#section5) - - - [Example](#subsection2) - - - [PE serialization format](#section6) - - - [Example](#subsection3) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::peg ?1\.0\.2? -package require pt::peg -package require pt::pe -package require text::write - -[__pt::peg::to::peg__ __reset__](#1) -[__pt::peg::to::peg__ __configure__](#2) -[__pt::peg::to::peg__ __configure__ *option*](#3) -[__pt::peg::to::peg__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::peg__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to PEG -markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__[pt::peg::export::peg](pt\_peg\_export\_peg\.md)__ sitting between -converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::peg__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::peg__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::peg__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::peg__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::peg__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates PEG markup encoding the grammar, - per the current package configuration\. The created string is then returned - as the result of the command\. - -# Options - -The converter to the PEG language recognizes the following options and changes -its behaviour as they specify\. - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - - - __\-template__ string - - The value of this option is a string into which to put the generated text - and the values of the other options\. The various locations for user\-data are - expected to be specified with the placeholders listed below\. The default - value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the option __\-user__\. - - * __@format@__ - - To be replaced with the the constant __PEG__\. - - * __@file@__ - - To be replaced with the value of the option __\-file__\. - - * __@name@__ - - To be replaced with the value of the option __\-name__\. - - * __@code@__ - - To be replaced with the generated text\. - -# PEG Specification Language - -__peg__, a language for the specification of parsing expression grammars is -meant to be human readable, and writable as well, yet strict enough to allow its -processing by machine\. Like any computer language\. It was defined to make -writing the specification of a grammar easy, something the other formats found -in the Parser Tools do not lend themselves too\. - -It is formally specified by the grammar shown below, written in itself\. For a -tutorial / introduction to the language please go and read the *[PEG Language -Tutorial](pt\_peg\_language\.md)*\. - - PEG pe-grammar-for-peg (Grammar) - - # -------------------------------------------------------------------- - # Syntactical constructs - - Grammar <- WHITESPACE Header Definition* Final EOF ; - - Header <- PEG Identifier StartExpr ; - Definition <- Attribute? Identifier IS Expression SEMICOLON ; - Attribute <- (VOID / LEAF) COLON ; - Expression <- Sequence (SLASH Sequence)* ; - Sequence <- Prefix+ ; - Prefix <- (AND / NOT)? Suffix ; - Suffix <- Primary (QUESTION / STAR / PLUS)? ; - Primary <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT - / GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER - / WORDCHAR / XDIGIT - / Identifier - / OPEN Expression CLOSE - / Literal - / Class - / DOT - ; - Literal <- APOSTROPH (!APOSTROPH Char)* APOSTROPH WHITESPACE - / DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ; - Class <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ; - Range <- Char TO Char / Char ; - - StartExpr <- OPEN Expression CLOSE ; - void: Final <- "END" WHITESPACE SEMICOLON WHITESPACE ; - - # -------------------------------------------------------------------- - # Lexing constructs - - Identifier <- Ident WHITESPACE ; - leaf: Ident <- ([_:] / ) ([_:] / )* ; - Char <- CharSpecial / CharOctalFull / CharOctalPart - / CharUnicode / CharUnescaped - ; - - leaf: CharSpecial <- "\\" [nrt'"\[\]\\] ; - leaf: CharOctalFull <- "\\" [0-2][0-7][0-7] ; - leaf: CharOctalPart <- "\\" [0-7][0-7]? ; - leaf: CharUnicode <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ; - leaf: CharUnescaped <- !"\\" . ; - - void: HexDigit <- [0-9a-fA-F] ; - - void: TO <- '-' ; - void: OPENB <- "[" ; - void: CLOSEB <- "]" ; - void: APOSTROPH <- "'" ; - void: DAPOSTROPH <- '"' ; - void: PEG <- "PEG" !([_:] / ) WHITESPACE ; - void: IS <- "<-" WHITESPACE ; - leaf: VOID <- "void" WHITESPACE ; # Implies that definition has no semantic value. - leaf: LEAF <- "leaf" WHITESPACE ; # Implies that definition has no terminals. - void: SEMICOLON <- ";" WHITESPACE ; - void: COLON <- ":" WHITESPACE ; - void: SLASH <- "/" WHITESPACE ; - leaf: AND <- "&" WHITESPACE ; - leaf: NOT <- "!" WHITESPACE ; - leaf: QUESTION <- "?" WHITESPACE ; - leaf: STAR <- "*" WHITESPACE ; - leaf: PLUS <- "+" WHITESPACE ; - void: OPEN <- "(" WHITESPACE ; - void: CLOSE <- ")" WHITESPACE ; - leaf: DOT <- "." WHITESPACE ; - - leaf: ALNUM <- "" WHITESPACE ; - leaf: ALPHA <- "" WHITESPACE ; - leaf: ASCII <- "" WHITESPACE ; - leaf: CONTROL <- "" WHITESPACE ; - leaf: DDIGIT <- "" WHITESPACE ; - leaf: DIGIT <- "" WHITESPACE ; - leaf: GRAPH <- "" WHITESPACE ; - leaf: LOWER <- "" WHITESPACE ; - leaf: PRINTABLE <- "" WHITESPACE ; - leaf: PUNCT <- "" WHITESPACE ; - leaf: SPACE <- "" WHITESPACE ; - leaf: UPPER <- "" WHITESPACE ; - leaf: WORDCHAR <- "" WHITESPACE ; - leaf: XDIGIT <- "" WHITESPACE ; - - void: WHITESPACE <- (" " / "\t" / EOL / COMMENT)* ; - void: COMMENT <- '#' (!EOL .)* EOL ; - void: EOL <- "\n\r" / "\n" / "\r" ; - void: EOF <- !. ; - - # -------------------------------------------------------------------- - END; - -## Example - -Our example specifies the grammar for a basic 4\-operation calculator\. - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -Using higher\-level features of the notation, i\.e\. the character classes -\(predefined and custom\), this example can be rewritten as - - PEG calculator (Expression) - Sign <- [-+] ; - Number <- Sign? + ; - Expression <- '(' Expression ')' / (Factor (MulOp Factor)*) ; - MulOp <- [*/] ; - Factor <- Term (AddOp Term)* ; - AddOp <- [-+] ; - Term <- Number ; - END; - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md Index: embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md +++ embedded/md/tcllib/files/modules/pt/pt_peg_to_tclparam.md @@ -1,585 +0,0 @@ - -[//000000001]: # (pt::peg::to::tclparam \- Parser Tools) -[//000000002]: # (Generated from file 'to\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg::to::tclparam\(n\) 1\.0\.3 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg::to::tclparam \- PEG Conversion\. Write TCLPARAM format - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [Tcl/PARAM code representation of parsing expression - grammars](#section4) - - - [PEG serialization format](#section5) - - - [Example](#subsection1) - - - [PE serialization format](#section6) - - - [Example](#subsection2) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg::to::tclparam ?1\.0\.3? - -[__pt::peg::to::tclparam__ __reset__](#1) -[__pt::peg::to::tclparam__ __configure__](#2) -[__pt::peg::to::tclparam__ __configure__ *option*](#3) -[__pt::peg::to::tclparam__ __configure__ *option* *value*\.\.\.](#4) -[__pt::peg::to::tclparam__ __convert__ *serial*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package implements the converter from parsing expression grammars to -TCLPARAM markup\. - -It resides in the Export section of the Core Layer of Parser Tools, and can be -used either directly with the other packages of this layer, or indirectly -through the export manager provided by -__[pt::peg::export](pt\_peg\_export\.md)__\. The latter is intented for use -in untrusted environments and done through the corresponding export plugin -__pt::peg::export::tclparam__ sitting between converter and export manager\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_eplugins\.png) - -# API - -The API provided by this package satisfies the specification of the Converter -API found in the *[Parser Tools Export API](pt\_to\_api\.md)* specification\. - - - __pt::peg::to::tclparam__ __reset__ - - This command resets the configuration of the package to its default - settings\. - - - __pt::peg::to::tclparam__ __configure__ - - This command returns a dictionary containing the current configuration of - the package\. - - - __pt::peg::to::tclparam__ __configure__ *option* - - This command returns the current value of the specified configuration - *option* of the package\. For the set of legal options, please read the - section [Options](#section3)\. - - - __pt::peg::to::tclparam__ __configure__ *option* *value*\.\.\. - - This command sets the given configuration *option*s of the package, to the - specified *value*s\. For the set of legal options, please read the section - [Options](#section3)\. - - - __pt::peg::to::tclparam__ __convert__ *serial* - - This command takes the canonical serialization of a parsing expression - grammar, as specified in section [PEG serialization format](#section5), - and contained in *serial*, and generates TCLPARAM markup encoding the - grammar, per the current package configuration\. The created string is then - returned as the result of the command\. - -# Options - -The converter to Tcl/PARAM markup recognizes the following configuration -variables and changes its behaviour as they specify\. - - - __\-template__ string - - The value of this configuration variable is a string into which to put the - generated text and the other configuration settings\. The various locations - for user\-data are expected to be specified with the placeholders listed - below\. The default value is "__@code@__"\. - - * __@user@__ - - To be replaced with the value of the configuration variable - __\-user__\. - - * __@format@__ - - To be replaced with the the constant __Tcl/PARAM__\. - - * __@file@__ - - To be replaced with the value of the configuration variable - __\-file__\. - - * __@name@__ - - To be replaced with the value of the configuration variable - __\-name__\. - - * __@code@__ - - To be replaced with the generated Tcl code\. - - The following configuration variables are special, in that they will occur - within the generated code, and are replaced there as well\. - - * __@runtime@__ - - To be replaced with the value of the configuration variable - __runtime\-command__\. - - * __@self@__ - - To be replaced with the value of the configuration variable - __self\-command__\. - - * __@def@__ - - To be replaced with the value of the configuration variable - __proc\-command__\. - - * __@ns@__ - - To be replaced with the value of the configuration variable - __namespace__\. - - * __@main@__ - - To be replaced with the value of the configuration variable - __main__\. - - * __@prelude@__ - - To be replaced with the value of the configuration variable - __prelude__\. - - - __\-name__ string - - The value of this configuration variable is the name of the grammar for - which the conversion is run\. The default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this configuration variable is the name of the user for which - the conversion is run\. The default value is __unknown__\. - - - __\-file__ string - - The value of this configuration variable is the name of the file or other - entity from which the grammar came, for which the conversion is run\. The - default value is __unknown__\. - - - __\-runtime\-command__ string - - A Tcl string representing the Tcl command or reference to it used to call - PARAM instruction from parser procedures, per the chosen framework - \(template\)\. The default value is the empty string\. - - - __\-self\-command__ string - - A Tcl string representing the Tcl command or reference to it used to call - the parser procedures \(methods \.\.\.\) from another parser procedure, per the - chosen framework \(template\)\. The default value is the empty string\. - - - __\-proc\-command__ string - - The name of the Tcl command used to define procedures \(methods \.\.\.\), per the - chosen framework \(template\)\. The default value is __proc__\. - - - __\-namespace__ string - - The name of the namespace the parser procedures \(methods, \.\.\.\) shall reside - in, including the trailing '::' needed to separate it from the actual - procedure name\. The default value is __::__\. - - - __\-main__ string - - The name of the main procedure \(method, \.\.\.\) to be called by the chosen - framework \(template\) to start parsing input\. The default value is - __\_\_main__\. - - - __\-prelude__ string - - A snippet of code to be insert at the head of each generated parsing - command\. The default value is the empty string\. - - - __\-indent__ integer - - The number of characters to indent each line of the generated code by\. The - default value is __0__\. - -While the high parameterizability of this converter, as shown by the multitude -of options it supports, is an advantage to the advanced user, allowing her to -customize the output of the converter as needed, a novice user will likely not -see the forest for the trees\. - -To help these latter users two adjunct packages are provided, each containing a -canned configuration which will generate immediately useful full parsers\. These -are - - - __[pt::tclparam::configuration::snit](pt\_tclparam\_config\_snit\.md)__ - - Generated parsers are classes based on the - __[snit](\.\./snit/snit\.md)__ package, i\.e\. snit::type's\. - - - __[pt::tclparam::configuration::tcloo](pt\_tclparam\_config\_tcloo\.md)__ - - Generated parsers are classes based on the - __[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__ package\. - -# Tcl/PARAM code representation of parsing expression grammars - -The Tcl/PARAM representation of parsing expression grammars is Tcl code whose -execution will parse input per the grammar\. The code is based on the virtual -machine documented in the *[PackRat Machine Specification](pt\_param\.md)*, -using its instructions and a few more to handle control flow\. - -Note that the generated code by itself is not functional\. It expects to be -embedded into a framework which provides services like the PARAM state, -implementations for the PARAM instructions, etc\. The bulk of such a framework -has to be specified through the option __\-template__\. The additional options - - - __\-indent__ integer - - - __\-main__ string - - - __\-namespace__ string - - - __\-prelude__ string - - - __\-proc\-command__ string - - - __\-runtime\-command__ string - - - __\-self\-command__ string - -provide code snippets which help to glue framework and generated code together\. -Their placeholders are in the *generated* code\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section6)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section6)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), -[TCLPARAM](\.\./\.\./\.\./\.\./index\.md\#tclparam), -[TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), [context\-free -languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), [format -conversion](\.\./\.\./\.\./\.\./index\.md\#format\_conversion), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_pegrammar.md Index: embedded/md/tcllib/files/modules/pt/pt_pegrammar.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_pegrammar.md +++ embedded/md/tcllib/files/modules/pt/pt_pegrammar.md @@ -1,455 +0,0 @@ - -[//000000001]: # (pt::peg \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_pegrammar\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::peg\(n\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::peg \- Parsing Expression Grammar Serialization - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [PEG serialization format](#section3) - - - [Example](#subsection1) - - - [PE serialization format](#section4) - - - [Example](#subsection2) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::peg ?1? -package require pt::pe - -[__::pt::peg__ __verify__ *serial* ?*canonvar*?](#1) -[__::pt::peg__ __verify\-as\-canonical__ *serial*](#2) -[__::pt::peg__ __canonicalize__ *serial*](#3) -[__::pt::peg__ __print__ *serial*](#4) -[__::pt::peg__ __merge__ *seriala* *serialb*](#5) -[__::pt::peg__ __equal__ *seriala* *serialb*](#6) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides commands to work with the serializations of parsing -expression grammars as managed by the Parser Tools, and specified in section -[PEG serialization format](#section3)\. - -This is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::peg__ __verify__ *serial* ?*canonvar*? - - This command verifies that the content of *serial* is a valid - serialization of a parsing expression and will throw an error if that is not - the case\. The result of the command is the empty string\. - - If the argument *canonvar* is specified it is interpreted as the name of a - variable in the calling context\. This variable will be written to if and - only if *serial* is a valid regular serialization\. Its value will be a - boolean, with __True__ indicating that the serialization is not only - valid, but also *canonical*\. __False__ will be written for a valid, - but non\-canonical serialization\. - - For the specification of serializations see the section [PE serialization - format](#section4)\. - - - __::pt::peg__ __verify\-as\-canonical__ *serial* - - This command verifies that the content of *serial* is a valid - *canonical* serialization of a PEG and will throw an error if that is not - the case\. The result of the command is the empty string\. - - For the specification of canonical serializations see the section [PEG - serialization format](#section3)\. - - - __::pt::peg__ __canonicalize__ *serial* - - This command assumes that the content of *serial* is a valid *regular* - serialization of a PEG and will throw an error if that is not the case\. - - It will then convert the input into the *canonical* serialization of the - contained PEG and return it as its result\. If the input is already canonical - it will be returned unchanged\. - - For the specification of regular and canonical serializations see the - section [PEG serialization format](#section3)\. - - - __::pt::peg__ __print__ *serial* - - This command assumes that the argument *serial* contains a valid - serialization of a parsing expression and returns a string containing that - PE in a human readable form\. - - The exact format of this form is not specified and cannot be relied on for - parsing or other machine\-based activities\. - - For the specification of serializations see the section [PEG serialization - format](#section3)\. - - - __::pt::peg__ __merge__ *seriala* *serialb* - - This command accepts the regular serializations of two grammars and uses - them to create their union\. The result of the command is the canonical - serialization of this unified grammar\. - - A merge errors occurs if for any nonterminal symbol S occuring in both input - grammars the two input grammars specify different semantic modes\. - - The semantic mode of each nonterminal symbol S is the semantic mode of S in - any of its input grammars\. The previous rule made sure that for symbols - occuring in both grammars these values are identical\. - - The right\-hand side of each nonterminal symbol S occuring in both input - grammars is the choice between the right\-hand sides of S in the input - grammars, with the parsing expression of S in *seriala* coming first, - except if both expressions are identical\. In that case the first expression - is taken\. - - The right\-hand side of each nonterminal symbol S occuring in only one of the - input grammars is the right\-hand side of S in its input grammar\. - - The start expression of the unified grammar is the choice between the start - expressions of the input grammars, with the start expression of *seriala* - coming first, except if both expressions are identical\. In that case the - first expression is taken - - - __::pt::peg__ __equal__ *seriala* *serialb* - - This command tests the two grammars *seriala* and *serialb* for - structural equality\. The result of the command is a boolean value\. It will - be set to __true__ if the expressions are identical, and __false__ - otherwise\. - - String equality is usable only if we can assume that the two grammars are - pure Tcl lists and dictionaries\. - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section4)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section4)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md Index: embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md +++ embedded/md/tcllib/files/modules/pt/pt_pexpr_op.md @@ -1,288 +0,0 @@ - -[//000000001]: # (pt::pe::op \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_pexpr\_op\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::pe::op\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::pe::op \- Parsing Expression Utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [PE serialization format](#section3) - - - [Example](#subsection1) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::pe::op ?1\.0\.1? -package require pt::pe ?1? -package require struct::set - -[__::pt::pe::op__ __drop__ *dropset* *pe*](#1) -[__::pt::pe::op__ __rename__ *nt* *ntnew* *pe*](#2) -[__::pt::pe::op__ __called__ *pe*](#3) -[__::pt::pe::op__ __flatten__ *pe*](#4) -[__::pt::pe::op__ __fusechars__ *pe*](#5) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides additional commands to work with the serializations of -parsing expressions as managed by the PEG and related packages, and specified in -section [PE serialization format](#section3)\. - -This is an internal package, for use by the higher level packages handling PEGs, -their conversion into and out of various other formats, or other uses\. - -# API - - - __::pt::pe::op__ __drop__ *dropset* *pe* - - This command removes all occurences of any of the nonterminals symbols in - the set *dropset* from the parsing expression *pe*, and simplifies it\. - This may result in the expression becoming "epsilon", i\.e\. matching nothing\. - - - __::pt::pe::op__ __rename__ *nt* *ntnew* *pe* - - This command renames all occurences of the nonterminal *nt* in the parsing - expression *pe* into *ntnew*\. - - - __::pt::pe::op__ __called__ *pe* - - This command extracts the set of all nonterminal symbols used, i\.e\. - 'called', in the parsing expression *pe*\. - - - __::pt::pe::op__ __flatten__ *pe* - - This command transforms the parsing expression by eliminating sequences - nested in sequences, and choices in choices, lifting the children of the - nested expression into the parent\. It further eliminates all sequences and - choices with only one child, as these are redundant\. - - The resulting parsing expression is returned as the result of the command\. - - - __::pt::pe::op__ __fusechars__ *pe* - - This command transforms the parsing expression by fusing adjacent terminals - in sequences and adjacent terminals and ranges in choices, it \(re\)constructs - highlevel *strings* and *character classes*\. - - The resulting pseudo\-parsing expression is returned as the result of the - command and may contain the pseudo\-operators __str__ for character - sequences, aka strings, and __cl__ for character choices, aka character - classes\. - - The result is called a *pseudo\-parsing expression* because it is not a - true parsing expression anymore, and will fail a check with __::pt::peg - verify__ if the new pseudo\-operators are present in the result, but is - otherwise of sound structure for a parsing expression\. Notably, the commands - __::pt::peg bottomup__ and __::pt::peg topdown__ will process them - without trouble\. - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_pexpression.md Index: embedded/md/tcllib/files/modules/pt/pt_pexpression.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_pexpression.md +++ embedded/md/tcllib/files/modules/pt/pt_pexpression.md @@ -1,487 +0,0 @@ - -[//000000001]: # (pt::pe \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_pexpression\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::pe\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::pe \- Parsing Expression Serialization - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [PE serialization format](#section3) - - - [Example](#subsection1) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::pe ?1\.0\.1? -package require char - -[__::pt::pe__ __verify__ *serial* ?*canonvar*?](#1) -[__::pt::pe__ __verify\-as\-canonical__ *serial*](#2) -[__::pt::pe__ __canonicalize__ *serial*](#3) -[__::pt::pe__ __print__ *serial*](#4) -[__::pt::pe__ __bottomup__ *cmdprefix* *pe*](#5) -[__cmdprefix__ *pe* *op* *arguments*](#6) -[__::pt::pe__ __topdown__ *cmdprefix* *pe*](#7) -[__::pt::pe__ __equal__ *seriala* *serialb*](#8) -[__::pt::pe__ __epsilon__](#9) -[__::pt::pe__ __dot__](#10) -[__::pt::pe__ __alnum__](#11) -[__::pt::pe__ __alpha__](#12) -[__::pt::pe__ __ascii__](#13) -[__::pt::pe__ __control__](#14) -[__::pt::pe__ __digit__](#15) -[__::pt::pe__ __graph__](#16) -[__::pt::pe__ __lower__](#17) -[__::pt::pe__ __print__](#18) -[__::pt::pe__ __punct__](#19) -[__::pt::pe__ __space__](#20) -[__::pt::pe__ __upper__](#21) -[__::pt::pe__ __wordchar__](#22) -[__::pt::pe__ __xdigit__](#23) -[__::pt::pe__ __ddigit__](#24) -[__::pt::pe__ __terminal__ *t*](#25) -[__::pt::pe__ __range__ *ta* *tb*](#26) -[__::pt::pe__ __nonterminal__ *nt*](#27) -[__::pt::pe__ __choice__ *pe*\.\.\.](#28) -[__::pt::pe__ __sequence__ *pe*\.\.\.](#29) -[__::pt::pe__ __repeat0__ *pe*](#30) -[__::pt::pe__ __repeat1__ *pe*](#31) -[__::pt::pe__ __optional__ *pe*](#32) -[__::pt::pe__ __ahead__ *pe*](#33) -[__::pt::pe__ __notahead__ *pe*](#34) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides commands to work with the serializations of parsing -expressions as managed by the Parser Tools, and specified in section [PE -serialization format](#section3)\. - -This is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::pe__ __verify__ *serial* ?*canonvar*? - - This command verifies that the content of *serial* is a valid - serialization of a parsing expression and will throw an error if that is not - the case\. The result of the command is the empty string\. - - If the argument *canonvar* is specified it is interpreted as the name of a - variable in the calling context\. This variable will be written to if and - only if *serial* is a valid regular serialization\. Its value will be a - boolean, with __True__ indicating that the serialization is not only - valid, but also *canonical*\. __False__ will be written for a valid, - but non\-canonical serialization\. - - For the specification of serializations see the section [PE serialization - format](#section3)\. - - - __::pt::pe__ __verify\-as\-canonical__ *serial* - - This command verifies that the content of *serial* is a valid - *canonical* serialization of a parsing expression and will throw an error - if that is not the case\. The result of the command is the empty string\. - - For the specification of canonical serializations see the section [PE - serialization format](#section3)\. - - - __::pt::pe__ __canonicalize__ *serial* - - This command assumes that the content of *serial* is a valid *regular* - serialization of a parsing expression and will throw an error if that is not - the case\. - - It will then convert the input into the *canonical* serialization of this - parsing expression and return it as its result\. If the input is already - canonical it will be returned unchanged\. - - For the specification of regular and canonical serializations see the - section [PE serialization format](#section3)\. - - - __::pt::pe__ __print__ *serial* - - This command assumes that the argument *serial* contains a valid - serialization of a parsing expression and returns a string containing that - PE in a human readable form\. - - The exact format of this form is not specified and cannot be relied on for - parsing or other machine\-based activities\. - - For the specification of serializations see the section [PE serialization - format](#section3)\. - - - __::pt::pe__ __bottomup__ *cmdprefix* *pe* - - This command walks the parsing expression *pe* from the bottom up to the - root, invoking the command prefix *cmdprefix* for each partial expression\. - This implies that the children of a parsing expression PE are handled before - PE\. - - The command prefix has the signature - - * __cmdprefix__ *pe* *op* *arguments* - - I\.e\. it is invoked with the parsing expression *pe* the walk is - currently at, the *op*'erator in the *pe*, and the operator's - *arguments*\. - - The result returned by the command prefix replaces *pe* in the parsing - expression it was a child of, allowing transformations of the expression - tree\. - - This also means that for all inner parsing expressions the contents of - *arguments* are the results of the command prefix invoked for the - children of this inner parsing expression\. - - - __::pt::pe__ __topdown__ *cmdprefix* *pe* - - This command walks the parsing expression *pe* from the root down to the - leaves, invoking the command prefix *cmdprefix* for each partial - expression\. This implies that the children of a parsing expression PE are - handled after PE\. - - The command prefix has the same signature as for __bottomup__, see - above\. - - The result returned by the command prefix is *ignored*\. - - - __::pt::pe__ __equal__ *seriala* *serialb* - - This command tests the two parsing expressions *seriala* and *serialb* - for structural equality\. The result of the command is a boolean value\. It - will be set to __true__ if the expressions are identical, and - __false__ otherwise\. - - String equality is usable only if we can assume that the two parsing - expressions are pure Tcl lists\. - - - __::pt::pe__ __epsilon__ - - This command constructs the atomic parsing expression for epsilon\. - - - __::pt::pe__ __dot__ - - This command constructs the atomic parsing expression for dot\. - - - __::pt::pe__ __alnum__ - - This command constructs the atomic parsing expression for alnum\. - - - __::pt::pe__ __alpha__ - - This command constructs the atomic parsing expression for alpha\. - - - __::pt::pe__ __ascii__ - - This command constructs the atomic parsing expression for ascii\. - - - __::pt::pe__ __control__ - - This command constructs the atomic parsing expression for control\. - - - __::pt::pe__ __digit__ - - This command constructs the atomic parsing expression for digit\. - - - __::pt::pe__ __graph__ - - This command constructs the atomic parsing expression for graph\. - - - __::pt::pe__ __lower__ - - This command constructs the atomic parsing expression for lower\. - - - __::pt::pe__ __print__ - - This command constructs the atomic parsing expression for print\. - - - __::pt::pe__ __punct__ - - This command constructs the atomic parsing expression for punct\. - - - __::pt::pe__ __space__ - - This command constructs the atomic parsing expression for space\. - - - __::pt::pe__ __upper__ - - This command constructs the atomic parsing expression for upper\. - - - __::pt::pe__ __wordchar__ - - This command constructs the atomic parsing expression for wordchar\. - - - __::pt::pe__ __xdigit__ - - This command constructs the atomic parsing expression for xdigit\. - - - __::pt::pe__ __ddigit__ - - This command constructs the atomic parsing expression for ddigit\. - - - __::pt::pe__ __terminal__ *t* - - This command constructs the atomic parsing expression for the terminal - symbol *t*\. - - - __::pt::pe__ __range__ *ta* *tb* - - This command constructs the atomic parsing expression for the range of - terminal symbols *ta* \.\.\. *tb*\. - - - __::pt::pe__ __nonterminal__ *nt* - - This command constructs the atomic parsing expression for the nonterminal - symbol *nt*\. - - - __::pt::pe__ __choice__ *pe*\.\.\. - - This command constructs the parsing expression representing the ordered or - prioritized choice between the argument parsing expressions\. The first - argument has the highest priority\. - - - __::pt::pe__ __sequence__ *pe*\.\.\. - - This command constructs the parsing expression representing the sequence of - the argument parsing expression\. The first argument is the first element of - the sequence\. - - - __::pt::pe__ __repeat0__ *pe* - - This command constructs the parsing expression representing the zero or more - repetition of the argument parsing expression *pe*, also known as the - kleene closure\. - - - __::pt::pe__ __repeat1__ *pe* - - This command constructs the parsing expression representing the one or more - repetition of the argument parsing expression *pe*, also known as the - positive kleene closure\. - - - __::pt::pe__ __optional__ *pe* - - This command constructs the parsing expression representing the optionality - of the argument parsing expression *pe*\. - - - __::pt::pe__ __ahead__ *pe* - - This command constructs the parsing expression representing the positive - lookahead of the argument parsing expression *pe*\. - - - __::pt::pe__ __notahead__ *pe* - - This command constructs the parsing expression representing the negative - lookahead of the argument parsing expression *pe*\. - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_pgen.md Index: embedded/md/tcllib/files/modules/pt/pt_pgen.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_pgen.md +++ embedded/md/tcllib/files/modules/pt/pt_pgen.md @@ -1,260 +0,0 @@ - -[//000000001]: # (pt::pgen \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_pgen\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::pgen\(n\) 1\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::pgen \- Parser Generator - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Example](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::pgen ?1\.1? - -[__::pt::pgen__ *inputformat* *text* *resultformat* ?*options\.\.\.*?](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a command implementing a *[parser -generator](\.\./\.\./\.\./\.\./index\.md\#parser\_generator)* taking parsing expression -grammars as input\. - -It is the implementation of method __generate__ of -__[pt](\.\./\.\./apps/pt\.md)__, the *[Parser Tools -Application](\.\./\.\./apps/pt\.md)*\. - -As such the intended audience of this document are people wishing to modify -and/or extend this part of __[pt](\.\./\.\./apps/pt\.md)__'s functionality\. -Users of __[pt](\.\./\.\./apps/pt\.md)__ on the other hand are hereby refered -to the applications' manpage, i\.e\. *[Parser Tools -Application](\.\./\.\./apps/pt\.md)*\. - -It resides in the User Package Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_user\_pkg\.png) - -# API - - - __::pt::pgen__ *inputformat* *text* *resultformat* ?*options\.\.\.*? - - This command takes the parsing expression grammar in *text* \(in the format - specified by *inputformat*\), and returns the same grammar in the format - *resultformat* as the result of the command\. - - The two known input formats are __peg__ and __json__\. Introductions - to them, including their formal specifications, can be found in the *[PEG - Language Tutorial](pt\_peg\_language\.md)* and *[The JSON Grammar - Exchange Format](pt\_json\_language\.md)*\. The packages used to parse these - formats are - - * __peg__ - - __[pt::peg::from::peg](pt\_peg\_from\_peg\.md)__ - - * __json__ - - __[pt::peg::from::json](pt\_peg\_from\_json\.md)__ - - On the output side the known formats, and the packages used to generate them - are - - * __c__ - - __[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ - - * __container__ - - __[pt::peg::to::container](pt\_peg\_to\_container\.md)__ - - * __critcl__ - - __[pt::peg::to::cparam](pt\_peg\_to\_cparam\.md)__ \+ - __[pt::cparam::configuration::critcl](pt\_cparam\_config\_critcl\.md)__ - - * __json__ - - __[pt::peg::to::json](pt\_peg\_to\_json\.md)__ - - * __oo__ - - __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ \+ - __[pt::tclparam::configuration::tcloo](pt\_tclparam\_config\_tcloo\.md)__ - - * __peg__ - - __[pt::peg::to::peg](pt\_peg\_to\_peg\.md)__ - - * __snit__ - - __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ \+ - __[pt::tclparam::configuration::snit](pt\_tclparam\_config\_snit\.md)__ - - The options supported by each of these formats are documented with their - respective packages\. - -# Example - -In this section we are working a complete example, starting with a PEG grammar -and ending with running the parser generated from it over some input, following -the outline shown in the figure below: - -![](\.\./\.\./\.\./\.\./image/flow\.png) Our grammar, assumed to the stored in the -file "calculator\.peg" is - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -From this we create a snit\-based parser using the script "gen" - - package require Tcl 8.5 - package require fileutil - package require pt::pgen - - lassign $argv name - set grammar [fileutil::cat $name.peg] - set pclass [pt::pgen peg $gr snit -class $name -file $name.peg -name $name] - fileutil::writeFile $name.tcl $pclass - exit 0 - -calling it like - - tclsh8.5 gen calculator - -which leaves us with the parser package and class written to the file -"calculator\.tcl"\. Assuming that this package is then properly installed in a -place where Tcl can find it we can now use this class via a script like - - package require calculator - - lassign $argv input - set channel [open $input r] - - set parser [calculator] - set ast [$parser parse $channel] - $parser destroy - close $channel - - ... now process the returned abstract syntax tree ... - -where the abstract syntax tree stored in the variable will look like - - set ast {Expression 0 4 - {Factor 0 4 - {Term 0 2 - {Number 0 2 - {Digit 0 0} - {Digit 1 1} - {Digit 2 2} - } - } - {AddOp 3 3} - {Term 4 4 - {Number 4 4 - {Digit 4 4} - } - } - } - } - -assuming that the input file and channel contained the text - - 120+5 - -A more graphical representation of the tree would be - -![](\.\./\.\./\.\./\.\./image/expr\_ast\.png) Regardless, at this point it is the -user's responsibility to work with the tree to reach whatever goal she desires\. -I\.e\. analyze it, transform it, etc\. The package -__[pt::ast](pt\_astree\.md)__ should be of help here, providing commands -to walk such ASTs structures in various ways\. - -One important thing to note is that the parsers used here return a data -structure representing the structure of the input per the grammar underlying the -parser\. There are *no* callbacks during the parsing process, i\.e\. no *parsing -actions*, as most other parsers will have\. - -Going back to the last snippet of code, the execution of the parser for some -input, note how the parser instance follows the specified *[Parser -API](pt\_parser\_api\.md)*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_rdengine.md Index: embedded/md/tcllib/files/modules/pt/pt_rdengine.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_rdengine.md +++ embedded/md/tcllib/files/modules/pt/pt_rdengine.md @@ -1,948 +0,0 @@ - -[//000000001]: # (pt::rde \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_rdengine\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::rde\(n\) 1\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::rde \- Parsing Runtime Support, PARAM based - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#subsection1) - - - [Object API](#subsection2) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::rde ?1\.1? -package require snit -package require struct::stack 1\.5 -package require pt::ast 1\.1 - -[__::pt::rde__ *objectName*](#1) -[*objectName* __destroy__](#2) -[*objectName* __reset__ *chan*](#3) -[*objectName* __complete__](#4) -[*objectName* __chan__](#5) -[*objectName* __line__](#6) -[*objectName* __column__](#7) -[*objectName* __current__](#8) -[*objectName* __location__](#9) -[*objectName* __locations__](#10) -[*objectName* __ok__](#11) -[*objectName* __value__](#12) -[*objectName* __error__](#13) -[*objectName* __errors__](#14) -[*objectName* __tokens__ ?*from* ?*to*??](#15) -[*objectName* __symbols__](#16) -[*objectName* __known__](#17) -[*objectName* __reducible__](#18) -[*objectName* __asts__](#19) -[*objectName* __ast__](#20) -[*objectName* __position__ *loc*](#21) -[*objectName* __i\_input\_next__ *msg*](#22) -[*objectName* __i\_test\_alnum__](#23) -[*objectName* __i\_test\_alpha__](#24) -[*objectName* __i\_test\_ascii__](#25) -[*objectName* __i\_test\_char__ *char*](#26) -[*objectName* __i\_test\_ddigit__](#27) -[*objectName* __i\_test\_digit__](#28) -[*objectName* __i\_test\_graph__](#29) -[*objectName* __i\_test\_lower__](#30) -[*objectName* __i\_test\_print__](#31) -[*objectName* __i\_test\_punct__](#32) -[*objectName* __i\_test\_range__ *chars* *chare*](#33) -[*objectName* __i\_test\_space__](#34) -[*objectName* __i\_test\_upper__](#35) -[*objectName* __i\_test\_wordchar__](#36) -[*objectName* __i\_test\_xdigit__](#37) -[*objectName* __i\_error\_clear__](#38) -[*objectName* __i\_error\_push__](#39) -[*objectName* __i\_error\_pop\_merge__](#40) -[*objectName* __i\_error\_nonterminal__ *symbol*](#41) -[*objectName* __i\_status\_ok__](#42) -[*objectName* __i\_status\_fail__](#43) -[*objectName* __i\_status\_negate__](#44) -[*objectName* __i\_loc\_push__](#45) -[*objectName* __i\_loc\_pop\_discard__](#46) -[*objectName* __i\_loc\_pop\_rewind__](#47) -[*objectName* __i:ok\_loc\_pop\_rewind__](#48) -[*objectName* __i\_loc\_pop\_rewind/discard__](#49) -[*objectName* __i\_symbol\_restore__ *symbol*](#50) -[*objectName* __i\_symbol\_save__ *symbol*](#51) -[*objectName* __i\_value\_clear__](#52) -[*objectName* __i\_value\_clear/leaf__](#53) -[*objectName* __i\_value\_clear/reduce__](#54) -[*objectName* __i:ok\_ast\_value\_push__](#55) -[*objectName* __i\_ast\_push__](#56) -[*objectName* __i\_ast\_pop\_rewind__](#57) -[*objectName* __i:fail\_ast\_pop\_rewind__](#58) -[*objectName* __i\_ast\_pop\_rewind/discard__](#59) -[*objectName* __i\_ast\_pop\_discard__](#60) -[*objectName* __i\_ast\_pop\_discard/rewind__](#61) -[*objectName* __i:ok\_continue__](#62) -[*objectName* __i:fail\_continue__](#63) -[*objectName* __i:fail\_return__](#64) -[*objectName* __i:ok\_return__](#65) -[*objectName* __si:void\_state\_push__](#66) -[*objectName* __si:void2\_state\_push__](#67) -[*objectName* __si:value\_state\_push__](#68) -[*objectName* __si:void\_state\_merge__](#69) -[*objectName* __si:void\_state\_merge\_ok__](#70) -[*objectName* __si:value\_state\_merge__](#71) -[*objectName* __si:value\_notahead\_start__](#72) -[*objectName* __si:void\_notahead\_exit__](#73) -[*objectName* __si:value\_notahead\_exit__](#74) -[*objectName* __si:kleene\_abort__](#75) -[*objectName* __si:kleene\_close__](#76) -[*objectName* __si:voidvoid\_branch__](#77) -[*objectName* __si:voidvalue\_branch__](#78) -[*objectName* __si:valuevoid\_branch__](#79) -[*objectName* __si:valuevalue\_branch__](#80) -[*objectName* __si:voidvoid\_part__](#81) -[*objectName* __si:voidvalue\_part__](#82) -[*objectName* __si:valuevalue\_part__](#83) -[*objectName* __si:value\_symbol\_start__ *symbol*](#84) -[*objectName* __si:value\_void\_symbol\_start__ *symbol*](#85) -[*objectName* __si:void\_symbol\_start__ *symbol*](#86) -[*objectName* __si:void\_void\_symbol\_start__ *symbol*](#87) -[*objectName* __si:reduce\_symbol\_end__ *symbol*](#88) -[*objectName* __si:void\_leaf\_symbol\_end__ *symbol*](#89) -[*objectName* __si:value\_leaf\_symbol\_end__ *symbol*](#90) -[*objectName* __si:value\_clear\_symbol\_end__ *symbol*](#91) -[*objectName* __si:void\_clear\_symbol\_end__ *symbol*](#92) -[*objectName* __si:next\_char__ *tok*](#93) -[*objectName* __si:next\_range__ *toks* *toke*](#94) -[*objectName* __si:next\_alnum__](#95) -[*objectName* __si:next\_alpha__](#96) -[*objectName* __si:next\_ascii__](#97) -[*objectName* __si:next\_ddigit__](#98) -[*objectName* __si:next\_digit__](#99) -[*objectName* __si:next\_graph__](#100) -[*objectName* __si:next\_lower__](#101) -[*objectName* __si:next\_print__](#102) -[*objectName* __si:next\_punct__](#103) -[*objectName* __si:next\_space__](#104) -[*objectName* __si:next\_upper__](#105) -[*objectName* __si:next\_wordchar__](#106) -[*objectName* __si:next\_xdigit__](#107) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides a class whose instances provide the runtime support for -recursive descent parsers with backtracking, as is needed for the execution of, -for example, parsing expression grammars\. It implements the *[PackRat Machine -Specification](pt\_param\.md)*, as such that document is *required* reading -to understand both this manpage, and the package itself\. The description below -does make numerous shorthand references to the PARAM's instructions and the -various parts of its architectural state\. - -The package resides in the Execution section of the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_transform\.png) - -Note: This package not only has the standard Tcl implementation, but also an -accelerator, i\.e\. a C implementation, based on Critcl\. - -## Class API - -The package exports the API described here\. - - - __::pt::rde__ *objectName* - - The command creates a new runtime object for a recursive descent parser with - backtracking and returns the fully qualified name of the object command as - its result\. The API of this object command is described in the section - [Object API](#subsection2)\. It may be used to invoke various operations - on the object\. - -## Object API - -All objects created by this package provide the following 63 methods for the -manipulation and querying of their state, which is, in essence the architectural -state of a PARAM\. - -First some general methods and the state accessors\. - - - *objectName* __destroy__ - - This method destroys the object, releasing all claimed memory, and deleting - the associated object command\. - - - *objectName* __reset__ *chan* - - This method resets the state of the runtme to its defaults, preparing it for - the parsing of the character in the channel *chan*, which becomes IN\. - - Note here that the Parser Tools are based on Tcl 8\.5\+\. In other words, the - channel argument is not restricted to files, sockets, etc\. We have the full - power of *reflected channels* available\. - - It should also be noted that the parser pulls the characters from the input - stream as it needs them\. If a parser created by this package has to be - operated in a push aka event\-driven manner it will be necessary to go to Tcl - 8\.6\+ and use the __[coroutine::auto](\.\./coroutine/coro\_auto\.md)__ to - wrap it into a coroutine where __[read](\.\./\.\./\.\./\.\./index\.md\#read)__ - is properly changed for push\-operation\. - - - *objectName* __complete__ - - This method completes parsing, either returning the AST made from the - elements of ARS, or throwing an error containing the current ER\. - - - *objectName* __chan__ - - This method returns the handle of the channel which is IN\. - - - *objectName* __line__ - - This method returns the line number for the position IN is currently at\. - Note that this may not match with the line number for CL, due to - backtracking\. - - - *objectName* __column__ - - This method returns the column for the position IN is currently at\. Note - that this may not match with the column for CL, due to backtracking\. - - - *objectName* __current__ - - This method returns CC\. - - - *objectName* __location__ - - This method returns CL\. - - - *objectName* __locations__ - - This method returns the LS\. The topmost entry of the stack will be the first - element of the returned list\. - - - *objectName* __ok__ - - This method returns ST\. - - - *objectName* __value__ - - This method returns SV\. - - - *objectName* __error__ - - This method returns ER\. This is either the empty string for an empty ER, or - a list of 2 elements, the location the error is for, and a set of messages - which specify which symbols were expected at the location\. The messages are - encoded as one of the possible atomic parsing expressions \(special - operators, terminal, range, and nonterminal operator\)\. - - - *objectName* __errors__ - - This method returns ES\. The topmost entry of the stack will be the first - element of the returned list\. Each entry is encoded as described for - __error__\. - - - *objectName* __tokens__ ?*from* ?*to*?? - - This method returns the part of TC for the range of locations of IN starting - at *from* and ending at *to*\. If *to* is not specified it is taken as - identical to *from*\. If neither argument is specified the whole of TC is - returned\. - - Each token in the returned list is a list of three elements itself, - containing the character at the location, and the associated line and column - numbers, in this order\. - - - *objectName* __symbols__ - - This method returns a dictionary containing NC\. Keys are two\-element lists - containing nonterminal symbol and location, in this order\. The values are - 4\-tuples containing CL, ST, ER, and SV, in this order\. ER is encoded as - specified for the method __error__\. - - - *objectName* __known__ - - This method returns a list containing the keys of SC\. They are encoded in - the same manner as is done by method __symbols__\. - - - *objectName* __reducible__ - - This method returns ARS\. The topmost entry of the stack will be the first - element of the returned list - - - *objectName* __asts__ - - This method returns AS\. The topmost entry of the stack will be the first - element of the returned list - - - *objectName* __ast__ - - This is a convenience method returning the topmost element of ARS\. - - - *objectName* __position__ *loc* - - This method returns the line and column numbers for the specified location - of IN, assuming that this location has already been reached during the - parsing process\. - -The following methods implement all PARAM instructions\. They all have the prefix -"i\_"\. - -The control flow is mainly provided by Tcl's builtin commands, like __if__, -__while__, etc\., plus a few guarded variants of PARAM instructions and Tcl -commands\.\. That means that these instruction variants will do nothing if their -guard condition is not fulfilled\. They can be recognized by the prefix "i:ok\_" -and "i:fail\_", which denote the value ST has to have for the instruction to -execute\. - -The instructions are listed in the same order they occur in the *[PackRat -Machine Specification](pt\_param\.md)*, with the guard variants listed after -their regular implementation, if any, or in their place\. - - - *objectName* __i\_input\_next__ *msg* - - This method implements the PARAM instruction __input\_next__\. - - - *objectName* __i\_test\_alnum__ - - This method implements the PARAM instruction __test\_alnum__\. - - - *objectName* __i\_test\_alpha__ - - This method implements the PARAM instruction __test\_alpha__\. - - - *objectName* __i\_test\_ascii__ - - This method implements the PARAM instruction __test\_ascii__\. - - - *objectName* __i\_test\_char__ *char* - - This method implements the PARAM instruction __test\_char__\. - - - *objectName* __i\_test\_ddigit__ - - This method implements the PARAM instruction __test\_ddigit__\. - - - *objectName* __i\_test\_digit__ - - This method implements the PARAM instruction __test\_digit__\. - - - *objectName* __i\_test\_graph__ - - This method implements the PARAM instruction __test\_graph__\. - - - *objectName* __i\_test\_lower__ - - This method implements the PARAM instruction __test\_lower__\. - - - *objectName* __i\_test\_print__ - - This method implements the PARAM instruction __test\_print__\. - - - *objectName* __i\_test\_punct__ - - This method implements the PARAM instruction __test\_punct__\. - - - *objectName* __i\_test\_range__ *chars* *chare* - - This method implements the PARAM instruction __test\_range__\. - - - *objectName* __i\_test\_space__ - - This method implements the PARAM instruction __test\_space__\. - - - *objectName* __i\_test\_upper__ - - This method implements the PARAM instruction __test\_upper__\. - - - *objectName* __i\_test\_wordchar__ - - This method implements the PARAM instruction __test\_wordchar__\. - - - *objectName* __i\_test\_xdigit__ - - This method implements the PARAM instruction __test\_xdigit__\. - - - *objectName* __i\_error\_clear__ - - This method implements the PARAM instruction __error\_clear__\. - - - *objectName* __i\_error\_push__ - - This method implements the PARAM instruction __error\_push__\. - - - *objectName* __i\_error\_pop\_merge__ - - This method implements the PARAM instruction __error\_pop\_merge__\. - - - *objectName* __i\_error\_nonterminal__ *symbol* - - This method implements the PARAM instruction __error\_nonterminal__\. - - - *objectName* __i\_status\_ok__ - - This method implements the PARAM instruction __status\_ok__\. - - - *objectName* __i\_status\_fail__ - - This method implements the PARAM instruction __status\_fail__\. - - - *objectName* __i\_status\_negate__ - - This method implements the PARAM instruction __status\_negate__\. - - - *objectName* __i\_loc\_push__ - - This method implements the PARAM instruction __loc\_push__\. - - - *objectName* __i\_loc\_pop\_discard__ - - This method implements the PARAM instruction __loc\_pop\_discard__\. - - - *objectName* __i\_loc\_pop\_rewind__ - - This method implements the PARAM instruction __loc\_pop\_rewind__\. - - - *objectName* __i:ok\_loc\_pop\_rewind__ - - This guarded method, a variant of __i\_loc\_pop\_rewind__, executes only - for "ST == ok"\. - - - *objectName* __i\_loc\_pop\_rewind/discard__ - - This method is a convenient combination of control flow and the two PARAM - instructions __loc\_pop\_rewind__ and __loc\_pop\_discard__\. The former - is executed for "ST == fail", the latter for "ST == ok"\. - - - *objectName* __i\_symbol\_restore__ *symbol* - - This method implements the PARAM instruction __symbol\_restore__\. - - The boolean result of the check is returned as the result of the method and - can be used with standard Tcl control flow commands\. - - - *objectName* __i\_symbol\_save__ *symbol* - - This method implements the PARAM instruction __symbol\_save__\. - - - *objectName* __i\_value\_clear__ - - This method implements the PARAM instruction __value\_clear__\. - - - *objectName* __i\_value\_clear/leaf__ - - This method is a convenient combination of control flow and the two PARAM - instructions __value\_clear__ and __value\_leaf__\. The former is - executed for "ST == fail", the latter for "ST == ok"\. - - - *objectName* __i\_value\_clear/reduce__ - - This method is a convenient combination of control flow and the two PARAM - instructions __value\_clear__ and __value\_reduce__\. The former is - executed for "ST == fail", the latter for "ST == ok"\. - - - *objectName* __i:ok\_ast\_value\_push__ - - This method implements a guarded variant of the the PARAM instruction - __ast\_value\_push__, which executes only for "ST == ok"\. - - - *objectName* __i\_ast\_push__ - - This method implements the PARAM instruction __ast\_push__\. - - - *objectName* __i\_ast\_pop\_rewind__ - - This method implements the PARAM instruction __ast\_pop\_rewind__\. - - - *objectName* __i:fail\_ast\_pop\_rewind__ - - This guarded method, a variant of __i\_ast\_pop\_rewind__, executes only - for "ST == fail"\. - - - *objectName* __i\_ast\_pop\_rewind/discard__ - - This method is a convenient combination of control flow and the two PARAM - instructions __ast\_pop\_rewind__ and __ast\_pop\_discard__\. The former - is executed for "ST == fail", the latter for "ST == ok"\. - - - *objectName* __i\_ast\_pop\_discard__ - - This method implements the PARAM instruction __ast\_pop\_discard__\. - - - *objectName* __i\_ast\_pop\_discard/rewind__ - - This method is a convenient combination of control flow and the two PARAM - instructions __ast\_pop\_discard__ and __ast\_pop\_rewind__\. The former - is executed for "ST == fail", the latter for "ST == ok"\. - - - *objectName* __i:ok\_continue__ - - This guarded method executes only for "ST == ok"\. Then it aborts the current - iteration of the innermost loop in the calling Tcl procedure\. - - - *objectName* __i:fail\_continue__ - - This guarded method executes only for "ST == fail"\. Then it aborts the - current iteration of the innermost loop in the calling Tcl procedure\. - - - *objectName* __i:fail\_return__ - - This guarded method executes only for "ST == fail"\. Then it aborts the - calling Tcl procedure\. - - - *objectName* __i:ok\_return__ - - This guarded method executes only for "ST == ok"\. Then it aborts the calling - Tcl procedure\. - -The next set of methods are *super instructions*, meaning that each implements -a longer sequence of instructions commonly used in parsers\. The combinated -instructions of the previous set, i\.e\. those with names matching the pattern -"i\_\*/\*", are actually super instructions as well, albeit with limited scope, -handling 2 instructions with their control flow\. The upcoming set is much -broader in scope, folding as much as six or more PARAM instructions into a -single method call\. - -In this we can see the reasoning behind their use well: - - 1. By using less instructions the generated parsers become smaller, as the - common parts are now truly part of the common runtime, and not explicitly - written in the parser's code over and over again\. - - 1. Using less instructions additionally reduces the overhead associated with - calls into the runtime, i\.e\. the cost of method dispatch and of setting up - the variable context\. - - 1. Another effect of the super instructions is that their internals can be - optimized as well, especially regarding control flow, and stack use, as the - runtime internals are accessible to all instructions folded into the - sequence\. - - - *objectName* __si:void\_state\_push__ - - This method combines - - i_loc_push - i_error_clear - i_error_push - - Parsers use it at the beginning of *void* sequences and choices with a - *void* initial branch\. - - - *objectName* __si:void2\_state\_push__ - - This method combines - - i_loc_push - i_error_clear - i_error_push - - Parsers use it at the beginning of optional and repeated expressions\. - - - *objectName* __si:value\_state\_push__ - - This method combines - - i_ast_push - i_loc_push - i_error_clear - i_error_push - - Parsers use it at the beginning of sequences generating an AST and choices - with an initial branch generating an AST\. - - - *objectName* __si:void\_state\_merge__ - - This method combines - - i_error_pop_merge - i_loc_pop_rewind/discard - - Parsers use it at the end of void sequences and choices whose last branch is - void\. - - - *objectName* __si:void\_state\_merge\_ok__ - - This method combines - - i_error_pop_merge - i_loc_pop_rewind/discard - i_status_ok - - Parsers use it at the end of optional expressions - - - *objectName* __si:value\_state\_merge__ - - This method combines - - i_error_pop_merge - i_ast_pop_rewind/discard - i_loc_pop_rewind/discard - - Parsers use it at the end of sequences generating ASTs and choices whose - last branch generates an AST - - - *objectName* __si:value\_notahead\_start__ - - This method combines - - i_loc_push - i_ast_push - - Parsers use it at the beginning of negative lookahead predicates which - generate ASTs\. - - - *objectName* __si:void\_notahead\_exit__ - - This method combines - - i_loc_pop_rewind - i_status_negate - - Parsers use it at the end of void negative lookahead predicates\. - - - *objectName* __si:value\_notahead\_exit__ - - This method combines - - i_ast_pop_discard/rewind - i_loc_pop_rewind - i_status_negate - - Parsers use it at the end of negative lookahead predicates which generate - ASTs\. - - - *objectName* __si:kleene\_abort__ - - This method combines - - i_loc_pop_rewind/discard - i:fail_return - - Parsers use it to stop a positive repetition when its first, required, - expression fails\. - - - *objectName* __si:kleene\_close__ - - This method combines - - i_error_pop_merge - i_loc_pop_rewind/discard - i:fail_status_ok - i:fail_return - - Parsers use it at the end of repetitions\. - - - *objectName* __si:voidvoid\_branch__ - - This method combines - - i_error_pop_merge - i:ok_loc_pop_discard - i:ok_return - i_loc_rewind - i_error_push - - Parsers use it when transiting between branches of a choice when both are - void\. - - - *objectName* __si:voidvalue\_branch__ - - This method combines - - i_error_pop_merge - i:ok_loc_pop_discard - i:ok_return - i_ast_push - i_loc_rewind - i_error_push - - Parsers use it when transiting between branches of a choice when the failing - branch is void, and the next to test generates an AST\. - - - *objectName* __si:valuevoid\_branch__ - - This method combines - - i_error_pop_merge - i_ast_pop_rewind/discard - i:ok_loc_pop_discard - i:ok_return - i_loc_rewind - i_error_push - - Parsers use it when transiting between branches of a choice when the failing - branch generates an AST, and the next to test is void\. - - - *objectName* __si:valuevalue\_branch__ - - This method combines - - i_error_pop_merge - i_ast_pop_discard - i:ok_loc_pop_discard - i:ok_return - i_ast_rewind - i_loc_rewind - i_error_push - - Parsers use it when transiting between branches of a choice when both - generate ASTs\. - - - *objectName* __si:voidvoid\_part__ - - This method combines - - i_error_pop_merge - i:fail_loc_pop_rewind - i:fail_return - i_error_push - - Parsers use it when transiting between parts of a sequence and both are - void\. - - - *objectName* __si:voidvalue\_part__ - - This method combines - - i_error_pop_merge - i:fail_loc_pop_rewind - i:fail_return - i_ast_push - i_error_push - - Parsers use it when transiting between parts of a sequence and the - sucessfully matched part is void, and after it an AST is generated\. - - - *objectName* __si:valuevalue\_part__ - - This method combines - - i_error_pop_merge - i:fail_ast_pop_rewind - i:fail_loc_pop_rewind - i:fail_return - i_error_push - - Parsers use it when transiting between parts of a sequence and both parts - generate ASTs\. - - - *objectName* __si:value\_symbol\_start__ *symbol* - - This method combines - - if/found? i_symbol_restore $symbol - i:found:ok_ast_value_push - i:found_return - i_loc_push - i_ast_push - - Parsers use it at the beginning of a nonterminal symbol generating an AST, - whose right\-hand side may have generated an AST as well\. - - - *objectName* __si:value\_void\_symbol\_start__ *symbol* - - This method combines - - if/found? i_symbol_restore $symbol - i:found:ok_ast_value_push - i:found_return - i_loc_push - i_ast_push - - Parsers use it at the beginning of a void nonterminal symbol whose - right\-hand side may generate an AST\. - - - *objectName* __si:void\_symbol\_start__ *symbol* - - This method combines - - if/found? i_symbol_restore $symbol - i:found_return - i_loc_push - i_ast_push - - Parsers use it at the beginning of a nonterminal symbol generating an AST - whose right\-hand side is void\. - - - *objectName* __si:void\_void\_symbol\_start__ *symbol* - - This method combines - - if/found? i_symbol_restore $symbol - i:found_return - i_loc_push - - Parsers use it at the beginning of a void nonterminal symbol whose - right\-hand side is void as well\. - - - *objectName* __si:reduce\_symbol\_end__ *symbol* - - This method combines - - i_value_clear/reduce $symbol - i_symbol_save $symbol - i_error_nonterminal $symbol - i_ast_pop_rewind - i_loc_pop_discard - i:ok_ast_value_push - - Parsers use it at the end of a non\-terminal symbol generating an AST using - the AST generated by the right\-hand side as child\. - - - *objectName* __si:void\_leaf\_symbol\_end__ *symbol* - - This method combines - - i_value_clear/leaf $symbol - i_symbol_save $symbol - i_error_nonterminal $symbol - i_loc_pop_discard - i:ok_ast_value_push - - Parsers use it at the end of a non\-terminal symbol generating an AST whose - right\-hand side is void\. - - - *objectName* __si:value\_leaf\_symbol\_end__ *symbol* - - This method combines - - i_value_clear/leaf $symbol - i_symbol_save $symbol - i_error_nonterminal $symbol - i_loc_pop_discard - i_ast_pop_rewind - i:ok_ast_value_push - - Parsers use it at the end of a non\-terminal symbol generating an AST - discarding the AST generated by the right\-hand side\. - - - *objectName* __si:value\_clear\_symbol\_end__ *symbol* - - This method combines - - i_value_clear - i_symbol_save $symbol - i_error_nonterminal $symbol - i_loc_pop_discard - i_ast_pop_rewind - - Parsers use it at the end of a void non\-terminal symbol, discarding the AST - generated by the right\-hand side\. - - - *objectName* __si:void\_clear\_symbol\_end__ *symbol* - - This method combines - - i_value_clear - i_symbol_save $symbol - i_error_nonterminal $symbol - i_loc_pop_discard - - Parsers use it at the end of a void non\-terminal symbol with a void - right\-hand side\. - - - *objectName* __si:next\_char__ *tok* - - - *objectName* __si:next\_range__ *toks* *toke* - - - *objectName* __si:next\_alnum__ - - - *objectName* __si:next\_alpha__ - - - *objectName* __si:next\_ascii__ - - - *objectName* __si:next\_ddigit__ - - - *objectName* __si:next\_digit__ - - - *objectName* __si:next\_graph__ - - - *objectName* __si:next\_lower__ - - - *objectName* __si:next\_print__ - - - *objectName* __si:next\_punct__ - - - *objectName* __si:next\_space__ - - - *objectName* __si:next\_upper__ - - - *objectName* __si:next\_wordchar__ - - - *objectName* __si:next\_xdigit__ - - These methods all combine - - i_input_next $msg - i:fail_return - - with the appropriate __i\_test\_xxx__ instruction\. Parsers use them for - handling atomic expressions\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_nx.md @@ -1,115 +0,0 @@ - -[//000000001]: # (pt::tclparam::configuration::nx \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_tclparam\_config\_nx\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::tclparam::configuration::nx\(n\) 1\.0\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::tclparam::configuration::nx \- Tcl/PARAM, Canned configuration, NX - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::tclparam::configuration::nx ?1\.0\.1? - -[__::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package is an adjunct to -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__, to make the use of -this highly configurable package easier by providing a canned configuration\. -When applied this configuration causes the package -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ to generate -__NX__\-based parser packages\. - -It is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::tclparam::configuration::nx__ __def__ *name* *pkg* *version* *cmdprefix* - - The command applies the configuration provided by this package to the - *cmdprefix*, causing the creation of __NX__\-based parsers whose class - is *name*, in package *pkg* with *version*\. - - The use of a command prefix as API allows application of the configuration - to not only __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ - \(__pt::peg::to::tclparam configure__\), but also export manager instances - and PEG containers \(__$export configuration set__ and __\[$container - exporter\] configuration set__ respectively\)\. - - Or anything other command prefix accepting two arguments, option and value\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_snit.md @@ -1,116 +0,0 @@ - -[//000000001]: # (pt::tclparam::configuration::snit \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_tclparam\_config\_snit\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::tclparam::configuration::snit\(n\) 1\.0\.2 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::tclparam::configuration::snit \- Tcl/PARAM, Canned configuration, Snit - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::tclparam::configuration::snit ?1\.0\.2? - -[__::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package is an adjunct to -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__, to make the use of -this highly configurable package easier by providing a canned configuration\. -When applied this configuration causes the package -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ to generate -__[snit](\.\./snit/snit\.md)__\-based parser packages\. - -It is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::tclparam::configuration::snit__ __def__ *name* *pkg* *version* *cmdprefix* - - The command applies the configuration provided by this package to the - *cmdprefix*, causing the creation of - __[snit](\.\./snit/snit\.md)__\-based parsers whose class is *name*, - in package *pkg* with *version*\. - - The use of a command prefix as API allows application of the configuration - to not only __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ - \(__pt::peg::to::tclparam configure__\), but also export manager instances - and PEG containers \(__$export configuration set__ and __\[$container - exporter\] configuration set__ respectively\)\. - - Or anything other command prefix accepting two arguments, option and value\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md Index: embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md +++ embedded/md/tcllib/files/modules/pt/pt_tclparam_config_tcloo.md @@ -1,116 +0,0 @@ - -[//000000001]: # (pt::tclparam::configuration::tcloo \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_tclparam\_config\_tcloo\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::tclparam::configuration::tcloo\(n\) 1\.0\.4 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::tclparam::configuration::tcloo \- Tcl/PARAM, Canned configuration, Tcloo - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::tclparam::configuration::tcloo ?1\.0\.4? - -[__::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix*](#1) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package is an adjunct to -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__, to make the use of -this highly configurable package easier by providing a canned configuration\. -When applied this configuration causes the package -__[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ to generate -__[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__\-based parser packages\. - -It is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::tclparam::configuration::tcloo__ __def__ *name* *pkg* *version* *cmdprefix* - - The command applies the configuration provided by this package to the - *cmdprefix*, causing the creation of - __[OO](\.\./\.\./\.\./\.\./index\.md\#oo)__\-based parsers whose class is - *name*, in package *pkg* with *version*\. - - The use of a command prefix as API allows application of the configuration - to not only __[pt::peg::to::tclparam](pt\_peg\_to\_tclparam\.md)__ - \(__pt::peg::to::tclparam configure__\), but also export manager instances - and PEG containers \(__$export configuration set__ and __\[$container - exporter\] configuration set__ respectively\)\. - - Or anything other command prefix accepting two arguments, option and value\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_to_api.md Index: embedded/md/tcllib/files/modules/pt/pt_to_api.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_to_api.md +++ embedded/md/tcllib/files/modules/pt/pt_to_api.md @@ -1,531 +0,0 @@ - -[//000000001]: # (pt\_export\_api \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_to\_api\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt\_export\_api\(i\) 1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt\_export\_api \- Parser Tools Export API - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Converter API](#section2) - - - [Plugin API](#section3) - - - [Options](#section4) - - - [Usage](#section5) - - - [PEG serialization format](#section6) - - - [Example](#subsection1) - - - [PE serialization format](#section7) - - - [Example](#subsection2) - - - [Bugs, Ideas, Feedback](#section8) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 - -[__CONVERTER__ __reset__](#1) -[__CONVERTER__ __configure__](#2) -[__CONVERTER__ __configure__ *option*](#3) -[__CONVERTER__ __configure__ *option* *value*\.\.\.](#4) -[__CONVERTER__ __convert__ *serial*](#5) -[__::export__ *serial* *configuration*](#6) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This document describes two APIs\. First the API shared by all packages for the -conversion of Parsing Expression Grammars into some other format, and then the -API shared by the packages which implement the export plugins sitting on top of -the conversion packages\. - -Its intended audience are people who wish to create their own converter for some -type of output, and/or an export plugin for their or some other converter\. - -It resides in the Export section of the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_export\.png) - -# Converter API - -Any \(grammar\) export converter has to follow the rules set out below: - - 1. A converter is a package\. Its name is arbitrary, however it is recommended - to put it under the __::pt::peg::to__ namespace\. - - 1. The package provides either a single Tcl command following the API outlined - below, or a class command whose instances follow the same API\. The commands - which follow the API are called *converter commands*\. - - 1. A converter command has to provide the following three methods with the - given signatures and semantics\. Converter commands are allowed to provide - more methods of their own, but not less, and they may not provide different - semantics for the standardized methods\. - - - __CONVERTER__ __reset__ - - This method has to reset the configuration of the converter to its - default settings\. The result of the method has to be the empty string\. - - - __CONVERTER__ __configure__ - - This method, in this form, has to return a dictionary containing the - current configuration of the converter\. - - - __CONVERTER__ __configure__ *option* - - This method, in this form, has to return the current value of the - specified configuration *option* of the converter\. - - Please read the section [Options](#section4) for the set of - standard options any converter has to accept\. Any other options - accepted by a specific converter will be described in its manpage\. - - - __CONVERTER__ __configure__ *option* *value*\.\.\. - - This command, in this form, sets the specified *option*s of the - converter to the given *value*s\. - - Please read the section [Options](#section4) for the set of - standard options a converter has to accept\. Any other options accepted - by a specific converter will be described in its manpage\. - - - __CONVERTER__ __convert__ *serial* - - This method has to accept the canonical serialization of a parsing - expression grammar, as specified in section [PEG serialization - format](#section6), and contained in *serial*\. The result of the - method has to be the result of converting the input grammar into - whatever the converter is for, per its configuration\. - -# Plugin API - -Any \(grammar\) export plugin has to follow the rules set out below: - - 1. A plugin is a package\. - - 1. The name of a plugin package has the form pt::peg::export::__FOO__, - where __FOO__ is the name of the format the plugin will generate output - for\. - - 1. The plugin can expect that the package __pt::peg::export::plugin__ is - present, as indicator that it was invoked from a genuine plugin manager\. - - It is recommended that a plugin does check for the presence of this - package\. - - 1. A plugin has to provide a single command, in the global namespace, with the - signature shown below\. Plugins are allowed to provide more command of their - own, but not less, and they may not provide different semantics for the - standardized command\. - - - __::export__ *serial* *configuration* - - This command has to accept the canonical serialization of a parsing - expression grammar and the configuration for the converter invoked by - the plugin\. The result of the command has to be the result of the - converter invoked by the plugin for th input grammar and configuration\. - - * string *serial* - - This argument will contain the *canonical* serialization of the - parsing expression grammar for which to generate the output\. The - specification of what a *canonical* serialization is can be found - in the section [PEG serialization format](#section6)\. - - * dictionary *configuration* - - This argument will contain the configuration to configure the - converter with before invoking it, as a dictionary mapping from - options to values\. - - Please read the section [Options](#section4) for the set of - standard options any converter has to accept, and thus any plugin - as well\. Any other options accepted by a specific plugin will be - described in its manpage\. - - 1. A single usage cycle of a plugin consists of an invokation of the command - __[export](\.\./\.\./\.\./\.\./index\.md\#export)__\. This call has to leave - the plugin in a state where another usage cycle can be run without - problems\. - -# Options - -Each export converter and plugin for an export converter has to accept the -options below in their __configure__ method\. Converters are allowed to -ignore the contents of these options when performing a conversion, but they must -not reject them\. Plugins are expected to pass the options given to them to the -converter they are invoking\. - - - __\-file__ string - - The value of this option is the name of the file or other entity from which - the grammar came, for which the command is run\. The default value is - __unknown__\. - - - __\-name__ string - - The value of this option is the name of the grammar we are processing\. The - default value is __a\_pe\_grammar__\. - - - __\-user__ string - - The value of this option is the name of the user for which the command is - run\. The default value is __unknown__\. - -# Usage - -To use a converter do - - # Get the converter (single command here, not class) - package require the-converter-package - - # Provide a configuration - theconverter configure ... - - # Perform the conversion - set result [theconverter convert $thegrammarserial] - - ... process the result ... - -To use a plugin __FOO__ do - - # Get an export plugin manager - package require pt::peg::export - pt::peg::export E - - # Provide a configuration - E configuration set ... - - # Run the plugin, and the converter inside. - set result [E export serial $grammarserial FOO] - - ... process the result ... - -# PEG serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expression Grammars as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a PEG -may have more than one regular serialization only exactly one of them will be -*canonical*\. - - - regular serialization - - 1. The serialization of any PEG is a nested Tcl dictionary\. - - 1. This dictionary holds a single key, __pt::grammar::peg__, and its - value\. This value holds the contents of the grammar\. - - 1. The contents of the grammar are a Tcl dictionary holding the set of - nonterminal symbols and the starting expression\. The relevant keys and - their values are - - * __rules__ - - The value is a Tcl dictionary whose keys are the names of the - nonterminal symbols known to the grammar\. - - 1) Each nonterminal symbol may occur only once\. - - 1) The empty string is not a legal nonterminal symbol\. - - 1) The value for each symbol is a Tcl dictionary itself\. The - relevant keys and their values in this dictionary are - - + __is__ - - The value is the serialization of the parsing expression - describing the symbols sentennial structure, as specified - in the section [PE serialization format](#section7)\. - - + __mode__ - - The value can be one of three values specifying how a - parser should handle the semantic value produced by the - symbol\. - - - __value__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal itself, which has the ASTs of the - symbol's right hand side as its children\. - - - __leaf__ - - The semantic value of the nonterminal symbol is an - abstract syntax tree consisting of a single node node - for the nonterminal, without any children\. Any ASTs - generated by the symbol's right hand side are - discarded\. - - - __void__ - - The nonterminal has no semantic value\. Any ASTs - generated by the symbol's right hand side are - discarded \(as well\)\. - - * __start__ - - The value is the serialization of the start parsing expression of - the grammar, as specified in the section [PE serialization - format](#section7)\. - - 1. The terminal symbols of the grammar are specified implicitly as the set - of all terminal symbols used in the start expression and on the RHS of - the grammar rules\. - - - canonical serialization - - The canonical serialization of a grammar has the format as specified in the - previous item, and then additionally satisfies the constraints below, which - make it unique among all the possible serializations of this grammar\. - - 1. The keys found in all the nested Tcl dictionaries are sorted in - ascending dictionary order, as generated by Tcl's builtin command - __lsort \-increasing \-dict__\. - - 1. The string representation of the value is the canonical representation - of a Tcl dictionary\. I\.e\. it does not contain superfluous whitespace\. - -## Example - -Assuming the following PEG for simple mathematical expressions - - PEG calculator (Expression) - Digit <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9' ; - Sign <- '-' / '+' ; - Number <- Sign? Digit+ ; - Expression <- Term (AddOp Term)* ; - MulOp <- '*' / '/' ; - Term <- Factor (MulOp Factor)* ; - AddOp <- '+'/'-' ; - Factor <- '(' Expression ')' / Number ; - END; - -then its canonical serialization \(except for whitespace\) is - - pt::grammar::peg { - rules { - AddOp {is {/ {t -} {t +}} mode value} - Digit {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}} mode value} - Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}} mode value} - Factor {is {/ {x {t (} {n Expression} {t )}} {n Number}} mode value} - MulOp {is {/ {t *} {t /}} mode value} - Number {is {x {? {n Sign}} {+ {n Digit}}} mode value} - Sign {is {/ {t -} {t +}} mode value} - Term {is {x {n Factor} {* {x {n MulOp} {n Factor}}}} mode value} - } - start {n Expression} - } - -# PE serialization format - -Here we specify the format used by the Parser Tools to serialize Parsing -Expressions as immutable values for transport, comparison, etc\. - -We distinguish between *regular* and *canonical* serializations\. While a -parsing expression may have more than one regular serialization only exactly one -of them will be *canonical*\. - - - Regular serialization - - * __Atomic Parsing Expressions__ - - 1. The string __epsilon__ is an atomic parsing expression\. It - matches the empty string\. - - 1. The string __dot__ is an atomic parsing expression\. It matches - any character\. - - 1. The string __alnum__ is an atomic parsing expression\. It - matches any Unicode alphabet or digit character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __alpha__ is an atomic parsing expression\. It - matches any Unicode alphabet character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ascii__ is an atomic parsing expression\. It - matches any Unicode character below U0080\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __control__ is an atomic parsing expression\. It - matches any Unicode control character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __digit__ is an atomic parsing expression\. It - matches any Unicode digit character\. Note that this includes - characters outside of the \[0\.\.9\] range\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __graph__ is an atomic parsing expression\. It - matches any Unicode printing character, except for space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __lower__ is an atomic parsing expression\. It - matches any Unicode lower\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __print__ is an atomic parsing expression\. It - matches any Unicode printing character, including space\. This is a - custom extension of PEs based on Tcl's builtin command __string - is__\. - - 1. The string __punct__ is an atomic parsing expression\. It - matches any Unicode punctuation character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __space__ is an atomic parsing expression\. It - matches any Unicode space character\. This is a custom extension of - PEs based on Tcl's builtin command __string is__\. - - 1. The string __upper__ is an atomic parsing expression\. It - matches any Unicode upper\-case alphabet character\. This is a custom - extension of PEs based on Tcl's builtin command __string is__\. - - 1. The string __wordchar__ is an atomic parsing expression\. It - matches any Unicode word character\. This is any alphanumeric - character \(see alnum\), and any connector punctuation characters - \(e\.g\. underscore\)\. This is a custom extension of PEs based on Tcl's - builtin command __string is__\. - - 1. The string __xdigit__ is an atomic parsing expression\. It - matches any hexadecimal digit character\. This is a custom extension - of PEs based on Tcl's builtin command __string is__\. - - 1. The string __ddigit__ is an atomic parsing expression\. It - matches any decimal digit character\. This is a custom extension of - PEs based on Tcl's builtin command __regexp__\. - - 1. The expression \[list t __x__\] is an atomic parsing expression\. - It matches the terminal string __x__\. - - 1. The expression \[list n __A__\] is an atomic parsing expression\. - It matches the nonterminal __A__\. - - * __Combined Parsing Expressions__ - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list / __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *ordered choice*, aka *prioritized choice*\. - - 1. For parsing expressions __e1__, __e2__, \.\.\. the result of - \[list x __e1__ __e2__ \.\.\. \] is a parsing expression as - well\. This is the *sequence*\. - - 1. For a parsing expression __e__ the result of \[list \* __e__\] - is a parsing expression as well\. This is the *kleene closure*, - describing zero or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list \+ __e__\] - is a parsing expression as well\. This is the *positive kleene - closure*, describing one or more repetitions\. - - 1. For a parsing expression __e__ the result of \[list & __e__\] - is a parsing expression as well\. This is the *and lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list \! __e__\] - is a parsing expression as well\. This is the *not lookahead - predicate*\. - - 1. For a parsing expression __e__ the result of \[list ? __e__\] - is a parsing expression as well\. This is the *optional input*\. - - - Canonical serialization - - The canonical serialization of a parsing expression has the format as - specified in the previous item, and then additionally satisfies the - constraints below, which make it unique among all the possible - serializations of this parsing expression\. - - 1. The string representation of the value is the canonical representation - of a pure Tcl list\. I\.e\. it does not contain superfluous whitespace\. - - 1. Terminals are *not* encoded as ranges \(where start and end of the - range are identical\)\. - -## Example - -Assuming the parsing expression shown on the right\-hand side of the rule - - Expression <- Term (AddOp Term)* - -then its canonical serialization \(except for whitespace\) is - - {x {n Term} {* {x {n AddOp} {n Term}}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/pt/pt_util.md Index: embedded/md/tcllib/files/modules/pt/pt_util.md ================================================================== --- embedded/md/tcllib/files/modules/pt/pt_util.md +++ embedded/md/tcllib/files/modules/pt/pt_util.md @@ -1,121 +0,0 @@ - -[//000000001]: # (pt::util \- Parser Tools) -[//000000002]: # (Generated from file 'pt\_util\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (pt::util\(n\) 1\.1 tcllib "Parser Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -pt::util \- General utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require pt::ast ?1\.1? - -[__::pt::util__ __error2readable__ *error* *text*](#1) -[__::pt::util__ __error2position__ *error* *text*](#2) -[__::pt::util__ __error2text__ *error*](#3) - -# DESCRIPTION - -Are you lost ? Do you have trouble understanding this document ? In that case -please read the overview provided by the *[Introduction to Parser -Tools](pt\_introduction\.md)*\. This document is the entrypoint to the whole -system the current package is a part of\. - -This package provides general utility commands\. - -This is a supporting package in the Core Layer of Parser Tools\. - -![](\.\./\.\./\.\./\.\./image/arch\_core\_support\.png) - -# API - - - __::pt::util__ __error2readable__ *error* *text* - - This command takes the structured form of a syntax *error* as thrown by - parser runtimes and the input *text* to the parser which caused that error - and returns a string describing the error in a human\-readable form\. - - The input *text* is required to convert the character position of the - error into a more readable line/column format, and to provide excerpts of - the input around the error position\. - - - __::pt::util__ __error2position__ *error* *text* - - This command takes the structured form of a syntax *error* as thrown by - parser runtimes and the input *text* to the parser which caused that error - and returns a 2\-element list containing the line number and column index for - the error's character position in the input, in this order\. - - - __::pt::util__ __error2text__ *error* - - This command takes the structured form of a syntax *error* as thrown by - parser runtimes and returns a list of strings, each describing a possible - expected input in a human\-readable form\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *pt* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[EBNF](\.\./\.\./\.\./\.\./index\.md\#ebnf), [LL\(k\)](\.\./\.\./\.\./\.\./index\.md\#ll\_k\_), -[PEG](\.\./\.\./\.\./\.\./index\.md\#peg), [TDPL](\.\./\.\./\.\./\.\./index\.md\#tdpl), -[context\-free languages](\.\./\.\./\.\./\.\./index\.md\#context\_free\_languages), -[expression](\.\./\.\./\.\./\.\./index\.md\#expression), -[grammar](\.\./\.\./\.\./\.\./index\.md\#grammar), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), -[parser](\.\./\.\./\.\./\.\./index\.md\#parser), [parsing -expression](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression), [parsing expression -grammar](\.\./\.\./\.\./\.\./index\.md\#parsing\_expression\_grammar), [push down -automaton](\.\./\.\./\.\./\.\./index\.md\#push\_down\_automaton), [recursive -descent](\.\./\.\./\.\./\.\./index\.md\#recursive\_descent), -[state](\.\./\.\./\.\./\.\./index\.md\#state), [top\-down parsing -languages](\.\./\.\./\.\./\.\./index\.md\#top\_down\_parsing\_languages), -[transducer](\.\./\.\./\.\./\.\./index\.md\#transducer) - -# CATEGORY - -Parsing and Grammars - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/rc4/rc4.md Index: embedded/md/tcllib/files/modules/rc4/rc4.md ================================================================== --- embedded/md/tcllib/files/modules/rc4/rc4.md +++ embedded/md/tcllib/files/modules/rc4/rc4.md @@ -1,161 +0,0 @@ - -[//000000001]: # (rc4 \- RC4 Stream Cipher) -[//000000002]: # (Generated from file 'rc4\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003, Pat Thoyts ) -[//000000004]: # (rc4\(n\) 1\.1\.0 tcllib "RC4 Stream Cipher") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -rc4 \- Implementation of the RC4 stream cipher - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require rc4 ?1\.1\.0? - -[__::rc4::rc4__ ?*\-hex*? *\-key keyvalue* ?*\-command lst*? ?*\-out channel*? \[ *\-in channel* | *\-infile filename* | *string* \]](#1) -[__::rc4::RC4Init__ *keydata*](#2) -[__::rc4::RC4__ *Key* *data*](#3) -[__::rc4::RC4Final__ *Key*](#4) - -# DESCRIPTION - -This package is an implementation in Tcl of the RC4 stream cipher developed by -Ron Rivest of RSA Data Security Inc\. The cipher was a trade secret of RSA but -was reverse\-engineered and published to the internet in 1994\. It is used in a -number of network protocols for securing communications\. To evade trademark -restrictions this cipher is sometimes known as ARCFOUR\. - -# COMMANDS - - - __::rc4::rc4__ ?*\-hex*? *\-key keyvalue* ?*\-command lst*? ?*\-out channel*? \[ *\-in channel* | *\-infile filename* | *string* \] - - Perform the RC4 algorithm on either the data provided by the argument or on - the data read from the *\-in* channel\. If an *\-out* channel is given then - the result will be written to this channel\. Giving the *\-hex* option will - return a hexadecimal encoded version of the result if not using an *\-out* - channel\. - - The data to be processes can be specified either as a string argument to the - rc4 command, or as a filename or a pre\-opened channel\. If the *\-infile* - argument is given then the file is opened, the data read and processed and - the file is closed\. If the *\-in* argument is given then data is read from - the channel until the end of file\. The channel is not closed\. If the - *\-out* argument is given then the processing result is written to this - channel\. - - If *\-command* is provided then the rc4 command does not return anything\. - Instead the command provided is called with the rc4 result data appended as - the final parameter\. This is most useful when reading from Tcl channels as a - fileevent is setup on the channel and the data processed in chunks - - Only one of *\-infile*, *\-in* or *string* should be given\. - -# PROGRAMMING INTERFACE - - - __::rc4::RC4Init__ *keydata* - - Initialize a new RC4 key\. The *keydata* is any amount of binary data and - is used to initialize the cipher internal state\. - - - __::rc4::RC4__ *Key* *data* - - Encrypt or decrypt the input data using the key obtained by calling - __RC4Init__\. - - - __::rc4::RC4Final__ *Key* - - This should be called to clean up resources associated with *Key*\. Once - this function has been called the key is destroyed\. - -# EXAMPLES - - % set keydata [binary format H* 0123456789abcdef] - % rc4::rc4 -hex -key $keydata HelloWorld - 3cf1ae8b7f1c670b612f - % rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f] - HelloWorld - - set Key [rc4::RC4Init "key data"] - append ciphertext [rc4::RC4 $Key $plaintext] - append ciphertext [rc4::RC4 $Key $additional_plaintext] - rc4::RC4Final $Key - - proc ::Finish {myState data} { - DoStuffWith $myState $data - } - rc4::rc4 -in $socket -command [list ::Finish $ApplicationState] - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *rc4* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[aes\(n\)](\.\./aes/aes\.md), [blowfish\(n\)](\.\./blowfish/blowfish\.md), -[des\(n\)](\.\./des/des\.md) - -# KEYWORDS - -[arcfour](\.\./\.\./\.\./\.\./index\.md\#arcfour), [data -integrity](\.\./\.\./\.\./\.\./index\.md\#data\_integrity), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), -[rc4](\.\./\.\./\.\./\.\./index\.md\#rc4), -[security](\.\./\.\./\.\./\.\./index\.md\#security), [stream -cipher](\.\./\.\./\.\./\.\./index\.md\#stream\_cipher) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2003, Pat Thoyts DELETED embedded/md/tcllib/files/modules/rcs/rcs.md Index: embedded/md/tcllib/files/modules/rcs/rcs.md ================================================================== --- embedded/md/tcllib/files/modules/rcs/rcs.md +++ embedded/md/tcllib/files/modules/rcs/rcs.md @@ -1,322 +0,0 @@ - -[//000000001]: # (rcs \- RCS low level utilities) -[//000000002]: # (Generated from file 'rcs\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Andreas Kupries ) -[//000000004]: # (Copyright © 2005, Colin McCormack ) -[//000000005]: # (rcs\(n\) 2\.0\.2 tcllib "RCS low level utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -rcs \- RCS low level utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [TEXT DICT DATA STRUCTURE](#section3) - - - [RCS PATCH FORMAT](#section4) - - - [RCS PATCH COMMAND LIST](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require rcs ?0\.1? - -[__::rcs::text2dict__ *text*](#1) -[__::rcs::dict2text__ *dict*](#2) -[__::rcs::file2dict__ *filename*](#3) -[__::rcs::dict2file__ *filename* *dict*](#4) -[__::rcs::decodeRcsPatch__ *text*](#5) -[__::rcs::encodeRcsPatch__ *pcmds*](#6) -[__::rcs::applyRcsPatch__ *text* *pcmds*](#7) - -# DESCRIPTION - -The *Revision Control System*, short *[RCS](\.\./\.\./\.\./\.\./index\.md\#rcs)*, -is a set of applications and related data formats which allow a system to -persist the history of changes to a text\. It, and its relative SCCS are the -basis for many other such systems, like *[CVS](\.\./\.\./\.\./\.\./index\.md\#cvs)*, -etc\. - -This package *does not* implement RCS\. - -It only provides a number of low level commands which should be useful in the -implementation of any revision management system, namely: - - 1. The conversion of texts into and out of a data structures which allow the - easy modification of such text by *patches*, i\.e\. sequences of - instructions for the transformation of one text into an other\. - - 1. And the conversion of one particular format for patches, the so\-called - *RCS patches*, into and out of data structures which allow their easy - application to texts\. - -# COMMANDS - - - __::rcs::text2dict__ *text* - - Converts the argument *text* into a dictionary containing and representing - the same text in an indexed form and returns that dictionary as its result\. - More information about the format of the result can be found in section - [TEXT DICT DATA STRUCTURE](#section3)\. This command returns the - *canonical* representation of the input\. - - - __::rcs::dict2text__ *dict* - - This command provides the complementary operation to - __::rcs::text2dict__\. It converts a dictionary in the form described in - section [TEXT DICT DATA STRUCTURE](#section3) back into a text and - returns that text as its result\. The command does accept non\-canonical - representations of the text as its input\. - - - __::rcs::file2dict__ *filename* - - This command is identical to __::rcs::text2dict__, except that it reads - the text to convert from the file with path *filename*\. The file has to - exist and must be readable as well\. - - - __::rcs::dict2file__ *filename* *dict* - - This command is identical to __::rcs::2dict2text__, except that it - stores the resulting text in the file with path *filename*\. The file is - created if it did not exist, and must be writable\. The result of the command - is the empty string\. - - - __::rcs::decodeRcsPatch__ *text* - - Converts the *text* argument into a patch command list \(PCL\) as specified - in the section [RCS PATCH COMMAND LIST](#section5) and returns this - list as its result\. It is assumed that the input text is in *[diff \-n - format](\.\./\.\./\.\./\.\./index\.md\#diff\_n\_format)*, also known as *[RCS - patch](\.\./\.\./\.\./\.\./index\.md\#rcs\_patch)* format, as specified in the - section [RCS PATCH FORMAT](#section4)\. Please note that the command - ignores no\-ops in the input, in other words the resulting PCL contains only - instructions doing something\. - - - __::rcs::encodeRcsPatch__ *pcmds* - - This command provides the complementary operation to - __::rcs::decodeRcsPatch__\. It convert a patch comand list \(PCL\) list as - specified in the section [RCS PATCH COMMAND LIST](#section5) back into - a text in [RCS PATCH FORMAT](#section4) and returns that text as its - result\. - - Note that this command and __::rcs::decodeRcsPatch__ are not exactly - complementary, as the latter strips no\-ops from its input, which the encoder - cannot put back anymore into the generated RCS patch\. In other words, the - result of a decode/encode step may not match the original input at the - character level, but it will match it at the functional level\. - - - __::rcs::applyRcsPatch__ *text* *pcmds* - - This operation applies a patch in the form of a PCL to a text given in the - form of a dictionary and returns the modified text, again as dictionary, as - its result\. - - To handle actual text use the commands __::rcs::text2dict__ \(or - equivalent\) and __::rcs::decodeRcsPatch__ to transform the inputs into - data structures acceptable to this command\. Analogously use the command - __::rcs::dict2text__ \(or equivalent\) to transform the result of this - command into actuall text as required\. - -# TEXT DICT DATA STRUCTURE - -A text dictionary is a dictionary whose keys are integer numbers and text -strings as the associated values\. The keys represent the line numbers of a text -and the values the text of that line\. Note that one text can have many -representations as a dictionary, as the index values only have to be properly -ordered for reconstruction, their exact values do not matter\. Similarly the -strings may actually span multiple physical lines\. - -The text - - Hello World, - how are you ? - Fine, and you ? - -for example can be represented by - - {{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}} - -or - - {{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}} - -or - - {{-1 {Hello World, - how are you ?}} {4 {Fine, and you ?}}} - -The first dictionary is the *canonical* representation of the text, with line -numbers starting at __1__, increasing in steps of __1__ and without -gaps, and each value representing exactly one physical line\. - -All the commands creating dictionaries from text will return the canonical -representation of their input text\. The commands taking a dictionary and -returning text will generally accept all representations, canonical or not\. - -The result of applying a patch to a text dictionary will in general cause the -dictionary to become non\-canonical\. - -# RCS PATCH FORMAT - -A *[patch](\.\./\.\./\.\./\.\./index\.md\#patch)* is in general a series of -instructions how to transform an input text T into a different text T', and also -encoded in text form as well\. - -The text format for patches understood by this package is a very simple one, -known under the names *[RCS patch](\.\./\.\./\.\./\.\./index\.md\#rcs\_patch)* or -*[diff \-n format](\.\./\.\./\.\./\.\./index\.md\#diff\_n\_format)*\. - -Patches in this format contain only two different commands, for the deletion of -old text, and addition of new text\. The replacement of some text by a different -text is handled as combination of a deletion following by an addition\. - -The format is line oriented, with each line containing either a command or text -data associated with the preceding command\. The first line of a *[RCS -patch](\.\./\.\./\.\./\.\./index\.md\#rcs\_patch)* is always a command line\. - -The commands are: - - - "" - - The empty line is a command which does nothing\. - - - "a__start__ __n__" - - A line starting with the character __a__ is a command for the addition - of text to the output\. It is followed by __n__ lines of text data\. When - applying the patch the data is added just between the lines __start__ - and __start__\+1\. The same effect is had by appending the data to the - existing text on line __start__\. A non\-existing line __start__ is - created\. - - - "d__start__ __n__" - - A line starting with the character __d__ is a command for the deletion - of text from the output\. When applied it deletes __n__ lines of text, - and the first line deleted is at index __start__\. - -Note that the line indices __start__ always refer to the text which is -transformed as it is in its original state, without taking the precending -changes into account\. - -Note also that the instruction have to be applied in the order they occur in the -patch, or in a manner which produces the same result as in\-order application\. - -This is the format of results returned by the command -__::rcs::decodeRcsPatch__ and accepted by the commands -__::rcs::encodeRcsPatch__ and __::rcs::appplyRcsPatch__ resp\. Note -however that the decoder will strip no\-op commands, and the encoder will not -generate no\-ops, making them not fully complementary at the textual level, only -at the functional level\. - -And example of a RCS patch is - - d1 2 - d4 1 - a4 2 - The named is the mother of all things. - - a11 3 - They both may be called deep and profound. - Deeper and more profound, - The door of all subtleties! - -# RCS PATCH COMMAND LIST - -Patch command lists \(sort: PCL's\) are the data structures generated by patch -decoder command and accepted by the patch encoder and applicator commands\. They -represent RCS patches in the form of Tcl data structures\. - -A PCL is a list where each element represents a single patch instruction, either -an addition, or a deletion\. The elements are lists themselves, where the first -item specifies the command and the remainder represent the arguments of the -command\. - - - a - - This is the instruction for the addition of text\. It has two arguments, the - index of the line where to add the text, and the text to add, in this order\. - - - d - - This is the instruction for the deletion of text\. It has two arguments, the - index of the line where to start deleting text, and the number of lines to - delete, in this order\. - -This is the format returned by the patch decoder command and accepted as input -by the patch encoder and applicator commands\. - -An example for a patch command is shown below, it represents the example RCS -patch found in section [RCS PATCH FORMAT](#section4)\. - - {{d 1 2} {d 4 1} {a 4 {The named is the mother of all things. - - }} {a 11 {They both may be called deep and profound. - Deeper and more profound, - The door of all subtleties!}}} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *rcs* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[struct](\.\./\.\./\.\./\.\./index\.md\#struct), -[textutil](\.\./textutil/textutil\.md) - -# KEYWORDS - -[CVS](\.\./\.\./\.\./\.\./index\.md\#cvs), [RCS](\.\./\.\./\.\./\.\./index\.md\#rcs), [RCS -patch](\.\./\.\./\.\./\.\./index\.md\#rcs\_patch), -[SCCS](\.\./\.\./\.\./\.\./index\.md\#sccs), [diff \-n -format](\.\./\.\./\.\./\.\./index\.md\#diff\_n\_format), -[patching](\.\./\.\./\.\./\.\./index\.md\#patching), [text -conversion](\.\./\.\./\.\./\.\./index\.md\#text\_conversion), [text -differences](\.\./\.\./\.\./\.\./index\.md\#text\_differences) - -# CATEGORY - -Text processing - -# COPYRIGHT - -Copyright © 2005, Andreas Kupries -Copyright © 2005, Colin McCormack DELETED embedded/md/tcllib/files/modules/report/report.md Index: embedded/md/tcllib/files/modules/report/report.md ================================================================== --- embedded/md/tcllib/files/modules/report/report.md +++ embedded/md/tcllib/files/modules/report/report.md @@ -1,458 +0,0 @@ - -[//000000001]: # (report \- Matrix reports) -[//000000002]: # (Generated from file 'report\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2014 Andreas Kupries ) -[//000000004]: # (report\(n\) 0\.3\.2 tcllib "Matrix reports") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -report \- Create and manipulate report objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [REGIONS](#section2) - - - [LINES](#section3) - - - [TEMPLATES](#section4) - - - [STYLES](#section5) - - - [REPORT METHODS](#section6) - - - [EXAMPLES](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require report ?0\.3\.2? - -[__::report::report__ *reportName* *columns* ?__style__ *style arg\.\.\.*?](#1) -[__reportName__ *option* ?*arg arg \.\.\.*?](#2) -[__::report::defstyle__ *styleName arguments script*](#3) -[__::report::rmstyle__ *styleName*](#4) -[__::report::stylearguments__ *styleName*](#5) -[__::report::stylebody__ *styleName*](#6) -[__::report::styles__](#7) -[*reportName* __destroy__](#8) -[*reportName* *templatecode* __disable__|__enable__](#9) -[*reportName* *templatecode* __enabled__](#10) -[*reportName* *templatecode* __get__](#11) -[*reportName* *templatecode* __set__ *templatedata*](#12) -[*reportName* __tcaption__ ?*size*?](#13) -[*reportName* __bcaption__ *size*](#14) -[*reportName* __size__ *column* ?*number*|__dyn__?](#15) -[*reportName* __sizes__ ?*size\-list*?](#16) -[*reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*??](#17) -[*reportName* __justify__ *column* ?__left__|__right__|__center__?](#18) -[*reportName* __printmatrix__ *matrix*](#19) -[*reportName* __printmatrix2channel__ *matrix chan*](#20) -[*reportName* __[columns](\.\./\.\./\.\./\.\./index\.md\#columns)__](#21) - -# DESCRIPTION - -This package provides report objects which can be used by the formatting methods -of matrix objects to generate tabular reports of the matrix in various forms\. -The report objects defined here break each report down into three -[REGIONS](#section2) and ten classes of -*[lines](\.\./\.\./\.\./\.\./index\.md\#lines)* \(various separator\- and data\-lines\)\. -See the following section for more detailed explanations\. - - - __::report::report__ *reportName* *columns* ?__style__ *style arg\.\.\.*? - - Creates a new report object for a report having *columns* columns with an - associated global Tcl command whose name is *reportName*\. This command may - be used to invoke various configuration operations on the report\. It has the - following general form: - - * __reportName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - See section [REPORT METHODS](#section6) for more explanations\. If - no __style__ is specified the report will use the builtin style - __plain__ as its default configuration\. - - - __::report::defstyle__ *styleName arguments script* - - Defines the new style *styleName*\. See section [STYLES](#section5) - for more information\. - - - __::report::rmstyle__ *styleName* - - Deletes the style *styleName*\. Trying to delete an unknown or builtin - style will result in an error\. Beware, this command will not check that - there are no other styles depending on the deleted one\. Deleting a style - which is still used by another style FOO will result in a runtime error when - FOO is applied to a newly instantiated report\. - - - __::report::stylearguments__ *styleName* - - This introspection command returns the list of arguments associated with the - style *styleName*\. - - - __::report::stylebody__ *styleName* - - This introspection command returns the script associated with the style - *styleName*\. - - - __::report::styles__ - - This introspection command returns a list containing the names of all styles - known to the package at the time of the call\. The order of the names in the - list reflects the order in which the styles were created\. In other words, - the first item is the predefined style __plain__, followed by the first - style defined by the user, and so on\. - -# REGIONS - -The three regions are the *top caption*, *data area* and *bottom caption*\. -These are, roughly speaking, the title, the values to report and a title at the -bottom\. The size of the caption regions can be specified by the user as the -number of rows they occupy in the matrix to format\. The size of the data area is -specified implicitly\. - -# LINES - -[TEMPLATES](#section4) are associated with each of the ten line classes, -defining the formatting for this kind of line\. The user is able to enable and -disable the separator lines at will, but not the data lines\. Their usage is -solely determined by the number of rows contained in the three regions\. Data -lines and all enabled separators must have a template associated with them\. - -Note that the data\-lines in a report and the rows in the matrix the report was -generated from are *not* in a 1:1 relationship if any row in the matrix has a -height greater than one\. - -The different kinds of lines and the codes used by the report methods to address -them are: - - - __top__ - - The topmost line of a report\. Separates the report from anything which came - before it\. The user can enable the usage of this line at will\. - - - __topdatasep__ - - This line is used to separate the data rows in the top caption region, if it - contains more than one row and the user enabled its usage\. - - - __topcapsep__ - - This line is used to separate the top caption and data regions, if the top - caption is not empty and the user enabled its usage\. - - - __datasep__ - - This line is used to separate the data rows in the data region, if it - contains more than one row and the user enabled its usage\. - - - __botcapsep__ - - This line is used to separate the data and bottom caption regions, if the - bottom caption is not empty and the user enabled its usage\. - - - __botdatasep__ - - This line is used to separate the data rows in the bottom caption region, if - it contains more than one row and the user enabled its usage\. - - - __bottom__ - - The bottommost line of a report\. Separates the report from anything which - comes after it\. The user can enable the usage of this line at will\. - - - __topdata__ - - This line defines the format of data lines in the top caption region of the - report\. - - - __data__ - - This line defines the format of data lines in the data region of the report\. - - - __botdata__ - - This line defines the format of data lines in the bottom caption region of - the report\. - -# TEMPLATES - -Each template is a list of strings used to format the line it is associated -with\. For a report containing __n__ columns a template for a data line has -to contain "__n__\+1" items and a template for a separator line -"2\*__n__\+1" items\. - -The items in a data template specify the strings used to separate the column -information\. Together with the corresponding items in the separator templates -they form the vertical lines in the report\. - -*Note* that the corresponding items in all defined templates have to be of -equal length\. This will be checked by the report object\. The first item defines -the leftmost vertical line and the last item defines the rightmost vertical -line\. The item at index __k__ \("1",\.\.\.,"__n__\-2"\) separates the -information in the columns "__k__\-1" and "__k__"\. - -The items in a separator template having an even\-numbered index \("0","2",\.\.\.\) -specify the column separators\. The item at index "2\*__k__" -\("0","2",\.\.\.,"2\*__n__"\) corresponds to the items at index "__k__" in the -data templates\. - -The items in a separator template having an odd\-numbered index \("1","3",\.\.\.\) -specify the strings used to form the horizontal lines in the separator lines\. -The item at index "2\*__k__\+1" \("1","3",\.\.\.,"2\*__n__\+1"\) corresponds to -column "__k__"\. When generating the horizontal lines the items are -replicated to be at least as long as the size of their column and then cut to -the exact size\. - -# STYLES - -Styles are a way for the user of this package to define common configurations -for report objects and then use them later during the actual instantiation of -report objects\. They are defined as tcl scripts which when executed configure -the report object into the requested configuration\. - -The command to define styles is __::report::defstyle__\. Its last argument is -the tcl __script__ performing the actual reconfiguration of the report -object to obtain the requested style\. - -In this script the names of all previously defined styles are available as -commands, as are all commands found in a safe interpreter and the configuration -methods of report objects\. The latter implicitly operate on the object currently -executing the style script\. The __arguments__ declared here are available in -the __script__ as variables\. When calling the command of a previously -declared style all the arguments expected by it have to be defined in the call\. - -# REPORT METHODS - -The following commands are possible for report objects: - - - *reportName* __destroy__ - - Destroys the report, including its storage space and associated command\. - - - *reportName* *templatecode* __disable__|__enable__ - - Enables or disables the usage of the template addressed by the - *templatecode*\. Only the codes for separator lines are allowed here\. It is - not possible to enable or disable data lines\. - - Enabling a template causes the report to check all used templates for - inconsistencies in the definition of the vertical lines \(See section - [TEMPLATES](#section4)\)\. - - - *reportName* *templatecode* __enabled__ - - Returns the whether the template addressed by the *templatecode* is - currently enabled or not\. - - - *reportName* *templatecode* __get__ - - Returns the template currently associated with the kind of line addressed by - the *templatecode*\. All known templatecodes are allowed here\. - - - *reportName* *templatecode* __set__ *templatedata* - - Sets the template associated with the kind of line addressed by the - *templatecode* to the new value in *templatedata*\. See section - [TEMPLATES](#section4) for constraints on the length of templates\. - - - *reportName* __tcaption__ ?*size*? - - Specifies the *size* of the top caption region as the number rows it - occupies in the matrix to be formatted\. Only numbers greater than or equal - to zero are allowed\. If no *size* is specified the command will return the - current size instead\. - - Setting the size of the top caption to a value greater than zero enables the - corresponding data template and causes the report to check all used - templates for inconsistencies in the definition of the vertical lines \(See - section [TEMPLATES](#section4)\)\. - - - *reportName* __bcaption__ *size* - - Specifies the *size* of the bottom caption region as the number rows it - occupies in the matrix to be formatted\. Only numbers greater than or equal - to zero are allowed\. If no *size* is specified the command will return the - current size instead\. - - Setting the size of the bottom caption to a value greater than zero enables - the corresponding data template and causes the report to check all used - templates for inconsistencies in the definition of the vertical lines \(See - section [TEMPLATES](#section4)\)\. - - - *reportName* __size__ *column* ?*number*|__dyn__? - - Specifies the size of the *column* in the output\. The value __dyn__ - means that the columnwidth returned by the matrix to be formatted for the - specified column shall be used\. The formatting of the column is dynamic\. If - a fixed *number* is used instead of __dyn__ it means that the column - has a width of that many characters \(padding excluded\)\. Only numbers greater - than zero are allowed here\. - - If no size specification is given the command will return the current size - of the *column* instead\. - - - *reportName* __sizes__ ?*size\-list*? - - This method allows the user to specify the sizes of all columns in one call\. - Its argument is a list containing the sizes to associate with the columns\. - The first item is associated with column 0, the next with column 1, and so - on\. - - If no *size\-list* is specified the command will return a list containing - the currently set sizes instead\. - - - *reportName* __pad__ *column* ?__left__|__right__|__both__ ?*padstring*?? - - This method allows the user to specify padding on the left, right or both - sides of a *column*\. If the *padstring* is not specified it defaults to - a single space character\. *Note*: An alternative way of specifying the - padding is to use vertical separator strings longer than one character in - the templates \(See section [TEMPLATES](#section4)\)\. - - If no pad specification is given at all the command will return the current - state of padding for the column instead\. This will be a list containing two - elements, the first element the left padding, the second describing the - right padding\. - - - *reportName* __justify__ *column* ?__left__|__right__|__center__? - - Declares how the cell values for a *column* are filled into the report - given the specified size of a column in the report\. - - For __left__ and __right__ justification a cell value shorter than - the width of the column is bound with its named edge to the same edge of the - column\. The other side is filled with spaces\. In the case of __center__ - the spaces are placed to both sides of the value and the left number of - spaces is at most one higher than the right number of spaces\. - - For a value longer than the width of the column the value is cut at the - named edge\. This means for __left__ justification that the *tail* - \(i\.e\. the __right__ part\) of the value is made visible in the output\. - For __center__ the value is cut at both sides to fit into the column and - the number of characters cut at the left side of the value is at most one - less than the number of characters cut from the right side\. - - If no justification was specified the command will return the current - justification for the column instead\. - - - *reportName* __printmatrix__ *matrix* - - Formats the *matrix* according to the configuration of the report and - returns the resulting string\. The matrix has to have the same number of - columns as the report\. The matrix also has to have enough rows so that the - top and bottom caption regions do not overlap\. The data region is allowed to - be empty\. - - - *reportName* __printmatrix2channel__ *matrix chan* - - Formats the *matrix* according to the configuration of the report and - writes the result into the channel *chan*\. The matrix has to have the same - number of columns as the report\. The matrix also has to have enough rows so - that the top and bottom caption regions do not overlap\. The data region is - allowed to be empty\. - - - *reportName* __[columns](\.\./\.\./\.\./\.\./index\.md\#columns)__ - - Returns the number of columns in the report\. - -The methods __size__, __pad__ and __justify__ all take a column -index as their first argument\. This index is allowed to use all the forms of an -index as accepted by the __lindex__ command\. The allowed range for indices -is "0,\.\.\.,\[__reportName__ columns\]\-1"\. - -# EXAMPLES - -Our examples define some generally useful report styles\. - -A simple table with lines surrounding all information and vertical separators, -but without internal horizontal separators\. - - ::report::defstyle simpletable {} { - data set [split "[string repeat "| " [columns]]|"] - top set [split "[string repeat "+ - " [columns]]+"] - bottom set [top get] - top enable - bottom enable - } - -An extension of a __simpletable__, see above, with a title area\. - - ::report::defstyle captionedtable {{n 1}} { - simpletable - topdata set [data get] - topcapsep set [top get] - topcapsep enable - tcaption $n - } - -Given the definitions above now an example which actually formats a matrix into -a tabular report\. It assumes that the matrix actually contains useful data\. - - % ::struct::matrix m - % # ... fill m with data, assume 5 columns - % ::report::report r 5 style captionedtable 1 - % r printmatrix m - +---+-------------------+-------+-------+--------+ - |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| - +---+-------------------+-------+-------+--------+ - |001|CATCH return ok |7 |13 |53.85 | - |002|CATCH return error |68 |91 |74.73 | - |003|CATCH no catch used|7 |14 |50.00 | - |004|IF if true numeric |12 |33 |36.36 | - |005|IF elseif |15 |47 |31.91 | - | |true numeric | | | | - +---+-------------------+-------+-------+--------+ - % - % # alternate way of doing the above - % m format 2string r - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *report* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[report](\.\./\.\./\.\./\.\./index\.md\#report), -[table](\.\./\.\./\.\./\.\./index\.md\#table) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002\-2014 Andreas Kupries DELETED embedded/md/tcllib/files/modules/rest/rest.md Index: embedded/md/tcllib/files/modules/rest/rest.md ================================================================== --- embedded/md/tcllib/files/modules/rest/rest.md +++ embedded/md/tcllib/files/modules/rest/rest.md @@ -1,579 +0,0 @@ - -[//000000001]: # (rest \- A framework for RESTful web services) -[//000000002]: # (Generated from file 'rest\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (rest\(n\) 1\.3\.1 tcllib "A framework for RESTful web services") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -rest \- define REST web APIs and call them inline or asychronously - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Simple usage](#section2) - - - [Interface usage](#section3) - - - [Examples](#section4) - - - [INCLUDED](#section5) - - - [TLS](#section6) - - - [TLS Security Considerations](#section7) - - - [Bugs, Ideas, Feedback](#section8) - -# SYNOPSIS - -package require Tcl 8\.5 -package require rest ?1\.3\.1? - -[__::rest::simple__ *url* *query* ?*config*? ?*body*?](#1) -[__::rest::get__ *url* *query* ?*config*? ?*body*?](#2) -[__::rest::post__ *url* *query* ?*config*? ?*body*?](#3) -[__::rest::patch__ *url* *query* ?*config*? ?*body*?](#4) -[__::rest::head__ *url* *query* ?*config*? ?*body*?](#5) -[__::rest::put__ *url* *query* ?*config*? ?*body*?](#6) -[__::rest::delete__ *url* *query* ?*config*? ?*body*?](#7) -[__::rest::save__ *name* *file*](#8) -[__::rest::describe__ *name*](#9) -[__::rest::parameters__ *url* ?*key*?](#10) -[__::rest::parse\_opts__ *static* *required* *optional* *words*](#11) -[__::rest::substitute__ *string* *var*](#12) -[__::rest::create\_interface__ *name*](#13) - -# DESCRIPTION - -There are two types of usage this package supports: *simple calls*, and -complete *interfaces*\. In an *interface* you specify a set of rules and then -the package builds the commands which correspond to the REST methods\. These -commands can have many options such as input and output transformations and data -type specific formatting\. This results in a cleaner and simpler script\. On the -other hand, while a *simple call* is easier and quicker to implement it is -also less featureful\. It takes the url and a few options about the command and -returns the result directly\. Any formatting or checking is up to rest of the -script\. - -# Simple usage - -In simple usage you make calls using the http method procedures and then check -or process the returned data yourself - - - __::rest::simple__ *url* *query* ?*config*? ?*body*? - - - __::rest::get__ *url* *query* ?*config*? ?*body*? - - - __::rest::post__ *url* *query* ?*config*? ?*body*? - - - __::rest::patch__ *url* *query* ?*config*? ?*body*? - - - __::rest::head__ *url* *query* ?*config*? ?*body*? - - - __::rest::put__ *url* *query* ?*config*? ?*body*? - - - __::rest::delete__ *url* *query* ?*config*? ?*body*? - - These commands are all equivalent except for the http method used\. If you - use __simple__ then the method should be specified as an option in the - *config* dictionary\. If that is not done it defaults to __get__\. If a - *body* is needed then the *config* dictionary must be present, however - it is allowed to be empty\. - - The *config* dictionary supports the following keys - - * __auth__ - - * __content\-type__ - - * __cookie__ - - * __error\-body__ - - * __format__ - - * __headers__ - - * __method__ - - Two quick examples: - - Example 1, Yahoo Boss: - - set appid APPID - set search tcl - set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]] - set res [rest::format_json $res] - - Example 2, Twitter: - - set url http://twitter.com/statuses/update.json - set query [list status $text] - set res [rest::simple $url $query { - method post - auth {basic user password} - format json - }] - -# Interface usage - -An interface to a REST API consists of a series of definitions of REST calls -contained in an array\. The name of that array becomes a namespace containing the -defined commands\. Each key of the array specifies the name of the call, with the -associated configuration a dictionary, i\.e\. key/value pairs\. The acceptable -keys, i\.e\. legal configuration options are described below\. After creating the -definitions in the array simply calling __rest::create\_interface__ with the -array as argument will then create the desired commands\. - -Example, Yahoo Weather: - - package require rest - - set yweather(forecast) { - url http://weather.yahooapis.com/forecastrss - req_args { p: } - opt_args { u: } - } - rest::create_interface yweather - puts [yweather::forecast -p 94089] - - - __::rest::save__ *name* *file* - - This command saves a copy of the dynamically created procedures for all the - API calls specified in the array variable *name* to the *file*, for - later loading\. - - The result of the command is the empty string - - - __::rest::describe__ *name* - - This command prints a description of all API calls specified in the array - variable *name* to the channel __stdout__\. - - The result of the command is the empty string\. - - - __::rest::parameters__ *url* ?*key*? - - This command parses an *url* query string into a dictionary and returns - said dictionary as its result\. - - If *key* is specified the command will not return the entire dictionary, - but only the value of that *key*\. - - - __::rest::parse\_opts__ *static* *required* *optional* *words* - - This command implements a custom parserfor command options\. - - * dict *static* - - A dictionary of options and their values that are always present in the - output\. - - * list *required* - - A list of options that must be supplied by *words* - - * list *optional* - - A list of options that may appear in the *words*, but are not - required\. The elements must be in one of three forms: - - + name - - The option may be present or not, no default\. - - + name: - - When present the option requires an argument\. - - + name:value - - When not present use __value__ as default\. - - * list *words* - - The words to parse into options and values\. - - The result of the command is a list containing two elements\. The first - element is a dictionary containing the parsed options and their values\. The - second element is a list of the remaining words\. - - - __::rest::substitute__ *string* *var* - - This command takes a *string*, substitutes values for any option - identifiers found inside and returns the modified string as its results\. - - The values to substitute are found in the variable *var*, which is - expected to contain a dictionary mapping from the option identifiers to - replace to their values\. *Note* that option identifiers which have no key - in *var* are replaced with the empty string\. - - The option identifiers in *string* have to follow the syntax __%\.\.\.%__ - where __\.\.\.__ may contain any combination of lower\-case alphanumeric - characters, plus underscore, colon and dash\. - - - __::rest::create\_interface__ *name* - - This command creates procedures for all the API calls specified in the array - variable *name*\. - - The name of that array becomes a namespace containing the defined commands\. - Each key of the array specifies the name of the call, with the associated - configuration a dictionary, i\.e\. key/value pairs\. The legal keys and their - meanings are: - - * __url__ - - The value of this *required* option must be the target of the http - request\. - - * __description__ - - The value of this option must be a short string describing the call\. - Default to the empty string, if not specified\. Used only by - __::rest::describe__\. - - * __body__ - - The value of this option indicates if arguments are required for the - call's request body or not\. The acceptable values are listed below\. - Defaults to __optional__ if not specified\. - - + __none__ - - The call has no request body, none must be supplied\. - - + __optional__ - - A request body can be supplied, but is not required\. - - + __required__ - - A request body must be supplied\. - - + __argument__ - - This value must be followed by the name of an option, treating the - entire string as a list\. The request body will be used as the value - of that option\. - - + __mime\_multipart__ - - A request body must be supplied and will be interpreted as each - argument representing one part of a mime/multipart document\. - Arguments must be lists containing 2 elements, a list of header keys - and values, and the mime part body, in this order\. - - * __method__ - - The value of this option must be the name of the HTTP method to call on - the url\. Defaults to GET, if not specified\. The acceptable values are - __GET__, __POST__, and __PUT__, regardless of letter\-case\. - - * __copy__ - - When present the value of this option specifies the name of a previously - defined call\. The definition of that call is copied to the current call, - except for the options specified by the current call itself\. - - * __unset__ - - When present the value of this option contains a list of options in the - current call\. These options are removed from the definition\. Use this - after __copy__ing an existing definition to remove options, instead - of overriding their value\. - - * __headers__ - - Specification of additional header fields\. The value of this option must - be a dictionary, interpreted to contain the new header fields and their - values\. The default is to not add any additional headers\. - - * __content\-type__ - - The value of this option specifies the content type for the request - data\. - - * __req\_args__ - - The value of this option is a list naming the required arguments of the - call\. Names ending in a colon will require a value\. - - * __opt\_args__ - - The value of this option a list naming the arguments that may be present - for a call but are not required\. - - * __static\_args__ - - The value of this option a list naming the arguments that are always the - same\. No sense in troubling the user with these\. A leading dash - \(__\-__\) is allowed but not required to maintain consistency with the - command line\. - - * __auth__ - - The value of this option specifies how to authenticate the calls\. No - authentication is done if the option is not specified\. - - + __basic__ - - The user may configure the *basic authentication* by overriding - the procedure __basic\_auth__ in the namespace of interface\. This - procedure takes two arguments, the username and password, in this - order\. - - + __sign__ - - The value must actually be a list with the second element the name - of a procedure which will be called to perform request signing\. - - * __callback__ - - If this option is present then the method will be created as an - *async* call\. Such calls will return immediately with the value of the - associated http token instead of the call's result\. The event loop must - be active to use this option\. - - The value of this option is treated as a command prefix which is invoked - when the HTTP call is complete\. The prefix will receive at least two - additional arguments, the name of the calling procedure and the status - of the result \(one of __OK__ or __ERROR__\), in this order\. - - In case of __OK__ a third argument is added, the data associated - with the result\. - - If and only if the __ERROR__ is a redirection, the location - redirected to will be added as argument\. Further, if the configuration - key __error\-body__ is set to __true__ the data associated with - the result will be added as argument as well\. - - The http request header will be available in that procedure via - __upvar token token__\. - - * __cookie__ - - The value of this option is a list of cookies to be passed in the http - header\. This is a shortcut to the __headers__ option\. - - * __input\_transform__ - - The value of this option is a command prefix or script to perform a - transformation on the query before invoking the call\. A script transform - is wrapped into an automatically generated internal procedure\. - - If not specified no transformation is done\. - - The command \(prefix\) must accept a single argument, the query \(a - dictionary\) to transform, and must return the modified query \(again as - dictionary\) as its result\. The request body is accessible in the - transform command via __upvar body body__\. - - * __format__ - - * __result__ - - The value of this option specifies the format of the returned data\. - Defaults to __auto__ if not specified\. The acceptable values are: - - + __auto__ - - Auto detect between __xml__ and __json__\. - - + __discard__ - - + __json__ - - + __raw__ - - + __rss__ - - This is formatted as a special case of __xml__\. - - + __tdom__ - - + __xml__ - - * __pre\_transform__ - - The value of this option is a command prefix or script to perform a - transformation on the result of a call \(*before* the application of - the output transform as per __format__\)\. A script transform is - wrapped into an automatically generated internal procedure\. - - If not specified no transformation is done\. - - The command \(prefix\) must accept a single argument, the result to - transform, and must return the modified result as its result\. - - The http request header is accessible in the transform command via - __upvar token token__ - - * __post\_transform__ - - The value of this option is a command prefix or script to perform a - transformation on the result of a call \(*after* the application of the - output transform as per __format__\)\. A script transform is wrapped - into an automatically generated internal procedure\. - - If not specified no transformation is done\. - - The command \(prefix\) must accept a single argument, the result to - transform, and must return the modified result as its result\. - - The http request header is accessible in the transform command via - __upvar token token__ - - * __check\_result__ - - The value of this option must be list of two expressions, either of - which may be empty\. - - The first expression is checks the OK condition, it must return - __true__ when the result is satisfactory, and __false__ - otherwise\. - - The second expression is the ERROR condition, it must return - __false__ unless there is an error, then it has to return - __true__\. - - * __error\_body__ - - The value of this option determines whether to return the response when - encountering an HTTP error, or not\. The default is to not return the - response body on error\. - - See __callback__ above for more information\. - -# Examples - -Yahoo Geo: - - set ygeo(parse) { - url http://wherein.yahooapis.com/v1/document - method post - body { arg documentContent } - } - ygeo::parse "san jose ca" - # "san jose ca" will be interpreted as if it were specified as the -documentContent option - -Google Docs: - - set gdocs(upload) { - url http://docs.google.com/feeds/default/private/full - body mime_multipart - } - gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata] - -Delicious: - - set delicious(updated) { - url https://api.del.icio.us/v1/posts/update - auth basic - } - - rest::create_interface flickr - - flickr::basic_auth username password - -Flickr: - - set flickr(auth.getToken) { - url http://api.flickr.com/services/rest/ - req_args { api_key: secret: } - auth { sign do_signature } - } - - rest::create_interface flickr - - proc ::flickr::do_signature {query} { - # perform some operations on the query here - return $query - } - -# INCLUDED - -The package provides functional but incomplete implementations for the following -services: - - - __del\.icio\.us__ - - - __facebook__ - - - __flickr__ - - - __twitter__ - - - __google calendar__ - - - __yahoo boss__ - - - __yahoo weather__ - -Please either read the package's implementation, or use __rest::describe__ -after loading it for their details\. - -Do not forget developers' documentation on the respective sites either\. - -# TLS - -The __rest__ package can be used with -*[https](\.\./\.\./\.\./\.\./index\.md\#https)*\-secured services, by requiring the -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package and then registering it with -the __[http](\.\./\.\./\.\./\.\./index\.md\#http)__ package it is sitting on top -of\. Example - - package require tls - http::register https 443 ::tls::socket - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *rest* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. DELETED embedded/md/tcllib/files/modules/ripemd/ripemd128.md Index: embedded/md/tcllib/files/modules/ripemd/ripemd128.md ================================================================== --- embedded/md/tcllib/files/modules/ripemd/ripemd128.md +++ embedded/md/tcllib/files/modules/ripemd/ripemd128.md @@ -1,218 +0,0 @@ - -[//000000001]: # (ripemd128 \- RIPEMD Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'ripemd128\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Pat Thoyts ) -[//000000004]: # (ripemd128\(n\) 1\.0\.5 tcllib "RIPEMD Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ripemd128 \- RIPEMD\-128 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require ripemd128 ?1\.0\.5? - -[__::ripemd::ripemd128__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \]](#1) -[__::ripemd::hmac128__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \]](#2) -[__::ripemd::RIPEMD128Init__](#3) -[__::ripemd::RIPEMD128Update__ *token* *data*](#4) -[__::ripemd::RIPEMD128Final__ *token*](#5) -[__::ripemd::RIPEHMAC128Init__ *key*](#6) -[__::ripemd::RIPEHMAC128Update__ *token* *data*](#7) -[__::ripemd::RIPEHMAC128Final__ *token*](#8) - -# DESCRIPTION - -This package is an implementation in Tcl of the RIPEMD\-128 message\-digest -algorithm \(1\)\. This algorithm takes an arbitrary quantity of data and generates -a 128\-bit message digest from the input\. The RIPEMD\-128 algorithm is based upon -the MD4 algorithm \(2, 4\) but has been cryptographically strengthened against -weaknesses that have been found in MD4 \(4\)\. RIPEMD\-128 has been designed to be a -drop\-in replacement for MD4 and MD5 \(5\)\. If security is the major consideration, -then RIPEMD\-160 or SHA1 should be considered\. - -This package will use __Trf__ to accelerate the digest computation if -available\. In the absence of an accelerator package the pure\-Tcl implementation -will be used\. - -# COMMANDS - - - __::ripemd::ripemd128__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate the RIPEMD\-128 digest of the data given in string\. This is - returned as a binary string by default\. Giving the *\-hex* option will - return a hexadecimal encoded version of the digest\. - - The data to be hashed can be specified either as a string argument to the - ripemd128 command, or as a filename or a pre\-opened channel\. If the - *\-filename* argument is given then the file is opened, the data read and - hashed and the file is closed\. If the *\-channel* argument is given then - data is read from the channel until the end of file\. The channel is not - closed\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - - __::ripemd::hmac128__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the - RIPEMD\-128 digest algorithm\. HMACs are described in RFC 2104 \(6\) and provide - a RIPEMD\-128 digest that includes a key\. All options other than *\-key* are - as for the __::ripemd::ripemd128__ command\. - -# PROGRAMMING INTERFACE - -For the programmer, hash functions can be viewed as a bucket into which one -pours data\. When you have finished, you extract a value that is uniquely derived -from the data that was poured into the bucket\. The programming interface to the -hash operates on a token \(equivalent to the bucket\)\. You call -__RIPEMD128Init__ to obtain a token and then call __RIPEMD128Update__ as -many times as required to add data to the hash\. To release any resources and -obtain the hash value, you then call __RIPEMD128Final__\. An equivalent set -of functions gives you a keyed digest \(HMAC\)\. - -If you have __critcl__ and have built the __tcllibc__ package then the -implementation of the hashing function will be performed by compiled code\. -Alternatively if both the Trf and Memchan extensions are available then these -will be used\. Finally the package will revert to a pure\-Tcl implementation\. The -programming interface remains the same, however\. - - - __::ripemd::RIPEMD128Init__ - - Begins a new RIPEMD\-128 hash\. Returns a token ID that must be used for the - remaining functions\. - - - __::ripemd::RIPEMD128Update__ *token* *data* - - Add data to the hash identified by token\. Calling *RIPEMD128Update $token - "abcd"* is equivalent to calling *RIPEMD128Update $token "ab"* followed - by *RIPEMD128Update $token "cb"*\. See [EXAMPLES](#section4)\. - - - __::ripemd::RIPEMD128Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 16 bytes representing the 128 bit RIPEMD\-128 digest value\. - - - __::ripemd::RIPEHMAC128Init__ *key* - - This is equivalent to the __::ripemd::RIPEMD128Init__ command except - that it requires the key that will be included in the HMAC\. - - - __::ripemd::RIPEHMAC128Update__ *token* *data* - - - __::ripemd::RIPEHMAC128Final__ *token* - - These commands are identical to the RIPEMD128 equivalent commands\. - -# EXAMPLES - - % ripemd::ripemd128 -hex "Tcl does RIPEMD-128" - 3cab177bae65205d81e7978f63556c63 - - % ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128" - b359dc5971a05beea0be7b106b30e389 - - % set tok [ripemd::RIPEMD128Init] - ::ripemd::1 - % ripemd::RIPEMD128Update $tok "Tcl " - % ripemd::RIPEMD128Update $tok "does " - % ripemd::RIPEMD128Update $tok "RIPEMD-128" - % ripemd::Hex [ripemd::RIPEMD128Final $tok] - 3cab177bae65205d81e7978f63556c63 - -# REFERENCES - - 1. H\. Dobbertin, A\. Bosselaers, B\. Preneel, "RIPEMD\-160, a strengthened - version of RIPEMD" - [http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf](http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Rivest, R\., "The MD4 message digest algorithm", in A\.J\. Menezes and S\.A\. - Vanstone, editors, Advances in Cryptology \- CRYPTO '90 Proceedings, pages - 303\-311, Springer\-Verlag, 1991\. - - 1. Dobbertin, H\., "Cryptanalysis of MD4", Journal of Cryptology vol 11 \(4\), - pp\. 253\-271 \(1998\) - - 1. Rivest, R\., "The MD5 Message\-Digest Algorithm", RFC 1321, MIT and RSA Data - Security, Inc, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1321\.txt](http://www\.rfc\-editor\.org/rfc/rfc1321\.txt)\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ripemd* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), -[ripemd160](ripemd160\.md), [sha1](\.\./sha1/sha1\.md) - -# KEYWORDS - -[RIPEMD](\.\./\.\./\.\./\.\./index\.md\#ripemd), -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[md4](\.\./\.\./\.\./\.\./index\.md\#md4), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -1320](\.\./\.\./\.\./\.\./index\.md\#rfc\_1320), [rfc -1321](\.\./\.\./\.\./\.\./index\.md\#rfc\_1321), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2004, Pat Thoyts DELETED embedded/md/tcllib/files/modules/ripemd/ripemd160.md Index: embedded/md/tcllib/files/modules/ripemd/ripemd160.md ================================================================== --- embedded/md/tcllib/files/modules/ripemd/ripemd160.md +++ embedded/md/tcllib/files/modules/ripemd/ripemd160.md @@ -1,206 +0,0 @@ - -[//000000001]: # (ripemd160 \- RIPEMD Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'ripemd160\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Pat Thoyts ) -[//000000004]: # (ripemd160\(n\) 1\.0\.5 tcllib "RIPEMD Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -ripemd160 \- RIPEMD\-160 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require ripemd160 ?1\.0\.5? - -[__::ripemd::ripemd160__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \]](#1) -[__::ripemd::hmac160__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \]](#2) -[__::ripemd::RIPEMD160Init__](#3) -[__::ripemd::RIPEMD160Update__ *token* *data*](#4) -[__::ripemd::RIPEMD160Final__ *token*](#5) -[__::ripemd::RIPEHMAC160Init__ *key*](#6) -[__::ripemd::RIPEHMAC160Update__ *token* *data*](#7) -[__::ripemd::RIPEHMAC160Final__ *token*](#8) - -# DESCRIPTION - -This package is an implementation in Tcl of the RIPEMD\-160 message\-digest -algorithm \(1\)\. This algorithm takes an arbitrary quantity of data and generates -a 160\-bit message digest from the input\. The RIPEMD\-160 algorithm is based upon -the MD4 algorithm \(2, 4\) but has been cryptographically strengthened against -weaknesses that have been found in MD4 \(4\)\. - -This package will use __cryptkit__ or __Trf__ to accelerate the digest -computation if either package is available\. In the absence of an accelerator -package the pure\-Tcl implementation will be used\. - -# COMMANDS - - - __::ripemd::ripemd160__ ?*\-hex*? \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate the RIPEMD\-160 digest of the data given in string\. This is - returned as a binary string by default\. Giving the *\-hex* option will - return a hexadecimal encoded version of the digest\. - - The data to be hashed can be specified either as a string argument to the - ripemd160 command, or as a filename or a pre\-opened channel\. If the - *\-filename* argument is given then the file is opened, the data read and - hashed and the file is closed\. If the *\-channel* argument is given then - data is read from the channel until the end of file\. The channel is not - closed\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - - __::ripemd::hmac160__ ?*\-hex*? *\-key key* \[ *\-channel channel* | *\-file filename* | *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the - RIPEMD\-160 digest algorithm\. HMACs are described in RFC 2104 \(5\) and provide - a RIPEMD\-160 digest that includes a key\. All options other than *\-key* are - as for the __::ripemd::ripemd160__ command\. - -# PROGRAMMING INTERFACE - -For the programmer, hash functions can be viewed as a bucket into which one -pours data\. When you have finished, you extract a value that is uniquely derived -from the data that was poured into the bucket\. The programming interface to the -hash operates on a token \(equivalent to the bucket\)\. You call -__RIPEMD160Init__ to obtain a token and then call __RIPEMD160Update__ as -many times as required to add data to the hash\. To release any resources and -obtain the hash value, you then call __RIPEMD160Final__\. An equivalent set -of functions gives you a keyed digest \(HMAC\)\. - - - __::ripemd::RIPEMD160Init__ - - Begins a new RIPEMD\-160 hash\. Returns a token ID that must be used for the - remaining functions\. - - - __::ripemd::RIPEMD160Update__ *token* *data* - - Add data to the hash identified by token\. Calling *RIPEMD160Update $token - "abcd"* is equivalent to calling *RIPEMD160Update $token "ab"* followed - by *RIPEMD160Update $token "cb"*\. See [EXAMPLES](#section4)\. - - - __::ripemd::RIPEMD160Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 16 bytes representing the 160 bit RIPEMD\-160 digest value\. - - - __::ripemd::RIPEHMAC160Init__ *key* - - This is equivalent to the __::ripemd::RIPEMD160Init__ command except - that it requires the key that will be included in the HMAC\. - - - __::ripemd::RIPEHMAC160Update__ *token* *data* - - - __::ripemd::RIPEHMAC160Final__ *token* - - These commands are identical to the RIPEMD160 equivalent commands\. - -# EXAMPLES - - % ripemd::ripemd160 -hex "Tcl does RIPEMD-160" - 0829dea75a1a7074c702896723fe37763481a0a7 - - % ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160" - bf0c927231733686731dddb470b64a9c23f7f53b - - % set tok [ripemd::RIPEMD160Init] - ::ripemd::1 - % ripemd::RIPEMD160Update $tok "Tcl " - % ripemd::RIPEMD160Update $tok "does " - % ripemd::RIPEMD160Update $tok "RIPEMD-160" - % ripemd::Hex [ripemd::RIPEMD160Final $tok] - 0829dea75a1a7074c702896723fe37763481a0a7 - -# REFERENCES - - 1. H\. Dobbertin, A\. Bosselaers, B\. Preneel, "RIPEMD\-160, a strengthened - version of RIPEMD" - [http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf](http://www\.esat\.kuleuven\.ac\.be/~cosicart/pdf/AB\-9601/AB\-9601\.pdf) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Rivest, R\., "The MD4 message digest algorithm", in A\.J\. Menezes and S\.A\. - Vanstone, editors, Advances in Cryptology \- CRYPTO '90 Proceedings, pages - 303\-311, Springer\-Verlag, 1991\. - - 1. Dobbertin, H\., "Cryptanalysis of MD4", Journal of Cryptology vol 11 \(4\), - pp\. 253\-271 \(1998\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *ripemd* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), -[ripemd128](ripemd128\.md), [sha1](\.\./sha1/sha1\.md) - -# KEYWORDS - -[RIPEMD](\.\./\.\./\.\./\.\./index\.md\#ripemd), -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[md4](\.\./\.\./\.\./\.\./index\.md\#md4), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -1320](\.\./\.\./\.\./\.\./index\.md\#rfc\_1320), [rfc -1321](\.\./\.\./\.\./\.\./index\.md\#rfc\_1321), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2004, Pat Thoyts DELETED embedded/md/tcllib/files/modules/sasl/gtoken.md Index: embedded/md/tcllib/files/modules/sasl/gtoken.md ================================================================== --- embedded/md/tcllib/files/modules/sasl/gtoken.md +++ embedded/md/tcllib/files/modules/sasl/gtoken.md @@ -1,106 +0,0 @@ - -[//000000001]: # (SASL::XGoogleToken \- Simple Authentication and Security Layer \(SASL\)) -[//000000002]: # (Generated from file 'gtoken\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006, Pat Thoyts ) -[//000000004]: # (SASL::XGoogleToken\(n\) 1\.0\.1 tcllib "Simple Authentication and Security Layer \(SASL\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -SASL::XGoogleToken \- Implementation of SASL NTLM mechanism for Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TLS Security Considerations](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require SASL::XGoogleToken ?1\.0\.1? - -# DESCRIPTION - -This package provides the XGoogleToken authentication mechanism for the Simple -Authentication and Security Layer \(SASL\)\. - -Please read the documentation for package __sasl__ for details\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sasl* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[SASL](\.\./\.\./\.\./\.\./index\.md\#sasl), -[XGoogleToken](\.\./\.\./\.\./\.\./index\.md\#xgoogletoken), -[authentication](\.\./\.\./\.\./\.\./index\.md\#authentication) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2006, Pat Thoyts DELETED embedded/md/tcllib/files/modules/sasl/ntlm.md Index: embedded/md/tcllib/files/modules/sasl/ntlm.md ================================================================== --- embedded/md/tcllib/files/modules/sasl/ntlm.md +++ embedded/md/tcllib/files/modules/sasl/ntlm.md @@ -1,86 +0,0 @@ - -[//000000001]: # (SASL::NTLM \- Simple Authentication and Security Layer \(SASL\)) -[//000000002]: # (Generated from file 'ntlm\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2006, Pat Thoyts ) -[//000000004]: # (SASL::NTLM\(n\) 1\.1\.2 tcllib "Simple Authentication and Security Layer \(SASL\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -SASL::NTLM \- Implementation of SASL NTLM mechanism for Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [REFERENCES](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require SASL::NTLM ?1\.1\.2? - -# DESCRIPTION - -This package provides the NTLM authentication mechanism for the Simple -Authentication and Security Layer \(SASL\)\. - -Please read the documentation for package __sasl__ for details\. - -# REFERENCES - - 1. No official specification is available\. However, - [http://davenport\.sourceforge\.net/ntlm\.html](http://davenport\.sourceforge\.net/ntlm\.html) - provides a good description\. - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sasl* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[NTLM](\.\./\.\./\.\./\.\./index\.md\#ntlm), [SASL](\.\./\.\./\.\./\.\./index\.md\#sasl), -[authentication](\.\./\.\./\.\./\.\./index\.md\#authentication) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2005\-2006, Pat Thoyts DELETED embedded/md/tcllib/files/modules/sasl/sasl.md Index: embedded/md/tcllib/files/modules/sasl/sasl.md ================================================================== --- embedded/md/tcllib/files/modules/sasl/sasl.md +++ embedded/md/tcllib/files/modules/sasl/sasl.md @@ -1,371 +0,0 @@ - -[//000000001]: # (SASL \- Simple Authentication and Security Layer \(SASL\)) -[//000000002]: # (Generated from file 'sasl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2006, Pat Thoyts ) -[//000000004]: # (SASL\(n\) 1\.3\.3 tcllib "Simple Authentication and Security Layer \(SASL\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -SASL \- Implementation of SASL mechanisms for Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [OPTIONS](#section3) - - - [CALLBACK PROCEDURE](#section4) - - - [MECHANISMS](#section5) - - - [EXAMPLES](#section6) - - - [REFERENCES](#section7) - - - [AUTHORS](#section8) - - - [Bugs, Ideas, Feedback](#section9) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require SASL ?1\.3\.3? - -[__::SASL::new__ *option value ?\.\.\.?*](#1) -[__::SASL::configure__ *option value* ?*\.\.\.*?](#2) -[__::SASL::step__ *context* *challenge* ?*\.\.\.*?](#3) -[__::SASL::response__ *context*](#4) -[__::SASL::reset__ *context*](#5) -[__::SASL::cleanup__ *context*](#6) -[__::SASL::mechanisms__ ?*type*? ?*minimum*?](#7) -[__::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*?](#8) - -# DESCRIPTION - -The Simple Authentication and Security Layer \(SASL\) is a framework for providing -authentication and authorization to comunications protocols\. The SASL framework -is structured to permit negotiation among a number of authentication mechanisms\. -SASL may be used in SMTP, IMAP and HTTP authentication\. It is also in use in -XMPP, LDAP and BEEP\. See [MECHANISMS](#section5) for the set of available -SASL mechanisms provided with tcllib\. - -The SASL framework operates using a simple multi\-step challenge response -mechanism\. All the mechanisms work the same way although the number of steps may -vary\. In this implementation a callback procedure must be provided from which -the SASL framework will obtain users details\. See [CALLBACK -PROCEDURE](#section4) for details of this procedure\. - -# COMMANDS - - - __::SASL::new__ *option value ?\.\.\.?* - - Contruct a new SASL context\. See [OPTIONS](#section3) for details of - the possible options to this command\. A context token is required for most - of the SASL procedures\. - - - __::SASL::configure__ *option value* ?*\.\.\.*? - - Modify and inspect the SASL context option\. See [OPTIONS](#section3) - for further details\. - - - __::SASL::step__ *context* *challenge* ?*\.\.\.*? - - This is the core procedure for using the SASL framework\. The __step__ - procedure should be called until it returns 0\. Each step takes a server - challenge string and the response is calculated and stored in the context\. - Each mechanism may require one or more steps\. For some steps there may be no - server challenge required in which case an empty string should be provided - for this parameter\. All mechanisms should accept an initial empty challenge\. - - - __::SASL::response__ *context* - - Returns the next response string that should be sent to the server\. - - - __::SASL::reset__ *context* - - Re\-initialize the SASL context\. Discards any internal state and permits the - token to be reused\. - - - __::SASL::cleanup__ *context* - - Release all resources associated with the SASL context\. The context token - may not be used again after this procedure has been called\. - - - __::SASL::mechanisms__ ?*type*? ?*minimum*? - - Returns a list of all the available SASL mechanisms\. The list is sorted by - the mechanism preference value \(see __register__\) with the preferred - mechanisms and the head of the list\. Any mechanism with a preference value - less than the*minimum* \(which defaults to 0\) is removed from the returned - list\. This permits a security threshold to be set\. Mechanisms with a - preference less that 25 transmit authentication are particularly susceptible - to eavesdropping and should not be provided unless a secure channel is in - use \(eg: tls\)\. - - The *type* parameter may be one of *client* or *server* and defaults - to *client*\. Only mechanisms that have an implementation matching the - *type* are returned \(this permits servers to correctly declare support - only for mechanisms that actually provide a server implementation\)\. - - - __::SASL::register__ *mechanism* *preference* *clientproc* ?*serverproc*? - - New mechanisms can be added to the package by registering the mechanism name - and the implementing procedures\. The server procedure is optional\. The - preference value is an integer that is used to order the list returned by - the __mechanisms__ command\. Higher values indicate a preferred - mechanism\. If the mechanism is already registered then the recorded values - are updated\. - -# OPTIONS - - - __\-callback__ - - Specify a command to be evaluated when the SASL mechanism requires - information about the user\. The command is called with the current SASL - context and a name specifying the information desired\. See - [EXAMPLES](#section6)\. - - - __\-mechanism__ - - Set the SASL mechanism to be used\. See __mechanisms__ for a list of - supported authentication mechanisms\. - - - __\-service__ - - Set the service type for this context\. Some mechanisms may make use of this - parameter \(eg DIGEST\-MD5, GSSAPI and Kerberos\)\. If not set it defaults to an - empty string\. If the __\-type__ is set to 'server' then this option - should be set to a valid service identity\. Some examples of valid service - names are smtp, ldap, beep and xmpp\. - - - __\-server__ - - This option is used to set the server name used in SASL challenges when - operating as a SASL server\. - - - __\-type__ - - The context type may be one of 'client' or 'server'\. The default is to - operate as a client application and respond to server challenges\. Mechanisms - may be written to support server\-side SASL and setting this option will - cause each __step__ to issue the next challenge\. A new context must be - created for each incoming client connection when in server mode\. - -# CALLBACK PROCEDURE - -When the SASL framework requires any user details it will call the procedure -provided when the context was created with an argument that specfies the item of -information required\. - -In all cases a single response string should be returned\. - - - login - - The callback procedure should return the users authorization identity\. - Return an empty string unless this is to be different to the authentication - identity\. Read \[1\] for a discussion about the specific meaning of - authorization and authentication identities within SASL\. - - - username - - The callback procedure should return the users authentication identity\. Read - \[1\] for a discussion about the specific meaning of authorization and - authentication identities within SASL\. - - - password - - The callback procedure should return the password that matches the - authentication identity as used within the current realm\. - - For server mechanisms the password callback should always be called with the - authentication identity and the realm as the first two parameters\. - - - realm - - Some SASL mechanisms use realms to partition authentication identities\. The - realm string is protocol dependent and is often the current DNS domain or in - the case of the NTLM mechanism it is the Windows NT domain name\. - - - hostname - - Returns the client host name \- typically \[info host\]\. - -# MECHANISMS - - - ANONYMOUS - - As used in FTP this mechanism only passes an email address for - authentication\. The ANONYMOUS mechanism is specified in \[2\]\. - - - PLAIN - - This is the simplest mechanism\. The users authentication details are - transmitted in plain text\. This mechanism should not be provided unless an - encrypted link is in use \- typically after SSL or TLS has been negotiated\. - - - LOGIN - - The LOGIN \[1\] mechanism transmits the users details with base64 encoding\. - This is no more secure than PLAIN and likewise should not be used without a - secure link\. - - - CRAM\-MD5 - - This mechanism avoids sending the users password over the network in plain - text by hashing the password with a server provided random value \(known as a - nonce\)\. A disadvantage of this mechanism is that the server must maintain a - database of plaintext passwords for comparison\. CRAM\-MD5 was defined in \[4\]\. - - - DIGEST\-MD5 - - This mechanism improves upon the CRAM\-MD5 mechanism by avoiding the need for - the server to store plaintext passwords\. With digest authentication the - server needs to store the MD5 digest of the users password which helps to - make the system more secure\. As in CRAM\-MD5 the password is hashed with a - server nonce and other data before being transmitted across the network\. - Specified in \[3\]\. - - - OTP - - OTP is the One\-Time Password system described in RFC 2289 \[6\]\. This - mechanism is secure against replay attacks and also avoids storing password - or password equivalents on the server\. Only a digest of a seed and a - passphrase is ever transmitted across the network\. Requires the - __[otp](\.\./otp/otp\.md)__ package from tcllib and one or more of the - cryptographic digest packages \(md5 or sha\-1 are the most commonly used\)\. - - - NTLM - - This is a proprietary protocol developed by Microsoft \[5\] and is in common - use for authenticating users in a Windows network environment\. NTLM uses DES - encryption and MD4 digests of the users password to authenticate a - connection\. Certain weaknesses have been found in NTLM and thus there are a - number of versions of the protocol\. As this mechanism has additional - dependencies it is made available as a separate sub\-package\. To enable this - mechanism your application must load the __[SASL::NTLM](ntlm\.md)__ - package\. - - - X\-GOOGLE\-TOKEN - - This is a proprietary protocol developed by Google and used for - authenticating users for the Google Talk service\. This mechanism makes a - pair of HTTP requests over an SSL channel and so this mechanism depends upon - the availability of the tls and http packages\. To enable this mechanism your - application must load the __[SASL::XGoogleToken](gtoken\.md)__ - package\. In addition you are recommended to make use of the autoproxy - package to handle HTTP proxies reasonably transparently\. - - - SCRAM - - This is a protocol specified in RFC 5802 \[7\]\. To enable this mechanism your - application must load the __[SASL::SCRAM](scram\.md)__ package\. - -# EXAMPLES - -See the examples subdirectory for more complete samples using SASL with network -protocols\. The following should give an idea how the SASL commands are to be -used\. In reality this should be event driven\. Each time the __step__ command -is called, the last server response should be provided as the command argument -so that the SASL mechanism can take appropriate action\. - - proc ClientCallback {context command args} { - switch -exact -- $command { - login { return "" } - username { return $::tcl_platform(user) } - password { return "SecRet" } - realm { return "" } - hostname { return [info host] } - default { return -code error unxpected } - } - } - - proc Demo {{mech PLAIN}} { - set ctx [SASL::new -mechanism $mech -callback ClientCallback] - set challenge "" - while {1} { - set more_steps [SASL::step $ctx challenge] - puts "Send '[SASL::response $ctx]'" - puts "Read server response into challenge var" - if {!$more_steps} {break} - } - SASL::cleanup $ctx - } - -# REFERENCES - - 1. Myers, J\. "Simple Authentication and Security Layer \(SASL\)", RFC 2222, - October 1997\. - \([http://www\.ietf\.org/rfc/rfc2222\.txt](http://www\.ietf\.org/rfc/rfc2222\.txt)\) - - 1. Newman, C\. "Anonymous SASL Mechanism", RFC 2245, November 1997\. - \([http://www\.ietf\.org/rfc/rfc2245\.txt](http://www\.ietf\.org/rfc/rfc2245\.txt)\) - - 1. Leach, P\., Newman, C\. "Using Digest Authentication as a SASL Mechanism", - RFC 2831, May 2000, - \([http://www\.ietf\.org/rfc/rfc2831\.txt](http://www\.ietf\.org/rfc/rfc2831\.txt)\) - - 1. Klensin, J\., Catoe, R\. and Krumviede, P\., "IMAP/POP AUTHorize Extension for - Simple Challenge/Response" RFC 2195, September 1997\. - \([http://www\.ietf\.org/rfc/rfc2195\.txt](http://www\.ietf\.org/rfc/rfc2195\.txt)\) - - 1. No official specification is available\. However, - [http://davenport\.sourceforge\.net/ntlm\.html](http://davenport\.sourceforge\.net/ntlm\.html) - provides a good description\. - - 1. Haller, N\. et al\., "A One\-Time Password System", RFC 2289, February 1998, - \([http://www\.ieft\.org/rfc/rfc2289\.txt](http://www\.ieft\.org/rfc/rfc2289\.txt)\) - - 1. Newman, C\. et al\., "Salted Challenge Response Authentication Mechanism - \(SCRAM\) SASL and GSS\-API Mechanisms", RFC 5802, July 2010, - \([http://www\.ieft\.org/rfc/rfc5802\.txt](http://www\.ieft\.org/rfc/rfc5802\.txt)\) - -# AUTHORS - -Pat Thoyts - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sasl* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[SASL](\.\./\.\./\.\./\.\./index\.md\#sasl), -[authentication](\.\./\.\./\.\./\.\./index\.md\#authentication) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2005\-2006, Pat Thoyts DELETED embedded/md/tcllib/files/modules/sasl/scram.md Index: embedded/md/tcllib/files/modules/sasl/scram.md ================================================================== --- embedded/md/tcllib/files/modules/sasl/scram.md +++ embedded/md/tcllib/files/modules/sasl/scram.md @@ -1,86 +0,0 @@ - -[//000000001]: # (SASL::SCRAM \- Simple Authentication and Security Layer \(SASL\)) -[//000000002]: # (Generated from file 'scram\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2013 Sergei Golovan ) -[//000000004]: # (SASL::SCRAM\(n\) 0\.1 tcllib "Simple Authentication and Security Layer \(SASL\)") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -SASL::SCRAM \- Implementation of SASL SCRAM mechanism for Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [REFERENCES](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require SASL::SCRAM ?0\.1? - -# DESCRIPTION - -This package provides the SCRAM authentication mechanism for the Simple -Authentication and Security Layer \(SASL\)\. - -Please read the documentation for package __sasl__ for details\. - -# REFERENCES - - 1. Newman, C\. et al\., "Salted Challenge Response Authentication Mechanism - \(SCRAM\) SASL and GSS\-API Mechanisms", RFC 5802, July 2010, - \([http://www\.ieft\.org/rfc/rfc5802\.txt](http://www\.ieft\.org/rfc/rfc5802\.txt)\) - -# AUTHORS - -Sergei Golovan - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sasl* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[SASL](\.\./\.\./\.\./\.\./index\.md\#sasl), [SCRAM](\.\./\.\./\.\./\.\./index\.md\#scram), -[authentication](\.\./\.\./\.\./\.\./index\.md\#authentication) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2013 Sergei Golovan DELETED embedded/md/tcllib/files/modules/sha1/sha1.md Index: embedded/md/tcllib/files/modules/sha1/sha1.md ================================================================== --- embedded/md/tcllib/files/modules/sha1/sha1.md +++ embedded/md/tcllib/files/modules/sha1/sha1.md @@ -1,217 +0,0 @@ - -[//000000001]: # (sha1 \- SHA\-x Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'sha1\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005, Pat Thoyts ) -[//000000004]: # (sha1\(n\) 2\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -sha1 \- SHA1 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require sha1 ?2\.0\.4? - -[__::sha1::sha1__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#1) -[__::sha1::hmac__ *key* *string*](#2) -[__::sha1::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#3) -[__::sha1::SHA1Init__](#4) -[__::sha1::SHA1Update__ *token* *data*](#5) -[__::sha1::SHA1Final__ *token*](#6) -[__::sha1::HMACInit__ *key*](#7) -[__::sha1::HMACUpdate__ *token* *data*](#8) -[__::sha1::HMACFinal__ *token*](#9) - -# DESCRIPTION - -This package provides an implementation in Tcl of the SHA1 message\-digest -algorithm as specified by FIPS PUB 180\-1 \(1\)\. This algorithm takes a message and -generates a 160\-bit digest from the input\. The SHA1 algorithm is related to the -MD4 algorithm \(2\) but has been strengthend against certain types of -cryptographic attack\. SHA1 should be used in preference to MD4 or MD5 in new -applications\. - -This package also includes support for creating keyed message\-digests using the -HMAC algorithm from RFC 2104 \(3\) with SHA1 as the message\-digest\. - -# COMMANDS - - - __::sha1::sha1__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] - - The command takes a message and returns the SHA1 digest of this message as a - hexadecimal string\. You may request the result as binary data by giving - *\-bin*\. - - The data to be hashed can be specified either as a string argument to the - __sha1__ command, or as a filename or a pre\-opened channel\. If the - *\-filename* argument is given then the file is opened, the data read and - hashed and the file is closed\. If the *\-channel* argument is given then - data is read from the channel until the end of file\. The channel is not - closed\. *NOTE* use of the channel or filename options results in the - internal use of __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\. To avoid - nested event loops in Tk or tclhttpd applications you should use the - incremental programming API \(see below\)\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - If the *string* to hash can be mistaken for an option \(leading dash "\-"\), - use the option __\-\-__ before it to terminate option processing and force - interpretation as a string\. - - - __::sha1::hmac__ *key* *string* - - - __::sha1::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the SHA1 - digest algorithm\. HMACs are described in RFC 2104 \(3\) and provide an SHA1 - digest that includes a key\. All options other than *\-key* are as for the - __::sha1::sha1__ command\. - - If the *string* to hash can be mistaken for an option \(leading dash "\-"\), - use the option __\-\-__ before it to terminate option processing and force - interpretation as a string\. - -# PROGRAMMING INTERFACE - -For the programmer, the SHA1 hash can be viewed as a bucket into which one pours -data\. When you have finished, you extract a value that is derived from the data -that was poured into the bucket\. The programming interface to the SHA1 hash -operates on a token \(equivalent to the bucket\)\. You call __SHA1Init__ to -obtain a token and then call __SHA1Update__ as many times as required to add -data to the hash\. To release any resources and obtain the hash value, you then -call __SHA1Final__\. An equivalent set of functions gives you a keyed digest -\(HMAC\)\. - -If you have __critcl__ and have built the __tcllibc__ package then the -implementation of the hashing function will be performed by compiled code\. -Failing that if you have the __Trf__ package then this can be used otherwise -there is a pure\-tcl equivalent\. The programming interface remains the same in -all cases\. - - - __::sha1::SHA1Init__ - - Begins a new SHA1 hash\. Returns a token ID that must be used for the - remaining functions\. - - - __::sha1::SHA1Update__ *token* *data* - - Add data to the hash identified by token\. Calling *SHA1Update $token - "abcd"* is equivalent to calling *SHA1Update $token "ab"* followed by - *SHA1Update $token "cb"*\. See [EXAMPLES](#section4)\. - - - __::sha1::SHA1Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 20 bytes representing the 160 bit SHA1 digest value\. - - - __::sha1::HMACInit__ *key* - - This is equivalent to the __::sha1::SHA1Init__ command except that it - requires the key that will be included in the HMAC\. - - - __::sha1::HMACUpdate__ *token* *data* - - - __::sha1::HMACFinal__ *token* - - These commands are identical to the SHA1 equivalent commands\. - -# EXAMPLES - - % sha1::sha1 "Tcl does SHA1" - 285a6a91c45a9066bf39fcf24425796ef0b2a8bf - - % sha1::hmac Sekret "Tcl does SHA1" - ae6251fa51b95b18cba2be95eb031d07475ff03c - - % set tok [sha1::SHA1Init] - ::sha1::1 - % sha1::SHA1Update $tok "Tcl " - % sha1::SHA1Update $tok "does " - % sha1::SHA1Update $tok "SHA1" - % sha1::Hex [sha1::SHA1Final $tok] - 285a6a91c45a9066bf39fcf24425796ef0b2a8bf - -# REFERENCES - - 1. "Secure Hash Standard", National Institute of Standards and Technology, - U\.S\. Department Of Commerce, April 1995\. - \([http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm](http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm)\) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sha1* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), -[ripemd128](\.\./ripemd/ripemd128\.md), [ripemd160](\.\./ripemd/ripemd160\.md) - -# KEYWORDS - -[FIPS 180\-1](\.\./\.\./\.\./\.\./index\.md\#fips\_180\_1), -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security), -[sha1](\.\./\.\./\.\./\.\./index\.md\#sha1) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2005, Pat Thoyts DELETED embedded/md/tcllib/files/modules/sha1/sha256.md Index: embedded/md/tcllib/files/modules/sha1/sha256.md ================================================================== --- embedded/md/tcllib/files/modules/sha1/sha256.md +++ embedded/md/tcllib/files/modules/sha1/sha256.md @@ -1,229 +0,0 @@ - -[//000000001]: # (sha256 \- SHA\-x Message\-Digest Algorithm) -[//000000002]: # (Generated from file 'sha256\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008, Andreas Kupries ) -[//000000004]: # (sha256\(n\) 1\.0\.4 tcllib "SHA\-x Message\-Digest Algorithm") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -sha256 \- SHA256 Message\-Digest Algorithm - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [PROGRAMMING INTERFACE](#section3) - - - [EXAMPLES](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require sha256 ?1\.0\.4? - -[__::sha2::sha256__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#1) -[__::sha2::sha224__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#2) -[__::sha2::hmac__ *key* *string*](#3) -[__::sha2::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \]](#4) -[__::sha2::SHA256Init__](#5) -[__::sha2::SHA224Init__](#6) -[__::sha2::SHA256Update__ *token* *data*](#7) -[__::sha2::SHA256Final__ *token*](#8) -[__::sha2::SHA224Final__ *token*](#9) -[__::sha2::HMACInit__ *key*](#10) -[__::sha2::HMACUpdate__ *token* *data*](#11) -[__::sha2::HMACFinal__ *token*](#12) - -# DESCRIPTION - -This package provides an implementation in Tcl of the SHA256 and SHA224 -message\-digest algorithms as specified by FIPS PUB 180\-1 \(1\)\. These algorithms -take a message and generates a 256\-bit \(224\-bit\) digest from the input\. The SHA2 -algorithms are related to the SHA1 algorithm\. - -This package also includes support for creating keyed message\-digests using the -HMAC algorithm from RFC 2104 \(3\) with SHA256 as the message\-digest\. - -# COMMANDS - - - __::sha2::sha256__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] - - The command takes a message and returns the SHA256 digest of this message as - a hexadecimal string\. You may request the result as binary data by giving - *\-bin*\. - - The data to be hashed can be specified either as a string argument to the - __sha256__ command, or as a filename or a pre\-opened channel\. If the - *\-filename* argument is given then the file is opened, the data read and - hashed and the file is closed\. If the *\-channel* argument is given then - data is read from the channel until the end of file\. The channel is not - closed\. *NOTE* use of the channel or filename options results in the - internal use of __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\. To avoid - nested event loops in Tk or tclhttpd applications you should use the - incremental programming API \(see below\)\. - - Only one of *\-file*, *\-channel* or *string* should be given\. - - If the *string* to hash can be mistaken for an option \(leading dash "\-"\), - use the option __\-\-__ before it to terminate option processing and force - interpretation as a string\. - - - __::sha2::sha224__ ?__\-hex|\-bin__? \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] - - Like __::sha2::sha256__, except that the SHA224 digest is returned\. - - - __::sha2::hmac__ *key* *string* - - - __::sha2::hmac__ ?__\-hex|\-bin__? __\-key key__ \[ __\-channel channel__ | __\-file filename__ | ?__\-\-__? *string* \] - - Calculate an Hashed Message Authentication digest \(HMAC\) using the SHA256 - digest algorithm\. HMACs are described in RFC 2104 \(3\) and provide an SHA256 - digest that includes a key\. All options other than *\-key* are as for the - __::sha2::sha256__ command\. - - If the *string* to hash can be mistaken for an option \(leading dash "\-"\), - use the option __\-\-__ before it to terminate option processing and force - interpretation as a string\. - -# PROGRAMMING INTERFACE - -For the programmer, the SHA256 hash can be viewed as a bucket into which one -pours data\. When you have finished, you extract a value that is derived from the -data that was poured into the bucket\. The programming interface to the SHA256 -hash operates on a token \(equivalent to the bucket\)\. You call __SHA256Init__ -to obtain a token and then call __SHA256Update__ as many times as required -to add data to the hash\. To release any resources and obtain the hash value, you -then call __SHA256Final__\. An equivalent set of functions gives you a keyed -digest \(HMAC\)\. - -If you have __critcl__ and have built the __tcllibc__ package then the -implementation of the hashing function will be performed by compiled code\. -Failing that there is a pure\-tcl equivalent\. The programming interface remains -the same in all cases\. - - - __::sha2::SHA256Init__ - - - __::sha2::SHA224Init__ - - Begins a new SHA256/SHA224 hash\. Returns a token ID that must be used for - the remaining functions\. - - - __::sha2::SHA256Update__ *token* *data* - - Add data to the hash identified by token\. Calling *SHA256Update $token - "abcd"* is equivalent to calling *SHA256Update $token "ab"* followed by - *SHA256Update $token "cb"*\. See [EXAMPLES](#section4)\. Note that this - command is used for both SHA256 and SHA224\. Only the initialization and - finalization commands of both hashes differ\. - - - __::sha2::SHA256Final__ *token* - - - __::sha2::SHA224Final__ *token* - - Returns the hash value and releases any resources held by this token\. Once - this command completes the token will be invalid\. The result is a binary - string of 32/28 bytes representing the 256/224 bit SHA256 / SHA224 digest - value\. - - - __::sha2::HMACInit__ *key* - - This is equivalent to the __::sha2::SHA256Init__ command except that it - requires the key that will be included in the HMAC\. - - - __::sha2::HMACUpdate__ *token* *data* - - - __::sha2::HMACFinal__ *token* - - These commands are identical to the SHA256 equivalent commands\. - -# EXAMPLES - - % sha2::sha256 "Tcl does SHA256" - 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 - - % sha2::hmac Sekret "Tcl does SHA256" - 4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0 - - % set tok [sha2::SHA256Init] - ::sha2::1 - % sha2::SHA256Update $tok "Tcl " - % sha2::SHA256Update $tok "does " - % sha2::SHA256Update $tok "SHA256" - % sha2::Hex [sha2::SHA256Final $tok] - 0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789 - -# REFERENCES - - 1. "Secure Hash Standard", National Institute of Standards and Technology, - U\.S\. Department Of Commerce, April 1995\. - \([http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm](http://www\.itl\.nist\.gov/fipspubs/fip180\-1\.htm)\) - - 1. Rivest, R\., "The MD4 Message Digest Algorithm", RFC 1320, MIT, April 1992\. - \([http://www\.rfc\-editor\.org/rfc/rfc1320\.txt](http://www\.rfc\-editor\.org/rfc/rfc1320\.txt)\) - - 1. Krawczyk, H\., Bellare, M\. and Canetti, R\. "HMAC: Keyed\-Hashing for Message - Authentication", RFC 2104, February 1997\. - \([http://www\.rfc\-editor\.org/rfc/rfc2104\.txt](http://www\.rfc\-editor\.org/rfc/rfc2104\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *sha1* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[md4](\.\./md4/md4\.md), [md5](\.\./md5/md5\.md), -[ripemd128](\.\./ripemd/ripemd128\.md), -[ripemd160](\.\./ripemd/ripemd160\.md), [sha1](sha1\.md) - -# KEYWORDS - -[FIPS 180\-1](\.\./\.\./\.\./\.\./index\.md\#fips\_180\_1), -[hashing](\.\./\.\./\.\./\.\./index\.md\#hashing), -[message\-digest](\.\./\.\./\.\./\.\./index\.md\#message\_digest), [rfc -2104](\.\./\.\./\.\./\.\./index\.md\#rfc\_2104), -[security](\.\./\.\./\.\./\.\./index\.md\#security), -[sha256](\.\./\.\./\.\./\.\./index\.md\#sha256) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2008, Andreas Kupries DELETED embedded/md/tcllib/files/modules/simulation/annealing.md Index: embedded/md/tcllib/files/modules/simulation/annealing.md ================================================================== --- embedded/md/tcllib/files/modules/simulation/annealing.md +++ embedded/md/tcllib/files/modules/simulation/annealing.md @@ -1,243 +0,0 @@ - -[//000000001]: # (simulation::annealing \- Tcl Simulation Tools) -[//000000002]: # (Generated from file 'annealing\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Arjen Markus ) -[//000000004]: # (simulation::annealing\(n\) 0\.2 tcllib "Tcl Simulation Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -simulation::annealing \- Simulated annealing - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [TIPS](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require simulation::annealing 0\.2 - -[__::simulation::annealing::getOption__ *keyword*](#1) -[__::simulation::annealing::hasOption__ *keyword*](#2) -[__::simulation::annealing::setOption__ *keyword* *value*](#3) -[__::simulation::annealing::findMinimum__ *args*](#4) -[__::simulation::annealing::findCombinatorialMinimum__ *args*](#5) - -# DESCRIPTION - -The technique of *simulated annealing* provides methods to estimate the global -optimum of a function\. It is described in some detail on the Wiki -[http://wiki\.tcl\.tk/\.\.\.](http://wiki\.tcl\.tk/\.\.\.)\. The idea is simple: - - - randomly select points within a given search space - - - evaluate the function to be optimised for each of these points and select - the point that has the lowest \(or highest\) function value or \- sometimes \- - accept a point that has a less optimal value\. The chance by which such a - non\-optimal point is accepted diminishes over time\. - - - Accepting less optimal points means the method does not necessarily get - stuck in a local optimum and theoretically it is capable of finding the - global optimum within the search space\. - -The method resembles the cooling of material, hence the name\. - -The package *simulation::annealing* offers the command *findMinimum*: - - puts [::simulation::annealing::findMinimum -trials 300 -parameters {x -5.0 5.0 y -5.0 5.0} -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}] - -prints the estimated minimum value of the function f\(x,y\) = -*x\*\*2\+y\*\*2\+sin\(10\*x\)\+4\*cos\(20\*y\)* and the values of x and y where the minimum -was attained: - - result -4.9112922923 x -0.181647676593 y 0.155743646974 - -# PROCEDURES - -The package defines the following auxiliary procedures: - - - __::simulation::annealing::getOption__ *keyword* - - Get the value of an option given as part of the *findMinimum* command\. - - * string *keyword* - - Given keyword \(without leading minus\) - - - __::simulation::annealing::hasOption__ *keyword* - - Returns 1 if the option is available, 0 if not\. - - * string *keyword* - - Given keyword \(without leading minus\) - - - __::simulation::annealing::setOption__ *keyword* *value* - - Set the value of the given option\. - - * string *keyword* - - Given keyword \(without leading minus\) - - * string *value* - - \(New\) value for the option - -The main procedures are *findMinimum* and *findCombinatorialMinimum*: - - - __::simulation::annealing::findMinimum__ *args* - - Find the minimum of a function using simulated annealing\. The function and - the method's parameters is given via a list of keyword\-value pairs\. - - * int *n* - - List of keyword\-value pairs, all of which are available during the - execution via the *getOption* command\. - - - __::simulation::annealing::findCombinatorialMinimum__ *args* - - Find the minimum of a function of discrete variables using simulated - annealing\. The function and the method's parameters is given via a list of - keyword\-value pairs\. - - * int *n* - - List of keyword\-value pairs, all of which are available during the - execution via the *getOption* command\. - -The *findMinimum* command predefines the following options: - - - *\-parameters list*: triples defining parameters and ranges - - - *\-function expr*: expression defining the function - - - *\-code body*: body of code to define the function \(takes precedence over - *\-function*\)\. The code should set the variable "result" - - - *\-init code*: code to be run at start up *\-final code*: code to be run - at the end *\-trials n*: number of trials before reducing the temperature - *\-reduce factor*: reduce the temperature by this factor \(between 0 and 1\) - *\-initial\-temp t*: initial temperature *\-scale s*: scale of the function - \(order of magnitude of the values\) *\-estimate\-scale y/n*: estimate the - scale \(only if *\-scale* is not present\) *\-verbose y/n*: print detailed - information on progress to the report file \(1\) or not \(0\) *\-reportfile - file*: opened file to print to \(defaults to stdout\) - -Any other options can be used via the getOption procedure in the body\. The -*findCombinatorialMinimum* command predefines the following options: - - - *\-number\-params n*: number of binary parameters \(the solution space - consists of lists of 1s and 0s\)\. This is a required option\. - - - *\-initial\-values*: list of 1s and 0s constituting the start of the search\. - -The other predefined options are identical to those of *findMinimum*\. - -# TIPS - -The procedure *findMinimum* works by constructing a temporary procedure that -does the actual work\. It loops until the point representing the estimated -optimum does not change anymore within the given number of trials\. As the -temperature gets lower and lower the chance of accepting a point with a higher -value becomes lower too, so the procedure will in practice terminate\. - -It is possible to optimise over a non\-rectangular region, but some care must be -taken: - - - If the point is outside the region of interest, you can specify a very high - value\. - - - This does mean that the automatic determination of a scale factor is out of - the question \- the high function values that force the point inside the - region would distort the estimation\. - -Here is an example of finding an optimum inside a circle: - - puts [::simulation::annealing::findMinimum -trials 3000 -reduce 0.98 -parameters {x -5.0 5.0 y -5.0 5.0} -code { - if { hypot($x-5.0,$y-5.0) < 4.0 } { - set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}] - } else { - set result 1.0e100 - } - }] - -The method is theoretically capable of determining the global optimum, but often -you need to use a large number of trials and a slow reduction of temperature to -get reliable and repeatable estimates\. - -You can use the *\-final* option to use a deterministic optimization method, -once you are sure you are near the required optimum\. - -The *findCombinatorialMinimum* procedure is suited for situations where the -parameters have the values 0 or 1 \(and there can be many of them\)\. Here is an -example: - - - We have a function that attains an absolute minimum if the first ten numbers - are 1 and the rest is 0: - - proc cost {params} { - set cost 0 - foreach p [lrange $params 0 9] { - if { $p == 0 } { - incr cost - } - } - foreach p [lrange $params 10 end] { - if { $p == 1 } { - incr cost - } - } - return $cost - } - - - We want to find the solution that gives this minimum for various lengths of - the solution vector *params*: - - foreach n {100 1000 10000} { - break - puts "Problem size: $n" - puts [::simulation::annealing::findCombinatorialMinimum -trials 300 -verbose 0 -number-params $n -code {set result [cost $params]}] - } - - - As the vector grows, the computation time increases, but the procedure will - stop if some kind of equilibrium is reached\. To achieve a useful solution - you may want to try different values of the trials parameter for instance\. - Also ensure that the function to be minimized depends on all or most - parameters \- see the source code for a counter example and run that\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), -[optimization](\.\./\.\./\.\./\.\./index\.md\#optimization), [simulated -annealing](\.\./\.\./\.\./\.\./index\.md\#simulated\_annealing) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2008 Arjen Markus DELETED embedded/md/tcllib/files/modules/simulation/montecarlo.md Index: embedded/md/tcllib/files/modules/simulation/montecarlo.md ================================================================== --- embedded/md/tcllib/files/modules/simulation/montecarlo.md +++ embedded/md/tcllib/files/modules/simulation/montecarlo.md @@ -1,239 +0,0 @@ - -[//000000001]: # (simulation::montecarlo \- Tcl Simulation Tools) -[//000000002]: # (Generated from file 'montecarlo\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Arjen Markus ) -[//000000004]: # (simulation::montecarlo\(n\) 0\.1 tcllib "Tcl Simulation Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -simulation::montecarlo \- Monte Carlo simulations - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [TIPS](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require simulation::montecarlo 0\.1 -package require simulation::random -package require math::statistics - -[__::simulation::montecarlo::getOption__ *keyword*](#1) -[__::simulation::montecarlo::hasOption__ *keyword*](#2) -[__::simulation::montecarlo::setOption__ *keyword* *value*](#3) -[__::simulation::montecarlo::setTrialResult__ *values*](#4) -[__::simulation::montecarlo::setExpResult__ *values*](#5) -[__::simulation::montecarlo::getTrialResults__](#6) -[__::simulation::montecarlo::getExpResult__](#7) -[__::simulation::montecarlo::transposeData__ *values*](#8) -[__::simulation::montecarlo::integral2D__ *\.\.\.*](#9) -[__::simulation::montecarlo::singleExperiment__ *args*](#10) - -# DESCRIPTION - -The technique of *Monte Carlo simulations* is basically simple: - - - generate random values for one or more parameters\. - - - evaluate the model of some system you are interested in and record the - interesting results for each realisation of these parameters\. - - - after a suitable number of such trials, deduce an overall characteristic of - the model\. - -You can think of a model of a network of computers, an ecosystem of some kind or -in fact anything that can be quantitatively described and has some stochastic -element in it\. - -The package *simulation::montecarlo* offers a basic framework for such a -modelling technique: - - # - # MC experiments: - # Determine the mean and median of a set of points and compare them - # - ::simulation::montecarlo::singleExperiment -init { - package require math::statistics - - set prng [::simulation::random::prng_Normal 0.0 1.0] - } -loop { - set numbers {} - for { set i 0 } { $i < [getOption samples] } { incr i } { - lappend numbers [$prng] - } - set mean [::math::statistics::mean $numbers] - set median [::math::statistics::median $numbers] ;# ? Exists? - setTrialResult [list $mean $median] - } -final { - set result [getTrialResults] - set means {} - set medians {} - foreach r $result { - foreach {m M} $r break - lappend means $m - lappend medians $M - } - puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]" - - } -trials 100 -samples 10 -verbose 1 -columns {Mean Median} - -This example attemps to find out how well the median value and the mean value of -a random set of numbers correlate\. Sometimes a median value is a more robust -characteristic than a mean value \- especially if you have a statistical -distribution with "fat" tails\. - -# PROCEDURES - -The package defines the following auxiliary procedures: - - - __::simulation::montecarlo::getOption__ *keyword* - - Get the value of an option given as part of the *singeExperiment* command\. - - * string *keyword* - - Given keyword \(without leading minus\) - - - __::simulation::montecarlo::hasOption__ *keyword* - - Returns 1 if the option is available, 0 if not\. - - * string *keyword* - - Given keyword \(without leading minus\) - - - __::simulation::montecarlo::setOption__ *keyword* *value* - - Set the value of the given option\. - - * string *keyword* - - Given keyword \(without leading minus\) - - * string *value* - - \(New\) value for the option - - - __::simulation::montecarlo::setTrialResult__ *values* - - Store the results of the trial for later analysis - - * list *values* - - List of values to be stored - - - __::simulation::montecarlo::setExpResult__ *values* - - Set the results of the entire experiment \(typically used in the final - phase\)\. - - * list *values* - - List of values to be stored - - - __::simulation::montecarlo::getTrialResults__ - - Get the results of all individual trials for analysis \(typically used in the - final phase or after completion of the command\)\. - - - __::simulation::montecarlo::getExpResult__ - - Get the results of the entire experiment \(typically used in the final phase - or even after completion of the *singleExperiment* command\)\. - - - __::simulation::montecarlo::transposeData__ *values* - - Interchange columns and rows of a list of lists and return the result\. - - * list *values* - - List of lists of values - -There are two main procedures: *integral2D* and *singleExperiment*\. - - - __::simulation::montecarlo::integral2D__ *\.\.\.* - - Integrate a function over a two\-dimensional region using a Monte Carlo - approach\. - - Arguments PM - - - __::simulation::montecarlo::singleExperiment__ *args* - - Iterate code over a number of trials and store the results\. The iteration is - gouverned by parameters given via a list of keyword\-value pairs\. - - * int *n* - - List of keyword\-value pairs, all of which are available during the - execution via the *getOption* command\. - -The *singleExperiment* command predefines the following options: - - - *\-init code*: code to be run at start up - - - *\-loop body*: body of code that defines the computation to be run time and - again\. The code should use *setTrialResult* to store the results of each - trial \(typically a list of numbers, but the interpretation is up to the - implementation\)\. Note: Required keyword\. - - - *\-final code*: code to be run at the end - - - *\-trials n*: number of trials in the experiment \(required\) - - - *\-reportfile file*: opened file to send the output to \(default: stdout\) - - - *\-verbose*: write the intermediate results \(1\) or not \(0\) \(default: 0\) - - - *\-analysis proc*: either "none" \(no automatic analysis\), standard \(basic - statistics of the trial results and a correlation matrix\) or the name of a - procedure that will take care of the analysis\. - - - *\-columns list*: list of column names, useful for verbose output and the - analysis - -Any other options can be used via the getOption procedure in the body\. - -# TIPS - -The procedure *singleExperiment* works by constructing a temporary procedure -that does the actual work\. It loops for the given number of trials\. - -As it constructs a temporary procedure, local variables defined at the start -continue to exist in the loop\. - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), [montecarlo -simulation](\.\./\.\./\.\./\.\./index\.md\#montecarlo\_simulation), [stochastic -modelling](\.\./\.\./\.\./\.\./index\.md\#stochastic\_modelling) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2008 Arjen Markus DELETED embedded/md/tcllib/files/modules/simulation/simulation_random.md Index: embedded/md/tcllib/files/modules/simulation/simulation_random.md ================================================================== --- embedded/md/tcllib/files/modules/simulation/simulation_random.md +++ embedded/md/tcllib/files/modules/simulation/simulation_random.md @@ -1,288 +0,0 @@ - -[//000000001]: # (simulation::random \- Tcl Simulation Tools) -[//000000002]: # (Generated from file 'simulation\_random\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Arjen Markus ) -[//000000004]: # (simulation::random\(n\) 0\.4 tcllib "Tcl Simulation Tools") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -simulation::random \- Pseudo\-random number generators - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [PROCEDURES](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl ?8\.4? -package require simulation::random 0\.4 - -[__::simulation::random::prng\_Bernoulli__ *p*](#1) -[__::simulation::random::prng\_Discrete__ *n*](#2) -[__::simulation::random::prng\_Poisson__ *lambda*](#3) -[__::simulation::random::prng\_Uniform__ *min* *max*](#4) -[__::simulation::random::prng\_Triangular__ *min* *max*](#5) -[__::simulation::random::prng\_SymmTriangular__ *min* *max*](#6) -[__::simulation::random::prng\_Exponential__ *min* *mean*](#7) -[__::simulation::random::prng\_Normal__ *mean* *stdev*](#8) -[__::simulation::random::prng\_Pareto__ *min* *steep*](#9) -[__::simulation::random::prng\_Gumbel__ *min* *f*](#10) -[__::simulation::random::prng\_chiSquared__ *df*](#11) -[__::simulation::random::prng\_Disk__ *rad*](#12) -[__::simulation::random::prng\_Sphere__ *rad*](#13) -[__::simulation::random::prng\_Ball__ *rad*](#14) -[__::simulation::random::prng\_Rectangle__ *length* *width*](#15) -[__::simulation::random::prng\_Block__ *length* *width* *depth*](#16) - -# DESCRIPTION - -This package consists of commands to generate pseudo\-random number generators\. -These new commands deliver - - - numbers that are distributed normally, uniformly, according to a Pareto or - Gumbel distribution and so on - - - coordinates of points uniformly spread inside a sphere or a rectangle - -For example: - - set p [::simulation::random::prng_Normal -1.0 10.0] - -produces a new command \(whose name is stored in the variable "p"\) that generates -normally distributed numbers with a mean of \-1\.0 and a standard deviation of -10\.0\. - -# PROCEDURES - -The package defines the following public procedures for *discrete* -distributions: - - - __::simulation::random::prng\_Bernoulli__ *p* - - Create a command \(PRNG\) that generates numbers with a Bernoulli - distribution: the value is either 1 or 0, with a chance p to be 1 - - * float *p* - - Chance the outcome is 1 - - - __::simulation::random::prng\_Discrete__ *n* - - Create a command \(PRNG\) that generates numbers 0 to n\-1 with equal - probability\. - - * int *n* - - Number of different values \(ranging from 0 to n\-1\) - - - __::simulation::random::prng\_Poisson__ *lambda* - - Create a command \(PRNG\) that generates numbers according to the Poisson - distribution\. - - * float *lambda* - - Mean number per time interval - -The package defines the following public procedures for *continuous* -distributions: - - - __::simulation::random::prng\_Uniform__ *min* *max* - - Create a command \(PRNG\) that generates uniformly distributed numbers between - "min" and "max"\. - - * float *min* - - Minimum number that will be generated - - * float *max* - - Maximum number that will be generated - - - __::simulation::random::prng\_Triangular__ *min* *max* - - Create a command \(PRNG\) that generates triangularly distributed numbers - between "min" and "max"\. If the argument min is lower than the argument max, - then smaller values have higher probability and vice versa\. In the first - case the probability density function is of the form *f\(x\) = 2\(1\-x\)* and - the other case it is of the form *f\(x\) = 2x*\. - - * float *min* - - Minimum number that will be generated - - * float *max* - - Maximum number that will be generated - - - __::simulation::random::prng\_SymmTriangular__ *min* *max* - - Create a command \(PRNG\) that generates numbers distributed according to a - symmetric triangle around the mean of "min" and "max"\. - - * float *min* - - Minimum number that will be generated - - * float *max* - - Maximum number that will be generated - - - __::simulation::random::prng\_Exponential__ *min* *mean* - - Create a command \(PRNG\) that generates exponentially distributed numbers - with a given minimum value and a given mean value\. - - * float *min* - - Minimum number that will be generated - - * float *mean* - - Mean value for the numbers - - - __::simulation::random::prng\_Normal__ *mean* *stdev* - - Create a command \(PRNG\) that generates normally distributed numbers with a - given mean value and a given standard deviation\. - - * float *mean* - - Mean value for the numbers - - * float *stdev* - - Standard deviation - - - __::simulation::random::prng\_Pareto__ *min* *steep* - - Create a command \(PRNG\) that generates numbers distributed according to - Pareto with a given minimum value and a given distribution steepness\. - - * float *min* - - Minimum number that will be generated - - * float *steep* - - Steepness of the distribution - - - __::simulation::random::prng\_Gumbel__ *min* *f* - - Create a command \(PRNG\) that generates numbers distributed according to - Gumbel with a given minimum value and a given scale factor\. The probability - density function is: - - P(v) = exp( -exp(f*(v-min))) - - * float *min* - - Minimum number that will be generated - - * float *f* - - Scale factor for the values - - - __::simulation::random::prng\_chiSquared__ *df* - - Create a command \(PRNG\) that generates numbers distributed according to the - chi\-squared distribution with df degrees of freedom\. The mean is 0 and the - standard deviation is 1\. - - * float *df* - - Degrees of freedom - -The package defines the following public procedures for random point sets: - - - __::simulation::random::prng\_Disk__ *rad* - - Create a command \(PRNG\) that generates \(x,y\)\-coordinates for points - uniformly spread over a disk of given radius\. - - * float *rad* - - Radius of the disk - - - __::simulation::random::prng\_Sphere__ *rad* - - Create a command \(PRNG\) that generates \(x,y,z\)\-coordinates for points - uniformly spread over the surface of a sphere of given radius\. - - * float *rad* - - Radius of the disk - - - __::simulation::random::prng\_Ball__ *rad* - - Create a command \(PRNG\) that generates \(x,y,z\)\-coordinates for points - uniformly spread within a ball of given radius\. - - * float *rad* - - Radius of the ball - - - __::simulation::random::prng\_Rectangle__ *length* *width* - - Create a command \(PRNG\) that generates \(x,y\)\-coordinates for points - uniformly spread over a rectangle\. - - * float *length* - - Length of the rectangle \(x\-direction\) - - * float *width* - - Width of the rectangle \(y\-direction\) - - - __::simulation::random::prng\_Block__ *length* *width* *depth* - - Create a command \(PRNG\) that generates \(x,y,z\)\-coordinates for points - uniformly spread over a block - - * float *length* - - Length of the block \(x\-direction\) - - * float *width* - - Width of the block \(y\-direction\) - - * float *depth* - - Depth of the block \(z\-direction\) - -# KEYWORDS - -[math](\.\./\.\./\.\./\.\./index\.md\#math), [random -numbers](\.\./\.\./\.\./\.\./index\.md\#random\_numbers), -[simulation](\.\./\.\./\.\./\.\./index\.md\#simulation), [statistical -distribution](\.\./\.\./\.\./\.\./index\.md\#statistical\_distribution) - -# CATEGORY - -Mathematics - -# COPYRIGHT - -Copyright © 2004 Arjen Markus DELETED embedded/md/tcllib/files/modules/smtpd/smtpd.md Index: embedded/md/tcllib/files/modules/smtpd/smtpd.md ================================================================== --- embedded/md/tcllib/files/modules/smtpd/smtpd.md +++ embedded/md/tcllib/files/modules/smtpd/smtpd.md @@ -1,324 +0,0 @@ - -[//000000001]: # (smtpd \- Tcl SMTP Server Package) -[//000000002]: # (Generated from file 'smtpd\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © Pat Thoyts ) -[//000000004]: # (smtpd\(n\) 1\.5 tcllib "Tcl SMTP Server Package") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -smtpd \- Tcl SMTP server implementation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [SECURITY](#section2) - - - [TLS Security Considerations](#section3) - - - [COMMANDS](#section4) - - - [CALLBACKS](#section5) - - - [VARIABLES](#section6) - - - [AUTHOR](#section7) - - - [LICENSE](#section8) - - - [Bugs, Ideas, Feedback](#section9) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require smtpd ?1\.5? - -[__::smtpd::start__ ?*myaddr*? ?*port*?](#1) -[__::smtpd::stop__](#2) -[__::smptd::configure__ ?*option* *value*? ?*option* *value* *\.\.\.*?](#3) -[__::smtpd::cget__ ?*option*?](#4) - -# DESCRIPTION - -The __smtpd__ package provides a simple Tcl\-only server library for the -Simple Mail Transfer Protocol as described in RFC 821 -\([http://www\.rfc\-editor\.org/rfc/rfc821\.txt](http://www\.rfc\-editor\.org/rfc/rfc821\.txt)\) -and RFC 2821 -\([http://www\.rfc\-editor\.org/rfc/rfc2821\.txt](http://www\.rfc\-editor\.org/rfc/rfc2821\.txt)\)\. -By default the server will bind to the default network address and the standard -SMTP port \(25\)\. - -This package was designed to permit testing of Mail User Agent code from a -developers workstation\. *It does not attempt to deliver mail to your mailbox\.* -Instead users of this package are expected to write a procedure that will be -called when mail arrives\. Once this procedure returns, the server has nothing -further to do with the mail\. - -# SECURITY - -On Unix platforms binding to the SMTP port requires root privileges\. I would not -recommend running any script\-based server as root unless there is some method -for dropping root privileges immediately after the socket is bound\. Under -Windows platforms, it is not necessary to have root or administrator privileges -to bind low numbered sockets\. However, security on these platforms is weak -anyway\. - -In short, this code should probably not be used as a permanently running Mail -Transfer Agent on an Internet connected server, even though we are careful not -to evaluate remote user input\. There are many other well tested and security -audited programs that can be used as mail servers for internet connected hosts\. - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# COMMANDS - - - __::smtpd::start__ ?*myaddr*? ?*port*? - - Start the service listening on *port* or the default port 25\. If - *myaddr* is given as a domain\-style name or numerical dotted\-quad IP - address then the server socket will be bound to that network interface\. By - default the server is bound to all network interfaces\. For example: - - set sock [::smtpd::start [info hostname] 0] - - will bind to the hosts internet interface on the first available port\. - - At present the package only supports a single instance of a SMTP server\. - This could be changed if required at the cost of making the package a little - more complicated to read\. If there is a good reason for running multiple - SMTP services then it will only be necessary to fix the __options__ - array and the __::smtpd::stopped__ variable usage\. - - As the server code uses __fileevent__\(n\) handlers to process the input - on sockets you will need to run the event loop\. This means either you should - be running from within __wish__\(1\) or you should - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\(n\) on the - __::smtpd::stopped__ variable which is set when the server is stopped\. - - - __::smtpd::stop__ - - Halt the server and release the listening socket\. If the server has not been - started then this command does nothing\. The __::smtpd::stopped__ - variable is set for use with - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\(n\)\. - - It should be noted that stopping the server does not disconnect any - currently active sessions as these are operating over an independent - channel\. Only explicitly tracking and closing these sessions, or exiting the - server process will close down all the running sessions\. This is similar to - the usual unix daemon practice where the server performs a __fork__\(2\) - and the client session continues on the child process\. - - - __::smptd::configure__ ?*option* *value*? ?*option* *value* *\.\.\.*? - - Set configuration options for the SMTP server\. Most values are the name of a - callback procedure to be called at various points in the SMTP protocol\. See - the [CALLBACKS](#section5) section for details of the procedures\. - - * __\-banner__ *text* - - Text of a custom banner message\. The default banner is "tcllib smtpd - 1\.5"\. Note that changing the banner does not affect the bracketing text - in the full greeting, printing status 220, server\-address, and - timestamp\. - - * __\-validate\_host__ *proc* - - Callback to authenticate new connections based on the ip\-address of the - client\. - - * __\-validate\_sender__ *proc* - - Callback to authenticate new connections based on the senders email - address\. - - * __\-validate\_recipient__ *proc* - - Callback to validate and authorize a recipient email address - - * __\-deliverMIME__ *proc* - - Callback used to deliver mail as a mime token created by the tcllib - __[mime](\.\./mime/mime\.md)__ package\. - - * __\-deliver__ *proc* - - Callback used to deliver email\. This option has no effect if the - __\-deliverMIME__ option has been set\. - - - __::smtpd::cget__ ?*option*? - - If no *option* is specified the command will return a list of all options - and their current values\. If an option is specified it will return the value - of that option\. - -# CALLBACKS - - - __validate\_host__ callback - - This procedure is called with the clients ip address as soon as a connection - request has been accepted and before any protocol commands are processed\. If - you wish to deny access to a specific host then an error should be returned - by this callback\. For example: - - proc validate_host {ipnum} { - if {[string match "192.168.1.*" $ipnum]} { - error "go away!" - } - } - - If access is denied the client will receive a standard message that includes - the text of your error, such as: - - 550 Access denied: I hate you. - - As per the SMTP protocol, the connection is not closed but we wait for the - client to send a QUIT command\. Any other commands cause a __503 Bad - Sequence__ error\. - - - __validate\_sender__ callback - - The validate\_sender callback is called with the senders mail address during - processing of a MAIL command to allow you to accept or reject mail based - upon the declared sender\. To reject mail you should throw an error\. For - example, to reject mail from user "denied": - - proc validate_sender {address} { - eval array set addr [mime::parseaddress $address] - if {[string match "denied" $addr(local)]} { - error "mailbox $addr(local) denied" - } - return - } - - The content of any error message will not be passed back to the client\. - - - __validate\_recipient__ callback - - The validate\_recipient callback is similar to the validate\_sender callback - and permits you to verify a local mailbox and accept mail for a local user - address during RCPT command handling\. To reject mail, throw an error as - above\. The error message is ignored\. - - - __deliverMIME__ callback - - The deliverMIME callback is called once a mail message has been successfully - passed to the server\. A mime token is constructed from the sender, - recipients and data and the users procedure it called with this single - argument\. When the call returns, the mime token is cleaned up so if the user - wishes to preserve the data she must make a copy\. - - proc deliverMIME {token} { - set sender [lindex [mime::getheader $token From] 0] - set recipients [lindex [mime::getheader $token To] 0] - set mail "From $sender [clock format [clock seconds]]" - append mail "\n" [mime::buildmessage $token] - puts $mail - } - - - __deliver__ callback - - The deliver callback is called once a mail message has been successfully - passed to the server and there is no \-deliverMIME option set\. The procedure - is called with the sender, a list of recipients and the text of the mail as - a list of lines\. For example: - - proc deliver {sender recipients data} { - set mail "From $sender [clock format [clock seconds]]" - append mail "\n" [join $data "\n"] - puts "$mail" - } - - Note that the DATA command will return an error if no sender or recipient - has yet been defined\. - -# VARIABLES - - - __::smtpd::stopped__ - - This variable is set to __true__ during the __::smtpd::stop__ - command to permit the use of the - __[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait)__\(n\) command\. - -# AUTHOR - -Written by Pat Thoyts -[mailto:patthoyts@users\.sourceforge\.net](mailto:patthoyts@users\.sourceforge\.net)\. - -# LICENSE - -This software is distributed in the hope that it will be useful, but WITHOUT ANY -WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A -PARTICULAR PURPOSE\. See the file "license\.terms" for more details\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *smtpd* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[rfc 2821](\.\./\.\./\.\./\.\./index\.md\#rfc\_2821), [rfc -821](\.\./\.\./\.\./\.\./index\.md\#rfc\_821), -[services](\.\./\.\./\.\./\.\./index\.md\#services), -[smtp](\.\./\.\./\.\./\.\./index\.md\#smtp), [smtpd](\.\./\.\./\.\./\.\./index\.md\#smtpd), -[socket](\.\./\.\./\.\./\.\./index\.md\#socket), -[vwait](\.\./\.\./\.\./\.\./index\.md\#vwait) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © Pat Thoyts DELETED embedded/md/tcllib/files/modules/snit/snit.md Index: embedded/md/tcllib/files/modules/snit/snit.md ================================================================== --- embedded/md/tcllib/files/modules/snit/snit.md +++ embedded/md/tcllib/files/modules/snit/snit.md @@ -1,2416 +0,0 @@ - -[//000000001]: # (snit \- Snit's Not Incr Tcl, OO system) -[//000000002]: # (Generated from file 'snit\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2009, by William H\. Duquette) -[//000000004]: # (snit\(n\) 2\.3\.2 tcllib "Snit's Not Incr Tcl, OO system") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -snit \- Snit's Not Incr Tcl - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [SNIT VERSIONS](#section2) - - - [REFERENCE](#section3) - - - [Type and Widget Definitions](#subsection1) - - - [The Type Command](#subsection2) - - - [Standard Type Methods](#subsection3) - - - [The Instance Command](#subsection4) - - - [Standard Instance Methods](#subsection5) - - - [Commands for use in Object Code](#subsection6) - - - [Components and Delegation](#subsection7) - - - [Type Components and Delegation](#subsection8) - - - [The Tk Option Database](#subsection9) - - - [Macros and Meta\-programming](#subsection10) - - - [Validation Types](#subsection11) - - - [Defining Validation Types](#subsection12) - - - [CAVEATS](#section4) - - - [KNOWN BUGS](#section5) - - - [HISTORY](#section6) - - - [CREDITS](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit ?2\.3\.2? - -[__snit::type__ *name* *definition*](#1) -[__typevariable__ *name* ?__\-array__? ?*value*?](#2) -[__typemethod__ *name* *arglist* *body*](#3) -[__typeconstructor__ *body*](#4) -[__variable__ *name* ?__\-array__? ?*value*?](#5) -[__[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *name* *arglist* *body*](#6) -[__option__ *namespec* ?*defaultValue*?](#7) -[__option__ *namespec* ?*options\.\.\.*?](#8) -[__constructor__ *arglist* *body*](#9) -[__destructor__ *body*](#10) -[__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *args* *body*](#11) -[__delegate__ __method__ *name* __to__ *comp* ?__as__ *target*?](#12) -[__delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern*](#13) -[__delegate__ __method__ __\*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#14) -[__delegate__ __option__ *namespec* __to__ *comp*](#15) -[__delegate__ __option__ *namespec* __to__ *comp* __as__ *target*](#16) -[__delegate__ __option__ __\*__ __to__ *comp*](#17) -[__delegate__ __option__ __\*__ __to__ *comp* __except__ *exceptions*](#18) -[__component__ *comp* ?__\-public__ *method*? ?__\-inherit__ *flag*?](#19) -[__delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*?](#20) -[__delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern*](#21) -[__delegate__ __typemethod__ __\*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*?](#22) -[__typecomponent__ *comp* ?__\-public__ *typemethod*? ?__\-inherit__ *flag*?](#23) -[__pragma__ ?*options\.\.\.*?](#24) -[__expose__ *comp*](#25) -[__expose__ *comp* __as__ *method*](#26) -[__onconfigure__ *name* *arglist* *body*](#27) -[__oncget__ *name* *body*](#28) -[__snit::widget__ *name* *definition*](#29) -[__widgetclass__ *name*](#30) -[__hulltype__ *type*](#31) -[__snit::widgetadaptor__ *name* *definition*](#32) -[__snit::typemethod__ *type* *name* *arglist* *body*](#33) -[__snit::method__ *type* *name* *arglist* *body*](#34) -[__snit::macro__ *name* *arglist* *body*](#35) -[__snit::compile__ *which* *type* *body*](#36) -[__$type__ *typemethod* *args*\.\.\.](#37) -[__$type__ __create__ *name* ?*option* *value* \.\.\.?](#38) -[__$type__ __info typevars__ ?*pattern*?](#39) -[__$type__ __info typemethods__ ?*pattern*?](#40) -[__$type__ __info args__ *method*](#41) -[__$type__ __info body__ *method*](#42) -[__$type__ __info default__ *method* *aname* *varname*](#43) -[__$type__ __info instances__ ?*pattern*?](#44) -[__$type__ __destroy__](#45) -[__$object__ *method* *args\.\.\.*](#46) -[__$object__ __configure__ ?*option*? ?*value*? \.\.\.](#47) -[__$object__ __configurelist__ *optionlist*](#48) -[__$object__ __cget__ *option*](#49) -[__$object__ __destroy__](#50) -[__$object__ __info type__](#51) -[__$object__ __info vars__ ?*pattern*?](#52) -[__$object__ __info typevars__ ?*pattern*?](#53) -[__$object__ __info typemethods__ ?*pattern*?](#54) -[__$object__ __info options__ ?*pattern*?](#55) -[__$object__ __info methods__ ?*pattern*?](#56) -[__$object__ __info args__ *method*](#57) -[__$object__ __info body__ *method*](#58) -[__$object__ __info default__ *method* *aname* *varname*](#59) -[__mymethod__ *name* ?*args\.\.\.*?](#60) -[__mytypemethod__ *name* ?*args\.\.\.*?](#61) -[__myproc__ *name* ?*args\.\.\.*?](#62) -[__myvar__ *name*](#63) -[__mytypevar__ *name*](#64) -[__from__ *argvName* *option* ?*defvalue*?](#65) -[__install__ *compName* __using__ *objType* *objName* *args\.\.\.*](#66) -[__installhull__ __using__ *widgetType* *args\.\.\.*](#67) -[__installhull__ *name*](#68) -[__variable__ *name*](#69) -[__typevariable__ *name*](#70) -[__varname__ *name*](#71) -[__typevarname__ *name*](#72) -[__codename__ *name*](#73) -[__snit::boolean__ __validate__ ?*value*?](#74) -[__snit::boolean__ *name*](#75) -[__snit::double__ __validate__ ?*value*?](#76) -[__snit::double__ *name* ?*option* *value*\.\.\.?](#77) -[__snit::enum__ __validate__ ?*value*?](#78) -[__snit::enum__ *name* ?*option* *value*\.\.\.?](#79) -[__snit::fpixels__ __validate__ ?*value*?](#80) -[__snit::fpixels__ *name* ?*option* *value*\.\.\.?](#81) -[__snit::integer__ __validate__ ?*value*?](#82) -[__snit::integer__ *name* ?*option* *value*\.\.\.?](#83) -[__snit::listtype__ __validate__ ?*value*?](#84) -[__snit::listtype__ *name* ?*option* *value*\.\.\.?](#85) -[__snit::pixels__ __validate__ ?*value*?](#86) -[__snit::pixels__ *name* ?*option* *value*\.\.\.?](#87) -[__snit::stringtype__ __validate__ ?*value*?](#88) -[__snit::stringtype__ *name* ?*option* *value*\.\.\.?](#89) -[__snit::window__ __validate__ ?*value*?](#90) -[__snit::window__ *name*](#91) - -# DESCRIPTION - -Snit is a pure Tcl object and megawidget system\. It's unique among Tcl object -systems in that it's based not on inheritance but on delegation\. Object systems -based on inheritance only allow you to inherit from classes defined using the -same system, which is limiting\. In Tcl, an object is anything that acts like an -object; it shouldn't matter how the object was implemented\. Snit is intended to -help you build applications out of the materials at hand; thus, Snit is designed -to be able to incorporate and build on any object, whether it's a hand\-coded -object, a __[Tk](\.\./\.\./\.\./\.\./index\.md\#tk)__ widget, an __[Incr -Tcl](\.\./\.\./\.\./\.\./index\.md\#incr\_tcl)__ object, a -__[BWidget](\.\./\.\./\.\./\.\./index\.md\#bwidget)__ or almost anything else\. - -This man page is intended to be a reference only; see the accompanying -__[snitfaq](snitfaq\.md)__ for a gentler, more tutorial introduction to -Snit concepts\. - -# SNIT VERSIONS - -This man page covers both Snit 2\.2 and Snit 1\.3\. The primary difference between -the two versions is simply that Snit 2\.2 contains speed optimizations based on -new features of Tcl 8\.5; Snit 1\.3 supports all of Tcl 8\.3, 8\.4 and Tcl 8\.5\. -There are a few minor inconsistencies; they are flagged in the body of the man -page with the label "Snit 1\.x Incompatibility"; they are also discussed in the -__[snitfaq](snitfaq\.md)__\. - -# REFERENCE - -## Type and Widget Definitions - -Snit provides the following commands for defining new types: - - - __snit::type__ *name* *definition* - - Defines a new abstract data type called *name*\. If *name* is not a fully - qualified command name, it is assumed to be a name in the namespace in which - the __snit::type__ command was called \(usually the global namespace\)\. It - returns the fully qualified name of the new type\. - - The type name is then a command that is used to create objects of the new - type, along with other activities\. - - The __snit::type__ *definition* block is a script that may contain the - following definitions: - - * __typevariable__ *name* ?__\-array__? ?*value*? - - Defines a type variable with the specified *name*, and optionally the - specified *value*\. Type variables are shared by all instances of the - type\. If the __\-array__ option is included, then *value* should be - a dictionary; it will be assigned to the variable using __array - set__\. - - * __typemethod__ *name* *arglist* *body* - - Defines a type method, a subcommand of the new type command, with the - specified name, argument list, and body\. The *arglist* is a normal Tcl - argument list and may contain default arguments and the __args__ - argument; however, it may not contain the argument names __type__, - __self__, __selfns__, or __win__\. - - The variable __type__ is automatically defined in the *body* to - the type's fully\-qualified name\. In addition, type variables are - automatically visible in the *body* of every type method\. - - If the *name* consists of two or more tokens, Snit handles it - specially: - - typemethod {a b} {arg} { puts "Got $arg" } - - This statement implicitly defines a type method called __a__ which - has a subcommand __b__\. __b__ is called like this: - - $type a b "Hello, world!" - - __a__ may have any number of subcommands\. This makes it possible to - define a hierarchical command structure; see - __[method](\.\./\.\./\.\./\.\./index\.md\#method)__, below, for more - examples\. - - Type methods can call commands from the namespace in which the type is - defined without importing them, e\.g\., if the type name is - __::parentns::typename__, then the type's type methods can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the following following two - calls to this type method are equivalent: - - $type a b "Hello, world!" - $type {a b} "Hello, world!" - - In Snit 2\.2, the second form is invalid\. - - * __typeconstructor__ *body* - - The type constructor's *body* is executed once when the type is first - defined; it is typically used to initialize array\-valued type variables - and to add entries to [The Tk Option Database](#subsection9)\. - - The variable __type__ is automatically defined in the *body*, and - contains the type's fully\-qualified name\. In addition, type variables - are automatically visible in the *body* of the type constructor\. - - A type may define at most one type constructor\. - - The type constructor can call commands from the namespace in which the - type is defined without importing them, e\.g\., if the type name is - __::parentns::typename__, then the type constructor can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - * __variable__ *name* ?__\-array__? ?*value*? - - Defines an instance variable, a private variable associated with each - instance of this type, and optionally its initial value\. If the - __\-array__ option is included, then *value* should be a - dictionary; it will be assigned to the variable using __array set__\. - - * __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *name* *arglist* *body* - - Defines an instance method, a subcommand of each instance of this type, - with the specified name, argument list and body\. The *arglist* is a - normal Tcl argument list and may contain default arguments and the - __args__ argument\. - - The method is implicitly passed the following arguments as well: - __type__, which contains the fully\-qualified type name; - __self__, which contains the current instance command name; - __selfns__, which contains the name of the instance's private - namespace; and __win__, which contains the original instance name\. - Consequently, the *arglist* may not contain the argument names - __type__, __self__, __selfns__, or __win__\. - - An instance method defined in this way is said to be *locally - defined*\. - - Type and instance variables are automatically visible in all instance - methods\. If the type has locally defined options, the __options__ - array is also visible\. - - If the *name* consists of two or more tokens, Snit handles it - specially: - - method {a b} {} { ... } - - This statement implicitly defines a method called __a__ which has a - subcommand __b__\. __b__ is called like this: - - $self a b "Hello, world!" - - __a__ may have any number of subcommands\. This makes it possible to - define a hierarchical command structure: - - % snit::type dog { - method {tail wag} {} {return "Wag, wag"} - method {tail droop} {} {return "Droop, droop"} - } - ::dog - % dog spot - ::spot - % spot tail wag - Wag, wag - % spot tail droop - Droop, droop - % - - What we've done is implicitly defined a "tail" method with subcommands - "wag" and "droop"\. Consequently, it's an error to define "tail" - explicitly\. - - Methods can call commands from the namespace in which the type is - defined without importing them, e\.g\., if the type name is - __::parentns::typename__, then the type's methods can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the following following two - calls to this method are equivalent: - - $self a b "Hello, world!" - $self {a b} "Hello, world!" - - In Snit 2\.2, the second form is invalid\. - - * __option__ *namespec* ?*defaultValue*? - - * __option__ *namespec* ?*options\.\.\.*? - - Defines an option for instances of this type, and optionally gives it an - initial value\. The initial value defaults to the empty string if no - *defaultValue* is specified\. - - An option defined in this way is said to be *locally defined*\. - - The *namespec* is a list defining the option's name, resource name, - and class name, e\.g\.: - - option {-font font Font} {Courier 12} - - The option name must begin with a hyphen, and must not contain any upper - case letters\. The resource name and class name are optional; if not - specified, the resource name defaults to the option name, minus the - hyphen, and the class name defaults to the resource name with the first - letter capitalized\. Thus, the following statement is equivalent to the - previous example: - - option -font {Courier 12} - - See [The Tk Option Database](#subsection9) for more information - about resource and class names\. - - Options are normally set and retrieved using the standard instance - methods __configure__ and __cget__; within instance code \(method - bodies, etc\.\), option values are available through the __options__ - array: - - set myfont $options(-font) - - If the type defines any option handlers \(e\.g\., - __\-configuremethod__\), then it should probably use __configure__ - and __cget__ to access its options to avoid subtle errors\. - - The __option__ statement may include the following options: - - + __\-default__ *defvalue* - - Defines the option's default value; the option's default value will - be "" otherwise\. - - + __\-readonly__ *flag* - - The *flag* can be any Boolean value recognized by Tcl\. If *flag* - is true, then the option is read\-only\-\-it can only be set using - __configure__ or __configurelist__ at creation time, i\.e\., - in the type's constructor\. - - + __\-type__ *type* - - Every locally\-defined option may define its validation type, which - may be either the name of a validation type or a specification for a - validation subtype - - For example, an option may declare that its value must be an integer - by specifying __snit::integer__ as its validation type: - - option -number -type snit::integer - - It may also declare that its value is an integer between 1 and 10 by - specifying a validation subtype: - - option -number -type {snit::integer -min 1 -max 10} - - If a validation type or subtype is defined for an option, then it - will be used to validate the option's value whenever it is changed - by the object's __configure__ or __configurelist__ methods\. - In addition, all such options will have their values validated - automatically immediately after the constructor executes\. - - Snit defines a family of validation types and subtypes, and it's - quite simple to define new ones\. See [Validation - Types](#subsection11) for the complete list, and [Defining - Validation Types](#subsection12) for an explanation of how to - define your own\. - - + __\-cgetmethod__ *methodName* - - Every locally\-defined option may define a __\-cgetmethod__; it is - called when the option's value is retrieved using the __cget__ - method\. Whatever the method's *body* returns will be the return - value of the call to __cget__\. - - The named method must take one argument, the option name\. For - example, this code is equivalent to \(though slower than\) Snit's - default handling of __cget__: - - option -font -cgetmethod GetOption - method GetOption {option} { - return $options($option) - } - - Note that it's possible for any number of options to share a - __\-cgetmethod__\. - - + __\-configuremethod__ *methodName* - - Every locally\-defined option may define a __\-configuremethod__; - it is called when the option's value is set using the - __configure__ or __configurelist__ methods\. It is the named - method's responsibility to save the option's value; in other words, - the value will not be saved to the __options\(\)__ array unless - the method saves it there\. - - The named method must take two arguments, the option name and its - new value\. For example, this code is equivalent to \(though slower - than\) Snit's default handling of __configure__: - - option -font -configuremethod SetOption - method SetOption {option value} { - set options($option) $value - } - - Note that it's possible for any number of options to share a single - __\-configuremethod__\. - - + __\-validatemethod__ *methodName* - - Every locally\-defined option may define a __\-validatemethod__; - it is called when the option's value is set using the - __configure__ or __configurelist__ methods, just before the - __\-configuremethod__ \(if any\)\. It is the named method's - responsibility to validate the option's new value, and to throw an - error if the value is invalid\. - - The named method must take two arguments, the option name and its - new value\. For example, this code verifies that __\-flag__'s - value is a valid Boolean value: - - option -font -validatemethod CheckBoolean - method CheckBoolean {option value} { - if {![string is boolean -strict $value]} { - error "option $option must have a boolean value." - } - } - - Note that it's possible for any number of options to share a single - __\-validatemethod__\. - - * __constructor__ *arglist* *body* - - The constructor definition specifies a *body* of code to be executed - when a new instance is created\. The *arglist* is a normal Tcl argument - list and may contain default arguments and the __args__ argument\. - - As with methods, the arguments __type__, __self__, - __selfns__, and __win__ are defined implicitly, and all type and - instance variables are automatically visible in its *body*\. - - If the *definition* doesn't explicitly define the constructor, Snit - defines one implicitly\. If the type declares at least one option - \(whether locally or by delegation\), the default constructor will be - defined as follows: - - constructor {args} { - $self configurelist $args - } - - For standard Tk widget behavior, the argument list should be the single - name __args__, as shown\. - - If the *definition* defines neither a constructor nor any options, the - default constructor is defined as follows: - - constructor {} {} - - As with methods, the constructor can call commands from the namespace in - which the type is defined without importing them, e\.g\., if the type name - is __::parentns::typename__, then the constructor can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - * __destructor__ *body* - - The destructor is used to code any actions that must take place when an - instance of the type is destroyed: typically, the destruction of - anything created in the constructor\. - - The destructor takes no explicit arguments; as with methods, the - arguments __type__, __self__, __selfns__, and __win__, - are defined implicitly, and all type and instance variables are - automatically visible in its *body*\. As with methods, the destructor - can call commands from the namespace in which the type is defined - without importing them, e\.g\., if the type name is - __::parentns::typename__, then the destructor can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* *args* *body* - - Defines a new Tcl procedure in the type's namespace\. - - The defined proc differs from a normal Tcl proc in that all type - variables are automatically visible\. The proc can access instance - variables as well, provided that it is passed __selfns__ \(with - precisely that name\) as one of its arguments\. - - Although they are not implicitly defined for procs, the argument names - __type__, __self__, and __win__ should be avoided\. - - As with methods and typemethods, procs can call commands from the - namespace in which the type is defined without importing them, e\.g\., if - the type name is __::parentns::typename__, then the proc can call - __::parentns::someproc__ just as __someproc__\. *Snit 1\.x - Incompatibility:* This does not work in Snit 1\.x, as it depends on - __namespace path__, a new command in Tcl 8\.5\. - - * __delegate__ __method__ *name* __to__ *comp* ?__as__ *target*? - - Delegates method *name* to component *comp*\. That is, when method - *name* is called on an instance of this type, the method and its - arguments will be passed to the named component's command instead\. That - is, the following statement - - delegate method wag to tail - - is roughly equivalent to this explicitly defined method: - - method wag {args} { - uplevel $tail wag $args - } - - As with methods, the *name* may have multiple tokens; in this case, - the last token of the name is assumed to be the name of the component's - method\. - - The optional __as__ clause allows you to specify the delegated - method name and possibly add some arguments: - - delegate method wagtail to tail as "wag briskly" - - A method cannot be both locally defined and delegated\. - - __Note:__ All forms of __delegate method__ can delegate to both - instance components and type components\. - - * __delegate__ __method__ *name* ?__to__ *comp*? __using__ *pattern* - - In this form of the __delegate__ statement, the __using__ clause - is used to specify the precise form of the command to which method - *name* name is delegated\. In this form, the __to__ clause is - optional, since the chosen command might not involve any particular - component\. - - The value of the __using__ clause is a list that may contain any or - all of the following substitution codes; these codes are substituted - with the described value to build the delegated command prefix\. Note - that the following two statements are equivalent: - - delegate method wag to tail - delegate method wag to tail using "%c %m" - - Each element of the list becomes a single element of the delegated - command\-\-it is never reparsed as a string\. - - Substitutions: - - + __%%__ - - This is replaced with a single "%"\. Thus, to pass the string "%c" to - the command as an argument, you'd write "%%c"\. - - + __%c__ - - This is replaced with the named component's command\. - - + __%m__ - - This is replaced with the final token of the method *name*; if the - method *name* has one token, this is identical to __%M__\. - - + __%M__ - - This is replaced by the method *name*; if the *name* consists of - multiple tokens, they are joined by space characters\. - - + __%j__ - - This is replaced by the method *name*; if the *name* consists of - multiple tokens, they are joined by underscores \("\_"\)\. - - + __%t__ - - This is replaced with the fully qualified type name\. - - + __%n__ - - This is replaced with the name of the instance's private namespace\. - - + __%s__ - - This is replaced with the name of the instance command\. - - + __%w__ - - This is replaced with the original name of the instance command; for - Snit widgets and widget adaptors, it will be the Tk window name\. It - remains constant, even if the instance command is renamed\. - - * __delegate__ __method__ __\*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*? - - The form __delegate method \*__ delegates all unknown method names to - the specified *comp*onent\. The __except__ clause can be used to - specify a list of *exceptions*, i\.e\., method names that will not be so - delegated\. The __using__ clause is defined as given above\. In this - form, the statement must contain the __to__ clause, the - __using__ clause, or both\. - - In fact, the "\*" can be a list of two or more tokens whose last element - is "\*", as in the following example: - - delegate method {tail *} to tail - - This implicitly defines the method __tail__ whose subcommands will - be delegated to the __tail__ component\. - - * __delegate__ __option__ *namespec* __to__ *comp* - - * __delegate__ __option__ *namespec* __to__ *comp* __as__ *target* - - * __delegate__ __option__ __\*__ __to__ *comp* - - * __delegate__ __option__ __\*__ __to__ *comp* __except__ *exceptions* - - Defines a delegated option; the *namespec* is defined as for the - __option__ statement\. When the __configure__, - __configurelist__, or __cget__ instance method is used to set or - retrieve the option's value, the equivalent __configure__ or - __cget__ command will be applied to the component as though the - option was defined with the following __\-configuremethod__ and - __\-cgetmethod__: - - method ConfigureMethod {option value} { - $comp configure $option $value - } - - method CgetMethod {option} { - return [$comp cget $option] - } - - Note that delegated options never appear in the __options__ array\. - - If the __as__ clause is specified, then the *target* option name - is used in place of *name*\. - - The form __delegate option \*__ delegates all unknown options to the - specified *comp*onent\. The __except__ clause can be used to - specify a list of *exceptions*, i\.e\., option names that will not be so - delegated\. - - Warning: options can only be delegated to a component if it supports the - __configure__ and __cget__ instance methods\. - - An option cannot be both locally defined and delegated\. TBD: Continue - from here\. - - * __component__ *comp* ?__\-public__ *method*? ?__\-inherit__ *flag*? - - Explicitly declares a component called *comp*, and automatically - defines the component's instance variable\. - - If the __\-public__ option is specified, then the option is made - public by defining a *method* whose subcommands are delegated to the - component e\.g\., specifying __\-public mycomp__ is equivalent to the - following: - - component mycomp - delegate method {mymethod *} to mycomp - - If the __\-inherit__ option is specified, then *flag* must be a - Boolean value; if *flag* is true then all unknown methods and options - will be delegated to this component\. The name __\-inherit__ implies - that instances of this new type inherit, in a sense, the methods and - options of the component\. That is, __\-inherit yes__ is equivalent - to: - - component mycomp - delegate option * to mycomp - delegate method * to mycomp - - * __delegate__ __typemethod__ *name* __to__ *comp* ?__as__ *target*? - - Delegates type method *name* to type component *comp*\. That is, when - type method *name* is called on this type, the type method and its - arguments will be passed to the named type component's command instead\. - That is, the following statement - - delegate typemethod lostdogs to pound - - is roughly equivalent to this explicitly defined method: - - typemethod lostdogs {args} { - uplevel $pound lostdogs $args - } - - As with type methods, the *name* may have multiple tokens; in this - case, the last token of the name is assumed to be the name of the - component's method\. - - The optional __as__ clause allows you to specify the delegated - method name and possibly add some arguments: - - delegate typemethod lostdogs to pound as "get lostdogs" - - A type method cannot be both locally defined and delegated\. - - * __delegate__ __typemethod__ *name* ?__to__ *comp*? __using__ *pattern* - - In this form of the __delegate__ statement, the __using__ clause - is used to specify the precise form of the command to which type method - *name* name is delegated\. In this form, the __to__ clause is - optional, since the chosen command might not involve any particular type - component\. - - The value of the __using__ clause is a list that may contain any or - all of the following substitution codes; these codes are substituted - with the described value to build the delegated command prefix\. Note - that the following two statements are equivalent: - - delegate typemethod lostdogs to pound - delegate typemethod lostdogs to pound using "%c %m" - - Each element of the list becomes a single element of the delegated - command\-\-it is never reparsed as a string\. - - Substitutions: - - + __%%__ - - This is replaced with a single "%"\. Thus, to pass the string "%c" to - the command as an argument, you'd write "%%c"\. - - + __%c__ - - This is replaced with the named type component's command\. - - + __%m__ - - This is replaced with the final token of the type method *name*; - if the type method *name* has one token, this is identical to - __%M__\. - - + __%M__ - - This is replaced by the type method *name*; if the *name* - consists of multiple tokens, they are joined by space characters\. - - + __%j__ - - This is replaced by the type method *name*; if the *name* - consists of multiple tokens, they are joined by underscores \("\_"\)\. - - + __%t__ - - This is replaced with the fully qualified type name\. - - * __delegate__ __typemethod__ __\*__ ?__to__ *comp*? ?__using__ *pattern*? ?__except__ *exceptions*? - - The form __delegate typemethod \*__ delegates all unknown type method - names to the specified type component\. The __except__ clause can be - used to specify a list of *exceptions*, i\.e\., type method names that - will not be so delegated\. The __using__ clause is defined as given - above\. In this form, the statement must contain the __to__ clause, - the __using__ clause, or both\. - - __Note:__ By default, Snit interprets __$type foo__, where - __foo__ is not a defined type method, as equivalent to __$type - create foo__, where __foo__ is the name of a new instance of the - type\. If you use __delegate typemethod \*__, then the __create__ - type method must always be used explicitly\. - - The "\*" can be a list of two or more tokens whose last element is "\*", - as in the following example: - - delegate typemethod {tail *} to tail - - This implicitly defines the type method __tail__ whose subcommands - will be delegated to the __tail__ type component\. - - * __typecomponent__ *comp* ?__\-public__ *typemethod*? ?__\-inherit__ *flag*? - - Explicitly declares a type component called *comp*, and automatically - defines the component's type variable\. A type component is an arbitrary - command to which type methods and instance methods can be delegated; the - command's name is stored in a type variable\. - - If the __\-public__ option is specified, then the type component is - made public by defining a *typemethod* whose subcommands are delegated - to the type component, e\.g\., specifying __\-public mytypemethod__ is - equivalent to the following: - - typecomponent mycomp - delegate typemethod {mytypemethod *} to mycomp - - If the __\-inherit__ option is specified, then *flag* must be a - Boolean value; if *flag* is true then all unknown type methods will be - delegated to this type component\. \(See the note on "delegate typemethod - \*", above\.\) The name __\-inherit__ implies that this type inherits, - in a sense, the behavior of the type component\. That is, __\-inherit - yes__ is equivalent to: - - typecomponent mycomp - delegate typemethod * to mycomp - - * __pragma__ ?*options\.\.\.*? - - The __pragma__ statement provides control over how Snit generates a - type\. It takes the following options; in each case, *flag* must be a - Boolean value recognized by Tcl, e\.g\., __0__, __1__, - __yes__, __no__, and so on\. - - By setting the __\-hastypeinfo__, __\-hastypedestroy__, and - __\-hasinstances__ pragmas to false and defining appropriate type - methods, you can create an ensemble command without any extraneous - behavior\. - - + __\-canreplace__ *flag* - - If false \(the default\) Snit will not create an instance of a - __snit::type__ that has the same name as an existing command; - this prevents subtle errors\. Setting this pragma to true restores - the behavior of Snit V0\.93 and earlier versions\. - - + __\-hastypeinfo__ *flag* - - If true \(the default\), the generated type will have a type method - called __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ that is used - for type introspection; the - __[info](\.\./\.\./\.\./\.\./index\.md\#info)__ type method is - documented below\. If false, it will not\. - - + __\-hastypedestroy__ *flag* - - If true \(the default\), the generated type will have a type method - called __destroy__ that is used to destroy the type and all of - its instances\. The __destroy__ type method is documented below\. - If false, it will not\. - - + __\-hastypemethods__ *flag* - - If true \(the default\), the generated type's type command will have - subcommands \(type methods\) as usual\. If false, the type command will - serve only to create instances of the type; the first argument is - the instance name\. - - This pragma and __\-hasinstances__ cannot both be set false\. - - + __\-hasinstances__ *flag* - - If true \(the default\), the generated type will have a type method - called __create__ that is used to create instances of the type, - along with a variety of instance\-related features\. If false, it will - not\. - - This pragma and __\-hastypemethods__ cannot both be set false\. - - + __\-hasinfo__ *flag* - - If true \(the default\), instances of the generated type will have an - instance method called __info__ that is used for instance - introspection; the __info__ method is documented below\. If - false, it will not\. - - + __\-simpledispatch__ *flag* - - This pragma is intended to make simple, heavily\-used abstract data - types \(e\.g\., stacks and queues\) more efficient\. - - If false \(the default\), instance methods are dispatched normally\. If - true, a faster dispatching scheme is used instead\. The speed comes - at a price; with __\-simpledispatch yes__ you get the following - limitations: - - - Methods cannot be delegated\. - - - __uplevel__ and __upvar__ do not work as expected: the - caller's scope is two levels up rather than one\. - - - The option\-handling methods \(__cget__, __configure__, - and __configurelist__\) are very slightly slower\. - - * __expose__ *comp* - - * __expose__ *comp* __as__ *method* - - __Deprecated\.__ To expose component *comp* publicly, use - __component__'s __\-public__ option\. - - * __onconfigure__ *name* *arglist* *body* - - __Deprecated\.__ Define __option__'s __\-configuremethod__ - option instead\. - - As of version 0\.95, the following definitions, - - option -myoption - onconfigure -myoption {value} { - # Code to save the option's value - } - - are implemented as follows: - - option -myoption -configuremethod _configure-myoption - method _configure-myoption {_option value} { - # Code to save the option's value - } - - * __oncget__ *name* *body* - - __Deprecated\.__ Define __option__'s __\-cgetmethod__ option - instead\. - - As of version 0\.95, the following definitions, - - option -myoption - oncget -myoption { - # Code to return the option's value - } - - are implemented as follows: - - option -myoption -cgetmethod _cget-myoption - method _cget-myoption {_option} { - # Code to return the option's value - } - - - __snit::widget__ *name* *definition* - - This command defines a Snit megawidget type with the specified *name*\. The - *definition* is defined as for __snit::type__\. A __snit::widget__ - differs from a __snit::type__ in these ways: - - * Every instance of a __snit::widget__ has an automatically\-created - component called __hull__, which is normally a Tk frame widget\. - Other widgets created as part of the megawidget will be created within - this widget\. - - The hull component is initially created with the requested widget name; - then Snit does some magic, renaming the hull component and installing - its own instance command in its place\. The hull component's new name is - saved in an instance variable called __hull__\. - - * The name of an instance must be valid Tk window name, and the parent - window must exist\. - - A __snit::widget__ definition can include any of statements allowed in a - __snit::type__ definition, and may also include the following: - - * __widgetclass__ *name* - - Sets the __snit::widget__'s widget class to *name*, overriding the - default\. See [The Tk Option Database](#subsection9) for more - information\. - - * __hulltype__ *type* - - Determines the kind of widget used as the __snit::widget__'s hull\. - The *type* may be __frame__ \(the default\), __toplevel__, - __labelframe__; the qualified equivalents of these, - __tk::frame__, __tk::toplevel__, and __tk::labelframe__; or, - if available, the equivalent Tile widgets: __ttk::frame__, - __ttk::toplevel__, and __ttk::labelframe__\. In practice, any - widget that supports the __\-class__ option can be used as a hull - widget by __lappend__'ing its name to the variable - __snit::hulltypes__\. - - - __snit::widgetadaptor__ *name* *definition* - - This command defines a Snit megawidget type with the specified name\. It - differs from __snit::widget__ in that the instance's __hull__ - component is not created automatically, but is created in the constructor - and installed using the __installhull__ command\. Once the hull is - installed, its instance command is renamed and replaced as with normal - __snit::widget__s\. The original command is again accessible in the - instance variable __hull__\. - - Note that in general it is not possible to change the *widget class* of a - __snit::widgetadaptor__'s hull widget\. - - See [The Tk Option Database](#subsection9) for information on how - __snit::widgetadaptor__s interact with the option database\. - - - __snit::typemethod__ *type* *name* *arglist* *body* - - Defines a new type method \(or redefines an existing type method\) for a - previously existing *type*\. - - - __snit::method__ *type* *name* *arglist* *body* - - Defines a new instance method \(or redefines an existing instance method\) for - a previously existing *type*\. Note that delegated instance methods can't - be redefined\. - - - __snit::macro__ *name* *arglist* *body* - - Defines a Snit macro with the specified *name*, *arglist*, and *body*\. - Macros are used to define new type and widget definition statements in terms - of the statements defined in this man page\. - - A macro is simply a Tcl proc that is defined in the slave interpreter used - to compile type and widget definitions\. Thus, macros have access to all of - the type and widget definition statements\. See [Macros and - Meta\-programming](#subsection10) for more details\. - - The macro *name* cannot be the same as any standard Tcl command, or any - Snit type or widget definition statement, e\.g\., you can't redefine the - __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ or __delegate__ - statements, or the standard __[set](\.\./\.\./\.\./\.\./index\.md\#set)__, - __[list](\.\./\.\./\.\./\.\./index\.md\#list)__, or - __[string](\.\./\.\./\.\./\.\./index\.md\#string)__ commands\. - - - __snit::compile__ *which* *type* *body* - - Snit defines a type, widget, or widgetadaptor by "compiling" the definition - into a Tcl script; this script is then evaluated in the Tcl interpreter, - which actually defines the new type\. - - This command exposes the "compiler"\. Given a definition *body* for the - named *type*, where *which* is __type__, __widget__, or - __widgetadaptor__, __snit::compile__ returns a list of two elements\. - The first element is the fully qualified type name; the second element is - the definition script\. - - __snit::compile__ is useful when additional processing must be done on - the Snit\-generated code\-\-if it must be instrumented, for example, or run - through the TclDevKit compiler\. In addition, the returned script could be - saved in a "\.tcl" file and used to define the type as part of an application - or library, thus saving the compilation overhead at application start\-up\. - Note that the same version of Snit must be used at run\-time as at - compile\-time\. - -## The Type Command - -A type or widget definition creates a type command, which is used to create -instances of the type\. The type command has this form: - - - __$type__ *typemethod* *args*\.\.\. - - The *typemethod* can be any of the [Standard Type - Methods](#subsection3) \(e\.g\., __create__\), or any type method - defined in the type definition\. The subsequent *args* depend on the - specific *typemethod* chosen\. - - The type command is most often used to create new instances of the type; - hence, the __create__ method is assumed if the first argument to the - type command doesn't name a valid type method, unless the type definition - includes __delegate typemethod \*__ or the __\-hasinstances__ pragma - is set to false\. - - Furthermore, if the __\-hastypemethods__ pragma is false, then Snit type - commands can be called with no arguments at all; in this case, the type - command creates an instance with an automatically generated name\. In other - words, provided that the __\-hastypemethods__ pragma is false and the - type has instances, the following commands are equivalent: - - snit::type dog { ... } - - set mydog [dog create %AUTO%] - set mydog [dog %AUTO%] - set mydog [dog] - - This doesn't work for Snit widgets, for obvious reasons\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the above behavior is available - whether __\-hastypemethods__ is true \(the default\) or false\. - -## Standard Type Methods - -In addition to any type methods in the type's definition, all type and widget -commands will usually have at least the following subcommands: - - - __$type__ __create__ *name* ?*option* *value* \.\.\.? - - Creates a new instance of the type, giving it the specified *name* and - calling the type's constructor\. - - For __snit::type__s, if *name* is not a fully\-qualified command name, - it is assumed to be a name in the namespace in which the call to - __snit::type__ appears\. The method returns the fully\-qualified instance - name\. - - For __snit::widget__s and __snit::widgetadaptor__s, *name* must be - a valid widget name; the method returns the widget name\. - - So long as *name* does not conflict with any defined type method name the - __create__ keyword may be omitted, unless the type definition includes - __delegate typemethod \*__ or the __\-hasinstances__ pragma is set to - false\. - - If the *name* includes the string __%AUTO%__, it will be replaced with - the string __$type$counter__ where __$type__ is the type name and - __$counter__ is a counter that increments each time __%AUTO%__ is - used for this type\. - - By default, any arguments following the *name* will be a list of - *option* names and their *value*s; however, a type's constructor can - specify a different argument list\. - - As of Snit V0\.95, __create__ will throw an error if the *name* is the - same as any existing command\-\-note that this was always true for - __snit::widget__s and __snit::widgetadaptor__s\. You can restore the - previous behavior using the __\-canreplace__ pragma\. - - - __$type__ __info typevars__ ?*pattern*? - - Returns a list of the type's type variables \(excluding Snit internal - variables\); all variable names are fully\-qualified\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - - __$type__ __info typemethods__ ?*pattern*? - - Returns a list of the names of the type's type methods\. If the type has - hierarchical type methods, whether locally\-defined or delegated, only the - first word of each will be included in the list\. - - If the type definition includes __delegate typemethod \*__, the list will - include only the names of those implicitly delegated type methods that have - been called at least once and are still in the type method cache\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - - __$type__ __info args__ *method* - - Returns a list containing the names of the arguments to the type's - *method*, in order\. This method cannot be applied to delegated type - methods\. - - - __$type__ __info body__ *method* - - Returns the body of typemethod *method*\. This method cannot be applied to - delegated type methods\. - - - __$type__ __info default__ *method* *aname* *varname* - - Returns a boolean value indicating whether the argument *aname* of the - type's *method* has a default value \(__true__\) or not \(__false__\)\. - If the argument has a default its value is placed into the variable - *varname*\. - - - __$type__ __info instances__ ?*pattern*? - - Returns a list of the type's instances\. For __snit::type__s, it will be - a list of fully\-qualified instance names; for __snit::widget__s, it will - be a list of Tk widget names\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the full multi\-word names of - hierarchical type methods are included in the return value\. - - - __$type__ __destroy__ - - Destroys the type's instances, the type's namespace, and the type command - itself\. - -## The Instance Command - -A Snit type or widget's __create__ type method creates objects of the type; -each object has a unique name that is also a Tcl command\. This command is used -to access the object's methods and data, and has this form: - - - __$object__ *method* *args\.\.\.* - - The *method* can be any of the [Standard Instance - Methods](#subsection5), or any instance method defined in the type - definition\. The subsequent *args* depend on the specific *method* - chosen\. - -## Standard Instance Methods - -In addition to any delegated or locally\-defined instance methods in the type's -definition, all Snit objects will have at least the following subcommands: - - - __$object__ __configure__ ?*option*? ?*value*? \.\.\. - - Assigns new values to one or more options\. If called with one argument, an - *option* name, returns a list describing the option, as Tk widgets do; if - called with no arguments, returns a list of lists describing all options, as - Tk widgets do\. - - Warning: This information will be available for delegated options only if - the component to which they are delegated has a __configure__ method - that returns this same kind of information\. - - Note: Snit defines this method only if the type has at least one option\. - - - __$object__ __configurelist__ *optionlist* - - Like __configure__, but takes one argument, a list of options and their - values\. It's mostly useful in the type constructor, but can be used - anywhere\. - - Note: Snit defines this method only if the type has at least one option\. - - - __$object__ __cget__ *option* - - Returns the option's value\. - - Note: Snit defines this method only if the type has at least one option\. - - - __$object__ __destroy__ - - Destroys the object, calling the __destructor__ and freeing all related - memory\. - - *Note:* The __destroy__ method isn't defined for __snit::widget__ - or __snit::widgetadaptor__ objects; instances of these are destroyed by - calling __[Tk](\.\./\.\./\.\./\.\./index\.md\#tk)__'s __destroy__ command, - just as normal widgets are\. - - - __$object__ __info type__ - - Returns the instance's type\. - - - __$object__ __info vars__ ?*pattern*? - - Returns a list of the object's instance variables \(excluding Snit internal - variables\)\. The names are fully qualified\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - - __$object__ __info typevars__ ?*pattern*? - - Returns a list of the object's type's type variables \(excluding Snit - internal variables\)\. The names are fully qualified\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - - __$object__ __info typemethods__ ?*pattern*? - - Returns a list of the names of the type's type methods\. If the type has - hierarchical type methods, whether locally\-defined or delegated, only the - first word of each will be included in the list\. - - If the type definition includes __delegate typemethod \*__, the list will - include only the names of those implicitly delegated type methods that have - been called at least once and are still in the type method cache\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the full multi\-word names of - hierarchical type methods are included in the return value\. - - - __$object__ __info options__ ?*pattern*? - - Returns a list of the object's option names\. This always includes local - options and explicitly delegated options\. If unknown options are delegated - as well, and if the component to which they are delegated responds to - __$object configure__ like Tk widgets do, then the result will include - all possible unknown options that can be delegated to the component\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - Note that the return value might be different for different instances of the - same type, if component object types can vary from one instance to another\. - - - __$object__ __info methods__ ?*pattern*? - - Returns a list of the names of the instance's methods\. If the type has - hierarchical methods, whether locally\-defined or delegated, only the first - word of each will be included in the list\. - - If the type definition includes __delegate method \*__, the list will - include only the names of those implicitly delegated methods that have been - called at least once and are still in the method cache\. - - If *pattern* is given, it's used as a __string match__ pattern; only - names that match the pattern are returned\. - - *Snit 1\.x Incompatibility:* In Snit 1\.x, the full multi\-word names of - hierarchical type methods are included in the return value\. - - - __$object__ __info args__ *method* - - Returns a list containing the names of the arguments to the instance's - *method*, in order\. This method cannot be applied to delegated methods\. - - - __$object__ __info body__ *method* - - Returns the body of the instance's method *method*\. This method cannot be - applied to delegated methods\. - - - __$object__ __info default__ *method* *aname* *varname* - - Returns a boolean value indicating whether the argument *aname* of the - instance's *method* has a default value \(__true__\) or not - \(__false__\)\. If the argument has a default its value is placed into the - variable *varname*\. - -## Commands for use in Object Code - -Snit defines the following commands for use in your object code: that is, for -use in type methods, instance methods, constructors, destructors, onconfigure -handlers, oncget handlers, and procs\. They do not reside in the ::snit:: -namespace; instead, they are created with the type, and can be used without -qualification\. - - - __mymethod__ *name* ?*args\.\.\.*? - - The __mymethod__ command is used for formatting callback commands to be - passed to other objects\. It returns a command that when called will invoke - method *name* with the specified arguments, plus of course any arguments - added by the caller\. In other words, both of the following commands will - cause the object's __dosomething__ method to be called when the - __$button__ is pressed: - - $button configure -command [list $self dosomething myargument] - - $button configure -command [mymethod dosomething myargument] - - The chief distinction between the two is that the latter form will not break - if the object's command is renamed\. - - - __mytypemethod__ *name* ?*args\.\.\.*? - - The __mytypemethod__ command is used for formatting callback commands to - be passed to other objects\. It returns a command that when called will - invoke type method *name* with the specified arguments, plus of course any - arguments added by the caller\. In other words, both of the following - commands will cause the object's __dosomething__ type method to be - called when __$button__ is pressed: - - $button configure -command [list $type dosomething myargument] - - $button configure -command [mytypemethod dosomething myargument] - - Type commands cannot be renamed, so in practice there's little difference - between the two forms\. __mytypemethod__ is provided for parallelism with - __mymethod__\. - - - __myproc__ *name* ?*args\.\.\.*? - - The __myproc__ command is used for formatting callback commands to be - passed to other objects\. It returns a command that when called will invoke - the type proc *name* with the specified arguments, plus of course any - arguments added by the caller\. In other words, both of the following - commands will cause the object's __dosomething__ proc to be called when - __$button__ is pressed: - - $button configure -command [list ${type}::dosomething myargument] - - $button configure -command [myproc dosomething myargument] - - - __myvar__ *name* - - Given an instance variable name, returns the fully qualified name\. Use this - if you're passing the variable to some other object, e\.g\., as a - __\-textvariable__ to a Tk label widget\. - - - __mytypevar__ *name* - - Given an type variable name, returns the fully qualified name\. Use this if - you're passing the variable to some other object, e\.g\., as a - __\-textvariable__ to a Tk label widget\. - - - __from__ *argvName* *option* ?*defvalue*? - - The __from__ command plucks an option value from a list of options and - their values, such as is passed into a type's __constructor__\. - *argvName* must be the name of a variable containing such a list; - *option* is the name of the specific option\. - - __from__ looks for *option* in the option list\. If it is found, it and - its value are removed from the list, and the value is returned\. If - *option* doesn't appear in the list, then the *defvalue* is returned\. If - the option is locally\-defined option, and *defvalue* is not specified, - then the option's default value as specified in the type definition will be - returned instead\. - - - __install__ *compName* __using__ *objType* *objName* *args\.\.\.* - - Creates a new object of type *objType* called *objName* and installs it - as component *compName*, as described in [Components and - Delegation](#subsection7)\. Any additional *args\.\.\.* are passed along - with the name to the *objType* command\. If this is a __snit::type__, - then the following two commands are equivalent: - - install myComp using myObjType $self.myComp args... - - set myComp [myObjType $self.myComp args...] - - Note that whichever method is used, *compName* must still be declared in - the type definition using __component__, or must be referenced in at - least one __delegate__ statement\. - - If this is a __snit::widget__ or __snit::widgetadaptor__, and if - options have been delegated to component *compName*, then those options - will receive default values from the Tk option database\. Note that it - doesn't matter whether the component to be installed is a widget or not\. See - [The Tk Option Database](#subsection9) for more information\. - - __install__ cannot be used to install type components; just assign the - type component's command name to the type component's variable instead\. - - - __installhull__ __using__ *widgetType* *args\.\.\.* - - - __installhull__ *name* - - The constructor of a __snit::widgetadaptor__ must create a widget to be - the object's hull component; the widget is installed as the hull component - using this command\. Note that the installed widget's name must be - __$win__\. This command has two forms\. - - The first form specifies the *widgetType* and the *args\.\.\.* \(that is, - the hardcoded option list\) to use in creating the hull\. Given this form, - __installhull__ creates the hull widget, and initializes any options - delegated to the hull from the Tk option database\. - - In the second form, the hull widget has already been created; note that its - name must be "$win"\. In this case, the Tk option database is *not* queried - for any options delegated to the hull\. The longer form is preferred; - however, the shorter form allows the programmer to adapt a widget created - elsewhere, which is sometimes useful\. For example, it can be used to adapt a - "page" widget created by a __BWidgets__ tabbed notebook or pages manager - widget\. - - See [The Tk Option Database](#subsection9) for more information about - __snit::widgetadaptor__s and the option database\. - - - __variable__ *name* - - Normally, instance variables are defined in the type definition along with - the options, methods, and so forth; such instance variables are - automatically visible in all instance code \(e\.g\., method bodies\)\. However, - instance code can use the __variable__ command to declare instance - variables that don't appear in the type definition, and also to bring - variables from other namespaces into scope in the usual way\. - - It's generally clearest to define all instance variables in the type - definition, and omit declaring them in methods and so forth\. - - Note that this is an instance\-specific version of the standard Tcl - __::variable__ command\. - - - __typevariable__ *name* - - Normally, type variables are defined in the type definition, along with the - instance variables; such type variables are automatically visible in all of - the type's code\. However, type methods, instance methods and so forth can - use __typevariable__ to declare type variables that don't appear in the - type definition\. - - It's generally clearest to declare all type variables in the type - definition, and omit declaring them in methods, type methods, etc\. - - - __varname__ *name* - - __Deprecated\.__ Use __myvar__ instead\. - - Given an instance variable name, returns the fully qualified name\. Use this - if you're passing the variable to some other object, e\.g\., as a - __\-textvariable__ to a Tk label widget\. - - - __typevarname__ *name* - - __Deprecated\.__ Use __mytypevar__ instead\. - - Given a type variable name, returns the fully qualified name\. Use this if - you're passing the type variable to some other object, e\.g\., as a - __\-textvariable__ to a Tk label widget\. - - - __codename__ *name* - - __Deprecated\.__ Use __myproc__ instead\. Given the name of a proc - \(but not a type or instance method\), returns the fully\-qualified command - name, suitable for passing as a callback\. - -## Components and Delegation - -When an object includes other objects, as when a toolbar contains buttons or a -GUI object contains an object that references a database, the included object is -called a component\. The standard way to handle component objects owned by a Snit -object is to declare them using __component__, which creates a component -instance variable\. In the following example, a __dog__ object has a -__tail__ object: - - snit::type dog { - component mytail - - constructor {args} { - set mytail [tail %AUTO% -partof $self] - $self configurelist $args - } - - method wag {} { - $mytail wag - } - } - - snit::type tail { - option -length 5 - option -partof - method wag {} { return "Wag, wag, wag."} - } - -Because the __tail__ object's name is stored in an instance variable, it's -easily accessible in any method\. - -The __install__ command provides an alternate way to create and install the -component: - - snit::type dog { - component mytail - - constructor {args} { - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - - method wag {} { - $mytail wag - } - } - -For __snit::type__s, the two methods are equivalent; for -__snit::widget__s and __snit::widgetadaptor__s, the __install__ -command properly initializes the widget's options by querying [The Tk Option -Database](#subsection9)\. - -In the above examples, the __dog__ object's __wag__ method simply calls -the __tail__ component's __wag__ method\. In OO jargon, this is called -delegation\. Snit provides an easier way to do this: - - snit::type dog { - delegate method wag to mytail - - constructor {args} { - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - } - -The __delegate__ statement in the type definition implicitly defines the -instance variable __mytail__ to hold the component's name \(though it's good -form to use __component__ to declare it explicitly\); it also defines the -__dog__ object's __wag__ method, delegating it to the __mytail__ -component\. - -If desired, all otherwise unknown methods can be delegated to a specific -component: - - snit::type dog { - delegate method * to mytail - - constructor {args} { - set mytail [tail %AUTO% -partof $self] - $self configurelist $args - } - - method bark { return "Bark, bark, bark!" } - } - -In this case, a __dog__ object will handle its own __bark__ method; but -__wag__ will be passed along to __mytail__\. Any other method, being -recognized by neither __dog__ nor __tail__, will simply raise an error\. - -Option delegation is similar to method delegation, except for the interactions -with the Tk option database; this is described in [The Tk Option -Database](#subsection9)\. - -## Type Components and Delegation - -The relationship between type components and instance components is identical to -that between type variables and instance variables, and that between type -methods and instance methods\. Just as an instance component is an instance -variable that holds the name of a command, so a type component is a type -variable that holds the name of a command\. In essence, a type component is a -component that's shared by every instance of the type\. - -Just as __delegate method__ can be used to delegate methods to instance -components, as described in [Components and Delegation](#subsection7), so -__delegate typemethod__ can be used to delegate type methods to type -components\. - -Note also that as of Snit 0\.95 __delegate method__ can delegate methods to -both instance components and type components\. - -## The Tk Option Database - -This section describes how Snit interacts with the Tk option database, and -assumes the reader has a working knowledge of the option database and its uses\. -The book *Practical Programming in Tcl and Tk* by Welch et al has a good -introduction to the option database, as does *Effective Tcl/Tk Programming*\. - -Snit is implemented so that most of the time it will simply do the right thing -with respect to the option database, provided that the widget developer does the -right thing by Snit\. The body of this section goes into great deal about what -Snit requires\. The following is a brief statement of the requirements, for -reference\. - - - If the __snit::widget__'s default widget class is not what is desired, - set it explicitly using __widgetclass__ in the widget definition\. - - - When defining or delegating options, specify the resource and class names - explicitly when if the defaults aren't what you want\. - - - Use __installhull using__ to install the hull for - __snit::widgetadaptor__s\. - - - Use __install__ to install all other components\. - -The interaction of Tk widgets with the option database is a complex thing; the -interaction of Snit with the option database is even more so, and repays -attention to detail\. - -__Setting the widget class:__ Every Tk widget has a widget class\. For Tk -widgets, the widget class name is the just the widget type name with an initial -capital letter, e\.g\., the widget class for __button__ widgets is "Button"\. - -Similarly, the widget class of a __snit::widget__ defaults to the -unqualified type name with the first letter capitalized\. For example, the widget -class of - - snit::widget ::mylibrary::scrolledText { ... } - -is "ScrolledText"\. The widget class can also be set explicitly using the -__widgetclass__ statement within the __snit::widget__ definition\. - -Any widget can be used as the __hulltype__ provided that it supports the -__\-class__ option for changing its widget class name\. See the discussion of -the __hulltype__ command, above\. The user may pass __\-class__ to the -widget at instantion\. - -The widget class of a __snit::widgetadaptor__ is just the widget class of -its hull widget; this cannot be changed unless the hull widget supports -__\-class__, in which case it will usually make more sense to use -__snit::widget__ rather than __snit::widgetadaptor__\. - -__Setting option resource names and classes:__ In Tk, every option has three -names: the option name, the resource name, and the class name\. The option name -begins with a hyphen and is all lowercase; it's used when creating widgets, and -with the __configure__ and __cget__ commands\. - -The resource and class names are used to initialize option default values by -querying the Tk option database\. The resource name is usually just the option -name minus the hyphen, but may contain uppercase letters at word boundaries; the -class name is usually just the resource name with an initial capital, but not -always\. For example, here are the option, resource, and class names for several -__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget options: - - -background background Background - -borderwidth borderWidth BorderWidth - -insertborderwidth insertBorderWidth BorderWidth - -padx padX Pad - -As is easily seen, sometimes the resource and class names can be inferred from -the option name, but not always\. - -Snit options also have a resource name and a class name\. By default, these names -follow the rule given above: the resource name is the option name without the -hyphen, and the class name is the resource name with an initial capital\. This is -true for both locally\-defined options and explicitly delegated options: - - snit::widget mywidget { - option -background - delegate option -borderwidth to hull - delegate option * to text - # ... - } - -In this case, the widget class name is "Mywidget"\. The widget has the following -options: __\-background__, which is locally defined, and -__\-borderwidth__, which is explicitly delegated; all other widgets are -delegated to a component called "text", which is probably a Tk -__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget\. If so, __mywidget__ -has all the same options as a __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ -widget\. The option, resource, and class names are as follows: - - -background background Background - -borderwidth borderwidth Borderwidth - -padx padX Pad - -Note that the locally defined option, __\-background__, happens to have the -same three names as the standard Tk __\-background__ option; and -__\-pad__, which is delegated implicitly to the __text__ component, has -the same three names for __mywidget__ as it does for the -__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget\. __\-borderwidth__, on -the other hand, has different resource and class names than usual, because the -internal word "width" isn't capitalized\. For consistency, it should be; this is -done as follows: - - snit::widget mywidget { - option -background - delegate option {-borderwidth borderWidth} to hull - delegate option * to text - # ... - } - -The class name will default to "BorderWidth", as expected\. - -Suppose, however, that __mywidget__ also delegated __\-padx__ and -__\-pady__ to the hull\. In this case, both the resource name and the class -name must be specified explicitly: - - snit::widget mywidget { - option -background - delegate option {-borderwidth borderWidth} to hull - delegate option {-padx padX Pad} to hull - delegate option {-pady padY Pad} to hull - delegate option * to text - # ... - } - -__Querying the option database:__ If you set your widgetclass and option -names as described above, Snit will query the option database when each instance -is created, and will generally do the right thing when it comes to querying the -option database\. The remainder of this section goes into the gory details\. - -__Initializing locally defined options:__ When an instance of a snit::widget -is created, its locally defined options are initialized as follows: each -option's resource and class names are used to query the Tk option database\. If -the result is non\-empty, it is used as the option's default; otherwise, the -default hardcoded in the type definition is used\. In either case, the default -can be overridden by the caller\. For example, - - option add *Mywidget.texture pebbled - - snit::widget mywidget { - option -texture smooth - # ... - } - - mywidget .mywidget -texture greasy - -Here, __\-texture__ would normally default to "smooth", but because of the -entry added to the option database it defaults to "pebbled"\. However, the caller -has explicitly overridden the default, and so the new widget will be "greasy"\. - -__Initializing options delegated to the hull:__ A __snit::widget__'s -hull is a widget, and given that its class has been set it is expected to query -the option database for itself\. The only exception concerns options that are -delegated to it with a different name\. Consider the following code: - - option add *Mywidget.borderWidth 5 - option add *Mywidget.relief sunken - option add *Mywidget.hullbackground red - option add *Mywidget.background green - - snit::widget mywidget { - delegate option -borderwidth to hull - delegate option -hullbackground to hull as -background - delegate option * to hull - # ... - } - - mywidget .mywidget - - set A [.mywidget cget -relief] - set B [.mywidget cget -hullbackground] - set C [.mywidget cget -background] - set D [.mywidget cget -borderwidth] - -The question is, what are the values of variables A, B, C and D? - -The value of A is "sunken"\. The hull is a Tk frame that has been given the -widget class "Mywidget"; it will automatically query the option database and -pick up this value\. Since the __\-relief__ option is implicitly delegated to -the hull, Snit takes no action\. - -The value of B is "red"\. The hull will automatically pick up the value "green" -for its __\-background__ option, just as it picked up the __\-relief__ -value\. However, Snit knows that __\-hullbackground__ is mapped to the hull's -__\-background__ option; hence, it queries the option database for -__\-hullbackground__ and gets "red" and updates the hull accordingly\. - -The value of C is also "red", because __\-background__ is implicitly -delegated to the hull; thus, retrieving it is the same as retrieving -__\-hullbackground__\. Note that this case is unusual; in practice, -__\-background__ would probably be explicitly delegated to some other -component\. - -The value of D is "5", but not for the reason you think\. Note that as it is -defined above, the resource name for __\-borderwidth__ defaults to -"borderwidth", whereas the option database entry is "borderWidth"\. As with -__\-relief__, the hull picks up its own __\-borderwidth__ option before -Snit does anything\. Because the option is delegated under its own name, Snit -assumes that the correct thing has happened, and doesn't worry about it any -further\. - -For __snit::widgetadaptor__s, the case is somewhat altered\. Widget adaptors -retain the widget class of their hull, and the hull is not created automatically -by Snit\. Instead, the __snit::widgetadaptor__ must call __installhull__ -in its constructor\. The normal way to do this is as follows: - - snit::widgetadaptor mywidget { - # ... - constructor {args} { - # ... - installhull using text -foreground white - # - } - #... - } - -In this case, the __installhull__ command will create the hull using a -command like this: - - set hull [text $win -foreground white] - -The hull is a __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget, so its -widget class is "Text"\. Just as with __snit::widget__ hulls, Snit assumes -that it will pick up all of its normal option values automatically; options -delegated from a different name are initialized from the option database in the -same way\. - -__Initializing options delegated to other components:__ Non\-hull components -are matched against the option database in two ways\. First, a component widget -remains a widget still, and therefore is initialized from the option database in -the usual way\. Second, the option database is queried for all options delegated -to the component, and the component is initialized accordingly\-\-provided that -the __install__ command is used to create it\. - -Before option database support was added to Snit, the usual way to create a -component was to simply create it in the constructor and assign its command name -to the component variable: - - snit::widget mywidget { - delegate option -background to myComp - - constructor {args} { - set myComp [text $win.text -foreground black] - } - } - -The drawback of this method is that Snit has no opportunity to initialize the -component properly\. Hence, the following approach is now used: - - snit::widget mywidget { - delegate option -background to myComp - - constructor {args} { - install myComp using text $win.text -foreground black - } - } - -The __install__ command does the following: - - - Builds a list of the options explicitly included in the __install__ - command \-\- in this case, __\-foreground__\. - - - Queries the option database for all options delegated explicitly to the - named component\. - - - Creates the component using the specified command, after inserting into it a - list of options and values read from the option database\. Thus, the - explicitly included options \(__\-foreground__\) will override anything - read from the option database\. - - - If the widget definition implicitly delegated options to the component using - __delegate option \*__, then Snit calls the newly created component's - __configure__ method to receive a list of all of the component's - options\. From this Snit builds a list of options implicitly delegated to the - component that were not explicitly included in the __install__ command\. - For all such options, Snit queries the option database and configures the - component accordingly\. - -__Non\-widget components:__ The option database is never queried for -__snit::type__s, since it can only be queried given a Tk widget name\. -However, __snit::widget__s can have non\-widget components\. And if options -are delegated to those components, and if the __install__ command is used to -install those components, then they will be initialized from the option database -just as widget components are\. - -## Macros and Meta\-programming - -The __snit::macro__ command enables a certain amount of meta\-programming -with Snit classes\. For example, suppose you like to define properties: instance -variables that have set/get methods\. Your code might look like this: - - snit::type dog { - variable mood happy - - method getmood {} { - return $mood - } - - method setmood {newmood} { - set mood $newmood - } - } - -That's nine lines of text per property\. Or, you could define the following -__snit::macro__: - - snit::macro property {name initValue} { - variable $name $initValue - - method get$name {} "return $name" - - method set$name {value} "set $name \$value" - } - -Note that a __snit::macro__ is just a normal Tcl proc defined in the slave -interpreter used to compile type and widget definitions; as a result, it has -access to all the commands used to define types and widgets\. - -Given this new macro, you can define a property in one line of code: - - snit::type dog { - property mood happy - } - -Within a macro, the commands __variable__ and -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ refer to the Snit type\-definition -commands, not the standard Tcl commands\. To get the standard Tcl commands, use -__\_variable__ and __\_proc__\. - -Because a single slave interpreter is used for compiling all Snit types and -widgets in the application, there's the possibility of macro name collisions\. If -you're writing a reuseable package using Snit, and you use some -__snit::macro__s, define them in your package namespace: - - snit::macro mypkg::property {name initValue} { ... } - - snit::type dog { - mypkg::property mood happy - } - -This leaves the global namespace open for application authors\. - -## Validation Types - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__ is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - snit::integer validate 5 ;# Does nothing - snit::integer validate 5.0 ;# Throws an error (not an integer!) - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error\. - -Snit defines a family of validation types, all of which are implemented as -__snit::type__'s\. They can be used as is; in addition, their instances serve -as parameterized subtypes\. For example, a probability is a number between 0\.0 -and 1\.0 inclusive: - - snit::double probability -min 0.0 -max 1.0 - -The example above creates an instance of __snit::double__\-\-a validation -subtype\-\-called __probability__, which can be used to validate probability -values: - - probability validate 0.5 ;# Does nothing - probability validate 7.9 ;# Throws an error - -Validation subtypes can be defined explicitly, as in the above example; when a -locally\-defined option's __\-type__ is specified, they may also be created on -the fly: - - snit::enum ::dog::breed -values {mutt retriever sheepdog} - - snit::type dog { - # Define subtypes on the fly... - option -breed -type { - snit::enum -values {mutt retriever sheepdog} - } - - # Or use predefined subtypes... - option -breed -type ::dog::breed - } - -Any object that has a __validate__ method with the semantics described above -can be used as a validation type; see [Defining Validation -Types](#subsection12) for information on how to define new ones\. - -Snit defines the following validation types: - - - __snit::boolean__ __validate__ ?*value*? - - - __snit::boolean__ *name* - - Validates Tcl boolean values: 1, 0, __on__, __off__, __yes__, - __no__, __true__, __false__\. It's possible to define - subtypes\-\-that is, instances\-\-of __snit::boolean__, but as it has no - options there's no reason to do so\. - - - __snit::double__ __validate__ ?*value*? - - - __snit::double__ *name* ?*option* *value*\.\.\.? - - Validates floating\-point values\. Subtypes may be created with the following - options: - - * __\-min__ *min* - - Specifies a floating\-point minimum bound; a value is invalid if it is - strictly less than *min*\. - - * __\-max__ *max* - - Specifies a floating\-point maximum bound; a value is invalid if it is - strictly greater than *max*\. - - - __snit::enum__ __validate__ ?*value*? - - - __snit::enum__ *name* ?*option* *value*\.\.\.? - - Validates that a value comes from an enumerated list\. The base type is of - little use by itself, as only subtypes actually have an enumerated list to - validate against\. Subtypes may be created with the following options: - - * __\-values__ *list* - - Specifies a list of valid values\. A value is valid if and only if it's - included in the list\. - - - __snit::fpixels__ __validate__ ?*value*? - - - __snit::fpixels__ *name* ?*option* *value*\.\.\.? - - *Tk programs only\.* Validates screen distances, in any of the forms - accepted by __winfo fpixels__\. Subtypes may be created with the - following options: - - * __\-min__ *min* - - Specifies a minimum bound; a value is invalid if it is strictly less - than *min*\. The bound may be expressed in any of the forms accepted by - __winfo fpixels__\. - - * __\-max__ *max* - - Specifies a maximum bound; a value is invalid if it is strictly greater - than *max*\. The bound may be expressed in any of the forms accepted by - __winfo fpixels__\. - - - __snit::integer__ __validate__ ?*value*? - - - __snit::integer__ *name* ?*option* *value*\.\.\.? - - Validates integer values\. Subtypes may be created with the following - options: - - * __\-min__ *min* - - Specifies an integer minimum bound; a value is invalid if it is strictly - less than *min*\. - - * __\-max__ *max* - - Specifies an integer maximum bound; a value is invalid if it is strictly - greater than *max*\. - - - __snit::listtype__ __validate__ ?*value*? - - - __snit::listtype__ *name* ?*option* *value*\.\.\.? - - Validates Tcl lists\. Subtypes may be created with the following options: - - * __\-minlen__ *min* - - Specifies a minimum list length; the value is invalid if it has fewer - than *min* elements\. Defaults to 0\. - - * __\-maxlen__ *max* - - Specifies a maximum list length; the value is invalid if it more than - *max* elements\. - - * __\-type__ *type* - - Specifies the type of the list elements; *type* must be the name of a - validation type or subtype\. In the following example, the value of - __\-numbers__ must be a list of integers\. - - option -numbers -type {snit::listtype -type snit::integer} - - Note that this option doesn't support defining new validation subtypes - on the fly; that is, the following code will not work \(yet, anyway\): - - option -numbers -type { - snit::listtype -type {snit::integer -min 5} - } - - Instead, define the subtype explicitly: - - snit::integer gt4 -min 5 - - snit::type mytype { - option -numbers -type {snit::listtype -type gt4} - } - - - __snit::pixels__ __validate__ ?*value*? - - - __snit::pixels__ *name* ?*option* *value*\.\.\.? - - *Tk programs only\.* Validates screen distances, in any of the forms - accepted by __winfo pixels__\. Subtypes may be created with the following - options: - - * __\-min__ *min* - - Specifies a minimum bound; a value is invalid if it is strictly less - than *min*\. The bound may be expressed in any of the forms accepted by - __winfo pixels__\. - - * __\-max__ *max* - - Specifies a maximum bound; a value is invalid if it is strictly greater - than *max*\. The bound may be expressed in any of the forms accepted by - __winfo pixels__\. - - - __snit::stringtype__ __validate__ ?*value*? - - - __snit::stringtype__ *name* ?*option* *value*\.\.\.? - - Validates Tcl strings\. The base type is of little use by itself, since very - Tcl value is also a valid string\. Subtypes may be created with the following - options: - - * __\-minlen__ *min* - - Specifies a minimum string length; the value is invalid if it has fewer - than *min* characters\. Defaults to 0\. - - * __\-maxlen__ *max* - - Specifies a maximum string length; the value is invalid if it has more - than *max* characters\. - - * __\-glob__ *pattern* - - Specifies a __string match__ pattern; the value is invalid if it - doesn't match the pattern\. - - * __\-regexp__ *regexp* - - Specifies a regular expression; the value is invalid if it doesn't match - the regular expression\. - - * __\-nocase__ *flag* - - By default, both __\-glob__ and __\-regexp__ matches are - case\-sensitive\. If __\-nocase__ is set to true, then both - __\-glob__ and __\-regexp__ matches are case\-insensitive\. - - - __snit::window__ __validate__ ?*value*? - - - __snit::window__ *name* - - *Tk programs only\.* Validates Tk window names\. The value must cause - __winfo exists__ to return true; otherwise, the value is invalid\. It's - possible to define subtypes\-\-that is, instances\-\-of __snit::window__, - but as it has no options at present there's no reason to do so\. - -## Defining Validation Types - -There are three ways to define a new validation type: as a subtype of one of -Snit's validation types, as a validation type command, and as a full\-fledged -validation type similar to those provided by Snit\. Defining subtypes of Snit's -validation types is described above, under [Validation -Types](#subsection11)\. - -The next simplest way to create a new validation type is as a validation type -command\. A validation type is simply an object that has a __validate__ -method; the __validate__ method must take one argument, a value, return the -value if it is valid, and throw an error with __\-errorcode__ INVALID if the -value is invalid\. This can be done with a simple -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__\. For example, the -__snit::boolean__ validate type could have been implemented like this: - - proc ::snit::boolean {"validate" value} { - if {![string is boolean -strict $value]} { - return -code error -errorcode INVALID "invalid boolean \"$value\", should be one of: 1, 0, ..." - } - - return $value - } - -A validation type defined in this way cannot be subtyped, of course; but for -many applications this will be sufficient\. - -Finally, one can define a full\-fledged, subtype\-able validation type as a -__snit::type__\. Here's a skeleton to get you started: - - snit::type myinteger { - # First, define any options you'd like to use to define - # subtypes. Give them defaults such that they won't take - # effect if they aren't used, and marked them "read-only". - # After all, you shouldn't be changing their values after - # a subtype is defined. - # - # For example: - - option -min -default "" -readonly 1 - option -max -default "" -readonly 1 - - # Next, define a "validate" type method which should do the - # validation in the basic case. This will allow the - # type command to be used as a validation type. - - typemethod validate {value} { - if {![string is integer -strict $value]} { - return -code error -errorcode INVALID "invalid value \"$value\", expected integer" - } - - return $value - } - - # Next, the constructor should validate the subtype options, - # if any. Since they are all readonly, we don't need to worry - # about validating the options on change. - - constructor {args} { - # FIRST, get the options - $self configurelist $args - - # NEXT, validate them. - - # I'll leave this to your imagination. - } - - # Next, define a "validate" instance method; its job is to - # validate values for subtypes. - - method validate {value} { - # First, call the type method to do the basic validation. - $type validate $value - - # Now we know it's a valid integer. - - if {("" != $options(-min) && $value < $options(-min)) || - ("" != $options(-max) && $value > $options(-max))} { - # It's out of range; format a detailed message about - # the error, and throw it. - - set msg "...." - - return -code error -errorcode INVALID $msg - } - - # Otherwise, if it's valid just return it. - return $valid - } - } - -And now you have a type that can be subtyped\. - -The file "validate\.tcl" in the Snit distribution defines all of Snit's -validation types; you can find the complete implementation for -__snit::integer__ and the other types there, to use as examples for your own -types\. - -# CAVEATS - -If you have problems, find bugs, or new ideas you are hereby cordially invited -to submit a report of your problem, bug, or idea as explained in the section -[Bugs, Ideas, Feedback](#section8) below\. - -Additionally, you might wish to join the Snit mailing list; see -[http://www\.wjduquette\.com/snit](http://www\.wjduquette\.com/snit) for -details\. - -One particular area to watch is using __snit::widgetadaptor__ to adapt -megawidgets created by other megawidget packages; correct widget destruction -depends on the order of the bindings\. The wisest course is simply not -to do this\. - -# KNOWN BUGS - - - Error stack traces returned by Snit 1\.x are extremely ugly and typically - contain far too much information about Snit internals\. The error messages - are much improved in Snit 2\.2\. - - - Also see the Project Trackers as explained in the section [Bugs, Ideas, - Feedback](#section8) below\. - -# HISTORY - -During the course of developing Notebook \(See -[http://www\.wjduquette\.com/notebook](http://www\.wjduquette\.com/notebook)\), -my Tcl\-based personal notebook application, I found I was writing it as a -collection of objects\. I wasn't using any particular object\-oriented framework; -I was just writing objects in pure Tcl following the guidelines in my Guide to -Object Commands \(see -[http://www\.wjduquette\.com/tcl/objects\.html](http://www\.wjduquette\.com/tcl/objects\.html)\), -along with a few other tricks I'd picked up since\. And though it was working -well, it quickly became tiresome because of the amount of boilerplate code -associated with each new object type\. - -So that was one thing\-\-tedium is a powerful motivator\. But the other thing I -noticed is that I wasn't using inheritance at all, and I wasn't missing it\. -Instead, I was using delegation: objects that created other objects and -delegated methods to them\. - -And I said to myself, "This is getting tedious\.\.\.there has got to be a better -way\." And one afternoon, on a whim, I started working on Snit, an object system -that works the way Tcl works\. Snit doesn't support inheritance, but it's great -at delegation, and it makes creating megawidgets easy\. - -If you have any comments or suggestions \(or bug reports\!\) don't hesitate to send -me e\-mail at [will@wjduquette\.com](will@wjduquette\.com)\. In addition, -there's a Snit mailing list; you can find out more about it at the Snit home -page \(see [http://www\.wjduquette\.com/snit](http://www\.wjduquette\.com/snit)\)\. - -# CREDITS - -Snit has been designed and implemented from the very beginning by William H\. -Duquette\. However, much credit belongs to the following people for using Snit -and providing me with valuable feedback: Rolf Ade, Colin McCormack, Jose -Nazario, Jeff Godfrey, Maurice Diamanti, Egon Pasztor, David S\. Cargo, Tom -Krehbiel, Michael Cleverly, Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, -Brian Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, and Anton Kovalenko\. -If I've forgotten anyone, my apologies; let me know and I'll add your name to -the list\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *snit* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[BWidget](\.\./\.\./\.\./\.\./index\.md\#bwidget), [C\+\+](\.\./\.\./\.\./\.\./index\.md\#c\_), -[Incr Tcl](\.\./\.\./\.\./\.\./index\.md\#incr\_tcl), -[Snit](\.\./\.\./\.\./\.\./index\.md\#snit), -[adaptors](\.\./\.\./\.\./\.\./index\.md\#adaptors), -[class](\.\./\.\./\.\./\.\./index\.md\#class), [mega -widget](\.\./\.\./\.\./\.\./index\.md\#mega\_widget), -[object](\.\./\.\./\.\./\.\./index\.md\#object), [object -oriented](\.\./\.\./\.\./\.\./index\.md\#object\_oriented), -[type](\.\./\.\./\.\./\.\./index\.md\#type), -[widget](\.\./\.\./\.\./\.\./index\.md\#widget), [widget -adaptors](\.\./\.\./\.\./\.\./index\.md\#widget\_adaptors) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2003\-2009, by William H\. Duquette DELETED embedded/md/tcllib/files/modules/snit/snitfaq.md Index: embedded/md/tcllib/files/modules/snit/snitfaq.md ================================================================== --- embedded/md/tcllib/files/modules/snit/snitfaq.md +++ embedded/md/tcllib/files/modules/snit/snitfaq.md @@ -1,3758 +0,0 @@ - -[//000000001]: # (snitfaq \- Snit's Not Incr Tcl, OO system) -[//000000002]: # (Generated from file 'snitfaq\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2006, by William H\. Duquette) -[//000000004]: # (snitfaq\(n\) 2\.2 tcllib "Snit's Not Incr Tcl, OO system") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -snitfaq \- Snit Frequently Asked Questions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [What is this document?](#subsection1) - - - [What is Snit?](#subsection2) - - - [What version of Tcl does Snit require?](#subsection3) - - - [Where can I download Snit?](#subsection4) - - - [What are Snit's goals?](#subsection5) - - - [How is Snit different from other OO frameworks?](#subsection6) - - - [What can I do with Snit?](#subsection7) - - - [SNIT VERSIONS](#section3) - - - [Which version of Snit should I use?](#subsection8) - - - [How do I select the version of Snit I want to use?](#subsection9) - - - [How are Snit 1\.3 and Snit 2\.2 incompatible?](#subsection10) - - - [Are there other differences between Snit 1\.x and Snit - 2\.2?](#subsection11) - - - [OBJECTS](#section4) - - - [What is an object?](#subsection12) - - - [What is an abstract data type?](#subsection13) - - - [What kinds of abstract data types does Snit - provide?](#subsection14) - - - [What is a snit::type?](#subsection15) - - - [What is a snit::widget?, the short story](#subsection16) - - - [What is a snit::widgetadaptor?, the short story](#subsection17) - - - [How do I create an instance of a snit::type?](#subsection18) - - - [How do I refer to an object indirectly?](#subsection19) - - - [How can I generate the object name automatically?](#subsection20) - - - [Can types be renamed?](#subsection21) - - - [Can objects be renamed?](#subsection22) - - - [How do I destroy a Snit object?](#subsection23) - - - [INSTANCE METHODS](#section5) - - - [What is an instance method?](#subsection24) - - - [How do I define an instance method?](#subsection25) - - - [How does a client call an instance method?](#subsection26) - - - [How does an instance method call another instance - method?](#subsection27) - - - [Are there any limitations on instance method - names?](#subsection28) - - - [What is a hierarchical method?](#subsection29) - - - [How do I define a hierarchical method?](#subsection30) - - - [How do I call hierarchical methods?](#subsection31) - - - [How do I make an instance method private?](#subsection32) - - - [Are there any limitations on instance method - arguments?](#subsection33) - - - [What implicit arguments are passed to each instance - method?](#subsection34) - - - [What is $type?](#subsection35) - - - [What is $self?](#subsection36) - - - [What is $selfns?](#subsection37) - - - [What is $win?](#subsection38) - - - [How do I pass an instance method as a callback?](#subsection39) - - - [How do I delegate instance methods to a component?](#subsection40) - - - [INSTANCE VARIABLES](#section6) - - - [What is an instance variable?](#subsection41) - - - [How is a scalar instance variable defined?](#subsection42) - - - [How is an array instance variable defined?](#subsection43) - - - [What happens if I don't initialize an instance - variable?](#subsection44) - - - [Are there any limitations on instance variable - names?](#subsection45) - - - [Do I need to declare my instance variables in my - methods?](#subsection46) - - - [How do I pass an instance variable's name to another - object?](#subsection47) - - - [How do I make an instance variable public?](#subsection48) - - - [OPTIONS](#section7) - - - [What is an option?](#subsection49) - - - [How do I define an option?](#subsection50) - - - [How can a client set options at object creation?](#subsection51) - - - [How can a client retrieve an option's value?](#subsection52) - - - [How can a client set options after object - creation?](#subsection53) - - - [How should an instance method access an option - value?](#subsection54) - - - [How can I make an option read\-only?](#subsection55) - - - [How can I catch accesses to an option's value?](#subsection56) - - - [What is a \-cgetmethod?](#subsection57) - - - [How can I catch changes to an option's value?](#subsection58) - - - [What is a \-configuremethod?](#subsection59) - - - [How can I validate an option's value?](#subsection60) - - - [What is a \-validatemethod?](#subsection61) - - - [TYPE VARIABLES](#section8) - - - [What is a type variable?](#subsection62) - - - [How is a scalar type variable defined?](#subsection63) - - - [How is an array\-valued type variable defined?](#subsection64) - - - [What happens if I don't initialize a type - variable?](#subsection65) - - - [Are there any limitations on type variable names?](#subsection66) - - - [Do I need to declare my type variables in my - methods?](#subsection67) - - - [How do I pass a type variable's name to another - object?](#subsection68) - - - [How do I make a type variable public?](#subsection69) - - - [TYPE METHODS](#section9) - - - [What is a type method?](#subsection70) - - - [How do I define a type method?](#subsection71) - - - [How does a client call a type method?](#subsection72) - - - [Are there any limitations on type method names?](#subsection73) - - - [How do I make a type method private?](#subsection74) - - - [Are there any limitations on type method - arguments?](#subsection75) - - - [How does an instance or type method call a type - method?](#subsection76) - - - [How do I pass a type method as a callback?](#subsection77) - - - [Can type methods be hierarchical?](#subsection78) - - - [PROCS](#section10) - - - [What is a proc?](#subsection79) - - - [How do I define a proc?](#subsection80) - - - [Are there any limitations on proc names?](#subsection81) - - - [How does a method call a proc?](#subsection82) - - - [How can I pass a proc to another object as a - callback?](#subsection83) - - - [TYPE CONSTRUCTORS](#section11) - - - [What is a type constructor?](#subsection84) - - - [How do I define a type constructor?](#subsection85) - - - [CONSTRUCTORS](#section12) - - - [What is a constructor?](#subsection86) - - - [How do I define a constructor?](#subsection87) - - - [What does the default constructor do?](#subsection88) - - - [Can I choose a different set of arguments for the - constructor?](#subsection89) - - - [Are there any limitations on constructor - arguments?](#subsection90) - - - [Is there anything special about writing the - constructor?](#subsection91) - - - [DESTRUCTORS](#section13) - - - [What is a destructor?](#subsection92) - - - [How do I define a destructor?](#subsection93) - - - [Are there any limitations on destructor arguments?](#subsection94) - - - [What implicit arguments are passed to the - destructor?](#subsection95) - - - [Must components be destroyed explicitly?](#subsection96) - - - [Is there any special about writing a destructor?](#subsection97) - - - [COMPONENTS](#section14) - - - [What is a component?](#subsection98) - - - [How do I declare a component?](#subsection99) - - - [How is a component named?](#subsection100) - - - [Are there any limitations on component names?](#subsection101) - - - [What is an owned component?](#subsection102) - - - [What does the install command do?](#subsection103) - - - [Must owned components be created in the - constructor?](#subsection104) - - - [Are there any limitations on component object - names?](#subsection105) - - - [Must I destroy the components I own?](#subsection106) - - - [Can I expose a component's object command as part of my - interface?](#subsection107) - - - [How do I expose a component's object command?](#subsection108) - - - [TYPE COMPONENTS](#section15) - - - [What is a type component?](#subsection109) - - - [How do I declare a type component?](#subsection110) - - - [How do I install a type component?](#subsection111) - - - [Are there any limitations on type component - names?](#subsection112) - - - [DELEGATION](#section16) - - - [What is delegation?](#subsection113) - - - [How can I delegate a method to a component - object?](#subsection114) - - - [Can I delegate to a method with a different name?](#subsection115) - - - [Can I delegate to a method with additional - arguments?](#subsection116) - - - [Can I delegate a method to something other than an - object?](#subsection117) - - - [How can I delegate a method to a type component - object?](#subsection118) - - - [How can I delegate a type method to a type component - object?](#subsection119) - - - [How can I delegate an option to a component - object?](#subsection120) - - - [Can I delegate to an option with a different - name?](#subsection121) - - - [How can I delegate any unrecognized method or option to a component - object?](#subsection122) - - - [How can I delegate all but certain methods or options to a - component?](#subsection123) - - - [Can a hierarchical method be delegated?](#subsection124) - - - [WIDGETS](#section17) - - - [What is a snit::widget?](#subsection125) - - - [How do I define a snit::widget?](#subsection126) - - - [How do snit::widgets differ from snit::types?](#subsection127) - - - [What is a hull component?](#subsection128) - - - [How can I set the hull type for a snit::widget?](#subsection129) - - - [How should I name widgets which are components of a - snit::widget?](#subsection130) - - - [WIDGET ADAPTORS](#section18) - - - [What is a snit::widgetadaptor?](#subsection131) - - - [How do I define a snit::widgetadaptor?](#subsection132) - - - [Can I adapt a widget created elsewhere in the - program?](#subsection133) - - - [Can I adapt another megawidget?](#subsection134) - - - [THE TK OPTION DATABASE](#section19) - - - [What is the Tk option database?](#subsection135) - - - [Do snit::types use the Tk option database?](#subsection136) - - - [What is my snit::widget's widget class?](#subsection137) - - - [What is my snit::widgetadaptor's widget class?](#subsection138) - - - [What are option resource and class names?](#subsection139) - - - [What are the resource and class names for my megawidget's - options?](#subsection140) - - - [How does Snit initialize my megawidget's locally\-defined - options?](#subsection141) - - - [How does Snit initialize delegated options?](#subsection142) - - - [How does Snit initialize options delegated to the - hull?](#subsection143) - - - [How does Snit initialize options delegated to other - components?](#subsection144) - - - [What happens if I install a non\-widget as a component of - widget?](#subsection145) - - - [ENSEMBLE COMMANDS](#section20) - - - [What is an ensemble command?](#subsection146) - - - [How can I create an ensemble command using Snit?](#subsection147) - - - [How can I create an ensemble command using an instance of a - snit::type?](#subsection148) - - - [How can I create an ensemble command using a - snit::type?](#subsection149) - - - [PRAGMAS](#section21) - - - [What is a pragma?](#subsection150) - - - [How do I set a pragma?](#subsection151) - - - [How can I get rid of the "info" type method?](#subsection152) - - - [How can I get rid of the "destroy" type method?](#subsection153) - - - [How can I get rid of the "create" type method?](#subsection154) - - - [How can I get rid of type methods altogether?](#subsection155) - - - [Why can't I create an object that replaces an old object with the same - name?](#subsection156) - - - [How can I make my simple type run faster?](#subsection157) - - - [MACROS](#section22) - - - [What is a macro?](#subsection158) - - - [What are macros good for?](#subsection159) - - - [How do I do conditional compilation?](#subsection160) - - - [How do I define new type definition syntax?](#subsection161) - - - [Are there are restrictions on macro names?](#subsection162) - - - [Bugs, Ideas, Feedback](#section23) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -# OVERVIEW - -## What is this document? - -This is an atypical FAQ list, in that few of the questions are frequently asked\. -Rather, these are the questions I think a newcomer to Snit should be asking\. -This file is not a complete reference to Snit, however; that information is in -the __[snit](snit\.md)__ man page\. - -## What is Snit? - -Snit is a framework for defining abstract data types and megawidgets in pure -Tcl\. The name "Snit" stands for "Snit's Not Incr Tcl", signifying that Snit -takes a different approach to defining objects than does Incr Tcl, the best -known object framework for Tcl\. Had I realized that Snit would become at all -popular, I'd probably have chosen something else\. - -The primary purpose of Snit is to be *object glue*\-\-to help you compose -diverse objects from diverse sources into types and megawidgets with clean, -convenient interfaces so that you can more easily build your application\. - -Snit isn't about theoretical purity or minimalist design; it's about being able -to do powerful things easily and consistently without having to think about -them\-\-so that you can concentrate on building your application\. - -Snit isn't about implementing thousands of nearly identical carefully\-specified -lightweight thingamajigs\-\-not as individual Snit objects\. Traditional Tcl -methods will be much faster, and not much more complicated\. But Snit *is* -about implementing a clean interface to manage a collection of thousands of -nearly identical carefully\-specified lightweight thingamajigs \(e\.g\., think of -the text widget and text tags, or the canvas widget and canvas objects\)\. Snit -lets you hide the details of just how those thingamajigs are stored\-\-so that you -can ignore it, and concentrate on building your application\. - -Snit isn't a way of life, a silver bullet, or the Fountain of Youth\. It's just a -way of managing complexity\-\-and of managing some of the complexity of managing -complexity\-\-so that you can concentrate on building your application\. - -## What version of Tcl does Snit require? - -Snit 1\.3 requires Tcl 8\.3 or later; Snit 2\.2 requires Tcl 8\.5 or later\. See -[SNIT VERSIONS](#section3) for the differences between Snit 1\.3 and Snit -2\.2\. - -## Where can I download Snit? - -Snit is part of Tcllib, the standard Tcl library, so you might already have it\. -It's also available at the Snit Home Page, -[http://www\.wjduquette\.com/snit](http://www\.wjduquette\.com/snit)\. - -## What are Snit's goals? - - - A Snit object should be at least as efficient as a hand\-coded Tcl object - \(see - [http://www\.wjduquette\.com/tcl/objects\.html](http://www\.wjduquette\.com/tcl/objects\.html)\)\. - - - The fact that Snit was used in an object's implementation should be - transparent \(and irrelevant\) to clients of that object\. - - - Snit should be able to encapsulate objects from other sources, particularly - Tk widgets\. - - - Snit megawidgets should be \(to the extent possible\) indistinguishable in - interface from Tk widgets\. - - - Snit should be Tclish\-\-that is, rather than trying to emulate C\+\+, - Smalltalk, or anything else, it should try to emulate Tcl itself\. - - - It should have a simple, easy\-to\-use, easy\-to\-remember syntax\. - -## How is Snit different from other OO frameworks? - -Snit is unique among Tcl object systems in that it is based not on inheritance -but on delegation\. Object systems based on inheritance only allow you to inherit -from classes defined using the same system, and that's a shame\. In Tcl, an -object is anything that acts like an object; it shouldn't matter how the object -was implemented\. I designed Snit to help me build applications out of the -materials at hand; thus, Snit is designed to be able to incorporate and build on -any object, whether it's a hand\-coded object, a Tk widget, an Incr Tcl object, a -BWidget or almost anything else\. - -Note that you can achieve the effect of inheritance using -[COMPONENTS](#section14) and [DELEGATION](#section16)\-\-and you can -inherit from anything that looks like a Tcl object\. - -## What can I do with Snit? - -Using Snit, a programmer can: - - - Create abstract data types and Tk megawidgets\. - - - Define instance variables, type variables, and Tk\-style options\. - - - Define constructors, destructors, instance methods, type methods, procs\. - - - Assemble a type out of component types\. Instance methods and options can be - delegated to the component types automatically\. - -# SNIT VERSIONS - -## Which version of Snit should I use? - -The current Snit distribution includes two versions, Snit 1\.3 and Snit 2\.2\. The -reason that both are included is that Snit 2\.2 takes advantage of a number of -new features of Tcl 8\.5 to improve run\-time efficiency; as a side\-effect, the -ugliness of Snit's error messages and stack traces has been reduced -considerably\. The cost of using Snit 2\.2, of course, is that you must target Tcl -8\.5\. - -Snit 1\.3, on the other hand, lacks Snit 2\.2's optimizations, but requires only -Tcl 8\.3 and later\. - -In short, if you're targetting Tcl 8\.3 or 8\.4 you should use Snit 1\.3\. If you -can afford to target Tcl 8\.5, you should definitely use Snit 2\.2\. If you will be -targetting both, you can use Snit 1\.3 exclusively, or \(if your code is -unaffected by the minor incompatibilities between the two versions\) you can use -Snit 1\.3 for Tcl 8\.4 and Snit 2\.2 for Tcl 8\.5\. - -## How do I select the version of Snit I want to use? - -To always use Snit 1\.3 \(or a later version of Snit 1\.x\), invoke Snit as follows: - - package require snit 1.3 - -To always use Snit 2\.2 \(or a later version of Snit 2\.x\), say this instead: - - package require snit 2.2 - -Note that if you request Snit 2\.2 explicitly, your application will halt with -Tcl 8\.4, since Snit 2\.2 is unavailable for Tcl 8\.4\. - -If you wish your application to always use the latest available version of Snit, -don't specify a version number: - - package require snit - -Tcl will find and load the latest version that's available relative to the -version of Tcl being used\. In this case, be careful to avoid using any -incompatible features\. - -## How are Snit 1\.3 and Snit 2\.2 incompatible? - -To the extent possible, Snit 2\.2 is intended to be a drop\-in replacement for -Snit 1\.3\. Unfortunately, some incompatibilities were inevitable because Snit 2\.2 -uses Tcl 8\.5's new __namespace ensemble__ mechanism to implement subcommand -dispatch\. This approach is much faster than the mechanism used in Snit 1\.3, and -also results in much better error messages; however, it also places new -constraints on the implementation\. - -There are four specific incompatibilities between Snit 1\.3 and Snit 2\.2\. - - - Snit 1\.3 supports implicit naming of objects\. Suppose you define a new - __snit::type__ called __dog__\. You can create instances of - __dog__ in three ways: - - dog spot ;# Explicit naming - set obj1 [dog %AUTO%] ;# Automatic naming - set obj2 [dog] ;# Implicit naming - - In Snit 2\.2, type commands are defined using the __namespace ensemble__ - mechanism; and __namespace ensemble__ doesn't allow an ensemble command - to be called without a subcommand\. In short, using __namespace - ensemble__ there's no way to support implicit naming\. - - All is not lost, however\. If the type has no type methods, then the type - command is a simple command rather than an ensemble, and __namespace - ensemble__ is not used\. In this case, implicit naming is still possible\. - - In short, you can have implicit naming if you're willing to do without type - methods \(including the standard type methods, like __$type info__\)\. To - do so, use the __\-hastypemethods__ pragma: - - pragma -hastypemethods 0 - - - Hierarchical methods and type methods are implemented differently in Snit - 2\.2\. - - A hierarchical method is an instance method which has subcommands; these - subcommands are themselves methods\. The Tk text widget's __tag__ command - and its subcommands are examples of hierarchical methods\. You can implement - such subcommands in Snit simply by including multiple words in the method - names: - - method {tag configure} {tag args} { ... } - - method {tag cget} {tag option} {...} - - Here we've implicitly defined a __tag__ method which has two - subcommands, __configure__ and __cget__\. - - In Snit 1\.3, hierarchical methods could be called in two ways: - - $obj tag cget -myoption ;# The good way - $obj {tag cget} -myoption ;# The weird way - - In the second call, we see that a hierarchical method or type method is - simply one whose name contains multiple words\. - - In Snit 2\.2 this is no longer the case, and the "weird" way of calling - hierarchical methods and type methods no longer works\. - - - The third incompatibility derives from the second\. In Snit 1\.3, hierarchical - methods were also simply methods whose name contains multiple words\. As a - result, __$obj info methods__ returned the full names of all - hierarchical methods\. In the example above, the list returned by __$obj - info methods__ would include __tag configure__ and __tag cget__ - but not __tag__, since __tag__ is defined only implicitly\. - - In Snit 2\.2, hierarchical methods and type methods are no longer simply ones - whose name contains multiple words; in the above example, the list returned - by __$obj info methods__ would include __tag__ but not __tag - configure__ or __tag cget__\. - - - The fourth incompatibility is due to a new feature\. Snit 2\.2 uses the new - __namespace path__ command so that a type's code can call any command - defined in the type's parent namespace without qualification or importation\. - For example, suppose you have a package called __mypackage__ which - defines a number of commands including a type, __::mypackage::mytype__\. - Thanks to __namespace path__, the type's code can call any of the other - commands defined in __::mypackage::__\. - - This is extremely convenient\. However, it also means that commands defined - in the parent namespace, __::mypackage::__ can block the type's access - to identically named commands in the global namespace\. This can lead to - bugs\. For example, Tcllib includes a type called __::tie::std::file__\. - This type's code calls the standard - __[file](\.\./\.\./\.\./\.\./index\.md\#file)__ command\. When run with Snit - 2\.2, the code broke\-\- the type's command, __::tie::std::file__, is - itself a command in the type's parent namespace, and so instead of calling - the standard __[file](\.\./\.\./\.\./\.\./index\.md\#file)__ command, the type - found itself calling itself\. - -## Are there other differences between Snit 1\.x and Snit 2\.2? - -Yes\. - - - Method dispatch is considerably faster\. - - - Many error messages and stack traces are cleaner\. - - - The __\-simpledispatch__ pragma is obsolete, and ignored if present\. In - Snit 1\.x, __\-simpledispatch__ substitutes a faster mechanism for method - dispatch, at the cost of losing certain features\. Snit 2\.2 method dispatch - is faster still in all cases, so __\-simpledispatch__ is no longer - needed\. - - - In Snit 2\.2, a type's code \(methods, type methods, etc\.\) can call commands - from the type's parent namespace without qualifying or importing them, i\.e\., - type __::parentns::mytype__'s code can call __::parentns::someproc__ - as just __someproc__\. - - This is extremely useful when a type is defined as part of a larger package, - and shares a parent namespace with the rest of the package; it means that - the type can call other commands defined by the package without any extra - work\. - - This feature depends on the new Tcl 8\.5 __namespace path__ command, - which is why it hasn't been implemented for V1\.x\. V1\.x code can achieve - something similar by placing - - namespace import [namespace parent]::* - - in a type constructor\. This is less useful, however, as it picks up only - those commands which have already been exported by the parent namespace at - the time the type is defined\. - -# OBJECTS - -## What is an object? - -A full description of object\-oriented programming is beyond the scope of this -FAQ, obviously\. In simple terms, an object is an instance of an abstract data -type\-\-a coherent bundle of code and data\. There are many ways to represent -objects in Tcl/Tk; the best known examples are the Tk widgets\. - -A Tk widget is an object; it is represented by a Tcl command\. The object's -methods are subcommands of the Tcl command\. The object's properties are options -accessed using the __configure__ and __cget__ methods\. Snit uses the -same conventions as Tk widgets do\. - -## What is an abstract data type? - -In computer science terms, an abstract data type is a complex data structure -along with a set of operations\-\-a stack, a queue, a binary tree, etc\-\-that is to -say, in modern terms, an object\. In systems that include some form of -inheritance the word *[class](\.\./\.\./\.\./\.\./index\.md\#class)* is usually used -instead of *abstract data type*, but as Snit doesn't implement inheritance as -it's ordinarily understood the older term seems more appropriate\. Sometimes this -is called *object\-based* programming as opposed to object\-oriented -programming\. Note that you can easily create the effect of inheritance using -[COMPONENTS](#section14) and [DELEGATION](#section16)\. - -In Snit, as in Tk, a *[type](\.\./\.\./\.\./\.\./index\.md\#type)* is a command that -creates instances \-\- objects \-\- which belong to the type\. Most types define some -number of *options* which can be set at creation time, and usually can be -changed later\. - -Further, an *instance* is also a Tcl command\-\-a command that gives access to -the operations which are defined for that abstract data type\. Conventionally, -the operations are defined as subcommands of the instance command\. For example, -to insert text into a Tk text widget, you use the text widget's __insert__ -subcommand: - - # Create a text widget and insert some text in it. - text .mytext -width 80 -height 24 - .mytext insert end "Howdy!" - -In this example, __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ is the -*[type](\.\./\.\./\.\./\.\./index\.md\#type)* command and __\.mytext__ is the -*instance* command\. - -In Snit, object subcommands are generally called [INSTANCE -METHODS](#section5)\. - -## What kinds of abstract data types does Snit provide? - -Snit allows you to define three kinds of abstract data type: - - - __snit::type__ - - - __snit::widget__ - - - __snit::widgetadaptor__ - -## What is a snit::type? - -A __snit::type__ is a non\-GUI abstract data type, e\.g\., a stack or a queue\. -__snit::type__s are defined using the __snit::type__ command\. For -example, if you were designing a kennel management system for a dog breeder, -you'd need a dog type\. - - % snit::type dog { - # ... - } - ::dog - % - -This definition defines a new command \(__::dog__, in this case\) that can be -used to define dog objects\. - -An instance of a __snit::type__ can have [INSTANCE METHODS](#section5), -[INSTANCE VARIABLES](#section6), [OPTIONS](#section7), and -[COMPONENTS](#section14)\. The type itself can have [TYPE -METHODS](#section9), [TYPE VARIABLES](#section8), [TYPE -COMPONENTS](#section15), and [PROCS](#section10)\. - -## What is a snit::widget?, the short story - -A __snit::widget__ is a Tk megawidget built using Snit; it is very similar -to a __snit::type__\. See [WIDGETS](#section17)\. - -## What is a snit::widgetadaptor?, the short story - -A __snit::widgetadaptor__ uses Snit to wrap an existing widget type \(e\.g\., a -Tk label\), modifying its interface to a lesser or greater extent\. It is very -similar to a __snit::widget__\. See [WIDGET ADAPTORS](#section18)\. - -## How do I create an instance of a snit::type? - -You create an instance of a __snit::type__ by passing the new instance's -name to the type's create method\. In the following example, we create a -__dog__ object called __spot__\. - - % snit::type dog { - # .... - } - ::dog - % dog create spot - ::spot - % - -In general, the __create__ method name can be omitted so long as the -instance name doesn't conflict with any defined [TYPE METHODS](#section9)\. -\(See [TYPE COMPONENTS](#section15) for the special case in which this -doesn't work\.\) So the following example is identical to the previous example: - - % snit::type dog { - # .... - } - ::dog - % dog spot - ::spot - % - -This document generally uses the shorter form\. - -If the __dog__ type defines [OPTIONS](#section7), these can usually be -given defaults at creation time: - - % snit::type dog { - option -breed mongrel - option -color brown - - method bark {} { return "$self barks." } - } - ::dog - % dog create spot -breed dalmation -color spotted - ::spot - % spot cget -breed - dalmation - % spot cget -color - spotted - % - -Once created, the instance name now names a new Tcl command that is used to -manipulate the object\. For example, the following code makes the dog bark: - - % spot bark - ::spot barks. - % - -## How do I refer to an object indirectly? - -Some programmers prefer to save the object name in a variable, and reference it -that way\. For example, - - % snit::type dog { ... } - ::dog - % set d [dog spot -breed dalmation -color spotted] - ::spot - % $d cget -breed - dalmation - % $d bark - ::spot barks. - % - -If you prefer this style, you might prefer to have Snit generate the instance's -name automatically\. - -## How can I generate the object name automatically? - -If you'd like Snit to generate an object name for you, use the __%AUTO%__ -keyword as the requested name: - - % snit::type dog { ... } - ::dog - % set d [dog %AUTO%] - ::dog2 - % $d bark - ::dog2 barks. - % - -The __%AUTO%__ keyword can be embedded in a longer string: - - % set d [dog obj_%AUTO%] - ::obj_dog4 - % $d bark - ::obj_dog4 barks. - % - -## Can types be renamed? - -Tcl's __rename__ command renames other commands\. It's a common technique in -Tcl to modify an existing command by renaming it and defining a new command with -the original name; the new command usually calls the renamed command\. - -__snit::type__ commands, however, should never be renamed; to do so breaks -the connection between the type and its objects\. - -## Can objects be renamed? - -Tcl's __rename__ command renames other commands\. It's a common technique in -Tcl to modify an existing command by renaming it and defining a new command with -the original name; the new command usually calls the renamed command\. - -All Snit objects \(including *widgets* and *widgetadaptors*\) can be renamed, -though this flexibility has some consequences: - - - In an instance method, the implicit argument __self__ will always - contain the object's current name, so instance methods can always call other - instance methods using __$self__\. - - - If the object is renamed, however, then __$self__'s value will change\. - Therefore, don't use __$self__ for anything that will break if - __$self__ changes\. For example, don't pass a callback command to another - object like this: - - .btn configure -command [list $self ButtonPress] - - You'll get an error if __\.btn__ calls your command after your object is - renamed\. - - - Instead, your object should define its callback command like this: - - .btn configure -command [mymethod ButtonPress] - - The __mymethod__ command returns code that will call the desired method - safely; the caller of the callback can add additional arguments to the end - of the command as usual\. - - - Every object has a private namespace; the name of this namespace is - available in method bodies, etc\., as the value of the implicit argument - __selfns__\. This value is constant for the life of the object\. Use - __$selfns__ instead of __$self__ if you need a unique token to - identify the object\. - - - When a __snit::widget__'s instance command is renamed, its Tk window - name remains the same \-\- and is still extremely important\. Consequently, the - Tk window name is available in method bodies as the value of the implicit - argument __win__\. This value is constant for the life of the object\. - When creating child windows, it's best to use __$win\.child__ rather than - __$self\.child__ as the name of the child window\. - -## How do I destroy a Snit object? - -Any Snit object of any type can be destroyed by renaming it to the empty string -using the Tcl __rename__ command\. - -Snit megawidgets \(i\.e\., instances of __snit::widget__ and -__snit::widgetadaptor__\) can be destroyed like any other widget: by using -the Tk __destroy__ command on the widget or on one of its ancestors in the -window hierarchy\. - -Every instance of a __snit::type__ has a __destroy__ method: - - % snit::type dog { ... } - ::dog - % dog spot - ::spot - % spot bark - ::spot barks. - % spot destroy - % spot barks - invalid command name "spot" - % - -Finally, every Snit type has a type method called __destroy__; calling it -destroys the type and all of its instances: - - % snit::type dog { ... } - ::dog - % dog spot - ::spot - % spot bark - ::spot barks. - % dog destroy - % spot bark - invalid command name "spot" - % dog fido - invalid command name "dog" - % - -# INSTANCE METHODS - -## What is an instance method? - -An instance method is a procedure associated with a specific object and called -as a subcommand of the object's command\. It is given free access to all of the -object's type variables, instance variables, and so forth\. - -## How do I define an instance method? - -Instance methods are defined in the type definition using the -__[method](\.\./\.\./\.\./\.\./index\.md\#method)__ statement\. Consider the -following code that might be used to add dogs to a computer simulation: - - % snit::type dog { - method bark {} { - return "$self barks." - } - - method chase {thing} { - return "$self chases $thing." - } - } - ::dog - % - -A dog can bark, and it can chase things\. - -The __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ statement looks just like -a normal Tcl __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__, except that it -appears in a __snit::type__ definition\. Notice that every instance method -gets an implicit argument called __self__; this argument contains the -object's name\. \(There's more on implicit method arguments below\.\) - -## How does a client call an instance method? - -The method name becomes a subcommand of the object\. For example, let's put a -simulated dog through its paces: - - % dog spot - ::spot - % spot bark - ::spot barks. - % spot chase cat - ::spot chases cat. - % - -## How does an instance method call another instance method? - -If method A needs to call method B on the same object, it does so just as a -client does: it calls method B as a subcommand of the object itself, using the -object name stored in the implicit argument __self__\. - -Suppose, for example, that our dogs never chase anything without barking at -them: - - % snit::type dog { - method bark {} { - return "$self barks." - } - - method chase {thing} { - return "$self chases $thing. [$self bark]" - } - } - ::dog - % dog spot - ::spot - % spot bark - ::spot barks. - % spot chase cat - ::spot chases cat. ::spot barks. - % - -## Are there any limitations on instance method names? - -Not really, so long as you avoid the standard instance method names: -__configure__, __configurelist__, __cget__, __destroy__, and -__info__\. Also, method names consisting of multiple words define -hierarchical methods\. - -## What is a hierarchical method? - -An object's methods are subcommands of the object's instance command\. -Hierarchical methods allow an object's methods to have subcommands of their own; -and these can in turn have subcommands, and so on\. This allows the programmer to -define a tree\-shaped command structure, such as is used by many of the Tk -widgets\-\-the subcommands of the Tk __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ -widget's __tag__ method are hierarchical methods\. - -## How do I define a hierarchical method? - -Define methods whose names consist of multiple words\. These words define the -hierarchy implicitly\. For example, the following code defines a __tag__ -method with subcommands __cget__ and __configure__: - - snit::widget mytext { - method {tag configure} {tag args} { ... } - - method {tag cget} {tag option} {...} - } - -Note that there is no explicit definition for the __tag__ method; it is -implicit in the definition of __tag configure__ and __tag cget__\. If you -tried to define __tag__ explicitly in this example, you'd get an error\. - -## How do I call hierarchical methods? - -As subcommands of subcommands\. - - % mytext .text - .text - % .text tag configure redtext -foreground red -background black - % .text tag cget redtext -foreground - red - % - -## How do I make an instance method private? - -It's often useful to define private methods, that is, instance methods intended -to be called only by other methods of the same object\. - -Snit doesn't implement any access control on instance methods, so all methods -are *de facto* public\. Conventionally, though, the names of public methods -begin with a lower\-case letter, and the names of private methods begin with an -upper\-case letter\. - -For example, suppose our simulated dogs only bark in response to other stimuli; -they never bark just for fun\. So the __bark__ method becomes __Bark__ to -indicate that it is private: - - % snit::type dog { - # Private by convention: begins with uppercase letter. - method Bark {} { - return "$self barks." - } - - method chase {thing} { - return "$self chases $thing. [$self Bark]" - } - } - ::dog - % dog fido - ::fido - % fido chase cat - ::fido chases cat. ::fido barks. - % - -## Are there any limitations on instance method arguments? - -Method argument lists are defined just like normal Tcl -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ argument lists; in particular, -they can include arguments with default values and the __args__ argument\. - -However, every method also has a number of implicit arguments provided by Snit -in addition to those explicitly defined\. The names of these implicit arguments -may not used to name explicit arguments\. - -## What implicit arguments are passed to each instance method? - -The arguments implicitly passed to every method are __type__, -__selfns__, __win__, and __self__\. - -## What is $type? - -The implicit argument __type__ contains the fully qualified name of the -object's type: - - % snit::type thing { - method mytype {} { - return $type - } - } - ::thing - % thing something - ::something - % something mytype - ::thing - % - -## What is $self? - -The implicit argument __self__ contains the object's fully qualified name\. - -If the object's command is renamed, then __$self__ will change to match in -subsequent calls\. Thus, your code should not assume that __$self__ is -constant unless you know for sure that the object will never be renamed\. - - % snit::type thing { - method myself {} { - return $self - } - } - ::thing - % thing mutt - ::mutt - % mutt myself - ::mutt - % rename mutt jeff - % jeff myself - ::jeff - % - -## What is $selfns? - -Each Snit object has a private namespace in which to store its [INSTANCE -VARIABLES](#section6) and [OPTIONS](#section7)\. The implicit argument -__selfns__ contains the name of this namespace; its value never changes, and -is constant for the life of the object, even if the object's name changes: - - % snit::type thing { - method myNameSpace {} { - return $selfns - } - } - ::thing - % thing jeff - ::jeff - % jeff myNameSpace - ::thing::Snit_inst3 - % rename jeff mutt - % mutt myNameSpace - ::thing::Snit_inst3 - % - -The above example reveals how Snit names an instance's private namespace; -however, you should not write code that depends on the specific naming -convention, as it might change in future releases\. - -## What is $win? - -The implicit argument __win__ is defined for all Snit methods, though it -really makes sense only for those of [WIDGETS](#section17) and [WIDGET -ADAPTORS](#section18)\. __$win__ is simply the original name of the -object, whether it's been renamed or not\. For widgets and widgetadaptors, it is -also therefore the name of a Tk window\. - -When a __snit::widgetadaptor__ is used to modify the interface of a widget -or megawidget, it must rename the widget's original command and replace it with -its own\. - -Thus, using __win__ whenever the Tk window name is called for means that a -__snit::widget__ or __snit::widgetadaptor__ can be adapted by a -__snit::widgetadaptor__\. See [WIDGETS](#section17) for more -information\. - -## How do I pass an instance method as a callback? - -It depends on the context\. - -Suppose in my application I have a __dog__ object named __fido__, and I -want __fido__ to bark when a Tk button called __\.bark__ is pressed\. In -this case, I create the callback command in the usual way, using -__[list](\.\./\.\./\.\./\.\./index\.md\#list)__: - - button .bark -text "Bark!" -command [list fido bark] - -In typical Tcl style, we use a callback to hook two independent components -together\. But suppose that the __dog__ object has a graphical interface and -owns the button itself? In this case, the __dog__ must pass one of its own -instance methods to the button it owns\. The obvious thing to do is this: - - % snit::widget dog { - constructor {args} { - #... - button $win.barkbtn -text "Bark!" -command [list $self bark] - #... - } - } - ::dog - % - -\(Note that in this example, our __dog__ becomes a __snit::widget__, -because it has GUI behavior\. See [WIDGETS](#section17) for more\.\) Thus, if -we create a __dog__ called __\.spot__, it will create a Tk button called -__\.spot\.barkbtn__; when pressed, the button will call __$self bark__\. - -Now, this will work\-\-provided that __\.spot__ is never renamed to something -else\. But surely renaming widgets is abnormal? And so it is\-\-unless -__\.spot__ is the hull component of a __snit::widgetadaptor__\. If it is, -then it will be renamed, and __\.spot__ will become the name of the -__snit::widgetadaptor__ object\. When the button is pressed, the command -__$self bark__ will be handled by the __snit::widgetadaptor__, which -might or might not do the right thing\. - -There's a safer way to do it, and it looks like this: - - % snit::widget dog { - constructor {args} { - #... - button $win.barkbtn -text "Bark!" -command [mymethod bark] - #... - } - } - ::dog - % - -The command __mymethod__ takes any number of arguments, and can be used like -__[list](\.\./\.\./\.\./\.\./index\.md\#list)__ to build up a callback command; -the only difference is that __mymethod__ returns a form of the command that -won't change even if the instance's name changes\. - -On the other hand, you might prefer to allow a widgetadaptor to override a -method such that your renamed widget will call the widgetadaptor's method -instead of its own\. In this case, using __\[list $self bark\]__ will do what -you want\.\.\.but this is a technique which should be used only in carefully -controlled circumstances\. - -## How do I delegate instance methods to a component? - -See [DELEGATION](#section16)\. - -# INSTANCE VARIABLES - -## What is an instance variable? - -An instance variable is a private variable associated with some particular Snit -object\. Instance variables can be scalars or arrays\. - -## How is a scalar instance variable defined? - -Scalar instance variables are defined in the type definition using the -__variable__ statement\. You can simply name it, or you can initialize it -with a value: - - snit::type mytype { - # Define variable "greeting" and initialize it with "Howdy!" - variable greeting "Howdy!" - } - -## How is an array instance variable defined? - -Array instance variables are also defined in the type definition using the -__variable__ command\. You can initialize them at the same time by specifying -the __\-array__ option: - - snit::type mytype { - # Define array variable "greetings" - variable greetings -array { - formal "Good Evening" - casual "Howdy!" - } - } - -## What happens if I don't initialize an instance variable? - -Variables do not really exist until they are given values\. If you do not -initialize a variable when you define it, then you must be sure to assign a -value to it \(in the constructor, say, or in some method\) before you reference -it\. - -## Are there any limitations on instance variable names? - -Just a few\. - -First, every Snit object has a built\-in instance variable called -__options__, which should never be redefined\. - -Second, all names beginning with "Snit\_" are reserved for use by Snit internal -code\. - -Third, instance variable names containing the namespace delimiter \(__::__\) -are likely to cause great confusion\. - -## Do I need to declare my instance variables in my methods? - -No\. Once you've defined an instance variable in the type definition, it can be -used in any instance code \(instance methods, the constructor, and the -destructor\) without declaration\. This differs from normal Tcl practice, in which -all non\-local variables in a proc need to be declared\. - -There is a speed penalty to having all instance variables implicitly available -in all instance code\. Even though your code need not declare the variables -explicitly, Snit must still declare them, and that takes time\. If you have ten -instance variables, a method that uses none of them must still pay the -declaration penalty for all ten\. In most cases, the additional runtime cost is -negligible\. If extreme cases, you might wish to avoid it; there are two methods -for doing so\. - -The first is to define a single instance variable, an array, and store all of -your instance data in the array\. This way, you're only paying the declaration -penalty for one variable\-\-and you probably need the variable most of the time -anyway\. This method breaks down if your instance variables include multiple -arrays; in Tcl 8\.5, however, the __[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ -command might come to your rescue\. - -The second method is to declare your instance variables explicitly in your -instance code, while *not* including them in the type definition: - - snit::type dog { - constructor {} { - variable mood - - set mood happy - } - - method setmood {newMood} { - variable mood - - set mood $newMood - } - - method getmood {} { - variable mood - - return $mood - } - } - -This allows you to ensure that only the required variables are included in each -method, at the cost of longer code and run\-time errors when you forget to -declare a variable you need\. - -## How do I pass an instance variable's name to another object? - -In Tk, it's common to pass a widget a variable name; for example, Tk label -widgets have a __\-textvariable__ option which names the variable which will -contain the widget's text\. This allows the program to update the label's value -just by assigning a new value to the variable\. - -If you naively pass the instance variable name to the label widget, you'll be -confused by the result; Tk will assume that the name names a global variable\. -Instead, you need to provide a fully\-qualified variable name\. From within an -instance method or a constructor, you can fully qualify the variable's name -using the __myvar__ command: - - snit::widget mywidget { - variable labeltext "" - - constructor {args} { - # ... - - label $win.label -textvariable [myvar labeltext] - - # ... - } - } - -## How do I make an instance variable public? - -Practically speaking, you don't\. Instead, you'll implement public variables as -[OPTIONS](#section7)\. Alternatively, you can write [INSTANCE -METHODS](#section5) to set and get the variable's value\. - -# OPTIONS - -## What is an option? - -A type's options are the equivalent of what other object\-oriented languages -would call public member variables or properties: they are data values which can -be retrieved and \(usually\) set by the clients of an object\. - -Snit's implementation of options follows the Tk model fairly exactly, except -that __snit::type__ objects usually don't interact with [THE TK OPTION -DATABASE](#section19); __snit::widget__ and __snit::widgetadaptor__ -objects, on the other hand, always do\. - -## How do I define an option? - -Options are defined in the type definition using the __option__ statement\. -Consider the following type, to be used in an application that manages a list of -dogs for a pet store: - - snit::type dog { - option -breed -default mongrel - option -color -default brown - option -akc -default 0 - option -shots -default 0 - } - -According to this, a dog has four notable properties: a breed, a color, a flag -that says whether it's pedigreed with the American Kennel Club, and another flag -that says whether it has had its shots\. The default dog, evidently, is a brown -mutt\. - -There are a number of options you can specify when defining an option; if -__\-default__ is the only one, you can omit the word __\-default__ as -follows: - - snit::type dog { - option -breed mongrel - option -color brown - option -akc 0 - option -shots 0 - } - -If no __\-default__ value is specified, the option's default value will be -the empty string \(but see [THE TK OPTION DATABASE](#section19)\)\. - -The Snit man page refers to options like these as "locally defined" options\. - -## How can a client set options at object creation? - -The normal convention is that the client may pass any number of options and -their values after the object's name at object creation\. For example, the -__::dog__ command defined in the previous answer can now be used to create -individual dogs\. Any or all of the options may be set at creation time\. - - % dog spot -breed beagle -color "mottled" -akc 1 -shots 1 - ::spot - % dog fido -shots 1 - ::fido - % - -So __::spot__ is a pedigreed beagle; __::fido__ is a typical mutt, but -his owners evidently take care of him, because he's had his shots\. - -*Note:* If the type defines a constructor, it can specify a different -object\-creation syntax\. See [CONSTRUCTORS](#section12) for more -information\. - -## How can a client retrieve an option's value? - -Retrieve option values using the __cget__ method: - - % spot cget -color - mottled - % fido cget -breed - mongrel - % - -## How can a client set options after object creation? - -Any number of options may be set at one time using the __configure__ -instance method\. Suppose that closer inspection shows that ::fido is not a brown -mongrel, but rather a rare Arctic Boar Hound of a lovely dun color: - - % fido configure -color dun -breed "Arctic Boar Hound" - % fido cget -color - dun - % fido cget -breed - Arctic Boar Hound - -Alternatively, the __configurelist__ method takes a list of options and -values; occasionally this is more convenient: - - % set features [list -color dun -breed "Arctic Boar Hound"] - -color dun -breed {Arctic Boar Hound} - % fido configurelist $features - % fido cget -color - dun - % fido cget -breed - Arctic Boar Hound - % - -In Tcl 8\.5, the __\*__ keyword can be used with __configure__ in this -case: - - % set features [list -color dun -breed "Arctic Boar Hound"] - -color dun -breed {Arctic Boar Hound} - % fido configure {*}$features - % fido cget -color - dun - % fido cget -breed - Arctic Boar Hound - % - -The results are the same\. - -## How should an instance method access an option value? - -There are two ways an instance method can set and retrieve an option's value\. -One is to use the __configure__ and __cget__ methods, as shown below\. - - % snit::type dog { - option -weight 10 - - method gainWeight {} { - set wt [$self cget -weight] - incr wt - $self configure -weight $wt - } - } - ::dog - % dog fido - ::fido - % fido cget -weight - 10 - % fido gainWeight - % fido cget -weight - 11 - % - -Alternatively, Snit provides a built\-in array instance variable called -__options__\. The indices are the option names; the values are the option -values\. The method __gainWeight__ can thus be rewritten as follows: - - method gainWeight {} { - incr options(-weight) - } - -As you can see, using the __options__ variable involves considerably less -typing and is the usual way to do it\. But if you use __\-configuremethod__ or -__\-cgetmethod__ \(described in the following answers\), you might wish to use -the __configure__ and __cget__ methods anyway, just so that any special -processing you've implemented is sure to get done\. Also, if the option is -delegated to a component then __configure__ and __cget__ are the only -way to access it without accessing the component directly\. See -[DELEGATION](#section16) for more information\. - -## How can I make an option read\-only? - -Define the option with __\-readonly yes__\. - -Suppose you've got an option that determines how instances of your type are -constructed; it must be set at creation time, after which it's constant\. For -example, a dog never changes its breed; it might or might not have had its -shots, and if not can have them at a later time\. __\-breed__ should be -read\-only, but __\-shots__ should not be\. - - % snit::type dog { - option -breed -default mongrel -readonly yes - option -shots -default no - } - ::dog - % dog fido -breed retriever - ::fido - % fido configure -shots yes - % fido configure -breed terrier - option -breed can only be set at instance creation - % - -## How can I catch accesses to an option's value? - -Define a __\-cgetmethod__ for the option\. - -## What is a \-cgetmethod? - -A __\-cgetmethod__ is a method that's called whenever the related option's -value is queried via the __cget__ instance method\. The handler can compute -the option's value, retrieve it from a database, or do anything else you'd like -it to do\. - -Here's what the default behavior would look like if written using a -__\-cgetmethod__: - - snit::type dog { - option -color -default brown -cgetmethod GetOption - - method GetOption {option} { - return $options($option) - } - } - -Any instance method can be used, provided that it takes one argument, the name -of the option whose value is to be retrieved\. - -## How can I catch changes to an option's value? - -Define a __\-configuremethod__ for the option\. - -## What is a \-configuremethod? - -A __\-configuremethod__ is a method that's called whenever the related option -is given a new value via the __configure__ or __configurelist__ instance -methods\. The method can pass the value on to some other object, store it in a -database, or do anything else you'd like it to do\. - -Here's what the default configuration behavior would look like if written using -a __\-configuremethod__: - - snit::type dog { - option -color -default brown -configuremethod SetOption - - method SetOption {option value} { - set options($option) $value - } - } - -Any instance method can be used, provided that it takes two arguments, the name -of the option and the new value\. - -Note that if your method doesn't store the value in the __options__ array, -the __options__ array won't get updated\. - -## How can I validate an option's value? - -Define a __\-validatemethod__\. - -## What is a \-validatemethod? - -A __\-validatemethod__ is a method that's called whenever the related option -is given a new value via the __configure__ or __configurelist__ instance -methods\. It's the method's responsibility to determine whether the new value is -valid, and throw an error if it isn't\. The __\-validatemethod__, if any, is -called before the value is stored in the __options__ array; in particular, -it's called before the __\-configuremethod__, if any\. - -For example, suppose an option always takes a Boolean value\. You can ensure that -the value is in fact a valid Boolean like this: - - % snit::type dog { - option -shots -default no -validatemethod BooleanOption - - method BooleanOption {option value} { - if {![string is boolean -strict $value]} { - error "expected a boolean value, got \"$value\"" - } - } - } - ::dog - % dog fido - % fido configure -shots yes - % fido configure -shots NotABooleanValue - expected a boolean value, got "NotABooleanValue" - % - -Note that the same __\-validatemethod__ can be used to validate any number of -boolean options\. - -Any method can be a __\-validatemethod__ provided that it takes two -arguments, the option name and the new option value\. - -# TYPE VARIABLES - -## What is a type variable? - -A type variable is a private variable associated with a Snit type rather than -with a particular instance of the type\. In C\+\+ and Java, the term *static -member variable* is used for the same notion\. Type variables can be scalars or -arrays\. - -## How is a scalar type variable defined? - -Scalar type variables are defined in the type definition using the -__typevariable__ statement\. You can simply name it, or you can initialize it -with a value: - - snit::type mytype { - # Define variable "greeting" and initialize it with "Howdy!" - typevariable greeting "Howdy!" - } - -Every object of type __mytype__ now has access to a single variable called -__greeting__\. - -## How is an array\-valued type variable defined? - -Array\-valued type variables are also defined using the __typevariable__ -command; to initialize them, include the __\-array__ option: - - snit::type mytype { - # Define typearray variable "greetings" - typevariable greetings -array { - formal "Good Evening" - casual "Howdy!" - } - } - -## What happens if I don't initialize a type variable? - -Variables do not really exist until they are given values\. If you do not -initialize a variable when you define it, then you must be sure to assign a -value to it \(in the type constructor, say\) before you reference it\. - -## Are there any limitations on type variable names? - -Type variable names have the same restrictions as the names of [INSTANCE -VARIABLES](#section6) do\. - -## Do I need to declare my type variables in my methods? - -No\. Once you've defined a type variable in the type definition, it can be used -in [INSTANCE METHODS](#section5) or [TYPE METHODS](#section9) without -declaration\. This differs from normal Tcl practice, in which all non\-local -variables in a proc need to be declared\. - -Type variables are subject to the same speed/readability tradeoffs as instance -variables; see [Do I need to declare my instance variables in my -methods?](#subsection46) - -## How do I pass a type variable's name to another object? - -In Tk, it's common to pass a widget a variable name; for example, Tk label -widgets have a __\-textvariable__ option which names the variable which will -contain the widget's text\. This allows the program to update the label's value -just by assigning a new value to the variable\. - -If you naively pass a type variable name to the label widget, you'll be confused -by the result; Tk will assume that the name names a global variable\. Instead, -you need to provide a fully\-qualified variable name\. From within an instance -method or a constructor, you can fully qualify the type variable's name using -the __mytypevar__ command: - - snit::widget mywidget { - typevariable labeltext "" - - constructor {args} { - # ... - - label $win.label -textvariable [mytypevar labeltext] - - # ... - } - } - -## How do I make a type variable public? - -There are two ways to do this\. The preferred way is to write a pair of [TYPE -METHODS](#section9) to set and query the type variable's value\. - -Type variables are stored in the type's namespace, which has the same name as -the type itself\. Thus, you can also publicize the type variable's name in your -documentation so that clients can access it directly\. For example, - - snit::type mytype { - typevariable myvariable - } - - set ::mytype::myvariable "New Value" - -# TYPE METHODS - -## What is a type method? - -A type method is a procedure associated with the type itself rather than with -any specific instance of the type, and called as a subcommand of the type -command\. - -## How do I define a type method? - -Type methods are defined in the type definition using the __typemethod__ -statement: - - snit::type dog { - # List of pedigreed dogs - typevariable pedigreed - - typemethod pedigreedDogs {} { - return $pedigreed - } - } - -Suppose the __dog__ type maintains a list of the names of the dogs that have -pedigrees\. The __pedigreedDogs__ type method returns this list\. - -The __typemethod__ statement looks just like a normal Tcl -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__, except that it appears in a -__snit::type__ definition\. Notice that every type method gets an implicit -argument called __type__, which contains the fully\-qualified type name\. - -## How does a client call a type method? - -The type method name becomes a subcommand of the type's command\. For example, -assuming that the constructor adds each pedigreed dog to the list of -__pedigreedDogs__, - - snit::type dog { - option -pedigreed 0 - - # List of pedigreed dogs - typevariable pedigreed - - typemethod pedigreedDogs {} { - return $pedigreed - } - - # ... - } - - dog spot -pedigreed 1 - dog fido - - foreach dog [dog pedigreedDogs] { ... } - -## Are there any limitations on type method names? - -Not really, so long as you avoid the standard type method names: __create__, -__destroy__, and __info__\. - -## How do I make a type method private? - -It's sometimes useful to define private type methods, that is, type methods -intended to be called only by other type or instance methods of the same object\. - -Snit doesn't implement any access control on type methods; by convention, the -names of public methods begin with a lower\-case letter, and the names of private -methods begin with an upper\-case letter\. - -Alternatively, a Snit __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ can be used -as a private type method; see [PROCS](#section10)\. - -## Are there any limitations on type method arguments? - -Method argument lists are defined just like normal Tcl proc argument lists; in -particular, they can include arguments with default values and the __args__ -argument\. - -However, every type method is called with an implicit argument called -__type__ that contains the name of the type command\. In addition, type -methods should by convention avoid using the names of the arguments implicitly -defined for [INSTANCE METHODS](#section5)\. - -## How does an instance or type method call a type method? - -If an instance or type method needs to call a type method, it should use -__$type__ to do so: - - snit::type dog { - - typemethod pedigreedDogs {} { ... } - - typemethod printPedigrees {} { - foreach obj [$type pedigreedDogs] { ... } - } - } - -## How do I pass a type method as a callback? - -It's common in Tcl to pass a snippet of code to another object, for it to call -later\. Because types cannot be renamed, you can just use the type name, or, if -the callback is registered from within a type method, __type__\. For example, -suppose we want to print a list of pedigreed dogs when a Tk button is pushed: - - button .btn -text "Pedigrees" -command [list dog printPedigrees] - pack .btn - -Alternatively, from a method or type method you can use the __mytypemethod__ -command, just as you would use __mymethod__ to define a callback command for -[INSTANCE METHODS](#section5)\. - -## Can type methods be hierarchical? - -Yes, you can define hierarchical type methods in just the same way as you can -define hierarchical instance methods\. See [INSTANCE METHODS](#section5) for -more\. - -# PROCS - -## What is a proc? - -A Snit __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ is really just a Tcl proc -defined within the type's namespace\. You can use procs for private code that -isn't related to any particular instance\. - -## How do I define a proc? - -Procs are defined by including a __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ -statement in the type definition: - - snit::type mytype { - # Pops and returns the first item from the list stored in the - # listvar, updating the listvar - proc pop {listvar} { ... } - - # ... - } - -## Are there any limitations on proc names? - -Any name can be used, so long as it does not begin with __Snit\___; names -beginning with __Snit\___ are reserved for Snit's own use\. However, the wise -programmer will avoid __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ names -\(__[set](\.\./\.\./\.\./\.\./index\.md\#set)__, -__[list](\.\./\.\./\.\./\.\./index\.md\#list)__, __if__, etc\.\) that would -shadow standard Tcl command names\. - -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ names, being private, should begin -with a capital letter according to convention; however, as there are typically -no public __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__s in the type's namespace -it doesn't matter much either way\. - -## How does a method call a proc? - -Just like it calls any Tcl command\. For example, - - snit::type mytype { - # Pops and returns the first item from the list stored in the - # listvar, updating the listvar - proc pop {listvar} { ... } - - variable requestQueue {} - - # Get one request from the queue and process it. - method processRequest {} { - set req [pop requestQueue] - } - } - -## How can I pass a proc to another object as a callback? - -The __myproc__ command returns a callback command for the -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__, just as __mymethod__ does for -a method\. - -# TYPE CONSTRUCTORS - -## What is a type constructor? - -A type constructor is a body of code that initializes the type as a whole, -rather like a C\+\+ static initializer\. The body of a type constructor is executed -once when the type is defined, and never again\. - -A type can have at most one type constructor\. - -## How do I define a type constructor? - -A type constructor is defined by using the __typeconstructor__ statement in -the type definition\. For example, suppose the type uses an array\-valued type -variable as a look\-up table, and the values in the array have to be computed at -start\-up\. - - % snit::type mytype { - typevariable lookupTable - - typeconstructor { - array set lookupTable {key value...} - } - } - -# CONSTRUCTORS - -## What is a constructor? - -In object\-oriented programming, an object's constructor is responsible for -initializing the object completely at creation time\. The constructor receives -the list of options passed to the __snit::type__ command's __create__ -method and can then do whatever it likes\. That might include computing instance -variable values, reading data from files, creating other objects, updating type -and instance variables, and so forth\. - -The constructor's return value is ignored \(unless it's an error, of course\)\. - -## How do I define a constructor? - -A constructor is defined by using the __constructor__ statement in the type -definition\. Suppose that it's desired to keep a list of all pedigreed dogs\. The -list can be maintained in a type variable and retrieved by a type method\. -Whenever a dog is created, it can add itself to the list\-\-provided that it's -registered with the American Kennel Club\. - - % snit::type dog { - option -akc 0 - - typevariable akcList {} - - constructor {args} { - $self configurelist $args - - if {$options(-akc)} { - lappend akcList $self - } - } - - typemethod akclist {} { - return $akcList - } - } - ::dog - % dog spot -akc 1 - ::spot - % dog fido - ::fido - % dog akclist - ::spot - % - -## What does the default constructor do? - -If you don't provide a constructor explicitly, you get the default constructor, -which is identical to the explicitly\-defined constructor shown here: - - snit::type dog { - constructor {args} { - $self configurelist $args - } - } - -When the constructor is called, __args__ will be set to the list of -arguments that follow the object's name\. The constructor is allowed to interpret -this list any way it chooses; the normal convention is to assume that it's a -list of option names and values, as shown in the example above\. If you simply -want to save the option values, you should use the __configurelist__ method, -as shown\. - -## Can I choose a different set of arguments for the constructor? - -Yes, you can\. For example, suppose we wanted to be sure that the breed was -explicitly stated for every dog at creation time, and couldn't be changed -thereafter\. One way to do that is as follows: - - % snit::type dog { - variable breed - - option -color brown - option -akc 0 - - constructor {theBreed args} { - set breed $theBreed - $self configurelist $args - } - - method breed {} { return $breed } - } - ::dog - % dog spot dalmatian -color spotted -akc 1 - ::spot - % spot breed - dalmatian - -The drawback is that this syntax is non\-standard, and may limit the -compatibility of your new type with other people's code\. For example, Snit -assumes that it can create [COMPONENTS](#section14) using the standard -creation syntax\. - -## Are there any limitations on constructor arguments? - -Constructor argument lists are subject to the same limitations as those on -instance method argument lists\. It has the same implicit arguments, and can -contain default values and the __args__ argument\. - -## Is there anything special about writing the constructor? - -Yes\. Writing the constructor can be tricky if you're delegating options to -components, and there are specific issues relating to __snit::widget__s and -__snit::widgetadaptor__s\. See [DELEGATION](#section16), -[WIDGETS](#section17), [WIDGET ADAPTORS](#section18), and [THE TK -OPTION DATABASE](#section19)\. - -# DESTRUCTORS - -## What is a destructor? - -A destructor is a special kind of method that's called when an object is -destroyed\. It's responsible for doing any necessary clean\-up when the object -goes away: destroying [COMPONENTS](#section14), closing files, and so -forth\. - -## How do I define a destructor? - -Destructors are defined by using the __destructor__ statement in the type -definition\. - -Suppose we're maintaining a list of pedigreed dogs; then we'll want to remove -dogs from it when they are destroyed\. - - snit::type dog { - option -akc 0 - - typevariable akcList {} - - constructor {args} { - $self configurelist $args - - if {$options(-akc)} { - lappend akcList $self - } - } - - destructor { - set ndx [lsearch $akcList $self] - - if {$ndx != -1} { - set akcList [lreplace $akcList $ndx $ndx] - } - } - - typemethod akclist {} { - return $akcList - } - } - -## Are there any limitations on destructor arguments? - -Yes; a destructor has no explicit arguments\. - -## What implicit arguments are passed to the destructor? - -The destructor gets the same implicit arguments that are passed to [INSTANCE -METHODS](#section5): __type__, __selfns__, __win__, and -__self__\. - -## Must components be destroyed explicitly? - -Yes and no\. - -Any Tk widgets created by a __snit::widget__ or __snit::widgetadaptor__ -will be destroyed automatically by Tk when the megawidget is destroyed, in -keeping with normal Tk behavior \(destroying a parent widget destroys the whole -tree\)\. - -Components of normal __snit::types__, on the other hand, are never destroyed -automatically, nor are non\-widget components of Snit megawidgets\. If your object -creates them in its constructor, then it should generally destroy them in its -destructor\. - -## Is there any special about writing a destructor? - -Yes\. If an object's constructor throws an error, the object's destructor will be -called to clean up; this means that the object might not be completely -constructed when the destructor is called\. This can cause the destructor to -throw its own error; the result is usually misleading, confusing, and unhelpful\. -Consequently, it's important to write your destructor so that it's fail\-safe\. - -For example, a __dog__ might create a __tail__ component; the component -will need to be destroyed\. But suppose there's an error while processing the -creation options\-\-the destructor will be called, and there will be no -__tail__ to destroy\. The simplest solution is generally to catch and ignore -any errors while destroying components\. - - snit::type dog { - component tail - - constructor {args} { - $self configurelist $args - - set tail [tail %AUTO%] - } - - destructor { - catch {$tail destroy} - } - } - -# COMPONENTS - -## What is a component? - -Often an object will create and manage a number of other objects\. A Snit -megawidget, for example, will often create a number of Tk widgets\. These objects -are part of the main object; it is composed of them, so they are called -components of the object\. - -But Snit also has a more precise meaning for [COMPONENT](#section14)\. The -components of a Snit object are those objects to which methods or options can be -delegated\. \(See [DELEGATION](#section16) for more information about -delegation\.\) - -## How do I declare a component? - -First, you must decide what role a component plays within your object, and give -the role a name\. Then, you declare the component using its role name and the -__component__ statement\. The __component__ statement declares an -*instance variable* which is used to store the component's command name when -the component is created\. - -For example, suppose your __dog__ object creates a __tail__ object \(the -better to wag with, no doubt\): - - snit::type dog { - component mytail - - constructor {args} { - # Create and save the component's command - set mytail [tail %AUTO% -partof $self] - $self configurelist $args - } - - method wag {} { - $mytail wag - } - } - -As shown here, it doesn't matter what the __tail__ object's real name is; -the __dog__ object refers to it by its component name\. - -The above example shows one way to delegate the __wag__ method to the -__mytail__ component; see [DELEGATION](#section16) for an easier way\. - -## How is a component named? - -A component has two names\. The first name is that of the component variable; -this represents the role the component object plays within the Snit object\. This -is the component name proper, and is the name used to refer to the component -within Snit code\. The second name is the name of the actual component object -created by the Snit object's constructor\. This second name is always a Tcl -command name, and is referred to as the component's object name\. - -In the example in the previous question, the component name is __mytail__; -the __mytail__ component's object name is chosen automatically by Snit since -__%AUTO%__ was used when the component object was created\. - -## Are there any limitations on component names? - -Yes\. __snit::widget__ and __snit::widgetadaptor__ objects have a special -component called the __hull__ component; thus, the name __hull__ should -be used for no other purpose\. - -Otherwise, since component names are in fact instance variable names they must -follow the rules for [INSTANCE VARIABLES](#section6)\. - -## What is an owned component? - -An *owned* component is a component whose object command's lifetime is -controlled by the __snit::type__ or __snit::widget__\. - -As stated above, a component is an object to which our object can delegate -methods or options\. Under this definition, our object will usually create its -component objects, but not necessarily\. Consider the following: a dog object has -a tail component; but tail knows that it's part of the dog: - - snit::type dog { - component mytail - - constructor {args} { - set mytail [tail %AUTO% -partof $self] - $self configurelist $args - } - - destructor { - catch {$mytail destroy} - } - - delegate method wagtail to mytail as wag - - method bark {} { - return "$self barked." - } - } - - snit::type tail { - component mydog - option -partof -readonly yes - - constructor {args} { - $self configurelist $args - set mydog $options(-partof) - } - - method wag {} { - return "Wag, wag." - } - - method pull {} { - $mydog bark - } - } - -Thus, if you ask a dog to wag its tail, it tells its tail to wag; and if you -pull the dog's tail, the tail tells the dog to bark\. In this scenario, the tail -is a component of the dog, and the dog is a component of the tail, but the dog -owns the tail and not the other way around\. - -## What does the install command do? - -The __install__ command creates an owned component using a specified -command, and assigns the result to the component's instance variable\. For -example: - - snit::type dog { - component mytail - - constructor {args} { - # set mytail [tail %AUTO% -partof $self] - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - } - -In a __snit::type__'s code, the __install__ command shown above is -equivalent to the __set mytail__ command that's commented out\. In a -__snit::widget__'s or __snit::widgetadaptor__'s, code, however, the -__install__ command also queries [THE TK OPTION DATABASE](#section19) -and initializes the new component's options accordingly\. For consistency, it's a -good idea to get in the habit of using __install__ for all owned components\. - -## Must owned components be created in the constructor? - -No, not necessarily\. In fact, there's no reason why an object can't destroy and -recreate a component multiple times over its own lifetime\. - -## Are there any limitations on component object names? - -Yes\. - -Component objects which are Tk widgets or megawidgets must have valid Tk window -names\. - -Component objects which are not widgets or megawidgets must have fully\-qualified -command names, i\.e\., names which include the full namespace of the command\. Note -that Snit always creates objects with fully qualified names\. - -Next, the object names of components and owned by your object must be unique\. -This is no problem for widget components, since widget names are always unique; -but consider the following code: - - snit::type tail { ... } - - snit::type dog { - delegate method wag to mytail - - constructor {} { - install mytail using tail mytail - } - } - -This code uses the component name, __mytail__, as the component object name\. -This is not good, and here's why: Snit instance code executes in the Snit type's -namespace\. In this case, the __mytail__ component is created in the -__::dog::__ namespace, and will thus have the name __::dog::mytail__\. - -Now, suppose you create two dogs\. Both dogs will attempt to create a tail called -__::dog::mytail__\. The first will succeed, and the second will fail, since -Snit won't let you create an object if its name is already a command\. Here are -two ways to avoid this situation: - -First, if the component type is a __snit::type__ you can specify -__%AUTO%__ as its name, and be guaranteed to get a unique name\. This is the -safest thing to do: - - install mytail using tail %AUTO% - -If the component type isn't a __snit::type__ you can create the component in -the object's instance namespace: - - install mytail using tail ${selfns}::mytail - -Make sure you pick a unique name within the instance namespace\. - -## Must I destroy the components I own? - -That depends\. When a parent widget is destroyed, all child widgets are destroyed -automatically\. Thus, if your object is a __snit::widget__ or -__snit::widgetadaptor__ you don't need to destroy any components that are -widgets, because they will generally be children or descendants of your -megawidget\. - -If your object is an instance of __snit::type__, though, none of its owned -components will be destroyed automatically, nor will be non\-widget components of -a __snit::widget__ be destroyed automatically\. All such owned components -must be destroyed explicitly, or they won't be destroyed at all\. - -## Can I expose a component's object command as part of my interface? - -Yes, and there are two ways to do it\. The most appropriate way is usually to use -[DELEGATION](#section16)\. Delegation allows you to pass the options and -methods you specify along to particular components\. This effectively hides the -components from the users of your type, and ensures good encapsulation\. - -However, there are times when it's appropriate, not to mention simpler, just to -make the entire component part of your type's public interface\. - -## How do I expose a component's object command? - -When you declare the component, specify the __component__ statement's -__\-public__ option\. The value of this option is the name of a method which -will be delegated to your component's object command\. - -For example, supposed you've written a combobox megawidget which owns a listbox -widget, and you want to make the listbox's entire interface public\. You can do -it like this: - - snit::widget combobox { - component listbox -public listbox - - constructor {args} { - install listbox using listbox $win.listbox .... - } - } - - combobox .mycombo - .mycombo listbox configure -width 30 - -Your comobox widget, __\.mycombo__, now has a __listbox__ method which -has all of the same subcommands as the listbox widget itself\. Thus, the above -code sets the listbox component's width to 30\. - -Usually you'll let the method name be the same as the component name; however, -you can name it anything you like\. - -# TYPE COMPONENTS - -## What is a type component? - -A type component is a component that belongs to the type itself instead of to a -particular instance of the type\. The relationship between components and type -components is the same as the relationship between [INSTANCE -VARIABLES](#section6) and [TYPE VARIABLES](#section8)\. Both [INSTANCE -METHODS](#section5) and [TYPE METHODS](#section9) can be delegated to -type components\. - -Once you understand [COMPONENTS](#section14) and -[DELEGATION](#section16), type components are just more of the same\. - -## How do I declare a type component? - -Declare a type component using the __typecomponent__ statement\. It takes the -same options \(__\-inherit__ and __\-public__\) as the __component__ -statement does, and defines a type variable to hold the type component's object -command\. - -Suppose in your model you've got many dogs, but only one veterinarian\. You might -make the veterinarian a type component\. - - snit::type veterinarian { ... } - - snit::type dog { - typecomponent vet - - # ... - } - -## How do I install a type component? - -Just use the __[set](\.\./\.\./\.\./\.\./index\.md\#set)__ command to assign the -component's object command to the type component\. Because types \(even -__snit::widget__ types\) are not widgets, and do not have options anyway, the -extra features of the __install__ command are not needed\. - -You'll usually install type components in the type constructor, as shown here: - - snit::type veterinarian { ... } - - snit::type dog { - typecomponent vet - - typeconstructor { - set vet [veterinarian %AUTO%] - } - } - -## Are there any limitations on type component names? - -Yes, the same as on [INSTANCE VARIABLES](#section6), [TYPE -VARIABLES](#section8), and normal [COMPONENTS](#section14)\. - -# DELEGATION - -## What is delegation? - -Delegation, simply put, is when you pass a task you've been given to one of your -assistants\. \(You do have assistants, don't you?\) Snit objects can do the same -thing\. The following example shows one way in which the __dog__ object can -delegate its __wag__ method and its __\-taillength__ option to its -__tail__ component\. - - snit::type dog { - variable mytail - - option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption - - method SetTailOption {option value} { - $mytail configure $option $value - } - - method GetTailOption {option} { - $mytail cget $option - } - - method wag {} { - $mytail wag - } - - constructor {args} { - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - - } - -This is the hard way to do it, by it demonstrates what delegation is all about\. -See the following answers for the easy way to do it\. - -Note that the constructor calls the __configurelist__ method -__[after](\.\./\.\./\.\./\.\./index\.md\#after)__ it creates its __tail__; -otherwise, if __\-taillength__ appeared in the list of __args__ we'd get -an error\. - -## How can I delegate a method to a component object? - -Delegation occurs frequently enough that Snit makes it easy\. Any method can be -delegated to any component or type component by placing a single -__delegate__ statement in the type definition\. \(See -[COMPONENTS](#section14) and [TYPE COMPONENTS](#section15) for more -information about component names\.\) - -For example, here's a much better way to delegate the __dog__ object's -__wag__ method: - - % snit::type dog { - delegate method wag to mytail - - constructor {} { - install mytail using tail %AUTO% - } - } - ::dog - % snit::type tail { - method wag {} { return "Wag, wag, wag."} - } - ::tail - % dog spot - ::spot - % spot wag - Wag, wag, wag. - -This code has the same effect as the code shown under the previous question: -when a __dog__'s __wag__ method is called, the call and its arguments -are passed along automatically to the __tail__ object\. - -Note that when a component is mentioned in a __delegate__ statement, the -component's instance variable is defined implicitly\. However, it's still good -practice to declare it explicitly using the __component__ statement\. - -Note also that you can define a method name using the -__[method](\.\./\.\./\.\./\.\./index\.md\#method)__ statement, or you can define -it using __delegate__; you can't do both\. - -## Can I delegate to a method with a different name? - -Suppose you wanted to delegate the __dog__'s __wagtail__ method to the -__tail__'s __wag__ method\. After all you wag the tail, not the dog\. It's -easily done: - - snit::type dog { - delegate method wagtail to mytail as wag - - constructor {args} { - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - } - -## Can I delegate to a method with additional arguments? - -Suppose the __tail__'s __wag__ method takes as an argument the number of -times the tail should be wagged\. You want to delegate the __dog__'s -__wagtail__ method to the __tail__'s __wag__ method, specifying that -the tail should be wagged exactly three times\. This is easily done, too: - - snit::type dog { - delegate method wagtail to mytail as {wag 3} - # ... - } - - snit::type tail { - method wag {count} { - return [string repeat "Wag " $count] - } - # ... - } - -## Can I delegate a method to something other than an object? - -Normal method delegation assumes that you're delegating a method \(a subcommand -of an object command\) to a method of another object \(a subcommand of a different -object command\)\. But not all Tcl objects follow Tk conventions, and not -everything you'd to which you'd like to delegate a method is necessary an -object\. Consequently, Snit makes it easy to delegate a method to pretty much -anything you like using the __delegate__ statement's __using__ clause\. - -Suppose your dog simulation stores dogs in a database, each dog as a single -record\. The database API you're using provides a number of commands to manage -records; each takes the record ID \(a string you choose\) as its first argument\. -For example, __saverec__ saves a record\. If you let the record ID be the -name of the dog object, you can delegate the dog's __save__ method to the -__saverec__ command as follows: - - snit::type dog { - delegate method save using {saverec %s} - } - -The __%s__ is replaced with the instance name when the __save__ method -is called; any additional arguments are the appended to the resulting command\. - -The __using__ clause understands a number of other %\-conversions; in -addition to the instance name, you can substitute in the method name -\(__%m__\), the type name \(__%t__\), the instance namespace \(__%n__\), -the Tk window name \(__%w__\), and, if a component or typecomponent name was -given in the __delegate__ statement, the component's object command -\(__%c__\)\. - -## How can I delegate a method to a type component object? - -Just exactly as you would to a component object\. The __delegate method__ -statement accepts both component and type component names in its __to__ -clause\. - -## How can I delegate a type method to a type component object? - -Use the __delegate typemethod__ statement\. It works like __delegate -method__, with these differences: first, it defines a type method instead of -an instance method; second, the __using__ clause ignores the __%s__, -__%n__, and __%w__ %\-conversions\. - -Naturally, you can't delegate a type method to an instance component\.\.\.Snit -wouldn't know which instance should receive it\. - -## How can I delegate an option to a component object? - -The first question in this section \(see [DELEGATION](#section16)\) shows one -way to delegate an option to a component; but this pattern occurs often enough -that Snit makes it easy\. For example, every __tail__ object has a -__\-length__ option; we want to allow the creator of a __dog__ object to -set the tail's length\. We can do this: - - % snit::type dog { - delegate option -length to mytail - - constructor {args} { - install mytail using tail %AUTO% -partof $self - $self configurelist $args - } - } - ::dog - % snit::type tail { - option -partof - option -length 5 - } - ::tail - % dog spot -length 7 - ::spot - % spot cget -length - 7 - -This produces nearly the same result as the __\-configuremethod__ and -__\-cgetmethod__ shown under the first question in this section: whenever a -__dog__ object's __\-length__ option is set or retrieved, the underlying -__tail__ object's option is set or retrieved in turn\. - -Note that you can define an option name using the __option__ statement, or -you can define it using __delegate__; you can't do both\. - -## Can I delegate to an option with a different name? - -In the previous answer we delegated the __dog__'s __\-length__ option -down to its __tail__\. This is, of course, wrong\. The dog has a length, and -the tail has a length, and they are different\. What we'd really like to do is -give the __dog__ a __\-taillength__ option, but delegate it to the -__tail__'s __\-length__ option: - - snit::type dog { - delegate option -taillength to mytail as -length - - constructor {args} { - set mytail [tail %AUTO% -partof $self] - $self configurelist $args - } - } - -## How can I delegate any unrecognized method or option to a component object? - -It may happen that a Snit object gets most of its behavior from one of its -components\. This often happens with __snit::widgetadaptors__, for example, -where we wish to slightly the modify the behavior of an existing widget\. To -carry on with our __dog__ example, however, suppose that we have a -__snit::type__ called __animal__ that implements a variety of animal -behaviors\-\-moving, eating, sleeping, and so forth\. We want our __dog__ -objects to inherit these same behaviors, while adding dog\-like behaviors of its -own\. Here's how we can give a __dog__ methods and options of its own while -delegating all other methods and options to its __animal__ component: - - snit::type dog { - delegate option * to animal - delegate method * to animal - - option -akc 0 - - constructor {args} { - install animal using animal %AUTO% -name $self - $self configurelist $args - } - - method wag {} { - return "$self wags its tail" - } - } - -That's it\. A __dog__ is now an __animal__ that has a __\-akc__ option -and can __wag__ its tail\. - -Note that we don't need to specify the full list of method names or option names -that __animal__ will receive\. It gets anything __dog__ doesn't -recognize\-\-and if it doesn't recognize it either, it will simply throw an error, -just as it should\. - -You can also delegate all unknown type methods to a type component using -__delegate typemethod \*__\. - -## How can I delegate all but certain methods or options to a component? - -In the previous answer, we said that every __dog__ is an __animal__ by -delegating all unknown methods and options to the __animal__ component\. But -what if the __animal__ type has some methods or options that we'd like to -suppress? - -One solution is to explicitly delegate all the options and methods, and forgo -the convenience of __delegate method \*__ and __delegate option \*__\. But -if we wish to suppress only a few options or methods, there's an easier way: - - snit::type dog { - delegate option * to animal except -numlegs - delegate method * to animal except {fly climb} - - # ... - - constructor {args} { - install animal using animal %AUTO% -name $self -numlegs 4 - $self configurelist $args - } - - # ... - } - -Dogs have four legs, so we specify that explicitly when we create the -__animal__ component, and explicitly exclude __\-numlegs__ from the set -of delegated options\. Similarly, dogs can neither __fly__ nor __climb__, -so we exclude those __animal__ methods as shown\. - -## Can a hierarchical method be delegated? - -Yes; just specify multiple words in the delegated method's name: - - snit::type tail { - method wag {} {return "Wag, wag"} - method droop {} {return "Droop, droop"} - } - - snit::type dog { - delegate method {tail wag} to mytail - delegate method {tail droop} to mytail - - # ... - - constructor {args} { - install mytail using tail %AUTO% - $self configurelist $args - } - - # ... - } - -Unrecognized hierarchical methods can also be delegated; the following code -delegates all subcommands of the "tail" method to the "mytail" component: - - snit::type dog { - delegate method {tail *} to mytail - - # ... - } - -# WIDGETS - -## What is a snit::widget? - -A __snit::widget__ is the Snit version of what Tcl programmers usually call -a *megawidget*: a widget\-like object usually consisting of one or more Tk -widgets all contained within a Tk frame\. - -A __snit::widget__ is also a special kind of __snit::type__\. Just about -everything in this FAQ list that relates to __snit::types__ also applies to -__snit::widgets__\. - -## How do I define a snit::widget? - -__snit::widgets__ are defined using the __snit::widget__ command, just -as __snit::types__ are defined by the __snit::type__ command\. - -The body of the definition can contain all of the same kinds of statements, plus -a couple of others which will be mentioned below\. - -## How do snit::widgets differ from snit::types? - - - The name of an instance of a __snit::type__ can be any valid Tcl command - name, in any namespace\. The name of an instance of a __snit::widget__ - must be a valid Tk widget name, and its parent widget must already exist\. - - - An instance of a __snit::type__ can be destroyed by calling its - __destroy__ method\. Instances of a __snit::widget__ have no destroy - method; use the Tk __destroy__ command instead\. - - - Every instance of a __snit::widget__ has one predefined component called - its __hull__ component\. The hull is usually a Tk - __[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__ or __toplevel__ widget; - any other widgets created as part of the __snit::widget__ will usually - be contained within the hull\. - - - __snit::widget__s can have their options receive default values from - [THE TK OPTION DATABASE](#section19)\. - -## What is a hull component? - -Snit can't create a Tk widget object; only Tk can do that\. Thus, every instance -of a __snit::widget__ must be wrapped around a genuine Tk widget; this Tk -widget is called the *hull component*\. Snit effectively piggybacks the -behavior you define \(methods, options, and so forth\) on top of the hull -component so that the whole thing behaves like a standard Tk widget\. - -For __snit::widget__s the hull component must be a Tk widget that defines -the __\-class__ option\. - -__snit::widgetadaptor__s differ from __snit::widget__s chiefly in that -any kind of widget can be used as the hull component; see [WIDGET -ADAPTORS](#section18)\. - -## How can I set the hull type for a snit::widget? - -A __snit::widget__'s hull component will usually be a Tk -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__ widget; however, it may be any -Tk widget that defines the __\-class__ option\. You can explicitly choose the -hull type you prefer by including the __hulltype__ command in the widget -definition: - - snit::widget mytoplevel { - hulltype toplevel - - # ... - } - -If no __hulltype__ command appears, the hull will be a -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__\. - -By default, Snit recognizes the following hull types: the Tk widgets -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__, __labelframe__, -__toplevel__, and the Tile widgets __ttk::frame__, -__ttk::labelframe__, and __ttk::toplevel__\. To enable the use of some -other kind of widget as the hull type, you can __lappend__ the widget -command to the variable __snit::hulltypes__ \(always provided the widget -defines the __\-class__ option\. For example, suppose Tk gets a new widget -type called a __prettyframe__: - - lappend snit::hulltypes prettyframe - - snit::widget mywidget { - hulltype prettyframe - - # ... - } - -## How should I name widgets which are components of a snit::widget? - -Every widget, whether a genuine Tk widget or a Snit megawidget, has to have a -valid Tk window name\. When a __snit::widget__ is first created, its instance -name, __self__, is a Tk window name; however, if the __snit::widget__ is -used as the hull component by a __snit::widgetadaptor__ its instance name -will be changed to something else\. For this reason, every __snit::widget__ -method, constructor, destructor, and so forth is passed another implicit -argument, __win__, which is the window name of the megawidget\. Any children -should be named using __win__ as the root\. - -Thus, suppose you're writing a toolbar widget, a frame consisting of a number of -buttons placed side\-by\-side\. It might look something like this: - - snit::widget toolbar { - delegate option * to hull - - constructor {args} { - button $win.open -text Open -command [mymethod open] - button $win.save -text Save -command [mymethod save] - - # .... - - $self configurelist $args - - } - } - -See also the question on renaming objects, toward the top of this file\. - -# WIDGET ADAPTORS - -## What is a snit::widgetadaptor? - -A __snit::widgetadaptor__ is a kind of __snit::widget__\. Whereas a -__snit::widget__'s hull is automatically created and is always a Tk frame, a -__snit::widgetadaptor__ can be based on any Tk widget\-\-or on any Snit -megawidget, or even \(with luck\) on megawidgets defined using some other package\. - -It's called a *widget adaptor* because it allows you to take an existing -widget and customize its behavior\. - -## How do I define a snit::widgetadaptor? - -Use the __snit::widgetadaptor__ command\. The definition for a -__snit::widgetadaptor__ looks just like that for a __snit::type__ or -__snit::widget__, except that the constructor must create and install the -hull component\. - -For example, the following code creates a read\-only text widget by the simple -device of turning its __insert__ and __delete__ methods into no\-ops\. -Then, we define new methods, __ins__ and __del__, which get delegated to -the hull component as __insert__ and __delete__\. Thus, we've adapted the -text widget and given it new behavior while still leaving it fundamentally a -text widget\. - - ::snit::widgetadaptor rotext { - - constructor {args} { - # Create the text widget; turn off its insert cursor - installhull using text -insertwidth 0 - - # Apply any options passed at creation time. - $self configurelist $args - } - - # Disable the text widget's insert and delete methods, to - # make this readonly. - method insert {args} {} - method delete {args} {} - - # Enable ins and del as synonyms, so the program can insert and - # delete. - delegate method ins to hull as insert - delegate method del to hull as delete - - # Pass all other methods and options to the real text widget, so - # that the remaining behavior is as expected. - delegate method * to hull - delegate option * to hull - } - -The most important part is in the constructor\. Whereas __snit::widget__ -creates the hull for you, __snit::widgetadaptor__ cannot \-\- it doesn't know -what kind of widget you want\. So the first thing the constructor does is create -the hull component \(a Tk text widget in this case\), and then installs it using -the __installhull__ command\. - -*Note:* There is no instance command until you create one by installing a hull -component\. Any attempt to pass methods to __$self__ prior to calling -__installhull__ will fail\. - -## Can I adapt a widget created elsewhere in the program? - -Yes\. - -At times, it can be convenient to adapt a pre\-existing widget instead of -creating your own\. For example, the Bwidget __PagesManager__ widget manages -a set of __[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__ widgets, only one of -which is visible at a time\. The application chooses which -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__ is visible\. All of the These -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__s are created by the -__PagesManager__ itself, using its __add__ method\. It's convenient to -adapt these frames to do what we'd like them to do\. - -In a case like this, the Tk widget will already exist when the -__snit::widgetadaptor__ is created\. Snit provides an alternate form of the -__installhull__ command for this purpose: - - snit::widgetadaptor pageadaptor { - constructor {args} { - # The widget already exists; just install it. - installhull $win - - # ... - } - } - -## Can I adapt another megawidget? - -Maybe\. If the other megawidget is a __snit::widget__ or -__snit::widgetadaptor__, then yes\. If it isn't then, again, maybe\. You'll -have to try it and see\. You're most likely to have trouble with widget -destruction\-\-you have to make sure that your megawidget code receives the -____ event before the megawidget you're adapting does\. - -# THE TK OPTION DATABASE - -## What is the Tk option database? - -The Tk option database is a database of default option values maintained by Tk -itself; every Tk application has one\. The concept of the option database derives -from something called the X Windows resource database; however, the option -database is available in every Tk implementation, including those which do not -use the X Windows system \(e\.g\., Microsoft Windows\)\. - -Full details about the Tk option database are beyond the scope of this document; -both *Practical Programming in Tcl and Tk* by Welch, Jones, and Hobbs, and -*Effective Tcl/Tk Programming* by Harrison and McClennan\., have good -introductions to it\. - -Snit is implemented so that most of the time it will simply do the right thing -with respect to the option database, provided that the widget developer does the -right thing by Snit\. The body of this section goes into great deal about what -Snit requires\. The following is a brief statement of the requirements, for -reference\. - - - If the widget's default widget class is not what is desired, set it - explicitly using the __widgetclass__ statement in the widget definition\. - - - When defining or delegating options, specify the resource and class names - explicitly when necessary\. - - - Use the __installhull using__ command to create and install the hull for - __snit::widgetadaptor__s\. - - - Use the __install__ command to create and install all components which - are widgets\. - - - Use the __install__ command to create and install components which - aren't widgets if you'd like them to receive option values from the option - database\. - -The interaction of Tk widgets with the option database is a complex thing; the -interaction of Snit with the option database is even more so, and repays -attention to detail\. - -## Do snit::types use the Tk option database? - -No, they don't; querying the option database requires a Tk window name, and -__snit::type__s don't have one\. - -If you create an instance of a __snit::type__ as a component of a -__snit::widget__ or __snit::widgetadaptor__, on the other hand, and if -any options are delegated to the component, and if you use __install__ to -create and install it, then the megawidget will query the option database on the -__snit::type__'s behalf\. This might or might not be what you want, so take -care\. - -## What is my snit::widget's widget class? - -Every Tk widget has a "widget class": a name that is used when adding option -settings to the database\. For Tk widgets, the widget class is the same as the -widget command name with an initial capital\. For example, the widget class of -the Tk __button__ widget is __Button__\. - -Similarly, the widget class of a __snit::widget__ defaults to the -unqualified type name with the first letter capitalized\. For example, the widget -class of - - snit::widget ::mylibrary::scrolledText { ... } - -is __ScrolledText__\. - -The widget class can also be set explicitly using the __widgetclass__ -statement within the __snit::widget__ definition: - - snit::widget ::mylibrary::scrolledText { - widgetclass Text - - # ... - } - -The above definition says that a __scrolledText__ megawidget has the same -widget class as an ordinary __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ -widget\. This might or might not be a good idea, depending on how the rest of the -megawidget is defined, and how its options are delegated\. - -## What is my snit::widgetadaptor's widget class? - -The widget class of a __snit::widgetadaptor__ is just the widget class of -its hull widget; Snit has no control over this\. - -Note that the widget class can be changed only for -__[frame](\.\./\.\./\.\./\.\./index\.md\#frame)__ and __toplevel__ widgets, -which is why these are the valid hull types for __snit::widget__s\. - -Try to use __snit::widgetadaptor__s only to make small modifications to -another widget's behavior\. Then, it will usually not make sense to change the -widget's widget class anyway\. - -## What are option resource and class names? - -Every Tk widget option has three names: the option name, the resource name, and -the class name\. The option name begins with a hyphen and is all lowercase; it's -used when creating widgets, and with the __configure__ and __cget__ -commands\. - -The resource and class names are used to initialize option default values by -querying the option database\. The resource name is usually just the option name -minus the hyphen, but may contain uppercase letters at word boundaries; the -class name is usually just the resource name with an initial capital, but not -always\. For example, here are the option, resource, and class names for several -Tk __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget options: - - -background background Background - -borderwidth borderWidth BorderWidth - -insertborderwidth insertBorderWidth BorderWidth - -padx padX Pad - -As is easily seen, sometimes the resource and class names can be inferred from -the option name, but not always\. - -## What are the resource and class names for my megawidget's options? - -For options implicitly delegated to a component using __delegate option \*__, -the resource and class names will be exactly those defined by the component\. The -__configure__ method returns these names, along with the option's default -and current values: - - % snit::widget mytext { - delegate option * to text - - constructor {args} { - install text using text .text - # ... - } - - # ... - } - ::mytext - % mytext .text - .text - % .text configure -padx - -padx padX Pad 1 1 - % - -For all other options \(whether locally defined or explicitly delegated\), the -resource and class names can be defined explicitly, or they can be allowed to -have default values\. - -By default, the resource name is just the option name minus the hyphen; the the -class name is just the option name with an initial capital letter\. For example, -suppose we explicitly delegate "\-padx": - - % snit::widget mytext { - option -myvalue 5 - - delegate option -padx to text - delegate option * to text - - constructor {args} { - install text using text .text - # ... - } - - # ... - } - ::mytext - % mytext .text - .text - % .text configure -myvalue - -myvalue myvalue Myvalue 5 5 - % .text configure -padx - -padx padx Padx 1 1 - % - -Here the resource and class names are chosen using the default rules\. Often -these rules are sufficient, but in the case of "\-padx" we'd most likely prefer -that the option's resource and class names are the same as for the built\-in Tk -widgets\. This is easily done: - - % snit::widget mytext { - delegate option {-padx padX Pad} to text - - # ... - } - ::mytext - % mytext .text - .text - % .text configure -padx - -padx padX Pad 1 1 - % - -## How does Snit initialize my megawidget's locally\-defined options? - -The option database is queried for each of the megawidget's locally\-defined -options, using the option's resource and class name\. If the result isn't "", -then it replaces the default value given in widget definition\. In either case, -the default can be overridden by the caller\. For example, - - option add *Mywidget.texture pebbled - - snit::widget mywidget { - option -texture smooth - # ... - } - - mywidget .mywidget -texture greasy - -Here, __\-texture__ would normally default to "smooth", but because of the -entry added to the option database it defaults to "pebbled"\. However, the caller -has explicitly overridden the default, and so the new widget will be "greasy"\. - -## How does Snit initialize delegated options? - -That depends on whether the options are delegated to the hull, or to some other -component\. - -## How does Snit initialize options delegated to the hull? - -A __snit::widget__'s hull is a widget, and given that its class has been set -it is expected to query the option database for itself\. The only exception -concerns options that are delegated to it with a different name\. Consider the -following code: - - option add *Mywidget.borderWidth 5 - option add *Mywidget.relief sunken - option add *Mywidget.hullbackground red - option add *Mywidget.background green - - snit::widget mywidget { - delegate option -borderwidth to hull - delegate option -hullbackground to hull as -background - delegate option * to hull - # ... - } - - mywidget .mywidget - - set A [.mywidget cget -relief] - set B [.mywidget cget -hullbackground] - set C [.mywidget cget -background] - set D [.mywidget cget -borderwidth] - -The question is, what are the values of variables A, B, C and D? - -The value of A is "sunken"\. The hull is a Tk frame which has been given the -widget class __Mywidget__; it will automatically query the option database -and pick up this value\. Since the __\-relief__ option is implicitly delegated -to the hull, Snit takes no action\. - -The value of B is "red"\. The hull will automatically pick up the value "green" -for its __\-background__ option, just as it picked up the __\-relief__ -value\. However, Snit knows that __\-hullbackground__ is mapped to the hull's -__\-background__ option; hence, it queries the option database for -__\-hullbackground__ and gets "red" and updates the hull accordingly\. - -The value of C is also "red", because __\-background__ is implicitly -delegated to the hull; thus, retrieving it is the same as retrieving -__\-hullbackground__\. Note that this case is unusual; the __\-background__ -option should probably have been excluded using the delegate statement's -__except__ clause, or \(more likely\) delegated to some other component\. - -The value of D is "5", but not for the reason you think\. Note that as it is -defined above, the resource name for __\-borderwidth__ defaults to -__borderwidth__, whereas the option database entry is __borderWidth__, -in accordance with the standard Tk naming for this option\. As with -__\-relief__, the hull picks up its own __\-borderwidth__ option before -Snit does anything\. Because the option is delegated under its own name, Snit -assumes that the correct thing has happened, and doesn't worry about it any -further\. To avoid confusion, the __\-borderwidth__ option should have been -delegated like this: - - delegate option {-borderwidth borderWidth BorderWidth} to hull - -For __snit::widgetadaptor__s, the case is somewhat altered\. Widget adaptors -retain the widget class of their hull, and the hull is not created automatically -by Snit\. Instead, the __snit::widgetadaptor__ must call __installhull__ -in its constructor\. The normal way to do this is as follows: - - snit::widgetadaptor mywidget { - # ... - constructor {args} { - # ... - installhull using text -foreground white - # ... - } - # ... - } - -In this case, the __installhull__ command will create the hull using a -command like this: - - set hull [text $win -foreground white] - -The hull is a __[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget, so its -widget class is __Text__\. Just as with __snit::widget__ hulls, Snit -assumes that it will pick up all of its normal option values automatically, -without help from Snit\. Options delegated from a different name are initialized -from the option database in the same way as described above\. - -In earlier versions of Snit, __snit::widgetadaptor__s were expected to call -__installhull__ like this: - - installhull [text $win -foreground white] - -This form still works\-\-but Snit will not query the option database as described -above\. - -## How does Snit initialize options delegated to other components? - -For hull components, Snit assumes that Tk will do most of the work -automatically\. Non\-hull components are somewhat more complicated, because they -are matched against the option database twice\. - -A component widget remains a widget still, and is therefore initialized from the -option database in the usual way\. A -__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget remains a -__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ widget whether it is a component -of a megawidget or not, and will be created as such\. - -But then, the option database is queried for all options delegated to the -component, and the component is initialized accordingly\-\-provided that the -__install__ command is used to create it\. - -Before option database support was added to Snit, the usual way to create a -component was to simply create it in the constructor and assign its command name -to the component variable: - - snit::widget mywidget { - delegate option -background to myComp - - constructor {args} { - set myComp [text $win.text -foreground black] - } - } - -The drawback of this method is that Snit has no opportunity to initialize the -component properly\. Hence, the following approach is now used: - - snit::widget mywidget { - delegate option -background to myComp - - constructor {args} { - install myComp using text $win.text -foreground black - } - } - -The __install__ command does the following: - - - Builds a list of the options explicitly included in the __install__ - command\-\-in this case, __\-foreground__\. - - - Queries the option database for all options delegated explicitly to the - named component\. - - - Creates the component using the specified command, after inserting into it a - list of options and values read from the option database\. Thus, the - explicitly included options \(like __\-foreground__\) will override - anything read from the option database\. - - - If the widget definition implicitly delegated options to the component using - __delegate option \*__, then Snit calls the newly created component's - __configure__ method to receive a list of all of the component's - options\. From this Snit builds a list of options implicitly delegated to the - component which were not explicitly included in the __install__ command\. - For all such options, Snit queries the option database and configures the - component accordingly\. - -You don't really need to know all of this; just use __install__ to install -your components, and Snit will try to do the right thing\. - -## What happens if I install a non\-widget as a component of widget? - -A __snit::type__ never queries the option database\. However, a -__snit::widget__ can have non\-widget components\. And if options are -delegated to those components, and if the __install__ command is used to -install those components, then they will be initialized from the option database -just as widget components are\. - -However, when used within a megawidget, __install__ assumes that the created -component uses a reasonably standard widget\-like creation syntax\. If it doesn't, -don't use __install__\. - -# ENSEMBLE COMMANDS - -## What is an ensemble command? - -An ensemble command is a command with subcommands\. Snit objects are all ensemble -commands; however, the term more usually refers to commands like the standard -Tcl commands __[string](\.\./\.\./\.\./\.\./index\.md\#string)__, -__[file](\.\./\.\./\.\./\.\./index\.md\#file)__, and __clock__\. In a sense, -these are singleton objects\-\-there's only one instance of them\. - -## How can I create an ensemble command using Snit? - -There are two ways\-\-as a __snit::type__, or as an instance of a -__snit::type__\. - -## How can I create an ensemble command using an instance of a snit::type? - -Define a type whose [INSTANCE METHODS](#section5) are the subcommands of -your ensemble command\. Then, create an instance of the type with the desired -name\. - -For example, the following code uses [DELEGATION](#section16) to create a -work\-alike for the standard __[string](\.\./\.\./\.\./\.\./index\.md\#string)__ -command: - - snit::type ::mynamespace::mystringtype { - delegate method * to stringhandler - - constructor {} { - set stringhandler string - } - } - - ::mynamespace::mystringtype mystring - -We create the type in a namespace, so that the type command is hidden; then we -create a single instance with the desired name\-\- __mystring__, in this case\. - -This method has two drawbacks\. First, it leaves the type command floating about\. -More seriously, your shiny new ensemble command will have __info__ and -__destroy__ subcommands that you probably have no use for\. But read on\. - -## How can I create an ensemble command using a snit::type? - -Define a type whose [TYPE METHODS](#section9) are the subcommands of your -ensemble command\. - -For example, the following code uses [DELEGATION](#section16) to create a -work\-alike for the standard __[string](\.\./\.\./\.\./\.\./index\.md\#string)__ -command: - - snit::type mystring { - delegate typemethod * to stringhandler - - typeconstructor { - set stringhandler string - } - } - -Now the type command itself is your ensemble command\. - -This method has only one drawback, and though it's major, it's also -surmountable\. Your new ensemble command will have __create__, __info__ -and __destroy__ subcommands you don't want\. And worse yet, since the -__create__ method can be implicit, users of your command will accidentally -be creating instances of your __mystring__ type if they should mispell one -of the subcommands\. The command will succeed\-\-the first time\-\-but won't do -what's wanted\. This is very bad\. - -The work around is to set some [PRAGMAS](#section21), as shown here: - - snit::type mystring { - pragma -hastypeinfo no - pragma -hastypedestroy no - pragma -hasinstances no - - delegate typemethod * to stringhandler - - typeconstructor { - set stringhandler string - } - } - -Here we've used the __pragma__ statement to tell Snit that we don't want the -__info__ typemethod or the __destroy__ typemethod, and that our type has -no instances; this eliminates the __create__ typemethod and all related -code\. As a result, our ensemble command will be well\-behaved, with no unexpected -subcommands\. - -# PRAGMAS - -## What is a pragma? - -A pragma is an option you can set in your type definitions that affects how the -type is defined and how it works once it is defined\. - -## How do I set a pragma? - -Use the __pragma__ statement\. Each pragma is an option with a value; each -time you use the __pragma__ statement you can set one or more of them\. - -## How can I get rid of the "info" type method? - -Set the __\-hastypeinfo__ pragma to __no__: - - snit::type dog { - pragma -hastypeinfo no - # ... - } - -Snit will refrain from defining the __info__ type method\. - -## How can I get rid of the "destroy" type method? - -Set the __\-hastypedestroy__ pragma to __no__: - - snit::type dog { - pragma -hastypedestroy no - # ... - } - -Snit will refrain from defining the __destroy__ type method\. - -## How can I get rid of the "create" type method? - -Set the __\-hasinstances__ pragma to __no__: - - snit::type dog { - pragma -hasinstances no - # ... - } - -Snit will refrain from defining the __create__ type method; if you call the -type command with an unknown method name, you'll get an error instead of a new -instance of the type\. - -This is useful if you wish to use a __snit::type__ to define an ensemble -command rather than a type with instances\. - -Pragmas __\-hastypemethods__ and __\-hasinstances__ cannot both be false -\(or there'd be nothing left\)\. - -## How can I get rid of type methods altogether? - -Normal Tk widget type commands don't have subcommands; all they do is create -widgets\-\-in Snit terms, the type command calls the __create__ type method -directly\. To get the same behavior from Snit, set the __\-hastypemethods__ -pragma to __no__: - - snit::type dog { - pragma -hastypemethods no - #... - } - - # Creates ::spot - dog spot - - # Tries to create an instance called ::create - dog create spot - -Pragmas __\-hastypemethods__ and __\-hasinstances__ cannot both be false -\(or there'd be nothing left\)\. - -## Why can't I create an object that replaces an old object with the same name? - -Up until Snit 0\.95, you could use any name for an instance of a -__snit::type__, even if the name was already in use by some other object or -command\. You could do the following, for example: - - snit::type dog { ... } - - dog proc - -You now have a new dog named "proc", which is probably not something that you -really wanted to do\. As a result, Snit now throws an error if your chosen -instance name names an existing command\. To restore the old behavior, set the -__\-canreplace__ pragma to __yes__: - - snit::type dog { - pragma -canreplace yes - # ... - } - -## How can I make my simple type run faster? - -In Snit 1\.x, you can set the __\-simpledispatch__ pragma to __yes__\. - -Snit 1\.x method dispatch is both flexible and fast, but the flexibility comes -with a price\. If your type doesn't require the flexibility, the -__\-simpledispatch__ pragma allows you to substitute a simpler dispatch -mechanism that runs quite a bit faster\. The limitations are these: - - - Methods cannot be delegated\. - - - __uplevel__ and __upvar__ do not work as expected: the caller's - scope is two levels up rather than one\. - - - The option\-handling methods \(__cget__, __configure__, and - __configurelist__\) are very slightly slower\. - -In Snit 2\.2, the __\-simpledispatch__ macro is obsolete, and ignored; all -Snit 2\.2 method dispatch is faster than Snit 1\.x's __\-simpledispatch__\. - -# MACROS - -## What is a macro? - -A Snit macro is nothing more than a Tcl proc that's defined in the Tcl -interpreter used to compile Snit type definitions\. - -## What are macros good for? - -You can use Snit macros to define new type definition syntax, and to support -conditional compilation\. - -## How do I do conditional compilation? - -Suppose you want your type to use a fast C extension if it's available; -otherwise, you'll fallback to a slower Tcl implementation\. You want to define -one set of methods in the first case, and another set in the second case\. But -how can your type definition know whether the fast C extension is available or -not? - -It's easily done\. Outside of any type definition, define a macro that returns 1 -if the extension is available, and 0 otherwise: - - if {$gotFastExtension} { - snit::macro fastcode {} {return 1} - } else { - snit::macro fastcode {} {return 0} - } - -Then, use your macro in your type definition: - - snit::type dog { - - if {[fastcode]} { - # Fast methods - method bark {} {...} - method wagtail {} {...} - } else { - # Slow methods - method bark {} {...} - method wagtail {} {...} - } - } - -## How do I define new type definition syntax? - -Use a macro\. For example, your __snit::widget__'s __\-background__ option -should be propagated to a number of component widgets\. You could implement that -like this: - - snit::widget mywidget { - option -background -default white -configuremethod PropagateBackground - - method PropagateBackground {option value} { - $comp1 configure $option $value - $comp2 configure $option $value - $comp3 configure $option $value - } - } - -For one option, this is fine; if you've got a number of options, it becomes -tedious and error prone\. So package it as a macro: - - snit::macro propagate {option "to" components} { - option $option -configuremethod Propagate$option - - set body "\n" - - foreach comp $components { - append body "\$$comp configure $option \$value\n" - } - - method Propagate$option {option value} $body - } - -Then you can use it like this: - - snit::widget mywidget { - option -background default -white - option -foreground default -black - - propagate -background to {comp1 comp2 comp3} - propagate -foreground to {comp1 comp2 comp3} - } - -## Are there are restrictions on macro names? - -Yes, there are\. You can't redefine any standard Tcl commands or Snit type -definition statements\. You can use any other command name, including the name of -a previously defined macro\. - -If you're using Snit macros in your application, go ahead and name them in the -global namespace, as shown above\. But if you're using them to define types or -widgets for use by others, you should define your macros in the same namespace -as your types or widgets\. That way, they won't conflict with other people's -macros\. - -If my fancy __snit::widget__ is called __::mylib::mywidget__, for -example, then I should define my __propagate__ macro as -__::mylib::propagate__: - - snit::macro mylib::propagate {option "to" components} { ... } - - snit::widget ::mylib::mywidget { - option -background default -white - option -foreground default -black - - mylib::propagate -background to {comp1 comp2 comp3} - mylib::propagate -foreground to {comp1 comp2 comp3} - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *snit* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[BWidget](\.\./\.\./\.\./\.\./index\.md\#bwidget), [C\+\+](\.\./\.\./\.\./\.\./index\.md\#c\_), -[Incr Tcl](\.\./\.\./\.\./\.\./index\.md\#incr\_tcl), -[adaptors](\.\./\.\./\.\./\.\./index\.md\#adaptors), -[class](\.\./\.\./\.\./\.\./index\.md\#class), [mega -widget](\.\./\.\./\.\./\.\./index\.md\#mega\_widget), -[object](\.\./\.\./\.\./\.\./index\.md\#object), [object -oriented](\.\./\.\./\.\./\.\./index\.md\#object\_oriented), -[widget](\.\./\.\./\.\./\.\./index\.md\#widget), [widget -adaptors](\.\./\.\./\.\./\.\./index\.md\#widget\_adaptors) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2003\-2006, by William H\. Duquette DELETED embedded/md/tcllib/files/modules/soundex/soundex.md Index: embedded/md/tcllib/files/modules/soundex/soundex.md ================================================================== --- embedded/md/tcllib/files/modules/soundex/soundex.md +++ embedded/md/tcllib/files/modules/soundex/soundex.md @@ -1,93 +0,0 @@ - -[//000000001]: # (soundex \- Soundex) -[//000000002]: # (Generated from file 'soundex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © ????, Algorithm: Donald E\. Knuth) -[//000000004]: # (Copyright © 2003, Documentation: Andreas Kupries ) -[//000000005]: # (Copyright © 1998, Tcl port: Evan Rempel ) -[//000000006]: # (soundex\(n\) 1\.0 tcllib "Soundex") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -soundex \- Soundex - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require soundex ?1\.0? - -[__::soundex::knuth__ *string*](#1) - -# DESCRIPTION - -This package provides soundex algorithms which allow the comparison of words -based on their phonetic likeness\. - -Currently only an algorithm by Knuth is provided, which is tuned to english -names and words\. - - - __::soundex::knuth__ *string* - - Computes the soundex code of the input *string* using Knuth's algorithm - and returns it as the result of the command\. - -# EXAMPLES - - % ::soundex::knuth Knuth - K530 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *soundex* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[knuth](\.\./\.\./\.\./\.\./index\.md\#knuth), -[soundex](\.\./\.\./\.\./\.\./index\.md\#soundex), [text -comparison](\.\./\.\./\.\./\.\./index\.md\#text\_comparison), [text -likeness](\.\./\.\./\.\./\.\./index\.md\#text\_likeness) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © ????, Algorithm: Donald E\. Knuth -Copyright © 2003, Documentation: Andreas Kupries -Copyright © 1998, Tcl port: Evan Rempel DELETED embedded/md/tcllib/files/modules/stooop/stooop.md Index: embedded/md/tcllib/files/modules/stooop/stooop.md ================================================================== --- embedded/md/tcllib/files/modules/stooop/stooop.md +++ embedded/md/tcllib/files/modules/stooop/stooop.md @@ -1,256 +0,0 @@ - -[//000000001]: # (stooop \- Simple Tcl Only Object Oriented Programming) -[//000000002]: # (Generated from file 'stooop\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (stooop\(n\) 4\.4\.1 tcllib "Simple Tcl Only Object Oriented Programming") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -stooop \- Object oriented extension\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [DEBUGGING](#section2) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.3 -package require stooop ?4\.4\.1? - -[__::stooop::class__ *name body*](#1) -[__::stooop::new__ *class* ?*arg arg \.\.\.*?](#2) -[__::stooop::delete__ *object* ?*object \.\.\.*?](#3) -[__::stooop::virtual__ __proc__ *name* \{__this__ ?*arg arg \.\.\.*?\} ?*body*?](#4) -[__::stooop::classof__ *object*](#5) -[__::stooop::new__ *object*](#6) -[__::stooop::printObjects__ ?*pattern*?](#7) -[__::stooop::record__](#8) -[__::stooop::report__ ?*pattern*?](#9) - -# DESCRIPTION - -This package provides commands to extend Tcl in an object oriented manner, using -a familiar C\+\+ like syntax and behaviour\. Stooop only introduces a few new -commands: __[class](\.\./\.\./\.\./\.\./index\.md\#class)__, __new__, -__delete__, __virtual__ and __classof__\. Along with a few coding -conventions, that is basically all you need to know to use stooop\. Stooop is -meant to be as simple to use as possible\. - -This manual is very succinct and is to be used as a quick reminder for the -programmer, who should have read the thorough -[stooop\_man\.html](stooop\_man\.html) HTML documentation at this point\. - - - __::stooop::class__ *name body* - - This command creates a class\. The body, similar in contents to a Tcl - namespace \(which a class actually also is\), contains member procedure - definitions\. Member procedures can also be defined outside the class body, - by prefixing their name with __class::__, as you would proceed with - namespace procedures\. - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *class* \{__this__ ?*arg arg \.\.\.*?\} ?*base* \{?*arg arg \.\.\.*?\} \.\.\.? *body* - - This is the constructor procedure for the class\. It is invoked following - a __new__ invocation on the class\. It must have the same name as the - class and a first argument named __this__\. Any number of base - classes specifications, including arguments to be passed to their - constructor, are allowed before the actual body of the procedure\. - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ ~*class* \{__this__\} *body* - - This is the destructor procedure for the class\. It is invoked following - a __delete__ invocation\. Its name must be the concatenation of a - single __~__ character followed by the class name \(as in C\+\+\)\. It - must have a single argument named __this__\. - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* \{__this__ ?*arg arg \.\.\.*?\} *body* - - This is a member procedure of the class, as its first argument is named - __this__\. It allows a simple access of member data for the object - referenced by __this__ inside the procedure\. For example: - - set ($this,data) 0 - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *name* \{?*arg arg \.\.\.*?\} *body* - - This is a static \(as in C\+\+\) member procedure of the class, as its first - argument is not named __this__\. Static \(global\) class data can be - accessed as in: - - set (data) 0 - - * __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ *class* \{__this copy__\} *body* - - This is the optional copy procedure for the class\. It must have the same - name as the class and exactly 2 arguments named __this__ and - __copy__\. It is invoked following a __new__ invocation on an - existing object of the class\. - - - __::stooop::new__ *class* ?*arg arg \.\.\.*? - - This command is used to create an object\. The first argument is the class - name and is followed by the arguments needed by the corresponding class - constructor\. A unique identifier for the object just created is returned\. - - - __::stooop::delete__ *object* ?*object \.\.\.*? - - This command is used to delete one or several objects\. It takes one or more - object identifiers as argument\(s\)\. - - - __::stooop::virtual__ __proc__ *name* \{__this__ ?*arg arg \.\.\.*?\} ?*body*? - - The __virtual__ specifier may be used on member procedures to achieve - dynamic binding\. A procedure in a base class can then be redefined - \(overloaded\) in the derived class\(es\)\. If the base class procedure is - invoked on an object, it is actually the derived class procedure which is - invoked, if it exists\. If the base class procedure has no body, then it is - considered to be a pure virtual and the derived class procedure is always - invoked\. - - - __::stooop::classof__ *object* - - This command returns the class of the existing object passed as single - parameter\. - - - __::stooop::new__ *object* - - This command is used to create an object by copying an existing object\. The - copy constructor of the corresponding class is invoked if it exists, - otherwise a simple copy of the copied object data members is performed\. - -# DEBUGGING - - - Environment variables - - * __STOOOPCHECKDATA__ - - Setting this variable to any true value will cause stooop to check for - invalid member or class data access\. - - * __STOOOPCHECKPROCEDURES__ - - Setting this variable to any true value will cause stooop to check for - invalid member procedure arguments and pure interface classes - instanciation\. - - * __STOOOPCHECKALL__ - - Setting this variable to any true value will cause stooop to activate - both procedure and data member checking\. - - * __STOOOPCHECKOBJECTS__ - - Setting this variable to any true value will cause stooop to activate - object checking\. The following stooop namespace procedures then become - available for debugging: __printObjects__, - __[record](\.\./\.\./\.\./\.\./index\.md\#record)__ and - __[report](\.\./report/report\.md)__\. - - * __STOOOPTRACEPROCEDURES__ - - Setting this environment variable to either __stdout__, - __stderr__ or a file name, activates procedure tracing\. The stooop - library will then output to the specified channel 1 line of - informational text for each member procedure invocation\. - - * __STOOOPTRACEPROCEDURESFORMAT__ - - Defines the trace procedures output format\. Defaults to __"class: %C, - procedure: %p, object: %O, arguments: %a"__\. - - * __STOOOPTRACEDATA__ - - Setting this environment variable to either __stdout__, - __stderr__ or a file name, activates data tracing\. The stooop - library will then output to the specified channel 1 line of - informational text for each member data access\. - - * __STOOOPTRACEDATAFORMAT__ - - Defines the trace data output format\. Defaults to __"class: %C, - procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: - %v"__\. - - * __STOOOPTRACEDATAOPERATIONS__ - - When tracing data output, by default, all read, write and unsetting - accesses are reported, but the user can set this variable to any - combination of the letters __r__, __w__, and __u__ for more - specific tracing \(please refer to the - __[trace](\.\./\.\./\.\./\.\./index\.md\#trace)__ Tcl manual page for more - information\)\. - - * __STOOOPTRACEALL__ - - Setting this environment variable to either __stdout__, - __stderr__ or a file name, enables both procedure and data tracing\. - - - __::stooop::printObjects__ ?*pattern*? - - Prints an ordered list of existing objects, in creation order, oldest first\. - Each output line contains the class name, object identifier and the - procedure within which the creation occurred\. The optional pattern argument - \(as in the Tcl __string match__ command\) can be used to limit the output - to matching class names\. - - - __::stooop::record__ - - When invoked, a snapshot of all existing stooop objects is taken\. Reporting - can then be used at a later time to see which objects were created or - deleted in the interval\. - - - __::stooop::report__ ?*pattern*? - - Prints the created and deleted objects since the __::stooop::record__ - procedure was invoked last\. If present, the pattern argument limits the - output to matching class names\. - -# EXAMPLES - -Please see the full HTML documentation in -[stooop\_man\.html](stooop\_man\.html)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stooop* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[C\+\+](\.\./\.\./\.\./\.\./index\.md\#c\_), [class](\.\./\.\./\.\./\.\./index\.md\#class), -[object](\.\./\.\./\.\./\.\./index\.md\#object), [object -oriented](\.\./\.\./\.\./\.\./index\.md\#object\_oriented) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/stooop/switched.md Index: embedded/md/tcllib/files/modules/stooop/switched.md ================================================================== --- embedded/md/tcllib/files/modules/stooop/switched.md +++ embedded/md/tcllib/files/modules/stooop/switched.md @@ -1,293 +0,0 @@ - -[//000000001]: # (switched \- Simple Tcl Only Object Oriented Programming) -[//000000002]: # (Generated from file 'switched\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (switched\(n\) 2\.2\.1 tcllib "Simple Tcl Only Object Oriented Programming") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -switched \- switch/option management\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.3 -package require switched ?2\.2\.1? - -[____ __complete__ *this*](#1) -[____ __options__ *this*](#2) -[____ __set\-__option____ *this* *value*](#3) - -# DESCRIPTION - -The __switched__ class serves as base class for user classes with switch / -option configuration procedures\. It provides facilities for managing options -through a simple interface\. - -For example: - - set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel] - puts "my car was running on [switched::cget $vehicle -fuel]" - switched::configure $vehicle -power 40 -fuel electricity - puts "but is now running on clean [switched::cget $vehicle -fuel]" - -Of course, as you might have guessed, the __car__ class is derived from the -__switched__ class\. Let us see how it works: - - class car { - proc car {this args} switched {$args} { - # car specific initialization code here - switched::complete $this - } - ... - } - -The switched class constructor takes the optional configuration option / value -pairs as parameters\. The switched class layer then completely manages the -switched options: it checks their validity, stores their values and provides a -clean interface to the user layer configuration setting procedures\. - -The switched class members available to the programmer are: - - - ____ __complete__ *this* - - This procedure is used to tell the switched layer that the derived class - object \(a car in the examples\) is completely built\. At that time, the - initial configuration of the switched object occurs, using default option - values \(see procedure __options__\) eventually overridden by construction - time values, passed at the time of the __new__ operator invocation\. This - procedure must be called only once, usually around or at the end of the - derived class constructor\. \(*Note*: Also check the __complete__ data - member later in this chapter\)\. - - - ____ __options__ *this* - - This procedure must return the configuration description for *all* options - that the switched object will accept\. It is a pure virtual member procedure - and therefore its implementation is *mandatory* in the derived class - layer\. The procedure must return a list of lists\. Each list pertains to a - single option and is composed of the switch name, the default value for the - option and an optional initial value\. For example: - - class car { - ... - proc options {this} { - return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ] - } - proc set-fuel {this value} { - ... - } - ... - } - - In this case, 4 options are specified: __fuel__, __length__, - __power__ and __width__\. The default and initial values for the - __fuel__ option are identical and set to __petrol__\. For the other - options, values are all empty\. - - For each option, there must be a corresponding __set\-__option____ - procedure defined in the derived class layer\. For example, since we defined - a __fuel__ option, there is a __set\-fuel__ procedure in the car - class\. The parameters always are the object identifier \(since this is not a - static procedure, but rather a dynamically defined virtual one\), followed by - the new value for the option\. A __set\-__option____ procedure is only - invoked if the new value differs from the current one \(a caching scheme for - improving performance\), or if there is no initial value set in the - __options__ procedure for that option\. - - In this procedure, if the initial value differs from the default value or is - omitted, then initial configuration is forced and the corresponding - __set\-__option____ procedure is invoked by the switched - __complete__ procedure located at the end of the derived class - constructor\. For example: - - class car { - ... - proc options {this} { - return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ] - } - ... - } - - In this case, configuration is forced on the __fuel__ and __power__ - options, that is the corresponding __set\-__option____ procedures - will be invoked when the switched object is constructed \(see - __set\-__option____ procedures documentation below\)\. - - For the __fuel__ option, since there is no initial value, the - __set\-__fuel____ procedure is called with the default value - \(__petrol__\) as argument\. For the __power__ option, since the - initial value differs from the default value, the __set\-__power____ - procedure is called with the initial value as argument \(__50__\)\. - - For the other options, since the initial values \(last elements of the option - lists\) are identical to their default values, the corresponding - __set\-__option____ procedures will not be invoked\. It is the - programmer's responsibility to insure that the initial option values are - correct\. - - - ____ __set\-__option____ *this* *value* - - These procedures may be viewed as dynamic virtual functions\. There must be - one implementation per supported option, as returned by the __options__ - procedure\. For example: - - class car { - ... - proc options {this} { - return [list ... - [list -width {} {}] ] - } - ... - proc set-width {this value} { - ... - } - ... - } - - Since the __\-width__ option was listed in the __options__ procedure, - a __set\-width__ procedure implementation is provided, which of course - would proceed to set the width of the car \(and would modify the looks of a - graphical representation, for example\)\. - - As you add a supported __option__ in the list returned by the - __options__ procedure, the corresponding __set\-__option____ - procedure may be called as soon as the switched object is complete, which - occurs when the switched level __complete__ procedure is invoked\. For - example: - - class car { - proc car {this args} switched {args} { - ... - switched::complete $this - } - ... - proc options {this} { - return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ] - } - proc set-fuel {this value} { - ... - } - proc set-length {this value} { - ... - } - proc set-power {this value} { - ... - } - proc set-width {this value} { - ... - } - } - - new car - - In this case, a new car is created with no options, which causes the car - constructor to be called, which in turns calls the switched level - __complete__ procedure after the car object layer is completely - initialized\. At this point, since there are no initial values in any option - list in the options procedure, the __set\-fuel__ procedure is called with - its default value of __petrol__ as parameter, followed by the - __set\-length__ call with __4\.5__ value, __set\-power__ with - __350__ value and finally with __set\-width__ with __1\.8__ as - parameter\. This is a good way to test the __set\-__option____ - procedures when debugging, and when done, just fill\-in the initial option - values\. - - The switched layer checks that an option is valid \(that is, listed in the - __options__ procedure\) but obviously does not check the validity of the - value passed to the __set\-__option____ procedure, which should throw - an error \(for example by using the Tcl error command\) if the value is - invalid\. - - The switched layer also keeps track of the options current values, so that a - __set\-__option____ procedure is called only when the corresponding - option value passed as parameter is different from the current value \(see - __\-option__ data members description\)\. - - - __\-option__ - - The __\-option__ data member is an options current value\. There is one - for each option listed in the options procedure\. It is a read\-only value - which the switched layer checks against when an option is changed\. It is - rarely used at the layer derived from switched, except in the few cases, - such as in the following example: - - ... - proc car::options {this} { - return { - ... - {-manufacturer {} {}} - ... - } - } - - proc car::set-manufacturer {this value} {} - - proc car::printData {this} { - puts "manufacturer: $switched::($this,-manufacturer)" - ... - } - - In this case, the manufacturer's name is stored at the switched layer level - \(this is why the set\-manufacturer procedure has nothing to do\) and later - retrieved in the printData procedure\. - - - __complete__ - - The __complete__ data member \(not to be confused with the - __complete__ procedure\) is a boolean\. Its initial value is __false__ - and it is set to __true__ at the very end of the switched - __complete__ procedure\. It becomes useful when some options should be - set at construction time only and not dynamically, as the following example - shows: - - proc car::set-width {this value} { - if {$switched::($this,complete)} { - error {option -width cannot be set dynamically} - } - ... - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stooop* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[C\+\+](\.\./\.\./\.\./\.\./index\.md\#c\_), [class](\.\./\.\./\.\./\.\./index\.md\#class), -[object](\.\./\.\./\.\./\.\./index\.md\#object), [object -oriented](\.\./\.\./\.\./\.\./index\.md\#object\_oriented) - -# CATEGORY - -Programming tools DELETED embedded/md/tcllib/files/modules/string/token.md Index: embedded/md/tcllib/files/modules/string/token.md ================================================================== --- embedded/md/tcllib/files/modules/string/token.md +++ embedded/md/tcllib/files/modules/string/token.md @@ -1,140 +0,0 @@ - -[//000000001]: # (string::token \- Text and string utilities) -[//000000002]: # (Generated from file 'token\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (string::token\(n\) 1 tcllib "Text and string utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -string::token \- Regex based iterative lexing - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require string::token ?1? -package require fileutil - -[__::string token text__ *lex* *string*](#1) -[__::string token file__ *lex* *path*](#2) -[__::string token chomp__ *lex* *startvar* *string* *resultvar*](#3) - -# DESCRIPTION - -This package provides commands for regular expression based lexing -\(tokenization\) of strings\. - -The complete set of procedures is described below\. - - - __::string token text__ *lex* *string* - - This command takes an ordered dictionary *lex* mapping regular expressions - to labels, and tokenizes the *string* according to this dictionary\. - - The result of the command is a list of tokens, where each token is a - 3\-element list of label, start\- and end\-index in the *string*\. - - The command will throw an error if it is not able to tokenize the whole - string\. - - - __::string token file__ *lex* *path* - - This command is a convenience wrapper around __::string token text__ - above, and __fileutil::cat__, enabling the easy tokenization of whole - files\. *Note* that this command loads the file wholly into memory before - starting to process it\. - - If the file is too large for this mode of operation a command directly based - on __::string token chomp__ below will be necessary\. - - - __::string token chomp__ *lex* *startvar* *string* *resultvar* - - This command is the work horse underlying __::string token text__ above\. - It is exposed to enable users to write their own lexers, which, for example - may apply different lexing dictionaries according to some internal state, - etc\. - - The command takes an ordered dictionary *lex* mapping regular expressions - to labels, a variable *startvar* which indicates where to start lexing in - the input *string*, and a result variable *resultvar* to extend\. - - The result of the command is a tri\-state numeric code indicating one of - - * __0__ - - No token found\. - - * __1__ - - Token found\. - - * __2__ - - End of string reached\. - - Note that recognition of a token from *lex* is started at the character - index in *startvar*\. - - If a token was recognized \(status __1__\) the command will update the - index in *startvar* to point to the first character of the *string* past - the recognized token, and it will further extend the *resultvar* with a - 3\-element list containing the label associated with the regular expression - of the token, and the start\- and end\-character\-indices of the token in - *string*\. - - Neither *startvar* nor *resultvar* will be updated if no token is - recognized at all\. - - Note that the regular expressions are applied \(tested\) in the order they are - specified in *lex*, and the first matching pattern stops the process\. - Because of this it is recommended to specify the patterns to lex with from - the most specific to the most general\. - - Further note that all regex patterns are implicitly prefixed with the - constraint escape __A__ to ensure that a match starts exactly at the - character index found in *startvar*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[lexing](\.\./\.\./\.\./\.\./index\.md\#lexing), -[regex](\.\./\.\./\.\./\.\./index\.md\#regex), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[tokenization](\.\./\.\./\.\./\.\./index\.md\#tokenization) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/string/token_shell.md Index: embedded/md/tcllib/files/modules/string/token_shell.md ================================================================== --- embedded/md/tcllib/files/modules/string/token_shell.md +++ embedded/md/tcllib/files/modules/string/token_shell.md @@ -1,170 +0,0 @@ - -[//000000001]: # (string::token::shell \- Text and string utilities) -[//000000002]: # (Generated from file 'token\_shell\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (string::token::shell\(n\) 1\.2 tcllib "Text and string utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -string::token::shell \- Parsing of shell command line - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.5 -package require string::token::shell ?1\.2? -package require string::token ?1? -package require fileutil - -[__::string token shell__ ?__\-indices__? ?__\-partial__? ?\-\-? *string*](#1) - -# DESCRIPTION - -This package provides a command which parses a line of text using basic -__sh__\-syntax into a list of words\. - -The complete set of procedures is described below\. - - - __::string token shell__ ?__\-indices__? ?__\-partial__? ?\-\-? *string* - - This command parses the input *string* under the assumption of it - following basic __sh__\-syntax\. The result of the command is a list of - words in the *string*\. An error is thrown if the input does not follow the - allowed syntax\. The behaviour can be modified by specifying any of the two - options __\-indices__ and __\-partial__\. - - * __\-\-__ - - When specified option parsing stops at this point\. This option is needed - if the input *string* may start with dash\. In other words, this is - pretty much required if *string* is user input\. - - * __\-indices__ - - When specified the output is not a list of words, but a list of 4\-tuples - describing the words\. Each tuple contains the type of the word, its - start\- and end\-indices in the input, and the actual text of the word\. - - Note that the length of the word as given by the indices can differ from - the length of the word found in the last element of the tuple\. The - indices describe the words extent in the input, including delimiters, - intra\-word quoting, etc\. whereas for the actual text of the word - delimiters are stripped, intra\-word quoting decoded, etc\. - - The possible token types are - - + __PLAIN__ - - Plain word, not quoted\. - - + __D:QUOTED__ - - Word is delimited by double\-quotes\. - - + __S:QUOTED__ - - Word is delimited by single\-quotes\. - - + __D:QUOTED:PART__ - - + __S:QUOTED:PART__ - - Like the previous types, but the word has no closing quote, i\.e\. is - incomplete\. These token types can occur if and only if the option - __\-partial__ was specified, and only for the last word of the - result\. If the option __\-partial__ was not specified such - incomplete words cause the command to thrown an error instead\. - - * __\-partial__ - - When specified the parser will accept an incomplete quoted word \(i\.e\. - without closing quote\) at the end of the line as valid instead of - throwing an error\. - - The basic shell syntax accepted here are unquoted, single\- and double\-quoted - words, separated by whitespace\. Leading and trailing whitespace are possible - too, and stripped\. Shell variables in their various forms are *not* - recognized, nor are sub\-shells\. As for the recognized forms of words, see - below for the detailed specification\. - - * __single\-quoted word__ - - A single\-quoted word begins with a single\-quote character, i\.e\. - __'__ \(ASCII 39\) followed by zero or more unicode characters not a - single\-quote, and then closed by a single\-quote\. - - The word must be followed by either the end of the string, or - whitespace\. A word cannot directly follow the word\. - - * __double\-quoted word__ - - A double\-quoted word begins with a double\-quote character, i\.e\. - __"__ \(ASCII 34\) followed by zero or more unicode characters not a - double\-quote, and then closed by a double\-quote\. - - Contrary to single\-quoted words a double\-quote can be embedded into the - word, by prefacing, i\.e\. escaping, i\.e\. quoting it with a backslash - character __\\__ \(ASCII 92\)\. Similarly a backslash character must be - quoted with itself to be inserted literally\. - - * __unquoted word__ - - Unquoted words are not delimited by quotes and thus cannot contain - whitespace or single\-quote characters\. Double\-quote and backslash - characters can be put into unquoted words, by quting them like for - double\-quoted words\. - - * __whitespace__ - - Whitespace is any unicode space character\. This is equivalent to - __string is space__, or the regular expression \\\\s\. - - Whitespace may occur before the first word, or after the last word\. - Whitespace must occur between adjacent words\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[bash](\.\./\.\./\.\./\.\./index\.md\#bash), -[lexing](\.\./\.\./\.\./\.\./index\.md\#lexing), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), -[shell](\.\./\.\./\.\./\.\./index\.md\#shell), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[tokenization](\.\./\.\./\.\./\.\./index\.md\#tokenization) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/stringprep/stringprep.md Index: embedded/md/tcllib/files/modules/stringprep/stringprep.md ================================================================== --- embedded/md/tcllib/files/modules/stringprep/stringprep.md +++ embedded/md/tcllib/files/modules/stringprep/stringprep.md @@ -1,165 +0,0 @@ - -[//000000001]: # (stringprep \- Preparation of Internationalized Strings) -[//000000002]: # (Generated from file 'stringprep\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2009, Sergei Golovan ) -[//000000004]: # (stringprep\(n\) 1\.0\.1 tcllib "Preparation of Internationalized Strings") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -stringprep \- Implementation of stringprep - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require stringprep 1\.0\.1 - -[__::stringprep::register__ *profile* ?*\-mapping list*? ?*\-normalization form*? ?*\-prohibited list*? ?*\-prohibitedList list*? ?*\-prohibitedCommand command*? ?*\-prohibitedBidi boolean*?](#1) -[__::stringprep::stringprep__ *profile* *string*](#2) -[__::stringprep::compare__ *profile* *string1* *string2*](#3) - -# DESCRIPTION - -This is an implementation in Tcl of the Preparation of Internationalized Strings -\("stringprep"\)\. It allows to define stringprep profiles and use them to prepare -Unicode strings for comparison as defined in RFC\-3454\. - -# COMMANDS - - - __::stringprep::register__ *profile* ?*\-mapping list*? ?*\-normalization form*? ?*\-prohibited list*? ?*\-prohibitedList list*? ?*\-prohibitedCommand command*? ?*\-prohibitedBidi boolean*? - - Register the __stringprep__ profile named *profile*\. Options are the - following\. - - Option *\-mapping* specifies __stringprep__ mapping tables\. This - parameter takes list of tables from appendix B of RFC\-3454\. The usual list - values are \{B\.1 B\.2\} or \{B\.1 B\.3\} where B\.1 contains characters which - commonly map to nothing, B\.3 specifies case folding, and B\.2 is used in - profiles with unicode normalization form KC\. Defult value is \{\} which means - no mapping\. - - Option *\-normalization* takes a string and if it is nonempty then it uses - as a name of Unicode normalization form\. Any value of "D", "C", "KD" or "KC" - may be used, though RFC\-3454 defines only two options: no normalization or - normalization using form KC\. - - Option *\-prohibited* takes a list of RFC\-3454 tables with prohibited - characters\. Current version does allow to prohibit either all tables from - C\.3 to C\.9 or neither of them\. An example of this list for RFC\-3491 is \{A\.1 - C\.1\.2 C\.2\.2 C\.3 C\.4 C\.5 C\.6 C\.7 C\.8 C\.9\}\. - - Option *\-prohibitedList* specifies a list of additional prohibited - characters\. The list contains not characters themselves but their Unicode - numbers\. For example, Nodeprep specification from RFC\-3920 forbids the - following codes: \{0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40\} \(\\" \\& \\' / : < > - @\)\. - - Option *\-prohibitedCommand* specifies a command which is called for every - character code in mapped and normalized string\. If the command returns true - then the character is considered prohibited\. This option is useful when a - list for *\-prohibitedList* is too large\. - - Option *\-prohibitedBidi* takes boolean value and if it is true then the - bidirectional character processing rules defined in section 6 of RFC\-3454 - are used\. - - - __::stringprep::stringprep__ *profile* *string* - - Performs __stringprep__ operations defined in profile *profile* to - string *string*\. Result is a prepared string or one of the following - errors: *invalid\_profile* \(profile *profile* is not defined\), - *prohibited\_character* \(string *string* contains a prohibited character\) - or *prohibited\_bidi* \(string *string* contains a prohibited - bidirectional sequence\)\. - - - __::stringprep::compare__ *profile* *string1* *string2* - - Compares two unicode strings prepared accordingly to __stringprep__ - profile *profile*\. The command returns 0 if prepared strings are equal, \-1 - if *string1* is lexicographically less than *string2*, or 1 if - *string1* is lexicographically greater than *string2*\. - -# EXAMPLES - -Nameprep profile definition \(see RFC\-3491\): - - ::stringprep::register nameprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1 - -Nodeprep and resourceprep profile definitions \(see RFC\-3920\): - - ::stringprep::register nodeprep -mapping {B.1 B.2} -normalization KC -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} -prohibitedBidi 1 - - ::stringprep::register resourceprep -mapping {B.1} -normalization KC -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9} -prohibitedBidi 1 - -# REFERENCES - - 1. "Preparation of Internationalized Strings \('stringprep'\)", - \([http://www\.ietf\.org/rfc/rfc3454\.txt](http://www\.ietf\.org/rfc/rfc3454\.txt)\) - - 1. "Nameprep: A Stringprep Profile for Internationalized Domain Names \(IDN\)", - \([http://www\.ietf\.org/rfc/rfc3491\.txt](http://www\.ietf\.org/rfc/rfc3491\.txt)\) - - 1. "Extensible Messaging and Presence Protocol \(XMPP\): Core", - \([http://www\.ietf\.org/rfc/rfc3920\.txt](http://www\.ietf\.org/rfc/rfc3920\.txt)\) - -# AUTHORS - -Sergei Golovan - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stringprep* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[unicode\(n\)](unicode\.md) - -# KEYWORDS - -[stringprep](\.\./\.\./\.\./\.\./index\.md\#stringprep), -[unicode](\.\./\.\./\.\./\.\./index\.md\#unicode) - -# COPYRIGHT - -Copyright © 2007\-2009, Sergei Golovan DELETED embedded/md/tcllib/files/modules/stringprep/stringprep_data.md Index: embedded/md/tcllib/files/modules/stringprep/stringprep_data.md ================================================================== --- embedded/md/tcllib/files/modules/stringprep/stringprep_data.md +++ embedded/md/tcllib/files/modules/stringprep/stringprep_data.md @@ -1,67 +0,0 @@ - -[//000000001]: # (stringprep::data \- Preparation of Internationalized Strings) -[//000000002]: # (Generated from file 'stringprep\_data\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2009, Sergei Golovan ) -[//000000004]: # (stringprep::data\(n\) 1\.0\.1 tcllib "Preparation of Internationalized Strings") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -stringprep::data \- stringprep data tables, generated, internal - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require stringprep::data 1\.0\.1 - -# DESCRIPTION - -The __stringprep::data__ package is a helper for -__[stringprep](stringprep\.md)__, providing it with the data tables -needed to perform its functions\. It is an *internal* package which should not -be accessed on its own\. Because of that it has no publicly documented API -either\. Its implementation is generated by a script\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stringprep* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[stringprep](\.\./\.\./\.\./\.\./index\.md\#stringprep), -[unicode](\.\./\.\./\.\./\.\./index\.md\#unicode) - -# COPYRIGHT - -Copyright © 2007\-2009, Sergei Golovan DELETED embedded/md/tcllib/files/modules/stringprep/unicode.md Index: embedded/md/tcllib/files/modules/stringprep/unicode.md ================================================================== --- embedded/md/tcllib/files/modules/stringprep/unicode.md +++ embedded/md/tcllib/files/modules/stringprep/unicode.md @@ -1,130 +0,0 @@ - -[//000000001]: # (unicode \- Unicode normalization) -[//000000002]: # (Generated from file 'unicode\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007, Sergei Golovan ) -[//000000004]: # (unicode\(n\) 1\.0\.0 tcllib "Unicode normalization") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -unicode \- Implementation of Unicode normalization - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require unicode 1\.0 - -[__::unicode::fromstring__ *string*](#1) -[__::unicode::tostring__ *uclist*](#2) -[__::unicode::normalize__ *form* *uclist*](#3) -[__::unicode::normalizeS__ *form* *string*](#4) - -# DESCRIPTION - -This is an implementation in Tcl of the Unicode normalization forms\. - -# COMMANDS - - - __::unicode::fromstring__ *string* - - Converts *string* to list of integer Unicode character codes which is used - in __unicode__ for internal string representation\. - - - __::unicode::tostring__ *uclist* - - Converts list of integers *uclist* back to Tcl string\. - - - __::unicode::normalize__ *form* *uclist* - - Normalizes Unicode characters list *ulist* according to *form* and - returns the normalized list\. Form *form* takes one of the following - values: *D* \(canonical decomposition\), *C* \(canonical decomposition, - followed by canonical composition\), *KD* \(compatibility decomposition\), or - *KC* \(compatibility decomposition, followed by canonical composition\)\. - - - __::unicode::normalizeS__ *form* *string* - - A shortcut to ::unicode::tostring \[unicode::normalize \\$form - \[::unicode::fromstring \\$string\]\]\. Normalizes Tcl string and returns - normalized string\. - -# EXAMPLES - - % ::unicode::fromstring "\u0410\u0411\u0412\u0413" - 1040 1041 1042 1043 - % ::unicode::tostring {49 50 51 52 53} - 12345 - % - - % ::unicode::normalize D {7692 775} - 68 803 775 - % ::unicode::normalizeS KD "\u1d2c" - A - % - -# REFERENCES - - 1. "Unicode Standard Annex \#15: Unicode Normalization Forms", - \([http://unicode\.org/reports/tr15/](http://unicode\.org/reports/tr15/)\) - -# AUTHORS - -Sergei Golovan - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stringprep* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[stringprep\(n\)](stringprep\.md) - -# KEYWORDS - -[normalization](\.\./\.\./\.\./\.\./index\.md\#normalization), -[unicode](\.\./\.\./\.\./\.\./index\.md\#unicode) - -# COPYRIGHT - -Copyright © 2007, Sergei Golovan DELETED embedded/md/tcllib/files/modules/stringprep/unicode_data.md Index: embedded/md/tcllib/files/modules/stringprep/unicode_data.md ================================================================== --- embedded/md/tcllib/files/modules/stringprep/unicode_data.md +++ embedded/md/tcllib/files/modules/stringprep/unicode_data.md @@ -1,67 +0,0 @@ - -[//000000001]: # (unicode::data \- Preparation of Internationalized Strings) -[//000000002]: # (Generated from file 'unicode\_data\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007, Sergei Golovan ) -[//000000004]: # (unicode::data\(n\) 1\.0\.0 tcllib "Preparation of Internationalized Strings") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -unicode::data \- unicode data tables, generated, internal - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require unicode::data 1\.0\.0 - -# DESCRIPTION - -The __unicode::data__ package is a helper for -__[unicode](unicode\.md)__, providing it with the data tables needed to -perform its functions\. It is an *internal* package which should not be -accessed on its own\. Because of that it has no publicly documented API either\. -Its implementation is generated by a script\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *stringprep* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[stringprep](\.\./\.\./\.\./\.\./index\.md\#stringprep), -[unicode](\.\./\.\./\.\./\.\./index\.md\#unicode) - -# COPYRIGHT - -Copyright © 2007, Sergei Golovan DELETED embedded/md/tcllib/files/modules/struct/disjointset.md Index: embedded/md/tcllib/files/modules/struct/disjointset.md ================================================================== --- embedded/md/tcllib/files/modules/struct/disjointset.md +++ embedded/md/tcllib/files/modules/struct/disjointset.md @@ -1,240 +0,0 @@ - -[//000000001]: # (struct::disjointset \- Tcl Data Structures) -[//000000002]: # (Generated from file 'disjointset\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (struct::disjointset\(n\) 1\.1 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::disjointset \- Disjoint set data structure - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.6 -package require struct::disjointset ?1\.1? - -[__::struct::disjointset__ *disjointsetName*](#1) -[*disjointsetName* *option* ?*arg arg \.\.\.*?](#2) -[*disjointsetName* __add\-element__ *item*](#3) -[*disjointsetName* __add\-partition__ *elements*](#4) -[*disjointsetName* __partitions__](#5) -[*disjointsetName* __num\-partitions__](#6) -[*disjointsetName* __equal__ *a* *b*](#7) -[*disjointsetName* __merge__ *a* *b*](#8) -[*disjointsetName* __find__ *e*](#9) -[*disjointsetName* __exemplars__](#10) -[*disjointsetName* __find\-exemplar__ *e*](#11) -[*disjointsetName* __destroy__](#12) - -# DESCRIPTION - -This package provides *disjoint sets*\. An alternative name for this kind of -structure is *merge\-find*\. - -Normally when dealing with sets and their elements the question is "Is this -element E contained in this set S?", with both E and S known\. - -Here the question is "Which of several sets contains the element E?"\. I\.e\. while -the element is known, the set is not, and we wish to find it quickly\. It is not -quite the inverse of the original question, but close\. Another operation which -is often wanted is that of quickly merging two sets into one, with the result -still fast for finding elements\. Hence the alternative term *merge\-find* for -this\. - -Why now is this named a *disjoint\-set* ? Because another way of describing the -whole situation is that we have - - - a finite *[set](\.\./\.\./\.\./\.\./index\.md\#set)* S, containing - - - a number of *elements* E, split into - - - a set of *partitions* P\. The latter term applies, because the intersection - of each pair P, P' of partitions is empty, with the union of all partitions - covering the whole set\. - - - An alternative name for the *partitions* would be *equvalence classes*, - and all elements in the same class are considered as equal\. - -Here is a pictorial representation of the concepts listed above: - - +-----------------+ The outer lines are the boundaries of the set S. - | / | The inner regions delineated by the skewed lines - | * / * | are the partitions P. The *'s denote the elements - | * / \ | E in the set, each in a single partition, their - |* / \ | equivalence class. - | / * \ | - | / * / | - | * /\ * / | - | / \ / | - | / \/ * | - | / * \ | - | / * \ | - +-----------------+ - -For more information see -[http://en\.wikipedia\.org/wiki/Disjoint\_set\_data\_structure](http://en\.wikipedia\.org/wiki/Disjoint\_set\_data\_structure)\. - -# API - -The package exports a single command, __::struct::disjointset__\. All -functionality provided here can be reached through a subcommand of this command\. - - - __::struct::disjointset__ *disjointsetName* - - Creates a new disjoint set object with an associated global Tcl command - whose name is *disjointsetName*\. This command may be used to invoke - various operations on the disjointset\. It has the following general form: - - * *disjointsetName* *option* ?*arg arg \.\.\.*? - - The __option__ and the *arg*s determine the exact behavior of the - command\. The following commands are possible for disjointset objects: - - - *disjointsetName* __add\-element__ *item* - - Creates a new partition in the specified disjoint set, and fills it with the - single item *item*\. The command maintains the integrity of the disjoint - set, i\.e\. it verifies that none of the *elements* are already part of the - disjoint set and throws an error otherwise\. - - The result of this method is the empty string\. - - This method runs in constant time\. - - - *disjointsetName* __add\-partition__ *elements* - - Creates a new partition in specified disjoint set, and fills it with the - values found in the set of *elements*\. The command maintains the integrity - of the disjoint set, i\.e\. it verifies that none of the *elements* are - already part of the disjoint set and throws an error otherwise\. - - The result of the command is the empty string\. - - This method runs in time proportional to the size of *elements*\]\. - - - *disjointsetName* __partitions__ - - Returns the set of partitions the named disjoint set currently consists of\. - The form of the result is a list of lists; the inner lists contain the - elements of the partitions\. - - This method runs in time O\(N\*alpha\(N\)\), where N is the number of elements in - the disjoint set and alpha is the inverse Ackermann function\. - - - *disjointsetName* __num\-partitions__ - - Returns the number of partitions the named disjoint set currently consists - of\. - - This method runs in constant time\. - - - *disjointsetName* __equal__ *a* *b* - - Determines if the two elements *a* and *b* of the disjoint set belong to - the same partition\. The result of the method is a boolean value, - __True__ if the two elements are contained in the same partition, and - __False__ otherwise\. - - An error will be thrown if either *a* or *b* are not elements of the - disjoint set\. - - This method runs in amortized time O\(alpha\(N\)\), where N is the number of - elements in the larger partition and alpha is the inverse Ackermann - function\. - - - *disjointsetName* __merge__ *a* *b* - - Determines the partitions the elements *a* and *b* are contained in and - merges them into a single partition\. If the two elements were already - contained in the same partition nothing will change\. - - The result of the method is the empty string\. - - This method runs in amortized time O\(alpha\(N\)\), where N is the number of - items in the larger of the partitions being merged\. The worst case time is - O\(N\)\. - - - *disjointsetName* __find__ *e* - - Returns a list of the members of the partition of the disjoint set which - contains the element *e*\. - - This method runs in O\(N\*alpha\(N\)\) time, where N is the total number of items - in the disjoint set and alpha is the inverse Ackermann function, See - __find\-exemplar__ for a faster method, if all that is needed is a unique - identifier for the partition, rather than an enumeration of all its - elements\. - - - *disjointsetName* __exemplars__ - - Returns a list containing an exemplar of each partition in the disjoint set\. - The exemplar is a member of the partition, chosen arbitrarily\. - - This method runs in O\(N\*alpha\(N\)\) time, where N is the total number of items - in the disjoint set and alpha is the inverse Ackermann function\. - - - *disjointsetName* __find\-exemplar__ *e* - - Returns the exemplar of the partition of the disjoint set containing the - element *e*\. Throws an error if *e* is not found in the disjoint set\. - The exemplar is an arbitrarily chosen member of the partition\. The only - operation that will change the exemplar of any partition is __merge__\. - - This method runs in O\(alpha\(N\)\) time, where N is the number of items in the - partition containing E, and alpha is the inverse Ackermann function\. - - - *disjointsetName* __destroy__ - - Destroys the disjoint set object and all associated memory\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: disjointset* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[disjoint set](\.\./\.\./\.\./\.\./index\.md\#disjoint\_set), [equivalence -class](\.\./\.\./\.\./\.\./index\.md\#equivalence\_class), -[find](\.\./\.\./\.\./\.\./index\.md\#find), [merge -find](\.\./\.\./\.\./\.\./index\.md\#merge\_find), -[partition](\.\./\.\./\.\./\.\./index\.md\#partition), [partitioned -set](\.\./\.\./\.\./\.\./index\.md\#partitioned\_set), -[union](\.\./\.\./\.\./\.\./index\.md\#union) - -# CATEGORY - -Data structures DELETED embedded/md/tcllib/files/modules/struct/graph.md Index: embedded/md/tcllib/files/modules/struct/graph.md ================================================================== --- embedded/md/tcllib/files/modules/struct/graph.md +++ embedded/md/tcllib/files/modules/struct/graph.md @@ -1,885 +0,0 @@ - -[//000000001]: # (struct::graph \- Tcl Data Structures) -[//000000002]: # (Generated from file 'graph\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2009,2019 Andreas Kupries ) -[//000000004]: # (struct::graph\(n\) 2\.4\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::graph \- Create and manipulate directed graph objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Changes for 2\.0](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require struct::graph ?2\.4\.3? -package require struct::list ?1\.5? -package require struct::set ?2\.2\.3? - -[__::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) -[__graphName__ *option* ?*arg arg \.\.\.*?](#2) -[*graphName* __=__ *sourcegraph*](#3) -[*graphName* __\-\->__ *destgraph*](#4) -[*graphName* __append__ *key* *value*](#5) -[*graphName* __deserialize__ *serialization*](#6) -[*graphName* __destroy__](#7) -[*graphName* __arc append__ *arc* *key* *value*](#8) -[*graphName* __arc attr__ *key*](#9) -[*graphName* __arc attr__ *key* __\-arcs__ *list*](#10) -[*graphName* __arc attr__ *key* __\-glob__ *globpattern*](#11) -[*graphName* __arc attr__ *key* __\-regexp__ *repattern*](#12) -[*graphName* __arc delete__ *arc* ?*arc* \.\.\.?](#13) -[*graphName* __arc exists__ *arc*](#14) -[*graphName* __arc flip__ *arc*](#15) -[*graphName* __arc get__ *arc* *key*](#16) -[*graphName* __arc getall__ *arc* ?*pattern*?](#17) -[*graphName* __arc getunweighted__](#18) -[*graphName* __arc getweight__ *arc*](#19) -[*graphName* __arc keys__ *arc* ?*pattern*?](#20) -[*graphName* __arc keyexists__ *arc* *key*](#21) -[*graphName* __arc insert__ *start* *end* ?*child*?](#22) -[*graphName* __arc lappend__ *arc* *key* *value*](#23) -[*graphName* __arc rename__ *arc* *newname*](#24) -[*graphName* __arc set__ *arc* *key* ?*value*?](#25) -[*graphName* __arc setunweighted__ ?*weight*?](#26) -[*graphName* __arc setweight__ *arc* *weight*](#27) -[*graphName* __arc unsetweight__ *arc*](#28) -[*graphName* __arc hasweight__ *arc*](#29) -[*graphName* __arc source__ *arc*](#30) -[*graphName* __arc target__ *arc*](#31) -[*graphName* __arc nodes__ *arc*](#32) -[*graphName* __arc move\-source__ *arc* *newsource*](#33) -[*graphName* __arc move\-target__ *arc* *newtarget*](#34) -[*graphName* __arc move__ *arc* *newsource* *newtarget*](#35) -[*graphName* __arc unset__ *arc* *key*](#36) -[*graphName* __arc weights__](#37) -[*graphName* __arcs__ ?\-key *key*? ?\-value *value*? ?\-filter *cmdprefix*? ?\-in|\-out|\-adj|\-inner|\-embedding *node node\.\.\.*?](#38) -[*graphName* __lappend__ *key* *value*](#39) -[*graphName* __node append__ *node* *key* *value*](#40) -[*graphName* __node attr__ *key*](#41) -[*graphName* __node attr__ *key* __\-nodes__ *list*](#42) -[*graphName* __node attr__ *key* __\-glob__ *globpattern*](#43) -[*graphName* __node attr__ *key* __\-regexp__ *repattern*](#44) -[*graphName* __node degree__ ?\-in|\-out? *node*](#45) -[*graphName* __node delete__ *node* ?*node*\.\.\.?](#46) -[*graphName* __node exists__ *node*](#47) -[*graphName* __node get__ *node* *key*](#48) -[*graphName* __node getall__ *node* ?*pattern*?](#49) -[*graphName* __node keys__ *node* ?*pattern*?](#50) -[*graphName* __node keyexists__ *node* *key*](#51) -[*graphName* __node insert__ ?*node*\.\.\.?](#52) -[*graphName* __node lappend__ *node* *key* *value*](#53) -[*graphName* __node opposite__ *node* *arc*](#54) -[*graphName* __node rename__ *node* *newname*](#55) -[*graphName* __node set__ *node* *key* ?*value*?](#56) -[*graphName* __node unset__ *node* *key*](#57) -[*graphName* __nodes__ ?\-key *key*? ?\-value *value*? ?\-filter *cmdprefix*? ?\-in|\-out|\-adj|\-inner|\-embedding *node* *node*\.\.\.?](#58) -[*graphName* __get__ *key*](#59) -[*graphName* __getall__ ?*pattern*?](#60) -[*graphName* __keys__ ?*pattern*?](#61) -[*graphName* __keyexists__ *key*](#62) -[*graphName* __serialize__ ?*node*\.\.\.?](#63) -[*graphName* __set__ *key* ?*value*?](#64) -[*graphName* __swap__ *node1* *node2*](#65) -[*graphName* __unset__ *key*](#66) -[*graphName* __walk__ *node* ?\-order *order*? ?\-type *type*? ?\-dir *direction*? \-command *cmd*](#67) - -# DESCRIPTION - -A directed graph is a structure containing two collections of elements, called -*nodes* and *arcs* respectively, together with a relation \("connectivity"\) -that places a general structure upon the nodes and arcs\. - -Each arc is connected to two nodes, one of which is called the -*[source](\.\./\.\./\.\./\.\./index\.md\#source)* and the other the *target*\. This -imposes a direction upon the arc, which is said to go from the source to the -target\. It is allowed that source and target of an arc are the same node\. Such -an arc is called a *[loop](\.\./\.\./\.\./\.\./index\.md\#loop)*\. Whenever a node is -either the source or target of an arc both are said to be -*[adjacent](\.\./\.\./\.\./\.\./index\.md\#adjacent)*\. This extends into a relation -between nodes, i\.e\. if two nodes are connected through at least one arc they are -said to be *[adjacent](\.\./\.\./\.\./\.\./index\.md\#adjacent)* too\. - -Each node can be the source and target for any number of arcs\. The former are -called the *outgoing arcs* of the node, the latter the *incoming arcs* of -the node\. The number of arcs in either set is called the *in\-degree* resp\. the -*out\-degree* of the node\. - -In addition to maintaining the node and arc relationships, this graph -implementation allows any number of named *attributes* to be associated with -the graph itself, and each node or arc\. - -*Note:* The major version of the package -__[struct](\.\./\.\./\.\./\.\./index\.md\#struct)__ has been changed to version -2\.0, due to backward incompatible changes in the API of this module\. Please read -the section [Changes for 2\.0](#section2) for a full list of all changes, -incompatible and otherwise\. - -*Note:* A C\-implementation of the command can be had from the location -[http://www\.purl\.org/NET/schlenker/tcl/cgraph](http://www\.purl\.org/NET/schlenker/tcl/cgraph)\. -See also [http://wiki\.tcl\.tk/cgraph](http://wiki\.tcl\.tk/cgraph)\. This -implementation uses a bit less memory than the tcl version provided here -directly, and is faster\. Its support is limited to versions of the package -before 2\.0\. - -As of version 2\.2 of this package a critcl based C implementation is available -from here as well\. This implementation however requires Tcl 8\.4 to run\. - -The main command of the package is: - - - __::struct::graph__ ?*graphName*? ?__=__|__:=__|__as__|__deserialize__ *source*? - - The command creates a new graph object with an associated global Tcl command - whose name is *graphName*\. This command may be used to invoke various - operations on the graph\. It has the following general form: - - * __graphName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - If *graphName* is not specified a unique name will be generated by the - package itself\. If a *source* is specified the new graph will be - initialized to it\. For the operators __=__, __:=__, and __as__ - the *source* argument is interpreted as the name of another graph object, - and the assignment operator __=__ will be executed\. For the operator - __deserialize__ the *source* is a serialized graph object and - __deserialize__ will be executed\. - - In other words - - ::struct::graph mygraph = b - - is equivalent to - - ::struct::graph mygraph - mygraph = b - - and - - ::struct::graph mygraph deserialize $b - - is equivalent to - - ::struct::graph mygraph - mygraph deserialize $b - -The following commands are possible for graph objects: - - - *graphName* __=__ *sourcegraph* - - This is the *assignment* operator for graph objects\. It copies the graph - contained in the graph object *sourcegraph* over the graph data in - *graphName*\. The old contents of *graphName* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *graphName* __deserialize__ \[*sourcegraph* __serialize__\] - - The operation assumes that the *sourcegraph* provides the method - __serialize__ and that this method returns a valid graph serialization\. - - - *graphName* __\-\->__ *destgraph* - - This is the *reverse assignment* operator for graph objects\. It copies the - graph contained in the graph object *graphName* over the graph data in the - object *destgraph*\. The old contents of *destgraph* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *destgraph* __deserialize__ \[*graphName* __serialize__\] - - The operation assumes that the *destgraph* provides the method - __deserialize__ and that this method takes a graph serialization\. - - - *graphName* __append__ *key* *value* - - Appends a *value* to one of the keyed values associated with the graph\. - Returns the new value given to the attribute *key*\. - - - *graphName* __deserialize__ *serialization* - - This is the complement to __serialize__\. It replaces the graph data in - *graphName* with the graph described by the *serialization* value\. The - old contents of *graphName* are deleted by this operation\. - - - *graphName* __destroy__ - - Destroys the graph, including its storage space and associated command\. - - - *graphName* __arc append__ *arc* *key* *value* - - Appends a *value* to one of the keyed values associated with an *arc*\. - Returns the new value given to the attribute *key*\. - - - *graphName* __arc attr__ *key* - - - *graphName* __arc attr__ *key* __\-arcs__ *list* - - - *graphName* __arc attr__ *key* __\-glob__ *globpattern* - - - *graphName* __arc attr__ *key* __\-regexp__ *repattern* - - This method retrieves the value of the attribute named *key*, for all arcs - in the graph \(matching the restriction specified via one of the possible - options\) and having the specified attribute\. - - The result is a dictionary mapping from arc names to the value of attribute - *key* at that arc\. Arcs not having the attribute *key*, or not passing a - specified restriction, are not listed in the result\. - - The possible restrictions are: - - * __\-arcs__ - - The value is a list of arcs\. Only the arcs mentioned in this list are - searched for the attribute\. - - * __\-glob__ - - The value is a glob pattern\. Only the arcs in the graph whose names - match this pattern are searched for the attribute\. - - * __\-regexp__ - - The value is a regular expression\. Only the arcs in the graph whose - names match this pattern are searched for the attribute\. - - - *graphName* __arc delete__ *arc* ?*arc* \.\.\.? - - Remove the specified arcs from the graph\. - - - *graphName* __arc exists__ *arc* - - Return true if the specified *arc* exists in the graph\. - - - *graphName* __arc flip__ *arc* - - Reverses the direction of the named *arc*, i\.e\. the source and target - nodes of the arc are exchanged with each other\. - - - *graphName* __arc get__ *arc* *key* - - Returns the value associated with the key *key* for the *arc*\. - - - *graphName* __arc getall__ *arc* ?*pattern*? - - Returns a dictionary \(suitable for use with \[__array set__\]\) for the - *arc*\. If the *pattern* is specified only the attributes whose names - match the pattern will be part of the returned dictionary\. The pattern is a - __glob__ pattern\. - - - *graphName* __arc getunweighted__ - - Returns a list containing the names of all arcs in the graph which have no - weight associated with them\. - - - *graphName* __arc getweight__ *arc* - - Returns the weight associated with the *arc*\. Throws an error if the arc - has no weight associated with it\. - - - *graphName* __arc keys__ *arc* ?*pattern*? - - Returns a list of keys for the *arc*\. If the *pattern* is specified only - the attributes whose names match the pattern will be part of the returned - list\. The pattern is a __glob__ pattern\. - - - *graphName* __arc keyexists__ *arc* *key* - - Return true if the specified *key* exists for the *arc*\. - - - *graphName* __arc insert__ *start* *end* ?*child*? - - Insert an arc named *child* into the graph beginning at the node *start* - and ending at the node *end*\. If the name of the new arc is not specified - the system will generate a unique name of the form *arc**x*\. - - - *graphName* __arc lappend__ *arc* *key* *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *arc*\. Returns the new value given to the attribute *key*\. - - - *graphName* __arc rename__ *arc* *newname* - - Renames the arc *arc* to *newname*\. An error is thrown if either the arc - does not exist, or a arc with name *newname* does exist\. The result of the - command is the new name of the arc\. - - - *graphName* __arc set__ *arc* *key* ?*value*? - - Set or get one of the keyed values associated with an arc\. An arc may have - any number of keyed values associated with it\. If *value* is not - specified, this command returns the current value assigned to the key; if - *value* is specified, this command assigns that value to the key, and - returns that value\. - - - *graphName* __arc setunweighted__ ?*weight*? - - Sets the weight of all arcs without a weight to *weight*\. Returns the - empty string as its result\. If not present *weight* defaults to __0__\. - - - *graphName* __arc setweight__ *arc* *weight* - - Sets the weight of the *arc* to *weight*\. Returns *weight*\. - - - *graphName* __arc unsetweight__ *arc* - - Removes the weight of the *arc*, if present\. Does nothing otherwise\. - Returns the empty string\. - - - *graphName* __arc hasweight__ *arc* - - Determines if the *arc* has a weight associated with it\. The result is a - boolean value, __True__ if a weight is defined, and __False__ - otherwise\. - - - *graphName* __arc source__ *arc* - - Return the node the given *arc* begins at\. - - - *graphName* __arc target__ *arc* - - Return the node the given *arc* ends at\. - - - *graphName* __arc nodes__ *arc* - - Return the nodes the given *arc* begins and ends at, as a two\-element - list\. - - - *graphName* __arc move\-source__ *arc* *newsource* - - Changes the source node of the arc to *newsource*\. It can be said that the - arc rotates around its target node\. - - - *graphName* __arc move\-target__ *arc* *newtarget* - - Changes the target node of the arc to *newtarget*\. It can be said that the - arc rotates around its source node\. - - - *graphName* __arc move__ *arc* *newsource* *newtarget* - - Changes both source and target nodes of the arc to *newsource*, and - *newtarget* resp\. - - - *graphName* __arc unset__ *arc* *key* - - Remove a keyed value from the arc *arc*\. The method will do nothing if the - *key* does not exist\. - - - *graphName* __arc weights__ - - Returns a dictionary whose keys are the names of all arcs which have a - weight associated with them, and the values are these weights\. - - - *graphName* __arcs__ ?\-key *key*? ?\-value *value*? ?\-filter *cmdprefix*? ?\-in|\-out|\-adj|\-inner|\-embedding *node node\.\.\.*? - - Returns a list of arcs in the graph\. If no restriction is specified a list - containing all arcs is returned\. Restrictions can limit the list of returned - arcs based on the nodes that are connected by the arc, on the keyed values - associated with the arc, or both\. A general filter command can be used as - well\. The restrictions that involve connected nodes take a variable number - of nodes as argument, specified after the name of the restriction itself\. - - The restrictions imposed by either __\-in__, __\-out__, __\-adj__, - __\-inner__, or __\-embedding__ are applied first\. Specifying more - than one of them is illegal\. - - After that the restrictions set via __\-key__ \(and __\-value__\) are - applied\. Specifying more than one __\-key__ \(and __\-value__\) is - illegal\. Specifying __\-value__ alone, without __\-key__ is illegal as - well\. - - Any restriction set through __\-filter__ is applied last\. Specifying more - than one __\-filter__ is illegal\. - - Coming back to the restrictions based on a set of nodes, the command - recognizes the following switches: - - * __\-in__ - - Return a list of all arcs whose target is one of the nodes in the set of - nodes\. I\.e\. it computes the union of all incoming arcs of the nodes in - the set\. - - * __\-out__ - - Return a list of all arcs whose source is one of the nodes in the set of - nodes\. I\.e\. it computes the union of all outgoing arcs of the nodes in - the set\. - - * __\-adj__ - - Return a list of all arcs adjacent to at least one of the nodes in the - set\. This is the union of the nodes returned by __\-in__ and - __\-out__\. - - * __\-inner__ - - Return a list of all arcs which are adjacent to two of the nodes in the - set\. This is the set of arcs in the subgraph spawned by the specified - nodes\. - - * __\-embedding__ - - Return a list of all arcs adjacent to exactly one of the nodes in the - set\. This is the set of arcs connecting the subgraph spawned by the - specified nodes to the rest of the graph\. - - *Attention*: After the above options any word with a leading dash which is - not a valid option is treated as a node name instead of an invalid option to - error out on\. This condition holds until either a valid option terminates - the list of nodes, or the end of the command is reached, whichever comes - first\. - - The remaining filter options are: - - * __\-key__ *key* - - Limit the list of arcs that are returned to those arcs that have an - associated key *key*\. - - * __\-value__ *value* - - This restriction can only be used in combination with __\-key__\. It - limits the list of arcs that are returned to those arcs whose associated - key *key* has the value *value*\. - - * __\-filter__ *cmdrefix* - - Limit the list of arcs that are returned to those arcs that pass the - test\. The command in *cmdprefix* is called with two arguments, the - name of the graph object, and the name of the arc in question\. It is - executed in the context of the caller and has to return a boolean value\. - Arcs for which the command returns __false__ are removed from the - result list before it is returned to the caller\. - - - *graphName* __lappend__ *key* *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - the graph\. Returns the new value given to the attribute *key*\. - - - *graphName* __node append__ *node* *key* *value* - - Appends a *value* to one of the keyed values associated with an *node*\. - Returns the new value given to the attribute *key*\. - - - *graphName* __node attr__ *key* - - - *graphName* __node attr__ *key* __\-nodes__ *list* - - - *graphName* __node attr__ *key* __\-glob__ *globpattern* - - - *graphName* __node attr__ *key* __\-regexp__ *repattern* - - This method retrieves the value of the attribute named *key*, for all - nodes in the graph \(matching the restriction specified via one of the - possible options\) and having the specified attribute\. - - The result is a dictionary mapping from node names to the value of attribute - *key* at that node\. Nodes not having the attribute *key*, or not passing - a specified restriction, are not listed in the result\. - - The possible restrictions are: - - * __\-nodes__ - - The value is a list of nodes\. Only the nodes mentioned in this list are - searched for the attribute\. - - * __\-glob__ - - The value is a glob pattern\. Only the nodes in the graph whose names - match this pattern are searched for the attribute\. - - * __\-regexp__ - - The value is a regular expression\. Only the nodes in the graph whose - names match this pattern are searched for the attribute\. - - - *graphName* __node degree__ ?\-in|\-out? *node* - - Return the number of arcs adjacent to the specified *node*\. If one of the - restrictions __\-in__ or __\-out__ is given only the incoming resp\. - outgoing arcs are counted\. - - - *graphName* __node delete__ *node* ?*node*\.\.\.? - - Remove the specified nodes from the graph\. All of the nodes' arcs will be - removed as well to prevent unconnected arcs\. - - - *graphName* __node exists__ *node* - - Return true if the specified *node* exists in the graph\. - - - *graphName* __node get__ *node* *key* - - Return the value associated with the key *key* for the *node*\. - - - *graphName* __node getall__ *node* ?*pattern*? - - Returns a dictionary \(suitable for use with \[__array set__\]\) for the - *node*\. If the *pattern* is specified only the attributes whose names - match the pattern will be part of the returned dictionary\. The pattern is a - __glob__ pattern\. - - - *graphName* __node keys__ *node* ?*pattern*? - - Returns a list of keys for the *node*\. If the *pattern* is specified - only the attributes whose names match the pattern will be part of the - returned list\. The pattern is a __glob__ pattern\. - - - *graphName* __node keyexists__ *node* *key* - - Return true if the specified *key* exists for the *node*\. - - - *graphName* __node insert__ ?*node*\.\.\.? - - Insert one or more nodes into the graph\. The new nodes have no arcs - connected to them\. If no node is specified one node will be inserted, and - the system will generate a unique name of the form *node**x* for it\. - - - *graphName* __node lappend__ *node* *key* *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *node*\. Returns the new value given to the attribute *key*\. - - - *graphName* __node opposite__ *node* *arc* - - Return the node at the other end of the specified *arc*, which has to be - adjacent to the given *node*\. - - - *graphName* __node rename__ *node* *newname* - - Renames the node *node* to *newname*\. An error is thrown if either the - node does not exist, or a node with name *newname* does exist\. The result - of the command is the new name of the node\. - - - *graphName* __node set__ *node* *key* ?*value*? - - Set or get one of the keyed values associated with a node\. A node may have - any number of keyed values associated with it\. If *value* is not - specified, this command returns the current value assigned to the key; if - *value* is specified, this command assigns that value to the key\. - - - *graphName* __node unset__ *node* *key* - - Remove a keyed value from the node *node*\. The method will do nothing if - the *key* does not exist\. - - - *graphName* __nodes__ ?\-key *key*? ?\-value *value*? ?\-filter *cmdprefix*? ?\-in|\-out|\-adj|\-inner|\-embedding *node* *node*\.\.\.? - - Return a list of nodes in the graph\. Restrictions can limit the list of - returned nodes based on neighboring nodes, or based on the keyed values - associated with the node\. The restrictions that involve neighboring nodes - have a list of nodes as argument, specified after the name of the - restriction itself\. - - The possible restrictions are the same as for method __arcs__\. Note that - while the exact meanings change slightly, as they operate on nodes instead - of arcs, the general behaviour is the same, especially when it comes to the - handling of words with a leading dash in node lists\. - - The command recognizes: - - * __\-in__ - - Return a list of all nodes with at least one outgoing arc ending in a - node found in the specified set of nodes\. Alternatively specified as the - set of source nodes for the __\-in__ arcs of the node set\. The - *incoming neighbours*\. - - * __\-out__ - - Return a list of all nodes with at least one incoming arc starting in a - node found in the specified set of nodes\. Alternatively specified as the - set of target nodes for the __\-out__ arcs of the node set\. The - *outgoing neighbours*\. - - * __\-adj__ - - This is the union of the nodes returned by __\-in__ and __\-out__\. - The *neighbours*\. - - * __\-inner__ - - The set of neighbours \(see __\-adj__ above\) which are also in the set - of nodes\. I\.e\. the intersection between the set of nodes and the - neighbours per __\-adj__\. - - * __\-embedding__ - - The set of neighbours \(see __\-adj__ above\) which are not in the set - of nodes\. I\.e\. the difference between the neighbours as per - __\-adj__, and the set of nodes\. - - * __\-key__ *key* - - Limit the list of nodes that are returned to those nodes that have an - associated key *key*\. - - * __\-value__ *value* - - This restriction can only be used in combination with __\-key__\. It - limits the list of nodes that are returned to those nodes whose - associated key *key* has the value *value*\. - - * __\-filter__ *cmdrefix* - - Limit the list of nodes that are returned to those nodes that pass the - test\. The command in *cmdprefix* is called with two arguments, the - name of the graph object, and the name of the node in question\. It is - executed in the context of the caller and has to return a boolean value\. - Nodes for which the command returns __false__ are removed from the - result list before it is returned to the caller\. - - - *graphName* __get__ *key* - - Return the value associated with the key *key* for the graph\. - - - *graphName* __getall__ ?*pattern*? - - Returns a dictionary \(suitable for use with \[__array set__\]\) for the - whole graph\. If the *pattern* is specified only the attributes whose names - match the pattern will be part of the returned dictionary\. The pattern is a - __glob__ pattern\. - - - *graphName* __keys__ ?*pattern*? - - Returns a list of keys for the whole graph\. If the *pattern* is specified - only the attributes whose names match the pattern will be part of the - returned list\. The pattern is a __glob__ pattern\. - - - *graphName* __keyexists__ *key* - - Return true if the specified *key* exists for the whole graph\. - - - *graphName* __serialize__ ?*node*\.\.\.? - - This method serializes the sub\-graph spanned up by the *node*s\. In other - words it returns a tcl value completely describing that graph\. If no nodes - are specified the whole graph will be serialized\. This allows, for example, - the transfer of graph objects \(or parts thereof\) over arbitrary channels, - persistence, etc\. This method is also the basis for both the copy - constructor and the assignment operator\. - - The result of this method has to be semantically identical over all - implementations of the graph interface\. This is what will enable us to copy - graph data between different implementations of the same interface\. - - The result is a list containing a multiple of three items, plus one\! In - other words, '\[llength $serial\] % 3 == 1'\. Valid values include 1, 4, 7, \.\.\. - - The last element of the list is a dictionary containing the attributes - associated with the whole graph\. Regarding the other elements; each triple - consists of - - 1. The name of the node to be described, - - 1. A dictionary containing the attributes associated with the node, - - 1. And a list describing all the arcs starting at that node\. - - The elements of the arc list are lists containing three or four elements - each, i\.e\. - - 1. The name of the arc described by the element, - - 1. A reference to the destination node of the arc\. This reference is an - integer number given the index of that node in the main serialization - list\. As that it is greater than or equal to zero, less than the length - of the serialization, and a multiple of three\. *Note:* For internal - consistency no arc name may be used twice, whether in the same node, or - at some other node\. This is a global consistency requirement for the - serialization\. - - 1. And a dictionary containing the attributes associated with the arc\. - - 1. The weight associated with the arc\. This value is optional\. Its - non\-presence means that the arc in question has no weight associated - with it\. - - *Note:* This information is new, compared to the serialization of - __[graph](\.\./\.\./\.\./\.\./index\.md\#graph)__ 2\.3 and earlier\. By - making it an optional element the new format is maximally compatible - with the old\. This means that any graph not using weights will generate - a serialization which is still understood by the older graph package\. A - serialization will not be understood any longer by the older packages - if, and only if the graph it was generated from actually has arcs with - weights\. - - For all attribute dictionaries they keys are the names of the attributes, - and the values are the values for each name\. - - *Note:* The order of the nodes in the serialization has no relevance, nor - has the order of the arcs per node\. - - # A possible serialization for the graph structure - # - # d -----> %2 - # / ^ \ - # / / \ - # / b \ - # / / \ - # %1 <- a - %0 e - # ^ \\ / - # \\ c / - # \\ \\ / - # \\ v v - # f ------ %3 - # is - # - # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {} - # - # This assumes that the graph has neither attribute data nor weighted arcs. - - - *graphName* __set__ *key* ?*value*? - - Set or get one of the keyed values associated with a graph\. A graph may have - any number of keyed values associated with it\. If *value* is not - specified, this command returns the current value assigned to the key; if - *value* is specified, this command assigns that value to the key\. - - - *graphName* __swap__ *node1* *node2* - - Swap the position of *node1* and *node2* in the graph\. - - - *graphName* __unset__ *key* - - Remove a keyed value from the graph\. The method will do nothing if the - *key* does not exist\. - - - *graphName* __walk__ *node* ?\-order *order*? ?\-type *type*? ?\-dir *direction*? \-command *cmd* - - Perform a breadth\-first or depth\-first walk of the graph starting at the - node *node* going in either the direction of outgoing or opposite to the - incoming arcs\. - - The type of walk, breadth\-first or depth\-first, is determined by the value - of *type*; __bfs__ indicates breadth\-first, __dfs__ indicates - depth\-first\. Depth\-first is the default\. - - The order of the walk, pre\-order, post\-order or both\-order is determined by - the value of *order*; __pre__ indicates pre\-order, __post__ - indicates post\-order, __both__ indicates both\-order\. Pre\-order is the - default\. Pre\-order walking means that a node is visited before any of its - neighbors \(as defined by the *direction*, see below\)\. Post\-order walking - means that a parent is visited after any of its neighbors\. Both\-order - walking means that a node is visited before *and* after any of its - neighbors\. The combination of a breadth\-first walk with post\- or both\-order - is illegal\. - - The direction of the walk is determined by the value of *dir*; - __backward__ indicates the direction opposite to the incoming arcs, - __forward__ indicates the direction of the outgoing arcs\. - - As the walk progresses, the command *cmd* will be evaluated at each node, - with the mode of the call \(__enter__ or __leave__\) and values - *graphName* and the name of the current node appended\. For a pre\-order - walk, all nodes are __enter__ed, for a post\-order all nodes are left\. In - a both\-order walk the first visit of a node __enter__s it, the second - visit __leave__s it\. - -# Changes for 2\.0 - -The following noteworthy changes have occurred: - - 1. The API for accessing attributes and their values has been simplified\. - - All functionality regarding the default attribute "data" has been removed\. - This default attribute does not exist anymore\. All accesses to attributes - have to specify the name of the attribute in question\. This backward - *incompatible* change allowed us to simplify the signature of all methods - handling attributes\. - - Especially the flag __\-key__ is not required anymore, even more, its - use is now forbidden\. Please read the documentation for the arc and node - methods __set__, __get__, __getall__, __unset__, - __append__, __lappend__, __keyexists__ and __keys__ for a - description of the new API's\. - - 1. The methods __keys__ and __getall__ now take an optional pattern - argument and will return only attribute data for keys matching this - pattern\. - - 1. Arcs and nodes can now be renamed\. See the documentation for the methods - __arc rename__ and __node rename__\. - - 1. The structure has been extended with API's for the serialization and - deserialization of graph objects, and a number of operations based on them - \(graph assignment, copy construction\)\. - - Please read the documentation for the methods __serialize__, - __deserialize__, __=__, and __\-\->__, and the documentation on - the construction of graph objects\. - - Beyond the copying of whole graph objects these new API's also enable the - transfer of graph objects over arbitrary channels and for easy persistence\. - - 1. A new method, __attr__, was added to both __arc__ and __node__ - allowing the query and retrieval of attribute data without regard to arc - and node relationships\. - - 1. Both methods __arcs__ and __nodes__ have been extended with the - ability to select arcs and nodes based on an arbitrary filtering criterium\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: graph* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[adjacent](\.\./\.\./\.\./\.\./index\.md\#adjacent), -[arc](\.\./\.\./\.\./\.\./index\.md\#arc), [cgraph](\.\./\.\./\.\./\.\./index\.md\#cgraph), -[degree](\.\./\.\./\.\./\.\./index\.md\#degree), -[edge](\.\./\.\./\.\./\.\./index\.md\#edge), [graph](\.\./\.\./\.\./\.\./index\.md\#graph), -[loop](\.\./\.\./\.\./\.\./index\.md\#loop), -[neighbour](\.\./\.\./\.\./\.\./index\.md\#neighbour), -[node](\.\./\.\./\.\./\.\./index\.md\#node), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[subgraph](\.\./\.\./\.\./\.\./index\.md\#subgraph), -[vertex](\.\./\.\./\.\./\.\./index\.md\#vertex) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002\-2009,2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/graph1.md Index: embedded/md/tcllib/files/modules/struct/graph1.md ================================================================== --- embedded/md/tcllib/files/modules/struct/graph1.md +++ embedded/md/tcllib/files/modules/struct/graph1.md @@ -1,410 +0,0 @@ - -[//000000001]: # (struct::graph\_v1 \- Tcl Data Structures) -[//000000002]: # (Generated from file 'graph1\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (struct::graph\_v1\(n\) 1\.2\.1 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::graph\_v1 \- Create and manipulate directed graph objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::graph ?1\.2\.1? - -[__graphName__ *option* ?*arg arg \.\.\.*?](#1) -[*graphName* __destroy__](#2) -[*graphName* __arc append__ *arc* ?\-key *key*? *value*](#3) -[*graphName* __arc delete__ *arc* ?*arc* \.\.\.?](#4) -[*graphName* __arc exists__ *arc*](#5) -[*graphName* __arc get__ *arc* ?\-key *key*?](#6) -[*graphName* __arc getall__ *arc*](#7) -[*graphName* __arc keys__ *arc*](#8) -[*graphName* __arc keyexists__ *arc* ?\-key *key*?](#9) -[*graphName* __arc insert__ *start* *end* ?*child*?](#10) -[*graphName* __arc lappend__ *arc* ?\-key *key*? *value*](#11) -[*graphName* __arc set__ *arc* ?\-key *key*? ?*value*?](#12) -[*graphName* __arc source__ *arc*](#13) -[*graphName* __arc target__ *arc*](#14) -[*graphName* __arc unset__ *arc* ?\-key *key*?](#15) -[*graphName* __arcs__ ?\-key *key*? ?\-value *value*? ?\-in|\-out|\-adj|\-inner|\-embedding *nodelist*?](#16) -[*graphName* __node append__ *node* ?\-key *key*? *value*](#17) -[*graphName* __node degree__ ?\-in|\-out? *node*](#18) -[*graphName* __node delete__ *node* ?*node* \.\.\.?](#19) -[*graphName* __node exists__ *node*](#20) -[*graphName* __node get__ *node* ?\-key *key*?](#21) -[*graphName* __node getall__ *node*](#22) -[*graphName* __node keys__ *node*](#23) -[*graphName* __node keyexists__ *node* ?\-key *key*?](#24) -[*graphName* __node insert__ ?*child*?](#25) -[*graphName* __node lappend__ *node* ?\-key *key*? *value*](#26) -[*graphName* __node opposite__ *node* *arc*](#27) -[*graphName* __node set__ *node* ?\-key *key*? ?*value*?](#28) -[*graphName* __node unset__ *node* ?\-key *key*?](#29) -[*graphName* __nodes__ ?\-key *key*? ?\-value *value*? ?\-in|\-out|\-adj|\-inner|\-embedding *nodelist*?](#30) -[*graphName* __get__ ?\-key *key*?](#31) -[*graphName* __getall__](#32) -[*graphName* __keys__](#33) -[*graphName* __keyexists__ ?\-key *key*?](#34) -[*graphName* __set__ ?\-key *key*? ?*value*?](#35) -[*graphName* __swap__ *node1* *node2*](#36) -[*graphName* __unset__ ?\-key *key*?](#37) -[*graphName* __walk__ *node* ?\-order *order*? ?\-type *type*? ?\-dir *direction*? \-command *cmd*](#38) - -# DESCRIPTION - -The __::struct::graph__ command creates a new graph object with an -associated global Tcl command whose name is *graphName*\. This command may be -used to invoke various operations on the graph\. It has the following general -form: - - - __graphName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -A directed graph is a structure containing two collections of elements, called -*nodes* and *arcs* respectively, together with a relation \("connectivity"\) -that places a general structure upon the nodes and arcs\. - -Each arc is connected to two nodes, one of which is called the *source* and -the other the *target*\. This imposes a direction upon the arc, which is said -to go from the source to the target\. It is allowed that source and target of an -arc are the same node\. Such an arc is called a *loop*\. Whenever a node is -source or target of an arc both are said to be *adjacent*\. This extends into a -relation between nodes, i\.e\. if two nodes are connected through at least one arc -they are said to be *adjacent* too\. - -Each node can be the source and target for any number of arcs\. The former are -called the *outgoing arcs* of the node, the latter the *incoming arcs* of -the node\. The number of edges in either set is called the *in\-* resp\. the -*out\-degree* of the node\. - -In addition to maintaining the node and arc relationships, this graph -implementation allows any number of keyed values to be associated with each node -and arc\. - -The following commands are possible for graph objects: - - - *graphName* __destroy__ - - Destroy the graph, including its storage space and associated command\. - - - *graphName* __arc append__ *arc* ?\-key *key*? *value* - - Appends a *value* to one of the keyed values associated with an *arc*\. - If no *key* is specified, the key __data__ is assumed\. - - - *graphName* __arc delete__ *arc* ?*arc* \.\.\.? - - Remove the specified arcs from the graph\. - - - *graphName* __arc exists__ *arc* - - Return true if the specified *arc* exists in the graph\. - - - *graphName* __arc get__ *arc* ?\-key *key*? - - Return the value associated with the key *key* for the *arc*\. If no key - is specified, the key __data__ is assumed\. - - - *graphName* __arc getall__ *arc* - - Returns a serialized list of key/value pairs \(suitable for use with - \[__array set__\]\) for the *arc*\. - - - *graphName* __arc keys__ *arc* - - Returns a list of keys for the *arc*\. - - - *graphName* __arc keyexists__ *arc* ?\-key *key*? - - Return true if the specified *key* exists for the *arc*\. If no *key* - is specified, the key __data__ is assumed\. - - - *graphName* __arc insert__ *start* *end* ?*child*? - - Insert an arc named *child* into the graph beginning at the node *start* - and ending at the node *end*\. If the name of the new arc is not specified - the system will generate a unique name of the form *arc**x*\. - - - *graphName* __arc lappend__ *arc* ?\-key *key*? *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *arc*\. If no *key* is specified, the key __data__ is assumed\. - - - *graphName* __arc set__ *arc* ?\-key *key*? ?*value*? - - Set or get one of the keyed values associated with an arc\. If no key is - specified, the key __data__ is assumed\. Each arc that is added to a - graph has the empty string assigned to the key __data__ automatically\. - An arc may have any number of keyed values associated with it\. If *value* - is not specified, this command returns the current value assigned to the - key; if *value* is specified, this command assigns that value to the key\. - - - *graphName* __arc source__ *arc* - - Return the node the given *arc* begins at\. - - - *graphName* __arc target__ *arc* - - Return the node the given *arc* ends at\. - - - *graphName* __arc unset__ *arc* ?\-key *key*? - - Remove a keyed value from the arc *arc*\. If no key is specified, the key - __data__ is assumed\. - - - *graphName* __arcs__ ?\-key *key*? ?\-value *value*? ?\-in|\-out|\-adj|\-inner|\-embedding *nodelist*? - - Return a list of arcs in the graph\. If no restriction is specified a list - containing all arcs is returned\. Restrictions can limit the list of returned - arcs based on the nodes that are connected by the arc, on the keyed values - associated with the arc, or both\. The restrictions that involve connected - nodes have a list of nodes as argument, specified after the name of the - restriction itself\. - - * __\-in__ - - Return a list of all arcs whose target is one of the nodes in the - *nodelist*\. - - * __\-out__ - - Return a list of all arcs whose source is one of the nodes in the - *nodelist*\. - - * __\-adj__ - - Return a list of all arcs adjacent to at least one of the nodes in the - *nodelist*\. This is the union of the nodes returned by __\-in__ and - __\-out__\. - - * __\-inner__ - - Return a list of all arcs adjacent to two of the nodes in the - *nodelist*\. This is the set of arcs in the subgraph spawned by the - specified nodes\. - - * __\-embedding__ - - Return a list of all arcs adjacent to exactly one of the nodes in the - *nodelist*\. This is the set of arcs connecting the subgraph spawned by - the specified nodes to the rest of the graph\. - - * __\-key__ *key* - - Limit the list of arcs that are returned to those arcs that have an - associated key *key*\. - - * __\-value__ *value* - - This restriction can only be used in combination with __\-key__\. It - limits the list of arcs that are returned to those arcs whose associated - key *key* has the value *value*\. - - The restrictions imposed by either __\-in__, __\-out__, __\-adj__, - __\-inner__, or __\-embedded__ are applied first\. Specifying more than - one of them is illegal\. At last the restrictions set via __\-key__ \(and - __\-value__\) are applied\. Specifying more than one __\-key__ \(and - __\-value__\) is illegal\. - - - *graphName* __node append__ *node* ?\-key *key*? *value* - - Appends a *value* to one of the keyed values associated with an *node*\. - If no *key* is specified, the key __data__ is assumed\. - - - *graphName* __node degree__ ?\-in|\-out? *node* - - Return the number of arcs adjacent to the specified *node*\. If one of the - restrictions __\-in__ or __\-out__ is given only the incoming resp\. - outgoing arcs are counted\. - - - *graphName* __node delete__ *node* ?*node* \.\.\.? - - Remove the specified nodes from the graph\. All of the nodes' arcs will be - removed as well to prevent unconnected arcs\. - - - *graphName* __node exists__ *node* - - Return true if the specified *node* exists in the graph\. - - - *graphName* __node get__ *node* ?\-key *key*? - - Return the value associated with the key *key* for the *node*\. If no key - is specified, the key __data__ is assumed\. - - - *graphName* __node getall__ *node* - - Returns a serialized list of key/value pairs \(suitable for use with - \[__array set__\]\) for the *node*\. - - - *graphName* __node keys__ *node* - - Returns a list of keys for the *node*\. - - - *graphName* __node keyexists__ *node* ?\-key *key*? - - Return true if the specified *key* exists for the *node*\. If no *key* - is specified, the key __data__ is assumed\. - - - *graphName* __node insert__ ?*child*? - - Insert a node named *child* into the graph\. The nodes has no arcs - connected to it\. If the name of the new child is not specified the system - will generate a unique name of the form *node**x*\. - - - *graphName* __node lappend__ *node* ?\-key *key*? *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *node*\. If no *key* is specified, the key __data__ is assumed\. - - - *graphName* __node opposite__ *node* *arc* - - Return the node at the other end of the specified *arc*, which has to be - adjacent to the given *node*\. - - - *graphName* __node set__ *node* ?\-key *key*? ?*value*? - - Set or get one of the keyed values associated with a node\. If no key is - specified, the key __data__ is assumed\. Each node that is added to a - graph has the empty string assigned to the key __data__ automatically\. A - node may have any number of keyed values associated with it\. If *value* is - not specified, this command returns the current value assigned to the key; - if *value* is specified, this command assigns that value to the key\. - - - *graphName* __node unset__ *node* ?\-key *key*? - - Remove a keyed value from the node *node*\. If no key is specified, the key - __data__ is assumed\. - - - *graphName* __nodes__ ?\-key *key*? ?\-value *value*? ?\-in|\-out|\-adj|\-inner|\-embedding *nodelist*? - - Return a list of nodes in the graph\. Restrictions can limit the list of - returned nodes based on neighboring nodes, or based on the keyed values - associated with the node\. The restrictions that involve neighboring nodes - have a list of nodes as argument, specified after the name of the - restriction itself\. - - The possible restrictions are the same as for method __arcs__\. The set - of nodes to return is computed as the union of all source and target nodes - for all the arcs satisfying the restriction as defined for __arcs__\. - - - *graphName* __get__ ?\-key *key*? - - Return the value associated with the key *key* for the graph\. If no key is - specified, the key __data__ is assumed\. - - - *graphName* __getall__ - - Returns a serialized list of key/value pairs \(suitable for use with - \[__array set__\]\) for the whole graph\. - - - *graphName* __keys__ - - Returns a list of keys for the whole graph\. - - - *graphName* __keyexists__ ?\-key *key*? - - Return true if the specified *key* exists for the whole graph\. If no - *key* is specified, the key __data__ is assumed\. - - - *graphName* __set__ ?\-key *key*? ?*value*? - - Set or get one of the keyed values associated with a graph\. If no key is - specified, the key __data__ is assumed\. Each graph has the empty string - assigned to the key __data__ automatically\. A graph may have any number - of keyed values associated with it\. If *value* is not specified, this - command returns the current value assigned to the key; if *value* is - specified, this command assigns that value to the key\. - - - *graphName* __swap__ *node1* *node2* - - Swap the position of *node1* and *node2* in the graph\. - - - *graphName* __unset__ ?\-key *key*? - - Remove a keyed value from the graph\. If no key is specified, the key - __data__ is assumed\. - - - *graphName* __walk__ *node* ?\-order *order*? ?\-type *type*? ?\-dir *direction*? \-command *cmd* - - Perform a breadth\-first or depth\-first walk of the graph starting at the - node *node* going in either the direction of outgoing or opposite to the - incoming arcs\. - - The type of walk, breadth\-first or depth\-first, is determined by the value - of *type*; __bfs__ indicates breadth\-first, __dfs__ indicates - depth\-first\. Depth\-first is the default\. - - The order of the walk, pre\-order, post\-order or both\-order is determined by - the value of *order*; __pre__ indicates pre\-order, __post__ - indicates post\-order, __both__ indicates both\-order\. Pre\-order is the - default\. Pre\-order walking means that a node is visited before any of its - neighbors \(as defined by the *direction*, see below\)\. Post\-order walking - means that a parent is visited after any of its neighbors\. Both\-order - walking means that a node is visited before *and* after any of its - neighbors\. The combination of a bread\-first walk with post\- or both\-order is - illegal\. - - The direction of the walk is determined by the value of *dir*; - __backward__ indicates the direction opposite to the incoming arcs, - __forward__ indicates the direction of the outgoing arcs\. - - As the walk progresses, the command *cmd* will be evaluated at each node, - with the mode of the call \(__enter__ or __leave__\) and values - *graphName* and the name of the current node appended\. For a pre\-order - walk, all nodes are __enter__ed, for a post\-order all nodes are left\. In - a both\-order walk the first visit of a node __enter__s it, the second - visit __leave__s it\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: graph* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[cgraph](\.\./\.\./\.\./\.\./index\.md\#cgraph), -[graph](\.\./\.\./\.\./\.\./index\.md\#graph) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/graphops.md Index: embedded/md/tcllib/files/modules/struct/graphops.md ================================================================== --- embedded/md/tcllib/files/modules/struct/graphops.md +++ embedded/md/tcllib/files/modules/struct/graphops.md @@ -1,1469 +0,0 @@ - -[//000000001]: # (struct::graph::op \- Tcl Data Structures) -[//000000002]: # (Generated from file 'graphops\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Alejandro Paz ) -[//000000004]: # (Copyright © 2008 \(docs\) Andreas Kupries ) -[//000000005]: # (Copyright © 2009 Michal Antoniewski ) -[//000000006]: # (struct::graph::op\(n\) 0\.11\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::graph::op \- Operation for \(un\)directed graph objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Operations](#section2) - - - [Background theory and terms](#section3) - - - [Shortest Path Problem](#subsection1) - - - [Travelling Salesman Problem](#subsection2) - - - [Matching Problem](#subsection3) - - - [Cut Problems](#subsection4) - - - [K\-Center Problem](#subsection5) - - - [Flow Problems](#subsection6) - - - [Approximation algorithm](#subsection7) - - - [References](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require struct::graph::op ?0\.11\.3? - -[__struct::graph::op::toAdjacencyMatrix__ *g*](#1) -[__struct::graph::op::toAdjacencyList__ *G* ?*options*\.\.\.?](#2) -[__struct::graph::op::kruskal__ *g*](#3) -[__struct::graph::op::prim__ *g*](#4) -[__struct::graph::op::isBipartite?__ *g* ?*bipartvar*?](#5) -[__struct::graph::op::tarjan__ *g*](#6) -[__struct::graph::op::connectedComponents__ *g*](#7) -[__struct::graph::op::connectedComponentOf__ *g* *n*](#8) -[__struct::graph::op::isConnected?__ *g*](#9) -[__struct::graph::op::isCutVertex?__ *g* *n*](#10) -[__struct::graph::op::isBridge?__ *g* *a*](#11) -[__struct::graph::op::isEulerian?__ *g* ?*tourvar*?](#12) -[__struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*?](#13) -[__struct::graph::op::dijkstra__ *g* *start* ?*options*\.\.\.?](#14) -[__struct::graph::op::distance__ *g* *origin* *destination* ?*options*\.\.\.?](#15) -[__struct::graph::op::eccentricity__ *g* *n* ?*options*\.\.\.?](#16) -[__struct::graph::op::radius__ *g* ?*options*\.\.\.?](#17) -[__struct::graph::op::diameter__ *g* ?*options*\.\.\.?](#18) -[__struct::graph::op::BellmanFord__ *G* *startnode*](#19) -[__struct::graph::op::Johnsons__ *G* ?*options*\.\.\.?](#20) -[__struct::graph::op::FloydWarshall__ *G*](#21) -[__struct::graph::op::MetricTravellingSalesman__ *G*](#22) -[__struct::graph::op::Christofides__ *G*](#23) -[__struct::graph::op::GreedyMaxMatching__ *G*](#24) -[__struct::graph::op::MaxCut__ *G* *U* *V*](#25) -[__struct::graph::op::UnweightedKCenter__ *G* *k*](#26) -[__struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W*](#27) -[__struct::graph::op::GreedyMaxIndependentSet__ *G*](#28) -[__struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights*](#29) -[__struct::graph::op::VerticesCover__ *G*](#30) -[__struct::graph::op::EdmondsKarp__ *G* *s* *t*](#31) -[__struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t*](#32) -[__struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat*](#33) -[__struct::graph::op::BFS__ *G* *s* ?*outputFormat*\.\.\.?](#34) -[__struct::graph::op::MinimumDiameterSpanningTree__ *G*](#35) -[__struct::graph::op::MinimumDegreeSpanningTree__ *G*](#36) -[__struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg*](#37) -[__struct::graph::op::BlockingFlowByDinic__ *G* *s* *t*](#38) -[__struct::graph::op::BlockingFlowByMKM__ *G* *s* *t*](#39) -[__struct::graph::op::createResidualGraph__ *G* *f*](#40) -[__struct::graph::op::createAugmentingNetwork__ *G* *f* *path*](#41) -[__struct::graph::op::createLevelGraph__ *Gf* *s*](#42) -[__struct::graph::op::TSPLocalSearching__ *G* *C*](#43) -[__struct::graph::op::TSPLocalSearching3Approx__ *G* *C*](#44) -[__struct::graph::op::createSquaredGraph__ *G*](#45) -[__struct::graph::op::createCompleteGraph__ *G* *originalEdges*](#46) - -# DESCRIPTION - -The package described by this document, __struct::graph::op__, is a -companion to the package __[struct::graph](graph\.md)__\. It provides a -series of common operations and algorithms applicable to \(un\)directed graphs\. - -Despite being a companion the package is not directly dependent on -__[struct::graph](graph\.md)__, only on the API defined by that package\. -I\.e\. the operations of this package can be applied to any and all graph objects -which provide the same API as the objects created through -__[struct::graph](graph\.md)__\. - -# Operations - - - __struct::graph::op::toAdjacencyMatrix__ *g* - - This command takes the graph *g* and returns a nested list containing the - adjacency matrix of *g*\. - - The elements of the outer list are the rows of the matrix, the inner - elements are the column values in each row\. The matrix has "__n__\+1" - rows and columns, with the first row and column \(index 0\) containing the - name of the node the row/column is for\. All other elements are boolean - values, __True__ if there is an arc between the 2 nodes of the - respective row and column, and __False__ otherwise\. - - Note that the matrix is symmetric\. It does not represent the directionality - of arcs, only their presence between nodes\. It is also unable to represent - parallel arcs in *g*\. - - - __struct::graph::op::toAdjacencyList__ *G* ?*options*\.\.\.? - - Procedure creates for input graph *G*, it's representation as - *[Adjacency List](\.\./\.\./\.\./\.\./index\.md\#adjacency\_list)*\. It handles - both directed and undirected graphs \(default is undirected\)\. It returns - dictionary that for each node \(key\) returns list of nodes adjacent to it\. - When considering weighted version, for each adjacent node there is also - weight of the edge included\. - - * Arguments: - - + Graph object *G* \(input\) - - A graph to convert into an *[Adjacency - List](\.\./\.\./\.\./\.\./index\.md\#adjacency\_list)*\. - - * Options: - - + __\-directed__ - - By default *G* is operated as if it were an *Undirected graph*\. - Using this option tells the command to handle *G* as the directed - graph it is\. - - + __\-weights__ - - By default any weight information the graph *G* may have is - ignored\. Using this option tells the command to put weight - information into the result\. In that case it is expected that all - arcs have a proper weight, and an error is thrown if that is not the - case\. - - - __struct::graph::op::kruskal__ *g* - - This command takes the graph *g* and returns a list containing the names - of the arcs in *g* which span up a minimum weight spanning tree \(MST\), or, - in the case of an un\-connected graph, a minimum weight spanning forest - \(except for the 1\-vertex components\)\. Kruskal's algorithm is used to compute - the tree or forest\. This algorithm has a time complexity of *O\(E\*log E\)* - or *O\(E\* log V\)*, where *V* is the number of vertices and - *[E](\.\./\.\./\.\./\.\./index\.md\#e)* is the number of edges in graph *g*\. - - The command will throw an error if one or more arcs in *g* have no weight - associated with them\. - - A note regarding the result, the command refrains from explicitly listing - the nodes of the MST as this information is implicitly provided in the arcs - already\. - - - __struct::graph::op::prim__ *g* - - This command takes the graph *g* and returns a list containing the names - of the arcs in *g* which span up a minimum weight spanning tree \(MST\), or, - in the case of an un\-connected graph, a minimum weight spanning forest - \(except for the 1\-vertex components\)\. Prim's algorithm is used to compute - the tree or forest\. This algorithm has a time complexity between *O\(E\+V\*log - V\)* and *O\(V\*V\)*, depending on the implementation \(Fibonacci heap \+ - Adjacency list versus Adjacency Matrix\)\. As usual *V* is the number of - vertices and *[E](\.\./\.\./\.\./\.\./index\.md\#e)* the number of edges in - graph *g*\. - - The command will throw an error if one or more arcs in *g* have no weight - associated with them\. - - A note regarding the result, the command refrains from explicitly listing - the nodes of the MST as this information is implicitly provided in the arcs - already\. - - - __struct::graph::op::isBipartite?__ *g* ?*bipartvar*? - - This command takes the graph *g* and returns a boolean value indicating - whether it is bipartite \(__true__\) or not \(__false__\)\. If the - variable *bipartvar* is specified the two partitions of the graph are - there as a list, if, and only if the graph is bipartit\. If it is not the - variable, if specified, is not touched\. - - - __struct::graph::op::tarjan__ *g* - - This command computes the set of *strongly connected* components \(SCCs\) of - the graph *g*\. The result of the command is a list of sets, each of which - contains the nodes for one of the SCCs of *g*\. The union of all SCCs - covers the whole graph, and no two SCCs intersect with each other\. - - The graph *g* is *acyclic* if all SCCs in the result contain only a - single node\. The graph *g* is *strongly connected* if the result - contains only a single SCC containing all nodes of *g*\. - - - __struct::graph::op::connectedComponents__ *g* - - This command computes the set of *connected* components \(CCs\) of the graph - *g*\. The result of the command is a list of sets, each of which contains - the nodes for one of the CCs of *g*\. The union of all CCs covers the whole - graph, and no two CCs intersect with each other\. - - The graph *g* is *connected* if the result contains only a single SCC - containing all nodes of *g*\. - - - __struct::graph::op::connectedComponentOf__ *g* *n* - - This command computes the *connected* component \(CC\) of the graph *g* - containing the node *n*\. The result of the command is a sets which - contains the nodes for the CC of *n* in *g*\. - - The command will throw an error if *n* is not a node of the graph *g*\. - - - __struct::graph::op::isConnected?__ *g* - - This is a convenience command determining whether the graph *g* is - *connected* or not\. The result is a boolean value, __true__ if the - graph is connected, and __false__ otherwise\. - - - __struct::graph::op::isCutVertex?__ *g* *n* - - This command determines whether the node *n* in the graph *g* is a - *[cut vertex](\.\./\.\./\.\./\.\./index\.md\#cut\_vertex)* \(aka *[articulation - point](\.\./\.\./\.\./\.\./index\.md\#articulation\_point)*\)\. The result is a - boolean value, __true__ if the node is a cut vertex, and __false__ - otherwise\. - - The command will throw an error if *n* is not a node of the graph *g*\. - - - __struct::graph::op::isBridge?__ *g* *a* - - This command determines whether the arc *a* in the graph *g* is a - *[bridge](\.\./\.\./\.\./\.\./index\.md\#bridge)* \(aka *[cut - edge](\.\./\.\./\.\./\.\./index\.md\#cut\_edge)*, or - *[isthmus](\.\./\.\./\.\./\.\./index\.md\#isthmus)*\)\. The result is a boolean - value, __true__ if the arc is a bridge, and __false__ otherwise\. - - The command will throw an error if *a* is not an arc of the graph *g*\. - - - __struct::graph::op::isEulerian?__ *g* ?*tourvar*? - - This command determines whether the graph *g* is *eulerian* or not\. The - result is a boolean value, __true__ if the graph is eulerian, and - __false__ otherwise\. - - If the graph is eulerian and *tourvar* is specified then an euler tour is - computed as well and stored in the named variable\. The tour is represented - by the list of arcs traversed, in the order of traversal\. - - - __struct::graph::op::isSemiEulerian?__ *g* ?*pathvar*? - - This command determines whether the graph *g* is *semi\-eulerian* or not\. - The result is a boolean value, __true__ if the graph is semi\-eulerian, - and __false__ otherwise\. - - If the graph is semi\-eulerian and *pathvar* is specified then an euler - path is computed as well and stored in the named variable\. The path is - represented by the list of arcs traversed, in the order of traversal\. - - - __struct::graph::op::dijkstra__ *g* *start* ?*options*\.\.\.? - - This command determines distances in the weighted *g* from the node - *start* to all other nodes in the graph\. The options specify how to - traverse graphs, and the format of the result\. - - Two options are recognized - - * __\-arcmode__ mode - - The accepted mode values are __directed__ and __undirected__\. - For directed traversal all arcs are traversed from source to target\. For - undirected traversal all arcs are traversed in the opposite direction as - well\. Undirected traversal is the default\. - - * __\-outputformat__ format - - The accepted format values are __distances__ and __tree__\. In - both cases the result is a dictionary keyed by the names of all nodes in - the graph\. For __distances__ the value is the distance of the node - to *start*, whereas for __tree__ the value is the path from the - node to *start*, excluding the node itself, but including *start*\. - Tree format is the default\. - - - __struct::graph::op::distance__ *g* *origin* *destination* ?*options*\.\.\.? - - This command determines the \(un\)directed distance between the two nodes - *origin* and *destination* in the graph *g*\. It accepts the option - __\-arcmode__ of __struct::graph::op::dijkstra__\. - - - __struct::graph::op::eccentricity__ *g* *n* ?*options*\.\.\.? - - This command determines the \(un\)directed - *[eccentricity](\.\./\.\./\.\./\.\./index\.md\#eccentricity)* of the node *n* - in the graph *g*\. It accepts the option __\-arcmode__ of - __struct::graph::op::dijkstra__\. - - The \(un\)directed *[eccentricity](\.\./\.\./\.\./\.\./index\.md\#eccentricity)* - of a node is the maximal \(un\)directed distance between the node and any - other node in the graph\. - - - __struct::graph::op::radius__ *g* ?*options*\.\.\.? - - This command determines the \(un\)directed - *[radius](\.\./\.\./\.\./\.\./index\.md\#radius)* of the graph *g*\. It accepts - the option __\-arcmode__ of __struct::graph::op::dijkstra__\. - - The \(un\)directed *[radius](\.\./\.\./\.\./\.\./index\.md\#radius)* of a graph is - the minimal \(un\)directed - *[eccentricity](\.\./\.\./\.\./\.\./index\.md\#eccentricity)* of all nodes in - the graph\. - - - __struct::graph::op::diameter__ *g* ?*options*\.\.\.? - - This command determines the \(un\)directed - *[diameter](\.\./\.\./\.\./\.\./index\.md\#diameter)* of the graph *g*\. It - accepts the option __\-arcmode__ of __struct::graph::op::dijkstra__\. - - The \(un\)directed *[diameter](\.\./\.\./\.\./\.\./index\.md\#diameter)* of a - graph is the maximal \(un\)directed - *[eccentricity](\.\./\.\./\.\./\.\./index\.md\#eccentricity)* of all nodes in - the graph\. - - - __struct::graph::op::BellmanFord__ *G* *startnode* - - Searching for [shortests paths](#subsection1) between chosen node and - all other nodes in graph *G*\. Based on relaxation method\. In comparison to - __struct::graph::op::dijkstra__ it doesn't need assumption that all - weights on edges in input graph *G* have to be positive\. - - That generality sets the complexity of algorithm to \- *O\(V\*E\)*, where - *V* is the number of vertices and *[E](\.\./\.\./\.\./\.\./index\.md\#e)* is - number of edges in graph *G*\. - - * Arguments: - - + Graph object *G* \(input\) - - Directed, connected and edge weighted graph *G*, without any - negative cycles \( presence of cycles with the negative sum of weight - means that there is no shortest path, since the total weight becomes - lower each time the cycle is traversed \)\. Negative weights on edges - are allowed\. - - + Node *startnode* \(input\) - - The node for which we find all shortest paths to each other node in - graph *G*\. - - * Result: - - Dictionary containing for each node \(key\) distances to each other node - in graph *G*\. - - *Note:* If algorithm finds a negative cycle, it will return error message\. - - - __struct::graph::op::Johnsons__ *G* ?*options*\.\.\.? - - Searching for [shortest paths](#subsection1) between all pairs of - vertices in graph\. For sparse graphs asymptotically quicker than - __struct::graph::op::FloydWarshall__ algorithm\. Johnson's algorithm uses - __struct::graph::op::BellmanFord__ and - __struct::graph::op::dijkstra__ as subprocedures\. - - Time complexity: *O\(n\*\*2\*log\(n\) \+n\*m\)*, where *n* is the number of nodes - and *m* is the number of edges in graph *G*\. - - * Arguments: - - + Graph object *G* \(input\) - - Directed graph *G*, weighted on edges and not containing any - cycles with negative sum of weights \( the presence of such cycles - means there is no shortest path, since the total weight becomes - lower each time the cycle is traversed \)\. Negative weights on edges - are allowed\. - - * Options: - - + __\-filter__ - - Returns only existing distances, cuts all *Inf* values for - non\-existing connections between pairs of nodes\. - - * Result: - - Dictionary containing distances between all pairs of vertices\. - - - __struct::graph::op::FloydWarshall__ *G* - - Searching for [shortest paths](#subsection1) between all pairs of edges - in weighted graphs\. - - Time complexity: *O\(V^3\)* \- where *V* is number of vertices\. - - Memory complexity: *O\(V^2\)*\. - - * Arguments: - - + Graph object *G* \(input\) - - Directed and weighted graph *G*\. - - * Result: - - Dictionary containing shortest distances to each node from each node\. - - *Note:* Algorithm finds solutions dynamically\. It compares all possible - paths through the graph between each pair of vertices\. Graph shouldn't - possess any cycle with negative sum of weights \(the presence of such cycles - means there is no shortest path, since the total weight becomes lower each - time the cycle is traversed\)\. - - On the other hand algorithm can be used to find those cycles \- if any - shortest distance found by algorithm for any nodes *v* and *u* \(when - *v* is the same node as *u*\) is negative, that node surely belong to at - least one negative cycle\. - - - __struct::graph::op::MetricTravellingSalesman__ *G* - - Algorithm for solving a metric variation of [Travelling salesman - problem](#subsection2)\. *TSP problem* is *NP\-Complete*, so there is - no efficient algorithm to solve it\. Greedy methods are getting extremely - slow, with the increase in the set of nodes\. - - * Arguments: - - + Graph object *G* \(input\) - - Undirected, weighted graph *G*\. - - * Result: - - Approximated solution of minimum *Hamilton Cycle* \- closed path - visiting all nodes, each exactly one time\. - - *Note:* [It's 2\-approximation algorithm\.](#subsection7) - - - __struct::graph::op::Christofides__ *G* - - Another algorithm for solving [metric *TSP problem*](#subsection2)\. - Christofides implementation uses *Max Matching* for reaching better - approximation factor\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected, weighted graph *G*\. - - * Result: - - Approximated solution of minimum *Hamilton Cycle* \- closed path - visiting all nodes, each exactly one time\. - - *Note:* [It's is a 3/2 approximation algorithm\. ](#subsection7) - - - __struct::graph::op::GreedyMaxMatching__ *G* - - *Greedy Max Matching* procedure, which finds [maximal - matching](#subsection3) \(not maximum\) for given graph *G*\. It adds - edges to solution, beginning from edges with the lowest cost\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected graph *G*\. - - * Result: - - Set of edges \- the max matching for graph *G*\. - - - __struct::graph::op::MaxCut__ *G* *U* *V* - - Algorithm solving a [Maximum Cut Problem](#subsection4)\. - - * Arguments: - - + Graph Object *G* \(input\) - - The graph to cut\. - - + List *U* \(output\) - - Variable storing first set of nodes \(cut\) given by solution\. - - + List *V* \(output\) - - Variable storing second set of nodes \(cut\) given by solution\. - - * Result: - - Algorithm returns number of edges between found two sets of nodes\. - - *Note:* *MaxCut* is a [2\-approximation algorithm\.](#subsection7) - - - __struct::graph::op::UnweightedKCenter__ *G* *k* - - Approximation algorithm that solves a [k\-center problem](#subsection5)\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected complete graph *G*, which satisfies triangle - inequality\. - - + Integer *k* \(input\) - - Positive integer that sets the number of nodes that will be included - in *k\-center*\. - - * Result: - - Set of nodes \- *k* center for graph *G*\. - - *Note:* *UnweightedKCenter* is a [2\-approximation - algorithm\.](#subsection7) - - - __struct::graph::op::WeightedKCenter__ *G* *nodeWeights* *W* - - Approximation algorithm that solves a weighted version of [k\-center - problem](#subsection5)\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected complete graph *G*, which satisfies triangle - inequality\. - - + Integer *W* \(input\) - - Positive integer that sets the maximum possible weight of - *k\-center* found by algorithm\. - - + List *nodeWeights* \(input\) - - List of nodes and its weights in graph *G*\. - - * Result: - - Set of nodes, which is solution found by algorithm\. - - *Note:**WeightedKCenter* is a [3\-approximation - algorithm\.](#subsection7) - - - __struct::graph::op::GreedyMaxIndependentSet__ *G* - - A *maximal independent set* is an *[independent - set](\.\./\.\./\.\./\.\./index\.md\#independent\_set)* such that adding any other - node to the set forces the set to contain an edge\. - - Algorithm for input graph *G* returns set of nodes \(list\), which are - contained in Max Independent Set found by algorithm\. - - - __struct::graph::op::GreedyWeightedMaxIndependentSet__ *G* *nodeWeights* - - Weighted variation of *Maximal Independent Set*\. It takes as an input - argument not only graph *G* but also set of weights for all vertices in - graph *G*\. - - *Note:* Read also *Maximal Independent Set* description for more info\. - - - __struct::graph::op::VerticesCover__ *G* - - *Vertices cover* is a set of vertices such that each edge of the graph is - incident to at least one vertex of the set\. This 2\-approximation algorithm - searches for minimum *vertices cover*, which is a classical optimization - problem in computer science and is a typical example of an *NP\-hard* - optimization problem that has an approximation algorithm\. For input graph - *G* algorithm returns the set of edges \(list\), which is Vertex Cover found - by algorithm\. - - - __struct::graph::op::EdmondsKarp__ *G* *s* *t* - - Improved Ford\-Fulkerson's algorithm, computing the [maximum - flow](#subsection6) in given flow network *G*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Weighted and directed graph\. Each edge should have set integer - attribute considered as maximum throughputs that can be carried by - that link \(edge\)\. - - + Node *s* \(input\) - - The node that is a source for graph *G*\. - - + Node *t* \(input\) - - The node that is a sink for graph *G*\. - - * Result: - - Procedure returns the dictionary containing throughputs for all edges\. - For each key \( the edge between nodes *u* and *v* in the form of - *list u v* \) there is a value that is a throughput for that key\. Edges - where throughput values are equal to 0 are not returned \( it is like - there was no link in the flow network between nodes connected by such - edge\)\. - - The general idea of algorithm is finding the shortest augumenting paths in - graph *G*, as long as they exist, and for each path updating the edge's - weights along that path, with maximum possible throughput\. The final - \(maximum\) flow is found when there is no other augumenting path from source - to sink\. - - *Note:* Algorithm complexity : *O\(V\*E\)*, where *V* is the number of - nodes and *[E](\.\./\.\./\.\./\.\./index\.md\#e)* is the number of edges in - graph *G*\. - - - __struct::graph::op::BusackerGowen__ *G* *desiredFlow* *s* *t* - - Algorithm finds solution for a [minimum cost flow - problem](#subsection6)\. So, the goal is to find a flow, whose max value - can be *desiredFlow*, from source node *s* to sink node *t* in given - flow network *G*\. That network except throughputs at edges has also - defined a non\-negative cost on each edge \- cost of using that edge when - directing flow with that edge \( it can illustrate e\.g\. fuel usage, time or - any other measure dependent on usages \)\. - - * Arguments: - - + Graph Object *G* \(input\) - - Flow network \(directed graph\), each edge in graph should have two - integer attributes: *cost* and *throughput*\. - - + Integer *desiredFlow* \(input\) - - Max value of the flow for that network\. - - + Node *s* \(input\) - - The source node for graph *G*\. - - + Node *t* \(input\) - - The sink node for graph *G*\. - - * Result: - - Dictionary containing values of used throughputs for each edge \( key \)\. - found by algorithm\. - - *Note:* Algorithm complexity : *O\(V\*\*2\*desiredFlow\)*, where *V* is the - number of nodes in graph *G*\. - - - __struct::graph::op::ShortestsPathsByBFS__ *G* *s* *outputFormat* - - Shortest pathfinding algorithm using BFS method\. In comparison to - __struct::graph::op::dijkstra__ it can work with negative weights on - edges\. Of course negative cycles are not allowed\. Algorithm is better than - dijkstra for sparse graphs, but also there exist some pathological cases - \(those cases generally don't appear in practise\) that make time complexity - increase exponentially with the growth of the number of nodes\. - - * Arguments: - - + Graph Object *G* \(input\) - - Input graph\. - - + Node *s* \(input\) - - Source node for which all distances to each other node in graph - *G* are computed\. - - * Options and result: - - + __distances__ - - When selected *outputFormat* is __distances__ \- procedure - returns dictionary containing distances between source node *s* - and each other node in graph *G*\. - - + __paths__ - - When selected *outputFormat* is __paths__ \- procedure returns - dictionary containing for each node *v*, a list of nodes, which is - a path between source node *s* and node *v*\. - - - __struct::graph::op::BFS__ *G* *s* ?*outputFormat*\.\.\.? - - Breadth\-First Search \- algorithm creates the BFS Tree\. Memory and time - complexity: *O\(V \+ E\)*, where *V* is the number of nodes and - *[E](\.\./\.\./\.\./\.\./index\.md\#e)* is number of edges\. - - * Arguments: - - + Graph Object *G* \(input\) - - Input graph\. - - + Node *s* \(input\) - - Source node for BFS procedure\. - - * Options and result: - - + __graph__ - - When selected __outputFormat__ is __graph__ \- procedure - returns a graph structure \(__[struct::graph](graph\.md)__\), - which is equivalent to BFS tree found by algorithm\. - - + __tree__ - - When selected __outputFormat__ is __tree__ \- procedure - returns a tree structure - \(__[struct::tree](struct\_tree\.md)__\), which is equivalent to - BFS tree found by algorithm\. - - - __struct::graph::op::MinimumDiameterSpanningTree__ *G* - - The goal is to find for input graph *G*, the *spanning tree* that has - the minimum *[diameter](\.\./\.\./\.\./\.\./index\.md\#diameter)* value\. - - General idea of algorithm is to run *[BFS](\.\./\.\./\.\./\.\./index\.md\#bfs)* - over all vertices in graph *G*\. If the diameter *d* of the tree is odd, - then we are sure that tree given by *[BFS](\.\./\.\./\.\./\.\./index\.md\#bfs)* - is minimum \(considering diameter value\)\. When, diameter *d* is even, then - optimal tree can have minimum - *[diameter](\.\./\.\./\.\./\.\./index\.md\#diameter)* equal to *d* or *d\-1*\. - - In that case, what algorithm does is rebuilding the tree given by - *[BFS](\.\./\.\./\.\./\.\./index\.md\#bfs)*, by adding a vertice between root - node and root's child node \(nodes\), such that subtree created with child - node as root node is the greatest one \(has the greatests height\)\. In the - next step for such rebuilded tree, we run again - *[BFS](\.\./\.\./\.\./\.\./index\.md\#bfs)* with new node as root node\. If the - height of the tree didn't changed, we have found a better solution\. - - For input graph *G* algorithm returns the graph structure - \(__[struct::graph](graph\.md)__\) that is a spanning tree with minimum - diameter found by algorithm\. - - - __struct::graph::op::MinimumDegreeSpanningTree__ *G* - - Algorithm finds for input graph *G*, a spanning tree *T* with the - minimum possible degree\. That problem is *NP\-hard*, so algorithm is an - approximation algorithm\. - - Let *V* be the set of nodes for graph *G* and let *W* be any subset of - *V*\. Lets assume also that *OPT* is optimal solution and *ALG* is - solution found by algorithm for input graph *G*\. - - It can be proven that solution found with the algorithm must fulfil - inequality: - - *\(\(|W| \+ k \- 1\) / |W|\) <= ALG <= 2\*OPT \+ log2\(n\) \+ 1*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected simple graph\. - - * Result: - - Algorithm returns graph structure, which is equivalent to spanning tree - *T* found by algorithm\. - - - __struct::graph::op::MaximumFlowByDinic__ *G* *s* *t* *blockingFlowAlg* - - Algorithm finds [maximum flow](#subsection6) for the flow network - represented by graph *G*\. It is based on the blocking\-flow finding - methods, which give us different complexities what makes a better fit for - different graphs\. - - * Arguments: - - + Graph Object *G* \(input\) - - Directed graph *G* representing the flow network\. Each edge should - have attribute *throughput* set with integer value\. - - + Node *s* \(input\) - - The source node for the flow network *G*\. - - + Node *t* \(input\) - - The sink node for the flow network *G*\. - - * Options: - - + __dinic__ - - Procedure will find maximum flow for flow network *G* using - Dinic's algorithm \(__struct::graph::op::BlockingFlowByDinic__\) - for blocking flow computation\. - - + __mkm__ - - Procedure will find maximum flow for flow network *G* using - Malhotra, Kumar and Maheshwari's algorithm - \(__struct::graph::op::BlockingFlowByMKM__\) for blocking flow - computation\. - - * Result: - - Algorithm returns dictionary containing it's flow value for each edge - \(key\) in network *G*\. - - *Note:* __struct::graph::op::BlockingFlowByDinic__ gives *O\(m\*n^2\)* - complexity and __struct::graph::op::BlockingFlowByMKM__ gives *O\(n^3\)* - complexity, where *n* is the number of nodes and *m* is the number of - edges in flow network *G*\. - - - __struct::graph::op::BlockingFlowByDinic__ *G* *s* *t* - - Algorithm for given network *G* with source *s* and sink *t*, finds a - [blocking flow](#subsection6), which can be used to obtain a - *[maximum flow](\.\./\.\./\.\./\.\./index\.md\#maximum\_flow)* for that network - *G*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Directed graph *G* representing the flow network\. Each edge should - have attribute *throughput* set with integer value\. - - + Node *s* \(input\) - - The source node for the flow network *G*\. - - + Node *t* \(input\) - - The sink node for the flow network *G*\. - - * Result: - - Algorithm returns dictionary containing it's blocking flow value for - each edge \(key\) in network *G*\. - - *Note:* Algorithm's complexity is *O\(n\*m\)*, where *n* is the number of - nodes and *m* is the number of edges in flow network *G*\. - - - __struct::graph::op::BlockingFlowByMKM__ *G* *s* *t* - - Algorithm for given network *G* with source *s* and sink *t*, finds a - [blocking flow](#subsection6), which can be used to obtain a - *[maximum flow](\.\./\.\./\.\./\.\./index\.md\#maximum\_flow)* for that - *[network](\.\./\.\./\.\./\.\./index\.md\#network)* *G*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Directed graph *G* representing the flow network\. Each edge should - have attribute *throughput* set with integer value\. - - + Node *s* \(input\) - - The source node for the flow network *G*\. - - + Node *t* \(input\) - - The sink node for the flow network *G*\. - - * Result: - - Algorithm returns dictionary containing it's blocking flow value for - each edge \(key\) in network *G*\. - - *Note:* Algorithm's complexity is *O\(n^2\)*, where *n* is the number of - nodes in flow network *G*\. - - - __struct::graph::op::createResidualGraph__ *G* *f* - - Procedure creates a *[residual - graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)* \(or [residual - network](#subsection6) \) for network *G* and given flow *f*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Flow network \(directed graph where each edge has set attribute: - *throughput* \)\. - - + dictionary *f* \(input\) - - Current flows in flow network *G*\. - - * Result: - - Procedure returns graph structure that is a *[residual - graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)* created from input flow - network *G*\. - - - __struct::graph::op::createAugmentingNetwork__ *G* *f* *path* - - Procedure creates an [augmenting network](#subsection6) for a given - residual network *G* , flow *f* and augmenting path *path*\. - - * Arguments: - - + Graph Object *G* \(input\) - - Residual network \(directed graph\), where for every edge there are - set two attributes: throughput and cost\. - - + Dictionary *f* \(input\) - - Dictionary which contains for every edge \(key\), current value of the - flow on that edge\. - - + List *path* \(input\) - - Augmenting path, set of edges \(list\) for which we create the network - modification\. - - * Result: - - Algorithm returns graph structure containing the modified augmenting - network\. - - - __struct::graph::op::createLevelGraph__ *Gf* *s* - - For given residual graph *Gf* procedure finds the [level - graph](#subsection6)\. - - * Arguments: - - + Graph Object *Gf* \(input\) - - Residual network, where each edge has it's attribute *throughput* - set with certain value\. - - + Node *s* \(input\) - - The source node for the residual network *Gf*\. - - * Result: - - Procedure returns a *[level - graph](\.\./\.\./\.\./\.\./index\.md\#level\_graph)* created from input - *residual network*\. - - - __struct::graph::op::TSPLocalSearching__ *G* *C* - - Algorithm is a *heuristic of local searching* for *Travelling Salesman - Problem*\. For some solution of *TSP problem*, it checks if it's possible - to find a better solution\. As *TSP* is well known NP\-Complete problem, so - algorithm is a approximation algorithm \(with 2 approximation factor\)\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected and complete graph with attributes "weight" set on each - single edge\. - - + List *C* \(input\) - - A list of edges being *Hamiltonian cycle*, which is solution of - *TSP Problem* for graph *G*\. - - * Result: - - Algorithm returns the best solution for *TSP problem*, it was able to - find\. - - *Note:* The solution depends on the choosing of the beginning cycle *C*\. - It's not true that better cycle assures that better solution will be found, - but practise shows that we should give starting cycle with as small sum of - weights as possible\. - - - __struct::graph::op::TSPLocalSearching3Approx__ *G* *C* - - Algorithm is a *heuristic of local searching* for *Travelling Salesman - Problem*\. For some solution of *TSP problem*, it checks if it's possible - to find a better solution\. As *TSP* is well known NP\-Complete problem, so - algorithm is a approximation algorithm \(with 3 approximation factor\)\. - - * Arguments: - - + Graph Object *G* \(input\) - - Undirected and complete graph with attributes "weight" set on each - single edge\. - - + List *C* \(input\) - - A list of edges being *Hamiltonian cycle*, which is solution of - *TSP Problem* for graph *G*\. - - * Result: - - Algorithm returns the best solution for *TSP problem*, it was able to - find\. - - *Note:* In practise 3\-approximation algorithm turns out to be far more - effective than 2\-approximation, but it gives worser approximation factor\. - Further heuristics of local searching \(e\.g\. 4\-approximation\) doesn't give - enough boost to square the increase of approximation factor, so 2 and 3 - approximations are mainly used\. - - - __struct::graph::op::createSquaredGraph__ *G* - - X\-Squared graph is a graph with the same set of nodes as input graph *G*, - but a different set of edges\. X\-Squared graph has edge *\(u,v\)*, if and - only if, the distance between *u* and *v* nodes is not greater than X - and *u \!= v*\. - - Procedure for input graph *G*, returns its two\-squared graph\. - - *Note:* Distances used in choosing new set of edges are considering the - number of edges, not the sum of weights at edges\. - - - __struct::graph::op::createCompleteGraph__ *G* *originalEdges* - - For input graph *G* procedure adds missing arcs to make it a *[complete - graph](\.\./\.\./\.\./\.\./index\.md\#complete\_graph)*\. It also holds in variable - *originalEdges* the set of arcs that graph *G* possessed before that - operation\. - -# Background theory and terms - -## Shortest Path Problem - - - Definition \(*single\-pair shortest path problem*\): - - Formally, given a weighted graph \(let *V* be the set of vertices, and - *[E](\.\./\.\./\.\./\.\./index\.md\#e)* a set of edges\), and one vertice *v* - of *V*, find a path *P* from *v* to a *v'* of V so that the sum of - weights on edges along the path is minimal among all paths connecting v to - v'\. - - - Generalizations: - - * *The single\-source shortest path problem*, in which we have to find - shortest paths from a source vertex v to all other vertices in the - graph\. - - * *The single\-destination shortest path problem*, in which we have to - find shortest paths from all vertices in the graph to a single - destination vertex v\. This can be reduced to the single\-source shortest - path problem by reversing the edges in the graph\. - - * *The all\-pairs shortest path problem*, in which we have to find - shortest paths between every pair of vertices v, v' in the graph\. - - *Note:* The result of *Shortest Path problem* can be *Shortest Path - tree*, which is a subgraph of a given \(possibly weighted\) graph constructed - so that the distance between a selected root node and all other nodes is - minimal\. It is a tree because if there are two paths between the root node - and some vertex v \(i\.e\. a cycle\), we can delete the last edge of the longer - path without increasing the distance from the root node to any node in the - subgraph\. - -## Travelling Salesman Problem - - - Definition: - - For given edge\-weighted \(weights on edges should be positive\) graph the goal - is to find the cycle that visits each node in graph exactly once - \(*Hamiltonian cycle*\)\. - - - Generalizations: - - * *Metric TSP* \- A very natural restriction of the *TSP* is to require - that the distances between cities form a *metric*, i\.e\., they satisfy - *the triangle inequality*\. That is, for any 3 cities *A*, *B* and - *[C](\.\./\.\./\.\./\.\./index\.md\#c)*, the distance between *A* and - *[C](\.\./\.\./\.\./\.\./index\.md\#c)* must be at most the distance from - *A* to *B* plus the distance from *B* to - *[C](\.\./\.\./\.\./\.\./index\.md\#c)*\. Most natural instances of *TSP* - satisfy this constraint\. - - * *Euclidean TSP* \- Euclidean TSP, or *planar TSP*, is the *TSP* - with the distance being the ordinary *Euclidean distance*\. *Euclidean - TSP* is a particular case of *TSP* with *triangle inequality*, - since distances in plane obey triangle inequality\. However, it seems to - be easier than general *TSP* with *triangle inequality*\. For - example, *the minimum spanning tree* of the graph associated with an - instance of *Euclidean TSP* is a *Euclidean minimum spanning tree*, - and so can be computed in expected *O\(n log n\)* time for *n* points - \(considerably less than the number of edges\)\. This enables the simple - *2\-approximation algorithm* for TSP with triangle inequality above to - operate more quickly\. - - * *Asymmetric TSP* \- In most cases, the distance between two nodes in - the *TSP* network is the same in both directions\. The case where the - distance from *A* to *B* is not equal to the distance from *B* to - *A* is called *asymmetric TSP*\. A practical application of an - *asymmetric TSP* is route optimisation using street\-level routing - \(asymmetric due to one\-way streets, slip\-roads and motorways\)\. - -## Matching Problem - - - Definition: - - Given a graph *G = \(V,E\)*, a matching or *edge\-independent set* *M* in - *G* is a set of pairwise non\-adjacent edges, that is, no two edges share a - common vertex\. A vertex is *matched* if it is incident to an edge in the - *matching M*\. Otherwise the vertex is *unmatched*\. - - - Generalizations: - - * *Maximal matching* \- a matching *M* of a graph G with the property - that if any edge not in *M* is added to *M*, it is no longer a - *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)*, that is, *M* is - maximal if it is not a proper subset of any other - *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* in graph G\. In other - words, a *matching M* of a graph G is maximal if every edge in G has a - non\-empty intersection with at least one edge in *M*\. - - * *Maximum matching* \- a matching that contains the largest possible - number of edges\. There may be many *maximum matchings*\. The *matching - number* of a graph G is the size of a *maximum matching*\. Note that - every *maximum matching* is *maximal*, but not every *maximal - matching* is a *maximum matching*\. - - * *Perfect matching* \- a matching which matches all vertices of the - graph\. That is, every vertex of the graph is incident to exactly one - edge of the matching\. Every *perfect matching* is - *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)* and hence *maximal*\. - In some literature, the term *complete matching* is used\. A *perfect - matching* is also a *minimum\-size edge cover*\. Moreover, the size of - a *maximum matching* is no larger than the size of a *minimum edge - cover*\. - - * *Near\-perfect matching* \- a matching in which exactly one vertex is - unmatched\. This can only occur when the graph has an odd number of - vertices, and such a *[matching](\.\./\.\./\.\./\.\./index\.md\#matching)* - must be *[maximum](\.\./\.\./\.\./\.\./index\.md\#maximum)*\. If, for every - vertex in a graph, there is a near\-perfect matching that omits only that - vertex, the graph is also called *factor\-critical*\. - - - Related terms: - - * *Alternating path* \- given a matching *M*, an *alternating path* - is a path in which the edges belong alternatively to the matching and - not to the matching\. - - * *[Augmenting path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* \- given - a matching *M*, an *[augmenting - path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path)* is an *alternating - path* that starts from and ends on free \(unmatched\) vertices\. - -## Cut Problems - - - Definition: - - A *cut* is a partition of the vertices of a graph into two *disjoint - subsets*\. The *cut\-set* of the *cut* is the set of edges whose end - points are in different subsets of the partition\. Edges are said to be - crossing the cut if they are in its *cut\-set*\. - - Formally: - - * a *cut* *C = \(S,T\)* is a partition of *V* of a graph *G = \(V, - E\)*\. - - * an *s\-t cut* *C = \(S,T\)* of a *[flow - network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)* *N = \(V, E\)* is a cut - of *N* such that *s* is included in *S* and *t* is included in - *T*, where *s* and *t* are the - *[source](\.\./\.\./\.\./\.\./index\.md\#source)* and the *sink* of *N* - respectively\. - - * The *cut\-set* of a *cut C = \(S,T\)* is such set of edges from graph - *G = \(V, E\)* that each edge *\(u, v\)* satisfies condition that *u* - is included in *S* and *v* is included in *T*\. - - In an *unweighted undirected* graph, the size or weight of a cut is the - number of edges crossing the cut\. In a *weighted graph*, the same term is - defined by the sum of the weights of the edges crossing the cut\. - - In a *[flow network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*, an *s\-t - cut* is a cut that requires the - *[source](\.\./\.\./\.\./\.\./index\.md\#source)* and the *sink* to be in - different subsets, and its *cut\-set* only consists of edges going from the - *source's* side to the *sink's* side\. The capacity of an *s\-t cut* is - defined by the sum of capacity of each edge in the *cut\-set*\. - - The *cut* of a graph can sometimes refer to its *cut\-set* instead of the - partition\. - - - Generalizations: - - * *Minimum cut* \- A cut is minimum if the size of the cut is not larger - than the size of any other cut\. - - * *Maximum cut* \- A cut is maximum if the size of the cut is not smaller - than the size of any other cut\. - - * *Sparsest cut* \- The *Sparsest cut problem* is to bipartition the - vertices so as to minimize the ratio of the number of edges across the - cut divided by the number of vertices in the smaller half of the - partition\. - -## K\-Center Problem - - - Definitions: - - * *Unweighted K\-Center* - - For any set *S* \( which is subset of *V* \) and node *v*, let the - *connect\(v,S\)* be the cost of cheapest edge connecting *v* with any - node in *S*\. The goal is to find such *S*, that *|S| = k* and - *max\_v\{connect\(v,S\)\}* is possibly small\. - - In other words, we can use it i\.e\. for finding best locations in the - city \( nodes of input graph \) for placing k buildings, such that those - buildings will be as close as possible to all other locations in town\. - - * *Weighted K\-Center* - - The variation of *unweighted k\-center problem*\. Besides the fact graph - is edge\-weighted, there are also weights on vertices of input graph - *G*\. We've got also restriction *W*\. The goal is to choose such set - of nodes *S* \( which is a subset of *V* \), that it's total weight is - not greater than *W* and also function: *max\_v \{ min\_u \{ cost\(u,v\) - \}\}* has the smallest possible worth \( *v* is a node in *V* and - *u* is a node in *S* \)\. - -## Flow Problems - - - Definitions: - - * *the maximum flow problem* \- the goal is to find a feasible flow - through a single\-source, single\-sink flow network that is maximum\. The - *maximum flow problem* can be seen as a special case of more complex - network flow problems, such as the *circulation problem*\. The maximum - value of an *s\-t flow* is equal to the minimum capacity of an *s\-t - cut* in the network, as stated in the *max\-flow min\-cut theorem*\. - - More formally for flow network *G = \(V,E\)*, where for each edge *\(u, - v\)* we have its throuhgput *c\(u,v\)* defined\. As - *[flow](\.\./\.\./\.\./\.\./index\.md\#flow)* *F* we define set of - non\-negative integer attributes *f\(u,v\)* assigned to edges, satisfying - such conditions: - - 1. for each edge *\(u, v\)* in *G* such condition should be - satisfied: 0 <= f\(u,v\) <= c\(u,v\) - - 1. Network *G* has source node *s* such that the flow *F* is - equal to the sum of outcoming flow decreased by the sum of incoming - flow from that source node *s*\. - - 1. Network *G* has sink node *t* such that the the *\-F* value is - equal to the sum of the incoming flow decreased by the sum of - outcoming flow from that sink node *t*\. - - 1. For each node that is not a - *[source](\.\./\.\./\.\./\.\./index\.md\#source)* or *sink* the sum - of incoming flow and sum of outcoming flow should be equal\. - - * *the minimum cost flow problem* \- the goal is finding the cheapest - possible way of sending a certain amount of flow through a *[flow - network](\.\./\.\./\.\./\.\./index\.md\#flow\_network)*\. - - * *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* \- a - *[blocking flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow)* for a - *residual network* *Gf* we name such flow *b* in *Gf* that: - - 1. Each path from *sink* to - *[source](\.\./\.\./\.\./\.\./index\.md\#source)* is the shortest path - in *Gf*\. - - 1. Each shortest path in *Gf* contains an edge with fully used - throughput in *Gf\+b*\. - - * *residual network* \- for a flow network *G* and flow *f* - *residual network* is built with those edges, which can send larger - flow\. It contains only those edges, which can send flow larger than 0\. - - * *level network* \- it has the same set of nodes as *[residual - graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph)*, but has only those - edges *\(u,v\)* from *Gf* for which such equality is satisfied: - *distance\(s,u\)\+1 = distance\(s,v\)*\. - - * *[augmenting network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network)* \- - it is a modification of *residual network* considering the new flow - values\. Structure stays unchanged but values of throughputs and costs at - edges are different\. - -## Approximation algorithm - - - k\-approximation algorithm: - - Algorithm is a k\-approximation, when for *ALG* \(solution returned by - algorithm\) and *OPT* \(optimal solution\), such inequality is true: - - * for minimalization problems: *ALG/OPT <= k* - - * for maximalization problems: *OPT/ALG <= k* - -# References - - 1. [Adjacency matrix](http://en\.wikipedia\.org/wiki/Adjacency\_matrix) - - 1. [Adjacency list](http://en\.wikipedia\.org/wiki/Adjacency\_list) - - 1. [Kruskal's - algorithm](http://en\.wikipedia\.org/wiki/Kruskal%27s\_algorithm) - - 1. [Prim's algorithm](http://en\.wikipedia\.org/wiki/Prim%27s\_algorithm) - - 1. [Bipartite graph](http://en\.wikipedia\.org/wiki/Bipartite\_graph) - - 1. [Strongly connected - components](http://en\.wikipedia\.org/wiki/Strongly\_connected\_components) - - 1. [Tarjan's strongly connected components - algorithm](http://en\.wikipedia\.org/wiki/Tarjan%27s\_strongly\_connected\_components\_algorithm) - - 1. [Cut vertex](http://en\.wikipedia\.org/wiki/Cut\_vertex) - - 1. [Bridge](http://en\.wikipedia\.org/wiki/Bridge\_\(graph\_theory\)) - - 1. [Bellman\-Ford's - algorithm](http://en\.wikipedia\.org/wiki/Bellman\-Ford\_algorithm) - - 1. [Johnson's algorithm](http://en\.wikipedia\.org/wiki/Johnson\_algorithm) - - 1. [Floyd\-Warshall's - algorithm](http://en\.wikipedia\.org/wiki/Floyd\-Warshall\_algorithm) - - 1. [Travelling Salesman - Problem](http://en\.wikipedia\.org/wiki/Travelling\_salesman\_problem) - - 1. [Christofides - Algorithm](http://en\.wikipedia\.org/wiki/Christofides\_algorithm) - - 1. [Max Cut](http://en\.wikipedia\.org/wiki/Maxcut) - - 1. [Matching](http://en\.wikipedia\.org/wiki/Matching) - - 1. [Max Independent - Set](http://en\.wikipedia\.org/wiki/Maximal\_independent\_set) - - 1. [Vertex Cover](http://en\.wikipedia\.org/wiki/Vertex\_cover\_problem) - - 1. [Ford\-Fulkerson's - algorithm](http://en\.wikipedia\.org/wiki/Ford\-Fulkerson\_algorithm) - - 1. [Maximum Flow - problem](http://en\.wikipedia\.org/wiki/Maximum\_flow\_problem) - - 1. [Busacker\-Gowen's - algorithm](http://en\.wikipedia\.org/wiki/Minimum\_cost\_flow\_problem) - - 1. [Dinic's algorithm](http://en\.wikipedia\.org/wiki/Dinic's\_algorithm) - - 1. [K\-Center - problem](http://www\.csc\.kth\.se/~viggo/wwwcompendium/node128\.html) - - 1. [BFS](http://en\.wikipedia\.org/wiki/Breadth\-first\_search) - - 1. [Minimum Degree Spanning - Tree](http://en\.wikipedia\.org/wiki/Degree\-constrained\_spanning\_tree) - - 1. [Approximation - algorithm](http://en\.wikipedia\.org/wiki/Approximation\_algorithm) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: graph* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[adjacency list](\.\./\.\./\.\./\.\./index\.md\#adjacency\_list), [adjacency -matrix](\.\./\.\./\.\./\.\./index\.md\#adjacency\_matrix), -[adjacent](\.\./\.\./\.\./\.\./index\.md\#adjacent), [approximation -algorithm](\.\./\.\./\.\./\.\./index\.md\#approximation\_algorithm), -[arc](\.\./\.\./\.\./\.\./index\.md\#arc), [articulation -point](\.\./\.\./\.\./\.\./index\.md\#articulation\_point), [augmenting -network](\.\./\.\./\.\./\.\./index\.md\#augmenting\_network), [augmenting -path](\.\./\.\./\.\./\.\./index\.md\#augmenting\_path), -[bfs](\.\./\.\./\.\./\.\./index\.md\#bfs), -[bipartite](\.\./\.\./\.\./\.\./index\.md\#bipartite), [blocking -flow](\.\./\.\./\.\./\.\./index\.md\#blocking\_flow), -[bridge](\.\./\.\./\.\./\.\./index\.md\#bridge), [complete -graph](\.\./\.\./\.\./\.\./index\.md\#complete\_graph), [connected -component](\.\./\.\./\.\./\.\./index\.md\#connected\_component), [cut -edge](\.\./\.\./\.\./\.\./index\.md\#cut\_edge), [cut -vertex](\.\./\.\./\.\./\.\./index\.md\#cut\_vertex), -[degree](\.\./\.\./\.\./\.\./index\.md\#degree), [degree constrained spanning -tree](\.\./\.\./\.\./\.\./index\.md\#degree\_constrained\_spanning\_tree), -[diameter](\.\./\.\./\.\./\.\./index\.md\#diameter), -[dijkstra](\.\./\.\./\.\./\.\./index\.md\#dijkstra), -[distance](\.\./\.\./\.\./\.\./index\.md\#distance), -[eccentricity](\.\./\.\./\.\./\.\./index\.md\#eccentricity), -[edge](\.\./\.\./\.\./\.\./index\.md\#edge), [flow -network](\.\./\.\./\.\./\.\./index\.md\#flow\_network), -[graph](\.\./\.\./\.\./\.\./index\.md\#graph), -[heuristic](\.\./\.\./\.\./\.\./index\.md\#heuristic), [independent -set](\.\./\.\./\.\./\.\./index\.md\#independent\_set), -[isthmus](\.\./\.\./\.\./\.\./index\.md\#isthmus), [level -graph](\.\./\.\./\.\./\.\./index\.md\#level\_graph), [local -searching](\.\./\.\./\.\./\.\./index\.md\#local\_searching), -[loop](\.\./\.\./\.\./\.\./index\.md\#loop), -[matching](\.\./\.\./\.\./\.\./index\.md\#matching), [max -cut](\.\./\.\./\.\./\.\./index\.md\#max\_cut), [maximum -flow](\.\./\.\./\.\./\.\./index\.md\#maximum\_flow), [minimal spanning -tree](\.\./\.\./\.\./\.\./index\.md\#minimal\_spanning\_tree), [minimum cost -flow](\.\./\.\./\.\./\.\./index\.md\#minimum\_cost\_flow), [minimum degree spanning -tree](\.\./\.\./\.\./\.\./index\.md\#minimum\_degree\_spanning\_tree), [minimum diameter -spanning tree](\.\./\.\./\.\./\.\./index\.md\#minimum\_diameter\_spanning\_tree), -[neighbour](\.\./\.\./\.\./\.\./index\.md\#neighbour), -[node](\.\./\.\./\.\./\.\./index\.md\#node), -[radius](\.\./\.\./\.\./\.\./index\.md\#radius), [residual -graph](\.\./\.\./\.\./\.\./index\.md\#residual\_graph), [shortest -path](\.\./\.\./\.\./\.\./index\.md\#shortest\_path), [squared -graph](\.\./\.\./\.\./\.\./index\.md\#squared\_graph), [strongly connected -component](\.\./\.\./\.\./\.\./index\.md\#strongly\_connected\_component), -[subgraph](\.\./\.\./\.\./\.\./index\.md\#subgraph), [travelling -salesman](\.\./\.\./\.\./\.\./index\.md\#travelling\_salesman), -[vertex](\.\./\.\./\.\./\.\./index\.md\#vertex), [vertex -cover](\.\./\.\./\.\./\.\./index\.md\#vertex\_cover) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2008 Alejandro Paz -Copyright © 2008 \(docs\) Andreas Kupries -Copyright © 2009 Michal Antoniewski DELETED embedded/md/tcllib/files/modules/struct/matrix.md Index: embedded/md/tcllib/files/modules/struct/matrix.md ================================================================== --- embedded/md/tcllib/files/modules/struct/matrix.md +++ embedded/md/tcllib/files/modules/struct/matrix.md @@ -1,536 +0,0 @@ - -[//000000001]: # (struct::matrix \- Tcl Data Structures) -[//000000002]: # (Generated from file 'matrix\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2013,2019 Andreas Kupries ) -[//000000004]: # (struct::matrix\(n\) 2\.0\.4 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::matrix \- Create and manipulate matrix objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::matrix ?2\.0\.4? - -[__::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) -[__matrixName__ *option* ?*arg arg \.\.\.*?](#2) -[*matrixName* __=__ *sourcematrix*](#3) -[*matrixName* __\-\->__ *destmatrix*](#4) -[*matrixName* __add column__ ?*values*?](#5) -[*matrixName* __add row__ ?*values*?](#6) -[*matrixName* __add columns__ *n*](#7) -[*matrixName* __add rows__ *n*](#8) -[*matrixName* __cells__](#9) -[*matrixName* __cellsize__ *column row*](#10) -[*matrixName* __columns__](#11) -[*matrixName* __columnwidth__ *column*](#12) -[*matrixName* __delete column__ *column*](#13) -[*matrixName* __delete columns__ *n*](#14) -[*matrixName* __delete row__ *row*](#15) -[*matrixName* __delete rows__ *n*](#16) -[*matrixName* __deserialize__ *serialization*](#17) -[*matrixName* __destroy__](#18) -[*matrixName* __format 2string__ ?*report*?](#19) -[*matrixName* __format 2chan__ ??*report*? *channel*?](#20) -[*matrixName* __get cell__ *column row*](#21) -[*matrixName* __get column__ *column*](#22) -[*matrixName* __get rect__ *column\_tl row\_tl column\_br row\_br*](#23) -[*matrixName* __get row__ *row*](#24) -[*matrixName* __insert column__ *column* ?*values*?](#25) -[*matrixName* __insert row__ *row* ?*values*?](#26) -[*matrixName* __link__ ?\-transpose? *arrayvar*](#27) -[*matrixName* __links__](#28) -[*matrixName* __rowheight__ *row*](#29) -[*matrixName* __rows__](#30) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __all__ *pattern*](#31) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __column__ *column pattern*](#32) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __row__ *row pattern*](#33) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __rect__ *column\_tl row\_tl column\_br row\_br pattern*](#34) -[*matrixName* __serialize__ ?*column\_tl row\_tl column\_br row\_br*?](#35) -[*matrixName* __set cell__ *column row value*](#36) -[*matrixName* __set column__ *column values*](#37) -[*matrixName* __set rect__ *column row values*](#38) -[*matrixName* __set row__ *row values*](#39) -[*matrixName* __sort columns__ ?__\-increasing__|__\-decreasing__? *row*](#40) -[*matrixName* __sort rows__ ?__\-increasing__|__\-decreasing__? *column*](#41) -[*matrixName* __swap columns__ *column\_a column\_b*](#42) -[*matrixName* __swap rows__ *row\_a row\_b*](#43) -[*matrixName* __transpose__](#44) -[*matrixName* __unlink__ *arrayvar*](#45) - -# DESCRIPTION - -A matrix is a rectangular collection of cells, i\.e\. organized in rows and -columns\. Each cell contains exactly one value of arbitrary form\. The cells in -the matrix are addressed by pairs of integer numbers, with the first \(left\) -number in the pair specifying the column and the second \(right\) number -specifying the row the cell is in\. These indices are counted from 0 upward\. The -special non\-numeric index __end__ refers to the last row or column in the -matrix, depending on the context\. Indices of the form __end__\-__number__ -are counted from the end of the row or column, like they are for standard Tcl -lists\. Trying to access non\-existing cells causes an error\. - -The matrices here are created empty, i\.e\. they have neither rows nor columns\. -The user then has to add rows and columns as needed by his application\. A -specialty of this structure is the ability to export an array\-view onto its -contents\. Such can be used by tkTable, for example, to link the matrix into the -display\. - -The main command of the package is: - - - __::struct::matrix__ ?*matrixName*? ?__=__|__:=__|__as__|__deserialize__ *source*? - - The command creates a new matrix object with an associated global Tcl - command whose name is *matrixName*\. This command may be used to invoke - various operations on the matrix\. It has the following general form: - - * __matrixName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - If *matrixName* is not specified a unique name will be generated by the - package itself\. If a *source* is specified the new matrix will be - initialized to it\. For the operators __=__, __:=__, and __as__ - the argument *source* is interpreted as the name of another matrix object, - and the assignment operator __=__ will be executed\. For - __deserialize__ the *source* is a serialized matrix object and - __deserialize__ will be executed\. - - In other words - - ::struct::matrix mymatrix = b - - is equivalent to - - ::struct::matrix mymatrix - mymatrix = b - - and - - ::struct::matrix mymatrix deserialize $b - - is equivalent to - - ::struct::matrix mymatrix - mymatrix deserialize $b - -The following commands are possible for matrix objects: - - - *matrixName* __=__ *sourcematrix* - - This is the assignment operator for matrix objects\. It copies the matrix - contained in the matrix object *sourcematrix* over the matrix data in - *matrixName*\. The old contents of *matrixName* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *matrixName* __deserialize__ \[*sourcematrix* __serialize__\] - - - *matrixName* __\-\->__ *destmatrix* - - This is the reverse assignment operator for matrix objects\. It copies the - matrix contained in the matrix object *matrixName* over the matrix data in - the object *destmatrix*\. The old contents of *destmatrix* are deleted by - this operation\. - - This operation is in effect equivalent to - - > *destmatrix* __deserialize__ \[*matrixName* __serialize__\] - - - *matrixName* __add column__ ?*values*? - - Extends the matrix by one column and then acts like __set column__ \(see - below\) on this new column if there were *values* supplied\. Without - *values* the new cells will be set to the empty string\. The new column is - appended immediately behind the last existing column\. - - - *matrixName* __add row__ ?*values*? - - Extends the matrix by one row and then acts like __set row__ \(see below\) - on this new row if there were *values* supplied\. Without *values* the - new cells will be set to the empty string\. The new row is appended - immediately behind the last existing row\. - - - *matrixName* __add columns__ *n* - - Extends the matrix by *n* columns\. The new cells will be set to the empty - string\. The new columns are appended immediately behind the last existing - column\. A value of *n* equal to or smaller than 0 is not allowed\. - - - *matrixName* __add rows__ *n* - - Extends the matrix by *n* rows\. The new cells will be set to the empty - string\. The new rows are appended immediately behind the last existing row\. - A value of *n* equal to or smaller than 0 is not allowed\. - - - *matrixName* __cells__ - - Returns the number of cells currently managed by the matrix\. This is the - product of __rows__ and __columns__\. - - - *matrixName* __cellsize__ *column row* - - Returns the length of the string representation of the value currently - contained in the addressed cell\. - - - *matrixName* __columns__ - - Returns the number of columns currently managed by the matrix\. - - - *matrixName* __columnwidth__ *column* - - Returns the length of the longest string representation of all the values - currently contained in the cells of the addressed column if these are all - spanning only one line\. For cell values spanning multiple lines the length - of their longest line goes into the computation\. - - *Note:* The command recognizes ANSI color control sequences and excludes - them from the width of a line, as they are logically of zero width\. - - - *matrixName* __delete column__ *column* - - Deletes the specified column from the matrix and shifts all columns with - higher indices one index down\. - - - *matrixName* __delete columns__ *n* - - Deletes *n* columns from the right of the matrix\. The value of *n* has - to satisfy the constraint "0 < *n* < \[__matrixName__ __columns__\]" - - - *matrixName* __delete row__ *row* - - Deletes the specified row from the matrix and shifts all row with higher - indices one index down\. - - - *matrixName* __delete rows__ *n* - - Deletes *n* rows from the bottom of the matrix\. The value of *n* has to - satisfy the constraint "0 < *n* < \[__matrixName__ __rows__\]" - - - *matrixName* __deserialize__ *serialization* - - This is the complement to __serialize__\. It replaces matrix data in - *matrixName* with the matrix described by the *serialization* value\. The - old contents of *matrixName* are deleted by this operation\. - - - *matrixName* __destroy__ - - Destroys the matrix, including its storage space and associated command\. - - - *matrixName* __format 2string__ ?*report*? - - Formats the matrix using the specified report object and returns the string - containing the result of this operation\. The report has to support the - __printmatrix__ method\. If no *report* is specified the system will - use an internal report definition to format the matrix\. - - - *matrixName* __format 2chan__ ??*report*? *channel*? - - Formats the matrix using the specified report object and writes the string - containing the result of this operation into the channel\. The report has to - support the __printmatrix2channel__ method\. If no *report* is - specified the system will use an internal report definition to format the - matrix\. If no *channel* is specified the system will use __stdout__\. - - - *matrixName* __get cell__ *column row* - - Returns the value currently contained in the cell identified by row and - column index\. - - - *matrixName* __get column__ *column* - - Returns a list containing the values from all cells in the column identified - by the index\. The contents of the cell in row 0 are stored as the first - element of this list\. - - - *matrixName* __get rect__ *column\_tl row\_tl column\_br row\_br* - - Returns a list of lists of cell values\. The values stored in the result come - from the sub\-matrix whose top\-left and bottom\-right cells are specified by - *column\_tl, row\_tl* and *column\_br, row\_br* resp\. Note that the - following equations have to be true: "*column\_tl* <= *column\_br*" and - "*row\_tl* <= *row\_br*"\. The result is organized as follows: The outer - list is the list of rows, its elements are lists representing a single row\. - The row with the smallest index is the first element of the outer list\. The - elements of the row lists represent the selected cell values\. The cell with - the smallest index is the first element in each row list\. - - - *matrixName* __get row__ *row* - - Returns a list containing the values from all cells in the row identified by - the index\. The contents of the cell in column 0 are stored as the first - element of this list\. - - - *matrixName* __insert column__ *column* ?*values*? - - Extends the matrix by one column and then acts like __set column__ \(see - below\) on this new column if there were *values* supplied\. Without - *values* the new cells will be set to the empty string\. The new column is - inserted just before the column specified by the given index\. This means, if - *column* is less than or equal to zero, then the new column is inserted at - the beginning of the matrix, before the first column\. If *column* has the - value __end__, or if it is greater than or equal to the number of - columns in the matrix, then the new column is appended to the matrix, behind - the last column\. The old column at the chosen index and all columns with - higher indices are shifted one index upward\. - - - *matrixName* __insert row__ *row* ?*values*? - - Extends the matrix by one row and then acts like __set row__ \(see below\) - on this new row if there were *values* supplied\. Without *values* the - new cells will be set to the empty string\. The new row is inserted just - before the row specified by the given index\. This means, if *row* is less - than or equal to zero, then the new row is inserted at the beginning of the - matrix, before the first row\. If *row* has the value __end__, or if it - is greater than or equal to the number of rows in the matrix, then the new - row is appended to the matrix, behind the last row\. The old row at that - index and all rows with higher indices are shifted one index upward\. - - - *matrixName* __link__ ?\-transpose? *arrayvar* - - Links the matrix to the specified array variable\. This means that the - contents of all cells in the matrix is stored in the array too, with all - changes to the matrix propagated there too\. The contents of the cell - *\(column,row\)* is stored in the array using the key *column,row*\. If the - option __\-transpose__ is specified the key *row,column* will be used - instead\. It is possible to link the matrix to more than one array\. Note that - the link is bidirectional, i\.e\. changes to the array are mirrored in the - matrix too\. - - - *matrixName* __links__ - - Returns a list containing the names of all array variables the matrix was - linked to through a call to method __link__\. - - - *matrixName* __rowheight__ *row* - - Returns the height of the specified row in lines\. This is the highest number - of lines spanned by a cell over all cells in the row\. - - - *matrixName* __rows__ - - Returns the number of rows currently managed by the matrix\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __all__ *pattern* - - Searches the whole matrix for cells matching the *pattern* and returns a - list with all matches\. Each item in the aforementioned list is a list itself - and contains the column and row index of the matching cell, in this order\. - The results are ordered by column first and row second, both times in - ascending order\. This means that matches to the left and the top of the - matrix come before matches to the right and down\. - - The type of the pattern \(string, glob, regular expression\) is determined by - the option after the __search__ keyword\. If no option is given it - defaults to __\-exact__\. - - If the option __\-nocase__ is specified the search will be - case\-insensitive\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __column__ *column pattern* - - Like __search all__, but the search is restricted to the specified - column\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __row__ *row pattern* - - Like __search all__, but the search is restricted to the specified row\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __rect__ *column\_tl row\_tl column\_br row\_br pattern* - - Like __search all__, but the search is restricted to the specified - rectangular area of the matrix\. - - - *matrixName* __serialize__ ?*column\_tl row\_tl column\_br row\_br*? - - This method serializes the sub\-matrix spanned up by the rectangle - specification\. In other words it returns a tcl *value* completely - describing that matrix\. If no rectangle is specified the whole matrix will - be serialized\. This allows, for example, the transfer of matrix objects \(or - parts thereof\) over arbitrary channels, persistence, etc\. This method is - also the basis for both the copy constructor and the assignment operator\. - - The result of this method has to be semantically identical over all - implementations of the matrix interface\. This is what will enable us to copy - matrix data between different implementations of the same interface\. - - The result is a list containing exactly three items\. - - The first two elements of the list specify the number of rows and columns of - the matrix, in that order\. The values integer numbers greater than or equal - to zero\. - - The last element of the list contains the values of the matrix cells we have - serialized, in the form of a value like it is returned by the __get - rect__\. However empty cells to the right and bottom of the matrix can be - left out of that value as the size information in the serialization allows - the receiver the creation of a matrix with the proper size despite the - missing values\. - - # A possible serialization for the matrix structure - # - # | a b d g | - # | c e | - # | f | - # - # is - # - # 3 4 {{a b d g} {c e} {f}} - - - *matrixName* __set cell__ *column row value* - - Sets the value in the cell identified by row and column index to the data in - the third argument\. - - - *matrixName* __set column__ *column values* - - Sets the values in the cells identified by the column index to the elements - of the list provided as the third argument\. Each element of the list is - assigned to one cell, with the first element going into the cell in row 0 - and then upward\. If there are less values in the list than there are rows - the remaining rows are set to the empty string\. If there are more values in - the list than there are rows the superfluous elements are ignored\. The - matrix is not extended by this operation\. - - - *matrixName* __set rect__ *column row values* - - Takes a list of lists of cell values and writes them into the submatrix - whose top\-left cell is specified by the two indices\. If the sublists of the - outerlist are not of equal length the shorter sublists will be filled with - empty strings to the length of the longest sublist\. If the submatrix - specified by the top\-left cell and the number of rows and columns in the - *values* extends beyond the matrix we are modifying the over\-extending - parts of the values are ignored, i\.e\. essentially cut off\. This subcommand - expects its input in the format as returned by __get rect__\. - - - *matrixName* __set row__ *row values* - - Sets the values in the cells identified by the row index to the elements of - the list provided as the third argument\. Each element of the list is - assigned to one cell, with the first element going into the cell in column 0 - and then upward\. If there are less values in the list than there are columns - the remaining columns are set to the empty string\. If there are more values - in the list than there are columns the superfluous elements are ignored\. The - matrix is not extended by this operation\. - - - *matrixName* __sort columns__ ?__\-increasing__|__\-decreasing__? *row* - - Sorts the columns in the matrix using the data in the specified *row* as - the key to sort by\. The options __\-increasing__ and __\-decreasing__ - have the same meaning as for __lsort__\. If no option is specified - __\-increasing__ is assumed\. - - - *matrixName* __sort rows__ ?__\-increasing__|__\-decreasing__? *column* - - Sorts the rows in the matrix using the data in the specified *column* as - the key to sort by\. The options __\-increasing__ and __\-decreasing__ - have the same meaning as for __lsort__\. If no option is specified - __\-increasing__ is assumed\. - - - *matrixName* __swap columns__ *column\_a column\_b* - - Swaps the contents of the two specified columns\. - - - *matrixName* __swap rows__ *row\_a row\_b* - - Swaps the contents of the two specified rows\. - - - *matrixName* __transpose__ - - Transposes the contents of the matrix, i\.e\. swaps rows for columns and vice - versa\. - - - *matrixName* __unlink__ *arrayvar* - - Removes the link between the matrix and the specified arrayvariable, if - there is one\. - -# EXAMPLES - -The examples below assume a 5x5 matrix M with the first row containing the -values 1 to 5, with 1 in the top\-left cell\. Each other row contains the contents -of the row above it, rotated by one cell to the right\. - - % M get rect 0 0 4 4 - {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}} - - % M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}} - % M get rect 0 0 4 4 - {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}} - -Assuming that the style definitions in the example section of the manpage for -the package __[report](\.\./report/report\.md)__ are loaded into the -interpreter now an example which formats a matrix into a tabular report\. The -code filling the matrix with data is not shown\. contains useful data\. - - % ::struct::matrix m - % # ... fill m with data, assume 5 columns - % ::report::report r 5 style captionedtable 1 - % m format 2string r - +---+-------------------+-------+-------+--------+ - |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| - +---+-------------------+-------+-------+--------+ - |001|CATCH return ok |7 |13 |53.85 | - |002|CATCH return error |68 |91 |74.73 | - |003|CATCH no catch used|7 |14 |50.00 | - |004|IF if true numeric |12 |33 |36.36 | - |005|IF elseif |15 |47 |31.91 | - | |true numeric | | | | - +---+-------------------+-------+-------+--------+ - % - % # alternate way of doing the above - % r printmatrix m - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: matrix* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002\-2013,2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/matrix1.md Index: embedded/md/tcllib/files/modules/struct/matrix1.md ================================================================== --- embedded/md/tcllib/files/modules/struct/matrix1.md +++ embedded/md/tcllib/files/modules/struct/matrix1.md @@ -1,417 +0,0 @@ - -[//000000001]: # (struct::matrix\_v1 \- Tcl Data Structures) -[//000000002]: # (Generated from file 'matrix1\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002,2019 Andreas Kupries ) -[//000000004]: # (struct::matrix\_v1\(n\) 1\.2\.2 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::matrix\_v1 \- Create and manipulate matrix objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::matrix ?1\.2\.2? - -[__matrixName__ *option* ?*arg arg \.\.\.*?](#1) -[*matrixName* __add column__ ?*values*?](#2) -[*matrixName* __add row__ ?*values*?](#3) -[*matrixName* __add columns__ *n*](#4) -[*matrixName* __add rows__ *n*](#5) -[*matrixName* __cells__](#6) -[*matrixName* __cellsize__ *column row*](#7) -[*matrixName* __columns__](#8) -[*matrixName* __columnwidth__ *column*](#9) -[*matrixName* __delete column__ *column*](#10) -[*matrixName* __delete row__ *row*](#11) -[*matrixName* __destroy__](#12) -[*matrixName* __format 2string__ ?*report*?](#13) -[*matrixName* __format 2chan__ ??*report*? *channel*?](#14) -[*matrixName* __get cell__ *column row*](#15) -[*matrixName* __get column__ *column*](#16) -[*matrixName* __get rect__ *column\_tl row\_tl column\_br row\_br*](#17) -[*matrixName* __get row__ *row*](#18) -[*matrixName* __insert column__ *column* ?*values*?](#19) -[*matrixName* __insert row__ *row* ?*values*?](#20) -[*matrixName* __link__ ?\-transpose? *arrayvar*](#21) -[*matrixName* __links__](#22) -[*matrixName* __rowheight__ *row*](#23) -[*matrixName* __rows__](#24) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __all__ *pattern*](#25) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __column__ *column pattern*](#26) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __row__ *row pattern*](#27) -[*matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __rect__ *column\_tl row\_tl column\_br row\_br pattern*](#28) -[*matrixName* __set cell__ *column row value*](#29) -[*matrixName* __set column__ *column values*](#30) -[*matrixName* __set rect__ *column row values*](#31) -[*matrixName* __set row__ *row values*](#32) -[*matrixName* __sort columns__ ?__\-increasing__|__\-decreasing__? *row*](#33) -[*matrixName* __sort rows__ ?__\-increasing__|__\-decreasing__? *column*](#34) -[*matrixName* __swap columns__ *column\_a column\_b*](#35) -[*matrixName* __swap rows__ *row\_a row\_b*](#36) -[*matrixName* __unlink__ *arrayvar*](#37) - -# DESCRIPTION - -The __::struct::matrix__ command creates a new matrix object with an -associated global Tcl command whose name is *matrixName*\. This command may be -used to invoke various operations on the matrix\. It has the following general -form: - - - __matrixName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -A matrix is a rectangular collection of cells, i\.e\. organized in rows and -columns\. Each cell contains exactly one value of arbitrary form\. The cells in -the matrix are addressed by pairs of integer numbers, with the first \(left\) -number in the pair specifying the column and the second \(right\) number -specifying the row the cell is in\. These indices are counted from 0 upward\. The -special non\-numeric index __end__ refers to the last row or column in the -matrix, depending on the context\. Indices of the form __end__\-__number__ -are counted from the end of the row or column, like they are for standard Tcl -lists\. Trying to access non\-existing cells causes an error\. - -The matrices here are created empty, i\.e\. they have neither rows nor columns\. -The user then has to add rows and columns as needed by his application\. A -specialty of this structure is the ability to export an array\-view onto its -contents\. Such can be used by tkTable, for example, to link the matrix into the -display\. - -The following commands are possible for matrix objects: - - - *matrixName* __add column__ ?*values*? - - Extends the matrix by one column and then acts like __setcolumn__ \(see - below\) on this new column if there were *values* supplied\. Without - *values* the new cells will be set to the empty string\. The new column is - appended immediately behind the last existing column\. - - - *matrixName* __add row__ ?*values*? - - Extends the matrix by one row and then acts like __setrow__ \(see below\) - on this new row if there were *values* supplied\. Without *values* the - new cells will be set to the empty string\. The new row is appended - immediately behind the last existing row\. - - - *matrixName* __add columns__ *n* - - Extends the matrix by *n* columns\. The new cells will be set to the empty - string\. The new columns are appended immediately behind the last existing - column\. A value of *n* equal to or smaller than 0 is not allowed\. - - - *matrixName* __add rows__ *n* - - Extends the matrix by *n* rows\. The new cells will be set to the empty - string\. The new rows are appended immediately behind the last existing row\. - A value of *n* equal to or smaller than 0 is not allowed\. - - - *matrixName* __cells__ - - Returns the number of cells currently managed by the matrix\. This is the - product of __rows__ and __columns__\. - - - *matrixName* __cellsize__ *column row* - - Returns the length of the string representation of the value currently - contained in the addressed cell\. - - - *matrixName* __columns__ - - Returns the number of columns currently managed by the matrix\. - - - *matrixName* __columnwidth__ *column* - - Returns the length of the longest string representation of all the values - currently contained in the cells of the addressed column if these are all - spanning only one line\. For cell values spanning multiple lines the length - of their longest line goes into the computation\. - - - *matrixName* __delete column__ *column* - - Deletes the specified column from the matrix and shifts all columns with - higher indices one index down\. - - - *matrixName* __delete row__ *row* - - Deletes the specified row from the matrix and shifts all row with higher - indices one index down\. - - - *matrixName* __destroy__ - - Destroys the matrix, including its storage space and associated command\. - - - *matrixName* __format 2string__ ?*report*? - - Formats the matrix using the specified report object and returns the string - containing the result of this operation\. The report has to support the - __printmatrix__ method\. If no *report* is specified the system will - use an internal report definition to format the matrix\. - - - *matrixName* __format 2chan__ ??*report*? *channel*? - - Formats the matrix using the specified report object and writes the string - containing the result of this operation into the channel\. The report has to - support the __printmatrix2channel__ method\. If no *report* is - specified the system will use an internal report definition to format the - matrix\. If no *channel* is specified the system will use __stdout__\. - - - *matrixName* __get cell__ *column row* - - Returns the value currently contained in the cell identified by row and - column index\. - - - *matrixName* __get column__ *column* - - Returns a list containing the values from all cells in the column identified - by the index\. The contents of the cell in row 0 are stored as the first - element of this list\. - - - *matrixName* __get rect__ *column\_tl row\_tl column\_br row\_br* - - Returns a list of lists of cell values\. The values stored in the result come - from the sub\-matrix whose top\-left and bottom\-right cells are specified by - *column\_tl, row\_tl* and *column\_br, row\_br* resp\. Note that the - following equations have to be true: "*column\_tl* <= *column\_br*" and - "*row\_tl* <= *row\_br*"\. The result is organized as follows: The outer - list is the list of rows, its elements are lists representing a single row\. - The row with the smallest index is the first element of the outer list\. The - elements of the row lists represent the selected cell values\. The cell with - the smallest index is the first element in each row list\. - - - *matrixName* __get row__ *row* - - Returns a list containing the values from all cells in the row identified by - the index\. The contents of the cell in column 0 are stored as the first - element of this list\. - - - *matrixName* __insert column__ *column* ?*values*? - - Extends the matrix by one column and then acts like __setcolumn__ \(see - below\) on this new column if there were *values* supplied\. Without - *values* the new cells will be set to the empty string\. The new column is - inserted just before the column specified by the given index\. This means, if - *column* is less than or equal to zero, then the new column is inserted at - the beginning of the matrix, before the first column\. If *column* has the - value __end__, or if it is greater than or equal to the number of - columns in the matrix, then the new column is appended to the matrix, behind - the last column\. The old column at the chosen index and all columns with - higher indices are shifted one index upward\. - - - *matrixName* __insert row__ *row* ?*values*? - - Extends the matrix by one row and then acts like __setrow__ \(see below\) - on this new row if there were *values* supplied\. Without *values* the - new cells will be set to the empty string\. The new row is inserted just - before the row specified by the given index\. This means, if *row* is less - than or equal to zero, then the new row is inserted at the beginning of the - matrix, before the first row\. If *row* has the value __end__, or if it - is greater than or equal to the number of rows in the matrix, then the new - row is appended to the matrix, behind the last row\. The old row at that - index and all rows with higher indices are shifted one index upward\. - - - *matrixName* __link__ ?\-transpose? *arrayvar* - - Links the matrix to the specified array variable\. This means that the - contents of all cells in the matrix is stored in the array too, with all - changes to the matrix propagated there too\. The contents of the cell - *\(column,row\)* is stored in the array using the key *column,row*\. If the - option __\-transpose__ is specified the key *row,column* will be used - instead\. It is possible to link the matrix to more than one array\. Note that - the link is bidirectional, i\.e\. changes to the array are mirrored in the - matrix too\. - - - *matrixName* __links__ - - Returns a list containing the names of all array variables the matrix was - linked to through a call to method __link__\. - - - *matrixName* __rowheight__ *row* - - Returns the height of the specified row in lines\. This is the highest number - of lines spanned by a cell over all cells in the row\. - - - *matrixName* __rows__ - - Returns the number of rows currently managed by the matrix\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __all__ *pattern* - - Searches the whole matrix for cells matching the *pattern* and returns a - list with all matches\. Each item in the aforementioned list is a list itself - and contains the column and row index of the matching cell, in this order\. - The results are ordered by column first and row second, both times in - ascending order\. This means that matches to the left and the top of the - matrix come before matches to the right and down\. - - The type of the pattern \(string, glob, regular expression\) is determined by - the option after the __search__ keyword\. If no option is given it - defaults to __\-exact__\. - - If the option __\-nocase__ is specified the search will be - case\-insensitive\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __column__ *column pattern* - - Like __search all__, but the search is restricted to the specified - column\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __row__ *row pattern* - - Like __search all__, but the search is restricted to the specified row\. - - - *matrixName* __search__ ?\-nocase? ?\-exact|\-glob|\-regexp? __rect__ *column\_tl row\_tl column\_br row\_br pattern* - - Like __search all__, but the search is restricted to the specified - rectangular area of the matrix\. - - - *matrixName* __set cell__ *column row value* - - Sets the value in the cell identified by row and column index to the data in - the third argument\. - - - *matrixName* __set column__ *column values* - - Sets the values in the cells identified by the column index to the elements - of the list provided as the third argument\. Each element of the list is - assigned to one cell, with the first element going into the cell in row 0 - and then upward\. If there are less values in the list than there are rows - the remaining rows are set to the empty string\. If there are more values in - the list than there are rows the superfluous elements are ignored\. The - matrix is not extended by this operation\. - - - *matrixName* __set rect__ *column row values* - - Takes a list of lists of cell values and writes them into the submatrix - whose top\-left cell is specified by the two indices\. If the sublists of the - outerlist are not of equal length the shorter sublists will be filled with - empty strings to the length of the longest sublist\. If the submatrix - specified by the top\-left cell and the number of rows and columns in the - *values* extends beyond the matrix we are modifying the over\-extending - parts of the values are ignored, i\.e\. essentially cut off\. This subcommand - expects its input in the format as returned by __getrect__\. - - - *matrixName* __set row__ *row values* - - Sets the values in the cells identified by the row index to the elements of - the list provided as the third argument\. Each element of the list is - assigned to one cell, with the first element going into the cell in column 0 - and then upward\. If there are less values in the list than there are columns - the remaining columns are set to the empty string\. If there are more values - in the list than there are columns the superfluous elements are ignored\. The - matrix is not extended by this operation\. - - - *matrixName* __sort columns__ ?__\-increasing__|__\-decreasing__? *row* - - Sorts the columns in the matrix using the data in the specified *row* as - the key to sort by\. The options __\-increasing__ and __\-decreasing__ - have the same meaning as for __lsort__\. If no option is specified - __\-increasing__ is assumed\. - - - *matrixName* __sort rows__ ?__\-increasing__|__\-decreasing__? *column* - - Sorts the rows in the matrix using the data in the specified *column* as - the key to sort by\. The options __\-increasing__ and __\-decreasing__ - have the same meaning as for __lsort__\. If no option is specified - __\-increasing__ is assumed\. - - - *matrixName* __swap columns__ *column\_a column\_b* - - Swaps the contents of the two specified columns\. - - - *matrixName* __swap rows__ *row\_a row\_b* - - Swaps the contents of the two specified rows\. - - - *matrixName* __unlink__ *arrayvar* - - Removes the link between the matrix and the specified arrayvariable, if - there is one\. - -# EXAMPLES - -The examples below assume a 5x5 matrix M with the first row containing the -values 1 to 5, with 1 in the top\-left cell\. Each other row contains the contents -of the row above it, rotated by one cell to the right\. - - % M getrect 0 0 4 4 - {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}} - - % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}} - % M getrect 0 0 4 4 - {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}} - -Assuming that the style definitions in the example section of the manpage for -the package __[report](\.\./report/report\.md)__ are loaded into the -interpreter now an example which formats a matrix into a tabular report\. The -code filling the matrix with data is not shown\. contains useful data\. - - % ::struct::matrix m - % # ... fill m with data, assume 5 columns - % ::report::report r 5 style captionedtable 1 - % m format 2string r - +---+-------------------+-------+-------+--------+ - |000|VERSIONS: |2:8.4a3|1:8.4a3|1:8.4a3%| - +---+-------------------+-------+-------+--------+ - |001|CATCH return ok |7 |13 |53.85 | - |002|CATCH return error |68 |91 |74.73 | - |003|CATCH no catch used|7 |14 |50.00 | - |004|IF if true numeric |12 |33 |36.36 | - |005|IF elseif |15 |47 |31.91 | - | |true numeric | | | | - +---+-------------------+-------+-------+--------+ - % - % # alternate way of doing the above - % r printmatrix m - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: matrix* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002,2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/pool.md Index: embedded/md/tcllib/files/modules/struct/pool.md ================================================================== --- embedded/md/tcllib/files/modules/struct/pool.md +++ embedded/md/tcllib/files/modules/struct/pool.md @@ -1,419 +0,0 @@ - -[//000000001]: # (struct::pool \- Tcl Data Structures) -[//000000002]: # (Generated from file 'pool\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Erik Leunissen ) -[//000000004]: # (struct::pool\(n\) 1\.2\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::pool \- Create and manipulate pool objects \(of discrete items\) - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [POOLS AND ALLOCATION](#section2) - - - [ITEMS](#section3) - - - [POOL OBJECT COMMAND](#section4) - - - [EXAMPLES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::pool ?1\.2\.3? - -[__::struct::pool__ ?*poolName*? ?*maxsize*?](#1) -[__poolName__ *option* ?*arg arg \.\.\.*?](#2) -[*poolName* __add__ *itemName1* ?*itemName2 itemName3 \.\.\.*?](#3) -[*poolName* __clear__ ?__\-force__?](#4) -[*poolName* __destroy__ ?__\-force__?](#5) -[*poolName* __info__ *type* ?*arg*?](#6) -[*poolName* __maxsize__ ?*maxsize*?](#7) -[*poolName* __release__ *itemName*](#8) -[*poolName* __remove__ *itemName* ?__\-force__?](#9) -[*poolName* __request__ itemVar ?options?](#10) - -# DESCRIPTION - -This package provides pool objects which can be used to manage finite -collections of discrete items\. - - - __::struct::pool__ ?*poolName*? ?*maxsize*? - - Creates a new pool object\. If no *poolName* is supplied, then the new pool - will be named pool__X__, where X is a positive integer\. The optional - second argument *maxsize* has to be a positive integer indicating the - maximum size of the pool; this is the maximum number of items the pool may - hold\. The default for this value is __10__\. - - The pool object has an associated global Tcl command whose name is - *poolName*\. This command may be used to invoke various configuration - operations on the report\. It has the following general form: - - * __poolName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - See section [POOL OBJECT COMMAND](#section4) for a detailed list of - options and their behaviour\. - -# POOLS AND ALLOCATION - -The purpose of the pool command and the pool object command that it generates, -is to manage pools of discrete items\. Examples of a pool of discrete items are: - - - the seats in a cinema, theatre, train etc\.\. for which visitors/travelers can - make a reservation; - - - the dynamic IP\-addresses that an ISP can dole out to subscribers; - - - a car rental's collection of cars, which can be rented by customers; - - - the class rooms in a school building, which need to be scheduled; - - - the database connections available to client\-threads in a web\-server - application; - - - the books in a library that customers can borrow; - - - etc \.\.\. - -The common denominator in the examples is that there is a more or less fixed -number of items \(seats, IP\-addresses, cars, \.\.\.\) that are supposed to be -allocated on a more or less regular basis\. An item can be allocated only once at -a time\. An item that is allocated, must be released before it can be -re\-allocated\. While several items in a pool are being allocated and released -continuously, the total number of items in the pool remains constant\. - -Keeping track of which items are allocated, and by whom, is the purpose of the -pool command and its subordinates\. - -*Pool parlance*: If we say that an item is *allocated*, it means that the -item is *busy*, *owned* or *occupied*; it is not available anymore\. If an -item is *free*, it is *available*\. Deallocating an item is equivalent to -setting free or releasing an item\. The person or entity to which the item has -been allotted is said to own the item\. - -# ITEMS - -*Discrete items* - -The __[pool](\.\./\.\./\.\./\.\./index\.md\#pool)__ command is designed for -*discrete items only*\. Note that there are pools where allocation occurs on a -non\-discrete basis, for example computer memory\. There are also pools from which -the shares that are doled out are not expected to be returned, for example a -charity fund or a pan of soup from which you may receive a portion\. Finally, -there are even pools from which nothing is ever allocated or returned, like a -swimming pool or a cesspool\. - -*Unique item names* - -A pool cannot manage duplicate item names\. Therefore, items in a pool must have -unique names\. - -*Item equivalence* - -From the point of view of the manager of a pool, items are equivalent\. The -manager of a pool is indifferent about which entity/person occupies a given -item\. However, clients may have preferences for a particular item, based on some -item property they know\. - -*Preferences* - -A future owner may have a preference for a particular item\. Preference based -allocation is supported \(see the __\-prefer__ option to the request -subcommand\)\. A preference for a particular item is most likely to result from -variability among features associated with the items\. Note that the pool -commands themselves are not designed to manage such item properties\. If item -properties play a role in an application, they should be managed separately\. - -# POOL OBJECT COMMAND - -The following subcommands and corresponding arguments are available to any pool -object command\. - - - *poolName* __add__ *itemName1* ?*itemName2 itemName3 \.\.\.*? - - This command adds the items on the command line to the pool\. If duplicate - item names occur on the command line, an error is raised\. If one or more of - the items already exist in the pool, this also is considered an error\. - - - *poolName* __clear__ ?__\-force__? - - Removes all items from the pool\. If there are any allocated items at the - time when the command is invoked, an error is raised\. This behaviour may be - modified through the __\-force__ argument\. If it is supplied on the - command line, the pool will be cleared regardless the allocation state of - its items\. - - - *poolName* __destroy__ ?__\-force__? - - Destroys the pool data structure, all associated variables and the - associated pool object command\. By default, the command checks whether any - items are still allocated and raises an error if such is the case\. This - behaviour may be modified through the argument __\-force__\. If it is - supplied on the command line, the pool data structure will be destroyed - regardless allocation state of its items\. - - - *poolName* __info__ *type* ?*arg*? - - Returns various information about the pool for further programmatic use\. The - *type* argument indicates the type of information requested\. Only the type - __allocID__ uses an additional argument\. - - * __allocID__ *itemName* - - returns the allocID of the item whose name is *itemName*\. Free items - have an allocation id of __\-1__\. - - * __allitems__ - - returns a list of all items in the pool\. - - * __allocstate__ - - Returns a list of key\-value pairs, where the keys are the items and the - values are the corresponding allocation id's\. Free items have an - allocation id of __\-1__\. - - * __cursize__ - - returns the current pool size, i\.e\. the number of items in the pool\. - - * __freeitems__ - - returns a list of items that currently are not allocated\. - - * __maxsize__ - - returns the maximum size of the pool\. - - - *poolName* __maxsize__ ?*maxsize*? - - Sets or queries the maximum size of the pool, depending on whether the - *maxsize* argument is supplied or not\. If *maxsize* is supplied, the - maximum size of the pool will be set to that value\. If no argument is - supplied, the current maximum size of the pool is returned\. In this variant, - the command is an alias for: - - __poolName info maxsize__\. - - The *maxsize* argument has to be a positive integer\. - - - *poolName* __release__ *itemName* - - Releases the item whose name is *itemName* that was allocated previously\. - An error is raised if the item was not allocated at the time when the - command was issued\. - - - *poolName* __remove__ *itemName* ?__\-force__? - - Removes the item whose name is *itemName* from the pool\. If the item was - allocated at the time when the command was invoked, an error is raised\. This - behaviour may be modified through the optional argument __\-force__\. If - it is supplied on the command line, the item will be removed regardless its - allocation state\. - - - *poolName* __request__ itemVar ?options? - - Handles a request for an item, taking into account a possible preference for - a particular item\. There are two possible outcomes depending on the - availability of items: - - 1. The request is honoured, an item is allocated and the variable whose - name is passed with the argument *itemVar* will be set to the name of - the item that was allocated\. The command returns 1\. - - 1. The request is denied\. No item is allocated\. The variable whose name is - itemVar is not set\. Attempts to read *itemVar* may raise an error if - the variable was not defined before issuing the request\. The command - returns 0\. - - The return values from this command are meant to be inspected\. The examples - below show how to do this\. Failure to check the return value may result in - erroneous behaviour\. If no preference for a particular item is supplied - through the option __\-prefer__ \(see below\), then all requests are - honoured as long as items are available\. - - The following options are supported: - - * __\-allocID__ *allocID* - - If the request is honoured, an item will be allocated to the entity - identified by allocID\. If the allocation state of an item is queried, it - is this allocation ID that will be returned\. If the option - __\-allocID__ is not supplied, the item will be given to and owned by - __dummyID__\. Allocation id's may be anything except the value \-1, - which is reserved for free items\. - - * __\-prefer__ *preferredItem* - - This option modifies the allocation strategy as follows: If the item - whose name is *preferredItem* is not allocated at the time when the - command is invoked, the request is honoured \(return value is 1\)\. If the - item was allocated at the time when the command was invoked, the request - is denied \(return value is 0\)\. - -# EXAMPLES - -Two examples are provided\. The first one mimics a step by step interactive tclsh -session, where each step is explained\. The second example shows the usage in a -server application that talks to a back\-end application\. - -*Example 1* - -This example presents an interactive tclsh session which considers the case of a -Car rental's collection of cars\. Ten steps explain its usage in chronological -order, from the creation of the pool, via the most important stages in the usage -of a pool, to the final destruction\. - -*Note aside:* - -In this example, brand names are used to label the various items\. However, a -brand name could be regarded as a property of an item\. Because the pool command -is not designed to manage properties of items, they need to be managed -separately\. In the latter case the items should be labeled with more neutral -names such as: car1, car2, car3 , etc \.\.\. and a separate database or array -should hold the brand names associated with the car labels\. - - 1. Load the package into an interpreter - % package require pool - 0.1 - - 2. Create a pool object called `CarPool' with a maximum size of 55 items (cars): - % pool CarPool 55 - CarPool - - 4. Add items to the pool: - % CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen - - 5. Somebody crashed the Toyota. Remove it from the pool as follows: - % CarPool remove Toyota - - 6. Acquired a new car for the pool. Add it as follows: - % CarPool add Nissan - - 7. Check whether the pool was adjusted correctly: - % CarPool info allitems - Trabant Chrysler1 Chrysler2 Volkswagen Nissan - -Suspend the interactive session temporarily, and show the programmatic use of -the request subcommand: - - # Mrs. Swift needs a car. She doesn't have a preference for a - # particular car. We'll issue a request on her behalf as follows: - if { [CarPool request car -allocID "Mrs. Swift"] } { - # request was honoured, process the variable `car' - puts "$car has been allocated to [CarPool info allocID $car]." - } else { - # request was denied - puts "No car available." - } - -Note how the __if__ command uses the value returned by the __request__ -subcommand\. - - # Suppose Mr. Wiggly has a preference for the Trabant: - if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] } { - # request was honoured, process the variable `car' - puts "$car has been allocated to [CarPool info allocID $car]." - } else { - # request was denied - puts "The Trabant was not available." - } - -Resume the interactive session: - - 8. When the car is returned then you can render it available by: - % CarPool release Trabant - - 9. When done, you delete the pool. - % CarPool destroy - Couldn't destroy `CarPool' because some items are still allocated. - - Oops, forgot that Mrs. Swift still occupies a car. - - 10. We force the destruction of the pool as follows: - % CarPool destroy -force - -*Example 2* - -This example describes the case from which the author's need for pool management -originated\. It is an example of a server application that receives requests from -client applications\. The client requests are dispatched onto a back\-end -application before being returned to the client application\. In many cases there -are a few equivalent instances of back\-end applications to which a client -request may be passed along\. The file descriptors that identify the channels to -these back\-end instances make up a pool of connections\. A particular connection -may be allocated to just one client request at a time\. - - # Create the pool of connections (pipes) - set maxpipes 10 - pool Pipes $maxpipes - for {set i 0} {$i < $maxpipes} {incr i} { - set fd [open "|backendApplication" w+] - Pipes add $fd - } - - # A client request comes in. The request is identified as `clientX'. - # Dispatch it onto an instance of a back-end application - if { [Pipes request fd -allocID clientX] } { - # a connection was allocated - # communicate to the back-end application via the variable `fd' - puts $fd "someInstruction" - # ...... etc. - } else { - # all connections are currently occupied - # store the client request in a queue for later processing, - # or return a 'Server busy' message to the client. - } - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: pool* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[discrete items](\.\./\.\./\.\./\.\./index\.md\#discrete\_items), -[finite](\.\./\.\./\.\./\.\./index\.md\#finite), -[pool](\.\./\.\./\.\./\.\./index\.md\#pool), [struct](\.\./\.\./\.\./\.\./index\.md\#struct) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002, Erik Leunissen DELETED embedded/md/tcllib/files/modules/struct/prioqueue.md Index: embedded/md/tcllib/files/modules/struct/prioqueue.md ================================================================== --- embedded/md/tcllib/files/modules/struct/prioqueue.md +++ embedded/md/tcllib/files/modules/struct/prioqueue.md @@ -1,155 +0,0 @@ - -[//000000001]: # (struct::prioqueue \- Tcl Data Structures) -[//000000002]: # (Generated from file 'prioqueue\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003 Michael Schlenker ) -[//000000004]: # (struct::prioqueue\(n\) 1\.4 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::prioqueue \- Create and manipulate prioqueue objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::prioqueue ?1\.4? - -[__::struct::prioqueue__ ?__\-ascii|\-dictionary|\-integer|\-real__? ?*prioqueueName*?](#1) -[*prioqueueName* __option__ ?*arg arg \.\.\.*?](#2) -[*prioqueueName* __clear__](#3) -[*prioqueueName* __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *item*](#4) -[*prioqueueName* __destroy__](#5) -[*prioqueueName* __get__ ?*count*?](#6) -[*prioqueueName* __peek__ ?*count*?](#7) -[*prioqueueName* __peekpriority__ ?*count*?](#8) -[*prioqueueName* __put__ *item prio* ?*item prio \.\.\.*?](#9) -[*prioqueueName* __size__](#10) - -# DESCRIPTION - -This package implements a simple priority queue using nested tcl lists\. - -The command __::struct::prioqueue__ creates a new priority queue with -default priority key type *\-integer*\. This means that keys given to the -__put__ subcommand must have this type\. - -This also sets the priority ordering\. For key types *\-ascii* and -*\-dictionary* the data is sorted in ascending order \(as with __lsort__ -*\-increasing*\), thereas for *\-integer* and *\-real* the data is sorted in -descending order \(as with __lsort__ *\-decreasing*\)\. - -Prioqueue names are unrestricted, but may be recognized as options if no -priority type is given\. - - - __::struct::prioqueue__ ?__\-ascii|\-dictionary|\-integer|\-real__? ?*prioqueueName*? - - The __::struct::prioqueue__ command creates a new prioqueue object with - an associated global Tcl command whose name is *prioqueueName*\. This - command may be used to invoke various operations on the prioqueue\. It has - the following general form: - - - *prioqueueName* __option__ ?*arg arg \.\.\.*? - - __option__ and the *arg*s determine the exact behavior of the command\. - The following commands are possible for prioqueue objects: - - - *prioqueueName* __clear__ - - Remove all items from the prioqueue\. - - - *prioqueueName* __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *item* - - Remove the selected item from this priority queue\. - - - *prioqueueName* __destroy__ - - Destroy the prioqueue, including its storage space and associated command\. - - - *prioqueueName* __get__ ?*count*? - - Return the front *count* items of the prioqueue \(but not their priorities\) - and remove them from the prioqueue\. If *count* is not specified, it - defaults to 1\. If *count* is 1, the result is a simple string; otherwise, - it is a list\. If specified, *count* must be greater than or equal to 1\. If - there are no or too few items in the prioqueue, this command will throw an - error\. - - - *prioqueueName* __peek__ ?*count*? - - Return the front *count* items of the prioqueue \(but not their - priorities\), without removing them from the prioqueue\. If *count* is not - specified, it defaults to 1\. If *count* is 1, the result is a simple - string; otherwise, it is a list\. If specified, *count* must be greater - than or equal to 1\. If there are no or too few items in the queue, this - command will throw an error\. - - - *prioqueueName* __peekpriority__ ?*count*? - - Return the front *count* items priority keys, without removing them from - the prioqueue\. If *count* is not specified, it defaults to 1\. If *count* - is 1, the result is a simple string; otherwise, it is a list\. If specified, - *count* must be greater than or equal to 1\. If there are no or too few - items in the queue, this command will throw an error\. - - - *prioqueueName* __put__ *item prio* ?*item prio \.\.\.*? - - Put the *item* or items specified into the prioqueue\. *prio* must be a - valid priority key for this type of prioqueue, otherwise an error is thrown - and no item is added\. Items are inserted at their priority ranking\. Items - with equal priority are added in the order they were added\. - - - *prioqueueName* __size__ - - Return the number of items in the prioqueue\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: prioqueue* of -the [Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also -report any ideas for enhancements you may have for either package and/or -documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ordered list](\.\./\.\./\.\./\.\./index\.md\#ordered\_list), -[prioqueue](\.\./\.\./\.\./\.\./index\.md\#prioqueue), [priority -queue](\.\./\.\./\.\./\.\./index\.md\#priority\_queue) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2003 Michael Schlenker DELETED embedded/md/tcllib/files/modules/struct/queue.md Index: embedded/md/tcllib/files/modules/struct/queue.md ================================================================== --- embedded/md/tcllib/files/modules/struct/queue.md +++ embedded/md/tcllib/files/modules/struct/queue.md @@ -1,131 +0,0 @@ - -[//000000001]: # (struct::queue \- Tcl Data Structures) -[//000000002]: # (Generated from file 'queue\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (struct::queue\(n\) 1\.4\.5 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::queue \- Create and manipulate queue objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require struct::queue ?1\.4\.5? - -[*queueName* __option__ ?*arg arg \.\.\.*?](#1) -[*queueName* __clear__](#2) -[*queueName* __destroy__](#3) -[*queueName* __get__ ?*count*?](#4) -[*queueName* __peek__ ?*count*?](#5) -[*queueName* __put__ *item* ?*item \.\.\.*?](#6) -[*queueName* __unget__ *item*](#7) -[*queueName* __size__](#8) - -# DESCRIPTION - -The __::struct__ namespace contains a commands for processing finite queues\. - -It exports a single command, __::struct::queue__\. All functionality provided -here can be reached through a subcommand of this command\. - -*Note:* As of version 1\.4\.1 of this package a critcl based C implementation is -available\. This implementation however requires Tcl 8\.4 to run\. - -The __::struct::queue__ command creates a new queue object with an -associated global Tcl command whose name is *queueName*\. This command may be -used to invoke various operations on the queue\. It has the following general -form: - - - *queueName* __option__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. The - following commands are possible for queue objects: - - - *queueName* __clear__ - - Remove all items from the queue\. - - - *queueName* __destroy__ - - Destroy the queue, including its storage space and associated command\. - - - *queueName* __get__ ?*count*? - - Return the front *count* items of the queue and remove them from the - queue\. If *count* is not specified, it defaults to 1\. If *count* is 1, - the result is a simple string; otherwise, it is a list\. If specified, - *count* must be greater than or equal to 1\. If there are not enough items - in the queue to fulfull the request, this command will throw an error\. - - - *queueName* __peek__ ?*count*? - - Return the front *count* items of the queue, without removing them from - the queue\. If *count* is not specified, it defaults to 1\. If *count* is - 1, the result is a simple string; otherwise, it is a list\. If specified, - *count* must be greater than or equal to 1\. If there are not enough items - in the queue to fulfull the request, this command will throw an error\. - - - *queueName* __put__ *item* ?*item \.\.\.*? - - Put the *item* or items specified into the queue\. If more than one - *item* is given, they will be added in the order they are listed\. - - - *queueName* __unget__ *item* - - Put the *item* into the queue, at the front, i\.e\. before any other items - already in the queue\. This makes this operation the complement to the method - __get__\. - - - *queueName* __size__ - - Return the number of items in the queue\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: queue* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[graph](\.\./\.\./\.\./\.\./index\.md\#graph), [list](\.\./\.\./\.\./\.\./index\.md\#list), -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[pool](\.\./\.\./\.\./\.\./index\.md\#pool), -[prioqueue](\.\./\.\./\.\./\.\./index\.md\#prioqueue), -[record](\.\./\.\./\.\./\.\./index\.md\#record), [set](\.\./\.\./\.\./\.\./index\.md\#set), -[skiplist](\.\./\.\./\.\./\.\./index\.md\#skiplist), -[stack](\.\./\.\./\.\./\.\./index\.md\#stack), [tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# CATEGORY - -Data structures DELETED embedded/md/tcllib/files/modules/struct/record.md Index: embedded/md/tcllib/files/modules/struct/record.md ================================================================== --- embedded/md/tcllib/files/modules/struct/record.md +++ embedded/md/tcllib/files/modules/struct/record.md @@ -1,432 +0,0 @@ - -[//000000001]: # (struct::record \- Tcl Data Structures) -[//000000002]: # (Generated from file 'record\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002, Brett Schwarz ) -[//000000004]: # (struct::record\(n\) 1\.2\.2 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::record \- Define and create records \(similar to 'C' structures\) - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [RECORD MEMBERS](#section2) - - - [Getting Values](#subsection1) - - - [Setting Values](#subsection2) - - - [Alias access](#subsection3) - - - [RECORD COMMAND](#section3) - - - [INSTANCE COMMAND](#section4) - - - [EXAMPLES](#section5) - - - [Example 1 \- Contact Information](#subsection4) - - - [Example 2 \- Linked List](#subsection5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::record ?1\.2\.2? - -[__record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 \.\.\.*?](#1) -[__record show__ *record*](#2) -[__record show__ *instances* *recordName*](#3) -[__record show__ *members* *recordName*](#4) -[__record show__ *values* *instanceName*](#5) -[__record exists__ *record* *recordName*](#6) -[__record exists__ *instance* *instanceName*](#7) -[__record delete__ *record* *recordName*](#8) -[__record delete__ *instance* *instanceName*](#9) -[*instanceName* __cget__ \-*member*](#10) -[*instanceName* __cget__ \-*member1* \-*member2*](#11) -[*instanceName* __cget__](#12) -[*instanceName* __configure__](#13) -[*instanceName*](#14) -[*instanceName* __configure__ \-*member* *value*](#15) -[*instanceName* __configure__ \-*member1* *value1* \-*member2* *value2*](#16) -[*recordName* *instanceName*|__\#auto__ ?*\-member1 value1 \-member2 value2 \.\.\.*?](#17) -[*instanceName* __cget__ ?*\-member1 \-member2 \.\.\.*?](#18) -[*instanceName* __configure__ ?*\-member1 value1 \-member2 value2 \.\.\.*?](#19) - -# DESCRIPTION - -The __::struct::record__ package provides a mechanism to group variables -together as one data structure, similar to a *[C](\.\./\.\./\.\./\.\./index\.md\#c)* -structure\. The members of a record can be variables or other records\. However, a -record can not contain circular records, i\.e\. records that contain the same -record as a member\. - -This package was structured so that it is very similar to how Tk objects work\. -Each record definition creates a record object that encompasses that definition\. -Subsequently, that record object can create instances of that record\. These -instances can then be manipulated with the __cget__ and __configure__ -methods\. - -The package only contains one top level command, but several sub commands \(see -below\)\. It also obeys the namespace in which the record was defined, hence the -objects returned are fully qualified\. - - - __record define__ *recordName* *recordMembers* ?*instanceName1 instanceName2 \.\.\.*? - - Defines a record\. *recordName* is the name of the record, and is also used - as an object command\. This object command is used to create instances of the - record definition\. The *recordMembers* are the members of the record that - make up the record definition\. These are variables and other records\. If - optional *instanceName* args are specified, then an instance is generated - after the definition is created for each *instanceName*\. - - - __record show__ *record* - - Returns a list of records that have been defined\. - - - __record show__ *instances* *recordName* - - Returns the instances that have been instantiated by *recordName*\. - - - __record show__ *members* *recordName* - - Returns the members that are defined for record *recordName*\. It returns - the same format as how the records were defined\. - - - __record show__ *values* *instanceName* - - Returns a list of values that are set for the instance *instanceName*\. The - output is a list of key/value pairs\. If there are nested records, then the - values of the nested records will itself be a list\. - - - __record exists__ *record* *recordName* - - Tests for the existence of a *record* with the name *recordName*\. - - - __record exists__ *instance* *instanceName* - - Tests for the existence of a *instance* with the name *instanceName*\. - - - __record delete__ *record* *recordName* - - Deletes *recordName*, and all instances of *recordName*\. It will return - an error if the record does not exist\. - - - __record delete__ *instance* *instanceName* - - Deletes *instance* with the name of *instanceName*\. It will return an - error if the instance does not exist\. Note that this recursively deletes any - nested instances as well\. - -# RECORD MEMBERS - -Record members can either be variables, or other records, However, the same -record can not be nested witin itself \(circular\)\. To define a nested record, you -need to specify the __record__ keyword, along the with name of the record, -and the name of the instance of that nested record \(within the container\)\. For -example, it would look like this: - - # this is the nested record - record define mynestedrecord { - nest1 - nest2 - } - - # This is the main record - record define myrecord { - mem1 - mem2 - {record mynestedrecord mem3} - } - -You can also assign default or initial values to the members of a record, by -enclosing the member entry in braces: - - record define myrecord { - mem1 - {mem2 5} - } - -All instances created from this record definition will initially have __5__ -as the value for member *mem2*\. If no default is given, then the value will be -the empty string\. - -## Getting Values - -To get a value of a member, there are several ways to do this\. - - - *instanceName* __cget__ \-*member* - - In this form the built\-in __cget__ instance method returns the value of - the specified *member*\. Note the leading dash\. - - To reach a nested member use *dot notation*: - - > *instanceName* __cget__ \-mem3\.nest1 - - - *instanceName* __cget__ \-*member1* \-*member2* - - In this form the built\-in __cget__ instance method returns a list - containing the values of both specified members, in the order of - specification\. - - - *instanceName* __cget__ - - - *instanceName* __configure__ - - - *instanceName* - - These forms are all equivalent\. They return a dictionary of all members and - the associated values\. - -## Setting Values - -To set a value of a member, there are several ways to do this\. - - - *instanceName* __configure__ \-*member* *value* - - In this form the built\-in __configure__ instance method sets the - specified *member* to the given *value*\. Note the leading dash\. - - To reach a nested member use *dot notation*: - - > *instanceName* __configure__ \-mem3\.nest1 value - - - *instanceName* __configure__ \-*member1* *value1* \-*member2* *value2* - - In this form the built\-in __configure__ instance method sets all - specified members to the associated values\. - -## Alias access - -In the original implementation, access was done by using dot notation similar to -how *[C](\.\./\.\./\.\./\.\./index\.md\#c)* structures are accessed\. However, there -was a concensus to make the interface more Tcl like, which made sense\. However, -the original alias access still exists\. It might prove to be helpful to some\. - -Basically, for every member of every instance, an alias is created\. This alias -is used to get and set values for that member\. An example will illustrate the -point, using the above defined records: - - % # Create an instance first - % myrecord inst1 - ::inst1 - - % # To get a member of an instance, just use the alias. It behaves - % # like a Tcl command: - % inst1.mem1 - - % # To set a member via the alias, just include a value. And optionally - % # the equal sign - syntactic sugar. - % inst1.mem1 = 5 - 5 - - % inst1.mem1 - 5 - - % # For nested records, just continue with the dot notation. - % # note, no equal sign. - % inst1.mem3.nest1 10 - 10 - - % inst1.mem3.nest1 - 10 - - % # just the instance by itself gives all member/values pairs for that - % # instance - % inst1 - -mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} - - % # and to get all members within the nested record - % inst1.mem3 - -nest1 10 -nest2 {} - -# RECORD COMMAND - -The following subcommands and corresponding arguments are available to any -record command: - - - *recordName* *instanceName*|__\#auto__ ?*\-member1 value1 \-member2 value2 \.\.\.*? - - Using the *recordName* object command that was created from the record - definition, instances of the record definition can be created\. Once an - instance is created, it inherits the members of the record definition, very - similar to how objects work\. During instance generation, an object command - for the instance is created as well, using *instanceName*\. - - This object command is used to access the data members of the instance\. - During the instantiation, while values for that instance may be given, when - done, *all* values must be given, and be given as key/value pairs, like - for method __configure__\. Nested records have to be in list format\. - - Optionally, __\#auto__ can be used in place of *instanceName*\. When - __\#auto__ is used, the instance name will be automatically generated, - and of the form __recordName__N____, where __N__ is a unique - integer \(starting at 0\) that is generated\. - -# INSTANCE COMMAND - -The following subcommands and corresponding arguments are available to any -record instance command: - - - *instanceName* __cget__ ?*\-member1 \-member2 \.\.\.*? - - Each instance has the method __cget__\. This is very similar to how Tk - widget's __cget__ command works\. It queries the values of the members - for that particular instance\. If no arguments are given, then a dictionary - is returned\. - - - *instanceName* __configure__ ?*\-member1 value1 \-member2 value2 \.\.\.*? - - Each instance has the method __configure__\. This is very similar to how - Tk widget's __configure__ command works\. It sets the values of the - particular members for that particular instance\. If no arguments are given, - then a dictionary list is returned\. - -# EXAMPLES - -Two examples are provided to give a good illustration on how to use this -package\. - -## Example 1 \- Contact Information - -Probably the most obvious example would be to hold contact information, such as -addresses, phone numbers, comments, etc\. Since a person can have multiple phone -numbers, multiple email addresses, etc, we will use nested records to define -these\. So, the first thing we do is define the nested records: - - ## - ## This is an interactive example, to see what is returned by - ## each command as well. - ## - - % namespace import ::struct::record::* - - % # define a nested record. Notice that country has default 'USA'. - % record define locations { - street - street2 - city - state - zipcode - {country USA} - phone - } - ::locations - % # Define the main record. Notice that it uses the location record twice. - % record define contacts { - first - middle - last - {record locations home} - {record locations work} - } - ::contacts - % # Create an instance for the contacts record. - % contacts cont1 - ::cont1 - % # Display some introspection values - % record show records - ::contacts ::locations - % # - % record show values cont1 - -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} - % # - % record show instances contacts - ::cont1 - % # - % cont1 config - -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} - % # - % cont1 cget - -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} - % # copy one record to another record - % record define contacts2 [record show members contacts] - ::contacts2 - % record show members contacts2 - first middle last {record locations home} {record locations work} - % record show members contacts - first middle last {record locations home} {record locations work} - % - -## Example 2 \- Linked List - -This next example just illustrates a simple linked list - - % # define a very simple record for linked list - % record define linkedlist { - value - next - } - ::linkedlist - % linkedlist lstart - ::lstart - % lstart config -value 1 -next [linkedlist #auto] - % [lstart cget -next] config -value 2 -next [linkedlist #auto] - % [[lstart cget -next] cget -next] config -value 3 -next "end" - % set next lstart - lstart - % while 1 { - lappend values [$next cget -value] - set next [$next cget -next] - if {[string match "end" $next]} break - } - % puts "$values" - 1 2 3 - % # cleanup linked list - % # We could just use delete record linkedlist also - % foreach I [record show instances linkedlist] { - record delete instance $I - } - % record show instances linkedlist - % - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: record* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[data structures](\.\./\.\./\.\./\.\./index\.md\#data\_structures), -[record](\.\./\.\./\.\./\.\./index\.md\#record), -[struct](\.\./\.\./\.\./\.\./index\.md\#struct) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002, Brett Schwarz DELETED embedded/md/tcllib/files/modules/struct/skiplist.md Index: embedded/md/tcllib/files/modules/struct/skiplist.md ================================================================== --- embedded/md/tcllib/files/modules/struct/skiplist.md +++ embedded/md/tcllib/files/modules/struct/skiplist.md @@ -1,127 +0,0 @@ - -[//000000001]: # (struct::skiplist \- Tcl Data Structures) -[//000000002]: # (Generated from file 'skiplist\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2000 Keith Vetter) -[//000000004]: # (struct::skiplist\(n\) 1\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::skiplist \- Create and manipulate skiplists - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::skiplist ?1\.3? - -[__skiplistName__ *option* ?*arg arg \.\.\.*?](#1) -[*skiplistName* __delete__ *node* ?*node*\.\.\.?](#2) -[*skiplistName* __destroy__](#3) -[*skiplistName* __insert__ *key value*](#4) -[*skiplistName* __search__ *node* ?__\-key__ *key*?](#5) -[*skiplistName* __size__](#6) -[*skiplistName* __walk__ *cmd*](#7) - -# DESCRIPTION - -The __::struct::skiplist__ command creates a new skiplist object with an -associated global Tcl command whose name is *skiplistName*\. This command may -be used to invoke various operations on the skiplist\. It has the following -general form: - - - __skiplistName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -Skip lists are an alternative data structure to binary trees\. They can be used -to maintain ordered lists over any sequence of insertions and deletions\. Skip -lists use randomness to achieve probabilistic balancing, and as a result the -algorithms for insertion and deletion in skip lists are much simpler and faster -than those for binary trees\. - -To read more about skip lists see Pugh, William\. *Skip lists: a probabilistic -alternative to balanced trees* In: Communications of the ACM, June 1990, 33\(6\) -668\-676\. - -Currently, the key can be either a number or a string, and comparisons are -performed with the built in greater than operator\. The following commands are -possible for skiplist objects: - - - *skiplistName* __delete__ *node* ?*node*\.\.\.? - - Remove the specified nodes from the skiplist\. - - - *skiplistName* __destroy__ - - Destroy the skiplist, including its storage space and associated command\. - - - *skiplistName* __insert__ *key value* - - Insert a node with the given *key* and *value* into the skiplist\. If a - node with that key already exists, then the that node's value is updated and - its node level is returned\. Otherwise a new node is created and 0 is - returned\. - - - *skiplistName* __search__ *node* ?__\-key__ *key*? - - Search for a given key in a skiplist\. If not found then 0 is returned\. If - found, then a two element list of 1 followed by the node's value is retuned\. - - - *skiplistName* __size__ - - Return a count of the number of nodes in the skiplist\. - - - *skiplistName* __walk__ *cmd* - - Walk the skiplist from the first node to the last\. At each node, the command - *cmd* will be evaluated with the key and value of the current node - appended\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: skiplist* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[skiplist](\.\./\.\./\.\./\.\./index\.md\#skiplist) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2000 Keith Vetter DELETED embedded/md/tcllib/files/modules/struct/stack.md Index: embedded/md/tcllib/files/modules/struct/stack.md ================================================================== --- embedded/md/tcllib/files/modules/struct/stack.md +++ embedded/md/tcllib/files/modules/struct/stack.md @@ -1,150 +0,0 @@ - -[//000000001]: # (struct::stack \- Tcl Data Structures) -[//000000002]: # (Generated from file 'stack\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (struct::stack\(n\) 1\.5\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::stack \- Create and manipulate stack objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require struct::stack ?1\.5\.3? - -[*stackName* __option__ ?*arg arg \.\.\.*?](#1) -[*stackName* __clear__](#2) -[*stackName* __destroy__](#3) -[*stackName* __get__](#4) -[*stackName* __getr__](#5) -[*stackName* __peek__ ?*count*?](#6) -[*stackName* __peekr__ ?*count*?](#7) -[*stackName* __trim__ ?*newsize*?](#8) -[*stackName* __trim\*__ ?*newsize*?](#9) -[*stackName* __pop__ ?*count*?](#10) -[*stackName* __push__ *item* ?*item\.\.\.*?](#11) -[*stackName* __size__](#12) - -# DESCRIPTION - -The __::struct__ namespace contains a commands for processing finite stacks\. - -It exports a single command, __::struct::stack__\. All functionality provided -here can be reached through a subcommand of this command\. - -*Note:* As of version 1\.3\.3 of this package a critcl based C implementation is -available\. This implementation however requires Tcl 8\.4 to run\. - -The __::struct::stack__ command creates a new stack object with an -associated global Tcl command whose name is *stackName*\. This command may be -used to invoke various operations on the stack\. It has the following general -form: - - - *stackName* __option__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. The - following commands are possible for stack objects: - - - *stackName* __clear__ - - Remove all items from the stack\. - - - *stackName* __destroy__ - - Destroy the stack, including its storage space and associated command\. - - - *stackName* __get__ - - Returns the whole contents of the stack as a list, without removing them - from the stack\. - - - *stackName* __getr__ - - A variant of __get__, which returns the contents in reversed order\. - - - *stackName* __peek__ ?*count*? - - Return the top *count* items of the stack, without removing them from the - stack\. If *count* is not specified, it defaults to 1\. If *count* is 1, - the result is a simple string; otherwise, it is a list\. If specified, - *count* must be greater than or equal to 1\. If there are not enoughs items - on the stack to fulfull the request, this command will throw an error\. - - - *stackName* __peekr__ ?*count*? - - A variant of __peek__, which returns the items in reversed order\. - - - *stackName* __trim__ ?*newsize*? - - Shrinks the stack to contain at most *newsize* elements and returns a list - containing the elements which were removed\. Nothing is done if the stack is - already at the specified size, or smaller\. In that case the result is the - empty list\. - - - *stackName* __trim\*__ ?*newsize*? - - A variant of __trim__ which performs the shrinking, but does not return - the removed elements\. - - - *stackName* __pop__ ?*count*? - - Return the top *count* items of the stack, and remove them from the stack\. - If *count* is not specified, it defaults to 1\. If *count* is 1, the - result is a simple string; otherwise, it is a list\. If specified, *count* - must be greater than or equal to 1\. If there are not enoughs items on the - stack to fulfull the request, this command will throw an error\. - - - *stackName* __push__ *item* ?*item\.\.\.*? - - Push the *item* or items specified onto the stack\. If more than one - *item* is given, they will be pushed in the order they are listed\. - - - *stackName* __size__ - - Return the number of items on the stack\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: stack* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[graph](\.\./\.\./\.\./\.\./index\.md\#graph), -[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix), -[queue](\.\./\.\./\.\./\.\./index\.md\#queue), [tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# CATEGORY - -Data structures DELETED embedded/md/tcllib/files/modules/struct/struct_list.md Index: embedded/md/tcllib/files/modules/struct/struct_list.md ================================================================== --- embedded/md/tcllib/files/modules/struct/struct_list.md +++ embedded/md/tcllib/files/modules/struct/struct_list.md @@ -1,720 +0,0 @@ - -[//000000001]: # (struct::list \- Tcl Data Structures) -[//000000002]: # (Generated from file 'struct\_list\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2003\-2005 by Kevin B\. Kenny\. All rights reserved) -[//000000004]: # (Copyright © 2003\-2012 Andreas Kupries ) -[//000000005]: # (struct::list\(n\) 1\.8\.4 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::list \- Procedures for manipulating lists - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON](#section3) - - - [TABLE JOIN](#section4) - - - [REFERENCES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require struct::list ?1\.8\.4? - -[__::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*?](#1) -[__::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*?](#2) -[__::struct::list__ __lcsInvert__ *lcsData* *len1* *len2*](#3) -[__::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2*](#4) -[__::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2*](#5) -[__::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2*](#6) -[__::struct::list__ __reverse__ *sequence*](#7) -[__::struct::list__ __shuffle__ *list*](#8) -[__::struct::list__ __assign__ *sequence* *varname* ?*varname*?\.\.\.](#9) -[__::struct::list__ __flatten__ ?__\-full__? ?__\-\-__? *sequence*](#10) -[__::struct::list__ __map__ *sequence* *cmdprefix*](#11) -[__::struct::list__ __mapfor__ *var* *sequence* *script*](#12) -[__::struct::list__ __filter__ *sequence* *cmdprefix*](#13) -[__::struct::list__ __filterfor__ *var* *sequence* *expr*](#14) -[__::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*?](#15) -[__::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix*](#16) -[__::struct::list__ __shift__ *listvar*](#17) -[__::struct::list__ __iota__ *n*](#18) -[__::struct::list__ __equal__ *a* *b*](#19) -[__::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*\.\.\.?](#20) -[__::struct::list__ __repeatn__ *value* *size*\.\.\.](#21) -[__::struct::list__ __dbJoin__ ?__\-inner__|__\-left__|__\-right__|__\-full__? ?__\-keys__ *varname*? \{*keycol* *table*\}\.\.\.](#22) -[__::struct::list__ __dbJoinKeyed__ ?__\-inner__|__\-left__|__\-right__|__\-full__? ?__\-keys__ *varname*? *table*\.\.\.](#23) -[__::struct::list__ __swap__ *listvar* *i* *j*](#24) -[__::struct::list__ __firstperm__ *list*](#25) -[__::struct::list__ __nextperm__ *perm*](#26) -[__::struct::list__ __permutations__ *list*](#27) -[__::struct::list__ __foreachperm__ *var* *list* *body*](#28) - -# DESCRIPTION - -The __::struct::list__ namespace contains several useful commands for -processing Tcl lists\. Generally speaking, they implement algorithms more complex -or specialized than the ones provided by Tcl itself\. - -It exports only a single command, __struct::list__\. All functionality -provided here can be reached through a subcommand of this command\. - -# COMMANDS - - - __::struct::list__ __longestCommonSubsequence__ *sequence1* *sequence2* ?*maxOccurs*? - - Returns the longest common subsequence of elements in the two lists - *sequence1* and *sequence2*\. If the *maxOccurs* parameter is provided, - the common subsequence is restricted to elements that occur no more than - *maxOccurs* times in *sequence2*\. - - The return value is a list of two lists of equal length\. The first sublist - is of indices into *sequence1*, and the second sublist is of indices into - *sequence2*\. Each corresponding pair of indices corresponds to equal - elements in the sequences; the sequence returned is the longest possible\. - - - __::struct::list__ __longestCommonSubsequence2__ *sequence1 sequence2* ?*maxOccurs*? - - Returns an approximation to the longest common sequence of elements in the - two lists *sequence1* and *sequence2*\. If the *maxOccurs* parameter is - omitted, the subsequence computed is exactly the longest common subsequence; - otherwise, the longest common subsequence is approximated by first - determining the longest common sequence of only those elements that occur no - more than *maxOccurs* times in *sequence2*, and then using that result - to align the two lists, determining the longest common subsequences of the - sublists between the two elements\. - - As with __longestCommonSubsequence__, the return value is a list of two - lists of equal length\. The first sublist is of indices into *sequence1*, - and the second sublist is of indices into *sequence2*\. Each corresponding - pair of indices corresponds to equal elements in the sequences\. The sequence - approximates the longest common subsequence\. - - - __::struct::list__ __lcsInvert__ *lcsData* *len1* *len2* - - This command takes a description of a longest common subsequence - \(*lcsData*\), inverts it, and returns the result\. Inversion means here that - as the input describes which parts of the two sequences are identical the - output describes the differences instead\. - - To be fully defined the lengths of the two sequences have to be known and - are specified through *len1* and *len2*\. - - The result is a list where each element describes one chunk of the - differences between the two sequences\. This description is a list containing - three elements, a type and two pairs of indices into *sequence1* and - *sequence2* respectively, in this order\. The type can be one of three - values: - - * __added__ - - Describes an addition\. I\.e\. items which are missing in *sequence1* can - be found in *sequence2*\. The pair of indices into *sequence1* - describes where the added range had been expected to be in - *sequence1*\. The first index refers to the item just before the added - range, and the second index refers to the item just after the added - range\. The pair of indices into *sequence2* describes the range of - items which has been added to it\. The first index refers to the first - item in the range, and the second index refers to the last item in the - range\. - - * __deleted__ - - Describes a deletion\. I\.e\. items which are in *sequence1* are missing - from *sequence2*\. The pair of indices into *sequence1* describes the - range of items which has been deleted\. The first index refers to the - first item in the range, and the second index refers to the last item in - the range\. The pair of indices into *sequence2* describes where the - deleted range had been expected to be in *sequence2*\. The first index - refers to the item just before the deleted range, and the second index - refers to the item just after the deleted range\. - - * __changed__ - - Describes a general change\. I\.e a range of items in *sequence1* has - been replaced by a different range of items in *sequence2*\. The pair - of indices into *sequence1* describes the range of items which has - been replaced\. The first index refers to the first item in the range, - and the second index refers to the last item in the range\. The pair of - indices into *sequence2* describes the range of items replacing the - original range\. Again the first index refers to the first item in the - range, and the second index refers to the last item in the range\. - - sequence 1 = {a b r a c a d a b r a} - lcs 1 = {1 2 4 5 8 9 10} - lcs 2 = {0 1 3 4 5 6 7} - sequence 2 = {b r i c a b r a c} - - Inversion = {{deleted {0 0} {-1 0}} - {changed {3 3} {2 2}} - {deleted {6 7} {4 5}} - {added {10 11} {8 8}}} - - *Notes:* - - * An index of __\-1__ in a *deleted* chunk refers to just before the - first element of the second sequence\. - - * Also an index equal to the length of the first sequence in an *added* - chunk refers to just behind the end of the sequence\. - - - __::struct::list__ __lcsInvert2__ *lcs1* *lcs2* *len1* *len2* - - Similar to __lcsInvert__\. Instead of directly taking the result of a - call to __longestCommonSubsequence__ this subcommand expects the indices - for the two sequences in two separate lists\. - - - __::struct::list__ __lcsInvertMerge__ *lcsData* *len1* *len2* - - Similar to __lcsInvert__\. It returns essentially the same structure as - that command, except that it may contain chunks of type __unchanged__ - too\. - - These new chunks describe the parts which are unchanged between the two - sequences\. This means that the result of this command describes both the - changed and unchanged parts of the two sequences in one structure\. - - sequence 1 = {a b r a c a d a b r a} - lcs 1 = {1 2 4 5 8 9 10} - lcs 2 = {0 1 3 4 5 6 7} - sequence 2 = {b r i c a b r a c} - - Inversion/Merge = {{deleted {0 0} {-1 0}} - {unchanged {1 2} {0 1}} - {changed {3 3} {2 2}} - {unchanged {4 5} {3 4}} - {deleted {6 7} {4 5}} - {unchanged {8 10} {5 7}} - {added {10 11} {8 8}}} - - - __::struct::list__ __lcsInvertMerge2__ *lcs1* *lcs2* *len1* *len2* - - Similar to __lcsInvertMerge__\. Instead of directly taking the result of - a call to __longestCommonSubsequence__ this subcommand expects the - indices for the two sequences in two separate lists\. - - - __::struct::list__ __reverse__ *sequence* - - The subcommand takes a single *sequence* as argument and returns a new - sequence containing the elements of the input sequence in reverse order\. - - - __::struct::list__ __shuffle__ *list* - - The subcommand takes a *list* and returns a copy of that list with the - elements it contains in random order\. Every possible ordering of elements is - equally likely to be generated\. The Fisher\-Yates shuffling algorithm is used - internally\. - - - __::struct::list__ __assign__ *sequence* *varname* ?*varname*?\.\.\. - - The subcommand assigns the first __n__ elements of the input - *sequence* to the one or more variables whose names were listed after the - sequence, where __n__ is the number of specified variables\. - - If there are more variables specified than there are elements in the - *sequence* the empty string will be assigned to the superfluous variables\. - - If there are more elements in the *sequence* than variable names specified - the subcommand returns a list containing the unassigned elements\. Else an - empty list is returned\. - - tclsh> ::struct::list assign {a b c d e} foo bar - c d e - tclsh> set foo - a - tclsh> set bar - b - - - __::struct::list__ __flatten__ ?__\-full__? ?__\-\-__? *sequence* - - The subcommand takes a single *sequence* and returns a new sequence where - one level of nesting was removed from the input sequence\. In other words, - the sublists in the input sequence are replaced by their elements\. - - The subcommand will remove any nesting it finds if the option __\-full__ - is specified\. - - tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10} - 1 2 3 4 5 6 7 {8 9} 10 - tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10} - 1 2 3 4 5 6 7 8 9 10 - - - __::struct::list__ __map__ *sequence* *cmdprefix* - - The subcommand takes a *sequence* to operate on and a command prefix - \(*cmdprefix*\) specifying an operation, applies the command prefix to each - element of the sequence and returns a sequence consisting of the results of - that application\. - - The command prefix will be evaluated with a single word appended to it\. The - evaluation takes place in the context of the caller of the subcommand\. - - tclsh> # squaring all elements in a list - - tclsh> proc sqr {x} {expr {$x*$x}} - tclsh> ::struct::list map {1 2 3 4 5} sqr - 1 4 9 16 25 - - tclsh> # Retrieving the second column from a matrix - tclsh> # given as list of lists. - - tclsh> proc projection {n list} {::lindex $list $n} - tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1} - b 2 f - - - __::struct::list__ __mapfor__ *var* *sequence* *script* - - The subcommand takes a *sequence* to operate on and a tcl *script*, - applies the script to each element of the sequence and returns a sequence - consisting of the results of that application\. - - The script will be evaluated as is, and has access to the current list - element through the specified iteration variable *var*\. The evaluation - takes place in the context of the caller of the subcommand\. - - tclsh> # squaring all elements in a list - - tclsh> ::struct::list mapfor x {1 2 3 4 5} { - expr {$x * $x} - } - 1 4 9 16 25 - - tclsh> # Retrieving the second column from a matrix - tclsh> # given as list of lists. - - tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} { - lindex $x 1 - } - b 2 f - - - __::struct::list__ __filter__ *sequence* *cmdprefix* - - The subcommand takes a *sequence* to operate on and a command prefix - \(*cmdprefix*\) specifying an operation, applies the command prefix to each - element of the sequence and returns a sequence consisting of all elements of - the *sequence* for which the command prefix returned __true__\. In - other words, this command filters out all elements of the input *sequence* - which fail the test the *cmdprefix* represents, and returns the remaining - elements\. - - The command prefix will be evaluated with a single word appended to it\. The - evaluation takes place in the context of the caller of the subcommand\. - - tclsh> # removing all odd numbers from the input - - tclsh> proc even {x} {expr {($x % 2) == 0}} - tclsh> ::struct::list filter {1 2 3 4 5} even - 2 4 - - *Note:* The __filter__ is a specialized application of __fold__ - where the result is extended with the current item or not, depending o nthe - result of the test\. - - - __::struct::list__ __filterfor__ *var* *sequence* *expr* - - The subcommand takes a *sequence* to operate on and a tcl expression - \(*expr*\) specifying a condition, applies the conditionto each element of - the sequence and returns a sequence consisting of all elements of the - *sequence* for which the expression returned __true__\. In other words, - this command filters out all elements of the input *sequence* which fail - the test the condition *expr* represents, and returns the remaining - elements\. - - The expression will be evaluated as is, and has access to the current list - element through the specified iteration variable *var*\. The evaluation - takes place in the context of the caller of the subcommand\. - - tclsh> # removing all odd numbers from the input - - tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0} - 2 4 - - - __::struct::list__ __split__ *sequence* *cmdprefix* ?*passVar* *failVar*? - - This is a variant of method __filter__, see above\. Instead of returning - just the elements passing the test we get lists of both passing and failing - elements\. - - If no variable names are specified then the result of the command will be a - list containing the list of passing elements, and the list of failing - elements, in this order\. Otherwise the lists of passing and failing elements - are stored into the two specified variables, and the result will be a list - containing two numbers, the number of elements passing the test, and the - number of elements failing, in this order\. - - The interface to the test is the same as used by __filter__\. - - - __::struct::list__ __fold__ *sequence* *initialvalue* *cmdprefix* - - The subcommand takes a *sequence* to operate on, an arbitrary string - *initial value* and a command prefix \(*cmdprefix*\) specifying an - operation\. - - The command prefix will be evaluated with two words appended to it\. The - second of these words will always be an element of the sequence\. The - evaluation takes place in the context of the caller of the subcommand\. - - It then reduces the sequence into a single value through repeated - application of the command prefix and returns that value\. This reduction is - done by - - * __1__ - - Application of the command to the initial value and the first element of - the list\. - - * __2__ - - Application of the command to the result of the last call and the second - element of the list\. - - * __\.\.\.__ - - * __i__ - - Application of the command to the result of the last call and the - __i__'th element of the list\. - - * __\.\.\.__ - - * __end__ - - Application of the command to the result of the last call and the last - element of the list\. The result of this call is returned as the result - of the subcommand\. - - tclsh> # summing the elements in a list. - tclsh> proc + {a b} {expr {$a + $b}} - tclsh> ::struct::list fold {1 2 3 4 5} 0 + - 15 - - - __::struct::list__ __shift__ *listvar* - - The subcommand takes the list contained in the variable named by *listvar* - and shifts it down one element\. After the call *listvar* will contain a - list containing the second to last elements of the input list\. The first - element of the ist is returned as the result of the command\. Shifting the - empty list does nothing\. - - - __::struct::list__ __iota__ *n* - - The subcommand returns a list containing the integer numbers in the range - __\[0,n\)__\. The element at index __i__ of the list contain the number - __i__\. - - For "*n* == __0__" an empty list will be returned\. - - - __::struct::list__ __equal__ *a* *b* - - The subcommand compares the two lists *a* and *b* for equality\. In other - words, they have to be of the same length and have to contain the same - elements in the same order\. If an element is a list the same definition of - equality applies recursively\. - - A boolean value will be returned as the result of the command\. This value - will be __true__ if the two lists are equal, and __false__ else\. - - - __::struct::list__ __repeat__ *size* *element1* ?*element2* *element3*\.\.\.? - - The subcommand creates a list of length "*size* \* *number of elements*" - by repeating *size* times the sequence of elements *element1* - *element2* *\.\.\.*\. *size* must be a positive integer, - *element*__n__ can be any Tcl value\. Note that __repeat 1 arg - \.\.\.__ is identical to __list arg \.\.\.__, though the *arg* is required - with __repeat__\. - - *Examples:* - - tclsh> ::struct::list repeat 3 a - a a a - tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0] - {0 0 0} {0 0 0} {0 0 0} - tclsh> ::struct::list repeat 3 a b c - a b c a b c a b c - tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c - {a a} b c {a a} b c {a a} b c - - - __::struct::list__ __repeatn__ *value* *size*\.\.\. - - The subcommand creates a \(nested\) list containing the *value* in all - positions\. The exact size and degree of nesting is determined by the - *size* arguments, all of which have to be integer numbers greater than or - equal to zero\. - - A single argument *size* which is a list of more than one element will be - treated as if more than argument *size* was specified\. - - If only one argument *size* is present the returned list will not be - nested, of length *size* and contain *value* in all positions\. If more - than one *size* argument is present the returned list will be nested, and - of the length specified by the last *size* argument given to it\. The - elements of that list are defined as the result of __Repeat__ for the - same arguments, but with the last *size* value removed\. - - An empty list will be returned if no *size* arguments are present\. - - tclsh> ::struct::list repeatn 0 3 4 - {0 0 0} {0 0 0} {0 0 0} {0 0 0} - tclsh> ::struct::list repeatn 0 {3 4} - {0 0 0} {0 0 0} {0 0 0} {0 0 0} - tclsh> ::struct::list repeatn 0 {3 4 5} - {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} - - - __::struct::list__ __dbJoin__ ?__\-inner__|__\-left__|__\-right__|__\-full__? ?__\-keys__ *varname*? \{*keycol* *table*\}\.\.\. - - The method performs a table join according to relational algebra\. The - execution of any of the possible outer join operation is triggered by the - presence of either option __\-left__, __\-right__, or __\-full__\. - If none of these options is present a regular inner join will be performed\. - This can also be triggered by specifying __\-inner__\. The various - possible join operations are explained in detail in section [TABLE - JOIN](#section4)\. - - If the __\-keys__ is present its argument is the name of a variable to - store the full list of found keys into\. Depending on the exact nature of the - input table and the join mode the output table may not contain all the keys - by default\. In such a case the caller can declare a variable for this - information and then insert it into the output table on its own, as she will - have more information about the placement than this command\. - - What is left to explain is the format of the arguments\. - - The *keycol* arguments are the indices of the columns in the tables which - contain the key values to use for the joining\. Each argument applies to the - table following immediately after it\. The columns are counted from - __0__, which references the first column\. The table associated with the - column index has to have at least *keycol*\+1 columns\. An error will be - thrown if there are less\. - - The *table* arguments represent a table or matrix of rows and columns of - values\. We use the same representation as generated and consumed by the - methods __get rect__ and __set rect__ of - __[matrix](\.\./\.\./\.\./\.\./index\.md\#matrix)__ objects\. In other words, - each argument is a list, representing the whole matrix\. Its elements are - lists too, each representing a single rows of the matrix\. The elements of - the row\-lists are the column values\. - - The table resulting from the join operation is returned as the result of the - command\. We use the same representation as described above for the input - *table*s\. - - - __::struct::list__ __dbJoinKeyed__ ?__\-inner__|__\-left__|__\-right__|__\-full__? ?__\-keys__ *varname*? *table*\.\.\. - - The operations performed by this method are the same as described above for - __dbJoin__\. The only difference is in the specification of the keys to - use\. Instead of using column indices separate from the table here the keys - are provided within the table itself\. The row elements in each *table* are - not the lists of column values, but a two\-element list where the second - element is the regular list of column values and the first element is the - key to use\. - - - __::struct::list__ __swap__ *listvar* *i* *j* - - The subcommand exchanges the elements at the indices *i* and *j* in the - list stored in the variable named by *listvar*\. The list is modified in - place, and also returned as the result of the subcommand\. - - - __::struct::list__ __firstperm__ *list* - - This subcommand returns the lexicographically first permutation of the input - *list*\. - - - __::struct::list__ __nextperm__ *perm* - - This subcommand accepts a permutation of a set of elements \(provided by - *perm*\) and returns the next permutatation in lexicographic sequence\. - - The algorithm used here is by Donal E\. Knuth, see section - [REFERENCES](#section5) for details\. - - - __::struct::list__ __permutations__ *list* - - This subcommand returns a list containing all permutations of the input - *list* in lexicographic order\. - - - __::struct::list__ __foreachperm__ *var* *list* *body* - - This subcommand executes the script *body* once for each permutation of - the specified *list*\. The permutations are visited in lexicographic order, - and the variable *var* is set to the permutation for which *body* is - currently executed\. The result of the loop command is the empty string\. - -# LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON - -The __longestCommonSubsequence__ subcommand forms the core of a flexible -system for doing differential comparisons of files, similar to the capability -offered by the Unix command __[diff](\.\./\.\./\.\./\.\./index\.md\#diff)__\. While -this procedure is quite rapid for many tasks of file comparison, its performance -degrades severely if *sequence2* contains many equal elements \(as, for -instance, when using this procedure to compare two files, a quarter of whose -lines are blank\. This drawback is intrinsic to the algorithm used \(see the -Reference for details\)\. - -One approach to dealing with the performance problem that is sometimes effective -in practice is arbitrarily to exclude elements that appear more than a certain -number of times\. This number is provided as the *maxOccurs* parameter\. If -frequent lines are excluded in this manner, they will not appear in the common -subsequence that is computed; the result will be the longest common subsequence -of infrequent elements\. The procedure __longestCommonSubsequence2__ -implements this heuristic\. It functions as a wrapper around -__longestCommonSubsequence__; it computes the longest common subsequence of -infrequent elements, and then subdivides the subsequences that lie between the -matches to approximate the true longest common subsequence\. - -# TABLE JOIN - -This is an operation from relational algebra for relational databases\. - -The easiest way to understand the regular inner join is that it creates the -cartesian product of all the tables involved first and then keeps only all those -rows in the resulting table for which the values in the specified key columns -are equal to each other\. - -Implementing this description naively, i\.e\. as described above will generate a -*huge* intermediate result\. To avoid this the cartesian product and the -filtering of row are done at the same time\. What is required is a fast way to -determine if a key is present in a table\. In a true database this is done -through indices\. Here we use arrays internally\. - -An *outer* join is an extension of the inner join for two tables\. There are -three variants of outerjoins, called *left*, *right*, and *full* outer -joins\. Their result always contains all rows from an inner join and then some -additional rows\. - - 1. For the left outer join the additional rows are all rows from the left - table for which there is no key in the right table\. They are joined to an - empty row of the right table to fit them into the result\. - - 1. For the right outer join the additional rows are all rows from the right - table for which there is no key in the left table\. They are joined to an - empty row of the left table to fit them into the result\. - - 1. The full outer join combines both left and right outer join\. In other - words, the additional rows are as defined for left outer join, and right - outer join, combined\. - -We extend all the joins from two to __n__ tables \(__n__ > 2\) by -executing - - (...((table1 join table2) join table3) ...) join tableN - -Examples for all the joins: - - Inner Join - - {0 foo} {0 bagel} {0 foo 0 bagel} - {1 snarf} inner join {1 snatz} = {1 snarf 1 snatz} - {2 blue} {3 driver} - - Left Outer Join - - {0 foo} {0 bagel} {0 foo 0 bagel} - {1 snarf} left outer join {1 snatz} = {1 snarf 1 snatz} - {2 blue} {3 driver} {2 blue {} {}} - - Right Outer Join - - {0 foo} {0 bagel} {0 foo 0 bagel} - {1 snarf} right outer join {1 snatz} = {1 snarf 1 snatz} - {2 blue} {3 driver} {{} {} 3 driver} - - Full Outer Join - - {0 foo} {0 bagel} {0 foo 0 bagel} - {1 snarf} full outer join {1 snatz} = {1 snarf 1 snatz} - {2 blue} {3 driver} {2 blue {} {}} - {{} {} 3 driver} - -# REFERENCES - - 1. J\. W\. Hunt and M\. D\. McIlroy, "An algorithm for differential file - comparison," Comp\. Sci\. Tech\. Rep\. \#41, Bell Telephone Laboratories \(1976\)\. - Available on the Web at the second author's personal site: - [http://www\.cs\.dartmouth\.edu/~doug/](http://www\.cs\.dartmouth\.edu/~doug/) - - 1. Donald E\. Knuth, "Fascicle 2b of 'The Art of Computer Programming' volume - 4"\. Available on the Web at the author's personal site: - [http://www\-cs\-faculty\.stanford\.edu/~knuth/fasc2b\.ps\.gz](http://www\-cs\-faculty\.stanford\.edu/~knuth/fasc2b\.ps\.gz)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: list* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Fisher\-Yates](\.\./\.\./\.\./\.\./index\.md\#fisher\_yates), -[assign](\.\./\.\./\.\./\.\./index\.md\#assign), -[common](\.\./\.\./\.\./\.\./index\.md\#common), -[comparison](\.\./\.\./\.\./\.\./index\.md\#comparison), -[diff](\.\./\.\./\.\./\.\./index\.md\#diff), -[differential](\.\./\.\./\.\./\.\./index\.md\#differential), -[equal](\.\./\.\./\.\./\.\./index\.md\#equal), -[equality](\.\./\.\./\.\./\.\./index\.md\#equality), -[filter](\.\./\.\./\.\./\.\./index\.md\#filter), [first -permutation](\.\./\.\./\.\./\.\./index\.md\#first\_permutation), -[flatten](\.\./\.\./\.\./\.\./index\.md\#flatten), -[folding](\.\./\.\./\.\./\.\./index\.md\#folding), [full outer -join](\.\./\.\./\.\./\.\./index\.md\#full\_outer\_join), [generate -permutations](\.\./\.\./\.\./\.\./index\.md\#generate\_permutations), [inner -join](\.\./\.\./\.\./\.\./index\.md\#inner\_join), -[join](\.\./\.\./\.\./\.\./index\.md\#join), [left outer -join](\.\./\.\./\.\./\.\./index\.md\#left\_outer\_join), -[list](\.\./\.\./\.\./\.\./index\.md\#list), [longest common -subsequence](\.\./\.\./\.\./\.\./index\.md\#longest\_common\_subsequence), -[map](\.\./\.\./\.\./\.\./index\.md\#map), [next -permutation](\.\./\.\./\.\./\.\./index\.md\#next\_permutation), [outer -join](\.\./\.\./\.\./\.\./index\.md\#outer\_join), -[permutation](\.\./\.\./\.\./\.\./index\.md\#permutation), -[reduce](\.\./\.\./\.\./\.\./index\.md\#reduce), -[repeating](\.\./\.\./\.\./\.\./index\.md\#repeating), -[repetition](\.\./\.\./\.\./\.\./index\.md\#repetition), -[reshuffle](\.\./\.\./\.\./\.\./index\.md\#reshuffle), -[reverse](\.\./\.\./\.\./\.\./index\.md\#reverse), [right outer -join](\.\./\.\./\.\./\.\./index\.md\#right\_outer\_join), -[shuffle](\.\./\.\./\.\./\.\./index\.md\#shuffle), -[subsequence](\.\./\.\./\.\./\.\./index\.md\#subsequence), -[swapping](\.\./\.\./\.\./\.\./index\.md\#swapping) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2003\-2005 by Kevin B\. Kenny\. All rights reserved -Copyright © 2003\-2012 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/struct_map.md Index: embedded/md/tcllib/files/modules/struct/struct_map.md ================================================================== --- embedded/md/tcllib/files/modules/struct/struct_map.md +++ embedded/md/tcllib/files/modules/struct/struct_map.md @@ -1,98 +0,0 @@ - -[//000000001]: # (struct::map \- ) -[//000000002]: # (Generated from file 'struct\_map\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (struct::map\(n\) 1 tcllib "") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::map \- Manage key/value maps - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - -# SYNOPSIS - -package require struct::map ?1? - -[__::struct::map__ *mapName*](#1) -[__mapName__ __method__ ?*arg arg \.\.\.*?](#2) -[*mapName* __get__](#3) -[*mapName* __names__](#4) -[*mapName* __set__ *name* ?*value*?](#5) -[*mapName* __unset__ ?*pattern*\.\.\.?](#6) - -# DESCRIPTION - -Provides a snit class whose instances manage a key/value map\. In other words, an -object wrapper around Tcl arrays\. - -# API - -The main command provides construction of maps: - - - __::struct::map__ *mapName* - - Creates a new, empty map with an associated global Tcl command whose name is - *mapName*\. It may be used to invoke various operations on the map\. It has - the following general form: - - * __mapName__ __method__ ?*arg arg \.\.\.*? - - __method__ and *arg*uments determine the exact behavior of the - command\. - - If *mapName* is specified as __%AUTO%__ a unique name will be - generated by the package itself\. The result of the command is the - fully\-qualified name of the instance command\. - -The following commands are possible for map objects: - - - *mapName* __get__ - - Returns the entire map as a Tcl dictionary\. - - - *mapName* __names__ - - Returns the list of all keys known to the map, in arbitrary order\. - - - *mapName* __set__ *name* ?*value*? - - Sets key *name* to the specified *value*, if the value specified\. - Returns the value for the key\. Throws an error if the key is not known\. - - - *mapName* __unset__ ?*pattern*\.\.\.? - - Removes all keys matching at least one of the glob *pattern*s from the - map\. If no pattern is specified all keys are removed\. In other words, the - default pattern is __\*__\. The result of the command is the empty string\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: list* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. DELETED embedded/md/tcllib/files/modules/struct/struct_set.md Index: embedded/md/tcllib/files/modules/struct/struct_set.md ================================================================== --- embedded/md/tcllib/files/modules/struct/struct_set.md +++ embedded/md/tcllib/files/modules/struct/struct_set.md @@ -1,189 +0,0 @@ - -[//000000001]: # (struct::set \- Tcl Data Structures) -[//000000002]: # (Generated from file 'struct\_set\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008 Andreas Kupries ) -[//000000004]: # (struct::set\(n\) 2\.2\.3 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::set \- Procedures for manipulating sets - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [REFERENCES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.0 -package require struct::set ?2\.2\.3? - -[__::struct::set__ __empty__ *set*](#1) -[__::struct::set__ __size__ *set*](#2) -[__::struct::set__ __contains__ *set* *item*](#3) -[__::struct::set__ __union__ ?*set1*\.\.\.?](#4) -[__::struct::set__ __intersect__ ?*set1*\.\.\.?](#5) -[__::struct::set__ __difference__ *set1* *set2*](#6) -[__::struct::set__ __symdiff__ *set1* *set2*](#7) -[__::struct::set__ __intersect3__ *set1* *set2*](#8) -[__::struct::set__ __equal__ *set1* *set2*](#9) -[__::struct::set__ __include__ *svar* *item*](#10) -[__::struct::set__ __exclude__ *svar* *item*](#11) -[__::struct::set__ __add__ *svar* *set*](#12) -[__::struct::set__ __subtract__ *svar* *set*](#13) -[__::struct::set__ __subsetof__ *A* *B*](#14) - -# DESCRIPTION - -The __::struct::set__ namespace contains several useful commands for -processing finite sets\. - -It exports only a single command, __struct::set__\. All functionality -provided here can be reached through a subcommand of this command\. - -*Note:* As of version 2\.2 of this package a critcl based C implementation is -available\. This implementation however requires Tcl 8\.4 to run\. - -# COMMANDS - - - __::struct::set__ __empty__ *set* - - Returns a boolean value indicating if the *set* is empty \(__true__\), - or not \(__false__\)\. - - - __::struct::set__ __size__ *set* - - Returns an integer number greater than or equal to zero\. This is the number - of elements in the *set*\. In other words, its cardinality\. - - - __::struct::set__ __contains__ *set* *item* - - Returns a boolean value indicating if the *set* contains the element - *item* \(__true__\), or not \(__false__\)\. - - - __::struct::set__ __union__ ?*set1*\.\.\.? - - Computes the set containing the union of *set1*, *set2*, etc\., i\.e\. - "*set1* \+ *set2* \+ \.\.\.", and returns this set as the result of the - command\. - - - __::struct::set__ __intersect__ ?*set1*\.\.\.? - - Computes the set containing the intersection of *set1*, *set2*, etc\., - i\.e\. "*set1* \* *set2* \* \.\.\.", and returns this set as the result of the - command\. - - - __::struct::set__ __difference__ *set1* *set2* - - Computes the set containing the difference of *set1* and *set2*, i\.e\. - \("*set1* \- *set2*"\) and returns this set as the result of the command\. - - - __::struct::set__ __symdiff__ *set1* *set2* - - Computes the set containing the symmetric difference of *set1* and - *set2*, i\.e\. \("\(*set1* \- *set2*\) \+ \(*set2* \- *set1*\)"\) and returns - this set as the result of the command\. - - - __::struct::set__ __intersect3__ *set1* *set2* - - This command is a combination of the methods __intersect__ and - __difference__\. It returns a three\-element list containing - "*set1*\**set2*", "*set1*\-*set2*", and "*set2*\-*set1*", in this - order\. In other words, the intersection of the two parameter sets, and their - differences\. - - - __::struct::set__ __equal__ *set1* *set2* - - Returns a boolean value indicating if the two sets are equal \(__true__\) - or not \(__false__\)\. - - - __::struct::set__ __include__ *svar* *item* - - The element *item* is added to the set specified by the variable name in - *svar*\. The return value of the command is empty\. This is the equivalent - of __lappend__ for sets\. If the variable named by *svar* does not - exist it will be created\. - - - __::struct::set__ __exclude__ *svar* *item* - - The element *item* is removed from the set specified by the variable name - in *svar*\. The return value of the command is empty\. This is a - near\-equivalent of __lreplace__ for sets\. - - - __::struct::set__ __add__ *svar* *set* - - All the element of *set* are added to the set specified by the variable - name in *svar*\. The return value of the command is empty\. This is like the - method __include__, but for the addition of a whole set\. If the variable - named by *svar* does not exist it will be created\. - - - __::struct::set__ __subtract__ *svar* *set* - - All the element of *set* are removed from the set specified by the - variable name in *svar*\. The return value of the command is empty\. This is - like the method __exclude__, but for the removal of a whole set\. - - - __::struct::set__ __subsetof__ *A* *B* - - Returns a boolean value indicating if the set *A* is a true subset of or - equal to the set *B* \(__true__\), or not \(__false__\)\. - -# REFERENCES - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: set* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[cardinality](\.\./\.\./\.\./\.\./index\.md\#cardinality), -[difference](\.\./\.\./\.\./\.\./index\.md\#difference), -[emptiness](\.\./\.\./\.\./\.\./index\.md\#emptiness), -[exclusion](\.\./\.\./\.\./\.\./index\.md\#exclusion), -[inclusion](\.\./\.\./\.\./\.\./index\.md\#inclusion), -[intersection](\.\./\.\./\.\./\.\./index\.md\#intersection), -[membership](\.\./\.\./\.\./\.\./index\.md\#membership), -[set](\.\./\.\./\.\./\.\./index\.md\#set), [symmetric -difference](\.\./\.\./\.\./\.\./index\.md\#symmetric\_difference), -[union](\.\./\.\./\.\./\.\./index\.md\#union) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2004\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/struct_tree.md Index: embedded/md/tcllib/files/modules/struct/struct_tree.md ================================================================== --- embedded/md/tcllib/files/modules/struct/struct_tree.md +++ embedded/md/tcllib/files/modules/struct/struct_tree.md @@ -1,713 +0,0 @@ - -[//000000001]: # (struct::tree \- Tcl Data Structures) -[//000000002]: # (Generated from file 'struct\_tree\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002\-2004,2012 Andreas Kupries ) -[//000000004]: # (struct::tree\(n\) 2\.1\.1 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::tree \- Create and manipulate tree objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Tree CLASS API](#subsection1) - - - [Tree OBJECT API](#subsection2) - - - [Changes for 2\.0](#subsection3) - - - [EXAMPLES](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::tree ?2\.1\.1? -package require struct::list ?1\.5? - -[__::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*?](#1) -[__treeName__ __option__ ?*arg arg \.\.\.*?](#2) -[__::struct::tree::prune__](#3) -[*treeName* __=__ *sourcetree*](#4) -[*treeName* __\-\->__ *desttree*](#5) -[*treeName* __ancestors__ *node*](#6) -[*treeName* __append__ *node* *key* *value*](#7) -[*treeName* __attr__ *key*](#8) -[*treeName* __attr__ *key* __\-nodes__ *list*](#9) -[*treeName* __attr__ *key* __\-glob__ *globpattern*](#10) -[*treeName* __attr__ *key* __\-regexp__ *repattern*](#11) -[*treeName* __children__ ?__\-all__? *node* ?__filter__ *cmdprefix*?](#12) -[*treeName* __cut__ *node*](#13) -[*treeName* __delete__ *node* ?*node* \.\.\.?](#14) -[*treeName* __depth__ *node*](#15) -[*treeName* __descendants__ *node* ?__filter__ *cmdprefix*?](#16) -[*treeName* __deserialize__ *serialization*](#17) -[*treeName* __destroy__](#18) -[*treeName* __exists__ *node*](#19) -[*treeName* __get__ *node* *key*](#20) -[*treeName* __getall__ *node* ?*pattern*?](#21) -[*treeName* __keys__ *node* ?*pattern*?](#22) -[*treeName* __keyexists__ *node* *key*](#23) -[*treeName* __index__ *node*](#24) -[*treeName* __insert__ *parent* *index* ?*child* ?*child* \.\.\.??](#25) -[*treeName* __isleaf__ *node*](#26) -[*treeName* __lappend__ *node* *key* *value*](#27) -[*treeName* __leaves__](#28) -[*treeName* __move__ *parent* *index* *node* ?*node* \.\.\.?](#29) -[*treeName* __next__ *node*](#30) -[*treeName* __numchildren__ *node*](#31) -[*treeName* __nodes__](#32) -[*treeName* __parent__ *node*](#33) -[*treeName* __previous__ *node*](#34) -[*treeName* __rename__ *node* *newname*](#35) -[*treeName* __rootname__](#36) -[*treeName* __serialize__ ?*node*?](#37) -[*treeName* __set__ *node* *key* ?*value*?](#38) -[*treeName* __size__ ?*node*?](#39) -[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#40) -[*treeName* __swap__ *node1* *node2*](#41) -[*treeName* __unset__ *node* *key*](#42) -[*treeName* __walk__ *node* ?__\-order__ *order*? ?__\-type__ *type*? *loopvar* *script*](#43) -[*treeName* __walkproc__ *node* ?__\-order__ *order*? ?__\-type__ *type*? *cmdprefix*](#44) - -# DESCRIPTION - -A tree is a collection of named elements, called nodes, one of which is -distinguished as a root, along with a relation \("parenthood"\) that places a -hierarchical structure on the nodes\. \(Data Structures and Algorithms; Aho, -Hopcroft and Ullman; Addison\-Wesley, 1987\)\. In addition to maintaining the node -relationships, this tree implementation allows any number of keyed values to be -associated with each node\. - -The element names can be arbitrary strings\. - -A tree is thus similar to an array, but with three important differences: - - 1. Trees are accessed through an object command, whereas arrays are accessed - as variables\. \(This means trees cannot be local to a procedure\.\) - - 1. Trees have a hierarchical structure, whereas an array is just an unordered - collection\. - - 1. Each node of a tree has a separate collection of attributes and values\. - This is like an array where every value is a dictionary\. - -*Note:* The major version of the package -__[struct](\.\./\.\./\.\./\.\./index\.md\#struct)__ has been changed to version -2\.0, due to backward incompatible changes in the API of this module\. Please read -the section [Changes for 2\.0](#subsection3) for a full list of all changes, -incompatible and otherwise\. - -# API - -## Tree CLASS API - -The main commands of the package are: - - - __::struct::tree__ ?*treeName*? ?__=__|__:=__|__as__|__deserialize__ *source*? - - The command creates a new tree object with an associated global Tcl command - whose name is *treeName*\. This command may be used to invoke various - operations on the tree\. It has the following general form: - - * __treeName__ __option__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - - If *treeName* is not specified a unique name will be generated by the - package itself\. If a *source* is specified the new tree will be - initialized to it\. For the operators __=__, __:=__, and __as__ - *source* is interpreted as the name of another tree object, and the - assignment operator __=__ will be executed\. For __deserialize__ the - *source* is a serialized tree object and __deserialize__ will be - executed\. - - In other words - - ::struct::tree mytree = b - - is equivalent to - - ::struct::tree mytree - mytree = b - - and - - ::struct::tree mytree deserialize $b - - is equivalent to - - ::struct::tree mytree - mytree deserialize $b - - - __::struct::tree::prune__ - - This command is provided outside of the tree methods, as it is not a tree - method per se\. It however interacts tightly with the method __walk__\. - When used in the walk script it causes the traversal to ignore the children - of the node we are currently at\. This command cannot be used with the - traversal modes which look at children before their parent, i\.e\. - __post__ and __in__\. The only applicable orders of traversal are - __pre__ and __both__\. An error is thrown if the command and chosen - order of traversal do not fit\. - -## Tree OBJECT API - -Two general observations beforehand: - - 1. The root node of the tree can be used in most places where a node is asked - for\. The default name of the rootnode is "root", but this can be changed - with the method __rename__ \(see below\)\. Whatever the current name for - the root node of the tree is, it can be retrieved by calling the method - __rootname__\. - - 1. The method __insert__ is the only way to create new nodes, and they are - automatically added to a parent\. A tree object cannot have nodes without a - parent, save the root node\. - -And now the methods supported by tree objects created by this package: - - - *treeName* __=__ *sourcetree* - - This is the assignment operator for tree objects\. It copies the tree - contained in the tree object *sourcetree* over the tree data in - *treeName*\. The old contents of *treeName* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *treeName* __deserialize__ \[*sourcetree* __serialize__\] - - - *treeName* __\-\->__ *desttree* - - This is the reverse assignment operator for tree objects\. It copies the tree - contained in the tree object *treeName* over the tree data in the object - *desttree*\. The old contents of *desttree* are deleted by this - operation\. - - This operation is in effect equivalent to - - > *desttree* __deserialize__ \[*treeName* __serialize__\] - - - *treeName* __ancestors__ *node* - - This method extends the method __parent__ and returns a list containing - all ancestor nodes to the specified *node*\. The immediate ancestor, in - other words, parent node, is the first element in that list, its parent the - second element, and so on until the root node is reached, making it the last - element of the returned list\. - - - *treeName* __append__ *node* *key* *value* - - Appends a *value* to one of the keyed values associated with an node\. - Returns the new value given to the attribute *key*\. - - - *treeName* __attr__ *key* - - - *treeName* __attr__ *key* __\-nodes__ *list* - - - *treeName* __attr__ *key* __\-glob__ *globpattern* - - - *treeName* __attr__ *key* __\-regexp__ *repattern* - - This method retrieves the value of the attribute named *key*, for all - nodes in the tree \(matching the restriction specified via one of the - possible options\) and having the specified attribute\. - - The result is a dictionary mapping from node names to the value of attribute - *key* at that node\. Nodes not having the attribute *key*, or not passing - a specified restriction, are not listed in the result\. - - The possible restrictions are: - - * __\-nodes__ - - The value is a list of nodes\. Only the nodes mentioned in this list are - searched for the attribute\. - - * __\-glob__ - - The value is a glob pattern\. Only the nodes in the tree whose names - match this pattern are searched for the attribute\. - - * __\-regexp__ - - The value is a regular expression\. Only the nodes in the tree whose - names match this pattern are searched for the attribute\. - - - *treeName* __children__ ?__\-all__? *node* ?__filter__ *cmdprefix*? - - Return a list of the children of *node*\. If the option __\-all__ is - specified, then not only the direct children, but their children, and so on - are returned in the result\. If a filter command is specified only those - nodes are listed in the final result which pass the test\. The command in - *cmdprefix* is called with two arguments, the name of the tree object, and - the name of the node in question\. It is executed in the context of the - caller and has to return a boolean value\. Nodes for which the command - returns __false__ are removed from the result list before it is returned - to the caller\. - - Some examples: - - mytree insert root end 0 ; mytree set 0 volume 30 - mytree insert root end 1 - mytree insert root end 2 - mytree insert 0 end 3 - mytree insert 0 end 4 - mytree insert 4 end 5 ; mytree set 5 volume 50 - mytree insert 4 end 6 - - proc vol {t n} { - $t keyexists $n volume - } - proc vgt40 {t n} { - if {![$t keyexists $n volume]} {return 0} - expr {[$t get $n volume] > 40} - } - - tclsh> lsort [mytree children -all root filter vol] - 0 5 - - tclsh> lsort [mytree children -all root filter vgt40] - 5 - - tclsh> lsort [mytree children root filter vol] - 0 - - tclsh> puts ([lsort [mytree children root filter vgt40]]) - () - - - *treeName* __cut__ *node* - - Removes the node specified by *node* from the tree, but not its children\. - The children of *node* are made children of the parent of the *node*, at - the index at which *node* was located\. - - - *treeName* __delete__ *node* ?*node* \.\.\.? - - Removes the specified nodes from the tree\. All of the nodes' children will - be removed as well to prevent orphaned nodes\. - - - *treeName* __depth__ *node* - - Return the number of steps from node *node* to the root node\. - - - *treeName* __descendants__ *node* ?__filter__ *cmdprefix*? - - This method extends the method __children__ and returns a list - containing all nodes descending from *node*, and passing the filter, if - such was specified\. - - This is actually the same as "*treeName* __children__ __\-all__"\. - __descendants__ should be prefered, and "children \-all" will be - deprecated sometime in the future\. - - - *treeName* __deserialize__ *serialization* - - This is the complement to __serialize__\. It replaces tree data in - *treeName* with the tree described by the *serialization* value\. The old - contents of *treeName* are deleted by this operation\. - - - *treeName* __destroy__ - - Destroy the tree, including its storage space and associated command\. - - - *treeName* __exists__ *node* - - Returns true if the specified node exists in the tree\. - - - *treeName* __get__ *node* *key* - - Returns the value associated with the key *key* for the node *node*\. - - - *treeName* __getall__ *node* ?*pattern*? - - Returns a dictionary \(suitable for use with \[__array set__\]\) containing - the attribute data for the *node*\. If the glob *pattern* is specified - only the attributes whose names match the pattern will be part of the - dictionary\. - - - *treeName* __keys__ *node* ?*pattern*? - - Returns a list of keys for the *node*\. If the *pattern* is specified - only the attributes whose names match the pattern will be part of the - returned list\. The pattern is a __glob__ pattern\. - - - *treeName* __keyexists__ *node* *key* - - Return true if the specified *key* exists for the *node*\. - - - *treeName* __index__ *node* - - Returns the index of *node* in its parent's list of children\. For example, - if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that - order, the index of *nodeBar* is 1\. - - - *treeName* __insert__ *parent* *index* ?*child* ?*child* \.\.\.?? - - Insert one or more nodes into the tree as children of the node *parent*\. - The nodes will be added in the order they are given\. If *parent* is - __root__, it refers to the root of the tree\. The new nodes will be added - to the *parent* node's child list at the index given by *index*\. The - *index* can be __end__ in which case the new nodes will be added after - the current last child\. Indices of the form "end\-__n__" are accepted as - well\. - - If any of the specified children already exist in *treeName*, those nodes - will be moved from their original location to the new location indicated by - this command\. - - If no *child* is specified, a single node will be added, and a name will - be generated for the new node\. The generated name is of the form - *node*__x__, where __x__ is a number\. If names are specified they - must neither contain whitespace nor colons \(":"\)\. - - The return result from this command is a list of nodes added\. - - - *treeName* __isleaf__ *node* - - Returns true if *node* is a leaf of the tree \(if *node* has no - children\), false otherwise\. - - - *treeName* __lappend__ *node* *key* *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *node*\. Returns the new value given to the attribute *key*\. - - - *treeName* __leaves__ - - Return a list containing all leaf nodes known to the tree\. - - - *treeName* __move__ *parent* *index* *node* ?*node* \.\.\.? - - Make the specified nodes children of *parent*, inserting them into the - parent's child list at the index given by *index*\. Note that the command - will take all nodes out of the tree before inserting them under the new - parent, and that it determines the position to place them into after the - removal, before the re\-insertion\. This behaviour is important when it comes - to moving one or more nodes to a different index without changing their - parent node\. - - - *treeName* __next__ *node* - - Return the right sibling of *node*, or the empty string if *node* was - the last child of its parent\. - - - *treeName* __numchildren__ *node* - - Return the number of immediate children of *node*\. - - - *treeName* __nodes__ - - Return a list containing all nodes known to the tree\. - - - *treeName* __parent__ *node* - - Return the parent of *node*\. - - - *treeName* __previous__ *node* - - Return the left sibling of *node*, or the empty string if *node* was the - first child of its parent\. - - - *treeName* __rename__ *node* *newname* - - Renames the node *node* to *newname*\. An error is thrown if either the - node does not exist, or a node with name *newname* does exist\. The result - of the command is the new name of the node\. - - - *treeName* __rootname__ - - Returns the name of the root node of the tree\. - - - *treeName* __serialize__ ?*node*? - - This method serializes the sub\-tree starting at *node*\. In other words it - returns a tcl *value* completely describing the tree starting at *node*\. - This allows, for example, the transfer of tree objects \(or parts thereof\) - over arbitrary channels, persistence, etc\. This method is also the basis for - both the copy constructor and the assignment operator\. - - The result of this method has to be semantically identical over all - implementations of the tree interface\. This is what will enable us to copy - tree data between different implementations of the same interface\. - - The result is a list containing containing a multiple of three elements\. It - is like a serialized array except that there are two values following each - key\. They are the names of the nodes in the serialized tree\. The two values - are a reference to the parent node and the attribute data, in this order\. - - The reference to the parent node is the empty string for the root node of - the tree\. For all other nodes it is the index of the parent node in the - list\. This means that they are integers, greater than or equal to zero, less - than the length of the list, and multiples of three\. The order of the nodes - in the list is important insofar as it is used to reconstruct the lists of - children for each node\. The children of a node have to be listed in the - serialization in the same order as they are listed in their parent in the - tree\. - - The attribute data of a node is a dictionary, i\.e\. a list of even length - containing a serialized array\. For a node without attribute data the - dictionary is the empty list\. - - *Note:* While the current implementation returns the root node as the - first element of the list, followed by its children and their children in a - depth\-first traversal this is not necessarily true for other - implementations\. The only information a reader of the serialized data can - rely on for the structure of the tree is that the root node is signaled by - the empty string for the parent reference, that all other nodes refer to - their parent through the index in the list, and that children occur in the - same order as in their parent\. - - A possible serialization for the tree structure - - +- d - +- a -+ - root -+- b +- e - +- c - is - - {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}} - - The above assumes that none of the nodes have attributes. - - - *treeName* __set__ *node* *key* ?*value*? - - Set or get one of the keyed values associated with a node\. A node may have - any number of keyed values associated with it\. If *value* is not - specified, this command returns the current value assigned to the key; if - *value* is specified, this command assigns that value to the key, and - returns it\. - - - *treeName* __size__ ?*node*? - - Return a count of the number of descendants of the node *node*; if no node - is specified, __root__ is assumed\. - - - *treeName* __splice__ *parent* *from* ?*to*? ?*child*? - - Insert a node named *child* into the tree as a child of the node - *parent*\. If *parent* is __root__, it refers to the root of the - tree\. The new node will be added to the parent node's child list at the - index given by *from*\. The children of *parent* which are in the range - of the indices *from* and *to* are made children of *child*\. If the - value of *to* is not specified it defaults to __end__\. If no name is - given for *child*, a name will be generated for the new node\. The - generated name is of the form *node*__x__, where __x__ is a - number\. The return result from this command is the name of the new node\. - - The arguments *from* and *to* are regular list indices, i\.e\. the form - "end\-__n__" is accepted as well\. - - - *treeName* __swap__ *node1* *node2* - - Swap the position of *node1* and *node2* in the tree\. - - - *treeName* __unset__ *node* *key* - - Removes a keyed value from the node *node*\. The method will do nothing if - the *key* does not exist\. - - - *treeName* __walk__ *node* ?__\-order__ *order*? ?__\-type__ *type*? *loopvar* *script* - - Perform a breadth\-first or depth\-first walk of the tree starting at the node - *node*\. The type of walk, breadth\-first or depth\-first, is determined by - the value of *type*; __bfs__ indicates breadth\-first, __dfs__ - indicates depth\-first\. Depth\-first is the default\. The order of the walk, - pre\-, post\-, both\- or in\-order is determined by the value of *order*; - __pre__ indicates pre\-order, __post__ indicates post\-order, - __both__ indicates both\-order and __in__ indicates in\-order\. - Pre\-order is the default\. - - Pre\-order walking means that a parent node is visited before any of its - children\. For example, a breadth\-first search starting from the root will - visit the root, followed by all of the root's children, followed by all of - the root's grandchildren\. Post\-order walking means that a parent node is - visited after any of its children\. Both\-order walking means that a parent - node is visited before *and* after any of its children\. In\-order walking - means that a parent node is visited after its first child and before the - second\. This is a generalization of in\-order walking for binary trees and - will do the right thing if a binary tree is walked\. The combination of a - breadth\-first walk with in\-order is illegal\. - - As the walk progresses, the *script* will be evaluated at each node\. The - evaluation takes place in the context of the caller of the method\. Regarding - loop variables, these are listed in *loopvar*\. If one only one variable is - specified it will be set to the id of the node\. When two variables are - specified, i\.e\. *loopvar* is a true list, then the first variable will be - set to the action performed at the node, and the other to the id of the node - itself\. All loop variables are created in the context of the caller\. - - There are three possible actions: __enter__, __leave__, or - __visit__\. __enter__ actions occur during pre\-order walks; - __leave__ actions occur during post\-order walks; __visit__ actions - occur during in\-order walks\. In a both\-order walk, the command will be - evaluated twice for each node; the action is __enter__ for the first - evaluation, and __leave__ for the second\. - - *Note*: The __enter__ action for a node is always performed before the - walker will look at the children of that node\. This means that changes made - by the *script* to the children of the node will immediately influence the - walker and the steps it will take\. - - Any other manipulation, for example of nodes higher in the tree \(i\.e already - visited\), or upon leaving will have undefined results\. They may succeed, - error out, silently compute the wrong result, or anything in between\. - - At last a small table showing the relationship between the various options - and the possible actions\. - - order type actions notes - ----- ---- ----- ----- - pre dfs enter parent before children - post dfs leave parent after children - in dfs visit parent between first and second child. - both dfs enter, leave parent before and after children - ----- ---- ----- ----- - pre bfs enter parent before children - post bfs leave parent after children - in bfs -- illegal -- - both bfs enter, leave parent before and after children - ----- ---- ----- ----- - - Note the command __::struct::tree::prune__\. This command can be used in - the walk script to force the command to ignore the children of the node we - are currently at\. It will throw an error if the order of traversal is either - __post__ or __in__ as these modes visit the children before their - parent, making pruning non\-sensical\. - - - *treeName* __walkproc__ *node* ?__\-order__ *order*? ?__\-type__ *type*? *cmdprefix* - - This method is like method __walk__ in all essentials, except the - interface to the user code\. This method invokes a command prefix with three - additional arguments \(tree, node, and action\), instead of evaluating a - script and passing the node via a loop variable\. - -## Changes for 2\.0 - -The following noteworthy changes have occurred: - - 1. The API for accessing attributes and their values has been simplified\. - - All functionality regarding the default attribute "data" has been removed\. - This default attribute does not exist anymore\. All accesses to attributes - have to specify the name of the attribute in question\. This backward - *incompatible* change allowed us to simplify the signature of all methods - handling attributes\. - - Especially the flag __\-key__ is not required anymore, even more, its - use is now forbidden\. Please read the documentation for the methods - __set__, __get__, __getall__, __unset__, __append__, - __lappend__, __keyexists__ and __keys__ for a description of - the new API's\. - - 1. The methods __keys__ and __getall__ now take an optional pattern - argument and will return only attribute data for keys matching this - pattern\. - - 1. Nodes can now be renamed\. See the documentation for the method - __rename__\. - - 1. The structure has been extended with API's for the serialization and - deserialization of tree objects, and a number of operations based on them - \(tree assignment, copy construction\)\. - - Please read the documentation for the methods __serialize__, - __deserialize__, __=__, and __\-\->__, and the documentation on - the construction of tree objects\. - - Beyond the copying of whole tree objects these new API's also enable the - transfer of tree objects over arbitrary channels and for easy persistence\. - - 1. The walker API has been streamlined and made more similar to the command - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__\. In detail: - - - The superfluous option __\-command__ has been removed\. - - - Ditto for the place holders\. Instead of the placeholders two loop - variables have to be specified to contain node and action information\. - - - The old command argument has been documented as a script now, which it - was in the past too\. - - - The fact that __enter__ actions are called before the walker looks - at the children of a node has been documented now\. In other words it is - now officially allowed to manipulate the list of children for a node - under *these* circumstances\. It has been made clear that changes - under any other circumstances will have undefined results, from - silently computing the wrong result to erroring out\. - - 1. A new method, __attr__, was added allowing the query and retrieval of - attribute data without regard to the node relationship\. - - 1. The method __children__ has been extended with the ability to select - from the children of the node based on an arbitrary filtering criterium\. - Another extension is the ability to look not only at the immediate children - of the node, but the whole tree below it\. - -# EXAMPLES - -The following example demonstrates the creation of new nodes: - - mytree insert root end 0 ; # Create node 0, as child of the root - mytree insert root end 1 2 ; # Ditto nodes 1 & 2 - mytree insert 0 end 3 ; # Now create node 3 as child of node 0 - mytree insert 0 end ; # Create another child of 0, with a - # generated name. The name is returned - # as the result of the command. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: tree* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[breadth\-first](\.\./\.\./\.\./\.\./index\.md\#breadth\_first), -[depth\-first](\.\./\.\./\.\./\.\./index\.md\#depth\_first), -[in\-order](\.\./\.\./\.\./\.\./index\.md\#in\_order), -[node](\.\./\.\./\.\./\.\./index\.md\#node), -[post\-order](\.\./\.\./\.\./\.\./index\.md\#post\_order), -[pre\-order](\.\./\.\./\.\./\.\./index\.md\#pre\_order), -[serialization](\.\./\.\./\.\./\.\./index\.md\#serialization), -[tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002\-2004,2012 Andreas Kupries DELETED embedded/md/tcllib/files/modules/struct/struct_tree1.md Index: embedded/md/tcllib/files/modules/struct/struct_tree1.md ================================================================== --- embedded/md/tcllib/files/modules/struct/struct_tree1.md +++ embedded/md/tcllib/files/modules/struct/struct_tree1.md @@ -1,322 +0,0 @@ - -[//000000001]: # (struct::tree\_v1 \- Tcl Data Structures) -[//000000002]: # (Generated from file 'struct\_tree1\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2002 Andreas Kupries ) -[//000000004]: # (struct::tree\_v1\(n\) 1\.2\.2 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -struct::tree\_v1 \- Create and manipulate tree objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require struct::tree ?1\.2\.2? - -[__treeName__ __option__ ?*arg arg \.\.\.*?](#1) -[*treeName* __append__ *node* ?\-key *key*? *value*](#2) -[*treeName* __children__ *node*](#3) -[*treeName* __cut__ *node*](#4) -[*treeName* __delete__ *node* ?*node* \.\.\.?](#5) -[*treeName* __depth__ *node*](#6) -[*treeName* __destroy__](#7) -[*treeName* __exists__ *node*](#8) -[*treeName* __get__ *node* ?__\-key__ *key*?](#9) -[*treeName* __getall__ *node*](#10) -[*treeName* __keys__ *node*](#11) -[*treeName* __keyexists__ *node* ?\-key *key*?](#12) -[*treeName* __index__ *node*](#13) -[*treeName* __insert__ *parent* *index* ?*child* ?*child* \.\.\.??](#14) -[*treeName* __isleaf__ *node*](#15) -[*treeName* __lappend__ *node* ?\-key *key*? *value*](#16) -[*treeName* __move__ *parent* *index* *node* ?*node* \.\.\.?](#17) -[*treeName* __next__ *node*](#18) -[*treeName* __numchildren__ *node*](#19) -[*treeName* __parent__ *node*](#20) -[*treeName* __previous__ *node*](#21) -[*treeName* __set__ *node* ?__\-key__ *key*? ?*value*?](#22) -[*treeName* __size__ ?*node*?](#23) -[*treeName* __splice__ *parent* *from* ?*to*? ?*child*?](#24) -[*treeName* __swap__ *node1* *node2*](#25) -[*treeName* __unset__ *node* ?__\-key__ *key*?](#26) -[*treeName* __walk__ *node* ?__\-order__ *order*? ?__\-type__ *type*? __\-command__ *cmd*](#27) - -# DESCRIPTION - -The __::struct::tree__ command creates a new tree object with an associated -global Tcl command whose name is *treeName*\. This command may be used to -invoke various operations on the tree\. It has the following general form: - - - __treeName__ __option__ ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -A tree is a collection of named elements, called nodes, one of which is -distinguished as a root, along with a relation \("parenthood"\) that places a -hierarchical structure on the nodes\. \(Data Structures and Algorithms; Aho, -Hopcroft and Ullman; Addison\-Wesley, 1987\)\. In addition to maintaining the node -relationships, this tree implementation allows any number of keyed values to be -associated with each node\. - -The element names can be arbitrary strings\. - -A tree is thus similar to an array, but with three important differences: - - 1. Trees are accessed through an object command, whereas arrays are accessed - as variables\. \(This means trees cannot be local to a procedure\.\) - - 1. Trees have a hierarchical structure, whereas an array is just an unordered - collection\. - - 1. Each node of a tree has a separate collection of attributes and values\. - This is like an array where every value is a dictionary\. - -The following commands are possible for tree objects: - - - *treeName* __append__ *node* ?\-key *key*? *value* - - Appends a *value* to one of the keyed values associated with an node\. If - no *key* is specified, the key __data__ is assumed\. - - - *treeName* __children__ *node* - - Return a list of the children of *node*\. - - - *treeName* __cut__ *node* - - Removes the node specified by *node* from the tree, but not its children\. - The children of *node* are made children of the parent of the *node*, at - the index at which *node* was located\. - - - *treeName* __delete__ *node* ?*node* \.\.\.? - - Removes the specified nodes from the tree\. All of the nodes' children will - be removed as well to prevent orphaned nodes\. - - - *treeName* __depth__ *node* - - Return the number of steps from node *node* to the root node\. - - - *treeName* __destroy__ - - Destroy the tree, including its storage space and associated command\. - - - *treeName* __exists__ *node* - - Returns true if the specified node exists in the tree\. - - - *treeName* __get__ *node* ?__\-key__ *key*? - - Return the value associated with the key *key* for the node *node*\. If - no key is specified, the key __data__ is assumed\. - - - *treeName* __getall__ *node* - - Returns a serialized list of key/value pairs \(suitable for use with - \[__array set__\]\) for the *node*\. - - - *treeName* __keys__ *node* - - Returns a list of keys for the *node*\. - - - *treeName* __keyexists__ *node* ?\-key *key*? - - Return true if the specified *key* exists for the *node*\. If no *key* - is specified, the key __data__ is assumed\. - - - *treeName* __index__ *node* - - Returns the index of *node* in its parent's list of children\. For example, - if a node has *nodeFoo*, *nodeBar*, and *nodeBaz* as children, in that - order, the index of *nodeBar* is 1\. - - - *treeName* __insert__ *parent* *index* ?*child* ?*child* \.\.\.?? - - Insert one or more nodes into the tree as children of the node *parent*\. - The nodes will be added in the order they are given\. If *parent* is - __root__, it refers to the root of the tree\. The new nodes will be added - to the *parent* node's child list at the index given by *index*\. The - *index* can be __end__ in which case the new nodes will be added after - the current last child\. - - If any of the specified children already exist in *treeName*, those nodes - will be moved from their original location to the new location indicated by - this command\. - - If no *child* is specified, a single node will be added, and a name will - be generated for the new node\. The generated name is of the form - *node*__x__, where __x__ is a number\. If names are specified they - must neither contain whitespace nor colons \(":"\)\. - - The return result from this command is a list of nodes added\. - - - *treeName* __isleaf__ *node* - - Returns true if *node* is a leaf of the tree \(if *node* has no - children\), false otherwise\. - - - *treeName* __lappend__ *node* ?\-key *key*? *value* - - Appends a *value* \(as a list\) to one of the keyed values associated with - an *node*\. If no *key* is specified, the key __data__ is assumed\. - - - *treeName* __move__ *parent* *index* *node* ?*node* \.\.\.? - - Make the specified nodes children of *parent*, inserting them into the - parent's child list at the index given by *index*\. Note that the command - will take all nodes out of the tree before inserting them under the new - parent, and that it determines the position to place them into after the - removal, before the re\-insertion\. This behaviour is important when it comes - to moving one or more nodes to a different index without changing their - parent node\. - - - *treeName* __next__ *node* - - Return the right sibling of *node*, or the empty string if *node* was - the last child of its parent\. - - - *treeName* __numchildren__ *node* - - Return the number of immediate children of *node*\. - - - *treeName* __parent__ *node* - - Return the parent of *node*\. - - - *treeName* __previous__ *node* - - Return the left sibling of *node*, or the empty string if *node* was the - first child of its parent\. - - - *treeName* __set__ *node* ?__\-key__ *key*? ?*value*? - - Set or get one of the keyed values associated with a node\. If no key is - specified, the key __data__ is assumed\. Each node that is added to a - tree has the value "" assigned to the key __data__ automatically\. A node - may have any number of keyed values associated with it\. If *value* is not - specified, this command returns the current value assigned to the key; if - *value* is specified, this command assigns that value to the key\. - - - *treeName* __size__ ?*node*? - - Return a count of the number of descendants of the node *node*; if no node - is specified, __root__ is assumed\. - - - *treeName* __splice__ *parent* *from* ?*to*? ?*child*? - - Insert a node named *child* into the tree as a child of the node - *parent*\. If *parent* is __root__, it refers to the root of the - tree\. The new node will be added to the parent node's child list at the - index given by *from*\. The children of *parent* which are in the range - of the indices *from* and *to* are made children of *child*\. If the - value of *to* is not specified it defaults to __end__\. If no name is - given for *child*, a name will be generated for the new node\. The - generated name is of the form *node*__x__, where __x__ is a - number\. The return result from this command is the name of the new node\. - - - *treeName* __swap__ *node1* *node2* - - Swap the position of *node1* and *node2* in the tree\. - - - *treeName* __unset__ *node* ?__\-key__ *key*? - - Removes a keyed value from the node *node*\. If no key is specified, the - key __data__ is assumed\. - - - *treeName* __walk__ *node* ?__\-order__ *order*? ?__\-type__ *type*? __\-command__ *cmd* - - Perform a breadth\-first or depth\-first walk of the tree starting at the node - *node*\. The type of walk, breadth\-first or depth\-first, is determined by - the value of *type*; __bfs__ indicates breadth\-first, __dfs__ - indicates depth\-first\. Depth\-first is the default\. The order of the walk, - pre\-, post\-, both\- or in\-order is determined by the value of *order*; - __pre__ indicates pre\-order, __post__ indicates post\-order, - __both__ indicates both\-order and __in__ indicates in\-order\. - Pre\-order is the default\. - - Pre\-order walking means that a parent node is visited before any of its - children\. For example, a breadth\-first search starting from the root will - visit the root, followed by all of the root's children, followed by all of - the root's grandchildren\. Post\-order walking means that a parent node is - visited after any of its children\. Both\-order walking means that a parent - node is visited before *and* after any of its children\. In\-order walking - means that a parent node is visited after its first child and before the - second\. This is a generalization of in\-order walking for binary trees and - will do the right thing if a binary is walked\. The combination of a - breadth\-first walk with in\-order is illegal\. - - As the walk progresses, the command *cmd* will be evaluated at each node\. - Percent substitution will be performed on *cmd* before evaluation, just as - in a __[bind](\.\./\.\./\.\./\.\./index\.md\#bind)__ script\. The following - substitutions are recognized: - - * __%%__ - - Insert the literal % character\. - - * __%t__ - - Name of the tree object\. - - * __%n__ - - Name of the current node\. - - * __%a__ - - Name of the action occurring; one of __enter__, __leave__, or - __visit__\. __enter__ actions occur during pre\-order walks; - __leave__ actions occur during post\-order walks; __visit__ - actions occur during in\-order walks\. In a both\-order walk, the command - will be evaluated twice for each node; the action is __enter__ for - the first evaluation, and __leave__ for the second\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *struct :: tree* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[tree](\.\./\.\./\.\./\.\./index\.md\#tree) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2002 Andreas Kupries DELETED embedded/md/tcllib/files/modules/tar/tar.md Index: embedded/md/tcllib/files/modules/tar/tar.md ================================================================== --- embedded/md/tcllib/files/modules/tar/tar.md +++ embedded/md/tcllib/files/modules/tar/tar.md @@ -1,213 +0,0 @@ - -[//000000001]: # (tar \- Tar file handling) -[//000000002]: # (Generated from file 'tar\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (tar\(n\) 0\.11 tcllib "Tar file handling") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tar \- Tar file creation, extraction & manipulation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require tar ?0\.11? - -[__::tar::contents__ *tarball* ?__\-chan__?](#1) -[__::tar::stat__ *tarball* ?file? ?__\-chan__?](#2) -[__::tar::untar__ *tarball* *args*](#3) -[__::tar::get__ *tarball* *fileName* ?__\-chan__?](#4) -[__::tar::create__ *tarball* *files* *args*](#5) -[__::tar::add__ *tarball* *files* *args*](#6) -[__::tar::remove__ *tarball* *files*](#7) - -# DESCRIPTION - -Note: Starting with version 0\.8 the tar reader commands \(contents, stats, get, -untar\) support the GNU LongName extension \(header type 'L'\) for large paths\. - - - __::tar::contents__ *tarball* ?__\-chan__? - - Returns a list of the files contained in *tarball*\. The order is not - sorted and depends on the order files were stored in the archive\. - - If the option __\-chan__ is present *tarball* is interpreted as an open - channel\. It is assumed that the channel was opened for reading, and - configured for binary input\. The command will *not* close the channel\. - - - __::tar::stat__ *tarball* ?file? ?__\-chan__? - - Returns a nested dict containing information on the named ?file? in - *tarball*, or all files if none is specified\. The top level are pairs of - filename and info\. The info is a dict with the keys "__mode__ - __uid__ __gid__ __size__ __mtime__ __type__ - __linkname__ __uname__ __gname__ __devmajor__ - __devminor__" - - % ::tar::stat tarball.tar - foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0} - - If the option __\-chan__ is present *tarball* is interpreted as an open - channel\. It is assumed that the channel was opened for reading, and - configured for binary input\. The command will *not* close the channel\. - - - __::tar::untar__ *tarball* *args* - - Extracts *tarball*\. *\-file* and *\-glob* limit the extraction to files - which exactly match or pattern match the given argument\. No error is thrown - if no files match\. Returns a list of filenames extracted and the file size\. - The size will be null for non regular files\. Leading path seperators are - stripped so paths will always be relative\. - - * __\-dir__ dirName - - Directory to extract to\. Uses __pwd__ if none is specified - - * __\-file__ fileName - - Only extract the file with this name\. The name is matched against the - complete path stored in the archive including directories\. - - * __\-glob__ pattern - - Only extract files patching this glob style pattern\. The pattern is - matched against the complete path stored in the archive\. - - * __\-nooverwrite__ - - Dont overwrite files that already exist - - * __\-nomtime__ - - Leave the file modification time as the current time instead of setting - it to the value in the archive\. - - * __\-noperms__ - - In Unix, leave the file permissions as the current umask instead of - setting them to the values in the archive\. - - * __\-chan__ - - If this option is present *tarball* is interpreted as an open channel\. - It is assumed that the channel was opened for reading, and configured - for binary input\. The command will *not* close the channel\. - - % foreach {file size} [::tar::untar tarball.tar -glob *.jpg] { - puts "Extracted $file ($size bytes)" - } - - - __::tar::get__ *tarball* *fileName* ?__\-chan__? - - Returns the contents of *fileName* from the *tarball*\. - - % set readme [::tar::get tarball.tar doc/README] { - % puts $readme - } - - If the option __\-chan__ is present *tarball* is interpreted as an open - channel\. It is assumed that the channel was opened for reading, and - configured for binary input\. The command will *not* close the channel\. - - An error is thrown when *fileName* is not found in the tar archive\. - - - __::tar::create__ *tarball* *files* *args* - - Creates a new tar file containing the *files*\. *files* must be specified - as a single argument which is a proper list of filenames\. - - * __\-dereference__ - - Normally __create__ will store links as an actual link pointing at a - file that may or may not exist in the archive\. Specifying this option - will cause the actual file point to by the link to be stored instead\. - - * __\-chan__ - - If this option is present *tarball* is interpreted as an open channel\. - It is assumed that the channel was opened for writing, and configured - for binary output\. The command will *not* close the channel\. - - % ::tar::create new.tar [glob -nocomplain file*] - % ::tar::contents new.tar - file1 file2 file3 - - - __::tar::add__ *tarball* *files* *args* - - Appends *files* to the end of the existing *tarball*\. *files* must be - specified as a single argument which is a proper list of filenames\. - - * __\-dereference__ - - Normally __add__ will store links as an actual link pointing at a - file that may or may not exist in the archive\. Specifying this option - will cause the actual file point to by the link to be stored instead\. - - * __\-prefix__ string - - Normally __add__ will store files under exactly the name specified - as argument\. Specifying a ?\-prefix? causes the *string* to be - prepended to every name\. - - * __\-quick__ - - The only sure way to find the position in the *tarball* where new - files can be added is to read it from start, but if *tarball* was - written with a "blocksize" of 1 \(as this package does\) then one can - alternatively find this position by seeking from the end\. The ?\-quick? - option tells __add__ to do the latter\. - - - __::tar::remove__ *tarball* *files* - - Removes *files* from the *tarball*\. No error will result if the file - does not exist in the tarball\. Directory write permission and free disk - space equivalent to at least the size of the tarball will be needed\. - - % ::tar::remove new.tar {file2 file3} - % ::tar::contents new.tar - file3 - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tar* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[archive](\.\./\.\./\.\./\.\./index\.md\#archive), [tape -archive](\.\./\.\./\.\./\.\./index\.md\#tape\_archive), -[tar](\.\./\.\./\.\./\.\./index\.md\#tar) - -# CATEGORY - -File formats DELETED embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md Index: embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md ================================================================== --- embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md +++ embedded/md/tcllib/files/modules/tepam/tepam_argument_dialogbox.md @@ -1,910 +0,0 @@ - -[//000000001]: # (tepam::argument\_dialogbox \- Tcl's Enhanced Procedure and Argument Manager) -[//000000002]: # (Generated from file 'tepam\_argument\_dialogbox\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2013, Andreas Drollinger) -[//000000004]: # (tepam::argument\_dialogbox\(n\) 0\.5\.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tepam::argument\_dialogbox \- TEPAM argument\_dialogbox, reference manual - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [ARGUMENT DIALOGBOX CALL](#section2) - - - [Context Definition Items](#subsection1) - - - [Formatting and Display Options](#subsection2) - - - [Global Custom Data Validation](#subsection3) - - - [Data Entry Widget Items](#subsection4) - - - [Entry Widget Item Attributes](#subsection5) - - - [APPLICATION SPECIFIC ENTRY WIDGETS](#section3) - - - [VARIABLES](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require Tk 8\.3 -package require tepam ?0\.5? - -[__tepam::argument\_dialogbox__ *item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*](#1) -[__tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\}](#2) - -# DESCRIPTION - -# ARGUMENT DIALOGBOX CALL - -The TEPAM __argument\_dialogbox__ is a flexible and easily usable data entry -form generator that is available if Tk has been loaded\. Each data entry element -of a form is defined via a *data entry item* that can be provided to -__argument\_dialogbox__ in two formats: - - - __tepam::argument\_dialogbox__ *item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?* - - Using this first format, each *data entry item* is defined via a pair of - two arguments\. The first one is the *item name* that defines the entry - widget that has to be used in the form\. The second argument, called *item - attributes*, specifies the variable which is attributed to the data entry - element as well as eventual formatting and context information\. - - The __argument\_dialogbox__ returns __ok__ if the entered data have - been acknowledged \(via the *OK* button\) and validated by a data checker\. - If the entered data have been rejected \(via the *Cancel* button\) the - __argument\_dialogbox__ returns __cancel__\. - - A small example illustrates how the __argument\_dialogbox__ can be - employed: - - > set DialogResult \[__tepam::argument\_dialogbox__ \\ - >    __\-title__ "Itinerary selection" \\ - >    __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} \\ - >    __\-frame__ \{*\-label "Itinerary start"*\} \\ - >       __\-comment__ \{*\-text "Specify your itinerary start location"*\} \\ - >       __\-entry__ \{*\-label "City" \-variable start\_city \-type string*\} \\ - >       __\-entry__ \{*\-label "Street" \-variable start\_street \-type string \-optional 1*\} \\ - >       __\-entry__ \{*\-label "Street number" \-variable start\_street\_nbr \-type integer \-optional 1*\} \\ - >    __\-frame__ \{*\-label "Itinerary destination"*\} \\ - >       __\-comment__ \{*\-text "Specify your itinerary destination"*\} \\ - >       __\-entry__ \{*\-label "City" \-variable dest\_city \-type string*\} \\ - >       __\-entry__ \{*\-label "Street" \-variable dest\_street \-type string \-optional 1*\} \\ - >       __\-entry__ \{*\-label "Street number" \-variable dest\_street\_nbr \-type integer \-optional 1*\} \\ - >    __\-frame__ \{\} \\ - >    __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\}\] - - This example opens a dialog box that has the title *Itinerary selection*\. - A first entry widget in this box allows selecting a report file\. It follows - two frames to define respectively an itinerary start and end location\. Each - of these locations that are described with a comment has three entry widgets - to specify respectively the city, street and the street number\. Bellow the - second frame there is a check button that allows specifying if eventual - highways should be ignored\. - - - __tepam::argument\_dialogbox__ \{*item\_name item\_attributes ?item\_name item\_attributes? ?\.\.\.?*\} - - Sometimes it is simpler to provide all the data entry item definitions in - form of a single list to __argument\_dialogbox__, and not as individual - arguments\. The second format that is supported by __argument\_dialogbox__ - corresponds exactly to the first one, except that all item definitions are - packed into a single list that is provided to __argument\_dialogbox__\. - The previous example can therefore also be written in the following way: - - > set DialogResult \[__tepam::argument\_dialogbox \{__ - >    __\-title__ "Itinerary selection" - >    __\-file__ \{*\-label "Itinerary report" \-variable report\_file*\} - >    \.\.\. - >    __\-checkbutton__ \{*\-label "Don't use highways" \-variable no\_highway*\} __\}__\] - -The commands __argument\_dialogbox__ as well as -__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ are exported from the -namespace __tepam__\. To use these commands without the __tepam::__ -namespace prefix, it is sufficient to import them into the main namespace: - -> __namespace import tepam::\*__ -> -> set DialogResult \[__argument\_dialogbox__ \\ ->    \-title "Itinerary selection" ->    \.\.\. - -The following subsections explain the different argument item types that are -accepted by the __argument\_dialogbox__, classified into three groups\. The -first data entry item definition format will be used in the remaining document, -knowing that this format can always be transformed into the second format by -putting all arguments into a single list that is then provided to -__argument\_dialogbox__\. - -## Context Definition Items - -The first item group allows specifying some context aspects of an argument -dialog box\. These items are taking a simple character string as item attribute: - -> tepam::argument\_dialogbox \\ ->    __\-__ *string* \\ ->    \.\.\. - -The following items are classified into this group: - - - \-title *string* - - The dialog box window title which is by default *Dialog* can be changed - with the *\-title* item: - -> tepam::argument\_dialogbox \\ ->    __\-title__ "System configuration" \\ ->    \.\.\. - - - \-window *string* - - The argument dialog box uses by default *\.dialog* as dialog top level - window\. This path can be changed with the *\-window* item: - -> tepam::argument\_dialogbox \\ ->    __\-window__ \.dialog \\ ->    \.\.\. - - - \-parent *string* - - By defining a parent window, the argument dialog box will be displayed - beside this one\. Without explicit parent window definition, the top\-level - window will be considered as parent window\. - -> tepam::argument\_dialogbox \\ ->    __\-parent__ \.my\_appl \\ ->    \.\.\. - - - \-context *string* - - If a context is defined the dialog box state, e\.g\. the entered data as well - as the window size and position, is restored the next time the argument - dialog box is called\. The assignment of a context allows saving the dialog - box state in its context to distinguish between different usages of the - argument dialog box\. - -> tepam::argument\_dialogbox \\ ->    __\-context__ destination\_definitions \\ ->    \.\.\. - -## Formatting and Display Options - -Especially for big, complex forms it becomes important that the different data -entry widgets are graphically well organized and commented to provide an -immediate and clear overview to the user\. A couple of items allow structuring -and commenting the dialog boxes\. - -The items of this classification group require as item attributes a definition -list, which contains itself attribute name and value pairs: - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-__ \{ ->       *?\- ?* ->       *?\- ?* ->       *?\.\.\.?* -> ->    \} ->    \.\.\. - -The following items are classified into this group: - - - \-frame *list* - - The *\-frame* item allows packing all following entry widgets into a - labeled frame, until a next frame item is defined or until the last entry - widget has been defined\. It recognizes the following attributes inside the - item attribute list: - - * \-label *string* - - An optional frame label can be specified with the *\-label* statement\. - - Example: - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-frame__ \{*\-label "Destination address"*\} ->    \.\.\. - - To close an open frame without opening a new one, an empty list has to be - provided to the *\-frame* statement\. - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-frame__ \{\} ->    \.\.\. - - - \-sep \[const \{\{\}\}\] - - Entry widgets can be separated with the *\-sep* statement which doesn't - require additional definitions\. The related definition list has to exist, - but its content is ignored\. - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-sep__ \{\} ->    \.\.\. - - - \-comment *string* - - Comments and descriptions can be added with the *\-text* attribute of the - *\-comment* item\. Please note that each entry widget itself can also - contain a *\-text* attribute for comments and descriptions\. But the - *\-comment* item allows for example adding a description between two - frames\. - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-comment__ \{*\-text "Specify bellow the destination address"*\} ->    \.\.\. - - - \-yscroll __0__|__1__|__auto__ - - This attribute allows controlling an eventual vertical scrollbar\. Setting it - to __0__ will permanently disable the scrollbar, setting it to __1__ - will enable it\. By default it is set to __auto__\. The scrollbar is - enabled in this mode only if the vertical data entry form size exceeds 66% - of the screen height\. - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-yscroll__ __auto__ ->    \.\.\. - -## Global Custom Data Validation - -This item group allows specifying global custom checks to validate the entered -data\. - - - \-validatecommand *script* - - Custom data checks can be performed via validation commands that are defined - with the *\-validatecommand* item\. Example: - -> tepam::argument\_dialogbox \\ ->    \-entry \{\-label "Your comment" \-variable YourCom\} \\ ->    __\-validatecommand__ \{IllegalWordDetector $YourCom\} - - The validation command is executed in the context of the calling procedure, - once all the basic data checks have been performed and data variables are - assigned\. All data is accessed via the data variables\. Note that there is - also an entry widget specific attribute *\-validatecommand* that allows - declaring custom checks for specific data entries\. - - The attribute *\-validatecommand* can be repeated to declare multiple - custom checks\. - - - \-validatecommand\_error\_text *string* - - This item allows overriding the default error message for a global custom - argument validation \(defined by *\-validatecommand*\)\. Also this attribute - can be repeated in case multiple checks are declared\. - - - \-validatecommand2 *script* - - - \-validatecommand2\_error\_text *string* - - These items are mainly for TEPAM internal usage\. - - These items corrspond respectively to *\-validatecommand* and - *\-validatecommand\_error\_text*\. However, the data validation is not - performed in the next upper stack level, but two stack levels higher\. - -## Data Entry Widget Items - -Data entry widgets are created with the widget items\. These items require as -item attributes a definition list, which contains itself attribute name and -value pairs: - -> tepam::argument\_dialogbox \\ ->    \.\.\. ->    __\-__ \{ ->       *?\- ?* ->       *?\- ?* ->       *?\.\.\.?* -> ->    \} ->    \.\.\. - -The attribute list can contain various attributes to describe and comment an -entry widget and to constrain its entered value\. All entry widgets are accepting -a common set of attributes that are described in the section [Entry Widget Item -Attributes](#subsection5)\. - -TEPAM defines a rich set of entry widgets\. If necessary, this set can be -extended with additional application specific entry widgets \(see [APPLICATION -SPECIFIC ENTRY WIDGETS](#section3)\): - - - \-entry *list* - - The *\-entry* item generates the simplest but most universal data entry - widget\. It allows entering any kind of data in form of single line strings\. - -> tepam::argument\_dialogbox \\ ->    __\-entry__ \{\-label Name \-variable Entry\} - - - \-text *list* - - The *\-text* item generates a multi line text entry widget\. The widget - height can be selected with the *\-height* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-text__ \{\-label Name \-variable Text \-height 5\} - - - \-checkbox *list* - - A group of check boxes is created with the *\-checkbox* item\. The number of - check boxes and their option values are specified with a list assigned to - the *\-choices* attribute or via a variable declared with the - *\-choicevariable* attribute: - -> tepam::argument\_dialogbox \\ ->    __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\ ->                \-choices \{bold italic underline\} \-default italic\} - - If the labels of the check boxes should differ from the option values, their - labels can be defined with the *\-choicelabels* attribute: - -> tepam::argument\_dialogbox \\ ->    __\-checkbox__ \{\-label "Font sytle" \-variable FontStyle \\ ->               \-choices \{bold italic underline\} \\ ->               \-choicelabels \{Bold Italic Underline\} \\ ->               \-default italic\} - - In contrast to a radio box group, a check box group allows selecting - simultaneously several choice options\. The selection is stored for this - reason inside the defined variable in form of a list, even if only one - choice option has been selected\. - - - \-radiobox *list* - - A group of radio boxes is created with the *\-radiobox* item\. The number of - radio boxes and their option values are specified with a list assigned to - the *\-choices* attribute or via a variable declared with the - *\-choicevariable* attribute\. - - In contrast to a check box group, a radio box group allows selecting - simultaneously only one choice option\. The selected option value is stored - directly, and not in form of a list, inside the defined variable\. - -> tepam::argument\_dialogbox \\ ->    __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\ ->               \-choices \{left center right\} \-default left\} - - If the labels of the radio boxes should differ from the option values, their - labels can be defined with the *\-choicelabels* attribute: - -> tepam::argument\_dialogbox \\ ->    __\-radiobox__ \{\-label "Text adjustment" \-variable Adjustment \\ ->               \-choices \{left center right\} \\ ->               \-choicelabels \{Left Center Right\} \-default left\} - - - \-checkbutton *list* - - The *\-checkbutton* entry widget allows activating or deactivating a single - choice option\. The result written into the variable will either be __0__ - if the check button was not activated or __1__ if it was activated\. An - eventually provided default value has also to be either __0__ or - __1__\. - -> tepam::argument\_dialogbox \\ ->    __\-checkbutton__ \{\-label Capitalize \-variable Capitalize \-default 1\} - -Several types of list and combo boxes are available to handle selection lists\. - - - \-combobox *list* - - The combobox is a combination of a normal entry widget together with a - drop\-down list box\. The combobox allows selecting from this drop\-down list - box a single element\. The list of the available elements can be provided - either as a list to the *\-choices* attribute, or via a variable that is - specified with the *\-choicevariable* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-combobox__ \{\-label "Text size" \-variable Size \-choices \{8 9 10 12 15 18\} \-default 12\} - - And here is an example of using a variable to define the selection list: - -> set TextSizes \{8 9 10 12 15 18\} -> tepam::argument\_dialogbox \\ ->    __\-combobox__ \{\-label "Text size" \-variable Size \-choicevariable TextSizes \-default 12\} - - - \-listbox *list* - - In contrast to the combo box, the list box is always displayed by the - *listbox* entry widget\. Only one element is selectable unless the - *\-multiple\_selection* attribute is set\. The list box height can be - selected with the *\-height* attribute\. If the height is not explicitly - defined, the list box height is automatically adapted to the argument dialog - box size\. The first example uses a variable to define the available choices: - -> set set AvailableSizes -> for \{set k 0\} \{$k<16\} \{incr k\} \{lappend AvailableSizes \[expr 1<<$k\]\} -> -> tepam::argument\_dialogbox \\ ->    __\-listbox__ \{\-label "Distance" \-variable Distance \\ ->              \-choicevariable AvailableSizes \-default 6 \-height 5\} - - Here is a multi\-element selection example\. Please note that also the default - selection can contain multiple elements: - -> tepam::argument\_dialogbox \\ ->    __\-listbox__ \{\-label "Text styles" \-variable Styles \\ ->              \-choices \{bold italic underline overstrike\} \\ ->              \-choicelabels \{Bold Italic Underline Overstrike\} \\ ->              \-default \{bold underline\} \-multiple\_selection 1 \\ ->              \-height 3\} - - - \-disjointlistbox *list* - - A disjoint list box has to be used instead of a normal list box if the - selection order is important\. The disjoint list box entry widget has in fact - two list boxes, one to select elements and one to display the selected - elements in the chosen order\. - - Disjoint listboxes allow always selecting multiple elements\. With the - exception of the *\-multiple\_selection* attribute, disjointed list boxes - are accepting the same attributes as the normal listbox, e\.g\. *\-height, - \-choices, \-choicevariable, \-default*\. - -> tepam::argument\_dialogbox \\ ->    __\-disjointlistbox__ \{\-label "Preferred scripting languages" \-variable Languages \\ ->              \-comment "Please select your preferred languages in the order" \\ ->              \-choices \{JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl\} \\ ->              \-default \{Tcl Perl Python\}\} - -The file and directory selectors are building a next group of data entry -widgets\. A paragraph of section [Entry Widget Item -Attributes](#subsection5) explains the widget specific attributes that allow -specifying the targeted file types, active directory etc\. - - - \-file *list* - - The item *\-file* creates a group composed by an entry widget together with - a button that allows opening a file browser\. The data type *file* is - automatically selected for this entry if no data type has been explicitly - defined with the *\-type* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-file__ \{\-label "Image file" \-variable ImageF \\ ->           \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\ ->           \-initialfile "picture\.gif"\} - - - \-existingfile *list* - - The item *\-existingfile* creates a group composed by an entry widget - together with a button that allows opening a browser to select an existing - file\. The data type *existingfile* is automatically selected for this - entry if no data type has been explicitly defined with the *\-type* - attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-existingfile__ \{\-label "Image file" \-variable ImageF \\ ->                   \-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\} \\ ->                   \-initialfile "picture\.gif"\} - - - \-directory *list* - - The item *\-directory* creates a group composed by an entry widget together - with a button that allows opening a directory browser\. The data type - *directory* is automatically selected for this entry if no data type has - been explicitly defined with the *\-type* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-directory__ \{\-label "Report directory" \-variable ReportDir\} - - - \-existingdirectory *list* - - The item *\-existingdirectory* creates a group composed by an entry widget - together with a button that allows opening a browser to select an existing - directory\. The data type *existingdirectory* is automatically selected for - this entry if no data type has been explicitly defined with the *\-type* - attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-existingdirectory__ \{\-label "Report directory" \-variable ReportDir\} - -Finally, there is a last group of some other special data entry widgets\. - - - \-color *list* - - The color selector is composed by an entry widget together with a button - that allows opening a color browser\. The data type *color* is - automatically selected for this entry widget type if no data type has been - explicitly defined with the *\-type* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-color__ \{\-label "Background color" \-variable Color \-default red\} - - - \-font *list* - - The font selector is composed by an entry widget together with a button that - allows opening a font browser\. The data type *font* is automatically - selected for this entry widget type if no data type has been explicitly - defined with the *\-type* attribute\. The entry widget displays an example - text in the format of the selected font\. - - The font browser allows selecting by default the font families provided by - the __font families__ Tk command as well as a reasonable set of - different font sizes between 6 points and 40 points\. Different sets of font - families and font sizes can be specified respectively via the - *\-font\_families* or *\-font\_sizes* attributes\. - - If no default font is provided via the *\-default* attribute, the default - font of the label widget to display the selected font will be used as - default selected font\. If the font family of this label widget is not part - of the available families the first available family is used as default\. If - the font size of this label widget is not part of the available sizes the - next close available size is selected as default size\. - -> tepam::argument\_dialogbox \\ ->    __\-font__ \{\-label "Font" \-variable Font \\ ->           \-font\_sizes \{8 10 12 16\} \\ ->           \-default \{Arial 20 italic\}\} - -## Entry Widget Item Attributes - -All the entry widget items are accepting the following attributes: - - - \-text *string* - - Eventual descriptions and comments specified with the *\-text* attribute - are displayed above the entry widget\. - -> tepam::argument\_dialogbox \\ ->    \-entry \{__\-text "Please enter your name bellow"__ \-variable Name\} - - - \-label *string* - - The label attribute creates left to the entry widget a label using the - provided string as label text: - -> tepam::argument\_dialogbox \\ ->    \-entry \{__\-label Name__ \-variable Name\} - - - \-variable *string* - - All entry widgets require a specified variable\. After accepting the entered - information with the OK button, the entry widget data is stored inside the - defined variables\. - -> tepam::argument\_dialogbox \\ ->    \-existingdirectory \{\-label "Report directory" __\-variable ReportDir__\} - - - \-default *string* - - Eventual default data for the entry widgets can be provided via the - *\-default* attribute\. The default value is overridden if an argument - dialog box with a defined context is called another time\. The value - acknowledged in a previous call will be used in this case as default value\. - -> tepam::argument\_dialogbox \\ ->    \-checkbox \{\-label "Font sytle" \-variable FontStyle \\ ->                \-choices \{bold italic underline\} __\-default italic__\} - - - \-optional __0__|__1__ - - Data can be specified as optional or mandatory with the *\-optional* - attribute that requires either __0__ \(mandatory\) or __1__ \(optional\) - as attribute data\. - - In case an entry is optional and no data has been entered, e\.g\. the entry - contains an empty character string, the entry will be considered as - undefined and the assigned variable will not be defined\. - -> tepam::argument\_dialogbox \\ ->    \-entry \{\-label "City" \-variable start\_city \-type string\} \\ ->    \-entry \{\-label "Street" \-variable start\_street \-type string __\-optional 0__\} \\ ->    \-entry \{\-label "Street number" \-variable start\_street\_nbr \-type integer __\-optional 1__\} \\ - - - \-type *string* - - If the data type is defined with the *\-type* attribute the argument dialog - box will automatically perform a data type check after acknowledging the - entered values and before the dialog box is closed\. If a type incompatible - value is found an error message box appears and the user can correct the - value\. - - The argument dialog box accepts all types that have been specified by the - TEPAM package and that are also used by - __[tepam::procedure](tepam\_procedure\.md)__ \(see the - *tepam::procedure reference manual*\)\. - - Some entry widgets like the file and directory widgets, as well as the color - and font widgets are specifying automatically the default data type if no - type has been specified explicitly with the *\-type* attribute\. - -> tepam::argument\_dialogbox \\ ->    __\-entry__ \{\-label "Street number" \-variable start\_street\_nbr __\-type integer__\} \\ - - - \-range *string* - - Values can be constrained with the *\-range* attribute\. The valid range is - defined with a list containing the minimum valid value and a maximum valid - value\. - - The *\-range* attribute has to be used only for numerical arguments, like - integers and doubles\. - -> tepam::argument\_dialogbox \\ ->    \-entry \{\-label Month \-variable Month \-type integer __\-range \{1 12\}__\} - - - \-validatecommand *string* - - Custom argument value validations can be performed via specific validation - commands that are defined with the *\-validatecommand* attribute\. The - provided validation command can be a complete script in which the pattern - *%P* is placeholder for the argument value that has to be validated\. - -> tepam::argument\_dialogbox \\ ->    \-entry \{\-label "Your comment" \-variable YourCom \\ ->            __\-validatecommand__ "IllegalWordDetector %P"\} - - While the purpose of this custom argument validation attribute is the - validation of a specific argument, there is also a global data validation - attribute *\-validatecommand* that allows performing validation that - involves multiple arguments\. - - - \-validatecommand\_error\_text *string* - - This attribute allows overriding the default error message for a custom - argument validation \(defined by *\-validatecommand*\)\. - -Some other attributes are supported by the list and combo boxes as well as by -the radio and check buttons\. - - - \-choices *string* - - Choice lists can directly be defined with the *\-choices* attribute\. This - way to define choice lists is especially adapted for smaller, fixed - selection lists\. - -> tepam::argument\_dialogbox \\ ->    \-listbox \{\-label "Text styles" \-variable Styles \\ ->              __\-choices \{bold italic underline\}__ \-default underline - - - \-choicelabels *string* *\(only check and radio buttons\)* - - If the labels of the check and radio boxes should differ from the option - values, they can be defined with the *\-choicelabels* attribute: - -> tepam::argument\_dialogbox \\ ->    \-checkbox \{\-label "Font sytle" \-variable FontStyle \\ ->               \-choices \{bold italic underline\} \\ ->               __\-choicelabels \{Bold Italic Underline\}__ - - - \-choicevariable *string* - - Another way to define the choice lists is using the *\-choicevariable* - attribute\. This way to define choice lists is especially adapted for huge - and eventually variable selection lists\. - -> set TextSizes \{8 9 10 12 15 18\} -> tepam::argument\_dialogbox \\ ->    \-combobox \{\-label "Text size" \-variable Size __\-choicevariable TextSizes__\} - - - \-multiple\_selection __0__|__1__ - - The list box item \(__\-listbox__\) allows by default selecting only one - list element\. By setting the *\-multiple\_selection* attribute to __1__, - multiple elements can be selected\. - -> tepam::argument\_dialogbox \\ ->    \-listbox \{\-label "Text styles" \-variable Styles \\ ->              \-choices \{bold italic underline\} \-default underline \\ ->              __\-multiple\_selection 1__ \-height 3\} - -Some additional attributes are supported by the file and directory selection -widgets\. - - - \-filetypes *string* - - The file type attribute is used by the __\-file__ and - __\-existingfile__ items to define the file endings that are searched by - the file browser\. - -> tepam::argument\_dialogbox \\ ->    \-file \{\-label "Image file" \-variable ImageF \\ ->           __\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\}\}__\} - - - \-initialfile *string* - - The initial file used by the file browsers of the __\-file__ and - __\-existingfile__ widgets are by default the file defined with the - *\-default* attribute, unless a file is specified with the *\-initialfile* - attribute\. - -> tepam::argument\_dialogbox \\ ->    \-file \{\-variable ImageF __\-initialfile "picture\.gif"__\} - - - \-activedir *string* - - The *\-activedir* attribute will override the default active search - directory used by the file browsers of all file and directory entry widgets\. - The default active search directory is defined by the directory of a - specified initial file \(*\-initialfile*\) if defined, and otherwise by the - directory of the default file/directory, specified with the *\-default* - attribute\. - -> tepam::argument\_dialogbox \\ ->    \-file "\-variable ImageF __\-activedir $pwd__" - -Finally, there is a last attribute supported by some widgets: - - - \-height *string* - - All widgets containing a selection list \(__\-listbox__, - __\-disjointlistbox__, __\-font__\) as well as the multi line - __\-text__ widget are accepting the *\-height* attribute that defines - the number of displayed rows of the selection lists\. - -> tepam::argument\_dialogbox \\ ->    \-listbox \{\-label "Text size" \-variable Size \\ ->              \-choices \{8 9 10 12 15 18\} \-default 12 __\-height 3__\} - - If the no height has been explicitly specified the height of the widget will - be dynamically adapted to the argument dialog box size\. - -# APPLICATION SPECIFIC ENTRY WIDGETS - -An application specific entry widget can be made available to the argument -dialog box by adding a dedicated procedure to the __tepam__ namespace\. This -procedure has three arguments; the first one is the widget path, the second one -a subcommand and the third argument has various purposes: - -> *proc* tepam::ad\_form\(\) \{W Command \{Par ""\}\} \{ ->    *upvar Option Option; \# if required* ->    *variable argument\_dialogbox; \# if required* ->    switch $Command \{ ->       "create" ->       "set\_choice" ->       "set" ->       "get" ->    \} -> \} - -__Argument\_dialogbox__ takes care about the *\-label* and *\-text* -attributes for all entry widgets\. For any data entry widget it creates a frame -into which the data entry widget components can be placed\. The path to this -frame is provided via the *W* argument\. - -The entry widget procedure has to support 3 mandatory and an optional command -that are selected via the argument *Command*: - - - *create* - - The entry widget is called a first time with the command *create* to build - the data entry widget\. - - The frames that are made available by __argument\_dialogbox__ for the - entry widgets are by default only extendable in the X direction\. To make - them also extendable in the Y direction, for example for extendable list - boxes, the command __ad\_form\(make\_expandable\) $W__ has to be executed - when an entry widget is built\. - - - *set\_choice* - - The entry widget procedure is only called with the *set\_choice* command if - the *\-choices* or *\-choicevariable* has been specified\. The command is - therefore only relevant for list and combo boxes\. - - The available selection list that is either specified with the *\-choices* - or *\-choicevariable* attribute is provided via the *Par* argument to the - entry widget procedure\. This list can be used to initialize an available - choice list\. - - - *set* - - If a default value is either defined via the *\-default* attribute or via a - preceding call the entry widget procedure is called with the *set* - command\. The argument *Par* contains in this case the value to which the - entry widget has to be initialized\. - - - *get* - - The entry widget procedure command *get* has to return the current value - of the entry widget\. - -Eventually specified entry widget item attributes are available via the -__Option__ array variable of the calling procedure\. This variable becomes -accessible inside the entry widget procedure via the __upvar__ command\. - -There may be a need to store some information in a variable\. The array variable -__argument\_dialogbox__ has to be used for this purpose together with array -indexes starting with *"$W,"*, e\.g\. *argument\_dialogbox\($W,values\)*\. - -Examples of entry widget procedures are directly provided by the TEPAM package -source file that specifies the standard entry widget procedures\. The simplest -procedure is the one for the basic *entry* widget: - - proc tepam::ad_form(entry) {W Command {Par ""}} { - switch $Command { - "create" {pack [entry \$W.entry] -fill x \ - -expand yes -pady 4 -side left} - "set" {\$W.entry insert 0 $Par} - "get" {return [\$W.entry get]} - } - } - -It is also possible to relay on an existing entry widget procedure to derive a -new, more specific one\. The *radiobox* widget is used for example, to create a -new entry widget that allows selecting either *left*, *center* or *right*\. -The original *radiobox* widget is called with the *set\_choice* command -immediately after the *create* command, to define the fixed list of selection -options\. - - proc tepam::ad_form(rcl) {W Command {Par ""}} { - set Res [ad_form(radiobox) $W $Command $Par] - if {$Command=="create"} { - ad_form(radiobox) $W set_choice {left center right} - } - return $Res - } - -Please consult the TEPAM package source file to find additional and more complex -examples of entry widget procedures\. - -# VARIABLES - -The __argument\_dialogbox__ is using two variables inside the namespace -__::tepam__: - - - __argument\_dialogbox__ - - Application specific entry widget procedures can use this array variable to - store their own data, using as index the widget path provided to the - procedure, e\.g\. *argument\_dialogbox\($W,\)*\. - - - __last\_parameters__ - - This array variable is only used by an argument dialog box if its context - has been specified via the *\-context* attribute\. The argument dialog box - position and size as well as its entered data are stored inside this - variable if the data are acknowledged and the form is closed\. This allows - the form to restore its previous state once it is called another time\. - - To reuse the saved parameters not just in the actual application session but - also in another one, it is sufficient to store the __last\_parameter__ - array variable contents in a configuration file which is loaded the next - time an application is launched\. - -# SEE ALSO - -[tepam\(n\)](tepam\_introduction\.md), -[tepam::procedure\(n\)](tepam\_procedure\.md) - -# KEYWORDS - -[data entry form](\.\./\.\./\.\./\.\./index\.md\#data\_entry\_form), [parameter entry -form](\.\./\.\./\.\./\.\./index\.md\#parameter\_entry\_form) - -# CATEGORY - -Argument entry form, mega widget - -# COPYRIGHT - -Copyright © 2009\-2013, Andreas Drollinger DELETED embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md Index: embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md ================================================================== --- embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md +++ embedded/md/tcllib/files/modules/tepam/tepam_doc_gen.md @@ -1,557 +0,0 @@ - -[//000000001]: # (tepam::doc\_gen \- Tcl's Enhanced Procedure and Argument Manager) -[//000000002]: # (Generated from file 'tepam\_doc\_gen\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2013, Andreas Drollinger) -[//000000004]: # (tepam::doc\_gen\(n\) 0\.5\.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tepam::doc\_gen \- TEPAM DOC Generation, reference manual - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [ARGUMENTS](#section2) - - - [PREDEFINED DOCUMENT FORMATS](#section3) - - - [TXT \- Text format](#subsection1) - - - [HTML \- HTML format](#subsection2) - - - [POD \- Perl document format](#subsection3) - - - [DT \- TclLib DocTools format](#subsection4) - - - [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) - - - [EXAMPLES](#section5) - - - [tepam::doc\_gen::generate](#subsection5) - - - [tepam::doc\_gen::patch](#subsection6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require tepam 0\.5 -package require tepam::doc\_gen ?0\.1? - -[__tepam::doc\_gen::generate__ ?\-format *format*? ?\-style *style*? ?\-header\_footer? ?\-dest\_file *dest\_file*? *name*](#1) -[__tepam::doc\_gen::patch__ ?\-format *format*? ?\-style *style*? ?\-search\_pattern *search\_pattern*? ?\-src\_string *src\_string* | \-src\_file *src\_file*? ?\-dest\_file *dest\_file*? ?name?](#2) - -# DESCRIPTION - -This package generates documentations of TEPAM procedures \(procedures that have -been declared with __[tepam::procedure](tepam\_procedure\.md)__\)\. The -documents are generated in the classic UNIX document style using the following -document sections: Name, Synopsis, Description, Arguments and Example\. __TEPAM -Doc Gen__ provides support for various document formats\. Support for -additional formats can be added if necessary\. - -The __TEPAM Doc Gen__ package provides the following commands: - - - __tepam::doc\_gen::generate__ ?\-format *format*? ?\-style *style*? ?\-header\_footer? ?\-dest\_file *dest\_file*? *name* - - This command generates the documentation for a specified procedure - \(*name*\) in one of the supported formats \(TXT, HTML, POD \(Perl Doc\), DT - \(TclLib DocTool\), or in a custom specific format\. The format is specified - via ?format?\. The flag ?\-header\_footer? adds to the documentation file - header and footer\. If ?dest\_file? is specified the documentation is stored - in a file \(the file header and footer are added automatically in this case\) - and the file name is returned\. Otherwise the documentation string is - returned by __generate__\. - - - __tepam::doc\_gen::patch__ ?\-format *format*? ?\-style *style*? ?\-search\_pattern *search\_pattern*? ?\-src\_string *src\_string* | \-src\_file *src\_file*? ?\-dest\_file *dest\_file*? ?name? - - This command inserts procedure documentations into an existing master - document at the locations indicated by insertion placeholders which are - matching the pattern of ?search\_pattern?\. The existing master document is - either provided as data to the argument \(?src\_string?\) or via a file - \(?src\_file?\)\. The final document is returned by - __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ if no destination file is - defined \(?dest\_file?\)\. Otherwise, the document is stored in the specified - file, and the number of insertion placeholders that could be handled - successfully is returned\. - - Any insertion placeholders of the master document are handled by default\. By - defining the argument ?name? the documentation insertion will be restricted - to a particular procedure\. - -# ARGUMENTS - - - ?\-format *format*? - - Specifies the documentation format\. __TEPAM Doc Gen__ provides support - for the following formats: - - * TXT \- Text format \(default\) - - * HTML - - * POD \- Perl Plain Old Documentation format \(PerlPOD\) - - * DT \- TclLib DocTool format - - Section [ADDING SUPPORT FOR NEW DOCUMENT FORMATS](#section4) shows how - support for additional formats can be added\. - - - ?\-style *style*? - - The documentation is by default generated in Tcl style \(e\.g\. __command - arg1 arg2 \.\.\.__\)\. C\-style documentation can be generated by setting this - argument to 'C' \(e\.g\. __command\(arg1,arg2,\.\.\.\)__\)\. - - - ?\-dest\_file *dest\_file*? - - If ?dest\_file? is defined the documentation is written into the specified - destination file\. Otherwise the documentation string is returned by the - commands __generate__ and - __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__\. - - - *name* / ?name? - - This is the name of the procedure for which the documentation has to be - generated\. This is a mandatory argument for __generate__, but an - optional argument for __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__\. - - - ?\-header\_footer? - - __Generate__ adds to the generated procedure documentation the file - header and footer only if a file is generated\. By selecting the flag - ?\-header\_footer? the header and footer are also generated if the - documentation is returned as string by __generate__\. - - - ?\-src\_string *src\_string* | \-src\_file *src\_file*? - - __[Patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ inserts procedure - documentations into an existing document that is either provided as string - to the argument \(?src\_string?\) or as a file \(?src\_file?\)\. One of these two - arguments need to be specified\. - - - ?\-search\_pattern *search\_pattern*? - - The argument ?search\_pattern? defines the documentation insertion - placeholder used in a document\. It is a regular expression accepted by - __regexp__ and needs to contain a parenthesized sub\-expression that - contains the procedure name for which the documentation needs to be - inserted\. - - The default insertion placeholder pattern is *\\\{\!\(\.\*?\)\!\\\}*, which means - that the procedure name will be embedded between *\{\!* and *\!\}*\. The - section [EXAMPLES](#section5) contains a custom insertion placeholder - pattern example\. - -# PREDEFINED DOCUMENT FORMATS - -__TEPAM Doc Gen__ pre\-defines the following document formats: - -## TXT \- Text format - -The documentation will be generated in a simple text format if this format is -selected\. The format can be customized via the following variable: - - - __tepam::doc\_gen::Option\(TXT,MaxLineLength\)__ - - Default: 80 - - This variable defines the line wrapping limit \(character position\)\. - -## HTML \- HTML format - -__TEPAM Doc Gen__ generates CSS styled HTML files\. The HTML documentation -can be customized via the following variable: - - - __tepam::doc\_gen::Option\(HTML,CssFile\)__ - - Default: "tepam\_doc\_stylesheet\.css" - - This variable specifies the CSS stylesheet file that is referred by the - generated HTML files\. - -The CSS stylesheet can be customized to change the documentation formatting\. A -good starting point to create a customized CSS stylesheet is to use the CSS file -provided by the __TEPAM Doc Gen__ example/demo\. The HTML documentation uses -the following CSS class styles: - - - *h1\.tepam\_page\_title* \- Document page title\. Only used by __generate__ - if a file is created or if the header and footer are built \(flag - ?\-header\_footer? selected\)\. - - - *div\.tepam\_command\_help* \- Documentation container\. The entire procedure - documentation is placed inside this container\. - - - *p\.tepam\_section\_title* \- Section title \(e\.g\. *Name*, *Synopsis*, - *Description*, \.\.\.\) - - - *p\.tepam\_sub\_section\_title* \- Sub\-section title \(used to separate the - documentation of multiple sub\-procedures\) - - - *p\.tepam\_name* \- Name section - - - *p\.tepam\_synopsis* \- Synopsis section - - - *p\.tepam\_description* \- Single description paragraph - - - *ul\.tepam\_description\_list* \- Item of a HTML bulleted/unordered list - inside the description section - - - *dt\.tepam\_argument* \- Item of a HTML description list used to list the - procedure arguments - - - *p\.tepam\_argument\_description* \- Argument description paragraph - - - *p\.tepam\_argument\_attribute* \- Argument attribute line - - - *pre\.tepam\_example* \- Example section - -## POD \- Perl document format - -The documentation is generated in the Perl Plain Old Documentation format -\(PerlPOD\) if this format is selected\. - -## DT \- TclLib DocTools format - -The documentation is generated in the Tcllib DocTools format if this format is -selected\. - -# ADDING SUPPORT FOR NEW DOCUMENT FORMATS - -Support for a new document format can be added by defining in the -__tepam::doc\_gen__ namespace a set of procedures that generate the different -document components\. - -The following documentation listing contains tokens that refer to the different -document generation procedures: - ->       *<01>* ->  *<03> <20s>* NAME*<20e>* ->       *<30s>* message\_box \- Displays text in a message box*<30e>* ->       *<20s>* SYNOPSYS*<20e>* ->       *<40s>* message\_box \[\-mtype \] *<40e>* ->       *<20s>* DESCRIPTION*<20e>* ->       *<21s> message\_box<21e>* ->       *<54s> message\_box \[\-mtype \] <54e>* ->       *<50s>* This procedure allows displaying a text in an message box\. The following ->            ** message types are supported:*<50e>* ->  *<51> <53s>* \* Info*<53e>* ->       *<53s>* \* Warning*<53e>* ->       *<53s>* \* Error*<53e>* *<52>* ->       *<50s>* If the text parameter is use multiple times the different texts are ->            ** concatenated to create the message text\.*<50e>* ->       *<20s>* ARGUMENTS*<20e>* ->  *<60> <62s>* \[\-mtype \]*<62e>* ->  *<63> <65s>* Message type*<65e>* ->       *<66s>* Default: "Warning"*<66e>* ->       *<66s>* Multiple: yes*<66e>* ->       *<66s>* Choices: Info, Warning, Error*<66e>* *<64>* ->       *<62s>* *<62e>* ->  *<63> <65s>* One or multiple text lines to display*<65e>* ->       *<66s>* Type: string*<66e>* ->       *<66s>* Multiple: yes*<66e>* *<64><61>* ->       *<20s>* EXAMPLE*<20e>* ->  *<70> <72s>* message\_box "Please save first the document"*<72e>* ->       *<73s>* \-> 1*<73e>* *<71><04>* ->       *<02>* - -There are 2 types of document generation procedures: - - - Content generation procedures \(e\.g\. <40s>\.\.\.<40e>\) - - These procedures generate some document content based on the text that is - provided as procedure argument\. The listing above shows two tokens for these - procedures to indicate the beginning and the end of the generated content\. - - - Control generation procedures \(e\.g\. <03>\) - - These procedures generate control constructs, for example to generate the - prolog code and epilog code for lists, sections, etc\. These procedures have - no argument\. - -The following set of procedures needs to be defined to provide support for a new -document format: - - - *01* \- __gen\($Format,Header\)__ \{*Text*\} - - Only called if __doc\_gen__ generates a file or if it is called with the - flag ?\-header\_footer?\. The procedure creates the file header\. The provided - parameter is the procedure name for which the documentation has to be - generated\. - - - *02* \- __gen\($Format,Footer\)__ \{*Text*\} - - Only called if __doc\_gen__ generates a file or if it is called with the - flag ?\-header\_footer?\. The procedure creates the file footer\. - - - *03* \- __gen\($Format,Begin\)__ \{\} - - Generates the documentation prolog \(preamble\) - - - *04* \- __gen\($Format,End\)__ \{\} - - Generates the documentation epilog - - - *20* \- __gen\($Format,SectionTitle\)__ \{*Text*\} - - Generates a section title \(e\.g\. *Name*, *Synopsis*, *Description*, - \.\.\.\)\. The raw title text is provided as parameter - - - *21* \- __gen\($Format,SubSectionTitle\)__ \{*Text*\} - - Generates a sub\-section title\. Sub\-sections are used if a single - documentation is generated for multiple sub\-commands to make a separation - between them\. The raw title text is provided as parameter - - - *30* \- __gen\($Format,Name\)__ \{*Text*\} - - Generates the name section \(without title\)\. The raw section text is provided - as parameter\. - - - *40* \- __gen\($Format,Synopsis\)__ \{*Text*\} - - Generates the synopsis section \(without title\)\. The section text provided as - parameter is pre\-formatted \(the argument strings are generated by - __gen\($Format,ArgumentString\)__\)\. - - - *50* \- __gen\($Format,Description\)__ \{*Text*\} - - Generates a description paragraph\. The raw paragraph text is provided as - parameter\. - - - *51* \- __gen\($Format,DescriptionListBegin\)__ \{\} - - Generates the prolog of a bulleted/unordered list inside the description - section\. This prolog is usually the start code of a list structure\. - - - *52* \- __gen\($Format,DescriptionListEnd\)__ \{\} - - Generates the epilog of a bulleted/unordered list inside the description - section\. This epilog is usually the end code of a list structure\. - - - *53* \- __gen\($Format,DescriptionListItem\)__ \{*Text*\} - - Generates a text item in a bulleted/unordered description list\. The raw item - text is provided as parameter\. - - - *54* \- __gen\($Format,DescriptionSynopsis\)__ \{*Text*\} - - Generates the synopsis line on the beginning of the description section\. The - command can return an empty string if no synopsys line is required at this - place\. - - Some formats \(e\.g\. Tcl DocTools\) require that the synopsis line is defined - in the description section, to build then automatically the synopsis - section\. The section text provided as parameter is pre\-formatted \(the - argument strings are generated by __gen\($Format,ArgumentString\)__\)\. - - - *60* \- __gen\($Format,ArgumentListBegin\)__ \{\} - - Generates the prolog of argument list \(definition/non\-bulleted list\)\. This - prolog is usually the start code of a definition list\. - - - *61* \- __gen\($Format,ArgumentListEnd\)__ \{\} - - Generates the epilog of the argument list\. This epilog is usually the end - string of a list structure\. - - - *62* \- __gen\($Format,ArgumentListItem\)__ \{Name IsOptional IsNamed Type\} - - Generates an argument item line inside the argument list\. This command can - rely on __gen\($Format,ArgumentDetailBegin\)__ since the parameters are - identical\. - - - *63* \- __gen\($Format,ArgumentDetailBegin\)__ \{\} - - Generates the argument details prolog \(preamble\)\. - - - *64* \- __gen\($Format,ArgumentDetailEnd\)__ \{\} - - Generates the argument details epilog - - - *65* \- __gen\($Format,ArgumentDescription\)__ \{*Text*\} - - Generates the argument description \(single paragraph\)\. - - - *66* \- __gen\($Format,ArgumentAttribute\)__ \{*Text*\} - - Generates a single argument attribute string\. The command is called - individually for each attribute\. - - - *70* \- __gen\($Format,ExampleBegin\)__ \{\} - - Generates the example section prolog \(preamble\) - - - *71* \- __gen\($Format,ExampleEnd\)__ \{\} - - Generates the example section epilog - - - *72* \- __gen\($Format,ExampleCommandLine\)__ \{*Text*\} - - Generates a single command line in the example section\. The command is - called for each individual command line\. - - - *73* \- __gen\($Format,ExampleResultLine\)__ \{*Text*\} - - Generates a command result line - - - *80* \- __gen\($Format,ArgumentString\)__ \{Name IsOptional IsNamed Type\} - - Generates the part of the command line or the synopsis that is specific to - an argument\. The generated string has to indicate if an argument is - optional, named and if it is a flag\. - - The following parameters are provided to this procedure: - - * *Name* - - Name of the argument - - * *IsOptional* - - If true \(=__1__\) the argument is optional which should be indicated - by the generated string \(for example by putting the argument into - brackets \{\[\]\} or into question marks '?'\): - -> gen\(TXT,ArgumentString\) mtype 1 0 string \-> *"\[mtype\]"* - - * *IsNamed* - - If true \(=__1__\) an argument is a named argument \(option\)\. The - generated string should in this case contain the argument/option name, - followed by the argument itself: - -> gen\(TXT,ArgumentString\) mtype 0 1 string \-> *"\-mtype "* - - Named arguments can also be optional: - -> gen\(TXT,ArgumentString\) mtype 1 1 string \-> *"\[\-mtype \]"* - - * *Type* - - Indicates the type of the argument\. If the type is set to __none__ - the argument is a flag, which needs to be indicated by the generated - string\. Example: - -> gen\(TXT,ArgumentString\) close 1 1 none \-> *"\[\-close\]"* - -# EXAMPLES - -## tepam::doc\_gen::generate - -The __TEPAM Doc Gen__ package can be explored by generating the -documentation of the command __tepam::doc\_gen::generate__\. The following -example generates the document in text format \(default format\): - -> __tepam::doc\_gen::generate__ tepam::doc\_gen::generate - -The next example generates the documentation in HTML format: - -> __tepam::doc\_gen::generate__ \-format HTML tepam::doc\_gen::generate - -The flag ?header\_footer? adds also the file header and footer: - -> __tepam::doc\_gen::generate__ \-format HTML \-header\_footer tepam::doc\_gen::generate - -The documentation can directly be stored in a file\. The file header and footer -are automatically generated in this way: - -> __tepam::doc\_gen::generate__ \-format HTML \-dest\_file doc\_gen\.html tepam::doc\_gen::generate - -The generated HTML file refers a CSS stylesheet file \(default: -tepam\_doc\_stylesheet\.css\)\. To display the HTML file correctly this CSS -stylesheet file needs to be copied into the directory of the generated HTML -file\. - -The Tcl DOC Tools format can be used as intermediate format to generate other -formats, for example HTML: - -> *\# Generate the documentation in Tcl Doc Tool format* -> set dt \[__tepam::doc\_gen::generate__ \-format DT \-header\_footer tepam::doc\_gen::generate\] -> ** -> *\# Create a new doc tools object \(HTML format\)* -> package require doctools -> ::doctools::new myDoc \-format html -> ** -> *\# Open the HTML file, and write the HTML formatted documentation* -> set fHtml \[open doc\_gen\.dt\.html w\] -> puts $fHtml \[myDoc format $dt\] -> close $fHtml - -## tepam::doc\_gen::patch - -While __generate__ provides a limited number of possibilities to vary the -document structure, __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ offers more -flexibility\. Multiple documentations for different procedures and meta -information can for example be added\. - -The following listing shows how the -__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ command works\. It defines first -a HTML master document string that contains 2 procedure documentation -placeholders \(*\{\*\*\}*\)\. There placeholders are replaced by -__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ with the generated documentation -of the referred procedures\. Since nonstandard placeholders are used, -__[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ is called with an explicit -placeholder pattern definition \(argument *search\_pattern*\)\. - -> *\# Define the HTML master document* -> set HtmlMasterDoc \{\\ -> ->    ->     tepam::doc\_gen ->      ->      ->    ->    ->     

tepam::doc\_gen

->       

Generate

-> __\{\*tepam::doc\_gen::generate\*\}__ ->       

Patch

-> __\{\*tepam::doc\_gen::patch\*\}__ ->    -> \\ -> \} -> ** -> *\# Patch the master document: This will replace the placeholders by the * -> *\# procedure documentation divisions:* -> -> __tepam::doc\_gen::patch__ \-format HTML \-search\_pattern \{\\\{\\\*\(\.\*?\)\\\*\\\}\} \\ ->                       \-src\_string $HtmlMasterDoc \-dest\_file tepam\_doc\_gen\.html - -# SEE ALSO - -[tepam\(n\)](tepam\_introduction\.md), -[tepam::procedure\(n\)](tepam\_procedure\.md) - -# KEYWORDS - -[automatic documentation](\.\./\.\./\.\./\.\./index\.md\#automatic\_documentation), -[documentation](\.\./\.\./\.\./\.\./index\.md\#documentation), [procedure -documentation](\.\./\.\./\.\./\.\./index\.md\#procedure\_documentation) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © 2013, Andreas Drollinger DELETED embedded/md/tcllib/files/modules/tepam/tepam_introduction.md Index: embedded/md/tcllib/files/modules/tepam/tepam_introduction.md ================================================================== --- embedded/md/tcllib/files/modules/tepam/tepam_introduction.md +++ embedded/md/tcllib/files/modules/tepam/tepam_introduction.md @@ -1,468 +0,0 @@ - -[//000000001]: # (tepam \- Tcl's Enhanced Procedure and Argument Manager) -[//000000002]: # (Generated from file 'tepam\_introduction\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2013, Andreas Drollinger) -[//000000004]: # (tepam\(n\) 0\.5\.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tepam \- An introduction into TEPAM, Tcl's Enhanced Procedure and Argument -Manager - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Description](#section1) - - - [OVERVIEW](#section2) - - - [PROCEDURE DECLARATION](#section3) - - - [PROCEDURE HELP](#section4) - - - [PROCEDURE CALL](#section5) - - - [INTERACTIVE PROCEDURE CALLS](#section6) - - - [FLEXIBLE ARGUMENT DIALOG BOX](#section7) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# DESCRIPTION - -This document is an informal introduction into TEPAM, the Tcl's Enhanced -Procedure and Argument Manager\. Detailed information to the TEPAM package is -provided in the *tepam::procedure* and *tepam::argument\_dialogbox* reference -manuals\. - -# OVERVIEW - -This package provides a new Tcl procedure declaration syntax that simplifies the -implementation of procedure subcommands and the handling of the different types -of procedure arguments like flags or switches, options, unnamed arguments, -optional and mandatory options and arguments, default values, etc\. Procedure -declarations can be enriched with detailed information about the procedure and -its arguments\. This information is used for the following purposes: - -First of all, a preamble is added in front of the body of a procedure that is -declared with TEPAM\. This preamble calls an argument manager that that uses the -provided information to check the validity of the argument types and values -before the procedure body is executed\. Then, the information is used to generate -help and usage texts if requested, or to generate clear error message in case an -argument validation fails\. The information also allows generating automatically -graphical forms that allows an interactive definition of all arguments, in case -a procedure is called interactively\. And finally, the additional information -helps self\-commenting in a clean way the declaration of a procedure and of all -its arguments\. - -The graphical form generator that creates the necessary argument specification -forms for the interactive procedure calls is also available for other purposes -than for procedure argument specifications\. It allows creating code efficiently -complex parameter entry forms that are usable independently from TEPAM's new -procedure definition method\. - -Here is a short overview about all major TEPAM features: - - - New self\-documenting procedure declaration syntax: The additional - information to declare properly a procedure has not to be provided with - additional statements, but can be added in a natural syntax directly into - the procedure header\. - - - Easy way to specify subcommands: A subcommand is declared like a procedure, - simply with a procedure name composed by a base name followed by a - subcommand name\. Sub\-subcommands are created identically using simply - procedure names composed by 3 words\. - - - Flexible usage of flags \(switches\), options \(named arguments\) and unnamed - arguments\. Option names are optionally automatically completed\. - - - Support for default values, mandatory/optional options and arguments, choice - lists, value ranges, multiple usable options/arguments\. - - - Choice of a *named arguments first, unnamed arguments later* procedure - calling style \(typical for Tcl commands\) or of an *unnamed arguments first, - named arguments later* procedure calling style \(typical for Tk commands\)\. - - - In case the *named arguments first, unnamed arguments later* style \(Tcl\) - is selected: Clear separation between options and arguments via the "\-\-" - flag\. The unnamed arguments can optionally be accessed as options \(named - arguments\)\. - - - Automatic type and value check before the procedure body is executed, taking - into account validation ranges, choice lists and custom validation commands\. - Generation of clear error message if necessary\. - - - Many predefined types exist \(integer, boolean, double, color, file, font, - \.\.\.\)\. Other application specific types can easily be added\. - - - Automatic help and usage text generation if a procedure is called with the - *\-help* flag\. - - - Automatic generation of an interactive argument definition form, in case a - procedure is called with the *\-interactive* flag\. - - - Procedure calls can be logged which is useful to get for interactively - called procedures the command call lines\. - - - Powerful and code efficient generation of complex parameter definition - forms\. - -# PROCEDURE DECLARATION - -TEPAM's procedure declaration syntax is simple and self\-explaining\. Instead of -declaring a procedure with the Tcl key word -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__, a procedure is declared with the -TEPAM command __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ which -takes as __[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ also 3 arguments: The -procedure name, the procedure header and the procedure body\. - -The following example declares the subcommand -__[message](\.\./\.\./\.\./\.\./index\.md\#message)__ of the procedure -__display__\. This command has several named and unnamed arguments: - -> __[tepam::procedure](tepam\_procedure\.md)__ \{display message\} \{ ->    \-return \- ->    \-short\_description "Displays a simple message box" ->    \-description "This procedure allows displaying a configurable message box\." ->    \-args \{ ->       \{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\} ->       \{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\} ->       \{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\} ->       \{\-fg \-type color \-default black \-description "Message color"\} ->       \{\-bg \-type color \-optional \-description "Background color"\} ->       \{\-no\_border \-type none \-description "Use a splash window style \(no border\)"\} ->       \{\-log\_file \-type file \-optional \-description "Optional message log file"\} ->       \{text \-type string \-multiple \-description "Multiple text lines to display"\} ->    \} -> \} \{ ->    *puts "display message:"* ->    *foreach var \{mtype font level fg bg no\_border log\_file text\} \{* ->       *if \{\[info exists $var\]\} \{* ->          *puts " $var=\[set $var\]"* ->       *\}* ->    *\}* -> \} - -A call of procedure that has been declared in this way will first invoke the -TEPAM argument manager, before the procedure body is executed\. The argument -manager parses the provided arguments, validates them, completes them eventually -with some default values, and makes them finally available to the procedure body -as local variables\. In case an argument is missing or has a wrong type, the -argument manager generates an error message that explains the reason for the -error\. - -As the example above shows, the TEPAM command -__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ accepts subcommand -definitions as procedure name and allows defining much more information than -just the argument list inside the procedure header\. The procedure body on the -other hand is identical between a command declared with -__[proc](\.\./\.\./\.\./\.\./index\.md\#proc)__ and a command declared with -__[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__\. - -The procedure header allows defining in addition to the arguments some procedure -attributes, like a description, information concerning the return value, etc\. -This information is basically used for the automatic generation of comprehensive -help and usage texts\. - -A list of argument definition statements assigned to the *\-args* argument is -defining the procedure arguments\. Each argument definition statement starts with -the argument name, optionally followed by some argument attributes\. - -Three types of arguments can be defined: Unnamed arguments, named arguments and -flags\. The distinction between the named and unnamed arguments is made by the -first argument name character which is simply "\-" for named arguments\. A flag is -defined as named argument that has the type *none*\. - -Named and unnamed arguments are mandatory, unless they are declared with the -*\-optional* flag and unless they have a default value specified with the -*\-default* option\. Named arguments and the last unnamed argument can have the -attribute *\-multiple*, which means that they can be defined multiple times\. -The expected argument data type is specified with the *\-type* option\. TEPAM -defines a large set of standard data types which can easily be completed with -application specific data types\. - -The argument declaration order has only an importance for unnamed arguments that -are by default parsed after the named arguments \(Tcl style\)\. A variable allows -changing this behavior in a way that unnamed arguments are parsed first, before -the named arguments \(Tk style\)\. - -# PROCEDURE HELP - -The declared procedure can simply be called with the *\-help* option to get the -information about the usage of the procedure and its arguments: - -> __display message__ \-help ->   *\->* -> *NAME* ->       *display message \- Displays a simple message box* -> *SYNOPSYS* ->       *display message* ->             *\[\-mtype \] :* ->                *Message type, default: "Warning", choices: \{Info Warning Error\}* ->             *\[\-font \] :* ->                *Message text font, type: font, default: Arial 10 italic* ->             *\[\-level \] :* ->                *Message level, type: integer, range: 1\.\.10* ->             *\[\-fg \] :* ->                *Message color, type: color, default: black* ->             *\[\-bg \] :* ->                *Background color, type: color* ->             *\[\-no\_border \] :* ->                *Use a splash window style \(no border\)* ->             *\[\-log\_file \] :* ->                *Optional message log file, type: file* ->             * :* ->                *Multiple text lines to display, type: string* -> *DESCRIPTION* ->       *This procedure allows displaying a configurable message box\.* - -# PROCEDURE CALL - -The specified procedure can be called in many ways\. The following listing shows -some valid procedure calls: - -> __display message__ "The document hasn't yet been saved\!" -> *\-> display message:* ->      *mtype=Warning* ->      *font=Arial 10 italic* ->      *fg=black* ->      *no\_border=0* ->      *text=\{The document hasn't yet been saved\!\}* -> -> -> __display message__ \-fg red \-bg black "Please save first the document" -> *\-> display message:* ->      *mtype=Warning* ->      *font=Arial 10 italic* ->      *fg=red* ->      *bg=black* ->      *no\_border=0* ->      *text=\{Please save first the document\}* -> -> -> __display message__ \-mtype Error \-no\_border "Why is here no border?" -> *\-> display message:* ->      *mtype=Error* ->      *font=Arial 10 italic* ->      *fg=black* ->      *no\_border=1* ->      *text=\{Why is here no border?\}* -> -> -> __display message__ \-font \{Courier 12\} \-level 10 \\ ->    "Is there enough space?" "Reduce otherwise the font size\!" -> *\-> display message:* ->      *mtype=Warning* ->      *font=Courier 12* ->      *level=10* ->      *fg=black* ->      *no\_border=0* ->      *text=\{Is there enough space?\} \{Reduce otherwise the font size\!\}* - -The next lines show how wrong arguments are recognized\. The *text* argument -that is mandatory is missing in the first procedure call: - -> __display message__ \-font \{Courier 12\} ->   *\-> display message: Required argument is missing: text* - -Only known arguments are accepted: - -> __display message__ \-category warning Hello ->   *\-> display message: Argument '\-category' not known* - -Argument types are automatically checked and an error message is generated in -case the argument value has not the expected type: - -> __display message__ \-fg MyColor "Hello" ->   *\-> display message: Argument 'fg' requires type 'color'\. Provided value: 'MyColor'* - -Selection choices have to be respected \.\.\. - -> __display message__ \-mtype Fatal Hello ->   *\-> display message: Argument \(mtype\) has to be one of the following elements: Info, Warning, Error* - -\.\.\. as well as valid value ranges: - -> __display message__ \-level 12 Hello ->   *\-> display message: Argument \(level\) has to be between 1 and 10* - -# INTERACTIVE PROCEDURE CALLS - -The most intuitive way to call the procedure is using an form that allows -specifying all arguments interactively\. This form will automatically be -generated if the declared procedure is called with the *\-interactive* flag\. To -use this feature the Tk library has to be loaded\. - -> __display message__ \-interactive - -The generated form contains for each argument a data entry widget that is -adapted to the argument type\. Check buttons are used to specify flags, radio -boxes for tiny choice lists, disjoint list boxes for larger choice lists and -files, directories, fonts and colors can be selected with dedicated browsers\. - -After acknowledging the specified argument data via an OK button, the entered -data are first validated, before the provided arguments are transformed into -local variables and the procedure body is executed\. In case the entered data are -invalid, a message appears and the user can correct them until they are valid\. - -The procedure calls can optionally be logged in a variable\. This is for example -useful to get the command call lines of interactively called procedures\. - -# FLEXIBLE ARGUMENT DIALOG BOX - -The form generator that creates in the previous example the argument dialog box -for the interactive procedure call is also available for other purposes than for -the definition of procedure arguments\. If Tk has been loaded TEPAM provides and -argument dialog box that allows creating complex parameter definition forms in a -very efficient way\. - -The following example tries to illustrate the simplicity to create complex data -entry forms\. It creates an input mask that allows specifying a file to copy, a -destination folder as well as a checkbox that allows specifying if an eventual -existing file can be overwritten\. Comfortable browsers can be used to select -files and directories\. And finally, the form offers also the possibility to -accept and decline the selection\. Here is the code snippet that is doing all -this: - -> __[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\ ->    __\-existingfile__ \{\-label "Source file" \-variable SourceFile\} \\ ->    __\-existingdirectory__ \{\-label "Destination folder" \-variable DestDir\} \\ ->    __\-checkbutton__ \{\-label "Overwrite existing file" \-variable Overwrite\} - -The __argument\_dialogbox__ returns __ok__ if the entered data are -validated\. It will return __cancel__ if the data entry has been canceled\. -After the validation of the entered data, the __argument\_dialogbox__ defines -all the specified variables with the entered data inside the calling context\. - -An __argument\_dialogbox__ requires a pair of arguments for each variable -that it has to handle\. The first argument defines the entry widget type used to -select the variable's value and the second one is a lists of attributes related -to the variable and the entry widget\. - -Many entry widget types are available: Beside the simple generic entries, there -are different kinds of list and combo boxes available, browsers for existing and -new files and directories, check and radio boxes and buttons, as well as color -and font pickers\. If necessary, additional entry widgets can be defined\. - -The attribute list contains pairs of attribute names and attribute data\. The -primary attribute is *\-variable* used to specify the variable in the calling -context into which the entered data has to be stored\. Another often used -attribute is *\-label* that allows adding a label to the data entry widget\. -Other attributes are available that allow specifying default values, the -expected data types, valid data ranges, etc\. - -The next example of a more complex argument dialog box provides a good overview -about the different available entry widget types and parameter attributes\. The -example contains also some formatting instructions like *\-frame* and *\-sep* -which allows organizing the different entry widgets in frames and sections: - -> set ChoiceList \{"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"\} -> -> set Result \[__[tepam::argument\_dialogbox](tepam\_argument\_dialogbox\.md)__ \\ ->    __\-title__ "System configuration" \\ ->    __\-context__ test\_1 \\ ->    __\-frame__ \{\-label "Entries"\} \\ ->       __\-entry__ \{\-label Entry1 \-variable Entry1\} \\ ->       __\-entry__ \{\-label Entry2 \-variable Entry2 \-default "my default"\} \\ ->    __\-frame__ \{\-label "Listbox & combobox"\} \\ ->       __\-listbox__ \{\-label "Listbox, single selection" \-variable Listbox1 \\ ->                 \-choices \{1 2 3 4 5 6 7 8\} \-default 1 \-height 3\} \\ ->       __\-listbox__ \{\-label "Listbox, multiple selection" \-variable Listbox2 ->                 \-choicevariable ChoiceList \-default \{"Choice 2" "Choice 3"\} ->                 \-multiple\_selection 1 \-height 3\} \\ ->       __\-disjointlistbox__ \{\-label "Disjoined listbox" \-variable DisJntListbox ->                         \-choicevariable ChoiceList \\ ->                         \-default \{"Choice 3" "Choice 5"\} \-height 3\} \\ ->       __\-combobox__ \{\-label "Combobox" \-variable Combobox \\ ->                  \-choices \{1 2 3 4 5 6 7 8\} \-default 3\} \\ ->    __\-frame__ \{\-label "Checkbox, radiobox and checkbutton"\} \\ ->       __\-checkbox__ \{\-label Checkbox \-variable Checkbox ->                  \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\ ->                  \-default italic\} \\ ->       __\-radiobox__ \{\-label Radiobox \-variable Radiobox ->                  \-choices \{bold italic underline\} \-choicelabels \{Bold Italic Underline\} \\ ->                  \-default underline\} \\ ->       __\-checkbutton__ \{\-label CheckButton \-variable Checkbutton \-default 1\} \\ ->    __\-frame__ \{\-label "Files & directories"\} \\ ->       __\-existingfile__ \{\-label "Input file" \-variable InputFile\} \\ ->       __\-file__ \{\-label "Output file" \-variable OutputFile\} \\ ->       __\-sep__ \{\} \\ ->       __\-existingdirectory__ \{\-label "Input directory" \-variable InputDirectory\} \\ ->       __\-directory__ \{\-label "Output irectory" \-variable OutputDirectory\} \\ ->    __\-frame__ \{\-label "Colors and fonts"\} \\ ->       __\-color__ \{\-label "Background color" \-variable Color \-default red\} \\ ->       __\-sep__ \{\} \\ ->       __\-font__ \{\-label "Font" \-variable Font \-default \{Courier 12 italic\}\}\] - -The __argument\_dialogbox__ defines all the specified variables with the -entered data and returns __ok__ if the data have been validated via the Ok -button\. If the data entry is cancelled by activating the Cancel button, the -__argument\_dialogbox__ returns __cancel__\. - -> if \{$Result=="cancel"\} \{ ->    puts "Canceled" -> \} else \{ \# $Result=="ok" ->    puts "Arguments: " ->    foreach Var \{ ->       Entry1 Entry2 ->       Listbox1 Listbox2 DisJntListbox ->       Combobox Checkbox Radiobox Checkbutton ->       InputFile OutputFile InputDirectory OutputDirectory ->       Color Font ->    \} \{ ->       puts " $Var: '\[set $Var\]'" ->    \} -> \} -> *\-> Arguments:* ->    *Entry1: 'Hello, this is a trial'* ->    *Entry2: 'my default'* ->    *Listbox1: '1'* ->    *Listbox2: '\{Choice 2\} \{Choice 3\}'* ->    *DisJntListbox: '\{Choice 3\} \{Choice 5\}'* ->    *Combobox: '3'* ->    *Checkbox: 'italic'* ->    *Radiobox: 'underline'* ->    *Checkbutton: '1'* ->    *InputFile: 'c:\\tepam\\in\.txt'* ->    *OutputFile: 'c:\\tepam\\out\.txt'* ->    *InputDirectory: 'c:\\tepam\\input'* ->    *OutputDirectory: 'c:\\tepam\\output'* ->    *Color: 'red'* ->    *Font: 'Courier 12 italic'* - -# SEE ALSO - -[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md), -[tepam::procedure\(n\)](tepam\_procedure\.md) - -# KEYWORDS - -[argument integrity](\.\./\.\./\.\./\.\./index\.md\#argument\_integrity), [argument -validation](\.\./\.\./\.\./\.\./index\.md\#argument\_validation), -[arguments](\.\./\.\./\.\./\.\./index\.md\#arguments), [entry -mask](\.\./\.\./\.\./\.\./index\.md\#entry\_mask), [parameter entry -form](\.\./\.\./\.\./\.\./index\.md\#parameter\_entry\_form), -[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure), -[subcommand](\.\./\.\./\.\./\.\./index\.md\#subcommand) - -# CATEGORY - -Procedures, arguments, parameters, options - -# COPYRIGHT - -Copyright © 2009\-2013, Andreas Drollinger DELETED embedded/md/tcllib/files/modules/tepam/tepam_procedure.md Index: embedded/md/tcllib/files/modules/tepam/tepam_procedure.md ================================================================== --- embedded/md/tcllib/files/modules/tepam/tepam_procedure.md +++ embedded/md/tcllib/files/modules/tepam/tepam_procedure.md @@ -1,1321 +0,0 @@ - -[//000000001]: # (tepam::procedure \- Tcl's Enhanced Procedure and Argument Manager) -[//000000002]: # (Generated from file 'tepam\_procedure\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2013, Andreas Drollinger) -[//000000004]: # (tepam::procedure\(n\) 0\.5\.0 tcllib "Tcl's Enhanced Procedure and Argument Manager") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tepam::procedure \- TEPAM procedure, reference manual - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [TERMINOLOGY](#section2) - - - [PROCEDURE DECLARATION](#section3) - - - [Procedure Attributes](#subsection1) - - - [Argument Declaration](#subsection2) - - - [VARIABLES](#section4) - - - [ARGUMENT TYPES](#section5) - - - [Predefined Argument Types](#subsection3) - - - [Defining Application Specific Argument Types](#subsection4) - - - [PROCEDURE CALLS](#section6) - - - [Help](#subsection5) - - - [Interactive Procedure Call](#subsection6) - - - [Unnamed Arguments](#subsection7) - - - [Named Arguments](#subsection8) - - - [Unnamed Arguments First, Named Arguments Later \(Tk - Style\)](#subsection9) - - - [Named Arguments First, Unnamed Arguments Later \(Tcl - Style\)](#subsection10) - - - [Raw Argument List](#subsection11) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.3 -package require tepam ?0\.5? - -[__tepam::procedure__ *name* *attributes* *body*](#1) - -# DESCRIPTION - -This package provides an alternative way to declare Tcl procedures and to manage -its arguments\. There is a lot of benefit to declare a procedure with TEPAM -rather than with the Tcl standard command __proc__: TEPAM allows specifying -inside the procedure declaration all information that is required to generate -comprehensive documentations and help support\. The information is also used by -an automatically invoked argument checker that validates the provided procedure -arguments before the procedure body is executed\. Finally, a procedure can be -called interactively which will open a graphical form that allows specifying the -procedure arguments\. - -TEPAM simplifies also the handling of the different types of argument, like the -*named arguments* \(often also called *options*\) and the *unnamed -arguments*\. TEPAM supports the *named first, unnamed later* style \(typical -Tcl command style\) as well as also the *unnamed first, named later* style -\(typical Tk command style\)\. TEPAM takes care about default values for arguments, -optional arguments, multiple applicable arguments, etc\. and eliminates the need -to check the validity of the argument inside the procedure bodies\. - -An informal overview of all the TEPAM procedure declaration and calling features -as well as a short introduction into TEPAM is provided by *tepam\(n\)*\. - -# TERMINOLOGY - -The exact meaning of several terms that are used in this document will be -shortly explained to avoid any ambiguities and misunderstandings\. - - - *Subcommand* - - The usage of subcommands is heavily used in the Tcl language\. Several - commands are incorporated into a single main command and are selectable via - the first argument\. - - The __string__ command is an example of such a command that implements - for example subcommands to check a character string length, to compare - strings, to extract substrings, etc: - - > __string length__ *string* - > __string compare__ *string* *string* - > __string range__ *string* *first* *last* - > \.\.\. - - TEPAM provides a framework that allows implementing easily such subcommands - in form of Tcl procedures\. It allows not only defining a first level of - subcommands, but also a higher level of subcommands\. The __string__ - command class check could be implemented as independent sub\-sub\-commands of - the __string__ command: - - > __string is alnum__ *string* - > __string is integer__ *string* - > __string is double__ *string* - > \.\.\. - - - *Procedure attribute* - - TEPAM allows attaching to a declared procedure different kind of attributes\. - Some of these attributes are *just* used for documentation purposes, but - other attributes specify the way how the procedure has to be called\. Also - the procedure arguments are defined in form of a procedure attribute\. - - - *Argument* - - TEPAM uses the term *argument* for the parameters of a procedure\. - - The following example calls the subcommand __string compare__ with - several arguments: - - > __string compare__ *\-nocase \-length 3 "emphasized" "emphasised"* - - The following paragraphs discuss these different argument types\. - - - *Named argument* - - Some parameters, as *\-length 3* of the subcommand __string compare__ - have to be provided as pairs of argument names and argument values\. This - parameter type is often also called *option*\. - - TEPAM uses the term *named argument* for such options as well as for the - flags \(see next item\)\. - - - *Flag, switch* - - Another parameter type is the *flag* or the *switch*\. Flags are provided - simply by naming the flag leading with the '\-' character\. The *\-nocase* of - the previous __string compare__ example is such a flag\. - - *Flags* are considered by TEPAM like a special form of *named - arguments*\. - - - *Unnamed argument* - - For the other parameters, e\.g\. the ones for which the argument name has not - to be mentioned, TEPAM uses the term *unnamed argument*\. The previous - __string compare__ example uses for the two provided character strings - two *unnamed arguments*\. - - - *Argument attribute* - - TEPAM allows describing the purpose of each procedure argument with - *argument attributes*\. While some of them are just documenting the - attributes, most attributes are used by an argument manager to control and - validate the arguments that are provided during a procedure call\. Argument - attributes are used to specify default values, parameter classes \(integer, - xdigit, font, \.\.\.\), choice validation lists, value ranges, etc\. - - - *Named arguments first, unnamed arguments later* - - The __string compare__ command of the previous example requires that the - *named arguments* \(options, flags\) are provided first\. The two mandatory - \(unnamed\) arguments have to be provided as last argument\. - - > __string compare__ *\-nocase \-length 3 Water $Text* - - This is the usual Tcl style \(exceptions exist\) which is referred in the - TEPAM documentation as *named arguments first, unnamed arguments later - style*\. - - - *Unnamed arguments first, named arguments later* - - In contrast to most Tcl commands, Tk uses generally \(exceptions exist also - here\) a different calling style where the *unnamed arguments* have to be - provided first, before the *named arguments* have to be provided: - - > __pack__ *\.ent1 \.ent2 \-fill x \-expand yes \-side left* - - This style is referred in the TEPAM documentation as *unnamed arguments - first, named arguments later style*\. - -# PROCEDURE DECLARATION - -TEPAM allows declaring new Tcl procedures with the command -__tepam::procedure__ that has similar to the standard Tcl command -__proc__ also 3 arguments: - - - __tepam::procedure__ *name* *attributes* *body* - -The TEPAM procedure declaration syntax is demonstrated by the following example: - -> __tepam::procedure__ \{display message\} \{ ->    \-short\_description ->       "Displays a simple message box" ->    \-description ->       "This procedure allows displaying a configurable\\ ->        message box\. The default message type that is\\ ->        created is a warning, but also errors and info can\\ ->        be generated\. ->        The procedure accepts multiple text lines\." ->    \-example ->       \{display message \-mtype Warning "Save first your job"\} ->    \-args \{ ->       \{\-mtype \-choices \{Info Warning Error\} \\ ->               \-default Warning \-description "Message type"\} ->       \{text \-type string \-multiple \\ ->               \-description "Multiple text lines to display"\} ->    \} -> \} \{ ->    puts "Message type: $mtype" ->    puts "Message: $text" -> \} - -The 3 arguments of __procedure__ are: - - - *name* - - The procedure name can be used in very flexible ways\. Procedure names can - have namespace qualifiers\. By providing a two element name list as procedure - name, a subcommand of a procedure will be declared\. It is even possible to - declare sub\-sub\-commands of a procedure by providing name lists with three - elements\. - - Here are some valid procedure declarations using different procedure names - \(the attribute and body arguments are empty for simplicity\): - -> *\# Simple procedure name:* -> tepam::procedure __display\_message__ \{\} \{\} -> ** -> *\# Procedure declared in the main namespace:* -> tepam::procedure __::display\_message__ \{\} \{\} -> ** -> *\# Procedure in the namespace* __::ns__*:* -> tepam::procedure __::ns::display\_message__ \{\} \{\} -> ** -> *\# Declaration of the subcommand* __message__ *of the procedure* __display__*:* -> tepam::procedure __\{display message\}__ \{\} \{\} - - - *attributes* - - All procedure attributes are provided in form of an option list that - contains pairs of option names and option values\. The example above has as - procedure attribute a short and a normal description, but also the procedure - arguments are defined in form of a procedure attribute\. - - Most procedure attributes are providing information for documentation - purposes\. But some of them affect also the way how the procedure can be - called\. The section [Procedure Attributes](#subsection1) discusses in - detail the available procedure attributes\. - - The procedure arguments are defined in form of a special procedure - attribute\. Most of the information provided in the argument definition is - not just used for documentation purposes\. This information is in fact used - by the TEPAM argument manager to handle and validate the various forms of - arguments that are provided during the procedure calls\. The section - [Argument Declaration](#subsection2) discusses in detail all the - argument definition attributes\. - - - *body* - - This is the normal procedure body\. The declared arguments will be available - to the procedure body in form of variables\. - - The procedure body will only be executed if the provided set of arguments - could be validated by the TEPAM argument manager\. - -> tepam::procedure \{display\_message\} \{ ->    \-args \{ ->       \{\-__mtype__ \-default Warning \-choices \{Warning Error\}\} ->       \{__text__ \-type string\} ->    \} -> \} \{ ->    puts "Message type: __$mtype__" ->    puts "Message: __$text__" -> \} - -The commands __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ as well as -__argument\_dialogbox__ are exported from the namespace __tepam__\. To use -these commands without the __tepam::__ namespace prefix, it is sufficient to -import them into the main namespace: - -> __namespace import tepam::\*__ -> -> __[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure)__ \{display\_message\} \{ ->    \-args \{ ->       \.\.\. - -## Procedure Attributes - -The first group of attributes affect the behavior of the declared procedure: - - - \-named\_arguments\_first __0__|__1__ - - This attribute defines the calling style of a procedure\. TEPAM uses by - default the *named arguments first, unnamed arguments later* style \(Tcl\)\. - This default behavior can globally be changed by setting the variable - __tepam::named\_arguments\_first__ to __0__\. This global calling style - can be changed individually for a procedure with the - *\-named\_arguments\_first* attribute\. - - - \-auto\_argument\_name\_completion __0__|__1__ - - The declared procedures will by default automatically try to match - eventually abbreviated argument names to the defined arguments names\. This - default behavior can globally be changed by setting the variable - __tepam::auto\_argument\_name\_completion__ to __0__\. This global - setting of the automatic argument name completion can be changed - individually for a procedure with the *\-auto\_argument\_name\_completion* - procedure attribute\. - - - \-interactive\_display\_format __extended__|__short__ - - A procedure declared with the TEPAM __procedure__ command can always be - called with the __\-interactive__ option\. By doing so, a graphical form - will be generated that allows specifying all procedure argument values\. - There are two display modes for these interactive forms\. While the - *extended* mode is more adapted for small procedure argument sets, the - __short__ form is more adequate for huge procedure argument sets\. - - The choice to use short or extended forms can be globally configured via the - variable __tepam::interactive\_display\_format__\. This global setting can - then be changed individually for a procedure with the - *\-interactive\_display\_format* procedure attribute\. - - - \-args *list* - - The procedure arguments are declared via the *\-args* attribute\. An - argument is defined via a list having as first element the argument name, - followed by eventual argument attributes\. All these argument definition - lists are packaged themselves into a global list that is assigned to the - *\-args* attribute\. - - The argument definition syntax will be described more in detail in the - following sub section\. - -The next attributes allow specifying custom argument checks as well as custom -error messages in case these checks are failing: - - - \-validatecommand *script* - - Custom argument validations can be performed via specific validation - commands that are defined with the *\-validatecommand* attribute\. - - Validation command declaration example: - -> tepam::procedure \{display\_message\} \{ ->    \-args \{ ->       \{text \-type string \-description "Message text"\} \} ->    __\-validatecommand \{IllegalWordDetector $text\}__ -> \} \{ -> \} - - The validation command is executed in the context of the declared procedure - body\. The different argument values are accessed via the argument names\. - Note there is also an argument attribute *\-validatecommand* that allows - declaring custom checks for specific arguments\. - - The attribute *\-validatecommand* can be repeated to declare multiple - custom checks\. - - - \-validatecommand\_error\_text *string* - - This attribute allows overriding the default error message for a custom - argument validation \(defined by *\-validatecommand*\)\. Also this attribute - can be repeated in case multiple argument checks are declared\. - -The following attribute allows controlling the logging settings for an -individual procedure: - - - \-command\_log __0__|__1__|__"interactive"__ - - This argument configures the logging of the procedure calls into the list - variable __tepam::ProcedureCallLogList__\. The default configuration - defined by the variable __tepam::command\_log__ will be used if this - argument is not defined in a procedure declaration\. - - Setting this argument to __0__ will disable any procedure call loggings, - setting it to __1__ will log any procedure calls and setting it to - __interactive__ will log just the procedures that are called - interactively \(procedures called with the __\-interactive__ flag\)\. - -The next group of procedure attributes is just used for the purpose of -documentation and help text generation: - - - \-category *string* - - A category can be assigned to a procedure for documentation purposes\. Any - string is accepted as category\. - - - \-short\_description *string* - - The short description of a procedure is used in the documentation summary of - a generated procedure list as well as in the NAME section of a generated - procedure manual page\. - - - \-description *string* - - The \(full\) description assigned to a procedure is used to create user manual - and help pages\. - - - \-return *string* - - The *\-return* attribute allows defining the expected return value of a - procedure \(used for documentation purposes\)\. - - - \-example *string* - - A help text or manual page of a procedure can be enriched with eventual - examples, using the *\-example* attribute\. - -## Argument Declaration - -The following example shows the structure that is used for the argument -definitions in the context of a procedure declaration: - -> tepam::procedure \{display\_message\} \{ ->    \-args __\{__ ->       __\{\-mtype \-default Warning \-choices \{Info Warning Error\} \-description "Message type"\}__ ->       __\{\-font \-type font \-default \{Arial 10 italic\} \-description "Message text font"\}__ ->       __\{\-level \-type integer \-optional \-range \{1 10\} \-description "Message level"\}__ ->       __\{\-fg \-type color \-optional \-description "Message color"\}__ ->       __\{\-log\_file \-type file \-optional \-description "Optional message log file"\}__ ->       __\{text \-type string \-multiple \-description "Multiple text lines to display"\}__ ->    __\}__ -> -> \} \{ -> \} - -Each of the procedure arguments is declared with a list that has as first -element the argument name, followed by eventual attributes\. The argument -definition syntax can be formalized in the following way: - -> tepam::procedure \{ ->    \-args __\{__ ->       __\{ \.\.\.\}__ ->       __\{ \.\.\.\}__ ->       __\.\.\.__ ->    __\}__ -> -> \} - -The argument names and attributes have to be used in the following way: - - - Argument name \(*>*\) - - The provided argument name specifies whether the argument is an *unnamed - argument* or a *named argument*\. In addition to this, an argument name - can also be blank to indicate an argument comment, or it can start with \# to - indicate a section comment\. - - * *""* - - This is the simplest form of an argument name: An argument whose name is - not starting with '\-' is an *unnamed argument*\. The parameter provided - during a procedure call will be assigned to a variable with the name - **\. - -> tepam::procedure \{print\_string\} \{ ->    \-args \{ ->       \{__[text](\.\./\.\./\.\./\.\./index\.md\#text)__ \-type string \-description "This is an unnamed argument"\} ->    \} -> \} \{ ->    puts __$text__ -> \} -> -> print\_string __"Hello"__ ->  *\-> Hello* - - * *"\-"* - - An argument whose name starts with '\-' is a *named argument* \(also - called *option*\)\. The parameter provided during a procedure call will - be assigned to a variable with the name ** \(not *\-*\)\. - -> tepam::procedure \{print\_string\} \{ ->    \-args \{ ->       \{__\-text__ \-type string \-description "This is a named argument"\} ->    \} -> \} \{ ->    puts __$text__ -> \} -> -> print\_string __\-text "Hello"__ ->  *\-> Hello* - - * *"\-\-"* - - This flag allows clearly specifying the end of the named arguments and - the beginning of the unnamed arguments, in case the *named arguments - first, unnamed arguments later style \(Tcl\)* has been selected\. - - If the *unnamed arguments first, named arguments later style \(Tk\)* - style is selected, this flag is ignored if the unnamed arguments have - already been parsed\. Otherwise it will be assigned to the corresponding - unnamed argument\. - - * *"\-"* or *""* - - A blank argument name \(either '\-' or *''*\) starts a comment for the - following arguments\. - -> tepam::procedure \{print\_time\} \{ ->    \-interactive\_display\_format short ->    \-args \{ ->       \{hours \-type integer \-description "Hour"\} ->       \{minutes \-type integer \-description "Minute"\} -> ->       __\{\- The following arguments are optional:\}__ ->       \{seconds \-type integer \-default 0 \-description "Seconds"\} ->       \{milliseconds \-type integer \-default 0 \-description "Milliseconds"\} ->    \} -> \} \{ ->    puts "$\{hour\}h$\{minutes\}:\[expr $seconds\+0\.001\*$milliseconds\]" -> \} - - Argument comments are basically used in the graphical argument - definition forms that are created if a procedure is called - interactively\. - - * *"\#\*"* - - An argument definition list that starts with '\#' is considered as a - section comment\. The argument definition list will be trimmed from the - '\#' characters and the remaining string will be used as section comment\. - - Section comments can be used to structure visually the argument - definition code\. Section comments are also used to structure the - generated help texts and the interactive argument definition forms\. - -> tepam::procedure \{complex\_multiply\} \{ ->    \-description "This function perform a complex multiplication" ->    \-args \{ ->       __\{\#\#\#\# First complex number \#\#\#\#\}__ ->       \{\-r0 \-type double \-description "First number real part"\} ->       \{\-i0 \-type double \-description "First number imaginary part"\} -> ->       __\{\#\#\#\# Second complex number \#\#\#\#\}__ ->       \{\-r1 \-type double \-description "Second number real part"\} ->       \{\-i1 \-type double \-description "Second number imaginary part"\} ->    \} -> \} \{ ->    return \[expr $r0\*$r1 \- $i0\*$i1\] -> \} - - - Argument attributes \(*> >*\) - - The following argument attributes are supported: - - * \-description *string* - - The description argument attribute is used for documentation purpose\. - Interactive argument definition forms use this attribute to provide - explanations for an argument\. - - * \-type *type* - - The type argument attribute allows assigning the argument either to a - predefined data type, or to an application specific data type\. The - argument values that are provided during a procedure call are - automatically checked with respect to the defined argument type\. - - The section [ARGUMENT TYPES](#section5) provides a list of - predefined data types and explains how application specific types can be - specified\. - - The argument type *none* has a special meaning\. An argument that has - the type *none* is handled as a *flag*\. A flag is always optional - and its related variable contains the logical value __1__ if the - flag has been defined during the procedure call, or otherwise __0__\. - - * \-default *value* - - Eventual default values can be defined with the \-default argument - attribute\. Arguments with default values are automatically optional - arguments\. - - * \-optional|\-mandatory - - Arguments are by default mandatory, unless a default value is defined\. - The flag *\-optional* transforms an argument into an optional argument\. - - In case an optional argument is not defined during a procedure call, the - corresponding variable will not be defined\. The flag *\-mandatory* is - the opposite to *\-optional*\. This flag exists only for completion - reason, since an argument is anyway mandatory by default\. - - * \-multiple - - Arguments that have the *\-multiple* attribute can be defined multiple - times during a procedure call\. The values that are provided during a - procedure call for such an argument are stored in a list variable\. This - is even the case if such an argument is only defined once during a - procedure call\. - - The *\-multiple* attribute can be attributed to unnamed arguments and - to named arguments\. The pair of argument name/argument value has to be - repeated for each provided value in case of a named argument\. In case - the argument with the *\-multiple* attribute is an unnamed argument, - this one has to be the absolute last one of all unnamed arguments\. - - * \-choices *list* - - A possible set of valid argument values can be attributed to an argument - via the *\-choices* attribute\. The argument value provided during a - procedure call will be checked against the provided choice values\. - - * \-choicelabels *list* - - An eventual short description can be attributed to each choice option - with the *\-choicelabels* attribute\. These descriptions will be used in - the generated help texts and as radio and check box labels for the - interactive calls\. - - The *\-choicelabels* attribute is optional, but if it is defined, its - list needs to have the identical size as the *\-choices* argument list\. - - * \-range *\{double double\}* - - Another argument constraint can be defined with the *\-range* - attribute\. The valid range is defined with a list containing the minimum - valid value and a maximum valid value\. The *\-range* attribute has to - be used only for numerical arguments, like integers and doubles\. - - * \-validatecommand *script* - - Custom argument value validations can be performed via specific - validation commands that are defined with the *\-validatecommand* - attribute\. The provided validation command can be a complete script in - which the pattern *%P* is replaced by the argument value that has to - be validated\. - - Validation command declaration example: - -> tepam::procedure \{display\_message\} \{ ->    \-args \{ ->       \{text \-type string \-description "Message text" \\ ->             __\-validatecommand \{IllegalWordDetector %P\}__\} -> \} \{ -> \} - - While the purpose of this custom argument validation attribute is the - validation of a specific argument, there is also a global attribute - *\-validatecommand* that allows performing validation that involves - multiple arguments\. - - * \-validatecommand\_error\_text *string* - - This attribute allows overriding the default error message for a custom - argument validation \(defined by *\-validatecommand*\)\. - - * \-widget *string* - - The widgets that allow defining the different arguments in case of an - interactive procedure call are normally selected automatically in - function of the argument type\. The *\-widget* attribute allows - specifying explicitly a certain widget type for an argument\. - - * \-auxargs *list* - - In case a procedure is called interactively, additional argument - attributes can be provided to the interactive argument definition form - via the *\-auxargs* attribute that is itself a list of attribute - name/attribute value pairs: - - -auxargs {- \ - - - ... - } - - For example, if a procedure takes as argument a file name it may be - beneficial to specify the required file type for the interactive - argument definition form\. This information can be provided via the - *\-auxargs* attribute to the argument definition form: - -> tepam::procedure LoadPicture \{ ->    \-args \{ ->       \{FileName \-type existingfile \-description "Picture file" \\ ->                  __\-auxargs \{\-filetypes \{\{"GIF" \{\*\.gif\}\} \{"JPG" \{\*\.jpg\}\} \}\}__\} ->    \} -> \} \{ -> \} - - * \-auxargs\_commands *script* - - If the auxiliary argument attributes are not static but have to be - dynamically adaptable, the *\-auxargs\_commands* allows defining them - via commands that are executed during a procedure call\. A list of pairs - of auxiliary attribute names and commands has to be provided to the - *\-auxargs\_commands* attribute\. The provided commands are executed in - the context of the calling procedure\. - - -auxargs_commands {- \ - - - ... - } - -# VARIABLES - -Several variables defined inside the __::tepam__ namespace impact the mode -of operation of the procedures that have been declared with the TEPAM -__procedure__ command\. - - - __named\_arguments\_first__ - - This variable defines the general calling style of the procedures\. It is by - default set to __1__ which selects the *named arguments first, unnamed - arguments later* style \(Tcl style\)\. - - By setting this variable to __0__, the *named arguments first, unnamed - arguments later* style is globally selected \(Tk style\): - - set tepam::named_arguments_first 0 - - While this variable defines the general calling style, the procedure - attribute *\-named\_arguments\_first* can adapt this style individually for - each declared procedure\. - - - __auto\_argument\_name\_completion__ - - This variable controls the general automatic argument name matching mode\. By - default it is set to __1__, meaning that the called procedures are - trying to match eventually abbreviated argument names with the declared - argument names\. - - By setting this variable to __0__ the automatic argument name matching - mode is disabled: - - set tepam::auto_argument_name_completion 0 - - While this variable defines the general matching mode, the procedure - attribute *\-auto\_argument\_name\_completion* can adapt this mode - individually for each declared procedure\. - - - __interactive\_display\_format__ - - A procedure declared via the TEPAM __procedure__ command can always be - called with the __\-interactive__ switch\. By doing so, a graphical form - will be generated that allows entering interactively all procedure - arguments\. - - There are two display modes for these interactive forms\. The *extended* - mode which is the default mode is more adapted for small procedure argument - sets\. The __short__ form is more adequate for huge procedure argument - sets: - - set tepam::interactive_display_format "short" - - The choice to use short or extended forms can be globally configured via the - variable __interactive\_display\_format__\. This global setting can be - changed individually for a procedure with the procedure attribute - *\-interactive\_display\_format*\. - - - __help\_line\_length__ - - The maximum line length used by the procedure help text generator can be - specified with this variable\. The default length which is set to 80 - \(characters\) can easily be adapted to the need of an application: - - set tepam::help_line_length 120 - - Since this variable is applied directly during the help text generation, its - value can continuously be adapted to the current need\. - - - __command\_log__ - - Procedure calls can be logged inside the list variable - __tepam::ProcedureCallLogList__\. The variable __tepam::command\_log__ - controls the default logging settings for any procedures\. The following - configurations are supported: - - * *0*: Disables any procedure call loggings - - * *1*: Enables any procedure call loggings - - * *"interactive"*: Will log any procedures called interactively \(e\.g\. - procedures called with the \-interactive flag\)\. This is the default - configuration\. - - This default logging configuration can be changed individually for each - procedure with the *\-command\_log* attribute\. - -# ARGUMENT TYPES - -TEPAM provides a comprehensive set of procedure argument types\. They can easily -be completed with application specific types if necessary\. - -## Predefined Argument Types - -To remember, a type can be assigned to each specified procedure argument: - -> tepam::procedure \{warning\} \{ ->    \-args \{ ->       \{\-font __\-type font__ \-default \{Arial 10 italic\}\} ->       \{\-severity\_level __\-type integer__ \-optional \-range \{1 10\}\} ->       \{\-fg __\-type color__ \-optional \-description "Message color"\} ->       \{text __\-type string__ \-multiple \-description "Multiple text lines to display"\} ->    \} -> \} \{ ->    \.\.\. -> \} - -There are some *special purpose types* that are building the first category of -predefined argument types: - - - __none__ A *flag*, also called *switch*, is defined as a named - argument that has the type __none__\. Flags are always optional and the - default value of the assigned variable is set to __0__\. In contrast to - the \(normal\) named arguments, no argument value has to be provided to a - flag\. - -> tepam::procedure flag\_test \{ ->    \-args \{ ->       __\{\-flag \-type none \-description "This is a flag"\}__ ->    \} -> \} \{ ->    puts __$flag__ -> \} -> -> flag\_test -> *\-> 0* -> -> flag\_test \-flag -> *\-> 1* - - Since no argument value has to be provided to a flag, also no data check is - performed for this argument type\. - - - __string__ __String__ is a generic argument data type\. Any data - string can be provided to a string type argument and no data type checks are - therefore performed\. The string type allows defining single line strings - during the interactive procedure calls\. - - - __text__ __Text__ is identical to __string__ with the only - difference that it allows entering multi line strings during interactive - procedure calls\. - - - __\{\}__ A __blank__ argument type signifies an undefined argument - type\. This is the default argument type that will be used if no type has - been explicitly specified\. An argument that has a __blank__ type behaves - identically than an argument that has a __string__ type, e\.g\. no - argument data checks are performed\. The only difference is that the data - type __string__ is mentioned in the generated help documentation, while - this is not the case for the __blank__ type\. - -Several *numerical types* are defined by TEPAM\. The type validation procedures -are using the __string is \-strict__ commands to check the validity of -the provided arguments, which assures that no empty strings are accepted as -argument value\. The type validation expression for the numerical types and the -argument types to which this expression is applied are: - -> string is ____ \-strict ** - - - *boolean* - - - *integer* - - - *double* - -Empty strings are accepted as argument value for all the alpha numeric argument -types\. The argument types that are falling into this category and validation -expression used for them are: - -> string is ** ** - - - *alnum* - - - *alpha* - - - *ascii* - - - *control* - - - *digit* - - - *graph* - - - *lower* - - - *print* - - - *punct* - - - *space* - - - *upper* - - - *wordchar* - - - *xdigit* - -In addition to the data types checked with the __string is __ -commands, TEPAM specifies some other useful data types: - - - *char* Each string that has a length of 1 character meets the - *character* type\. The type check is made with the following expression: - -> expr \[string length **\]==1 - - - *color* Any character strings that are accepted by Tk as a color are - considered as valid color argument\. Please note that the Tk package has to - be loaded to use the type *color*\. TEPAM is using the following command to - validate the color type: - -> expr \!\[catch \{winfo rgb \. **\}\] - - - *font* Any character strings that are accepted by Tk as a font are - considered as valid font argument\. Please note that the Tk package has to be - loaded to use the *font* type\. TEPAM is using the following command to - validate the color type: - - expr ![catch {font measure ""}] - - - *file* Any strings that are not containing one of the following characters - are considered as valid file names: \* ? " < >\. It is not necessary that the - file and its containing directory exist\. Zero\-length strings are not - considered as valid file names\. - - The following expression is used to validate the file names: - - expr [string length ]>0 && ![regexp {[\"*?<>:]} ] - - - *existingfile* The argument is valid if it matches with an existing file\. - The following check is performed to validate the arguments of this type: - - file exists - - - *directory* The directory argument is validated exactly in the same way as - the file arguments\. - - - *existingdirectory* The argument is valid if it matches with an existing - directory\. The following check is performed to validate the arguments of - this type: - - file isdirectory - -## Defining Application Specific Argument Types - -To add support for a new application specific argument type it is just necessary -to add into the namespace __tepam__ a validation function -__Validation\(\)__\. This function requires one argument\. It has to -returns __1__ if the provided argument matches with the relevant data type\. -The function has to return otherwise __0__\. - -The validation command section of the "tepam\.tcl" package provides sufficient -examples of validation functions, since it implements the ones for the standard -TEPAM types\. - -The following additional code snippet shows the validation function for a custom -argument type that requires values that have a character string length of -exactly 2: - - proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}} - -# PROCEDURE CALLS - -## Help - -Each procedure can be called with the *\-help* flag\. The procedure will then -print a generated help text to *stdout* and will then return without -performing any additional actions\. - -Taking the first procedure declared in [PROCEDURE CALLS](#section6), the -help request and the printed help text would be: - -> __display message \-help__ -> *\->* -> *NAME* ->       *display message \- Displays a simple message box* -> *SYNOPSIS* ->       *display message* ->             *\[\-mtype \]* ->                *Message type, default: "Warning", choices: \{Info, Warning, Error\}* ->             ** ->                *Multiple text lines to display, type: string* -> *DESCRIPTION* ->       *This procedure allows displaying a configurable message box\. The default* ->       *message type that is created is a warning, but also errors and info can* ->       *be generated\.* ->       *The procedure accepts multiple text lines\.* -> *EXAMPLE* ->       *display message \-mtype Warning "Save first your job"* - -The argument manager is checking if the last provided argument is *\-help* and -generates the requested help message if this is the case\. So, also the following -example will print the help message: - -> __display message \-mtype Info "It is 7:00" \-help__ - -On the other hand, the following call will result in an error: - -> __display message \-help \-mtype Info "It is 7:00"__ -> *\->* -> *display message: Argument '\-help' not known* - -## Interactive Procedure Call - -If Tk has been loaded a procedure can be called with the *\-interactive* flag -to open a graphical form that allows specifying interactively all procedure -arguments\. The following example assures that the Tk library is loaded and shows -the command line to call interactively the procedure declared in [PROCEDURE -CALLS](#section6): - -> package require Tk -> __display message \-interactive__ - -Also the *\-interactive* flag has to be placed at the last argument position as -this is also required for the *\-help* flag\. Arguments defined before the -*\-interactive* flag will be ignored\. The following example is therefore also a -valid interactive procedure call: - -> __display message__ \-mtype Info "It is 7:00" __\-interactive__ - -## Unnamed Arguments - -Unnamed arguments are typically provided to the called procedure as simple -parameters\. This procedure calling form requires that the provided arguments are -strictly following the order of the specified arguments\. Several parameters can -be assigned to the last argument if this one has the *\-multiple* attribute\. -So, the following declared procedure \.\.\. - - tepam::procedure {display_message} { - -args { - {mtype -choices {Info Warning Error}} - {text -type string -multiple} - } - } { - puts "$mtype: [join $text]" - } - -\.\.\. can for example be called in the following ways: - -> __display\_message Info "It is PM 7:00\."__ -> *\-> Info: It is PM 7:00\.* -> -> __display\_message Info "It is PM 7:00\." "You should go home\."__ -> *\-> Info: It is PM 7:00\. You should go home\.* - -The nice thing is that unnamed arguments can also be called as named arguments, -which can be handy, for example if the exact specified argument order is not -known to a user: - -> __display\_message \-mtype Info \-text "It is PM 7:00\."__ -> *\-> Info: It is PM 7:00\.* -> -> __display\_message \-text "It is PM 7:00\." \-mtype Info__ -> *\-> Info: It is PM 7:00\.* -> -> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ -> *\-> Info: It is PM 7:00\. You should go home\.* -> -> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ -> *\-> Info: It is PM 7:00\. You should go home\.* - -## Named Arguments - -Named arguments have to be provided to a procedure in form of a parameter pairs -composed by the argument names and the argument values\. The order how they are -provided during a procedure call is irrelevant and has not to match with the -argument specification order\. - -The following declared procedure \.\.\. - - tepam::procedure {display_message} { - -args { - {-mtype -choices {Info Warning Error}} - {-text -type string -multiple} - } - } { - puts "$mtype: [join $text]" - } - -\.\.\. can be called in the following ways: - -> __display\_message \-mtype Info \-text "It is PM 7:00\."__ -> *\-> Info: It is PM 7:00\.* -> -> __display\_message \-text "It is PM 7:00\." \-mtype Info__ -> *\-> Info: It is PM 7:00\.* -> -> __display\_message \-mtype Info \-text "It is PM 7:00\." \-text "You should go home\."__ -> *\-> Info: It is PM 7:00\. You should go home\.* -> -> __display\_message \-text "It is PM 7:00\." \-text "You should go home\." \-mtype Info__ -> *\-> Info: It is PM 7:00\. You should go home\.* - -Also named arguments that have not the *\-multiple* attribute can be provided -multiple times\. Only the last provided argument will be retained in such a case: - -> __display\_message \-mtype Info \-text "It is PM 7:00\." \-mtype Warning__ -> *\-> Warning: It is PM 7:00\.* - -## Unnamed Arguments First, Named Arguments Later \(Tk Style\) - -A procedure that has been defined while the variable -__tepam::named\_arguments\_first__ was set to 1, or with the procedure -attribute *\-named\_arguments\_first* set to 1 has to be called in the Tcl style\. -The following procedure declaration will be used in this section to illustrate -the meaning of this calling style: - -> __set tepam::named\_arguments\_first 1__ -> tepam::procedure my\_proc \{ ->    \-args \{ ->       \{\-n1 \-default ""\} ->       \{\-n2 \-default ""\} ->       \{u1 \-default ""\} ->       \{u2 \-default ""\} ->    \} -> \} \{ ->    puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" -> \} - -The unnamed arguments are placed at the end of procedure call, after the named -arguments: - -> my\_proc __\-n1 N1 \-n2 N2 U1 U2__ -> *\-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'* - -The argument parser considers the first argument that doesn't start with the '\-' -character as well as all following arguments as unnamed argument: - -> my\_proc __U1 U2__ -> *\-> n1:'', n2:'', u1:'U1', u2:'U2'* - -Named arguments can be defined multiple times\. If the named argument has the -*\-multiply* attribute, all argument values will be collected in a list\. -Otherwise, only the last provided attribute value will be retained: - -> my\_proc __\-n1 N1 \-n2 N2 \-n1 M1 U1 U2__ -> *\-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'* - -The name of the first unnamed argument has therefore not to start with the '\-' -character\. The unnamed argument is otherwise considered as name of another named -argument\. This is especially important if the first unnamed argument is given by -a variable that can contain any character strings: - -> my\_proc __\-n1 N1 \-n2 N2 "\->" "<\-"__ -> *\-> my\_proc: Argument '\->' not known* -> -> set U1 "\->" -> my\_proc __\-n1 N1 \-n2 N2 $U1 U2__ -> my\_proc: Argument '\->' not known - -The '\-\-' flag allows separating unambiguously the unnamed arguments from the -named arguments\. All data after the '\-\-' flag will be considered as unnamed -argument: - -> my\_proc __\-n1 N1 \-n2 N2 \-\- "\->" "<\-"__ -> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* -> -> set U1 "\->" -> my\_proc __\-n1 N1 \-n2 N2 \-\- $U1 U2__ -> *\-> n1:'N1', n2:'N2', u1:'\->', u2:'<\-'* - -## Named Arguments First, Unnamed Arguments Later \(Tcl Style\) - -The Tk calling style will be chosen if a procedure is defined while the variable -__tepam::named\_arguments\_first__ is set to 0, or if the procedure attribute -*\-named\_arguments\_first* has been set to 0\. The following procedure will be -used in this section to illustrate this calling style: - -> __set tepam::named\_arguments\_first 0__ -> tepam::procedure my\_proc \{ ->    \-args \{ ->       \{\-n1 \-default ""\} ->       \{\-n2 \-default ""\} ->       \{u1\} ->       \{u2 \-default "" \-multiple\} ->    \} -> \} \{ ->    puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'" -> \} - -The unnamed arguments have to be provided first in this case\. The named -arguments are provided afterwards: - -> my\_proc __U1 U2 \-n1 N1 \-n2 N2__ -> *\-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'* - -The argument parser will assign to each defined unnamed argument a value before -it switches to read the named arguments\. This default behavior changes a bit if -there are unnamed arguments that are optional or that can take multiple values\. - -An argument value will only be assigned to an unnamed argument that is optional -\(that has either the *\-optional* attribute or that has a default value\), if -the value is not beginning with the '\-' character or if no named arguments are -defined\. The value that starts with '\-' is otherwise considered as the name of a -named argument\. - -Argument values are assigned to an argument that has the *\-multiple* attribute -as long as the parameter value doesn't starts with the '\-' character\. - -Values that start with the '\-' character can therefore not be assigned to -optional unnamed arguments, which restricts the usage of the Tcl procedure -calling style\. The Tk style may be preferable in some cases, since it allows -separating unambiguously the named arguments from the unnamed ones with the '\-\-' -flag\. - -Let's explore in a bit less theoretically the ways how the previously defined -procedure can be called: The first example calls the procedure without any -parameters, which leads to an error since *u1* is a mandatory argument: - -> my\_proc -> *\-> my\_proc: Required argument is missing: u1* - -The procedure call is valid if one parameter is provided for *u1*: - -> my\_proc __U1__ -> *\-> n1:'', n2:'', u1:'U1', u2:''* - -If more parameters are provided that are not starting with the '\-' character, -they will be attributed to the unnamed arguments\. *U2* will receive 3 of these -parameters, since it accepts multiple values: - -> my\_proc __U1 U2 U3 U4__ -> *\-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'* - -As soon as one parameter starts with '\-' and all unnamed arguments have been -assigned, the argument manager tries to interpret the parameter as name of a -named argument\. The procedure call will fail if a value beginning with '\-' is -assigned to an unnamed argument: - -> my\_proc __U1 U2 U3 U4 \-U5__ -> *\-> my\_proc: Argument '\-U5' not known* - -The attribution of a parameter to a named argument will fail if there are -undefined unnamed \(non optional\) arguments\. The name specification will in this -case simply be considered as a parameter value that is attributed to the -*next* unnamed argument\. This was certainly not the intention in the following -example: - -> my\_proc __\-n1 N1__ -> *\-> n1:'', n2:'', u1:'\-n1', u2:'N1'* - -The situation is completely different if values have already been assigned to -all mandatory unnamed arguments\. A parameter beginning with the '\-' character -will in this case be considered as a name identifier for a named argument: - -> my\_proc __U1 \-n1 N1__ -> *\-> n1:'N1', n2:'', u1:'U1', u2:''* - -No unnamed arguments are allowed behind the named arguments: - -> my\_proc __U1 \-n1 N1 U2__ -> *\-> my\_proc: Argument 'U2' is not an option* - -The '\-\-' flag has no special meaning if not all mandatory arguments have got -assigned a value\. This flag will simply be attributed to one of the unnamed -arguments: - -> my\_proc __\-\- \-n1 N1__ -> *\-> n1:'N1', n2:'', u1:'\-\-', u2:''* - -But the '\-\-' flag is simply ignored if the argument parser has started to handle -the named arguments: - -> my\_proc __U1 \-\- \-n1 N1__ -> *\-> n1:'N1', n2:'', u1:'U1', u2:''* -> -> my\_proc __U1 \-n1 N1 \-\- \-n2 N2__ -> *\-> n1:'N1', n2:'N2', u1:'U1', u2:''* - -## Raw Argument List - -It may be necessary sometimes that the procedure body is able to access the -entire list of arguments provided during a procedure call\. This can happen via -the __args__ variable that contains always the unprocessed argument list: - -> tepam::procedure \{display\_message\} \{ ->    \-args \{ ->       \{\-mtype \-choices \{Warning Error\} \-default Warning\} ->       \{text \-type string \-multiple\} -> ->    \} -> \} \{ ->    puts "args: __$args__" -> \} -> display\_message \-mtype Warning "It is 7:00" -> *\-> args: \-mtype Warning \{It is 7:00\}* - -# SEE ALSO - -[tepam\(n\)](tepam\_introduction\.md), -[tepam::argument\_dialogbox\(n\)](tepam\_argument\_dialogbox\.md) - -# KEYWORDS - -[argument integrity](\.\./\.\./\.\./\.\./index\.md\#argument\_integrity), [argument -validation](\.\./\.\./\.\./\.\./index\.md\#argument\_validation), -[arguments](\.\./\.\./\.\./\.\./index\.md\#arguments), -[procedure](\.\./\.\./\.\./\.\./index\.md\#procedure), -[subcommand](\.\./\.\./\.\./\.\./index\.md\#subcommand) - -# CATEGORY - -Procedures, arguments, parameters, options - -# COPYRIGHT - -Copyright © 2009\-2013, Andreas Drollinger DELETED embedded/md/tcllib/files/modules/term/ansi_cattr.md Index: embedded/md/tcllib/files/modules/term/ansi_cattr.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_cattr.md +++ embedded/md/tcllib/files/modules/term/ansi_cattr.md @@ -1,275 +0,0 @@ - -[//000000001]: # (term::ansi::code::attr \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_cattr\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::ansi::code::attr\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::code::attr \- ANSI attribute sequences - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Introspection](#subsection1) - - - [Attributes](#subsection2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::ansi::code ?0\.1? -package require term::ansi::code::attr ?0\.1? - -[__::term::ansi::code::attr::names__](#1) -[__::term::ansi::code::attr::import__ ?*ns*? ?*arg*\.\.\.?](#2) -[__::term::ansi::code::attr::fgblack__](#3) -[__::term::ansi::code::attr::fgred__](#4) -[__::term::ansi::code::attr::fggreen__](#5) -[__::term::ansi::code::attr::fgyellow__](#6) -[__::term::ansi::code::attr::fgblue__](#7) -[__::term::ansi::code::attr::fgmagenta__](#8) -[__::term::ansi::code::attr::fgcyan__](#9) -[__::term::ansi::code::attr::fgwhite__](#10) -[__::term::ansi::code::attr::fgdefault__](#11) -[__::term::ansi::code::attr::bgblack__](#12) -[__::term::ansi::code::attr::bgred__](#13) -[__::term::ansi::code::attr::bggreen__](#14) -[__::term::ansi::code::attr::bgyellow__](#15) -[__::term::ansi::code::attr::bgblue__](#16) -[__::term::ansi::code::attr::bgmagenta__](#17) -[__::term::ansi::code::attr::bgcyan__](#18) -[__::term::ansi::code::attr::bgwhite__](#19) -[__::term::ansi::code::attr::bgdefault__](#20) -[__::term::ansi::code::attr::bold__](#21) -[__::term::ansi::code::attr::dim__](#22) -[__::term::ansi::code::attr::italic__](#23) -[__::term::ansi::code::attr::underline__](#24) -[__::term::ansi::code::attr::blink__](#25) -[__::term::ansi::code::attr::revers__](#26) -[__::term::ansi::code::attr::hidden__](#27) -[__::term::ansi::code::attr::strike__](#28) -[__::term::ansi::code::attr::nobold__](#29) -[__::term::ansi::code::attr::noitalic__](#30) -[__::term::ansi::code::attr::nounderline__](#31) -[__::term::ansi::code::attr::noblink__](#32) -[__::term::ansi::code::attr::norevers__](#33) -[__::term::ansi::code::attr::nohidden__](#34) -[__::term::ansi::code::attr::nostrike__](#35) -[__::term::ansi::code::attr::reset__](#36) - -# DESCRIPTION - -This package provides symbolic names for the ANSI attribute control codes\. For -each control code a single command is provided which returns this code as its -result\. None of the commands of this package write to a channel; that is handled -by higher level packages, like __[term::ansi::send](ansi\_send\.md)__\. - -# API - -## Introspection - - - __::term::ansi::code::attr::names__ - - This command is for introspection\. It returns as its result a list - containing the names of all attribute commands\. - - - __::term::ansi::code::attr::import__ ?*ns*? ?*arg*\.\.\.? - - This command imports some or all attribute commands into the namespace - *ns*\. This is by default the namespace *attr*\. Note that this is - relative namespace name, placing the imported command into a child of the - current namespace\. By default all commands are imported, this can howver be - restricted by listing the names of the wanted commands after the namespace - argument\. - -## Attributes - - - __::term::ansi::code::attr::fgblack__ - - Set text color to *Black*\. - - - __::term::ansi::code::attr::fgred__ - - Set text color to *Red*\. - - - __::term::ansi::code::attr::fggreen__ - - Set text color to *Green*\. - - - __::term::ansi::code::attr::fgyellow__ - - Set text color to *Yellow*\. - - - __::term::ansi::code::attr::fgblue__ - - Set text color to *Blue*\. - - - __::term::ansi::code::attr::fgmagenta__ - - Set text color to *Magenta*\. - - - __::term::ansi::code::attr::fgcyan__ - - Set text color to *Cyan*\. - - - __::term::ansi::code::attr::fgwhite__ - - Set text color to *White*\. - - - __::term::ansi::code::attr::fgdefault__ - - Set default text color \(*Black*\)\. - - - __::term::ansi::code::attr::bgblack__ - - Set background to *Black*\. - - - __::term::ansi::code::attr::bgred__ - - Set background to *Red*\. - - - __::term::ansi::code::attr::bggreen__ - - Set background to *Green*\. - - - __::term::ansi::code::attr::bgyellow__ - - Set background to *Yellow*\. - - - __::term::ansi::code::attr::bgblue__ - - Set background to *Blue*\. - - - __::term::ansi::code::attr::bgmagenta__ - - Set background to *Magenta*\. - - - __::term::ansi::code::attr::bgcyan__ - - Set background to *Cyan*\. - - - __::term::ansi::code::attr::bgwhite__ - - Set background to *White*\. - - - __::term::ansi::code::attr::bgdefault__ - - Set default background \(Transparent\)\. - - - __::term::ansi::code::attr::bold__ - - Bold on\. - - - __::term::ansi::code::attr::dim__ - - Dim on\. - - - __::term::ansi::code::attr::italic__ - - Italics on\. - - - __::term::ansi::code::attr::underline__ - - Underscore on\. - - - __::term::ansi::code::attr::blink__ - - Blink on\. - - - __::term::ansi::code::attr::revers__ - - Reverse on\. - - - __::term::ansi::code::attr::hidden__ - - Hidden on\. - - - __::term::ansi::code::attr::strike__ - - Strike\-through on\. - - - __::term::ansi::code::attr::nobold__ - - Bold off\. - - - __::term::ansi::code::attr::noitalic__ - - Italics off\. - - - __::term::ansi::code::attr::nounderline__ - - Underscore off\. - - - __::term::ansi::code::attr::noblink__ - - Blink off\. - - - __::term::ansi::code::attr::norevers__ - - Reverse off\. - - - __::term::ansi::code::attr::nohidden__ - - Hidden off\. - - - __::term::ansi::code::attr::nostrike__ - - Strike\-through off\. - - - __::term::ansi::code::attr::reset__ - - Reset all attributes to their default values\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ansi](\.\./\.\./\.\./\.\./index\.md\#ansi), [attribute -control](\.\./\.\./\.\./\.\./index\.md\#attribute\_control), [color -control](\.\./\.\./\.\./\.\./index\.md\#color\_control), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ansi_cctrl.md Index: embedded/md/tcllib/files/modules/term/ansi_cctrl.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_cctrl.md +++ embedded/md/tcllib/files/modules/term/ansi_cctrl.md @@ -1,569 +0,0 @@ - -[//000000001]: # (term::ansi::code::ctrl \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_cctrl\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2008 Andreas Kupries ) -[//000000004]: # (term::ansi::code::ctrl\(n\) 0\.2 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::code::ctrl \- ANSI control sequences - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Introspection](#subsection1) - - - [Sequences](#subsection2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::ansi::code ?0\.2? -package require term::ansi::code::ctrl ?0\.2? - -[__::term::ansi::code::ctrl::names__](#1) -[__::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*\.\.\.?](#2) -[__::term::ansi::code::ctrl::eeol__](#3) -[__::term::ansi::code::ctrl::esol__](#4) -[__::term::ansi::code::ctrl::el__](#5) -[__::term::ansi::code::ctrl::ed__](#6) -[__::term::ansi::code::ctrl::eu__](#7) -[__::term::ansi::code::ctrl::es__](#8) -[__::term::ansi::code::ctrl::sd__](#9) -[__::term::ansi::code::ctrl::su__](#10) -[__::term::ansi::code::ctrl::ch__](#11) -[__::term::ansi::code::ctrl::sc__](#12) -[__::term::ansi::code::ctrl::rc__](#13) -[__::term::ansi::code::ctrl::sca__](#14) -[__::term::ansi::code::ctrl::rca__](#15) -[__::term::ansi::code::ctrl::st__](#16) -[__::term::ansi::code::ctrl::ct__](#17) -[__::term::ansi::code::ctrl::cat__](#18) -[__::term::ansi::code::ctrl::qdc__](#19) -[__::term::ansi::code::ctrl::qds__](#20) -[__::term::ansi::code::ctrl::qcp__](#21) -[__::term::ansi::code::ctrl::rd__](#22) -[__::term::ansi::code::ctrl::elw__](#23) -[__::term::ansi::code::ctrl::dlw__](#24) -[__::term::ansi::code::ctrl::eg__](#25) -[__::term::ansi::code::ctrl::lg__](#26) -[__::term::ansi::code::ctrl::scs0__ *tag*](#27) -[__::term::ansi::code::ctrl::scs1__ *tag*](#28) -[__::term::ansi::code::ctrl::sda__ *arg*\.\.\.](#29) -[__::term::ansi::code::ctrl::sda\_fgblack__](#30) -[__::term::ansi::code::ctrl::sda\_fgred__](#31) -[__::term::ansi::code::ctrl::sda\_fggreen__](#32) -[__::term::ansi::code::ctrl::sda\_fgyellow__](#33) -[__::term::ansi::code::ctrl::sda\_fgblue__](#34) -[__::term::ansi::code::ctrl::sda\_fgmagenta__](#35) -[__::term::ansi::code::ctrl::sda\_fgcyan__](#36) -[__::term::ansi::code::ctrl::sda\_fgwhite__](#37) -[__::term::ansi::code::ctrl::sda\_fgdefault__](#38) -[__::term::ansi::code::ctrl::sda\_bgblack__](#39) -[__::term::ansi::code::ctrl::sda\_bgred__](#40) -[__::term::ansi::code::ctrl::sda\_bggreen__](#41) -[__::term::ansi::code::ctrl::sda\_bgyellow__](#42) -[__::term::ansi::code::ctrl::sda\_bgblue__](#43) -[__::term::ansi::code::ctrl::sda\_bgmagenta__](#44) -[__::term::ansi::code::ctrl::sda\_bgcyan__](#45) -[__::term::ansi::code::ctrl::sda\_bgwhite__](#46) -[__::term::ansi::code::ctrl::sda\_bgdefault__](#47) -[__::term::ansi::code::ctrl::sda\_bold__](#48) -[__::term::ansi::code::ctrl::sda\_dim__](#49) -[__::term::ansi::code::ctrl::sda\_italic__](#50) -[__::term::ansi::code::ctrl::sda\_underline__](#51) -[__::term::ansi::code::ctrl::sda\_blink__](#52) -[__::term::ansi::code::ctrl::sda\_revers__](#53) -[__::term::ansi::code::ctrl::sda\_hidden__](#54) -[__::term::ansi::code::ctrl::sda\_strike__](#55) -[__::term::ansi::code::ctrl::sda\_nobold__](#56) -[__::term::ansi::code::ctrl::sda\_noitalic__](#57) -[__::term::ansi::code::ctrl::sda\_nounderline__](#58) -[__::term::ansi::code::ctrl::sda\_noblink__](#59) -[__::term::ansi::code::ctrl::sda\_norevers__](#60) -[__::term::ansi::code::ctrl::sda\_nohidden__](#61) -[__::term::ansi::code::ctrl::sda\_nostrike__](#62) -[__::term::ansi::code::ctrl::sda\_reset__](#63) -[__::term::ansi::send::fcp__ *row* *col*](#64) -[__::term::ansi::code::ctrl::cu__ ?*n*?](#65) -[__::term::ansi::code::ctrl::cd__ ?*n*?](#66) -[__::term::ansi::code::ctrl::cf__ ?*n*?](#67) -[__::term::ansi::code::ctrl::cb__ ?*n*?](#68) -[__::term::ansi::code::ctrl::ss__ ?*s* *e*?](#69) -[__::term::ansi::code::ctrl::skd__ *code* *str*](#70) -[__::term::ansi::code::ctrl::title__ *str*](#71) -[__::term::ansi::code::ctrl::gron__](#72) -[__::term::ansi::code::ctrl::groff__](#73) -[__::term::ansi::code::ctrl::tlc__](#74) -[__::term::ansi::code::ctrl::trc__](#75) -[__::term::ansi::code::ctrl::brc__](#76) -[__::term::ansi::code::ctrl::blc__](#77) -[__::term::ansi::code::ctrl::ltj__](#78) -[__::term::ansi::code::ctrl::ttj__](#79) -[__::term::ansi::code::ctrl::rtj__](#80) -[__::term::ansi::code::ctrl::btj__](#81) -[__::term::ansi::code::ctrl::fwj__](#82) -[__::term::ansi::code::ctrl::hl__](#83) -[__::term::ansi::code::ctrl::vl__](#84) -[__::term::ansi::code::ctrl::groptim__ *str*](#85) -[__::term::ansi::code::ctrl::clear__](#86) -[__::term::ansi::code::ctrl::init__](#87) -[__::term::ansi::code::ctrl::showat__ *row* *col* *text*](#88) - -# DESCRIPTION - -This package provides symbolic names for the ANSI control sequences\. For each -sequence a single command is provided which returns the sequence as its result\. -None of the commands of this package write to a channel; that is handled by -higher level packages, like __[term::ansi::send](ansi\_send\.md)__\. - -# API - -## Introspection - - - __::term::ansi::code::ctrl::names__ - - This command is for introspection\. It returns as its result a list - containing the names of all attribute commands\. - - - __::term::ansi::code::ctrl::import__ ?*ns*? ?*arg*\.\.\.? - - This command imports some or all attribute commands into the namespace - *ns*\. This is by default the namespace *ctrl*\. Note that this is - relative namespace name, placing the imported command into a child of the - current namespace\. By default all commands are imported, this can howver be - restricted by listing the names of the wanted commands after the namespace - argument\. - -## Sequences - - - __::term::ansi::code::ctrl::eeol__ - - Erase \(to\) End Of Line - - - __::term::ansi::code::ctrl::esol__ - - Erase \(to\) Start Of Line - - - __::term::ansi::code::ctrl::el__ - - Erase \(current\) Line - - - __::term::ansi::code::ctrl::ed__ - - Erase Down \(to bottom\) - - - __::term::ansi::code::ctrl::eu__ - - Erase Up \(to top\) - - - __::term::ansi::code::ctrl::es__ - - Erase Screen - - - __::term::ansi::code::ctrl::sd__ - - Scroll Down - - - __::term::ansi::code::ctrl::su__ - - Scroll Up - - - __::term::ansi::code::ctrl::ch__ - - Cursor Home - - - __::term::ansi::code::ctrl::sc__ - - Save Cursor - - - __::term::ansi::code::ctrl::rc__ - - Restore Cursor \(Unsave\) - - - __::term::ansi::code::ctrl::sca__ - - Save Cursor \+ Attributes - - - __::term::ansi::code::ctrl::rca__ - - Restore Cursor \+ Attributes - - - __::term::ansi::code::ctrl::st__ - - Set Tab \(@ current position\) - - - __::term::ansi::code::ctrl::ct__ - - Clear Tab \(@ current position\) - - - __::term::ansi::code::ctrl::cat__ - - Clear All Tabs - - - __::term::ansi::code::ctrl::qdc__ - - Query Device Code - - - __::term::ansi::code::ctrl::qds__ - - Query Device Status - - - __::term::ansi::code::ctrl::qcp__ - - Query Cursor Position - - - __::term::ansi::code::ctrl::rd__ - - Reset Device - - - __::term::ansi::code::ctrl::elw__ - - Enable Line Wrap - - - __::term::ansi::code::ctrl::dlw__ - - Disable Line Wrap - - - __::term::ansi::code::ctrl::eg__ - - Enter Graphics Mode - - - __::term::ansi::code::ctrl::lg__ - - Exit Graphics Mode - - - __::term::ansi::code::ctrl::scs0__ *tag* - - Set default character set - - - __::term::ansi::code::ctrl::scs1__ *tag* - - Set alternate character set Select Character Set\. - - Choose which character set is used for either default \(scs0\) or alternate - font \(scs1\)\. This does not change whether default or alternate font are - used, only their definition\. - - The legal tags, and their meanings, are: - - * A - - United Kingdom Set - - * B - - ASCII Set - - * 0 - - Special Graphics - - * 1 - - Alternate Character ROM Standard Character Set - - * 2 - - Alternate Character ROM Special Graphics - - - __::term::ansi::code::ctrl::sda__ *arg*\.\.\. - - Set Display Attributes\. The arguments are the code sequences for the - possible attributes, as provided by the package - __[term::ansi::code::attr](ansi\_cattr\.md)__\. For convenience this - package also provides additional commands each setting a single specific - attribute\. - - - __::term::ansi::code::ctrl::sda\_fgblack__ - - Set text color to *Black*\. - - - __::term::ansi::code::ctrl::sda\_fgred__ - - Set text color to *Red*\. - - - __::term::ansi::code::ctrl::sda\_fggreen__ - - Set text color to *Green*\. - - - __::term::ansi::code::ctrl::sda\_fgyellow__ - - Set text color to *Yellow*\. - - - __::term::ansi::code::ctrl::sda\_fgblue__ - - Set text color to *Blue*\. - - - __::term::ansi::code::ctrl::sda\_fgmagenta__ - - Set text color to *Magenta*\. - - - __::term::ansi::code::ctrl::sda\_fgcyan__ - - Set text color to *Cyan*\. - - - __::term::ansi::code::ctrl::sda\_fgwhite__ - - Set text color to *White*\. - - - __::term::ansi::code::ctrl::sda\_fgdefault__ - - Set default text color \(*Black*\)\. - - - __::term::ansi::code::ctrl::sda\_bgblack__ - - Set background to *Black*\. - - - __::term::ansi::code::ctrl::sda\_bgred__ - - Set background to *Red*\. - - - __::term::ansi::code::ctrl::sda\_bggreen__ - - Set background to *Green*\. - - - __::term::ansi::code::ctrl::sda\_bgyellow__ - - Set background to *Yellow*\. - - - __::term::ansi::code::ctrl::sda\_bgblue__ - - Set background to *Blue*\. - - - __::term::ansi::code::ctrl::sda\_bgmagenta__ - - Set background to *Magenta*\. - - - __::term::ansi::code::ctrl::sda\_bgcyan__ - - Set background to *Cyan*\. - - - __::term::ansi::code::ctrl::sda\_bgwhite__ - - Set background to *White*\. - - - __::term::ansi::code::ctrl::sda\_bgdefault__ - - Set default background \(Transparent\)\. - - - __::term::ansi::code::ctrl::sda\_bold__ - - Bold on\. - - - __::term::ansi::code::ctrl::sda\_dim__ - - Dim on\. - - - __::term::ansi::code::ctrl::sda\_italic__ - - Italics on\. - - - __::term::ansi::code::ctrl::sda\_underline__ - - Underscore on\. - - - __::term::ansi::code::ctrl::sda\_blink__ - - Blink on\. - - - __::term::ansi::code::ctrl::sda\_revers__ - - Reverse on\. - - - __::term::ansi::code::ctrl::sda\_hidden__ - - Hidden on\. - - - __::term::ansi::code::ctrl::sda\_strike__ - - Strike\-through on\. - - - __::term::ansi::code::ctrl::sda\_nobold__ - - Bold off\. - - - __::term::ansi::code::ctrl::sda\_noitalic__ - - Italics off\. - - - __::term::ansi::code::ctrl::sda\_nounderline__ - - Underscore off\. - - - __::term::ansi::code::ctrl::sda\_noblink__ - - Blink off\. - - - __::term::ansi::code::ctrl::sda\_norevers__ - - Reverse off\. - - - __::term::ansi::code::ctrl::sda\_nohidden__ - - Hidden off\. - - - __::term::ansi::code::ctrl::sda\_nostrike__ - - Strike\-through off\. - - - __::term::ansi::code::ctrl::sda\_reset__ - - Reset all attributes to their default values\. - - - __::term::ansi::send::fcp__ *row* *col* - - Force Cursor Position \(aka Go To\)\. - - - __::term::ansi::code::ctrl::cu__ ?*n*? - - Cursor Up\. *n* defaults to 1\. - - - __::term::ansi::code::ctrl::cd__ ?*n*? - - Cursor Down\. *n* defaults to 1\. - - - __::term::ansi::code::ctrl::cf__ ?*n*? - - Cursor Forward\. *n* defaults to 1\. - - - __::term::ansi::code::ctrl::cb__ ?*n*? - - Cursor Backward\. *n* defaults to 1\. - - - __::term::ansi::code::ctrl::ss__ ?*s* *e*? - - Scroll Screen \(entire display, or between rows start end, inclusive\)\. - - - __::term::ansi::code::ctrl::skd__ *code* *str* - - Set Key Definition\. - - - __::term::ansi::code::ctrl::title__ *str* - - Set the terminal title\. - - - __::term::ansi::code::ctrl::gron__ - - Switch to character/box graphics\. I\.e\. switch to the alternate font\. - - - __::term::ansi::code::ctrl::groff__ - - Switch to regular characters\. I\.e\. switch to the default font\. - - - __::term::ansi::code::ctrl::tlc__ - - Character graphics, Top Left Corner\. - - - __::term::ansi::code::ctrl::trc__ - - Character graphics, Top Right Corner\. - - - __::term::ansi::code::ctrl::brc__ - - Character graphics, Bottom Right Corner\. - - - __::term::ansi::code::ctrl::blc__ - - Character graphics, Bottom Left Corner\. - - - __::term::ansi::code::ctrl::ltj__ - - Character graphics, Left T Junction\. - - - __::term::ansi::code::ctrl::ttj__ - - Character graphics, Top T Junction\. - - - __::term::ansi::code::ctrl::rtj__ - - Character graphics, Right T Junction\. - - - __::term::ansi::code::ctrl::btj__ - - Character graphics, Bottom T Junction\. - - - __::term::ansi::code::ctrl::fwj__ - - Character graphics, Four\-Way Junction\. - - - __::term::ansi::code::ctrl::hl__ - - Character graphics, Horizontal Line\. - - - __::term::ansi::code::ctrl::vl__ - - Character graphics, Vertical Line\. - - - __::term::ansi::code::ctrl::groptim__ *str* - - Optimize character graphics\. The generator commands above create way to many - superfluous commands shifting into and out of the graphics mode\. This - command removes all shifts which are not needed\. To this end it also knows - which characters will look the same in both modes, to handle strings created - outside of this package\. - - - __::term::ansi::code::ctrl::clear__ - - Clear screen\. In essence a sequence of CursorHome \+ EraseDown\. - - - __::term::ansi::code::ctrl::init__ - - Initialize default and alternate fonts to ASCII and box graphics\. - - - __::term::ansi::code::ctrl::showat__ *row* *col* *text* - - Format the block of text for display at the specified location\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ansi](\.\./\.\./\.\./\.\./index\.md\#ansi), [attribute -control](\.\./\.\./\.\./\.\./index\.md\#attribute\_control), [color -control](\.\./\.\./\.\./\.\./index\.md\#color\_control), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ansi_cmacros.md Index: embedded/md/tcllib/files/modules/term/ansi_cmacros.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_cmacros.md +++ embedded/md/tcllib/files/modules/term/ansi_cmacros.md @@ -1,119 +0,0 @@ - -[//000000001]: # (term::ansi::code::macros \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_cmacros\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::ansi::code::macros\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::code::macros \- Macro sequences - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Introspection](#subsection1) - - - [Sequences](#subsection2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require textutil::repeat -package require textutil::tabify -package require term::ansi::code::macros ?0\.1? - -[__::term::ansi::code::macros::names__](#1) -[__::term::ansi::code::macros::import__ ?*ns*? ?*arg*\.\.\.?](#2) -[__::term::ansi::code::macros::menu__ *menu*](#3) -[__::term::ansi::code::macros::frame__ *string*](#4) - -# DESCRIPTION - -This package provides higher level control sequences for more complex shapes\. - -# API - -## Introspection - - - __::term::ansi::code::macros::names__ - - This command is for introspection\. It returns as its result a list - containing the names of all attribute commands\. - - - __::term::ansi::code::macros::import__ ?*ns*? ?*arg*\.\.\.? - - This command imports some or all attribute commands into the namespace - *ns*\. This is by default the namespace *macros*\. Note that this is - relative namespace name, placing the imported command into a child of the - current namespace\. By default all commands are imported, this can howver be - restricted by listing the names of the wanted commands after the namespace - argument\. - -## Sequences - - - __::term::ansi::code::macros::menu__ *menu* - - The description of a menu is converted into a formatted rectangular block of - text, with the menu command characters highlighted using bold red text\. The - result is returned as the result of the command\. - - The description, *menu*, is a dictionary mapping from menu label to - command character\. - - - __::term::ansi::code::macros::frame__ *string* - - The paragraph of text contained in the string is padded with spaces at the - right margin, after normalizing internal tabs, and then put into a frame - made of box\-graphics\. The result is returned as the result of the command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ansi](\.\./\.\./\.\./\.\./index\.md\#ansi), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[frame](\.\./\.\./\.\./\.\./index\.md\#frame), [menu](\.\./\.\./\.\./\.\./index\.md\#menu), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ansi_code.md Index: embedded/md/tcllib/files/modules/term/ansi_code.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_code.md +++ embedded/md/tcllib/files/modules/term/ansi_code.md @@ -1,98 +0,0 @@ - -[//000000001]: # (term::ansi::code \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_code\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::ansi::code\(n\) 0\.2 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::code \- Helper for control sequences - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::ansi::code ?0\.2? - -[__::term::ansi::code::esc__ *str*](#1) -[__::term::ansi::code::escb__ *str*](#2) -[__::term::ansi::code::define__ *name* *escape* *code*](#3) -[__::term::ansi::code::const__ *name* *code*](#4) - -# DESCRIPTION - -This package provides commands enabling the definition of control sequences in -an easy manner\. - - - __::term::ansi::code::esc__ *str* - - This command returns the argument string, prefixed with the ANSI escape - character, "\\033\." - - - __::term::ansi::code::escb__ *str* - - This command returns the argument string, prefixed with a common ANSI escape - sequence, "\\033\["\. - - - __::term::ansi::code::define__ *name* *escape* *code* - - This command defines a procedure *name* which returns the control sequence - *code*, beginning with the specified escape sequence, either __esc__, - or __escb__\. - - - __::term::ansi::code::const__ *name* *code* - - This command defines a procedure *name* which returns the control sequence - *code*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[declare](\.\./\.\./\.\./\.\./index\.md\#declare), -[define](\.\./\.\./\.\./\.\./index\.md\#define), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ansi_ctrlu.md Index: embedded/md/tcllib/files/modules/term/ansi_ctrlu.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_ctrlu.md +++ embedded/md/tcllib/files/modules/term/ansi_ctrlu.md @@ -1,135 +0,0 @@ - -[//000000001]: # (term::ansi::ctrl::unix \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_ctrlu\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2011 Andreas Kupries ) -[//000000004]: # (term::ansi::ctrl::unix\(n\) 0\.1\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::ctrl::unix \- Control operations and queries - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Introspection](#subsection1) - - - [Operations](#subsection2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::ansi::ctrl::unix ?0\.1\.1? - -[__::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*\.\.\.?](#1) -[__::term::ansi::ctrl::unix::raw__](#2) -[__::term::ansi::ctrl::unix::cooked__](#3) -[__::term::ansi::ctrl::unix::columns__](#4) -[__::term::ansi::ctrl::unix::rows__](#5) - -# DESCRIPTION - -*WARNING*: This package is unix\-specific and depends on the availability of -two unix system commands for terminal control, i\.e\. __stty__ and -__tput__, both of which have to be found in the __$PATH__\. If any of -these two commands is missing the loading of the package will fail\. - -The package provides commands to switch the standard input of the current -process between *[raw](\.\./\.\./\.\./\.\./index\.md\#raw)* and -*[cooked](\.\./\.\./\.\./\.\./index\.md\#cooked)* input modes, and to query the size -of terminals, i\.e\. the available number of columns and lines\. - -# API - -## Introspection - - - __::term::ansi::ctrl::unix::import__ ?*ns*? ?*arg*\.\.\.? - - This command imports some or all attribute commands into the namespace - *ns*\. This is by default the namespace *ctrl*\. Note that this is - relative namespace name, placing the imported command into a child of the - current namespace\. By default all commands are imported, this can howver be - restricted by listing the names of the wanted commands after the namespace - argument\. - -## Operations - - - __::term::ansi::ctrl::unix::raw__ - - This command switches the standard input of the current process to - *[raw](\.\./\.\./\.\./\.\./index\.md\#raw)* input mode\. This means that from - then on all characters typed by the user are immediately reported to the - application instead of waiting in the OS buffer until the Enter/Return key - is received\. - - - __::term::ansi::ctrl::unix::cooked__ - - This command switches the standard input of the current process to - *[cooked](\.\./\.\./\.\./\.\./index\.md\#cooked)* input mode\. This means that - from then on all characters typed by the user are kept in OS buffers for - editing until the Enter/Return key is received\. - - - __::term::ansi::ctrl::unix::columns__ - - This command queries the terminal connected to the standard input for the - number of columns available for display\. - - - __::term::ansi::ctrl::unix::rows__ - - This command queries the terminal connected to the standard input for the - number of rows \(aka lines\) available for display\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[ansi](\.\./\.\./\.\./\.\./index\.md\#ansi), -[columns](\.\./\.\./\.\./\.\./index\.md\#columns), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[cooked](\.\./\.\./\.\./\.\./index\.md\#cooked), [input -mode](\.\./\.\./\.\./\.\./index\.md\#input\_mode), -[lines](\.\./\.\./\.\./\.\./index\.md\#lines), [raw](\.\./\.\./\.\./\.\./index\.md\#raw), -[rows](\.\./\.\./\.\./\.\./index\.md\#rows), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006\-2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ansi_send.md Index: embedded/md/tcllib/files/modules/term/ansi_send.md ================================================================== --- embedded/md/tcllib/files/modules/term/ansi_send.md +++ embedded/md/tcllib/files/modules/term/ansi_send.md @@ -1,554 +0,0 @@ - -[//000000001]: # (term::ansi::send \- Terminal control) -[//000000002]: # (Generated from file 'ansi\_send\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::ansi::send\(n\) 0\.2 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::ansi::send \- Output of ANSI control sequences to terminals - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::ansi::send ?0\.2? - -[__::term::ansi::send::import__ ?*ns*? *\.\.\.*](#1) -[__::term::ansi::send::eeol__](#2) -[__::term::ansi::send::esol__](#3) -[__::term::ansi::send::el__](#4) -[__::term::ansi::send::ed__](#5) -[__::term::ansi::send::eu__](#6) -[__::term::ansi::send::es__](#7) -[__::term::ansi::send::sd__](#8) -[__::term::ansi::send::su__](#9) -[__::term::ansi::send::ch__](#10) -[__::term::ansi::send::sc__](#11) -[__::term::ansi::send::rc__](#12) -[__::term::ansi::send::sca__](#13) -[__::term::ansi::send::rca__](#14) -[__::term::ansi::send::st__](#15) -[__::term::ansi::send::ct__](#16) -[__::term::ansi::send::cat__](#17) -[__::term::ansi::send::qdc__](#18) -[__::term::ansi::send::qds__](#19) -[__::term::ansi::send::qcp__](#20) -[__::term::ansi::send::rd__](#21) -[__::term::ansi::send::elw__](#22) -[__::term::ansi::send::dlw__](#23) -[__::term::ansi::send::eg__](#24) -[__::term::ansi::send::lg__](#25) -[__::term::ansi::send::scs0__ *tag*](#26) -[__::term::ansi::send::scs1__ *tag*](#27) -[__::term::ansi::send::sda__ *arg*\.\.\.](#28) -[__::term::ansi::send::sda\_fgblack__](#29) -[__::term::ansi::send::sda\_fgred__](#30) -[__::term::ansi::send::sda\_fggreen__](#31) -[__::term::ansi::send::sda\_fgyellow__](#32) -[__::term::ansi::send::sda\_fgblue__](#33) -[__::term::ansi::send::sda\_fgmagenta__](#34) -[__::term::ansi::send::sda\_fgcyan__](#35) -[__::term::ansi::send::sda\_fgwhite__](#36) -[__::term::ansi::send::sda\_fgdefault__](#37) -[__::term::ansi::send::sda\_bgblack__](#38) -[__::term::ansi::send::sda\_bgred__](#39) -[__::term::ansi::send::sda\_bggreen__](#40) -[__::term::ansi::send::sda\_bgyellow__](#41) -[__::term::ansi::send::sda\_bgblue__](#42) -[__::term::ansi::send::sda\_bgmagenta__](#43) -[__::term::ansi::send::sda\_bgcyan__](#44) -[__::term::ansi::send::sda\_bgwhite__](#45) -[__::term::ansi::send::sda\_bgdefault__](#46) -[__::term::ansi::send::sda\_bold__](#47) -[__::term::ansi::send::sda\_dim__](#48) -[__::term::ansi::send::sda\_italic__](#49) -[__::term::ansi::send::sda\_underline__](#50) -[__::term::ansi::send::sda\_blink__](#51) -[__::term::ansi::send::sda\_revers__](#52) -[__::term::ansi::send::sda\_hidden__](#53) -[__::term::ansi::send::sda\_strike__](#54) -[__::term::ansi::send::sda\_nobold__](#55) -[__::term::ansi::send::sda\_noitalic__](#56) -[__::term::ansi::send::sda\_nounderline__](#57) -[__::term::ansi::send::sda\_noblink__](#58) -[__::term::ansi::send::sda\_norevers__](#59) -[__::term::ansi::send::sda\_nohidden__](#60) -[__::term::ansi::send::sda\_nostrike__](#61) -[__::term::ansi::send::sda\_reset__](#62) -[__::term::ansi::send::fcp__ *row* *col*](#63) -[__::term::ansi::send::cu__ ?*n*?](#64) -[__::term::ansi::send::cd__ ?*n*?](#65) -[__::term::ansi::send::cf__ ?*n*?](#66) -[__::term::ansi::send::cb__ ?*n*?](#67) -[__::term::ansi::send::ss__ ?*s* *e*?](#68) -[__::term::ansi::send::skd__ *code* *str*](#69) -[__::term::ansi::send::title__ *str*](#70) -[__::term::ansi::send::gron__](#71) -[__::term::ansi::send::groff__](#72) -[__::term::ansi::send::tlc__](#73) -[__::term::ansi::send::trc__](#74) -[__::term::ansi::send::brc__](#75) -[__::term::ansi::send::blc__](#76) -[__::term::ansi::send::ltj__](#77) -[__::term::ansi::send::ttj__](#78) -[__::term::ansi::send::rtj__](#79) -[__::term::ansi::send::btj__](#80) -[__::term::ansi::send::fwj__](#81) -[__::term::ansi::send::hl__](#82) -[__::term::ansi::send::vl__](#83) -[__::term::ansi::send::groptim__ *str*](#84) -[__::term::ansi::send::clear__](#85) -[__::term::ansi::send::init__](#86) -[__::term::ansi::send::showat__ *row* *col* *text*](#87) - -# DESCRIPTION - -This package provides commands to send ANSI terminal control sequences to a -terminal\. All commands come in two variants, one for sending to any channel, the -other for sending to *stdout*\. - -The commands are defined using the control sequences provided by the package -__[term::ansi::code::ctrl](ansi\_cctrl\.md)__\. They have the same -arguments as the commands they are based on, with the exception of the variant -for sending to any channel\. Their first argument is always a channel handle, -then followed by the original arguments\. Below we will list only the variant -sending to *stdout*\. - - - __::term::ansi::send::import__ ?*ns*? *\.\.\.* - - Imports the commands of this package into the namespace *ns*\. If not - specified it defaults to *send*\. Note that this default is a relative - namespace name, i\.e\. the actual namespace will be created under the current - namespace\. - - By default all commands will be imported, this can however be restricted to - specific commands, by listing them after the namespace to import them into\. - - - __::term::ansi::send::eeol__ - - Erase \(to\) End Of Line\. - - - __::term::ansi::send::esol__ - - Erase \(to\) Start Of Line\. - - - __::term::ansi::send::el__ - - Erase \(current\) Line\. - - - __::term::ansi::send::ed__ - - Erase Down \(to bottom\)\. - - - __::term::ansi::send::eu__ - - Erase Up \(to top\)\. - - - __::term::ansi::send::es__ - - Erase Screen\. - - - __::term::ansi::send::sd__ - - Scroll Down\. - - - __::term::ansi::send::su__ - - Scroll Up\. - - - __::term::ansi::send::ch__ - - Cursor Home\. - - - __::term::ansi::send::sc__ - - Save Cursor\. Note: Only one saved position can be handled\. This is no - unlimited stack\. Saving before restoring will overwrite the saved data\. - - - __::term::ansi::send::rc__ - - Restore Cursor \(Unsave\)\. - - - __::term::ansi::send::sca__ - - Save Cursor \+ Attributes\. - - - __::term::ansi::send::rca__ - - Restore Cursor \+ Attributes\. - - - __::term::ansi::send::st__ - - Set Tab \(@ current position\)\. - - - __::term::ansi::send::ct__ - - Clear Tab \(@ current position\)\. - - - __::term::ansi::send::cat__ - - Clear All Tabs\. - - - __::term::ansi::send::qdc__ - - Query Device Code\. - - - __::term::ansi::send::qds__ - - Query Device Status\. - - - __::term::ansi::send::qcp__ - - Query Cursor Position\. - - - __::term::ansi::send::rd__ - - Reset Device\. - - - __::term::ansi::send::elw__ - - Enable Line Wrap\. - - - __::term::ansi::send::dlw__ - - Disable Line Wrap\. - - - __::term::ansi::send::eg__ - - Enter Graphics Mode\. - - - __::term::ansi::send::lg__ - - Exit Graphics Mode\. - - - __::term::ansi::send::scs0__ *tag* - - - __::term::ansi::send::scs1__ *tag* - - Select Character Set\. - - Choose which character set is used for default \(scs0\) and alternate font - \(scs1\)\. This does not change whether default or alternate font are used, - just their definitions\. - - The legal tags, and their meanings, are: - - * A - - United Kingdom Set - - * B - - ASCII Set - - * 0 - - Special Graphics - - * 1 - - Alternate Character ROM Standard Character Set - - * 2 - - Alternate Character ROM Special Graphics - - - __::term::ansi::send::sda__ *arg*\.\.\. - - Set Display Attributes\. The arguments are the code sequences for the - possible attributes, as provided by the package - __[term::ansi::code::attr](ansi\_cattr\.md)__\. For convenience this - package also provides additional commands each setting a single specific - attribute\. - - - __::term::ansi::send::sda\_fgblack__ - - Set text color to *Black*\. - - - __::term::ansi::send::sda\_fgred__ - - Set text color to *Red*\. - - - __::term::ansi::send::sda\_fggreen__ - - Set text color to *Green*\. - - - __::term::ansi::send::sda\_fgyellow__ - - Set text color to *Yellow*\. - - - __::term::ansi::send::sda\_fgblue__ - - Set text color to *Blue*\. - - - __::term::ansi::send::sda\_fgmagenta__ - - Set text color to *Magenta*\. - - - __::term::ansi::send::sda\_fgcyan__ - - Set text color to *Cyan*\. - - - __::term::ansi::send::sda\_fgwhite__ - - Set text color to *White*\. - - - __::term::ansi::send::sda\_fgdefault__ - - Set default text color \(*Black*\)\. - - - __::term::ansi::send::sda\_bgblack__ - - Set background to *Black*\. - - - __::term::ansi::send::sda\_bgred__ - - Set background to *Red*\. - - - __::term::ansi::send::sda\_bggreen__ - - Set background to *Green*\. - - - __::term::ansi::send::sda\_bgyellow__ - - Set background to *Yellow*\. - - - __::term::ansi::send::sda\_bgblue__ - - Set background to *Blue*\. - - - __::term::ansi::send::sda\_bgmagenta__ - - Set background to *Magenta*\. - - - __::term::ansi::send::sda\_bgcyan__ - - Set background to *Cyan*\. - - - __::term::ansi::send::sda\_bgwhite__ - - Set background to *White*\. - - - __::term::ansi::send::sda\_bgdefault__ - - Set default background \(Transparent\)\. - - - __::term::ansi::send::sda\_bold__ - - Bold on\. - - - __::term::ansi::send::sda\_dim__ - - Dim on\. - - - __::term::ansi::send::sda\_italic__ - - Italics on\. - - - __::term::ansi::send::sda\_underline__ - - Underscore on\. - - - __::term::ansi::send::sda\_blink__ - - Blink on\. - - - __::term::ansi::send::sda\_revers__ - - Reverse on\. - - - __::term::ansi::send::sda\_hidden__ - - Hidden on\. - - - __::term::ansi::send::sda\_strike__ - - Strike\-through on\. - - - __::term::ansi::send::sda\_nobold__ - - Bold off\. - - - __::term::ansi::send::sda\_noitalic__ - - Italics off\. - - - __::term::ansi::send::sda\_nounderline__ - - Underscore off\. - - - __::term::ansi::send::sda\_noblink__ - - Blink off\. - - - __::term::ansi::send::sda\_norevers__ - - Reverse off\. - - - __::term::ansi::send::sda\_nohidden__ - - Hidden off\. - - - __::term::ansi::send::sda\_nostrike__ - - Strike\-through off\. - - - __::term::ansi::send::sda\_reset__ - - Reset all attributes to their default values\. - - - __::term::ansi::send::fcp__ *row* *col* - - Force Cursor Position \(aka Go To\)\. - - - __::term::ansi::send::cu__ ?*n*? - - Cursor Up\. *n* defaults to 1\. - - - __::term::ansi::send::cd__ ?*n*? - - Cursor Down\. *n* defaults to 1\. - - - __::term::ansi::send::cf__ ?*n*? - - Cursor Forward\. *n* defaults to 1\. - - - __::term::ansi::send::cb__ ?*n*? - - Cursor Backward\. *n* defaults to 1\. - - - __::term::ansi::send::ss__ ?*s* *e*? - - Scroll Screen \(entire display, or between rows start end, inclusive\)\. - - - __::term::ansi::send::skd__ *code* *str* - - Set Key Definition\. - - - __::term::ansi::send::title__ *str* - - Set the terminal title\. - - - __::term::ansi::send::gron__ - - Switch to character/box graphics\. I\.e\. switch to the alternate font\. - - - __::term::ansi::send::groff__ - - Switch to regular characters\. I\.e\. switch to the default font\. - - - __::term::ansi::send::tlc__ - - Character graphics, Top Left Corner\. - - - __::term::ansi::send::trc__ - - Character graphics, Top Right Corner\. - - - __::term::ansi::send::brc__ - - Character graphics, Bottom Right Corner\. - - - __::term::ansi::send::blc__ - - Character graphics, Bottom Left Corner\. - - - __::term::ansi::send::ltj__ - - Character graphics, Left T Junction\. - - - __::term::ansi::send::ttj__ - - Character graphics, Top T Junction\. - - - __::term::ansi::send::rtj__ - - Character graphics, Right T Junction\. - - - __::term::ansi::send::btj__ - - Character graphics, Bottom T Junction\. - - - __::term::ansi::send::fwj__ - - Character graphics, Four\-Way Junction\. - - - __::term::ansi::send::hl__ - - Character graphics, Horizontal Line\. - - - __::term::ansi::send::vl__ - - Character graphics, Vertical Line\. - - - __::term::ansi::send::groptim__ *str* - - Optimize character graphics\. The generator commands above create way to many - superfluous commands shifting into and out of the graphics mode\. This - command removes all shifts which are not needed\. To this end it also knows - which characters will look the same in both modes, to handle strings created - outside of this package\. - - - __::term::ansi::send::clear__ - - Clear screen\. In essence a sequence of CursorHome \+ EraseDown\. - - - __::term::ansi::send::init__ - - Initialize default and alternate fonts to ASCII and box graphics\. - - - __::term::ansi::send::showat__ *row* *col* *text* - - Show the block of text at the specified location\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[character output](\.\./\.\./\.\./\.\./index\.md\#character\_output), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/imenu.md Index: embedded/md/tcllib/files/modules/term/imenu.md ================================================================== --- embedded/md/tcllib/files/modules/term/imenu.md +++ embedded/md/tcllib/files/modules/term/imenu.md @@ -1,207 +0,0 @@ - -[//000000001]: # (term::interact::menu \- Terminal control) -[//000000002]: # (Generated from file 'imenu\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::interact::menu\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::interact::menu \- Terminal widget, menu - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Object API](#section3) - - - [Configuration](#section4) - - - [Interaction](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::interact::menu ?0\.1? - -[__term::interact::menu__ *object* *dict* ?*options*\.\.\.?](#1) -[*object* __interact__](#2) -[*object* __done__](#3) -[*object* __clear__](#4) -[*object* __configure__](#5) -[*object* __configure__ *option*](#6) -[*object* __configure__ *option* *value*\.\.\.](#7) -[*object* __cget__ *option*](#8) - -# DESCRIPTION - -This package provides a class for the creation of a simple menu control\. - -# Class API - -The package exports a single command, the class command, enabling the creation -of menu instances\. Its API is: - - - __term::interact::menu__ *object* *dict* ?*options*\.\.\.? - - This command creates a new menu object with the name *object*, initializes - it, and returns the fully qualified name of the object command as its - result\. - - The argument is the menu to show, possibly followed by configuration options - and their values\. The options are explained in the section - [Configuration](#section4)\. The menu is a dictionary maping labels to - symbolic action codes\. - -# Object API - -The objects created by the class command provide the methods listed below: - - - *object* __interact__ - - Shows the menu in the screen at the configured location and starts - interacting with it\. This opens its own event loop for the processing of - incoming characters\. The method returns when the interaction has completed\. - See section [Interaction](#section5) for a description of the possible - interaction\. - - The method returns the symbolic action of the menu item selected by the user - at the end of the interaction\. - - - *object* __done__ - - This method can be used by user supplied actions to terminate the - interaction with the object\. - - - *object* __clear__ - - This method can be used by user supplied actions to remove the menu from the - terminal\. - - - *object* __configure__ - - - *object* __configure__ *option* - - - *object* __configure__ *option* *value*\.\.\. - - - *object* __cget__ *option* - - Standard methods to retrieve and configure the options of the menu\. - -# Configuration - -A menu instance recognizes the following options: - - - __\-in__ chan - - Specifies the channel to read character sequences from\. Defaults to - __stdin__\. - - - __\-out__ chan - - Specifies the channel to write the menu contents to\. Defaults to - __stdout__\. - - - __\-column__ int - - Specifies the column of the terminal where the left margin of the menu - display should appear\. Defaults to 0, i\.e\. the left\-most column\. - - - __\-line__ int - - Specifies the line of the terminal where the top margin of the menu display - should appear\. Defaults to 0, i\.e\. the top\-most line\. - - - __\-height__ int - - Specifies the number of lines of text to show at most in the display\. - Defaults to 25\. - - - __\-actions__ dict - - Specifies a dictionary containing additional actions, using character - sequences as keys\. Note that these sequences cannot override the hardwired - sequences described in section [Interaction](#section5)\. - - - __\-hilitleft__ int - - - __\-hilitright__ int - - By default the entire selected menu entry is highlighted in revers output\. - However, when present these two options restrict revers dispay to the - specified sub\-range of the entry\. - - - __\-framed__ bool - - By default the menu is shown using only header and footer out of characters - box graphics\. If this flag is set the menu is fully enclosed in a box\. - -# Interaction - -A menu object recognizes the control sequences listed below and acts as -described\. The user can supply more control sequences to act on via the -configuration, but is not able to overide these defaults\. - - - Cursor Up - - The selection is moved up one entry, except if the first entry of the menu - is already selected\. - - - Cursor Down - - The selection is moved down one entry, except if the last entry of the menu - is already selected\. - - - Enter/Return - - The interaction with the object is terminated\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[menu](\.\./\.\./\.\./\.\./index\.md\#menu), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal), [text -display](\.\./\.\./\.\./\.\./index\.md\#text\_display) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/ipager.md Index: embedded/md/tcllib/files/modules/term/ipager.md ================================================================== --- embedded/md/tcllib/files/modules/term/ipager.md +++ embedded/md/tcllib/files/modules/term/ipager.md @@ -1,208 +0,0 @@ - -[//000000001]: # (term::interact::pager \- Terminal control) -[//000000002]: # (Generated from file 'ipager\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::interact::pager\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::interact::pager \- Terminal widget, paging - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Object API](#section3) - - - [Configuration](#section4) - - - [Interaction](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::interact::pager ?0\.1? - -[__term::interact::pager__ *object* *text* ?*options*\.\.\.?](#1) -[*object* __interact__](#2) -[*object* __done__](#3) -[*object* __clear__](#4) -[*object* __text__ *text*](#5) -[*object* __configure__](#6) -[*object* __configure__ *option*](#7) -[*object* __configure__ *option* *value*\.\.\.](#8) -[*object* __cget__ *option*](#9) - -# DESCRIPTION - -This package provides a class for the creation of a simple paging text display\. - -# Class API - -The package exports a single command, the class command, enabling the creation -of pager instances\. Its API is: - - - __term::interact::pager__ *object* *text* ?*options*\.\.\.? - - This command creates a new pager object with the name *object*, - initializes it, and returns the fully qualified name of the object command - as its result\. - - The argument is the text to show, possibly followed by configuration options - and their values\. The options are explained in the section - [Configuration](#section4)\. - -# Object API - -The objects created by the class command provide the methods listed below: - - - *object* __interact__ - - Show the pager in the screen at the configured location and start - interacting with it\. This opens its own event loop for the processing of - incoming characters\. The method returns when the interaction has completed\. - See section [Interaction](#section5) for a description of the possible - interaction\. - - - *object* __done__ - - This method can be used by user supplied actions to terminate the - interaction with the object\. - - - *object* __clear__ - - This method can be used by user supplied actions to remove the pager from - the terminal\. - - - *object* __text__ *text* - - This method can be used to change the text shown by the pager\. The pager - will reset the dispay to show the first line of the text at the top\. - - - *object* __configure__ - - - *object* __configure__ *option* - - - *object* __configure__ *option* *value*\.\.\. - - - *object* __cget__ *option* - - Standard methods to retrieve and configure the options of the pager\. - -# Configuration - -A pager instance recognizes the following options: - - - __\-in__ chan - - Specifies the channel to read character sequences from\. Defaults to - __stdin__\. - - - __\-out__ chan - - Specifies the channel to write the pager contents to\. Defaults to - __stdout__\. - - - __\-column__ int - - Specifies the column of the terminal where the left margin of the pager - display should appear\. Defaults to 0, i\.e\. the left\-most column\. - - - __\-line__ int - - Specifies the line of the terminal where the top margin of the pager display - should appear\. Defaults to 0, i\.e\. the top\-most line\. - - - __\-height__ int - - Specifies the number of lines of text to show at most in the display\. - Defaults to 25\. - - - __\-actions__ dict - - Specifies a dictionary containing additional actions, using character - sequences as keys\. Note that these sequences cannot override the hardwired - sequences described in section [Interaction](#section5)\. - -# Interaction - -A pager object recognizes the control sequences listed below and acts as -described\. The user can supply more control sequences to act on via the -configuration, but is not able to overide these defaults\. - - - Cursor Up - - The text is scrolled down a single line, making one more line visible at the - top\. The pager will not react if the first line of the text is already - shown\. - - - Cursor Down - - The text is scrolled up a single line, making one more line visible at the - bottom\. The pager will not react if the last line of the text is already - shown\. - - - Page Up - - The text is scrolled down a page\. The pager will not react if the first line - of the text is already shown\. - - - Page Down - - The text is scrolled up a page\. The pager will not react if the last line of - the text is already shown\. - - - Enter/Return - - The interaction with the object is terminated\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[pager](\.\./\.\./\.\./\.\./index\.md\#pager), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal), [text -display](\.\./\.\./\.\./\.\./index\.md\#text\_display) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/receive.md Index: embedded/md/tcllib/files/modules/term/receive.md ================================================================== --- embedded/md/tcllib/files/modules/term/receive.md +++ embedded/md/tcllib/files/modules/term/receive.md @@ -1,119 +0,0 @@ - -[//000000001]: # (term::receive \- Terminal control) -[//000000002]: # (Generated from file 'receive\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::receive\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::receive \- General input from terminals - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::receive ?0\.1? - -[__::term::receive::getch__ ?*chan*?](#1) -[__::term::receive::listen__ *cmd* ?*chan*?](#2) -[*cmd* __process__ *string*](#3) -[*cmd* __eof__](#4) -[__::term::receive::unlisten__ ?*chan*?](#5) - -# DESCRIPTION - -This package provides the most primitive commands for receiving characters to a -terminal\. They are in essence convenient wrappers around the builtin commands -__[read](\.\./\.\./\.\./\.\./index\.md\#read)__ and __fileevent__\. - - - __::term::receive::getch__ ?*chan*? - - This command reads a single character from the channel with handle *chan* - and returns it as the result of the command\. - - If not specified *chan* defaults to __stdin__\. - - It is the responsibility of the caller to make sure that the channel can - provide single characters\. On unix this can be done, for example, by using - the command of package __[term::ansi::ctrl::unix](ansi\_ctrlu\.md)__\. - - - __::term::receive::listen__ *cmd* ?*chan*? - - This command sets up a filevent listener for the channel with handle - *chan* and invokes the command prefix *cmd* whenever characters have - been received, or EOF was reached\. - - If not specified *chan* defaults to __stdin__\. - - The signature of the command prefix is - - * *cmd* __process__ *string* - - This method is invoked when characters were received, and *string* - holds them for processing\. - - * *cmd* __eof__ - - This method is invoked when EOF was reached on the channel we listen on\. - It will be the last call to be received by the callback\. - - - __::term::receive::unlisten__ ?*chan*? - - This command disables the filevent listener for the channel with handle - *chan*\. - - If not specified *chan* defaults to __stdin__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[character input](\.\./\.\./\.\./\.\./index\.md\#character\_input), -[control](\.\./\.\./\.\./\.\./index\.md\#control), [get -character](\.\./\.\./\.\./\.\./index\.md\#get\_character), -[listener](\.\./\.\./\.\./\.\./index\.md\#listener), -[receiver](\.\./\.\./\.\./\.\./index\.md\#receiver), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/term.md Index: embedded/md/tcllib/files/modules/term/term.md ================================================================== --- embedded/md/tcllib/files/modules/term/term.md +++ embedded/md/tcllib/files/modules/term/term.md @@ -1,72 +0,0 @@ - -[//000000001]: # (term \- Terminal control) -[//000000002]: # (Generated from file 'term\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term \- General terminal control - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term ?0\.1? - -# DESCRIPTION - -It is planned to have this package provide highlevel general terminal control -commands, in the vein of ncurses or similar packages\. Currently nothing has been -implemented however\. I\.e\. this package is empty\. It can be loaded, yet provides -nothing\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/term_bind.md Index: embedded/md/tcllib/files/modules/term/term_bind.md ================================================================== --- embedded/md/tcllib/files/modules/term/term_bind.md +++ embedded/md/tcllib/files/modules/term/term_bind.md @@ -1,167 +0,0 @@ - -[//000000001]: # (term::receive::bind \- Terminal control) -[//000000002]: # (Generated from file 'term\_bind\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::receive::bind\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::receive::bind \- Keyboard dispatch from terminals - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Object API](#section3) - - - [Notes](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::receive::bind ?0\.1? - -[__term::receive::bind__ *object* ?*map*?](#1) -[*object* __map__ *str* *cmd*](#2) -[*object* __default__ *cmd*](#3) -[*object* __listen__ ?*chan*?](#4) -[*object* __unlisten__ ?*chan*?](#5) -[*object* __reset__](#6) -[*object* __next__ *char*](#7) -[*object* __process__ *str*](#8) -[*object* __eof__](#9) - -# DESCRIPTION - -This package provides a class for the creation of simple dispatchers from -character sequences to actions\. Internally each dispatcher is in essence a -deterministic finite automaton with tree structure\. - -# Class API - -The package exports a single command, the class command, enabling the creation -of dispatcher instances\. Its API is: - - - __term::receive::bind__ *object* ?*map*? - - This command creates a new dispatcher object with the name *object*, - initializes it, and returns the fully qualified name of the object command - as its result\. - - The argument is a dictionary mapping from strings, i\.e\. character sequences - to the command prefices to invoke when the sequence is found in the input - stream\. - -# Object API - -The objects created by the class command provide the methods listed below: - - - *object* __map__ *str* *cmd* - - This method adds an additional mapping from the string *str* to the action - *cmd*\. The mapping will take effect immediately should the processor be in - a prefix of *str*, or at the next reset operation\. The action is a command - prefix and will be invoked with one argument appended to it, the character - sequence causing the invokation\. It is executed in the global namespace\. - - - *object* __default__ *cmd* - - This method defines a default action *cmd* which will be invoked whenever - an unknown character sequence is encountered\. The command prefix is handled - in the same as the regular action defined via method __map__\. - - - *object* __listen__ ?*chan*? - - This methods sets up a filevent listener for the channel with handle - *chan* and invokes the dispatcher object whenever characters have been - received, or EOF was reached\. - - If not specified *chan* defaults to __stdin__\. - - - *object* __unlisten__ ?*chan*? - - This methods removes the filevent listener for the channel with handle - *chan*\. - - If not specified *chan* defaults to __stdin__\. - - - *object* __reset__ - - This method resets the character processor to the beginning of the tree\. - - - *object* __next__ *char* - - This method causes the character processor to process the character *c*\. - This may simply advance the internal state, or invoke an associated action - for a recognized sequence\. - - - *object* __process__ *str* - - This method causes the character processor to process the character sequence - *str*, advancing the internal state and invoking action as necessary\. This - is a callback for __listen__\. - - - *object* __eof__ - - This method causes the character processor to handle EOF on the input\. This - is currently no\-op\. This is a callback for __listen__\. - -# Notes - -The simplicity of the DFA means that it is not possible to recognize a character -sequence with has a another recognized character sequence as its prefix\. - -In other words, the set of recognized strings has to form a *prefix code*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[character input](\.\./\.\./\.\./\.\./index\.md\#character\_input), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[dispatcher](\.\./\.\./\.\./\.\./index\.md\#dispatcher), -[listener](\.\./\.\./\.\./\.\./index\.md\#listener), -[receiver](\.\./\.\./\.\./\.\./index\.md\#receiver), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/term/term_send.md Index: embedded/md/tcllib/files/modules/term/term_send.md ================================================================== --- embedded/md/tcllib/files/modules/term/term_send.md +++ embedded/md/tcllib/files/modules/term/term_send.md @@ -1,87 +0,0 @@ - -[//000000001]: # (term::send \- Terminal control) -[//000000002]: # (Generated from file 'term\_send\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (term::send\(n\) 0\.1 tcllib "Terminal control") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -term::send \- General output to terminals - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require term::send ?0\.1? - -[__::term::send::wrch__ *chan* *str*](#1) -[__::term::send::wr__ *str*](#2) - -# DESCRIPTION - -This package provides the most primitive commands for sending characters to a -terminal\. They are in essence convenient wrappers around the builtin command -__puts__\. - - - __::term::send::wrch__ *chan* *str* - - Send the text *str* to the channel specified by the handle *chan*\. In - contrast to the builtin command __puts__ this command does not terminate - the string with a line terminator\. It also forces an flush of Tcl internal - and OS buffers to ensure that the characters are processed immediately\. - - - __::term::send::wr__ *str* - - This convenience command is like __::term::send::wrch__, except that the - destination channel is fixed to *stdout*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *term* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[character output](\.\./\.\./\.\./\.\./index\.md\#character\_output), -[control](\.\./\.\./\.\./\.\./index\.md\#control), -[terminal](\.\./\.\./\.\./\.\./index\.md\#terminal) - -# CATEGORY - -Terminal control - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/textutil/adjust.md Index: embedded/md/tcllib/files/modules/textutil/adjust.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/adjust.md +++ embedded/md/tcllib/files/modules/textutil/adjust.md @@ -1,224 +0,0 @@ - -[//000000001]: # (textutil::adjust \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'adjust\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::adjust\(n\) 0\.7\.3 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::adjust \- Procedures to adjust, indent, and undent paragraphs - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::adjust ?0\.7\.3? - -[__::textutil::adjust::adjust__ *string* ?*option value\.\.\.*?](#1) -[__::textutil::adjust::readPatterns__ *filename*](#2) -[__::textutil::adjust::listPredefined__](#3) -[__::textutil::adjust::getPredefined__ *filename*](#4) -[__::textutil::adjust::indent__ *string* *prefix* ?*skip*?](#5) -[__::textutil::adjust::undent__ *string*](#6) - -# DESCRIPTION - -The package __textutil::adjust__ provides commands that manipulate strings -or texts \(a\.k\.a\. long strings or string with embedded newlines or paragraphs\), -adjusting, or indenting them\. - -The complete set of procedures is described below\. - - - __::textutil::adjust::adjust__ *string* ?*option value\.\.\.*? - - Do a justification on the *string* according to the options\. The string is - taken as one big paragraph, ignoring any newlines\. Then the line is - formatted according to the options used, and the command returns a new - string with enough lines to contain all the printable chars in the input - string\. A line is a set of characters between the beginning of the string - and a newline, or between 2 newlines, or between a newline and the end of - the string\. If the input string is small enough, the returned string won't - contain any newlines\. - - Together with __::textutil::adjust::indent__ it is possible to create - properly wrapped paragraphs with arbitrary indentations\. - - By default, any occurrence of space or tabulation characters are replaced by - a single space so that each word in a line is separated from the next one by - exactly one space character, and this forms a *real* line\. Each *real* - line is placed in a *logical* line, which has exactly a given length \(see - the option __\-length__ below\)\. The *real* line may be shorter\. Again - by default, trailing spaces are ignored before returning the string \(see the - option __\-full__ below\)\. - - The following options may be used after the *string* parameter, and change - the way the command places a *real* line in a *logical* line\. - - * __\-full__ *boolean* - - If set to __false__ \(default\), trailing space characters are deleted - before returning the string\. If set to __true__, any trailing space - characters are left in the string\. - - * __\-hyphenate__ *boolean* - - If set to __false__ \(default\), no hyphenation will be done\. If set - to __true__, the command will try to hyphenate the last word of a - line\. *Note*: Hyphenation patterns must be loaded prior, using the - command __::textutil::adjust::readPatterns__\. - - * __\-justify__ __center|left|plain|right__ - - Sets the justification of the returned string to either __left__ - \(default\), __center__, __plain__ or __right__\. The - justification means that any line in the returned string but the last - one is build according to the value\. If the justification is set to - __plain__ and the number of printable chars in the last line is less - than 90% of the length of a line \(see the option __\-length__\), then - this line is justified with the __left__ value, avoiding the - expansion of this line when it is too small\. The meaning of each value - is: - - + __center__ - - The real line is centered in the logical line\. If needed, a set of - space characters are added at the beginning \(half of the needed set\) - and at the end \(half of the needed set\) of the line if required \(see - the option __\-full__\)\. - - + __left__ - - The real line is set on the left of the logical line\. It means that - there are no space chars at the beginning of this line\. If required, - all needed space chars are added at the end of the line \(see the - option __\-full__\)\. - - + __plain__ - - The real line is exactly set in the logical line\. It means that - there are no leading or trailing space chars\. All the needed space - chars are added in the *real* line, between 2 \(or more\) words\. - - + __right__ - - The real line is set on the right of the logical line\. It means that - there are no space chars at the end of this line, and there may be - some space chars at the beginning, despite of the __\-full__ - option\. - - * __\-length__ *integer* - - Set the length of the *logical* line in the string to *integer*\. - *integer* must be a positive integer value\. Defaults to __72__\. - - * __\-strictlength__ *boolean* - - If set to __false__ \(default\), a line can exceed the specified - __\-length__ if a single word is longer than __\-length__\. If set - to __true__, words that are longer than __\-length__ are split so - that no line exceeds the specified __\-length__\. - - - __::textutil::adjust::readPatterns__ *filename* - - Loads the internal storage for hyphenation patterns with the contents of the - file *filename*\. This has to be done prior to calling command - __::textutil::adjust::adjust__ with "__\-hyphenate__ __true__", - or the hyphenation process will not work correctly\. - - The package comes with a number of predefined pattern files, and the command - __::textutil::adjust::listPredefined__ can be used to find out their - names\. - - - __::textutil::adjust::listPredefined__ - - This command returns a list containing the names of the hyphenation files - coming with this package\. - - - __::textutil::adjust::getPredefined__ *filename* - - Use this command to query the package for the full path name of the - hyphenation file *filename* coming with the package\. Only the filenames - found in the list returned by __::textutil::adjust::listPredefined__ are - legal arguments for this command\. - - - __::textutil::adjust::indent__ *string* *prefix* ?*skip*? - - Each line in the *string* is indented by adding the string *prefix* at - its beginning\. The modified string is returned as the result of the command\. - - If *skip* is specified the first *skip* lines are left untouched\. The - default for *skip* is __0__, causing the modification of all lines\. - Negative values for *skip* are treated like __0__\. In other words, - *skip* > __0__ creates a hanging indentation\. - - Together with __::textutil::adjust::adjust__ it is possible to create - properly wrapped paragraphs with arbitrary indentations\. - - - __::textutil::adjust::undent__ *string* - - The command computes the common prefix for all lines in *string* - consisting solely out of whitespace, removes this from each line and returns - the modified string\. - - Lines containing only whitespace are always reduced to completely empty - lines\. They and empty lines are also ignored when computing the prefix to - remove\. - - Together with __::textutil::adjust::adjust__ it is possible to create - properly wrapped paragraphs with arbitrary indentations\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[TeX](\.\./\.\./\.\./\.\./index\.md\#tex), -[adjusting](\.\./\.\./\.\./\.\./index\.md\#adjusting), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[hyphenation](\.\./\.\./\.\./\.\./index\.md\#hyphenation), -[indenting](\.\./\.\./\.\./\.\./index\.md\#indenting), -[justification](\.\./\.\./\.\./\.\./index\.md\#justification), -[paragraph](\.\./\.\./\.\./\.\./index\.md\#paragraph), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[undenting](\.\./\.\./\.\./\.\./index\.md\#undenting) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/expander.md Index: embedded/md/tcllib/files/modules/textutil/expander.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/expander.md +++ embedded/md/tcllib/files/modules/textutil/expander.md @@ -1,485 +0,0 @@ - -[//000000001]: # (textutil::expander \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'expander\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © William H\. Duquette, http://www\.wjduquette\.com/expand) -[//000000004]: # (textutil::expander\(n\) 1\.3\.1 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::expander \- Procedures to process templates and expand text\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXPANDER API](#section2) - - - [TUTORIAL](#section3) - - - [Basics](#subsection1) - - - [Embedding Macros](#subsection2) - - - [Writing Macro Commands](#subsection3) - - - [Changing the Expansion Brackets](#subsection4) - - - [Customized Macro Expansion](#subsection5) - - - [Using the Context Stack](#subsection6) - - - [HISTORY](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::expander ?1\.3\.1? - -[__::textutil::expander__ *expanderName*](#1) -[*expanderName* __cappend__ *text*](#2) -[*expanderName* __cget__ *varname*](#3) -[*expanderName* __cis__ *cname*](#4) -[*expanderName* __cname__](#5) -[*expanderName* __cpop__ *cname*](#6) -[*expanderName* __ctopandclear__](#7) -[*expanderName* __cpush__ *cname*](#8) -[*expanderName* __cset__ *varname* *value*](#9) -[*expanderName* __cvar__ *varname*](#10) -[*expanderName* __errmode__ *newErrmode*](#11) -[*expanderName* __evalcmd__ ?*newEvalCmd*?](#12) -[*expanderName* __expand__ *string* ?*brackets*?](#13) -[*expanderName* __lb__ ?*newbracket*?](#14) -[*expanderName* __rb__ ?*newbracket*?](#15) -[*expanderName* __reset__](#16) -[*expanderName* __setbrackets__ *lbrack rbrack*](#17) -[*expanderName* __textcmd__ ?*newTextCmd*?](#18) -[*expanderName* __where__](#19) - -# DESCRIPTION - -The Tcl __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ command is often used to -support a kind of template processing\. Given a string with embedded variables or -function calls, __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ will interpolate -the variable and function values, returning the new string: - - % set greeting "Howdy" - Howdy - % proc place {} {return "World"} - % subst {$greeting, [place]!} - Howdy, World! - % - -By defining a suitable set of Tcl commands, -__[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ can be used to implement a -markup language similar to HTML\. - -The __[subst](\.\./\.\./\.\./\.\./index\.md\#subst)__ command is efficient, but it -has three drawbacks for this kind of template processing: - - - There's no way to identify and process the plain text between two embedded - Tcl commands; that makes it difficult to handle plain text in a - context\-sensitive way\. - - - Embedded commands are necessarily bracketed by __\[__ and __\]__; it's - convenient to be able to choose different brackets in special cases\. Someone - producing web pages that include a large quantity of Tcl code examples might - easily prefer to use __<<__ and __>>__ as the embedded code - delimiters instead\. - - - There's no easy way to handle incremental input, as one might wish to do - when reading data from a socket\. - -At present, expander solves the first two problems; eventually it will solve the -third problem as well\. - -The following section describes the command API to the expander; this is -followed by the tutorial sections, see [TUTORIAL](#section3)\. - -# EXPANDER API - -The __textutil::expander__ package provides only one command, described -below\. The rest of the section is taken by a description of the methods for the -expander objects created by this command\. - - - __::textutil::expander__ *expanderName* - - The command creates a new expander object with an associated Tcl command - whose name is *expanderName*\. This command may be used to invoke various - operations on the graph\. If the *expanderName* is not fully qualified it - is interpreted as relative to the current namespace\. The command has the - following general form: - - > *expanderName* option ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -The following commands are possible for expander objects: - - - *expanderName* __cappend__ *text* - - Appends a string to the output in the current context\. This command should - rarely be used by macros or application code\. - - - *expanderName* __cget__ *varname* - - Retrieves the value of variable *varname*, defined in the current context\. - - - *expanderName* __cis__ *cname* - - Determines whether or not the name of the current context is *cname*\. - - - *expanderName* __cname__ - - Returns the name of the current context\. - - - *expanderName* __cpop__ *cname* - - Pops a context from the context stack, returning all accumulated output in - that context\. The context must be named *cname*, or an error results\. - - - *expanderName* __ctopandclear__ - - Returns the output currently captured in the topmost context and clears that - buffer\. This is similar to a combination of __cpop__ followed by - __cpush__, except that internal state \(brackets\) is preserved here\. - - - *expanderName* __cpush__ *cname* - - Pushes a context named *cname* onto the context stack\. The context must be - popped by __cpop__ before expansion ends or an error results\. - - - *expanderName* __cset__ *varname* *value* - - Sets variable *varname* to *value* in the current context\. - - - *expanderName* __cvar__ *varname* - - Retrieves the internal variable name of context variable *varname*; this - allows the variable to be passed to commands like __lappend__\. - - - *expanderName* __errmode__ *newErrmode* - - Sets the macro expansion error mode to one of __nothing__, - __macro__, __error__, or __fail__; the default value is - __fail__\. The value determines what the expander does if an error is - detected during expansion of a macro\. - - * __fail__ - - The error propagates normally and can be caught or ignored by the - application\. - - * __error__ - - The macro expands into a detailed error message, and expansion - continues\. - - * __macro__ - - The macro expands to itself; that is, it is passed along to the output - unchanged\. - - * __nothing__ - - The macro expands to the empty string, and is effectively ignored\. - - - *expanderName* __evalcmd__ ?*newEvalCmd*? - - Returns the current evaluation command, which defaults to __uplevel - \#0__\. If specified, *newEvalCmd* will be saved for future use and then - returned; it must be a Tcl command expecting one additional argument: the - macro to evaluate\. - - - *expanderName* __expand__ *string* ?*brackets*? - - Expands the input string, replacing embedded macros with their expanded - values, and returns the expanded string\. - - Note that this method pushes a new \(empty\) context on the stack of contexts - while it is running, and removes it on return\. - - If *brackets* is given, it must be a list of two strings; the items will - be used as the left and right macro expansion bracket sequences for this - expansion only\. - - - *expanderName* __lb__ ?*newbracket*? - - Returns the current value of the left macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - - - *expanderName* __rb__ ?*newbracket*? - - Returns the current value of the right macro expansion bracket; this is for - use as or within a macro, when the bracket needs to be included in the - output text\. If *newbracket* is specified, it becomes the new bracket, and - is returned\. - - - *expanderName* __reset__ - - Resets all expander settings to their initial values\. Unusual results are - likely if this command is called from within a call to __expand__\. - - - *expanderName* __setbrackets__ *lbrack rbrack* - - Sets the left and right macro expansion brackets\. This command is for use as - or within a macro, or to permanently change the bracket definitions\. By - default, the brackets are __\[__ and __\]__, but any non\-empty string - can be used; for example, __<__ and __>__ or __\(\*__ and - __\*\)__ or even __Hello,__ and __World\!__\. - - - *expanderName* __textcmd__ ?*newTextCmd*? - - Returns the current command for processing plain text, which defaults to the - empty string, meaning *identity*\. If specified, *newTextCmd* will be - saved for future use and then returned; it must be a Tcl command expecting - one additional argument: the text to process\. The expander object will this - command for all plain text it encounters, giving the user of the object the - ability to process all plain text in some standard way before writing it to - the output\. The object expects that the command returns the processed plain - text\. - - *Note* that the combination of "__textcmd__ *plaintext*" is run - through the *evalcmd* for the actual evaluation\. In other words, the - *textcmd* is treated as a special macro implicitly surrounding all plain - text in the template\. - - - *expanderName* __where__ - - Returns a three\-element list containing the current character position, - line, and column the expander is at in the processing of the current input - string\. - -# TUTORIAL - -## Basics - -To begin, create an expander object: - - % package require textutil::expander - 1.2 - % ::textutil::expander myexp - ::myexp - % - -The created __::myexp__ object can be used to expand text strings containing -embedded Tcl commands\. By default, embedded commands are delimited by square -brackets\. Note that expander doesn't attempt to interpolate variables, since -variables can be referenced by embedded commands: - - % set greeting "Howdy" - Howdy - % proc place {} {return "World"} - % ::myexp expand {[set greeting], [place]!} - Howdy, World! - % - -## Embedding Macros - -An expander macro is simply a Tcl script embedded within a text string\. Expander -evaluates the script in the global context, and replaces it with its result -string\. For example, - - % set greetings {Howdy Hi "What's up"} - Howdy Hi "What's up" - % ::myexp expand {There are many ways to say "Hello, World!": - [set result {} - foreach greeting $greetings { - append result "$greeting, World!\\n" - } - set result] - And that's just a small sample!} - There are many ways to say "Hello, World!": - Howdy, World! - Hi, World! - What's up, World! - - And that's just a small sample! - % - -## Writing Macro Commands - -More typically, *macro commands* are used to create a markup language\. A macro -command is just a Tcl command that returns an output string\. For example, expand -can be used to implement a generic document markup language that can be -retargeted to HTML or any other output format: - - % proc bold {} {return ""} - % proc /bold {} {return ""} - % ::myexp expand {Some of this text is in [bold]boldface[/bold]} - Some of this text is in boldface - % - -The above definitions of __bold__ and __/bold__ returns HTML, but such -commands can be as complicated as needed; they could, for example, decide what -to return based on the desired output format\. - -## Changing the Expansion Brackets - -By default, embedded macros are enclosed in square brackets, __\[__ and -__\]__\. If square brackets need to be included in the output, the input can -contain the __lb__ and __rb__ commands\. Alternatively, or if square -brackets are objectionable for some other reason, the macro expansion brackets -can be changed to any pair of non\-empty strings\. - -The __setbrackets__ command changes the brackets permanently\. For example, -you can write pseudo\-html by change them to __<__ and __>__: - - % ::myexp setbrackets < > - % ::myexp expand {This is boldface} - This is boldface - -Alternatively, you can change the expansion brackets temporarily by passing the -desired brackets to the __expand__ command: - - % ::myexp setbrackets "\\[" "\\]" - % ::myexp expand {This is boldface} {< >} - This is boldface - % - -## Customized Macro Expansion - -By default, macros are evaluated using the Tcl __uplevel \#0__ command, so -that the embedded code executes in the global context\. The application can -provide a different evaluation command using __evalcmd__; this allows the -application to use a safe interpreter, for example, or even to evaluated -something other than Tcl code\. There is one caveat: to be recognized as valid, a -macro must return 1 when passed to Tcl's "info complete" command\. - -For example, the following code "evaluates" each macro by returning the macro -text itself\. - - proc identity {macro} {return $macro} - ::myexp evalcmd identity - -## Using the Context Stack - -Often it's desirable to define a pair of macros which operate in some way on the -plain text between them\. Consider a set of macros for adding footnotes to a web -page: one could have implement something like this: - - Dr. Pangloss, however, thinks that this is the best of all - possible worlds.[footnote "See Candide, by Voltaire"] - -The __footnote__ macro would, presumably, assign a number to this footnote -and save the text to be formatted later on\. However, this solution is ugly if -the footnote text is long or should contain additional markup\. Consider the -following instead: - - Dr. Pangloss, however, thinks that this is the best of all - possible worlds.[footnote]See [bookTitle "Candide"], by - [authorsName "Voltaire"], for more information.[/footnote] - -Here the footnote text is contained between __footnote__ and -__/footnote__ macros, continues onto a second line, and contains several -macros of its own\. This is both clearer and more flexible; however, with the -features presented so far there's no easy way to do it\. That's the purpose of -the context stack\. - -All macro expansion takes place in a particular context\. Here, the -__footnote__ macro pushes a new context onto the context stack\. Then, all -expanded text gets placed in that new context\. __/footnote__ retrieves it by -popping the context\. Here's a skeleton implementation of these two macros: - - proc footnote {} { - ::myexp cpush footnote - } - - proc /footnote {} { - set footnoteText [::myexp cpop footnote] - - # Save the footnote text, and return an appropriate footnote - # number and link. - } - -The __cpush__ command pushes a new context onto the stack; the argument is -the context's name\. It can be any string, but would typically be the name of the -macro itself\. Then, __cpop__ verifies that the current context has the -expected name, pops it off of the stack, and returns the accumulated text\. - -Expand provides several other tools related to the context stack\. Suppose the -first macro in a context pair takes arguments or computes values which the -second macro in the pair needs\. After calling __cpush__, the first macro can -define one or more context variables; the second macro can retrieve their values -any time before calling __cpop__\. For example, suppose the document must -specify the footnote number explicitly: - - proc footnote {footnoteNumber} { - ::myexp cpush footnote - ::myexp csave num $footnoteNumber - # Return an appropriate link - } - - proc /footnote {} { - set footnoteNumber [::myexp cget num] - set footnoteText [::myexp cpop footnote] - - # Save the footnote text and its footnoteNumber for future - # output. - } - -At times, it might be desirable to define macros that are valid only within a -particular context pair; such macros should verify that they are only called -within the correct context using either __cis__ or __cname__\. - -# HISTORY - -__expander__ was written by William H\. Duquette; it is a repackaging of the -central algorithm of the expand macro processing tool\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -\[uri, http://www\.wjduquette\.com/expand, regexp, -[split](\.\./\.\./\.\./\.\./index\.md\#split), -[string](\.\./\.\./\.\./\.\./index\.md\#string) - -# KEYWORDS - -[string](\.\./\.\./\.\./\.\./index\.md\#string), [template -processing](\.\./\.\./\.\./\.\./index\.md\#template\_processing), [text -expansion](\.\./\.\./\.\./\.\./index\.md\#text\_expansion) - -# CATEGORY - -Documentation tools - -# COPYRIGHT - -Copyright © William H\. Duquette, http://www\.wjduquette\.com/expand DELETED embedded/md/tcllib/files/modules/textutil/patch.md Index: embedded/md/tcllib/files/modules/textutil/patch.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/patch.md +++ embedded/md/tcllib/files/modules/textutil/patch.md @@ -1,108 +0,0 @@ - -[//000000001]: # (textutil::patch \- Text and string utilities) -[//000000002]: # (Generated from file 'patch\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::patch\(n\) 0\.1 tcllib "Text and string utilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::patch \- Application of uni\-diff patches to directory trees - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::patch ?0\.1? - -[__::textutil::patch::apply__ *basedirectory* *striplevel* *patch* *reportcmd*](#1) -[__\{\*\}reportcmd__ __apply__ *filename*](#2) -[__\{\*\}reportcmd__ __fail__ *filename* *hunk* *expected* *seen*](#3) -[__\{\*\}reportcmd__ __fail\-already__ *filename* *hunk*](#4) - -# DESCRIPTION - -This package provides a single command which applies a patch in [unified -format](https://www\.gnu\.org/software/diffutils/manual/html\_node/Detailed\-Unified\.html) -to a directory tree\. - - - __::textutil::patch::apply__ *basedirectory* *striplevel* *patch* *reportcmd* - - Applies the *patch* \(text of the path, not file\) to the files in the - *basedirectory* using the specified *striplevel*\. The result of the - command is the empty string\. - - The *striplevel* argument is equivalent to option __\-p__ of the - __[patch](\.\./\.\./\.\./\.\./index\.md\#patch)__ command\. - - Errors are thrown when the *patch* does not parse, and nothing is done to - the files in *basedirectory*\. - - All activities during the application of the patch, including the inability - to apply a hunk are reported through the command prefix *reportcmd* - instead\. Files with problems are left unchanged\. Note however that this does - *not prevent* changes to files with no problems, before and after the - problematic file\(s\)\. - - The command prefix is called in 3 possible forms: - - * __\{\*\}reportcmd__ __apply__ *filename* - - The caller begins operation on file *fname*, applying all hunks - collected for said file\. - - * __\{\*\}reportcmd__ __fail__ *filename* *hunk* *expected* *seen* - - Application of hunk number *hunk* of file *filename* has failed\. The - command expected to find the text *expected*, and saw *seen* - instead\. - - * __\{\*\}reportcmd__ __fail\-already__ *filename* *hunk* - - Application of hunk number *hunk* of file *filename* has failed\. The - command believes that this hunk has already been applied to the file\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[diff \-ruN](\.\./\.\./\.\./\.\./index\.md\#diff\_run), [diff, unified -format](\.\./\.\./\.\./\.\./index\.md\#diff\_unified\_format), -[fossil](\.\./\.\./\.\./\.\./index\.md\#fossil), [git](\.\./\.\./\.\./\.\./index\.md\#git), -[patch](\.\./\.\./\.\./\.\./index\.md\#patch), [unified format -diff](\.\./\.\./\.\./\.\./index\.md\#unified\_format\_diff) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/repeat.md Index: embedded/md/tcllib/files/modules/textutil/repeat.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/repeat.md +++ embedded/md/tcllib/files/modules/textutil/repeat.md @@ -1,90 +0,0 @@ - -[//000000001]: # (textutil::repeat \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'repeat\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::repeat\(n\) 0\.7\.1 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::repeat \- Procedures to repeat strings\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::repeat ?0\.7? - -[__::textutil::repeat::strRepeat__ *text* *num*](#1) -[__::textutil::repeat::blank__ *num*](#2) - -# DESCRIPTION - -The package __textutil::repeat__ provides commands to generate long strings -by repeating a shorter string many times\. - -The complete set of procedures is described below\. - - - __::textutil::repeat::strRepeat__ *text* *num* - - This command returns a string containing the *text* repeated *num* - times\. The repetitions are joined without characters between them\. A value - of *num* <= 0 causes the command to return an empty string\. - - *Note*: If the Tcl core the package is loaded in provides the command - __string repeat__ then this command will be implemented in its terms, - for maximum possible speed\. Otherwise a fast implementation in Tcl will be - used\. - - - __::textutil::repeat::blank__ *num* - - A convenience command\. Returns a string of *num* spaces\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[blanks](\.\./\.\./\.\./\.\./index\.md\#blanks), -[repetition](\.\./\.\./\.\./\.\./index\.md\#repetition), -[string](\.\./\.\./\.\./\.\./index\.md\#string) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/tabify.md Index: embedded/md/tcllib/files/modules/textutil/tabify.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/tabify.md +++ embedded/md/tcllib/files/modules/textutil/tabify.md @@ -1,114 +0,0 @@ - -[//000000001]: # (textutil::tabify \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'tabify\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::tabify\(n\) 0\.7 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::tabify \- Procedures to \(un\)tabify strings - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::tabify ?0\.7? - -[__::textutil::tabify::tabify__ *string* ?*num*?](#1) -[__::textutil::tabify::tabify2__ *string* ?*num*?](#2) -[__::textutil::tabify::untabify__ *string* ?*num*?](#3) -[__::textutil::tabify::untabify2__ *string* ?*num*?](#4) - -# DESCRIPTION - -The package __textutil::tabify__ provides commands that convert between -tabulation and ordinary whitespace in strings\. - -The complete set of procedures is described below\. - - - __::textutil::tabify::tabify__ *string* ?*num*? - - Tabify the *string* by replacing any substring of *num* space chars by a - tabulation and return the result as a new string\. *num* defaults to 8\. - - - __::textutil::tabify::tabify2__ *string* ?*num*? - - Similar to __::textutil::tabify__ this command tabifies the *string* - and returns the result as a new string\. A different algorithm is used - however\. Instead of replacing any substring of *num* spaces this command - works more like an editor\. *num* defaults to 8\. - - Each line of the text in *string* is treated as if there are tabstops - every *num* columns\. Only sequences of space characters containing more - than one space character and found immediately before a tabstop are replaced - with tabs\. - - - __::textutil::tabify::untabify__ *string* ?*num*? - - Untabify the *string* by replacing any tabulation char by a substring of - *num* space chars and return the result as a new string\. *num* defaults - to 8\. - - - __::textutil::tabify::untabify2__ *string* ?*num*? - - Untabify the *string* by replacing any tabulation char by a substring of - at most *num* space chars and return the result as a new string\. Unlike - __textutil::tabify::untabify__ each tab is not replaced by a fixed - number of space characters\. The command overlays each line in the *string* - with tabstops every *num* columns instead and replaces tabs with just - enough space characters to reach the next tabstop\. This is the complement of - the actions taken by __::textutil::tabify::tabify2__\. *num* defaults - to 8\. - - There is one asymmetry though: A tab can be replaced with a single space, - but not the other way around\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[tabstops](\.\./\.\./\.\./\.\./index\.md\#tabstops) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/textutil.md Index: embedded/md/tcllib/files/modules/textutil/textutil.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/textutil.md +++ embedded/md/tcllib/files/modules/textutil/textutil.md @@ -1,404 +0,0 @@ - -[//000000001]: # (textutil \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'textutil\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil\(n\) 0\.8 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil \- Procedures to manipulate texts and strings\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil ?0\.8? - -[__::textutil::adjust__ *string args*](#1) -[__::textutil::adjust::readPatterns__ *filename*](#2) -[__::textutil::adjust::listPredefined__](#3) -[__::textutil::adjust::getPredefined__ *filename*](#4) -[__::textutil::indent__ *string* *prefix* ?*skip*?](#5) -[__::textutil::undent__ *string*](#6) -[__::textutil::splitn__ *string* ?*len*?](#7) -[__::textutil::splitx__ *string* ?*regexp*?](#8) -[__::textutil::tabify__ *string* ?*num*?](#9) -[__::textutil::tabify2__ *string* ?*num*?](#10) -[__::textutil::trim__ *string* ?*regexp*?](#11) -[__::textutil::trimleft__ *string* ?*regexp*?](#12) -[__::textutil::trimright__ *string* ?*regexp*?](#13) -[__::textutil::trimPrefix__ *string* *prefix*](#14) -[__::textutil::trimEmptyHeading__ *string*](#15) -[__::textutil::untabify__ *string* ?*num*?](#16) -[__::textutil::untabify2__ *string* ?*num*?](#17) -[__::textutil::strRepeat__ *text num*](#18) -[__::textutil::blank__ *num*](#19) -[__::textutil::chop__ *string*](#20) -[__::textutil::tail__ *string*](#21) -[__::textutil::cap__ *string*](#22) -[__::textutil::uncap__ *string*](#23) -[__::textutil::longestCommonPrefixList__ *list*](#24) -[__::textutil::longestCommonPrefix__ ?*string*\.\.\.?](#25) - -# DESCRIPTION - -The package __textutil__ provides commands that manipulate strings or texts -\(a\.k\.a\. long strings or string with embedded newlines or paragraphs\)\. It is -actually a bundle providing the commands of the six packages - - - __[textutil::adjust](adjust\.md)__ - - - __[textutil::repeat](repeat\.md)__ - - - __[textutil::split](textutil\_split\.md)__ - - - __[textutil::string](textutil\_string\.md)__ - - - __[textutil::tabify](tabify\.md)__ - - - __[textutil::trim](trim\.md)__ - -in the namespace __textutil__\. - -The bundle is *deprecated*, and it will be removed in a future release of -Tcllib, after the next release\. It is recommended to use the relevant sub -packages instead for whatever functionality is needed by the using package or -application\. - -The complete set of procedures is described below\. - - - __::textutil::adjust__ *string args* - - Do a justification on the *string* according to *args*\. The string is - taken as one big paragraph, ignoring any newlines\. Then the line is - formatted according to the options used, and the command return a new string - with enough lines to contain all the printable chars in the input string\. A - line is a set of chars between the beginning of the string and a newline, or - between 2 newlines, or between a newline and the end of the string\. If the - input string is small enough, the returned string won't contain any - newlines\. - - Together with __::textutil::indent__ it is possible to create properly - wrapped paragraphs with arbitrary indentations\. - - By default, any occurrence of spaces characters or tabulation are replaced - by a single space so each word in a line is separated from the next one by - exactly one space char, and this forms a *real* line\. Each *real* line - is placed in a *logical* line, which have exactly a given length \(see - __\-length__ option below\)\. The *real* line may have a lesser length\. - Again by default, any trailing spaces are ignored before returning the - string \(see __\-full__ option below\)\. The following options may be used - after the *string* parameter, and change the way the command place a - *real* line in a *logical* line\. - - * \-full *boolean* - - If set to __false__, any trailing space chars are deleted before - returning the string\. If set to __true__, any trailing space chars - are left in the string\. Default to __false__\. - - * __\-hyphenate__ *boolean* - - if set to __false__, no hyphenation will be done\. If set to - __true__, the last word of a line is tried to be hyphenated\. - Defaults to __false__\. Note: hyphenation patterns must be loaded - prior, using the command __::textutil::adjust::readPatterns__\. - - * __\-justify__ __center|left|plain|right__ - - Set the justification of the returned string to __center__, - __left__, __plain__ or __right__\. By default, it is set to - __left__\. The justification means that any line in the returned - string but the last one is build according to the value\. If the - justification is set to __plain__ and the number of printable chars - in the last line is less than 90% of the length of a line \(see - __\-length__\), then this line is justified with the __left__ - value, avoiding the expansion of this line when it is too small\. The - meaning of each value is: - - + __center__ - - The real line is centered in the logical line\. If needed, a set of - space characters are added at the beginning \(half of the needed set\) - and at the end \(half of the needed set\) of the line if required \(see - the option __\-full__\)\. - - + __left__ - - The real line is set on the left of the logical line\. It means that - there are no space chars at the beginning of this line\. If required, - all needed space chars are added at the end of the line \(see the - option __\-full__\)\. - - + __plain__ - - The real line is exactly set in the logical line\. It means that - there are no leading or trailing space chars\. All the needed space - chars are added in the *real* line, between 2 \(or more\) words\. - - + __right__ - - The real line is set on the right of the logical line\. It means that - there are no space chars at the end of this line, and there may be - some space chars at the beginning, despite of the __\-full__ - option\. - - * __\-length__ *integer* - - Set the length of the *logical* line in the string to *integer*\. - *integer* must be a positive integer value\. Defaults to __72__\. - - * __\-strictlength__ *boolean* - - If set to __false__, a line can exceed the specified __\-length__ - if a single word is longer than __\-length__\. If set to __true__, - words that are longer than __\-length__ are split so that no line - exceeds the specified __\-length__\. Defaults to __false__\. - - - __::textutil::adjust::readPatterns__ *filename* - - Loads the internal storage for hyphenation patterns with the contents of the - file *filename*\. This has to be done prior to calling command - __::textutil::adjust__ with "__\-hyphenate__ __true__", or the - hyphenation process will not work correctly\. - - The package comes with a number of predefined pattern files, and the command - __::textutil::adjust::listPredefined__ can be used to find out their - names\. - - - __::textutil::adjust::listPredefined__ - - This command returns a list containing the names of the hyphenation files - coming with this package\. - - - __::textutil::adjust::getPredefined__ *filename* - - Use this command to query the package for the full path name of the - hyphenation file *filename* coming with the package\. Only the filenames - found in the list returned by __::textutil::adjust::listPredefined__ are - legal arguments for this command\. - - - __::textutil::indent__ *string* *prefix* ?*skip*? - - Each line in the *string* indented by adding the string *prefix* at its - beginning\. The modified string is returned as the result of the command\. - - If *skip* is specified the first *skip* lines are left untouched\. The - default for *skip* is __0__, causing the modification of all lines\. - Negative values for *skip* are treated like __0__\. In other words, - *skip* > __0__ creates a hanging indentation\. - - Together with __::textutil::adjust__ it is possible to create properly - wrapped paragraphs with arbitrary indentations\. - - - __::textutil::undent__ *string* - - The command computes the common prefix for all lines in *string* - consisting solely out of whitespace, removes this from each line and returns - the modified string\. - - Lines containing only whitespace are always reduced to completely empty - lines\. They and empty lines are also ignored when computing the prefix to - remove\. - - Together with __::textutil::adjust__ it is possible to create properly - wrapped paragraphs with arbitrary indentations\. - - - __::textutil::splitn__ *string* ?*len*? - - This command splits the given *string* into chunks of *len* characters - and returns a list containing these chunks\. The argument *len* defaults to - __1__ if none is specified\. A negative length is not allowed and will - cause the command to throw an error\. Providing an empty string as input is - allowed, the command will then return an empty list\. If the length of the - *string* is not an entire multiple of the chunk length, then the last - chunk in the generated list will be shorter than *len*\. - - - __::textutil::splitx__ *string* ?*regexp*? - - Split the *string* and return a list\. The string is split according to the - regular expression *regexp* instead of a simple list of chars\. Note that - if you add parenthesis into the *regexp*, the parentheses part of - separator would be added into list as additional element\. If the *string* - is empty the result is the empty list, like for - __[split](\.\./\.\./\.\./\.\./index\.md\#split)__\. If *regexp* is empty the - *string* is split at every character, like - __[split](\.\./\.\./\.\./\.\./index\.md\#split)__ does\. The regular expression - *regexp* defaults to "\[\\\\t \\\\r\\\\n\]\+"\. - - - __::textutil::tabify__ *string* ?*num*? - - Tabify the *string* by replacing any substring of *num* space chars by a - tabulation and return the result as a new string\. *num* defaults to 8\. - - - __::textutil::tabify2__ *string* ?*num*? - - Similar to __::textutil::tabify__ this command tabifies the *string* - and returns the result as a new string\. A different algorithm is used - however\. Instead of replacing any substring of *num* spaces this command - works more like an editor\. *num* defaults to 8\. - - Each line of the text in *string* is treated as if there are tabstops - every *num* columns\. Only sequences of space characters containing more - than one space character and found immediately before a tabstop are replaced - with tabs\. - - - __::textutil::trim__ *string* ?*regexp*? - - Remove in *string* any leading and trailing substring according to the - regular expression *regexp* and return the result as a new string\. This - apply on any *line* in the string, that is any substring between 2 newline - chars, or between the beginning of the string and a newline, or between a - newline and the end of the string, or, if the string contain no newline, - between the beginning and the end of the string\. The regular expression - *regexp* defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trimleft__ *string* ?*regexp*? - - Remove in *string* any leading substring according to the regular - expression *regexp* and return the result as a new string\. This apply on - any *line* in the string, that is any substring between 2 newline chars, - or between the beginning of the string and a newline, or between a newline - and the end of the string, or, if the string contain no newline, between the - beginning and the end of the string\. The regular expression *regexp* - defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trimright__ *string* ?*regexp*? - - Remove in *string* any trailing substring according to the regular - expression *regexp* and return the result as a new string\. This apply on - any *line* in the string, that is any substring between 2 newline chars, - or between the beginning of the string and a newline, or between a newline - and the end of the string, or, if the string contain no newline, between the - beginning and the end of the string\. The regular expression *regexp* - defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trimPrefix__ *string* *prefix* - - Removes the *prefix* from the beginning of *string* and returns the - result\. The *string* is left unchanged if it doesn't have *prefix* at - its beginning\. - - - __::textutil::trimEmptyHeading__ *string* - - Looks for empty lines \(including lines consisting of only whitespace\) at the - beginning of the *string* and removes it\. The modified string is returned - as the result of the command\. - - - __::textutil::untabify__ *string* ?*num*? - - Untabify the *string* by replacing any tabulation char by a substring of - *num* space chars and return the result as a new string\. *num* defaults - to 8\. - - - __::textutil::untabify2__ *string* ?*num*? - - Untabify the *string* by replacing any tabulation char by a substring of - at most *num* space chars and return the result as a new string\. Unlike - __textutil::untabify__ each tab is not replaced by a fixed number of - space characters\. The command overlays each line in the *string* with - tabstops every *num* columns instead and replaces tabs with just enough - space characters to reach the next tabstop\. This is the complement of the - actions taken by __::textutil::tabify2__\. *num* defaults to 8\. - - There is one asymmetry though: A tab can be replaced with a single space, - but not the other way around\. - - - __::textutil::strRepeat__ *text num* - - The implementation depends on the core executing the package\. Used - __string repeat__ if it is present, or a fast tcl implementation if it - is not\. Returns a string containing the *text* repeated *num* times\. The - repetitions are joined without characters between them\. A value of *num* - <= 0 causes the command to return an empty string\. - - - __::textutil::blank__ *num* - - A convenience command\. Returns a string of *num* spaces\. - - - __::textutil::chop__ *string* - - A convenience command\. Removes the last character of *string* and returns - the shortened string\. - - - __::textutil::tail__ *string* - - A convenience command\. Removes the first character of *string* and returns - the shortened string\. - - - __::textutil::cap__ *string* - - Capitalizes the first character of *string* and returns the modified - string\. - - - __::textutil::uncap__ *string* - - The complementary operation to __::textutil::cap__\. Forces the first - character of *string* to lower case and returns the modified string\. - - - __::textutil::longestCommonPrefixList__ *list* - - - __::textutil::longestCommonPrefix__ ?*string*\.\.\.? - - Computes the longest common prefix for either the *string*s given to the - command, or the strings specified in the single *list*, and returns it as - the result of the command\. - - If no strings were specified the result is the empty string\. If only one - string was specified, the string itself is returned, as it is its own - longest common prefix\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[TeX](\.\./\.\./\.\./\.\./index\.md\#tex), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[hyphenation](\.\./\.\./\.\./\.\./index\.md\#hyphenation), -[indenting](\.\./\.\./\.\./\.\./index\.md\#indenting), -[paragraph](\.\./\.\./\.\./\.\./index\.md\#paragraph), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[trimming](\.\./\.\./\.\./\.\./index\.md\#trimming) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/textutil_split.md Index: embedded/md/tcllib/files/modules/textutil/textutil_split.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/textutil_split.md +++ embedded/md/tcllib/files/modules/textutil/textutil_split.md @@ -1,97 +0,0 @@ - -[//000000001]: # (textutil::split \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'textutil\_split\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::split\(n\) 0\.8 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::split \- Procedures to split texts - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::split ?0\.8? - -[__::textutil::split::splitn__ *string* ?*len*?](#1) -[__::textutil::split::splitx__ *string* ?*regexp*?](#2) - -# DESCRIPTION - -The package __textutil::split__ provides commands that split strings by size -and arbitrary regular expressions\. - -The complete set of procedures is described below\. - - - __::textutil::split::splitn__ *string* ?*len*? - - This command splits the given *string* into chunks of *len* characters - and returns a list containing these chunks\. The argument *len* defaults to - __1__ if none is specified\. A negative length is not allowed and will - cause the command to throw an error\. Providing an empty string as input is - allowed, the command will then return an empty list\. If the length of the - *string* is not an entire multiple of the chunk length, then the last - chunk in the generated list will be shorter than *len*\. - - - __::textutil::split::splitx__ *string* ?*regexp*? - - This command splits the *string* and return a list\. The string is split - according to the regular expression *regexp* instead of a simple list of - chars\. *Note*: When parentheses are used in the *regexp*, i\.e\. regex - capture groups, then these groups will be added into the result list as - additional elements\. If the *string* is empty the result is the empty - list, like for __[split](\.\./\.\./\.\./\.\./index\.md\#split)__\. If - *regexp* is empty the *string* is split at every character, like - __[split](\.\./\.\./\.\./\.\./index\.md\#split)__ does\. The regular expression - *regexp* defaults to "\[\\\\t \\\\r\\\\n\]\+"\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[regular expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), -[split](\.\./\.\./\.\./\.\./index\.md\#split), -[string](\.\./\.\./\.\./\.\./index\.md\#string) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/textutil_string.md Index: embedded/md/tcllib/files/modules/textutil/textutil_string.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/textutil_string.md +++ embedded/md/tcllib/files/modules/textutil/textutil_string.md @@ -1,122 +0,0 @@ - -[//000000001]: # (textutil::string \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'textutil\_string\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::string\(n\) 0\.8 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::string \- Procedures to manipulate texts and strings\. - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::string ?0\.8? - -[__::textutil::string::chop__ *string*](#1) -[__::textutil::string::tail__ *string*](#2) -[__::textutil::string::cap__ *string*](#3) -[__::textutil::string::capEachWord__ *string*](#4) -[__::textutil::string::uncap__ *string*](#5) -[__::textutil::string::longestCommonPrefixList__ *list*](#6) -[__::textutil::string::longestCommonPrefix__ ?*string*\.\.\.?](#7) - -# DESCRIPTION - -The package __textutil::string__ provides miscellaneous string manipulation -commands\. - -The complete set of procedures is described below\. - - - __::textutil::string::chop__ *string* - - A convenience command\. Removes the last character of *string* and returns - the shortened string\. - - - __::textutil::string::tail__ *string* - - A convenience command\. Removes the first character of *string* and returns - the shortened string\. - - - __::textutil::string::cap__ *string* - - Capitalizes the first character of *string* and returns the modified - string\. - - - __::textutil::string::capEachWord__ *string* - - Capitalizes the first character of word of the *string* and returns the - modified string\. Words quoted with either backslash or dollar\-sign are left - untouched\. - - - __::textutil::string::uncap__ *string* - - The complementary operation to __::textutil::string::cap__\. Forces the - first character of *string* to lower case and returns the modified string\. - - - __::textutil::string::longestCommonPrefixList__ *list* - - - __::textutil::string::longestCommonPrefix__ ?*string*\.\.\.? - - Computes the longest common prefix for either the *string*s given to the - command, or the strings specified in the single *list*, and returns it as - the result of the command\. - - If no strings were specified the result is the empty string\. If only one - string was specified, the string itself is returned, as it is its own - longest common prefix\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[capitalize](\.\./\.\./\.\./\.\./index\.md\#capitalize), -[chop](\.\./\.\./\.\./\.\./index\.md\#chop), [common -prefix](\.\./\.\./\.\./\.\./index\.md\#common\_prefix), -[formatting](\.\./\.\./\.\./\.\./index\.md\#formatting), -[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[uncapitalize](\.\./\.\./\.\./\.\./index\.md\#uncapitalize) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/textutil/trim.md Index: embedded/md/tcllib/files/modules/textutil/trim.md ================================================================== --- embedded/md/tcllib/files/modules/textutil/trim.md +++ embedded/md/tcllib/files/modules/textutil/trim.md @@ -1,121 +0,0 @@ - -[//000000001]: # (textutil::trim \- Text and string utilities, macro processing) -[//000000002]: # (Generated from file 'trim\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (textutil::trim\(n\) 0\.7 tcllib "Text and string utilities, macro processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -textutil::trim \- Procedures to trim strings - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require textutil::trim ?0\.7? - -[__::textutil::trim::trim__ *string* ?*regexp*?](#1) -[__::textutil::trim::trimleft__ *string* ?*regexp*?](#2) -[__::textutil::trim::trimright__ *string* ?*regexp*?](#3) -[__::textutil::trim::trimPrefix__ *string* *prefix*](#4) -[__::textutil::trim::trimEmptyHeading__ *string*](#5) - -# DESCRIPTION - -The package __textutil::trim__ provides commands that trim strings using -arbitrary regular expressions\. - -The complete set of procedures is described below\. - - - __::textutil::trim::trim__ *string* ?*regexp*? - - Remove in *string* any leading and trailing substring according to the - regular expression *regexp* and return the result as a new string\. This is - done for all *lines* in the string, that is any substring between 2 - newline chars, or between the beginning of the string and a newline, or - between a newline and the end of the string, or, if the string contain no - newline, between the beginning and the end of the string\. The regular - expression *regexp* defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trim::trimleft__ *string* ?*regexp*? - - Remove in *string* any leading substring according to the regular - expression *regexp* and return the result as a new string\. This apply on - any *line* in the string, that is any substring between 2 newline chars, - or between the beginning of the string and a newline, or between a newline - and the end of the string, or, if the string contain no newline, between the - beginning and the end of the string\. The regular expression *regexp* - defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trim::trimright__ *string* ?*regexp*? - - Remove in *string* any trailing substring according to the regular - expression *regexp* and return the result as a new string\. This apply on - any *line* in the string, that is any substring between 2 newline chars, - or between the beginning of the string and a newline, or between a newline - and the end of the string, or, if the string contain no newline, between the - beginning and the end of the string\. The regular expression *regexp* - defaults to "\[ \\\\t\]\+"\. - - - __::textutil::trim::trimPrefix__ *string* *prefix* - - Removes the *prefix* from the beginning of *string* and returns the - result\. The *string* is left unchanged if it doesn't have *prefix* at - its beginning\. - - - __::textutil::trim::trimEmptyHeading__ *string* - - Looks for empty lines \(including lines consisting of only whitespace\) at the - beginning of the *string* and removes it\. The modified string is returned - as the result of the command\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *textutil* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -regexp\(n\), split\(n\), string\(n\) - -# KEYWORDS - -[prefix](\.\./\.\./\.\./\.\./index\.md\#prefix), [regular -expression](\.\./\.\./\.\./\.\./index\.md\#regular\_expression), -[string](\.\./\.\./\.\./\.\./index\.md\#string), -[trimming](\.\./\.\./\.\./\.\./index\.md\#trimming) - -# CATEGORY - -Text processing DELETED embedded/md/tcllib/files/modules/tie/tie.md Index: embedded/md/tcllib/files/modules/tie/tie.md ================================================================== --- embedded/md/tcllib/files/modules/tie/tie.md +++ embedded/md/tcllib/files/modules/tie/tie.md @@ -1,515 +0,0 @@ - -[//000000001]: # (tie \- Tcl Data Structures) -[//000000002]: # (Generated from file 'tie\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004\-2008 Andreas Kupries ) -[//000000004]: # (tie\(n\) 1\.1 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tie \- Array persistence - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [USING TIES](#section2) - - - [TIE API](#subsection1) - - - [STANDARD DATA SOURCE TYPES](#subsection2) - - - [CREATING NEW DATA SOURCES](#section3) - - - [DATA SOURCE OBJECTS](#subsection3) - - - [REGISTERING A NEW DATA SOURCE CLASS](#subsection4) - - - [DATA SOURCE CLASS](#subsection5) - - - [DATA SOURCE OBJECT API](#subsection6) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require tie ?1\.1? - -[__::tie::tie__ *arrayvarname* *options*\.\.\. *dstype* *dsname*\.\.\.](#1) -[__::tie::untie__ *arrayvarname* ?*token*?](#2) -[__::tie::info__ __ties__ *arrayvarname*](#3) -[__::tie::info__ __types__](#4) -[__::tie::info__ __type__ *dstype*](#5) -[__::tie::register__ *dsclasscmd* __as__ *dstype*](#6) -[__dsclasscmd__ *objname* ?*dsname*\.\.\.?](#7) -[__ds__ __destroy__](#8) -[__ds__ __names__](#9) -[__ds__ __size__](#10) -[__ds__ __get__](#11) -[__ds__ __set__ *dict*](#12) -[__ds__ __unset__ ?*pattern*?](#13) -[__ds__ __setv__ *index* *value*](#14) -[__ds__ __unsetv__ *index*](#15) -[__ds__ __getv__ *index*](#16) - -# DESCRIPTION - -The __tie__ package provides a framework for the creation of persistent Tcl -array variables\. It should be noted that the provided mechanism is generic -enough to also allow its usage for the distribution of the contents of Tcl -arrays over multiple threads and processes, i\.e\. communication\. - -This, persistence and communication, is accomplished by *tying*\) a Tcl array -variable to a *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. Examples -of data sources are other Tcl arrays and files\. - -It should be noted that a single Tcl array variable can be tied to more than one -*[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. It is this feature -which allows the framework to be used for communication as well\. Just tie -several Tcl arrays in many client processes to a Tcl array in a server and all -changes to any of them will be distributed to all\. Less centralized variants of -this are of course possible as well\. - -# USING TIES - -## TIE API - -This section describes the basic API used to establish and remove ties between -Tcl array variables and data sources\. This interface is the only one a casual -user has to be concerned about\. The following sections about the various -internal interfaces can be safely skipped\. - - - __::tie::tie__ *arrayvarname* *options*\.\.\. *dstype* *dsname*\.\.\. - - This command establishes a tie between the Tcl array whose name is provided - by the argument *arrayvarname* and the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* identified by the *dstype* - and its series of *dsname* arguments\. All changes made to the Tcl array - after this command returns will be saved to the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* for safekeeping \(or - distribution\)\. - - The result of the command is always a token which identifies the new tie\. - This token can be used later to destroy this specific tie\. - - * varname *arrayvarname* \(in\) - - The name of the Tcl array variable to connect the new tie to\. - - * name|command *dstype* \(in\) - - This argument specifies the type of the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* we wish to access\. The - *dstype* can be one of __log__, __array__, - __remotearray__, __file__, __growfile__, or __dsource__; - in addition, the programmer can register additional data source types\. - Each *dstype* is followed by one or more arguments that identify the - *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* to which the - array is to be tied\. - - * string *dsname* \(in\) - - The series of *dsname* arguments coming after the *dstype* - identifies the *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* - we wish to connect to, and has to be appropriate for the chosen type\. - - The command understands a number of additional options which guide the - process of setting up the connection between Tcl array and *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. - - * __\-open__ - - The Tcl array for the new tie is *loaded* from the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*, and the previously - existing contents of the Tcl array are erased\. Care is taken to *not* - erase the previous contents should the creation of the tie fail\. - - This option and the option __\-save__ exclude each other\. If neither - this nor option __\-save__ are specified then this option is assumed - as default\. - - * __\-save__ - - The Tcl array for the new tie is *saved* to the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*, and the previously - existing contents of the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* are erased\. - - This option and the option __\-open__ exclude each other\. If neither - this nor option __\-open__ are specified then option __\-open__ is - assumed as default\. - - * __\-merge__ - - Using this option prevents the erasure of any previously existing - content and merges the data instead\. It can be specified in conjunction - with either __\-open__ or __\-save__\. They determine how data - existing in both Tcl array and *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*, i\.e duplicates, are - dealt with\. - - When used with __\-open__ data in the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* has precedence\. In other - words, for duplicates the data in the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* is loaded into the Tcl - array\. - - When used with __\-save__ data in the Tcl array has precedence\. In - other words, for duplicates the data in the Tcl array is saved into the - *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. - - - __::tie::untie__ *arrayvarname* ?*token*? - - This command dissolves one or more ties associated with the Tcl array named - by *arrayvarname*\. If no *token* is specified then all ties to that Tcl - array are dissolved\. Otherwise only the tie the token stands for is removed, - if it is actually connected to the array\. Trying to remove a specific tie - not belonging to the provided array will cause an error\. - - It should be noted that while severing a tie will destroy management - information internal to the package the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* which was handled by the tie - will not be touched, only closed\. - - After the command returns none of changes made to the array will be saved to - the *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* anymore\. - - The result of the command is an empty string\. - - * varname *arrayname* \(in\) - - The name of a Tcl array variable which may have ties\. - - * handle *token* \(in\) - - A handle representing a specific tie\. This argument is optional\. - - - __::tie::info__ __ties__ *arrayvarname* - - This command returns a list of ties associated with the Tcl array variable - named by *arrayvarname*\. The result list will be empty if the variable has - no ties associated with it\. - - - __::tie::info__ __types__ - - This command returns a dictionary of registered types, and the class - commands they are associated with\. - - - __::tie::info__ __type__ *dstype* - - This command returns the fully resolved class command for a type name\. This - means that the command will follow a chain of type definitions ot its end\. - -## STANDARD DATA SOURCE TYPES - -This package provides the six following types as examples and standard data -sources\. - - - __log__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* does not - maintain any actual data, nor persistence\. It does not accept any - identifying arguments\. All changes are simply logged to __stdout__\. - - - __array__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* uses a regular - Tcl array as the origin of the persistent data\. It accepts a single - identifying argument, the name of this Tcl array\. All changes are mirrored - to that array\. - - - __remotearray__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* is similar to - __array__\. The difference is that the Tcl array to which we are - mirroring is not directly accessible, but through a - __[send](\.\./\.\./\.\./\.\./index\.md\#send)__\-like command\. - - It accepts three identifying arguments, the name of the other Tcl array, the - command prefix for the __[send](\.\./\.\./\.\./\.\./index\.md\#send)__\-like - accessor command, and an identifier for the remote entity hosting the array, - in this order\. All changes are mirrored to that array, via the command - prefix\. All commands will be executed in the context of the global - namespace\. - - __[send](\.\./\.\./\.\./\.\./index\.md\#send)__\-like means that the command - prefix has to have __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ syntax and - semantics\. I\.e\. it is a channel over which we can send arbitrary commands to - some other entity\. The remote array *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* however uses only the - commands __[set](\.\./\.\./\.\./\.\./index\.md\#set)__, __unset__, - __array exists__, __array names__, __array set__, and __array - get__ to retrieve and set values in the remote array\. - - The command prefix and the entity id are separate to allow the data source - to use options like __\-async__ when assembling the actual commands\. - - Examples of command prefixes, listed with the id of the remote entity, - without options\. In reality only the part before the id is the command - prefix: - - * __[send](\.\./\.\./\.\./\.\./index\.md\#send)__ *tkname* - - The Tcl array is in a remote interpreter and is accessed via Tk's X - communication\. - - * __comm::comm send__ *hostportid* - - The Tcl array is in a remote interpreter and is accessed through a - socket\. - - * __thread::send__ *threadid* - - The Tcl array is in a remote interpreter in a different thread of this - process\. - - - __file__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* uses a single - file as origin of the persistent data\. It accepts a single identifying - argument, the path to this file\. The file has to be both readable and - writable\. It may not exist, the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* will create it in that case\. - This \(and only this\) situation will require that the directory for the file - exists and is writable as well\. - - All changes are saved in the file, as proper Tcl commands, one command per - operation\. In other words, the file will always contain a proper Tcl script\. - - If the file exists when the tie using it is set up, then it will be - compacted, i\.e\. superfluous operations are removed, if the operations log - stored in it contains either at least one operation clearing the whole - array, or at least 1\.5 times more operations than entries in the loaded - array\. - - - __growfile__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* is like - __file__ in terms of the storage medium for the array data, and how it - is configured\. In constrast to the former it however assumes and ensures - that the tied array will never shrink\. I\.e\. the creation of new array - entries, and the modification of existing entries is allowed, but the - deletion of entries is not, and causes the data source to throw errors\. - - This restriction allows us to simplify both file format and access to the - file radically\. For one, the file is read only once and the internal cache - cannot be invalidated\. Second, writing data is reduced to a simple append, - and no compaction step is necessary\. The format of the contents is the - string representation of a dictionary which can be incrementally extended - forever at the end\. - - - __dsource__ - - This *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* uses an - explicitly specified *data source object* as the source for the persistent - data\. It accepts a single identifying argument, the command prefix, i\.e\. - object command\. - - To use this type it is necessary to know how the framework manages ties and - what [data source objects](#subsection3) are\. - - All changes are delegated to the specified object\. - -# CREATING NEW DATA SOURCES - -This section is of no interest to the casual user of ties\. Only developers -wishing to create new data sources have to know the information provided herein\. - -## DATA SOURCE OBJECTS - -All ties are represented internally by an in\-memory object which mediates -between the tie framework and the specific *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*, like an array, file, etc\. This -is the *data source object*\. - -Its class, the [data source class](#subsection5) is *not* generic, but -specific to the type of the *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. Writing a new *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* requires us to write such a -class, and then registering it with the framework as a new type\. - -The following subsections describe the various APIs a [data source -class](#subsection5) and the objects it generates will have to follow to be -compatible with the tie framework\. - -Data source objects are normally automatically created and destroyed by the -framework when a tie is created, or removed\. This management can be explicitly -bypassed through the usage of the "dsource" type\. The *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* for this type is a *data source -object* itself, and this object is outside of the scope of the tie framework -and not managed by it\. In other words, this type allows the creation of ties -which talk to pre\-existing *data source object*s, and these objects will -survive the removal of the ties using them as well\. - -## REGISTERING A NEW DATA SOURCE CLASS - -After a [data source class](#subsection5) has been written it is necessary -to register it as a new type with the framework\. - - - __::tie::register__ *dsclasscmd* __as__ *dstype* - - Using this command causes the tie framework to remember the class command - *dsclasscmd* of a [data source class](#subsection5) under the type - name *dstype*\. - - After the call the argument *dstype* of the basic user command - __::tie::tie__ will accept *dstype* as a type name and translate it - internally to the appropriate class command for the creation of [data - source objects](#subsection3) for the new *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. - -## DATA SOURCE CLASS - -Each data source class is represented by a single command, also called the -*class command*, or *object creation command*\. Its syntax is - - - __dsclasscmd__ *objname* ?*dsname*\.\.\.? - - The first argument of the class command is the name of the *data source - object* to create\. The framework itself will always supply the string - __%AUTO%__, to signal that the class command has to generate not only - the object, but the object name as well\. - - This is followed by a series of arguments identifying the data source the - new object is for\. These are the same *dsname* arguments which are given - to the basic user command __::tie::tie__\. Their actual meaning is - dependent on the *data source class*\. - - The result of the class command has to be the fully\-qualified name of the - new *data source object*, i\.e\. the name of the *object command*\. The - interface this command has to follow is described in the section [DATA - SOURCE OBJECT API](#subsection6) - -## DATA SOURCE OBJECT API - -Please read the section [DATA SOURCE CLASS](#subsection5) first, to know -how to generate new *object commands*\. - -Each *object command* for a *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* object has to provide at least -the methods listed below for proper inter\-operation with the tie framework\. Note -that the names of most of the methods match the subcommands of the builtin -__[array](\.\./\.\./\.\./\.\./index\.md\#array)__ command\. - - - __ds__ __destroy__ - - This method is called when the object __ds__ is destroyed\. It now has to - release all its internal resources associated with the external data source\. - - - __ds__ __names__ - - This command has to return a list containing the names of all keys found in - the *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the object talks - to\. This is equivalent to __array names__\. - - - __ds__ __size__ - - This command has to return an integer number specifying the number of keys - found in the *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the - object talks to\. This is equivalent to __array size__\. - - - __ds__ __get__ - - This command has to return a dictionary containing the data found in the - *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the object talks to\. - This is equivalent to __array get__\. - - - __ds__ __set__ *dict* - - This command takes a dictionary and adds its contents to the data source the - object talks to\. This is equivalent to __array set__\. - - - __ds__ __unset__ ?*pattern*? - - This command takes a pattern and removes all elements whose keys matching it - from the *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)*\. If no - pattern is specified it defaults to __\*__, causing the removal of all - elements\. This is nearly equivalent to __array unset__\. - - - __ds__ __setv__ *index* *value* - - This command has to save the *value* in the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the object talks to, under - the key *index*\. - - The result of the command is ignored\. If an error is thrown then this error - will show up as error of the set operation which caused the method call\. - - - __ds__ __unsetv__ *index* - - This command has to remove the value under the key *index* from the - *[data source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the object talks to\. - - The result of the command is ignored\. If an error is thrown then this error - will show up as error of the unset operation which caused the method call\. - - - __ds__ __getv__ *index* - - This command has to return the value for the key *index* in the *[data - source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* the object talks to\. - -And here a small table comparing the *[data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source)* methods to the regular Tcl -commands for accessing an array\. - - Regular Tcl Data source - ----------- ----------- - array names a ds names - array size a ds size - array get a ds get - array set a dict ds set dict - array unset a pattern ds unset ?pattern? - ----------- ----------- - set a($idx) $val ds setv idx val - unset a($idx) ds unsetv idx - $a($idx) ds getv idx - ----------- ----------- - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tie* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[array](\.\./\.\./\.\./\.\./index\.md\#array), -[database](\.\./\.\./\.\./\.\./index\.md\#database), -[file](\.\./\.\./\.\./\.\./index\.md\#file), -[metakit](\.\./\.\./\.\./\.\./index\.md\#metakit), -[persistence](\.\./\.\./\.\./\.\./index\.md\#persistence), -[tie](\.\./\.\./\.\./\.\./index\.md\#tie), [untie](\.\./\.\./\.\./\.\./index\.md\#untie) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2004\-2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/tie/tie_std.md Index: embedded/md/tcllib/files/modules/tie/tie_std.md ================================================================== --- embedded/md/tcllib/files/modules/tie/tie_std.md +++ embedded/md/tcllib/files/modules/tie/tie_std.md @@ -1,85 +0,0 @@ - -[//000000001]: # (tie \- Tcl Data Structures) -[//000000002]: # (Generated from file 'tie\_std\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008\-2015 Andreas Kupries ) -[//000000004]: # (tie\(n\) 1\.1 tcllib "Tcl Data Structures") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tie \- Array persistence, standard data sources - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require tie::std::log ?1\.0? -package require tie::std::array ?1\.0? -package require tie::std::rarray ?1\.0\.1? -package require tie::std::file ?1\.0\.4? -package require tie::std::growfile ?1\.0? -package require tie::std::dsource ?1\.0? - -# DESCRIPTION - -The packages listed as requirements for this document are internal packages -providing the standard data sources of package __[tie](tie\.md)__, as -described in section *STANDARD DATA SOURCE TYPES* of -__[tie](tie\.md)__'s documentation\. - -They are automatically loaded and registered by __[tie](tie\.md)__ when -it itself is requested, and as such there is no need to request them on their -own, although it is possible to do so\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tie* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[array](\.\./\.\./\.\./\.\./index\.md\#array), -[database](\.\./\.\./\.\./\.\./index\.md\#database), -[file](\.\./\.\./\.\./\.\./index\.md\#file), -[metakit](\.\./\.\./\.\./\.\./index\.md\#metakit), -[persistence](\.\./\.\./\.\./\.\./index\.md\#persistence), -[tie](\.\./\.\./\.\./\.\./index\.md\#tie), [untie](\.\./\.\./\.\./\.\./index\.md\#untie) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2008\-2015 Andreas Kupries DELETED embedded/md/tcllib/files/modules/tiff/tiff.md Index: embedded/md/tcllib/files/modules/tiff/tiff.md ================================================================== --- embedded/md/tcllib/files/modules/tiff/tiff.md +++ embedded/md/tcllib/files/modules/tiff/tiff.md @@ -1,267 +0,0 @@ - -[//000000001]: # (tiff \- TIFF image manipulation) -[//000000002]: # (Generated from file 'tiff\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2005\-2006, Aaron Faupell ) -[//000000004]: # (tiff\(n\) 0\.2\.1 tcllib "TIFF image manipulation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tiff \- TIFF reading, writing, and querying and manipulation of meta data - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [VARIABLES](#section3) - - - [LIMITATIONS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require tiff ?0\.2\.1? - -[__::tiff::isTIFF__ *file*](#1) -[__::tiff::byteOrder__ *file*](#2) -[__::tiff::numImages__ *file*](#3) -[__::tiff::dimensions__ *file* ?image?](#4) -[__::tiff::imageInfo__ *file* ?image?](#5) -[__::tiff::entries__ *file* ?image?](#6) -[__::tiff::getEntry__ *file* *entry* ?image?](#7) -[__::tiff::addEntry__ *file* *entry* ?image?](#8) -[__::tiff::deleteEntry__ *file* *entry* ?image?](#9) -[__::tiff::getImage__ *file* ?image?](#10) -[__::tiff::writeImage__ *image* *file* ?entry?](#11) -[__::tiff::nametotag__ *names*](#12) -[__::tiff::tagtoname__ *tags*](#13) -[__::tiff::debug__ *file*](#14) - -# DESCRIPTION - -This package provides commands to query, modify, read, and write TIFF images\. -TIFF stands for *Tagged Image File Format* and is a standard for lossless -storage of photographical images and associated metadata\. It is specified at -[http://partners\.adobe\.com/public/developer/tiff/index\.html](http://partners\.adobe\.com/public/developer/tiff/index\.html)\. - -Multiple images may be stored in a single TIFF file\. The ?image? options to the -functions in this package are for accessing images other than the first\. Data in -a TIFF image is stored as a series of tags having a numerical value, which are -represented in either a 4 digit hexadecimal format or a string name\. For a -reference on defined tags and their meanings see -[http://www\.awaresystems\.be/imaging/tiff/tifftags\.html](http://www\.awaresystems\.be/imaging/tiff/tifftags\.html) - -# COMMANDS - - - __::tiff::isTIFF__ *file* - - Returns a boolean value indicating if *file* is a TIFF image\. - - - __::tiff::byteOrder__ *file* - - Returns either __big__ or __little__\. Throws an error if *file* is - not a TIFF image\. - - - __::tiff::numImages__ *file* - - Returns the number of images in *file*\. Throws an error if *file* is not - a TIFF image\. - - - __::tiff::dimensions__ *file* ?image? - - Returns the dimensions of image number ?image? in *file* as a list of the - horizontal and vertical pixel count\. Throws an error if *file* is not a - TIFF image\. - - - __::tiff::imageInfo__ *file* ?image? - - Returns a dictionary with keys __ImageWidth__, __ImageLength__, - __BitsPerSample__, __Compression__, - __PhotometricInterpretation__, __ImageDescription__, - __Orientation__, __XResolution__, __YResolution__, - __ResolutionUnit__, __DateTime__, __Artist__, and - __HostComputer__\. The values are the associated properties of the TIFF - ?image? in *file*\. Values may be empty if the associated tag is not - present in the file\. - - puts [::tiff::imageInfo photo.tif] - - ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1 - PhotometricInterpretation 2 ImageDescription {} Orientation 1 - XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45} - Artist {} HostComputer {} - - There is nothing special about these tags, this is simply a convience - procedure which calls __getEntry__ with common entries\. Throws an error - if *file* is not a TIFF image\. - - - __::tiff::entries__ *file* ?image? - - Returns a list of all entries in the given *file* and ?image? in - hexadecimal format\. Throws an error if *file* is not a TIFF image\. - - - __::tiff::getEntry__ *file* *entry* ?image? - - Returns the value of *entry* from image ?image? in the TIFF *file*\. - *entry* may be a list of multiple entries\. If an entry does not exist, an - empty string is returned - - set data [::tiff::getEntry photo.tif {0131 0132}] - puts "file was written at [lindex $data 0] with software [lindex $data 1]" - - Throws an error if *file* is not a TIFF image\. - - - __::tiff::addEntry__ *file* *entry* ?image? - - Adds the specified entries to the image named by ?image? \(default 0\), or - optionally __all__\. *entry* must be a list where each element is a - list of tag, type, and value\. If a tag already exists, it is overwritten\. - - ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}} - - The data types are defined as follows - - * __1__ - - BYTE \(8 bit unsigned integer\) - - * __2__ - - ASCII - - * __3__ - - SHORT \(16 bit unsigned integer\) - - * __4__ - - LONG \(32 bit unsigned integer\) - - * __5__ - - RATIONAL - - * __6__ - - SBYTE \(8 bit signed byte\) - - * __7__ - - UNDEFINED \(uninterpreted binary data\) - - * __8__ - - SSHORT \(signed 16 bit integer\) - - * __9__ - - SLONG \(signed 32 bit integer\) - - * __10__ - - SRATIONAL - - * __11__ - - FLOAT \(32 bit floating point number\) - - * __12__ - - DOUBLE \(64 bit floating point number\) - - Throws an error if *file* is not a TIFF image\. - - - __::tiff::deleteEntry__ *file* *entry* ?image? - - Deletes the specified entries from the image named by ?image? \(default 0\), - or optionally __all__\. Throws an error if *file* is not a TIFF image\. - - - __::tiff::getImage__ *file* ?image? - - Returns the name of a Tk image containing the image at index ?image? from - *file* Throws an error if *file* is not a TIFF image, or if image is an - unsupported format\. Supported formats are uncompressed 24 bit RGB and - uncompressed 8 bit palette\. - - - __::tiff::writeImage__ *image* *file* ?entry? - - Writes the contents of the Tk image *image* to a tiff file *file*\. Files - are written in the 24 bit uncompressed format, with big endian byte order\. - Additional entries to be added to the image may be specified, in the same - format as __tiff::addEntry__ - - - __::tiff::nametotag__ *names* - - Returns a list with *names* translated from string to 4 digit format\. 4 - digit names in the input are passed through unchanged\. Strings without a - defined tag name will throw an error\. - - - __::tiff::tagtoname__ *tags* - - Returns a list with *tags* translated from 4 digit to string format\. If a - tag does not have a defined name it is passed through unchanged\. - - - __::tiff::debug__ *file* - - Prints everything we know about the given file in a nice format\. - -# VARIABLES - -The mapping of 4 digit tag names to string names uses the array -::tiff::tiff\_tags\. The reverse mapping uses the array ::tiff::tiff\_sgat\. - -# LIMITATIONS - - 1. Cannot write exif ifd - - 1. Reading limited to uncompressed 8 bit rgb and 8 bit palletized images - - 1. Writing limited to uncompressed 8 bit rgb - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tiff* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[image](\.\./\.\./\.\./\.\./index\.md\#image), [tif](\.\./\.\./\.\./\.\./index\.md\#tif), -[tiff](\.\./\.\./\.\./\.\./index\.md\#tiff) - -# CATEGORY - -File formats - -# COPYRIGHT - -Copyright © 2005\-2006, Aaron Faupell DELETED embedded/md/tcllib/files/modules/tool/meta.md Index: embedded/md/tcllib/files/modules/tool/meta.md ================================================================== --- embedded/md/tcllib/files/modules/tool/meta.md +++ embedded/md/tcllib/files/modules/tool/meta.md @@ -1,219 +0,0 @@ - -[//000000001]: # (oo::util \- Utility commands for TclOO) -[//000000002]: # (Generated from file 'meta\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011\-2015 Andreas Kupries, BSD licensed) -[//000000004]: # (oo::util\(n\) 1\.2\.2 tcllib "Utility commands for TclOO") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -oo::util \- Utility commands for TclOO - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [AUTHORS](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require oo::util ?1\.2\.2? - -[__mymethod__ *method* ?*arg*\.\.\.?](#1) -[__classmethod__ *name* *arguments* *body*](#2) -[__classvariable__ ?*arg*\.\.\.?](#3) -[__link__ *method*\.\.\.](#4) -[__link__ \{*alias* *method*\}\.\.\.](#5) -[__ooutil::singleton__ ?*arg*\.\.\.?](#6) - -# DESCRIPTION - -This package provides a convenience command for the easy specification of -instance methods as callback commands, like timers, file events, Tk bindings, -etc\. - -# COMMANDS - - - __mymethod__ *method* ?*arg*\.\.\.? - - This command is available within instance methods\. It takes a method name - and, possibly, arguments for the method and returns a command prefix which, - when executed, will invoke the named method of the object we are in, with - the provided arguments, and any others supplied at the time of actual - invokation\. - - Note: The command is equivalent to and named after the command provided by - the OO package __[snit](\.\./snit/snit\.md)__ for the same purpose\. - - - __classmethod__ *name* *arguments* *body* - - This command is available within class definitions\. It takes a method name - and, possibly, arguments for the method and creates a method on the class, - available to a user of the class and of derived classes\. - - Note: The command is equivalent to the command __typemethod__ provided - by the OO package __[snit](\.\./snit/snit\.md)__ for the same purpose\. - - Example - - oo::class create ActiveRecord { - classmethod find args { puts "[self] called with arguments: $args" } - } - oo::class create Table { - superclass ActiveRecord - } - puts [Table find foo bar] - # ====== - # which will write - # ====== - # ::Table called with arguments: foo bar - - - __classvariable__ ?*arg*\.\.\.? - - This command is available within instance methods\. It takes a series of - variable names and makes them available in the method's scope\. The - originating scope for the variables is the class \(instance\) the object - instance belongs to\. In other words, the referenced variables are shared - between all instances of their class\. - - Note: The command is roughly equivalent to the command __typevariable__ - provided by the OO package __[snit](\.\./snit/snit\.md)__ for the same - purpose\. The difference is that it cannot be used in the class definition - itself\. - - Example: - - % oo::class create Foo { - method bar {z} { - classvariable x y - return [incr x $z],[incr y] - } - } - ::Foo - % Foo create a - ::a - % Foo create b - ::b - % a bar 2 - 2,1 - % a bar 3 - 5,2 - % b bar 7 - 12,3 - % b bar -1 - 11,4 - % a bar 0 - 11,5 - - - __link__ *method*\.\.\. - - - __link__ \{*alias* *method*\}\.\.\. - - This command is available within instance methods\. It takes a list of method - names and/or pairs of alias\- and method\-name and makes the named methods - available to all instance methods without requiring the __my__ command\. - - The alias name under which the method becomes available defaults to the - method name, except where explicitly specified through an alias/method pair\. - - Examples: - - link foo - # The method foo is now directly accessible as foo instead of my foo. - - link {bar foo} - # The method foo is now directly accessible as bar. - - link a b c - # The methods a, b, and c all become directly acessible under their - # own names. - - The main use of this command is expected to be in instance constructors, for - convenience, or to set up some methods for use in a mini DSL\. - - - __ooutil::singleton__ ?*arg*\.\.\.? - - This command is a meta\-class, i\.e\. a variant of the builtin - __oo::class__ which ensures that it creates only a single instance of - the classes defined with it\. - - Syntax and results are like for __oo::class__\. - - Example: - - % oo::class create example { - self mixin singleton - method foo {} {self} - } - ::example - % [example new] foo - ::oo::Obj22 - % [example new] foo - ::oo::Obj22 - -# AUTHORS - -Donal Fellows, Andreas Kupries - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *oo::util* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[snit\(n\)](\.\./snit/snit\.md) - -# KEYWORDS - -[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), [class -methods](\.\./\.\./\.\./\.\./index\.md\#class\_methods), [class -variables](\.\./\.\./\.\./\.\./index\.md\#class\_variables), [command -prefix](\.\./\.\./\.\./\.\./index\.md\#command\_prefix), -[currying](\.\./\.\./\.\./\.\./index\.md\#currying), [method -reference](\.\./\.\./\.\./\.\./index\.md\#method\_reference), [my -method](\.\./\.\./\.\./\.\./index\.md\#my\_method), -[singleton](\.\./\.\./\.\./\.\./index\.md\#singleton) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2011\-2015 Andreas Kupries, BSD licensed DELETED embedded/md/tcllib/files/modules/tool/tool.md Index: embedded/md/tcllib/files/modules/tool/tool.md ================================================================== --- embedded/md/tcllib/files/modules/tool/tool.md +++ embedded/md/tcllib/files/modules/tool/tool.md @@ -1,313 +0,0 @@ - -[//000000001]: # (tool \- Standardized OO Framework for development) -[//000000002]: # (Generated from file 'tool\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Sean Woods ) -[//000000004]: # (tool\(n\) 0\.4\.2 tcllib "Standardized OO Framework for development") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tool \- TclOO Library \(TOOL\) Framework - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Keywords](#section2) - - - [Public Object Methods](#section3) - - - [Private Object Methods](#section4) - - - [AUTHORS](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require sha1 -package require dicttool -package require oo::meta -package require oo::dialect - -[tool::define __class\_method__ *arglist* *body*](#1) -[tool::define __[array](\.\./\.\./\.\./\.\./index\.md\#array)__ *name* *contents*](#2) -[tool::define __array\_ensemble__ *methodname* *varname* ?cases?](#3) -[tool::define __dict\_ensemble__ *methodname* *varname* ?cases?](#4) -[tool::define __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *methodname* *arglist* *body*](#5) -[tool::define __option__ *name* *dictopts*](#6) -[tool::define __property__ ?branch? *field* *value*](#7) -[tool::define __variable__ *name* *value*](#8) -[*object* __cget__ *option*](#9) -[*object* __configure__ ?keyvaluelist?](#10) -[*object* __configure__ *field* *value* ?field? ?value? ?\.\.\.?](#11) -[*object* __configurelist__ ?keyvaluelist?](#12) -[*object* __forward__ *stub* *forward*](#13) -[*object* __graft__ *stub* *forward*](#14) -[*object* __InitializePublic__](#15) -[*object* __Eval\_Script__ ?script?](#16) -[*object* __Option\_Default__ *field*](#17) - -# DESCRIPTION - -This module implements the Tcl Object Oriented Library framework, or *TOOL*\. -It is intended to be a general purpose framework that is useable in its own -right, and easily extensible\. - -TOOL defines a metaclass with provides several additional keywords to the TclOO -description langauge, default behaviors for its consituent objects, and top\-down -integration with the capabilities provided by the __oo::meta__ package\. - -The TOOL metaclass was build with the __oo::dialect__ package, and thus can -be used as the basis for additional metaclasses\. As a metaclass, TOOL has it's -own "class" class, "object" class, and define namespace\. - - package require tool - - # tool::class workds just like oo::class - tool::class create myclass { - } - - # tool::define works just like oo::define - tool::define myclass method noop {} {} - - # tool::define and tool::class understand additional keywords - tool::define myclass array_ensemble mysettings mysettings {} - - # And tool interoperates with oo::define - oo::define myclass method do_something {} { return something } - - # TOOL and TclOO objects are interchangeable - oo::class create myooclass { - superclass myclass - } - -Several manual pages go into more detail about specific keywords and methods\. - - - __tool::array\_ensemble__ - - - __[tool::dict\_ensemble](tool\_dict\_ensemble\.md)__ - - - __tool::method\_ensemble__ - - - __tool::object__ - - - __tool::option\_handling__ - -# Keywords - -TOOL adds new \(or modifies\) keywords used in the definitions of classes\. -However, the new keywords are only available via calls to *tool::class create* -or *tool::define* - - - tool::define __class\_method__ *arglist* *body* - - Defines a method for the class object itself\. This method will be passed on - to descendents of the class, unlike __self method__\. - - - tool::define __[array](\.\./\.\./\.\./\.\./index\.md\#array)__ *name* *contents* - - Declares a variable *name* which will be initialized as an array, - populated with *contents* for objects of this class, as well as any - objects for classes which are descendents of this class\. - - - tool::define __array\_ensemble__ *methodname* *varname* ?cases? - - Declares a method ensemble *methodname* which will control access to - variable *varname*\. Cases are a key/value list of method names and bodies - which will be overlaid on top of the standard template\. See - __tool::array\_ensemble__\. - - One method name is reserved: __initialize__\. __initialize__ Declares - the initial values to be populated in the array, as a key/value list, and - will not be expressed as a method for the ensemble\. - - - tool::define __dict\_ensemble__ *methodname* *varname* ?cases? - - Declares a method ensemble *methodname* which will control access to - variable *varname*\. Cases are a key/value list of method names and bodies - which will be overlaid on top of the standard template\. See - __[tool::dict\_ensemble](tool\_dict\_ensemble\.md)__\. - - One method name is reserved: __initialize__\. __initialize__ Declares - the initial values to be populated in the array, as a key/value list, and - will not be expressed as a method for the ensemble\. - - - tool::define __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ *methodname* *arglist* *body* - - If *methodname* contains ::, the method is considered to be part of a - method ensemble\. See __tool::method\_ensembles__\. Otherwise this command - behaves exactly like the standard __oo::define__ - __[method](\.\./\.\./\.\./\.\./index\.md\#method)__ command\. - - - tool::define __option__ *name* *dictopts* - - Declares an option\. *dictopts* is a key/value list defining parameters for - the option\. See __tool::option\_handling__\. - - tool::class create myclass { - option color { - post-command: {puts [list %self%'s %field% is now %value%]} - default: green - } - } - myclass create foo - foo configure color purple - > foo's color is now purple - - - tool::define __property__ ?branch? *field* *value* - - Defines a new leaf in the class metadata tree\. With no branch, the leaf will - appear in the *const* section, accessible by either the object's - __property__ method, or via __oo::meta::info__ *class* __get - const__ *field*: - - - tool::define __variable__ *name* *value* - - Declares a variable *name* which will be initialized with the value - *value* for objects of this class, as well as any objects for classes - which are descendents of this class\. - -# Public Object Methods - -The TOOL object mother of all classes defines several methods to enforces -consistent behavior throughout the framework\. - - - *object* __cget__ *option* - - Return the value of this object's option *option*\. If the __property - options\_strict__ is true for this class, calling an option which was not - declared by the __option__ keyword will throw an error\. In all other - cases if the value is present in the object's *options* array that value - is returned\. If it does not exist, the object will attempt to retrieve a - property of the same name\. - - - *object* __configure__ ?keyvaluelist? - - - *object* __configure__ *field* *value* ?field? ?value? ?\.\.\.? - - This command will inject new values into the objects *options* array, - according to the rules as set forth by the option descriptions\. See - __tool::option\_handling__ for details\. __configure__ will strip - leading \-'s off of field names, allowing it to behave in a quasi\-backward - compatible manner to tk options\. - - - *object* __configurelist__ ?keyvaluelist? - - This command will inject new values into the objects *options* array, - according to the rules as set forth by the option descriptions\. This command - will perform validation and alternate storage rules\. It will not invoke - trigger rules\. See __tool::option\_handling__ for details\. - - - *object* __forward__ *stub* *forward* - - A passthrough to __oo:objdefine \[self\] forward__ - - - *object* __graft__ *stub* *forward* - - Delegates the ** method to the object or command designated by - *forward* - - tool::object create A - tool::object create B - A graft buddy B - A configure color red - B configure color blue - A cget color - > red - A cget color - > blue - -# Private Object Methods - - - *object* __InitializePublic__ - - Consults the metadata for the class to ensure every array, option, and - variable which has been declared but not initialized is initialized with the - default value\. This method is called by the constructor and the morph - method\. It is safe to invoke multiple times\. - - - *object* __Eval\_Script__ ?script? - - Executes a block of text within the namespace of the object\. Lines that - begin with a \# are ignored as comments\. Commands that begin with :: are - interpreted as calling a global command\. All other Tcl commands that lack a - "my" prefix are given one, to allow the script to exercise internal methods\. - This method is intended for configuration scripts, where the object's - methods are intepreting a domain specific language\. - - tool::class myclass { - constructor script { - my Eval_Script $script - } - method node {nodename info} { - my variable node - dict set node $nodename $info - } - method get {args} { - my variable node - return [dict get $node $args] - } - } - myclass create movies { - # This block of code is executed by the object - node {The Day the Earth Stood Still} { - date: 1952 - characters: {GORT Klatoo} - } - } - movies get {The Day the Earth Stood Still} date: - > 1952 - - - *object* __Option\_Default__ *field* - - Computes the default value for an option\. See __tool::option\_handling__\. - -# AUTHORS - -Sean Woods - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tcloo* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[TOOL](\.\./\.\./\.\./\.\./index\.md\#tool), [TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), -[framework](\.\./\.\./\.\./\.\./index\.md\#framework) - -# CATEGORY - -TclOO - -# COPYRIGHT - -Copyright © 2015 Sean Woods DELETED embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md Index: embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md ================================================================== --- embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md +++ embedded/md/tcllib/files/modules/tool/tool_dict_ensemble.md @@ -1,85 +0,0 @@ - -[//000000001]: # (tool::dict\_ensemble \- Standardized OO Framework for development) -[//000000002]: # (Generated from file 'tool\_dict\_ensemble\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Sean Woods ) -[//000000004]: # (tool::dict\_ensemble\(n\) 0\.4\.2 tcllib "Standardized OO Framework for development") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tool::dict\_ensemble \- Dictionary Tools - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [AUTHORS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require tool ?0\.4\.2? - -[*object* *ensemble* __add__ *field*](#1) - -# DESCRIPTION - -The __dict\_ensemble__ command is a keyword added by -__[tool](tool\.md)__\. It defines a public variable \(stored as a dict\), -and an access function to manipulated and access the values stored in that dict\. - - - *object* *ensemble* __add__ *field* - - \] *value* *value \.\.\.*\] Adds elements to a list maintained with the - *field* leaf of the dict maintained my this ensemble\. Declares a variable - *name* which will be initialized as an array, populated with *contents* - for objects of this class, as well as any objects for classes which are - descendents of this class\. - -# AUTHORS - -Sean Woods - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *tool* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[TOOL](\.\./\.\./\.\./\.\./index\.md\#tool), [TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2015 Sean Woods DELETED embedded/md/tcllib/files/modules/transfer/connect.md Index: embedded/md/tcllib/files/modules/transfer/connect.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/connect.md +++ embedded/md/tcllib/files/modules/transfer/connect.md @@ -1,291 +0,0 @@ - -[//000000001]: # (transfer::connect \- Data transfer facilities) -[//000000002]: # (Generated from file 'connect\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (transfer::connect\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::connect \- Connection setup - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Options](#subsection4) - - - [Secure connections](#section3) - - - [TLS Security Considerations](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require transfer::connect ?0\.2? - -[__transfer::connect__ *objectName* ?*options*\.\.\.?](#1) -[*objectName* __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __connect__ *command*](#4) - -# DESCRIPTION - -This package provides objects holding enough information to enable them to -either actively connect to a counterpart, or to passively wait for a connection -from said counterpart\. I\.e\. any object created by this packages is always in one -of two complementary modes, called *[active](\.\./\.\./\.\./\.\./index\.md\#active)* -\(the object initiates the connection\) and -*[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* \(the object receives the -connection\)\. - -Of the two objects in a connecting pair one has to be configured for -*[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode, and the other then has to be -configured for *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode\. This -establishes which of the two partners connects to whom \(the -*[active](\.\./\.\./\.\./\.\./index\.md\#active)* to the other\), or, who is waiting -on whom \(the *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* on the other\)\. Note -that this is completely independent of the direction of any data transmission -using the connection after it has been established\. An active object can, after -establishing the connection, either transmit or receive data\. Equivalently the -passive object can do the same after the waiting for its partner has ended\. - -# API - -## Package commands - - - __transfer::connect__ *objectName* ?*options*\.\.\.? - - This command creates a new connection object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The set of supported *options* is explained in - section [Options](#subsection4)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - -## Object command - -All objects created by the __::transfer::connect__ command have the -following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. This is safe to do for an - *[active](\.\./\.\./\.\./\.\./index\.md\#active)* object when a connection has - been started, as the completion callback is synchronous\. For a - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* object currently waiting for - its partner to establish the connection however this is not safe and will - cause errors later on, when the connection setup completes and tries to - access the now missing data structures of the destroyed object\. - - - *objectName* __connect__ *command* - - This method starts the connection setup per the configuration of the object\. - When the connection is established the callback *command* will be invoked - with one additional argument, the channel handle of the socket over which - data can be transfered\. - - The detailed behaviour of the method depends on the configured mode\. - - * *[active](\.\./\.\./\.\./\.\./index\.md\#active)* - - The connection setup is done synchronously\. The object waits until the - connection is established\. The method returns the empty string as its - result\. - - * *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* - - The connection setup is done asynchronously\. The method returns - immediately after a listening socket has been set up\. The connection - will be established in the background\. The method returns the port - number of the listening socket, for use by the caller\. One important use - is the transfer of this information to the counterpart so that it knows - where it has to connect to\. - - This is necessary as the object might have been configured for port - __0__, allowing the operating system to choose the actual port it - will listen on\. - - The listening port is closed immediately when the connection was - established by the partner, to keep the time interval small within which - a third party can connect to the port too\. Even so it is recommended to - use additional measures in the protocol outside of the connect and - transfer object to ensure that a connection is not used with an - unidentified/unauthorized partner One possibility for this is the use of - SSL/TLS\. See the option __\-socketcmd__ and section [Secure - connections](#section3) for information on how to do this\. - -## Options - -Connection objects support the set of options listed below\. - - - __\-mode__ *mode* - - This option specifies the mode the object is in\. It is optional and defaults - to __active__ mode\. The two possible modes are: - - * __active__ - - In this mode the two options __\-host__ and __\-port__ are - relevant and specify the host and TCP port the object has to connect to\. - The host is given by either name or IP address\. - - * __passive__ - - In this mode the option __\-host__ has no relevance and is ignored - should it be configured\. The only option the object needs is - __\-port__, and it specifies the TCP port on which the listening - socket is opened to await the connection from the partner\. - - - __\-host__ *hostname\-or\-ipaddr* - - This option specifies the host to connect to in - *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode, either by name or - ip\-address\. An object configured for - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode ignores this option\. - - - __\-port__ *int* - - For *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode this option specifies - the port the object is expected to connect to\. For - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode however it is the port - where the object creates the listening socket waiting for a connection\. It - defaults to __0__, which allows the OS to choose the actual port to - listen on\. - - - __\-socketcmd__ *command* - - This option allows the user to specify which command to use to open a - socket\. The default is to use the builtin __::socket__\. Any compatible - with that command is allowed\. - - The envisioned main use is the specfication of __tls::socket__\. I\.e\. - this option allows the creation of secure transfer channels, without making - this package explicitly dependent on the - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package\. - - See also section [Secure connections](#section3)\. - - - __\-encoding__ encodingname - - - __\-eofchar__ eofspec - - - __\-translation__ transspec - - These options are the same as are recognized by the builtin command - __fconfigure__\. They provide the configuration to be set for the channel - between the two partners after it has been established, but before the - callback is invoked \(See method __connect__\)\. - -# Secure connections - -One way to secure connections made by objects of this package is to require the -package __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ and then configure the -option __\-socketcmd__ to force the use of command __tls::socket__ to -open the socket\. - - # Load and initialize tls - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create a connector with secure socket setup, - transfer::connect C -socketcmd tls::socket ... - ... - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[active](\.\./\.\./\.\./\.\./index\.md\#active), -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[connection](\.\./\.\./\.\./\.\./index\.md\#connection), -[passive](\.\./\.\./\.\./\.\./index\.md\#passive), -[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/copyops.md Index: embedded/md/tcllib/files/modules/transfer/copyops.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/copyops.md +++ embedded/md/tcllib/files/modules/transfer/copyops.md @@ -1,197 +0,0 @@ - -[//000000001]: # (transfer::copy \- Data transfer facilities) -[//000000002]: # (Generated from file 'copyops\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (transfer::copy\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::copy \- Data transfer foundation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require transfer::copy ?0\.2? - -[__transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*\.\.\.?](#1) -[__transfer::copy::chan__ *channel* *outchannel* ?*options*\.\.\.?](#2) -[__transfer::copy::string__ *string* *outchannel* ?*options*\.\.\.?](#3) -[__transfer::copy::doChan__ *channel* *outchannel* *optvar*](#4) -[__transfer::copy::doString__ *string* *outchannel* *optvar*](#5) -[__transfer::copy::options__ *outchannel* *optionlist* *optvar*](#6) - -# DESCRIPTION - -This package provides a number of commands for the asynchronous of information -contained in either a string or channel\. The main point of this package is that -the commands here provide a nicer callback API than the builtin command -__fcopy__, making the use of these facilities simpler than the builtin\. - -# API - - - __transfer::copy::do__ __chan__|__string__ *data* *outchannel* ?*options*\.\.\.? - - This command transfers the information in *data* to the *outchannel*, - according to the *options*\. The type of the information in *data* is - determined by the first argument\. - - The options available to this command are the same as are available to the - command __transfer::copy::options__, and explained there\. - - * __chan__ - - The argument *data* contains the handle of a channel and the actual - infomration to transfer is read from that channel\. - - * __string__ - - The argument *data* contains a string and this is the information to - be transfered\. - - - __transfer::copy::chan__ *channel* *outchannel* ?*options*\.\.\.? - - This command is a shorter and more direct form for the command - __transfer::copy::do chan__\. - - - __transfer::copy::string__ *string* *outchannel* ?*options*\.\.\.? - - This command is a shorter and more direct form for the command - __transfer::copy::do string__\. - - - __transfer::copy::doChan__ *channel* *outchannel* *optvar* - - This command is an alternate form of __transfer::copy::chan__ which - reads its options out of the array variable named by *optvar* instead of - from a variable length argument list\. - - - __transfer::copy::doString__ *string* *outchannel* *optvar* - - This command is an alternate form of __transfer::copy::string__ which - reads its options out of the array variable named by *optvar* instead of - from a variable length argument list\. - - - __transfer::copy::options__ *outchannel* *optionlist* *optvar* - - This command is the option processor used by all the commands above which - read their options from a variable length argument list\. It first reads - default settings from the channel handle *outchannel*, then processes the - list of options in *optionlist*, at last stores the results in the array - variable named by *optvar*\. The contents of that variable are in a format - which is directly understood by all the commands above which read their - options out of an array variable\. - - The recognized options are: - - * __\-blocksize__ *int* - - This option specifies the size of the chunks to transfer in one - operation\. It is optional and defaults to the value of - __\-buffersize__ as configured for the output channel\. - - If specified its value has to be an integer number greater than zero\. - - * __\-command__ *commandprefix* - - This option specifies the completion callback of the operation\. This - option has to be specified\. An error will be thrown if it is not, or if - the empty list was specified as argument to it\. - - Its value has to be a command prefix, i\.e\. a list whose first word is - the command to execute, followed by words containing fixed arguments\. - When the callback is invoked one or two additional arguments are - appended to the prefix\. The first argument is the number of bytes which - were transfered\. The optional second argument is an error message and - added if and only if an error occured during the the transfer\. - - * __\-progress__ *commandprefix* - - This option specifies the progress callback of the operation\. It is - optional and defaults to the empty list\. This last possibility signals - that no feedback was asked for and disabled it\. - - Its value has to be a command prefix, see above, __\-command__ for a - more detailed explanation\. When the callback is invoked a single - additional arguments is appended to the prefix\. This argument is the - number of bytes which were transfered so far\. - - * __\-size__ *int* - - This option specifies the number of bytes to read from the input data - and transfer\. It is optional and defaults to "Transfer everything"\. Its - value has to be an integer number and any value less than zero has the - same meaning, i\.e\. to transfer all available data\. Any other value is - the amount of bytes to transfer\. - - All transfer commands will throw error an when their user tries to - transfer more data than is available in the input\. This happens - immediately, before the transfer is actually started, should the input - be a string\. Otherwise the, i\.e\. for a channel as input, the error is - thrown the moment the underflow condition is actually detected\. - - * __\-encoding__ *encodingname* - - * __\-eofchar__ *eofspec* - - * __\-translation__ *transspec* - - These options are the same as are recognized by the builtin command - __fconfigure__ and provide the settings for the output channel which - are to be active during the transfer, and only then\. I\.e\. the settings - of the output channel before the transfer are saved, and restored at the - end of a transfer, regardless of its success or failure\. None of these - options are required, and they default to the settings of the output - channel if not specified\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/ddest.md Index: embedded/md/tcllib/files/modules/transfer/ddest.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/ddest.md +++ embedded/md/tcllib/files/modules/transfer/ddest.md @@ -1,186 +0,0 @@ - -[//000000001]: # (transfer::data::destination \- Data transfer facilities) -[//000000002]: # (Generated from file 'ddest\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (transfer::data::destination\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::data::destination \- Data destination - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Object command](#subsection1) - - - [Object methods](#subsection2) - - - [Options](#subsection3) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require transfer::data::destination ?0\.2? - -[__transfer::data::destination__ *objectName* ?*options*\.\.\.?](#1) -[*objectName* __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __put__ *chunk*](#4) -[*objectName* __done__](#5) -[*objectName* __valid__ *msgvar*](#6) -[*objectName* __receive__ *channel* *done*](#7) - -# DESCRIPTION - -This package provides objects mainly describing the destination of a data -transfer\. They are also able to initiate the reception of information from a -channel into the described destination\. - -# API - - - __transfer::data::destination__ *objectName* ?*options*\.\.\.? - - This command creates a new data destination object with an associated Tcl - command whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection1) and [Object - methods](#subsection2)\. The set of supported *options* is explained in - section [Options](#subsection3)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - -## Object command - -All objects created by the __::transfer::data::destination__ command have -the following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection2) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. Doing so while the object is busy with the - reception of information from a channel will cause errors later on, when the - reception completes and tries to access the now missing data structures of - the destroyed object\. - - - *objectName* __put__ *chunk* - - The main receptor method\. Saves the received *chunk* of data into the - configured destination\. It has to be called for each piece of data received\. - - - *objectName* __done__ - - The secondary receptor method\. Finalizes the receiver\. It has to be called - when the receiving channel signals EOF\. Afterward neither itself nor method - __put__ can be called anymore\. - - - *objectName* __valid__ *msgvar* - - This method checks the configuration of the object for validity\. It returns - a boolean flag as result, whose value is __True__ if the object is - valid, and __False__ otherwise\. In the latter case the variable whose - name is stored in *msgvar* is set to an error message describing the - problem found with the configuration\. Otherwise this variable is not - touched\. - - - *objectName* __receive__ *channel* *done* - - This method initiates the reception of data from the specified *channel*\. - The received data will be stored into the configured destination, via calls - to the methods __put__ and __done__\. When the reception completes - the command prefix *done* is invoked, with the number of received - characters appended to it as the sole additional argument\. - -## Options - -All data destinations support the options listed below\. It should be noted that -all are semi\-exclusive, each specifying a different type of destination and -associated information\. If these options are specified more than once then the -last option specified is used to actually configure the object\. - - - __\-channel__ *handle* - - This option specifies that the destination of the data is a channel, and its - associated argument is the handle of the channel to write the received data - to\. - - - __\-file__ *path* - - This option specifies that the destination of the data is a file, and its - associated argument is the path of the file to write the received data to\. - - - __\-variable__ *varname* - - This option specifies that the destination of the data is a variable, and - its associated argument contains the name of the variable to write the - received data to\. The variable is assumed to be global or namespaced, - anchored at the global namespace\. - - - __\-progress__ *command* - - This option, if specified, defines a command to be invoked for each chunk of - bytes received, allowing the user to monitor the progress of the reception - of the data\. The callback is always invoked with one additional argument, - the number of bytes received so far\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [data -destination](\.\./\.\./\.\./\.\./index\.md\#data\_destination), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/dsource.md Index: embedded/md/tcllib/files/modules/transfer/dsource.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/dsource.md +++ embedded/md/tcllib/files/modules/transfer/dsource.md @@ -1,229 +0,0 @@ - -[//000000001]: # (transfer::data::source \- Data transfer facilities) -[//000000002]: # (Generated from file 'dsource\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (transfer::data::source\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::data::source \- Data source - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Options](#subsection4) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require transfer::copy ?0\.2? -package require transfer::data::source ?0\.2? - -[__transfer::data::source__ *objectName* ?*options*\.\.\.?](#1) -[*objectName* __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __type__](#4) -[*objectName* __data__](#5) -[*objectName* __size__](#6) -[*objectName* __valid__ *msgvar*](#7) -[*objectName* __transmit__ *channel* *blocksize* *done*](#8) - -# DESCRIPTION - -This package provides objects mainly describing the origin of some data to -transfer\. They are also able to initiate transfers of the described information -to a channel using the foundation package -__[transfer::copy](copyops\.md)__\. - -# API - -## Package commands - - - __transfer::data::source__ *objectName* ?*options*\.\.\.? - - This command creates a new data source object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The set of supported *options* is explained in - section [Options](#subsection4)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - -## Object command - -All objects created by the __::transfer::data::source__ command have the -following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. Doing so while a transfer initiated by the - object is active is safe as all data required for the transfer itself was - copied, and the completion of the transfer will not try to access the - initiating object anymore\. i\.e\. the transfer is completely separate from the - source object itself\. - - - *objectName* __type__ - - This method returns a string describing the type of the data the object is - refering to\. The possible values and their meanings are: - - * __undefined__ - - No data was specified at all, or it was specified incompletely\. The - object does not know the type\. - - * __string__ - - The data to transfer is contained in a string\. - - * __channel__ - - The data to transfer is contained in a channel\. - - - *objectName* __data__ - - This method returns a value depending on the type of the data the object - refers to, through which the data can be accessed\. The method throws an - error if the type is __undefined__\. For type __string__ the returned - result is the data itself, whereas for type __channel__ the returned - result is the handle of the channel containing the data\. - - - *objectName* __size__ - - This method returns a value depending on the type of the data the object - refers to, the size of the data\. The method throws an error if the type is - __undefined__\. Return of a negative value signals that the object is - unable to determine an absolute size upfront \(like for data in a channel\)\. - - - *objectName* __valid__ *msgvar* - - This method checks the configuration of the object for validity\. It returns - a boolean flag as result, whose value is __True__ if the object is - valid, and __False__ otherwise\. In the latter case the variable whose - name is stored in *msgvar* is set to an error message describing the - problem found with the configuration\. Otherwise this variable is not - touched\. - - - *objectName* __transmit__ *channel* *blocksize* *done* - - This method initiates a transfer of the referenced data to the specified - *channel*\. When the transfer completes the command prefix *done* is - invoked, per the rules for the option __\-command__ of command - __transfer::copy::do__ in the package - __[transfer::copy](copyops\.md)__\. The *blocksize* specifies the - size of the chunks to transfer in one go\. See the option __\-blocksize__ - of command __transfer::copy::do__ in the package - __[transfer::copy](copyops\.md)__\. - -## Options - -All data sources support the options listed below\. It should be noted that the -first four options are semi\-exclusive, each specifying a different type of data -source and associated content\. If these options are specified more than once -then the last option specified is used to actually configure the object\. - - - __\-string__ *text* - - This option specifies that the source of the data is an immediate string, - and its associated argument contains the string in question\. - - - __\-channel__ *handle* - - This option specifies that the source of the data is a channel, and its - associated argument is the handle of the channel containing the data\. - - - __\-file__ *path* - - This option specifies that the source of the data is a file, and its - associated argument is the path of the file containing the data\. - - - __\-variable__ *varname* - - This option specifies that the source of the data is a string stored in a - variable, and its associated argument contains the name of the variable in - question\. The variable is assumed to be global or namespaced, anchored at - the global namespace\. - - - __\-size__ *int* - - This option specifies the size of the data transfer\. It is optional and - defaults to \-1\. This value, and any other value less than zero signals to - transfer all the data from the source\. - - - __\-progress__ *command* - - This option, if specified, defines a command to be invoked for each chunk of - bytes transmitted, allowing the user to monitor the progress of the - transmission of the data\. The callback is always invoked with one additional - argument, the number of bytes transmitted so far\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/receiver.md Index: embedded/md/tcllib/files/modules/transfer/receiver.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/receiver.md +++ embedded/md/tcllib/files/modules/transfer/receiver.md @@ -1,337 +0,0 @@ - -[//000000001]: # (transfer::receiver \- Data transfer facilities) -[//000000002]: # (Generated from file 'receiver\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (transfer::receiver\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::receiver \- Data source - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Options](#subsection4) - - - [Secure connections](#section3) - - - [TLS Security Considerations](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require transfer::data::destination ?0\.2? -package require transfer::connect ?0\.2? -package require transfer::receiver ?0\.2? - -[__transfer::receiver__ *object* ?*options*\.\.\.?](#1) -[__transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*\.\.\.?](#2) -[__transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*\.\.\.?](#3) -[*objectName* __method__ ?*arg arg \.\.\.*?](#4) -[*objectName* __destroy__](#5) -[*objectName* __start__](#6) -[*objectName* __busy__](#7) - -# DESCRIPTION - -This package pulls data destinations and connection setup together into a -combined object for the reception of information coming in over a socket\. These -objects understand all the options from objects created by the packages -__[transfer::data::destination](ddest\.md)__ and -__[transfer::connect](connect\.md)__\. - -# API - -## Package commands - - - __transfer::receiver__ *object* ?*options*\.\.\.? - - This command creates a new receiver object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The set of supported *options* is explained in - section [Options](#subsection4)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - - - __transfer::receiver__ __stream channel__ *chan* *host* *port* ?*arg*\.\.\.? - - This method creates a fire\-and\-forget transfer for the data coming from the - source at host/port \(details below\) and writing to the channel *chan*, - starting at the current seek location\. The channel is configured to use - binary translation and encoding for the transfer\. The channel is *not* - closed when the transfer has completed\. This is left to the completion - callback\. - - If both *host* and *port* are provided an __active__ connection to - the data source is made\. If only a *port* is specified \(with *host* the - empty string\) then a __passive__ connection is made instead, i\.e\. the - receiver then waits for a conneciton by the transmitter\. - - Any arguments after the port are treated as options and are used to - configure the internal receiver object\. See the section - [Options](#subsection4) for a list of the supported options and their - meaning\. *Note* however that the signature of the command prefix specified - for the __\-command__ callback differs from the signature for the same - option of the receiver object\. This callback is only given the number of - bytes and transfered, and possibly an error message\. No reference to the - internally used receiver object is made\. - - The result returned by the command is the empty string if it was set to make - an *[active](\.\./\.\./\.\./\.\./index\.md\#active)* connection, and the port - the internal receiver object is listening on otherwise, i\.e when it is - configured to connect *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)*ly\. See - also the package __[transfer::connect](connect\.md)__ and the - description of the method __connect__ for where this behaviour comes - from\. - - - __transfer::receiver__ __stream file__ *path* *host* *port* ?*arg*\.\.\.? - - This method is like __stream channel__, except that the received data is - written to the file *path*, replacing any prior content\. - -## Object command - -All objects created by the __::transfer::receiver__ command have the -following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. Doing so while a reception is on progress - will cause errors later on, when the reception completes and tries to access - the now missing data structures of the destroyed object\. - - - *objectName* __start__ - - This method initiates the data reception, setting up the connection first - and then copying the received information into the destination\. The method - will throw an error if a reception is already/still in progress\. I\.e\. it is - not possible to run two receptions in parallel, only in sequence\. Errors - will also be thrown if the configuration of the data destination is invalid, - or if no completion callback was specified\. - - The result returned by the method is the empty string for an object - configured to make an *[active](\.\./\.\./\.\./\.\./index\.md\#active)* - connection, and the port the object is listening on otherwise, i\.e when it - is configured to connect *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)*ly\. - See also the package __[transfer::connect](connect\.md)__ and the - description of the method __connect__ for where this behaviour comes - from\. - - - *objectName* __busy__ - - This method returns a boolean value telling us whether a reception is in - progress \(__True__\), or not \(__False__\)\. - -## Options - -All receiver objects support the union of the options supported by their connect -and data destination components, plus one of their own\. See also the -documentation for the packages -__[transfer::data::destination](ddest\.md)__ and -__[transfer::connect](connect\.md)__\. - - - __\-command__ *cmdprefix* - - This option specifies the command to invoke when the reception of the - information has been completed\. The arguments given to this command are the - same as given to the completion callback of the command - __transfer::copy::do__ provided by the package - __[transfer::copy](copyops\.md)__\. - - - __\-mode__ *mode* - - This option specifies the mode the object is in\. It is optional and defaults - to __active__ mode\. The two possible modes are: - - * __active__ - - In this mode the two options __\-host__ and __\-port__ are - relevant and specify the host and TCP port the object has to connect to\. - The host is given by either name or IP address\. - - * __passive__ - - In this mode the option __\-host__ has no relevance and is ignored - should it be configured\. The only option the object needs is - __\-port__, and it specifies the TCP port on which the listening - socket is opened to await the connection from the partner\. - - - __\-host__ *hostname\-or\-ipaddr* - - This option specifies the host to connect to in - *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode, either by name or - ip\-address\. An object configured for - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode ignores this option\. - - - __\-port__ *int* - - For *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode this option specifies - the port the object is expected to connect to\. For - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode however it is the port - where the object creates the listening socket waiting for a connection\. It - defaults to __0__, which allows the OS to choose the actual port to - listen on\. - - - __\-socketcmd__ *command* - - This option allows the user to specify which command to use to open a - socket\. The default is to use the builtin __::socket__\. Any compatible - with that command is allowed\. - - The envisioned main use is the specfication of __tls::socket__\. I\.e\. - this option allows the creation of secure transfer channels, without making - this package explicitly dependent on the - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package\. - - See also section [Secure connections](#section3)\. - - - __\-encoding__ encodingname - - - __\-eofchar__ eofspec - - - __\-translation__ transspec - - These options are the same as are recognized by the builtin command - __fconfigure__\. They provide the configuration to be set for the channel - between the two partners after it has been established, but before the - callback is invoked \(See method __connect__\)\. - - - __\-channel__ *handle* - - This option specifies that the destination of the data is a channel, and its - associated argument is the handle of the channel to write the received data - to\. - - - __\-file__ *path* - - This option specifies that the destination of the data is a file, and its - associated argument is the path of the file to write the received data to\. - - - __\-variable__ *varname* - - This option specifies that the destination of the data is a variable, and - its associated argument contains the name of the variable to write the - received data to\. The variable is assumed to be global or namespaced, - anchored at the global namespace\. - - - __\-progress__ *command* - - This option, if specified, defines a command to be invoked for each chunk of - bytes received, allowing the user to monitor the progress of the reception - of the data\. The callback is always invoked with one additional argument, - the number of bytes received so far\. - -# Secure connections - -One way to secure connections made by objects of this package is to require the -package __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ and then configure the -option __\-socketcmd__ to force the use of command __tls::socket__ to -open the socket\. - - # Load and initialize tls - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create a connector with secure socket setup, - transfer::receiver R -socketcmd tls::socket ... - ... - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [data -destination](\.\./\.\./\.\./\.\./index\.md\#data\_destination), -[receiver](\.\./\.\./\.\./\.\./index\.md\#receiver), -[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/tqueue.md Index: embedded/md/tcllib/files/modules/transfer/tqueue.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/tqueue.md +++ embedded/md/tcllib/files/modules/transfer/tqueue.md @@ -1,198 +0,0 @@ - -[//000000001]: # (transfer::copy::queue \- Data transfer facilities) -[//000000002]: # (Generated from file 'tqueue\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006 Andreas Kupries ) -[//000000004]: # (transfer::copy::queue\(n\) 0\.1 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::copy::queue \- Queued transfers - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Options](#section3) - - - [Use](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require struct::queue ?1\.4? -package require transfer::copy ?0\.2? -package require transfer::copy::queue ?0\.1? - -[__transfer::copy::queue__ *objectName* *outchannel* ?*options*\.\.\.?](#1) -[*objectName* __method__ ?*arg arg \.\.\.*?](#2) -[*objectName* __destroy__](#3) -[*objectName* __busy__](#4) -[*objectName* __pending__](#5) -[*objectName* __put__ *request*](#6) - -# DESCRIPTION - -This package provides objects which serialize transfer requests for a single -channel by means of a fifo queue\. Accumulated requests are executed in order of -entrance, with the first request reaching an idle object starting the execution -in general\. New requests can be added while the object is active and are defered -until all requests entered before them have been completed successfully\. - -When a request causes a transfer error execution stops and all requests coming -after it are not served\. Currently this means that their completion callbacks -are never triggered at all\. - -*NOTE*: Not triggering the completion callbacks of the unserved requests after -an error stops the queue object is something I am not fully sure that it makes -sense\. It forces the user of the queue to remember the callbacks as well and run -them\. Because otherwise everything in the system which depends on getting a -notification about the status of a request will hang in the air\. I am slowly -convincing myself that it is more sensible to trigger the relevant completion -callbacks with an error message about the queue abort, and 0 bytes transfered\. - -All transfer requests are of the form - - {type data options...} - -where *type* is in \{__chan__, __string__\}, and *data* specifies the -information to transfer\. For __chan__ the data is the handle of the channel -containing the actual information to transfer, whereas for __string__ -*data* contains directly the information to transfer\. The *options* are a -list of them and their values, and are the same as are accepted by the low\-level -copy operations of the package __[transfer::copy](copyops\.md)__\. Note -how just prepending the request with __transfer::copy::do__ and inserting a -channel handle in between *data* and *options* easily transforms it from a -pure data structure into a command whose evaluation will perform the request\. - -# API - -## Package commands - - - __transfer::copy::queue__ *objectName* *outchannel* ?*options*\.\.\.? - - This command creates a new queue object for the management of the channel - *outchannel*, with an associated Tcl command whose name is *objectName*\. - This *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in - full detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The set of supported *options* is explained in - section [Options](#section3)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - -## Object command - -All objects created by the __::transfer::copy::queue__ command have the -following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. Doing so while the object is busy will - cause errors later on, when the currently executed request completes and - tries to access the now missing data structures of the destroyed object\. - - - *objectName* __busy__ - - This method returns a boolean value telling us if the object is currently - serving a request \(i\.e\. *busy*, value __True__\), or not \(i\.e\. - *[idle](\.\./\.\./\.\./\.\./index\.md\#idle)*, value __False__\)\. - - - *objectName* __pending__ - - This method returns the number of requests currently waiting in the queue - for their execution\. A request currently served is not counted as waiting\. - - - *objectName* __put__ *request* - - This method enters the transfer *request* into the object's queue of - waiting requests\. If the object is *[idle](\.\./\.\./\.\./\.\./index\.md\#idle)* - it will become *busy*, immediately servicing the request\. Otherwise - servicing the new request will be defered until all preceding requests have - been served\. - -# Options - -The only option known is __\-on\-status\-change__\. It is optional and defaults -to the empty list, disabling the reporting of status changes\. Otherwise its -argument is a command prefix which is invoked whenever the internal status of -the object changed\. The callback is invoked with two additional arguments, the -result of the methods __pending__ and __busy__, in this order\. This -allows any user to easily know, for example, when the object has processed all -outstanding requests\. - -# Use - -A possible application of this package and class is within a HTTP 1\.1 server, -managing the results waiting for transfer to the client\. - -It should be noted that in this application the system also needs an additional -data structure which keeps track of outstanding results as they may come back in -a different order than the requests from the client, and releases them to the -actual queue in the proper order\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [queue](\.\./\.\./\.\./\.\./index\.md\#queue), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006 Andreas Kupries DELETED embedded/md/tcllib/files/modules/transfer/transmitter.md Index: embedded/md/tcllib/files/modules/transfer/transmitter.md ================================================================== --- embedded/md/tcllib/files/modules/transfer/transmitter.md +++ embedded/md/tcllib/files/modules/transfer/transmitter.md @@ -1,350 +0,0 @@ - -[//000000001]: # (transfer::transmitter \- Data transfer facilities) -[//000000002]: # (Generated from file 'transmitter\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2006\-2009 Andreas Kupries ) -[//000000004]: # (transfer::transmitter\(n\) 0\.2 tcllib "Data transfer facilities") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -transfer::transmitter \- Data source - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Package commands](#subsection1) - - - [Object command](#subsection2) - - - [Object methods](#subsection3) - - - [Options](#subsection4) - - - [Secure connections](#section3) - - - [TLS Security Considerations](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require snit ?1\.0? -package require transfer::copy ?0\.2? -package require transfer::data::source ?0\.2? -package require transfer::connect ?0\.2? -package require transfer::transmitter ?0\.2? - -[__transfer::transmitter__ *objectName* ?*options*\.\.\.?](#1) -[__transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*\.\.\.?](#2) -[__transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*\.\.\.?](#3) -[*objectName* __method__ ?*arg arg \.\.\.*?](#4) -[*objectName* __destroy__](#5) -[*objectName* __start__](#6) -[*objectName* __busy__](#7) - -# DESCRIPTION - -This package pulls data sources and connection setup together into a combined -object for the transmission of information over a socket\. These objects -understand all the options from objects created by the packages -__[transfer::data::source](dsource\.md)__ and -__[transfer::connect](connect\.md)__\. - -# API - -## Package commands - - - __transfer::transmitter__ *objectName* ?*options*\.\.\.? - - This command creates a new transmitter object with an associated Tcl command - whose name is *objectName*\. This - *[object](\.\./\.\./\.\./\.\./index\.md\#object)* command is explained in full - detail in the sections [Object command](#subsection2) and [Object - methods](#subsection3)\. The set of supported *options* is explained in - section [Options](#subsection4)\. - - The object command will be created under the current namespace if the - *objectName* is not fully qualified, and in the specified namespace - otherwise\. The fully qualified name of the object command is returned as the - result of the command\. - - - __transfer::transmitter__ __stream channel__ *chan* *host* *port* ?*arg*\.\.\.? - - This method creates a fire\-and\-forget transfer for the data contained in the - channel *chan*, starting at the current seek location\. The channel is - configured to use binary translation and encoding for the transfer\. The - channel is automatically closed when the transfer has completed\. - - If both *host* and *port* are provided an __active__ connection to - the destination is made\. If only a *port* is specified \(with *host* the - empty string\) then a __passive__ connection is made instead\. - - Any arguments after the port are treated as options and are used to - configure the internal transmitter object\. See the section - [Options](#subsection4) for a list of the supported options and their - meaning\. *Note* however that the signature of the command prefix specified - for the __\-command__ callback differs from the signature for the same - option of the transmitter object\. This callback is only given the number of - bytes and transfered, and possibly an error message\. No reference to the - internally used transmitter object is made\. - - The result returned by the command is the empty string if it was set to make - an *[active](\.\./\.\./\.\./\.\./index\.md\#active)* connection, and the port - the internal transmitter object is listening on otherwise, i\.e when it is - configured to connect *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)*ly\. See - also the package __[transfer::connect](connect\.md)__ and the - description of the method __connect__ for where this behaviour comes - from\. - - - __transfer::transmitter__ __stream file__ *path* *host* *port* ?*arg*\.\.\.? - - This method is like __stream channel__, except that the data contained - in the file *path* is transfered\. - -## Object command - -All objects created by the __::transfer::transmitter__ command have the -following general form: - - - *objectName* __method__ ?*arg arg \.\.\.*? - - The method __method__ and its *arg*'uments determine the exact - behavior of the command\. See section [Object methods](#subsection3) for - the detailed specifications\. - -## Object methods - - - *objectName* __destroy__ - - This method destroys the object\. Doing so while a transmission is in - progress will cause errors later on, when the transmission completes and - tries to access the now missing data structures of the destroyed object\. - - - *objectName* __start__ - - This method initiates the data transmission, setting up the connection first - and then copying the information\. The method will throw an error if a - transmission is already/still in progress\. I\.e\. it is not possible to run - two transmissions in parallel on a single object, only in sequence\. Multiple - transmitter objects are needed to manage parallel transfers, one per - transmission\. Errors will also be thrown if the configuration of the data - source is invalid, or if no completion callback was specified\. - - The result returned by the method is the empty string for an object - configured to make an *[active](\.\./\.\./\.\./\.\./index\.md\#active)* - connection, and the port the object is listening on otherwise, i\.e when it - is configured to connect *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)*ly\. - See also the package __[transfer::connect](connect\.md)__ and the - description of the method __connect__ for where this behaviour comes - from\. - - - *objectName* __busy__ - - This method returns a boolean value telling us whether a transmission is in - progress \(__True__\), or not \(__False__\)\. - -## Options - -All transmitter objects support the union of the options supported by their -connect and data source components, plus two of their own\. See also the -documentation for the packages __[transfer::data::source](dsource\.md)__ -and __[transfer::connect](connect\.md)__\. - - - __\-blocksize__ *int* - - This option specifies the size of the chunks to be transmitted in one block\. - Usage is optional, its default value is __1024__\. - - - __\-command__ *cmdprefix* - - This option specifies the command to invoke when the transmission of the - information has been completed\. The arguments given to this command are the - same as given to the completion callback of the command - __transfer::copy::do__ provided by the package - __[transfer::copy](copyops\.md)__\. - - - __\-mode__ *mode* - - This option specifies the mode the object is in\. It is optional and defaults - to __active__ mode\. The two possible modes are: - - * __active__ - - In this mode the two options __\-host__ and __\-port__ are - relevant and specify the host and TCP port the object has to connect to\. - The host is given by either name or IP address\. - - * __passive__ - - In this mode the option __\-host__ has no relevance and is ignored - should it be configured\. The only option the object needs is - __\-port__, and it specifies the TCP port on which the listening - socket is opened to await the connection from the partner\. - - - __\-host__ *hostname\-or\-ipaddr* - - This option specifies the host to connect to in - *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode, either by name or - ip\-address\. An object configured for - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode ignores this option\. - - - __\-port__ *int* - - For *[active](\.\./\.\./\.\./\.\./index\.md\#active)* mode this option specifies - the port the object is expected to connect to\. For - *[passive](\.\./\.\./\.\./\.\./index\.md\#passive)* mode however it is the port - where the object creates the listening socket waiting for a connection\. It - defaults to __0__, which allows the OS to choose the actual port to - listen on\. - - - __\-socketcmd__ *command* - - This option allows the user to specify which command to use to open a - socket\. The default is to use the builtin __::socket__\. Any compatible - with that command is allowed\. - - The envisioned main use is the specfication of __tls::socket__\. I\.e\. - this option allows the creation of secure transfer channels, without making - this package explicitly dependent on the - __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package\. - - See also section [Secure connections](#section3)\. - - - __\-encoding__ encodingname - - - __\-eofchar__ eofspec - - - __\-translation__ transspec - - These options are the same as are recognized by the builtin command - __fconfigure__\. They provide the configuration to be set for the channel - between the two partners after it has been established, but before the - callback is invoked \(See method __connect__\)\. - - - __\-string__ *text* - - This option specifies that the source of the data is an immediate string, - and its associated argument contains the string in question\. - - - __\-channel__ *handle* - - This option specifies that the source of the data is a channel, and its - associated argument is the handle of the channel containing the data\. - - - __\-file__ *path* - - This option specifies that the source of the data is a file, and its - associated argument is the path of the file containing the data\. - - - __\-variable__ *varname* - - This option specifies that the source of the data is a string stored in a - variable, and its associated argument contains the name of the variable in - question\. The variable is assumed to be global or namespaced, anchored at - the global namespace\. - - - __\-size__ *int* - - This option specifies the size of the data transfer\. It is optional and - defaults to \-1\. This value, and any other value less than zero signals to - transfer all the data from the source\. - - - __\-progress__ *command* - - This option, if specified, defines a command to be invoked for each chunk of - bytes transmitted, allowing the user to monitor the progress of the - transmission of the data\. The callback is always invoked with one additional - argument, the number of bytes transmitted so far\. - -# Secure connections - -One way to secure connections made by objects of this package is to require the -package __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ and then configure the -option __\-socketcmd__ to force the use of command __tls::socket__ to -open the socket\. - - # Load and initialize tls - package require tls - tls::init -cafile /path/to/ca/cert -keyfile ... - - # Create a connector with secure socket setup, - transfer::transmitter T -socketcmd tls::socket ... - ... - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *transfer* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel](\.\./\.\./\.\./\.\./index\.md\#channel), -[copy](\.\./\.\./\.\./\.\./index\.md\#copy), [data -source](\.\./\.\./\.\./\.\./index\.md\#data\_source), -[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), -[tls](\.\./\.\./\.\./\.\./index\.md\#tls), -[transfer](\.\./\.\./\.\./\.\./index\.md\#transfer), -[transmitter](\.\./\.\./\.\./\.\./index\.md\#transmitter) - -# CATEGORY - -Transfer module - -# COPYRIGHT - -Copyright © 2006\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/treeql/treeql.md Index: embedded/md/tcllib/files/modules/treeql/treeql.md ================================================================== --- embedded/md/tcllib/files/modules/treeql/treeql.md +++ embedded/md/tcllib/files/modules/treeql/treeql.md @@ -1,705 +0,0 @@ - -[//000000001]: # (treeql \- Tree Query Language) -[//000000002]: # (Generated from file 'treeql\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004 Colin McCormack ) -[//000000004]: # (Copyright © 2004 Andreas Kupries ) -[//000000005]: # (treeql\(n\) 1\.3\.1 tcllib "Tree Query Language") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -treeql \- Query tree objects - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [TreeQL CLASS API](#subsection1) - - - [TreeQL OBJECT API](#subsection2) - - - [The Tree Query Language](#section3) - - - [TreeQL Concepts](#subsection3) - - - [Structural generators](#subsection4) - - - [Attribute Filters](#subsection5) - - - [Attribute Mutators](#subsection6) - - - [Attribute String Accessors](#subsection7) - - - [Sub\-queries](#subsection8) - - - [Node Set Operators](#subsection9) - - - [Node Set Iterators](#subsection10) - - - [Typed node support](#subsection11) - - - [Examples](#section4) - - - [References](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.2 -package require snit -package require struct::list -package require struct::set -package require treeql ?1\.3\.1? - -[__treeql__ *objectname* __\-tree__ *tree* ?__\-query__ *query*? ?__\-nodes__ *nodes*? ?*args*\.\.\.?](#1) -[*qo* __query__ *args*\.\.\.](#2) -[*qo* __result__](#3) -[*qo* __discard__](#4) - -# DESCRIPTION - -This package provides objects which can be used to query and transform tree -objects following the API of tree objects created by the package -__[struct::tree](\.\./struct/struct\_tree\.md)__\. - -The tree query and manipulation language used here, TreeQL, is inspired by Cost -\(See section [References](#section5) for more information\)\. - -__treeql__, the package, is a fairly thin query facility over -tree\-structured data types\. It implements an ordered set of nodes \(really a -list\) which are generated and filtered through the application of TreeQL -operators to each node in turn\. - -# API - -## TreeQL CLASS API - -The command __treeql__ is a __[snit](\.\./snit/snit\.md)__::type which -implements the Treeql Query Language\. This means that it follows the API for -class commands as specified by the package __[snit](\.\./snit/snit\.md)__\. -Its general syntax is - - - __treeql__ *objectname* __\-tree__ *tree* ?__\-query__ *query*? ?__\-nodes__ *nodes*? ?*args*\.\.\.? - - The command creates a new tree query object and returns the fully qualified - name of the object command as its result\. The API the returned command is - following is described in the section [TreeQL OBJECT API](#subsection2) - - Each query object is associated with a single *tree* object\. This is the - object all queries will be run against\. - - If the option __\-nodes__ was specified then its argument is treated as a - list of nodes\. This list is used to initialize the node set\. It defaults to - the empty list\. - - If the option __\-query__ was specified then its argument will be - interpreted as an object, the *parent query* of this query\. It defaults to - the object itself\. All queries will be interpreted in the environment of - this object\. - - Any arguments coming after the options are treated as a query and run - immediately, after the *node set* has been initialized\. This uses the same - syntax for the query as the method __query__\. - - The operations of the TreeQL available for this are explained in the section - about [The Tree Query Language](#section3)\. This section also explains - the term *node set* used above\. - -## TreeQL OBJECT API - -As __treeql__ has been implemented in __[snit](\.\./snit/snit\.md)__ -all the standard methods of __[snit](\.\./snit/snit\.md)__\-based classes -are available to the user and therefore not listed here\. Please read the -documentation for __[snit](\.\./snit/snit\.md)__ for what they are and what -functionality they provide - -The methods provided by the package __treeql__ itself are listed and -explained below\. - - - *qo* __query__ *args*\.\.\. - - This method interprets its arguments as a series of TreeQL operators and - interpretes them from the left to right \(i\.e\. first to last\)\. Note that the - first operator uses the *node set* currently known to the object to - perform its actions\. In other words, the *node set* is *not* cleared, or - modified in other ways, before the query is run\. This allows the user to run - several queries one after the other and have each use the results of the - last\. Any initialization has to be done by any query itself, using TreeQL - operators\. The result of the method is the *node set* after the last - operator of the query has been executed\. - - *Note* that uncaught errors will leave the *node set* of the object in - an intermediate state, per the TreeQL operators which were executed - successfully before the error occurred\. - - The above means in detail that: - - 1. The first argument is interpreted as the name of a query operator, the - number of arguments required by that operator is then determined, and - taken from the immediately following arguments\. - - Because of this operators cannot have optional arguments, all arguments - have to be present as defined\. Failure to do this will, at least, - confuse the query interpreter, but more likely cause errors\. - - 1. The operator is applied to the current node set, yielding a new node - set, and/or manipulating the tree object the query object is connected - to\. - - 1. The arguments used \(i\.e\. operator name and arguments\) are removed from - the list of method arguments, and then the whole process is repeated - from step \[1\], until the list of arguments is empty or an error - occurred\. - - # q is the query object. - - q query root children get data - - # The above query - # - Resets the node set to the root node - root - # - Adds the children of root to the set - children - # - Replaces the node set with the - get data - # values for the attribute 'data', - # for all nodes in the set which - # have such an attribute. - # - And returns this information. - - # Below we can see the same query, but rewritten - # to show the structure as it is seen by the query - # interpreter. - - q query \ - root \ - children \ - get data - - The operators of the TreeQL language available for this are explained in the - section about [The Tree Query Language](#section3)\. This section also - explains the term *node set* used above\. - - - *qo* __result__ - - This method returns a list containing the current node set\. - - - *qo* __discard__ - - This method returns the current node set \(like method __result__\), but - also destroys the query object \(*qo*\)\. This is useful when constructing - and using sub\-queries \(%AUTO% objects immediately destroyed after use\)\. - -# The Tree Query Language - -This and the following sections specify the Tree Query Language used by the -query objects of this package in detail\. - -First we explain the general concepts underneath the language which are required -to comprehend it\. This is followed by the specifications for all the available -query operators\. They fall into eight categories, and each category has its own -section\. - - 1. [TreeQL Concepts](#subsection3) - - 1. [Structural generators](#subsection4) - - 1. [Attribute Filters](#subsection5) - - 1. [Attribute Mutators](#subsection6) - - 1. [Attribute String Accessors](#subsection7) - - 1. [Sub\-queries](#subsection8) - - 1. [Node Set Operators](#subsection9) - - 1. [Node Set Iterators](#subsection10) - - 1. [Typed node support](#subsection11) - -## TreeQL Concepts - -The main concept which has to be understood is that of the *node set*\. Each -query object maintains exactly one such *node set*, and essentially all -operators use it and input argument and for their result\. This structure simply -contains the handles of all nodes which are currently of interest to the query -object\. To name it a *[set](\.\./\.\./\.\./\.\./index\.md\#set)* is a bit of a -misnomer, because - - 1. A node \(handle\) can occur in the structure more than once, and - - 1. the order of nodes in the structure is important as well\. Whenever an - operator processes all nodes in the node set it will do so in the order - they occur in the structure\. - -Regarding the possible multiple occurrence of a node, consider a node set -containing two nodes A and B, both having node P as their immediate parent\. -Application of the TreeQL operator "parent" will then add P to the new node set -twice, once per node it was parent of\. I\.e\. the new node set will then be \{P P\}\. - -## Structural generators - -All tree\-structural operators locate nodes in the tree based on a structural -relation ship to the nodes currently in the set and then replace the current -node set with the set of nodes found Nodes which fulfill such a relationship -multiple times are added to the result as often as they fulfill the -relationship\. - -It is important to note that the found nodes are collected in a separate storage -area while processing the node set, and are added to \(or replacing\) the current -node set only after the current node set has been processed completely\. In other -words, the new nodes are *not* processed by the operator as well and do not -affect the iteration\. - -When describing an operator the variable __N__ will be used to refer to any -node in the node set\. - - - __ancestors__ - - Replaces the current node set with the ancestors for all nodes __N__ in - the node set, should __N__ have a parent\. In other words, nodes without - a parent do not contribute to the new node set\. In other words, uses all - nodes on the path from node __N__ to root, in this order \(root last\), - for all nodes __N__ in the node set\. This includes the root, but not the - node itself\. - - - __rootpath__ - - Replaces the current node set with the ancestors for all nodes __N__ in - the node set, should __N__ have a parent\. In other words, nodes without - a parent do not contribute to the new node set\. In contrast to the operator - __ancestors__ the nodes are added in reverse order however, i\.e\. the - root node first\. - - - __parent__ - - Replaces the current node set with the parent of node __N__, for all - nodes __N__ in the node set, should __N__ have a parent\. In other - words, nodes without a parent do not contribute to the new node set\. - - - __children__ - - Replaces the current node set with the immediate children of node __N__, - for all nodes __N__ in the node set, should __N__ have children\. In - other words, nodes without children do not contribute to the new node set\. - - - __left__ - - Replaces the current node set with the previous/left sibling for all nodes - __N__ in the node set, should __N__ have siblings to the left\. In - other words, nodes without left siblings do not contribute to the new node - set\. - - - __right__ - - Replaces the current node set with the next/right sibling for all nodes - __N__ in the node set, should __N__ have siblings to the right\. In - other words, nodes without right siblings do not contribute to the new node - set\. - - - __prev__ - - Replaces the current node set with all previous/left siblings of node - __N__, for all nodes __N__ in the node set, should __N__ have - siblings to the left\. In other words, nodes without left siblings are - ignored\. The left sibling adjacent to the node is added first, and the - leftmost sibling last \(reverse tree order\)\. - - - __esib__ - - Replaces the current node set with all previous/left siblings of node - __N__, for all nodes __N__ in the node set, should __N__ have - siblings to the left\. In other words, nodes without left siblings are - ignored\. The leftmost sibling is added first, and the left sibling adjacent - to the node last \(tree order\)\. - - The method name is a shorthand for *Earlier SIBling*\. - - - __next__ - - Replaces the current node set with all next/right siblings of node - __N__, for all nodes __N__ in the node set, should __N__ have - siblings to the right\. In other words, nodes without right siblings do not - contribute to the new node set\. The right sibling adjacent to the node is - added first, and the rightmost sibling last \(tree order\)\. - - - __root__ - - Replaces the current node set with a node set containing a single node, the - root of the tree\. - - - __tree__ - - Replaces the current node set with a node set containing all nodes found in - the tree\. The nodes are added in pre\-order \(parent first, then children, the - latter from left to right, first to last\)\. - - - __descendants__ - - Replaces the current node set with the nodes in all subtrees rooted at node - __N__, for all nodes __N__ in the node set, should __N__ have - children\. In other words, nodes without children do not contribute to the - new node set\. - - This is like the operator __children__, but covers the children of - children as well, i\.e\. all the *proper descendants*\. "Rooted at __N__" - means that __N__ itself is not added to the new set, which is also - implied by *proper descendants*\. - - - __subtree__ - - Like operator __descendants__, but includes the node __N__\. In other - words: - - Replaces the current node set with the nodes of the subtree of node - __N__, for all nodes __N__ in the node set, should __N__ have - children\. In other words, nodes without children do not contribute to the - new node set\. I\.e this is like the operator __children__, but covers the - children of children, etc\. as well\. "Of __N__" means that __N__ - itself is added to the new set\. - - - __forward__ - - Replaces the current node set with the nodes in the subtrees rooted at the - right siblings of node __N__, for all nodes __N__ in the node set, - should __N__ have right siblings, and they children\. In other words, - nodes without right siblings, and them without children are ignored\. - - This is equivalent to the operator sequence - - next descendants - - - __later__ - - This is an alias for the operator __forward__\. - - - __backward__ - - Replaces the current node set with the nodes in the flattened previous - subtrees, in reverse tree order\. - - This is nearly equivalent to the operator sequence - - prev descendants - - The only difference is that this uses the nodes in reverse order\. - - - __earlier__ - - Replaces the current node set with the nodes in the flattened previous - subtrees, in tree order\. - - This is equivalent to the operator sequence - - prev subtree - -## Attribute Filters - -These operators filter the node set by reference to attributes of nodes and -their properties\. Filter means that all nodes not fulfilling the criteria are -removed from the node set\. In other words, the node set is replaced by the set -of nodes fulfilling the filter criteria\. - - - __hasatt__ *attr* - - Reduces the node set to nodes which have an attribute named *attr*\. - - - __withatt__ *attr* *value* - - Reduces the node set to nodes which have an attribute named *attr*, and - where the value of that attribute is equal to *value* \(The "==" operator - is __string equal \-nocase__\)\. - - - __withatt\!__ *attr* *val* - - This is the same as __withatt__, but all nodes in the node set have to - have the attribute, and the "==" operator is __string equal__, i\.e\. no - __\-nocase__\. The operator will fail with an error if they don't have the - attribute\. - - - __attof__ *attr* *vals* - - Reduces the node set to nodes which which have an attribute named *attr* - and where the value of that attribute is contained in the list *vals* of - legal values\. The contained\-in operator used here does glob matching \(using - the attribute value as pattern\) and ignores the case of the attribute value, - *but not* for the elements of *vals*\. - - - __attmatch__ *attr* *match* - - Same as __withatt__, but __string match__ is used as the "==" - operator, and *match* is the pattern checked for\. - - *Note* that *match* is a interpreted as a partial argument *list* for - __string match__\. This means that it is interpreted as a list containing - the pattern, and the pattern element can be preceded by options understand - by __string match__, like __\-nocase__\. This is especially important - should the pattern contain spaces\. It has to be wrapped into a list for - correct interpretation by this operator - -## Attribute Mutators - -These operators change node attributes within the underlying tree\. In other -words, all these operators have *side effects*\. - - - __set__ *attr* *val* - - Sets the attribute *attr* to the value *val*, for all nodes __N__ in - the node set\. The operator will fail if a node does not have an attribute - named *attr*\. The tree will be left in a partially modified state\. - - - __unset__ *attr* - - Unsets the attribute *attr*, for all nodes __N__ in the node set\. The - operator will fail if a node does not have an attribute named *attr*\. The - tree will be left in a partially modified state\. - -## Attribute String Accessors - -These operators retrieve the values of node attributes from the underlying tree\. -The collected results are stored in the node set, but are not actually nodes\. - -In other words, they redefine the semantics of the node set stored by the query -object to contain non\-node data after their completion\. - -The query interpreter will terminate after it has finished processing one of -these operators, silently discarding any later query elements\. It also means -that our talk about maintenance of a node set is not quite true\. It is a node -set while the interpreter is processing commands, but can be left as an -attribute value set at the end of query processing\. - - - __string__ *op* *attr* - - Applies the string operator *op* to the attribute named *attr*, for all - nodes __N__ in the node set, collects the results of that application - and places them into the node set\. - - The operator will fail if a node does not have an attribute named *attr*\. - - The argument *op* is interpreted as partial argument list for the builtin - command __[string](\.\./\.\./\.\./\.\./index\.md\#string)__\. Its first word - has to be any of the sub\-commands understood by - __[string](\.\./\.\./\.\./\.\./index\.md\#string)__\. This has to be followed - by all arguments required for the subcommand, except the last\. that last - argument is supplied by the attribute value\. - - - __get__ *pattern* - - For all nodes __N__ in the node set it determines all their attributes - with names matching the glob *pattern*, then the values of these - attributes, at last it replaces the node set with the list of these - attribute values\. - - - __attlist__ - - This is a convenience definition for the operator __getvals \*__\. In - other words, it replaces the node set with a list of the attribute values - for all attributes for all nodes __N__ in the node set\. - - - __attrs__ *glob* - - Replaces the current node set with a list of attribute lists, one attribute - list per for all nodes __N__ in the node set\. - - - __attval__ *attname* - - Reduces the current node set with the operator __hasatt__, and then - replaces it with a list containing the values of the attribute named - *attname* for all nodes __N__ in the node set\. - -## Sub\-queries - -Sub\-queries yield node sets which are then used to augment, reduce or replace -the current node set\. - - - __andq__ *query* - - Replaces the node set with the set\-intersection of the node set generated by - the sub\-query *query* and itself\. - - The execution of the sub\-query uses the current node set as its own initial - node set\. - - - __orq__ *query* - - Replaces the node set with the set\-union of the node set generated by the - sub\-query *query* and itself\. Duplicate nodes are removed\. - - The execution of the sub\-query uses the current node set as its own initial - node set\. - - - __notq__ *query* - - Replaces the node set with the set of nodes generated by the sub\-query - *query* which are also not in the current node set\. In other word the set - difference of itself and the node set generated by the sub\-query\. - - The execution of the sub\-query uses the current node set as its own initial - node set\. - -## Node Set Operators - -These operators change the node set directly, without referring to the tree\. - - - __unique__ - - Removes duplicate nodes from the node set, preserving order\. In other words, - the earliest occurrence of a node handle is preserved, every other - occurrence is removed\. - - - __select__ - - Replaces the current node set with a node set containing only the first node - from the current node set - - - __transform__ *query* *var* *body* - - First it interprets the sub\-query *query*, using the current node set as - its initial node set\. Then it iterates over the result of that query, - binding the handle of each node to the variable named in *var*, and - executing the script *body*\. The collected results of these executions is - made the new node set, replacing the current one\. - - The script *body* is executed in the context of the caller\. - - - __map__ *var* *body* - - Iterates over the current node set, binding the handle of each node to the - variable named in *var*, and executing the script *body*\. The collected - results of these executions is made the new node set, replacing the current - one\. - - The script *body* is executed in the context of the caller\. - - - __quote__ *val* - - Appends the literal value *val* to the current node set\. - - - __replace__ *val* - - Replaces the current node set with the literal list value *val*\. - -## Node Set Iterators - - - __foreach__ *query* *var* *body* - - Interprets the sub\-query *query*, then performs the equivalent of operator - __over__ on the nodes in the node set created by that query\. The current - node set is not changed, except through side effects from the script - *body*\. - - The script *body* is executed in the context of the caller\. - - - __with__ *query* *body* - - Interprets the *query*, then runs the script *body* on the node set - generated by the query\. At last it restores the current node set as it was - before the execution of the query\. - - The script *body* is executed in the context of the caller\. - - - __over__ *var* *body* - - Executes the script *body* for each node in the node set, with the - variable named by *var* bound to the name of the current node\. The script - *body* is executed in the context of the caller\. - - This is like the builtin - __[foreach](\.\./\.\./\.\./\.\./index\.md\#foreach)__, with the node set as - the source of the list to iterate over\. - - The results of executing the *body* are ignored\. - - - __delete__ - - Deletes all the nodes contained in the current node set from the tree\. - -## Typed node support - -These filters and accessors assume the existence of an attribute called -__@type__, and are short\-hand forms useful for cost\-like tree query, html -tree editing, and so on\. - - - __nodetype__ - - Returns the node type of nodes\. Attribute string accessor\. This is - equivalent to - - get @type - - - __oftype__ *t* - - Reduces the node set to nodes whose type is equal to *t*, with letter case - ignored\. - - - __nottype__ *t* - - Reduces the node set to nodes whose type is not equal to *t*, with letter - case ignored\. - - - __oftypes__ *attrs* - - Reduces set to nodes whose @type is an element in the list *attrs* of - types\. The value of @type is used as a glob pattern, and letter case is - relevant\. - -# Examples - -\.\.\. TODO \.\.\. - -# References - - 1. [COST](http://wiki\.tcl\.tk/COST) on the Tcler's Wiki\. - - 1. [TreeQL](http://wiki\.tcl\.tk/treeql) on the Tcler's Wiki\. Discuss this - package there\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *treeql* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Cost](\.\./\.\./\.\./\.\./index\.md\#cost), [DOM](\.\./\.\./\.\./\.\./index\.md\#dom), -[TreeQL](\.\./\.\./\.\./\.\./index\.md\#treeql), -[XPath](\.\./\.\./\.\./\.\./index\.md\#xpath), [XSLT](\.\./\.\./\.\./\.\./index\.md\#xslt), -[structured queries](\.\./\.\./\.\./\.\./index\.md\#structured\_queries), -[tree](\.\./\.\./\.\./\.\./index\.md\#tree), [tree query -language](\.\./\.\./\.\./\.\./index\.md\#tree\_query\_language) - -# CATEGORY - -Data structures - -# COPYRIGHT - -Copyright © 2004 Colin McCormack -Copyright © 2004 Andreas Kupries DELETED embedded/md/tcllib/files/modules/try/tcllib_throw.md Index: embedded/md/tcllib/files/modules/try/tcllib_throw.md ================================================================== --- embedded/md/tcllib/files/modules/try/tcllib_throw.md +++ embedded/md/tcllib/files/modules/try/tcllib_throw.md @@ -1,91 +0,0 @@ - -[//000000001]: # (throw \- Forward compatibility implementation of \[throw\]) -[//000000002]: # (Generated from file 'tcllib\_throw\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2015 Miguel Martínez López, BSD licensed) -[//000000004]: # (throw\(n\) 1 tcllib "Forward compatibility implementation of \[throw\]") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -throw \- throw \- Throw an error exception with a message - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require throw ?1? - -[__::throw__ *error\_code* *error\_message*](#1) - -# DESCRIPTION - -This package provides a forward\-compatibility implementation of Tcl 8\.6's throw -command \(TIP 329\), for Tcl 8\.5\. The code was directly pulled from Tcl 8\.6 -revision ?, when try/finally was implemented as Tcl procedure instead of in C\. - - - __::throw__ *error\_code* *error\_message* - - throw is merely a reordering of the arguments of the error command\. It - throws an error with the indicated error code and error message\. - -# EXAMPLES - -> __throw__ \{MYERROR CODE\} "My error message" - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *try* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -error\(n\) - -# KEYWORDS - -[error](\.\./\.\./\.\./\.\./index\.md\#error), -[return](\.\./\.\./\.\./\.\./index\.md\#return), -[throw](\.\./\.\./\.\./\.\./index\.md\#throw) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2015 Miguel Martínez López, BSD licensed DELETED embedded/md/tcllib/files/modules/try/tcllib_try.md Index: embedded/md/tcllib/files/modules/try/tcllib_try.md ================================================================== --- embedded/md/tcllib/files/modules/try/tcllib_try.md +++ embedded/md/tcllib/files/modules/try/tcllib_try.md @@ -1,164 +0,0 @@ - -[//000000001]: # (try \- Forward compatibility implementation of \[try\]) -[//000000002]: # (Generated from file 'tcllib\_try\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Donal K\. Fellows, BSD licensed) -[//000000004]: # (try\(n\) 1 tcllib "Forward compatibility implementation of \[try\]") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -try \- try \- Trap and process errors and exceptions - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [EXAMPLES](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require try ?1? - -[__::try__ *body* ?*handler\.\.\.*? ?__finally__ *script*?](#1) - -# DESCRIPTION - -This package provides a forward\-compatibility implementation of Tcl 8\.6's -try/finally command \(TIP 329\), for Tcl 8\.5\. The code was directly pulled from -Tcl 8\.6 revision ?, when try/finally was implemented as Tcl procedure instead of -in C\. - - - __::try__ *body* ?*handler\.\.\.*? ?__finally__ *script*? - - This command executes the script *body* and, depending on what the outcome - of that script is \(normal exit, error, or some other exceptional result\), - runs a handler script to deal with the case\. Once that has all happened, if - the __finally__ clause is present, the *script* it includes will be - run and the result of the handler \(or the *body* if no handler matched\) is - allowed to continue to propagate\. Note that the __finally__ clause is - processed even if an error occurs and irrespective of which, if any, - *handler* is used\. - - The *handler* clauses are each expressed as several words, and must have - one of the following forms: - - * __on__ *code variableList script* - - This clause matches if the evaluation of *body* completed with the - exception code *code*\. The *code* may be expressed as an integer or - one of the following literal words: __ok__, __error__, - __return__, __break__, or __continue__\. Those literals - correspond to the integers 0 through 4 respectively\. - - * __trap__ *pattern variableList script* - - This clause matches if the evaluation of *body* resulted in an error - and the prefix of the __\-errorcode__ from the interpreter's status - dictionary is equal to the *pattern*\. The number of prefix words taken - from the __\-errorcode__ is equal to the list\-length of *pattern*, - and inter\-word spaces are normalized in both the __\-errorcode__ and - *pattern* before comparison\. - - The *variableList* word in each *handler* is always interpreted as a - list of variable names\. If the first word of the list is present and - non\-empty, it names a variable into which the result of the evaluation - of *body* \(from the main __try__\) will be placed; this will - contain the human\-readable form of any errors\. If the second word of the - list is present and non\-empty, it names a variable into which the - options dictionary of the interpreter at the moment of completion of - execution of *body* will be placed\. - - The *script* word of each *handler* is also always interpreted the - same: as a Tcl script to evaluate if the clause is matched\. If - *script* is a literal __\-__ and the *handler* is not the last - one, the *script* of the following *handler* is invoked instead - \(just like with the __switch__ command\)\. - - Note that *handler* clauses are matched against in order, and that the - first matching one is always selected\. At most one *handler* clause - will selected\. As a consequence, an __on error__ will mask any - subsequent __trap__ in the __try__\. Also note that __on - error__ is equivalent to __trap \{\}__\. - - If an exception \(i\.e\. any non\-__ok__ result\) occurs during the - evaluation of either the *handler* or the __finally__ clause, the - original exception's status dictionary will be added to the new - exception's status dictionary under the __\-during__ key\. - -# EXAMPLES - -Ensure that a file is closed no matter what: - -> set f \[open /some/file/name a\] -> __try__ \{ ->     puts \\$f "some message" ->     \# \.\.\. -> \} __finally__ \{ ->     close \\$f -> \} - -Handle different reasons for a file to not be openable for reading: - -> __try__ \{ ->     set f \[open /some/file/name\] -> \} __trap__ \{POSIX EISDIR\} \{\} \{ ->     puts "failed to open /some/file/name: it's a directory" -> \} __trap__ \{POSIX ENOENT\} \{\} \{ ->     puts "failed to open /some/file/name: it doesn't exist" -> \} - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *try* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -catch\(n\), error\(n\), return\(n\), [throw\(n\)](tcllib\_throw\.md) - -# KEYWORDS - -[cleanup](\.\./\.\./\.\./\.\./index\.md\#cleanup), -[error](\.\./\.\./\.\./\.\./index\.md\#error), -[exception](\.\./\.\./\.\./\.\./index\.md\#exception), -[final](\.\./\.\./\.\./\.\./index\.md\#final), [resource -management](\.\./\.\./\.\./\.\./index\.md\#resource\_management) - -# CATEGORY - -Utility - -# COPYRIGHT - -Copyright © 2008 Donal K\. Fellows, BSD licensed DELETED embedded/md/tcllib/files/modules/udpcluster/udpcluster.md Index: embedded/md/tcllib/files/modules/udpcluster/udpcluster.md ================================================================== --- embedded/md/tcllib/files/modules/udpcluster/udpcluster.md +++ embedded/md/tcllib/files/modules/udpcluster/udpcluster.md @@ -1,103 +0,0 @@ - -[//000000001]: # (udpcluster \- Lightweight UDP based tool for cluster node discovery) -[//000000002]: # (Generated from file 'udpcluster\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2016\-2018 Sean Woods ) -[//000000004]: # (udpcluster\(n\) 0\.3\.3 tcllib "Lightweight UDP based tool for cluster node discovery") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -udpcluster \- UDP Peer\-to\-Peer cluster - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Bugs, Ideas, Feedback](#section2) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require udpcluster ?0\.3\.3? -package require ip -package require nettool -package require comm -package require interp -package require dicttool -package require cron - -# DESCRIPTION - -This package is a lightweight alternative to Zeroconf\. It utilizes UDP packets -to populate a table of services provided by each node on a local network\. Each -participant broadcasts a key/value list in plain UTF\-8 which lists what ports -are open, and what protocols are expected on those ports\. Developers are free to -add any additional key/value pairs beyond those\. - -Using udpcluster\. - -For every service you wish to publish invoke: - - cluster::publish echo@[cluster::macid] {port 10000 protocol echo} - -To query what services are available on the local network: - - set results [cluster::search PATTERN] - # And inside that result... - echo@LOCALMACID { - port 10000 - protocol echo - } - -To unpublish a service: - - cluster::unpublish echo@[cluster::macid] - -Results will Historical Notes: - -This tool was originally known as nns::cluster, but as development progressed, -it was clear that it wasn't interacting with any of the other facilities in NNS\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *nameserv* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[name service](\.\./\.\./\.\./\.\./index\.md\#name\_service), -[server](\.\./\.\./\.\./\.\./index\.md\#server) - -# CATEGORY - -Networking - -# COPYRIGHT - -Copyright © 2016\-2018 Sean Woods DELETED embedded/md/tcllib/files/modules/uev/uevent.md Index: embedded/md/tcllib/files/modules/uev/uevent.md ================================================================== --- embedded/md/tcllib/files/modules/uev/uevent.md +++ embedded/md/tcllib/files/modules/uev/uevent.md @@ -1,228 +0,0 @@ - -[//000000001]: # (uevent \- User events) -[//000000002]: # (Generated from file 'uevent\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2012 Andreas Kupries ) -[//000000004]: # (uevent\(n\) 0\.3\.1 tcllib "User events") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uevent \- User events - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require uevent ?0\.3\.1? -package require logger - -[__::uevent::bind__ *tag* *event* *command*](#1) -[__[command](\.\./\.\./\.\./\.\./index\.md\#command)__ *tag* *event* *details*](#2) -[__::uevent::unbind__ *token*](#3) -[__::uevent::generate__ *tag* *event* ?*details*?](#4) -[__::uevent::list__](#5) -[__::uevent::list__ *tag*](#6) -[__::uevent::list__ *tag* *event*](#7) -[__::uevent::watch::tag::add__ *pattern* *command*](#8) -[__\{\*\}command__ __bound__ *tag*](#9) -[__\{\*\}command__ __unbound__ *tag*](#10) -[__::uevent::watch::tag::remove__ *token*](#11) -[__::uevent::watch::event::add__ *tag\_pattern* *event\_pattern* *command*](#12) -[__\{\*\}command__ __bound__ *tag* *event*](#13) -[__\{\*\}command__ __unbound__ *tag* *event*](#14) -[__::uevent::watch::event::remove__ *token*](#15) - -# DESCRIPTION - -This package provides a general facility for the handling of user events\. Allows -the binding of arbitrary commands to arbitrary events on arbitrary tags, removal -of bindings, and event generation\. - -The main difference to the event system built into the Tcl/Tk core is that the -latter can generate only virtual events, and only for widgets\. It is not -possible to use the builtin facilities to bind to events on arbitrary -\(pseudo\-\)objects, nor is it able to generate events for such\. - -Here we can, by assuming that each object in question is represented by its own -tag\. Which is possible as we allow arbitrary tags\. - -More differences: - - 1. The package uses only a two\-level hierarchy, tags and events, to handle - everything, whereas the Tcl/Tk system uses three levels, i\.e\. objects, - tags, and events, with a n:m relationship between objects and tags\. - - 1. This package triggers all bound commands for a tag/event combination, and - they are independent of each other\. A bound command cannot force the event - processing core to abort the processing of command coming after it\. - -# API - -The package exports eight commands, as specified below\. Note that when the -package is used from within Tcl 8\.5\+ all the higher commands are ensembles, i\.e\. -the :: separators can be replaceed by spaces\. - - - __::uevent::bind__ *tag* *event* *command* - - Using this command registers the *command* prefix to be triggered when the - *event* occurs for the *tag*\. The result of the command is an opaque - token representing the binding\. Note that if the same combination of - <*tag*,*event*,*command*> is used multiple times the same token is - returned by every call\. - - The signature of the *command* prefix is - - * __[command](\.\./\.\./\.\./\.\./index\.md\#command)__ *tag* *event* *details* - - where *details* contains the argument\(s\) of the event\. Its contents are - event specific and have to be agreed upon between actual event generator and - consumer\. This package simply transfers the information and does not perform - any processing beyond that\. - - - __::uevent::unbind__ *token* - - This command releases the event binding represented by the *token*\. The - token has to be the result of a call to __::uevent::bind__\. The result - of the command is the empty string\. - - - __::uevent::generate__ *tag* *event* ?*details*? - - This command generates an *event* for the *tag*, triggering all commands - bound to that combination\. The *details* argument is simply passed - unchanged to all event handlers\. It is the responsibility of the code - generating and consuming the event to have an agreement about the format and - contents of the information carried therein\. The result of the command is - the empty string\. - - Note that all bound commands are triggered, independently of each other\. The - event handlers cannot assume a specific order\. They are also *not* called - synchronously with the invokation of this command, but simply put into the - event queue for processing when the system returns to the event loop\. - - Generating an event for an unknown tag, or for a <*tag*,*event*> - combination which has no commands bound to it is allowed, such calls will be - ignored\. - - - __::uevent::list__ - - In this form the command returns a list containing the names of all tags - which have events with commands bound to them\. - - - __::uevent::list__ *tag* - - In this format the command returns a list containing the names of all events - for the *tag* with commands bound to them\. Specifying an unknown tag, i\.e\. - a tag without event and commands, will cause the command to throw an error\. - - - __::uevent::list__ *tag* *event* - - In this format the command returns a list containing all commands bound to - the *event* for the *tag*\. Specifying an unknown tag or unknown event, - will cause the command to throw an error\. - - - __::uevent::watch::tag::add__ *pattern* *command* - - This command sets up a sort of reverse events\. Events generated, i\.e\. the - *command* prefix invoked, when observers bind to and unbind from specific - tags\. - - Note that the command prefix is only invoked twice per tag, first when the - first command is bound to any event of the tag, and second when the last - command bound to the tag is removed\. - - The signature of the *command* prefix is - - * __\{\*\}command__ __bound__ *tag* - - * __\{\*\}command__ __unbound__ *tag* - - The result of the command is a token representing the watcher\. - - - __::uevent::watch::tag::remove__ *token* - - This command removes a watcher for \(un\)bind events on tags\. - - The result of the command is the empty string\. - - - __::uevent::watch::event::add__ *tag\_pattern* *event\_pattern* *command* - - This command sets up a sort of reverse events\. Events generated, i\.e\. the - *command* prefix invoked, when observers bind to and unbind from specific - combinations of tags and events\. - - Note that the command prefix is only invoked twice per tag/event - combination, first when the first command is bound to it, and second when - the last command bound to the it is removed\. - - The signature of the *command* prefix is - - * __\{\*\}command__ __bound__ *tag* *event* - - * __\{\*\}command__ __unbound__ *tag* *event* - - The result of the command is a token representing the watcher\. - - - __::uevent::watch::event::remove__ *token* - - This command removes a watcher for \(un\)bind events on tag/event - combinations\. - - The result of the command is the empty string\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *uevent* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[hook\(n\)](\.\./hook/hook\.md) - -# KEYWORDS - -[bind](\.\./\.\./\.\./\.\./index\.md\#bind), [event](\.\./\.\./\.\./\.\./index\.md\#event), -[generate event](\.\./\.\./\.\./\.\./index\.md\#generate\_event), -[hook](\.\./\.\./\.\./\.\./index\.md\#hook), [unbind](\.\./\.\./\.\./\.\./index\.md\#unbind) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2007\-2012 Andreas Kupries DELETED embedded/md/tcllib/files/modules/uev/uevent_onidle.md Index: embedded/md/tcllib/files/modules/uev/uevent_onidle.md ================================================================== --- embedded/md/tcllib/files/modules/uev/uevent_onidle.md +++ embedded/md/tcllib/files/modules/uev/uevent_onidle.md @@ -1,104 +0,0 @@ - -[//000000001]: # (uevent::onidle \- User events) -[//000000002]: # (Generated from file 'uevent\_onidle\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 Andreas Kupries ) -[//000000004]: # (uevent::onidle\(n\) 0\.1 tcllib "User events") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uevent::onidle \- Request merging and deferal to idle time - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Examples](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require uevent::onidle ?0\.1? -package require logger - -[__::uevent::onidle__ *objectName* *commandprefix*](#1) -[*objectName* __request__](#2) - -# DESCRIPTION - -This package provides objects which can merge multiple requestes for an action -and execute the action the moment the system \(event loop\) becomes idle\. The -action to be run is configured during object construction\. - -# API - -The package exports a class, __uevent::onidle__, as specified below\. - - - __::uevent::onidle__ *objectName* *commandprefix* - - The command creates a new *onidle* object with an associated global Tcl - command whose name is *objectName*\. This command may be used to invoke - various operations on the object\. - - The *commandprefix* is the action to perform when the event loop is idle - and the user asked for it using the method __request__ \(See below\)\. - -The object commands created by the class commands above have the form: - - - *objectName* __request__ - - This method requests the execution of the command prefix specified during - the construction of *objectName* the next time the event loop is idle\. - Multiple requests are merged and cause only one execution of the command - prefix\. - -# Examples - -Examples of this type of deferal are buried in the \(C\-level\) implementations all -the Tk widgets, defering geometry calculations and window redraw activity in -this manner\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *uevent* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[callback](\.\./\.\./\.\./\.\./index\.md\#callback), -[deferal](\.\./\.\./\.\./\.\./index\.md\#deferal), -[event](\.\./\.\./\.\./\.\./index\.md\#event), [idle](\.\./\.\./\.\./\.\./index\.md\#idle), -[merge](\.\./\.\./\.\./\.\./index\.md\#merge), -[on\-idle](\.\./\.\./\.\./\.\./index\.md\#on\_idle) - -# COPYRIGHT - -Copyright © 2008 Andreas Kupries DELETED embedded/md/tcllib/files/modules/units/units.md Index: embedded/md/tcllib/files/modules/units/units.md ================================================================== --- embedded/md/tcllib/files/modules/units/units.md +++ embedded/md/tcllib/files/modules/units/units.md @@ -1,394 +0,0 @@ - -[//000000001]: # (units \- Convert and manipulate quantities with units) -[//000000002]: # (Generated from file 'units\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2000\-2005 Mayo Foundation) -[//000000004]: # (units\(n\) 1\.2 tcllib "Convert and manipulate quantities with units") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -units \- unit conversion - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [UNIT STRING FORMAT](#section3) - - - [Example Valid Unit Strings](#subsection1) - - - [SI UNITS](#section4) - - - [SI Base Units](#subsection2) - - - [SI Derived Units with Special Names](#subsection3) - - - [SI Prefixes](#subsection4) - - - [Non\-SI Units](#subsection5) - - - [Quantities and Derived Units with Special Names](#subsection6) - - - [REFERENCES](#section5) - - - [AUTHORS](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.1 -package require units ?2\.1? - -[__::units::convert__ *value* *targetUnits*](#1) -[__::units::reduce__ *unitString*](#2) -[__::units::new__ *name* *baseUnits*](#3) - -# DESCRIPTION - -This library provides a conversion facility from a variety of scientific and -engineering shorthand notations into floating point numbers\. This allows -application developers to easily convert values with different units into -uniformly scaled numbers\. - -The units conversion facility is also able to convert between compatible units\. -If, for example, a application is expecting a value in *ohms* \(Resistance\), -and the user specifies units of *milliwebers/femtocoulomb*, the conversion -routine will handle it appropriately\. An error will be generated if an incorrect -conversion is attempted\. - -Values are scaled from one set of units to another by dimensional analysis\. Both -the value units and the target units are reduced into primitive units and a -scale factor\. Units are checked for compatibility, and the scale factors are -applied by multiplication and division\. This technique is extremely flexible and -quite robust\. - -New units and new unit abbreviations can be defined in terms of existing units -and abbreviations\. It is also possible to define a new primitive unit, although -that will probably be unnecessary\. New units will most commonly be defined to -accommodate non\-SI measurement systems, such as defining the unit *inch* as -*2\.54 cm*\. - -# COMMANDS - - - __::units::convert__ *value* *targetUnits* - - Converts the *value* string into a floating point number, scaled to the - specified *targetUnits*\. The *value* string may contain a number and - units\. If units are specified, then they must be compatible with the - *targetUnits*\. If units are not specified for the *value*, then it will - be scaled to the target units\. For example, - - % ::units::convert "2.3 miles" km - 3.7014912 - % ::units::convert 300m/s miles/hour - 671.080887616 - % ::units::convert "1.0 m kg/s^2" newton - 1.0 - % ::units::convert 1.0 millimeter - 1000.0 - - - __::units::reduce__ *unitString* - - Returns a unit string consisting of a scale factor followed by a space - separated list of sorted and reduced primitive units\. The reduced unit - string may include a forward\-slash \(separated from the surrounding primitive - subunits by spaces\) indicating that the remaining subunits are in the - denominator\. Generates an error if the *unitString* is invalid\. - - % ::units::reduce pascal - 1000.0 gram / meter second second - - - __::units::new__ *name* *baseUnits* - - Creates a new unit conversion with the specified name\. The new unit *name* - must be only alphabetic \(upper or lower case\) letters\. The *baseUnits* - string can consist of any valid units conversion string, including constant - factors, numerator and denominator parts, units with prefixes, and - exponents\. The baseUnits may contain any number of subunits, but it must - reduce to primitive units\. BaseUnits could also be the string *\-primitive* - to represent a new kind of quantity which cannot be derived from other - units\. But you probably would not do that unless you have discovered some - kind of new universal property\. - - % ::units::new furlong "220 yards" - % ::units::new fortnight "14 days" - % ::units::convert 100m/s furlongs/fortnight - 601288.475303 - -# UNIT STRING FORMAT - -Value and unit string format is quite flexible\. It is possible to define -virtually any combination of units, prefixes, and powers\. Valid unit strings -must conform to these rules\. - - - A unit string consists of an optional scale factor followed by zero or more - subunits\. The scale factor must be a valid floating point number, and may or - may not be separated from the subunits\. The scale factor could be negative\. - - - Subunits are separated form each other by one or more separator characters, - which are space \(" "\), hyphen \("\-"\), asterisk \("\*"\), and forward\-slash - \("/"\)\. Sure, go ahead and complain about using a minus sign \("\-"\) to - represent multiplication\. It just isn't sound mathematics, and, by rights, - we should require everyone to use the asterisk \("\*"\) to separate all units\. - But the bottom line is that complex unit strings like *m\-kg/s^2* are - pleasantly readable\. - - - The forward\-slash seperator \("/"\) indicates that following subunits are in - the denominator\. There can be at most one forward\-slash separator\. - - - Subunits can be floating point scale factors, but with the exception of the - leading scale factor, they must be surrounded by valid separators\. Subunit - scale factors cannot be negative\. \(Remember that the hyphen is a unit - separator\.\) - - - Subunits can be valid units or abbreviations\. They may include a prefix\. - They may include a plural suffix "s" or "es"\. They may also include a power - string denoted by a circumflex \("^"\), followed by a integer, after the unit - name \(or plural suffix, if there is one\)\. Negative exponents are not - allowed\. \(Remember that the hyphen is a unit separator\.\) - -## Example Valid Unit Strings - - Unit String Reduced Unit String - ------------------------------------------------------------ - meter 1.0 meter - kilometer 1000.0 meter - km 1000.0 meter - km/s 1000.0 meter / second - /microsecond 1000000.0 / second - /us 1000000.0 / second - kg-m/s^2 1000.0 gram meter / second second - 30second 30.0 second - 30 second 30.0 second - 30 seconds 30.0 second - 200*meter/20.5*second 9.75609756098 meter / second - -# SI UNITS - -The standard SI units are predefined according to *NIST Special* *Publication -330* \. Standard units for both SI Base Units \(Table 1\) and SI Derived Units -with Special Names \(Tables 3a and 3b\) are included here for reference\. Each -standard unit name and abbreviation are included in this package\. - -## SI Base Units - - Quantity Unit Name Abbr. - --------------------------------------------- - Length meter m - Mass kilogram kg - Time second s - Current ampere A - Temperature kelvin K - Amount mole mol - Luminous Intensity candela cd - -## SI Derived Units with Special Names - - Quantity Unit Name Abbr. Units Base Units - -------------------------------------------------------------------- - plane angle radian rad m/m m/m - solid angle steradian sr m^2/m^2 m^2/m^2 - frequency hertz Hz /s - force newton N m-kg/s^2 - pressure pascal Pa N/m^2 kg/m-s^2 - energy, work joule J N-m m^2-kg/s^2 - power, radiant flux watt W J/s m^2-kg/s^3 - electric charge coulomb C s-A - electric potential volt V W/A m^2-kg/s^3-A - capacitance farad F C/V s^4-A^2/m^2-kg - electric resistance ohm V/A m^2-kg/s^3-A^2 - electric conductance siemens S A/V s^3-A^2/m^2-kg - magnetic flux weber Wb V-s m^2-kg/s^2-A - magnetic flux density tesla T Wb/m^2 kg/s^2-A - inductance henry H Wb/A m^2-kg/s^2-A^2 - luminous flux lumen lm cd-sr - illuminance lux lx lm/m^2 cd-sr/m^2 - activity (of a - radionuclide) becquerel Bq /s - absorbed dose gray Gy J/kg m^2/s^2 - dose equivalent sievert Sv J/kg m^2/s^2 - -Note that the SI unit kilograms is actually implemented as grams because 1e\-6 -kilogram = 1 milligram, not 1 microkilogram\. The abbreviation for Electric -Resistance \(ohms\), which is the omega character, is not supported\. - -Also note that there is no support for Celsius or Farenheit temperature\. The -units conversion routines can only scale values with multiplication and -division, so it is not possible to convert from thermodynamic temperature -\(kelvins\) to absolute degrees Celsius or Farenheit\. Conversion of thermodynamic -quantities, such as thermal expansion \(per unit temperature\), however, are easy -to add to the units library\. - -SI Units can have a multiple or sub\-multiple prefix\. The prefix or its -abbreviation should appear before the unit, without spaces\. Compound prefixes -are not allowed, and a prefix should never be used alone\. These prefixes are -defined in Table 5 of *Special Publication* *330* \. - -## SI Prefixes - - Prefix Name Abbr. Factor - --------------------------------------- - yotta Y 1e24 - zetta Z 1e21 - exa E 1e18 - peta P 1e15 - tera T 1e12 - giga G 1e9 - mega M 1e6 - kilo k 1e3 - hecto h 1e2 - deka da 1e1 - deca 1e1 - - deci d 1e-1 - centi c 1e-2 - milli m 1e-3 - micro u 1e-6 - nano n 1e-9 - pico p 1e-12 - femto f 1e-15 - atto a 1e-18 - zepto z 1e-21 - yocto y 1e-24 - -Note that we define the same prefix with both the USA \("deka"\) and non\-USA -\("deca"\) spellings\. Also note that we take the liberty of allowing "micro" to be -typed as a "u" instead of the Greek character mu\. - -Many non\-SI units are commonly used in applications\. Appendix B\.8 of *NIST -Special Publication 811* lists many non\-SI conversion factors\. It is not -possible to include all possible unit definitions in this package\. In some -cases, many different conversion factors exist for a given unit, depending on -the context\. \(The appendix lists over 40 conversions for British thermal units\!\) -Application specific conversions can always be added using the __new__ -command, but some well known and often used conversions are included in this -package\. - -## Non\-SI Units - - Unit Name Abbr. Base Units - -------------------------------------------------- - angstrom 1.0E-10 m - astronomicalUnit AU 1.495979E11 m - atmosphere 1.01325E5 Pa - bar 1.0E5 Pa - calorie 4.1868 J - curie 3.7E10 Bq - day 8.64E4 s - degree 1.745329E-2 rad - erg 1.0E-7 J - faraday 9.648531 C - fermi 1.0E-15 m - foot ft 3.048E-1 m - gauss 1.0E-4 T - gilbert 7.957747E-1 A - grain gr 6.479891E-5 kg - hectare ha 1.0E4 m^2 - hour h 3.6E3 s - inch in 2.54E-2 m - lightYear 9.46073E15 m - liter L 1.0E-3 m^3 - maxwell Mx 1.0E-8 Wb - mho 1.0 S - micron 1.0E-6 m - mil 2.54E-5 m - mile mi 1.609344E3 m - minute min 6.0E1 s - parsec pc 3.085E16 m - pica 4.233333E-3 m - pound lb 4.535924E-1 kg - revolution 6.283185 rad - revolutionPerMinute rpm 1.047198E-1 rad/s - yard yd 9.144E-1 m - year 3.1536E7 s - -## Quantities and Derived Units with Special Names - -This units conversion package is limited specifically to unit reduction, -comparison, and scaling\. This package does not consider any of the quantity -names for either base or derived units\. A similar implementation or an extension -in a typed or object\-oriented language might introduce user defined types for -the quantities\. Quantity type checking could be used, for example, to ensure -that all *length* values properly reduced to *meters*, or that all -*velocity* values properly reduced to *meters/second*\. - -A C implementation of this package has been created to work in conjunction with -the Simplified Wrapper Interface Generator -\([http://www\.swig\.org/](http://www\.swig\.org/)\)\. That package \(units\.i\) -exploits SWIG's typemap system to automatically convert script quantity strings -into floating point quantities\. Function arguments are specified as quantity -types \(e\.g\., *typedef float Length*\), and target units \(expected by the C -application code\) are specified in an associative array\. Default units are also -defined for each quantity type, and are applied to any unit\-less quantity -strings\. - -A units system enhanced with quantity type checking might benefit from inclusion -of other derived types which are expressed in terms of special units, as -illustrated in Table 2 of *NIST Publication* *330* \. The quantity *area*, -for example, could be defined as units properly reducing to *meter^2*, -although the utility of defining a unit named *square meter* is arguable\. - -# REFERENCES - -The unit names, abbreviations, and conversion values are derived from those -published by the United States Department of Commerce Technology Administration, -National Institute of Standards and Technology \(NIST\) in *NIST Special -Publication 330: The International System of* *Units \(SI\)* and *NIST Special -Publication 811: Guide for* *the Use of the International System of Units -\(SI\)* \. Both of these publications are available \(as of December 2000\) from -[http://physics\.nist\.gov/cuu/Reference/contents\.html](http://physics\.nist\.gov/cuu/Reference/contents\.html) - -The ideas behind implementation of this package is based in part on code written -in 1993 by Adrian Mariano which performed dimensional analysis of unit strings -using fixed size tables of C structs\. After going missing in the late 1990's, -Adrian's code has reappeared in the GNU Units program at -[http://www\.gnu\.org/software/units/](http://www\.gnu\.org/software/units/) - -# AUTHORS - -Robert W\. Techentin - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *units* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[angle](\.\./\.\./\.\./\.\./index\.md\#angle), -[constants](\.\./\.\./\.\./\.\./index\.md\#constants), -[conversion](\.\./\.\./\.\./\.\./index\.md\#conversion), -[distance](\.\./\.\./\.\./\.\./index\.md\#distance), -[radians](\.\./\.\./\.\./\.\./index\.md\#radians), -[unit](\.\./\.\./\.\./\.\./index\.md\#unit) - -# COPYRIGHT - -Copyright © 2000\-2005 Mayo Foundation DELETED embedded/md/tcllib/files/modules/uri/uri.md Index: embedded/md/tcllib/files/modules/uri/uri.md ================================================================== --- embedded/md/tcllib/files/modules/uri/uri.md +++ embedded/md/tcllib/files/modules/uri/uri.md @@ -1,522 +0,0 @@ - -[//000000001]: # (uri \- Tcl Uniform Resource Identifier Management) -[//000000002]: # (Generated from file 'uri\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (uri\(n\) 1\.2\.7 tcllib "Tcl Uniform Resource Identifier Management") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uri \- URI utilities - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [SCHEMES](#section3) - - - [EXTENDING](#section4) - - - [QUIRK OPTIONS](#section5) - - - [BACKWARD COMPATIBILITY](#subsection1) - - - [NEW DESIGNS](#subsection2) - - - [DEFAULT VALUES](#subsection3) - - - [EXAMPLES](#section6) - - - [CREDITS](#section7) - - - [Bugs, Ideas, Feedback](#section8) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require uri ?1\.2\.7? - -[__uri::setQuirkOption__ *option* ?*value*?](#1) -[__uri::split__ *url* ?*defaultscheme*?](#2) -[__uri::join__ ?*key* *value*?\.\.\.](#3) -[__uri::resolve__ *base* *url*](#4) -[__uri::isrelative__ *url*](#5) -[__uri::geturl__ *url* ?*options*\.\.\.?](#6) -[__uri::canonicalize__ *uri*](#7) -[__uri::register__ *schemeList* *script*](#8) - -# DESCRIPTION - -This package does two things\. - -First, it provides a number of commands for manipulating URLs/URIs and fetching -data specified by them\. For fetching data this package analyses the requested -URL/URI and then dispatches it to the appropriate package -\(__[http](\.\./\.\./\.\./\.\./index\.md\#http)__, -__[ftp](\.\./ftp/ftp\.md)__, \.\.\.\) for actual retrieval\. Currently these -commands are defined for the schemes *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, -*[https](\.\./\.\./\.\./\.\./index\.md\#https)*, -*[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, -*[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, -*[news](\.\./\.\./\.\./\.\./index\.md\#news)*, -*[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, *ldaps* and -*[file](\.\./\.\./\.\./\.\./index\.md\#file)*\. The package __uri::urn__ adds -scheme *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)*\. - -Second, it provides regular expressions for a number of __registered__ -URL/URI schemes\. Registered schemes are currently -*[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, -*[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, *ldaps*, -*[file](\.\./\.\./\.\./\.\./index\.md\#file)*, -*[http](\.\./\.\./\.\./\.\./index\.md\#http)*, -*[https](\.\./\.\./\.\./\.\./index\.md\#https)*, -*[gopher](\.\./\.\./\.\./\.\./index\.md\#gopher)*, -*[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, -*[news](\.\./\.\./\.\./\.\./index\.md\#news)*, -*[wais](\.\./\.\./\.\./\.\./index\.md\#wais)* and -*[prospero](\.\./\.\./\.\./\.\./index\.md\#prospero)*\. The package __uri::urn__ -adds scheme *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)*\. - -The commands of the package conform to RFC 3986 -\([https://www\.rfc\-editor\.org/rfc/rfc3986\.txt](https://www\.rfc\-editor\.org/rfc/rfc3986\.txt)\), -with the exception of a loophole arising from RFC 1630 and described in RFC 3986 -Sections 5\.2\.2 and 5\.4\.2\. The loophole allows a relative URI to include a scheme -if it is the same as the scheme of the base URI against which it is resolved\. -RFC 3986 recommends avoiding this usage\. - -# COMMANDS - - - __uri::setQuirkOption__ *option* ?*value*? - - __uri::setQuirkOption__ is an accessor command for a number of "quirk - options"\. The command has the same semantics as the command - __[set](\.\./\.\./\.\./\.\./index\.md\#set)__: when called with one argument - it reads an existing value; with two arguments it writes a new value\. The - value of a "quirk option" is boolean: the value __false__ requests - conformance with RFC 3986, while __true__ requests use of the quirk\. See - section [QUIRK OPTIONS](#section5) for discussion of the different - options and their purpose\. - - - __uri::split__ *url* ?*defaultscheme*? - - __uri::split__ takes a *url*, decodes it and then returns a list of - key/value pairs suitable for __array set__ containing the constituents - of the *url*\. If the scheme is missing from the *url* it defaults to the - value of *defaultscheme* if it was specified, or - *[http](\.\./\.\./\.\./\.\./index\.md\#http)* else\. Currently the schemes - *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, - *[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, - *[news](\.\./\.\./\.\./\.\./index\.md\#news)*, - *[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, *ldaps* and - *[file](\.\./\.\./\.\./\.\./index\.md\#file)* are supported by the package - itself\. See section [EXTENDING](#section4) on how to expand that range\. - - The set of constituents of a URL \(= the set of keys in the returned - dictionary\) is dependent on the scheme of the URL\. The only key which is - therefore always present is __scheme__\. For the following schemes the - constituents and their keys are known: - - * ftp - - __user__, __pwd__, __host__, __port__, __path__, - __type__, __pbare__\. The pbare is optional\. - - * http\(s\) - - __user__, __pwd__, __host__, __port__, __path__, - __query__, __fragment__, __pbare__\. The pbare is optional\. - - * file - - __path__, __host__\. The host is optional\. - - * mailto - - __user__, __host__\. The host is optional\. - - * ldap\(s\) - - __host__, __port__, __dn__, __attrs__, __scope__, - __filter__, __extensions__ - - * news - - Either __message\-id__ or __newsgroup\-name__\. - - For discussion of the boolean __pbare__ see options *NoInitialSlash* - and *NoExtraKeys* in [QUIRK OPTIONS](#section5)\. - - The constituents are returned as slices of the argument *url*, without - removal of percent\-encoding \("url\-encoding"\) or other adaptations\. Notably, - on Windows® the __path__ in scheme - *[file](\.\./\.\./\.\./\.\./index\.md\#file)* is not a valid local filename\. See - [EXAMPLES](#section6) for more information\. - - - __uri::join__ ?*key* *value*?\.\.\. - - __uri::join__ takes a list of key/value pairs \(generated by - __uri::split__, for example\) and returns the canonical URL they - represent\. Currently the schemes *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, - *[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, - *[news](\.\./\.\./\.\./\.\./index\.md\#news)*, - *[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, *ldaps* and - *[file](\.\./\.\./\.\./\.\./index\.md\#file)* are supported by the package - itself\. See section [EXTENDING](#section4) on how to expand that range\. - - The arguments are expected to be slices of a valid URL, with - percent\-encoding \("url\-encoding"\) and any other necessary adaptations\. - Notably, on Windows the __path__ in scheme - *[file](\.\./\.\./\.\./\.\./index\.md\#file)* is not a valid local filename\. See - [EXAMPLES](#section6) for more information\. - - - __uri::resolve__ *base* *url* - - __uri::resolve__ resolves the specified *url* relative to *base*, in - conformance with RFC 3986\. In other words: a non\-relative *url* is - returned unchanged, whereas for a relative *url* the missing parts are - taken from *base* and prepended to it\. The result of this operation is - returned\. For an empty *url* the result is *base*, without its URI - fragment \(if any\)\. The command is available for schemes - *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, and - *[file](\.\./\.\./\.\./\.\./index\.md\#file)*\. - - - __uri::isrelative__ *url* - - __uri::isrelative__ determines whether the specified *url* is absolute - or relative\. The command is available for a *url* of any scheme\. - - - __uri::geturl__ *url* ?*options*\.\.\.? - - __uri::geturl__ decodes the specified *url* and then dispatches the - request to the package appropriate for the scheme found in the URL\. The - command assumes that the package to handle the given scheme either has the - same name as the scheme itself \(including possible capitalization\) followed - by __::geturl__, or, in case of this failing, has the same name as the - scheme itself \(including possible capitalization\)\. It further assumes that - whatever package was loaded provides a __geturl__\-command in the - namespace of the same name as the package itself\. This command is called - with the given *url* and all given *options*\. Currently __geturl__ - does not handle any options itself\. - - *Note:* *[file](\.\./\.\./\.\./\.\./index\.md\#file)*\-URLs are an exception to - the rule described above\. They are handled internally\. - - It is not possible to specify results of the command\. They depend on the - __geturl__\-command for the scheme the request was dispatched to\. - - - __uri::canonicalize__ *uri* - - __uri::canonicalize__ returns the canonical form of a URI\. The canonical - form of a URI is one where relative path specifications, i\.e\. "\." and "\.\.", - have been resolved\. The command is available for all URI schemes that have - __uri::split__ and __uri::join__ commands\. The command returns a - canonicalized URI if the URI scheme has a __path__ component \(i\.e\. - *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, and - *[file](\.\./\.\./\.\./\.\./index\.md\#file)*\)\. For schemes that have - __uri::split__ and __uri::join__ commands but no __path__ - component \(i\.e\. *[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, - *[news](\.\./\.\./\.\./\.\./index\.md\#news)*, - *[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, and *ldaps*\), the command - returns the *uri* unchanged\. - - - __uri::register__ *schemeList* *script* - - __uri::register__ registers the first element of *schemeList* as a new - scheme and the remaining elements as aliases for this scheme\. It creates the - namespace for the scheme and executes the *script* in the new namespace\. - The script has to declare variables containing regular expressions relevant - to the scheme\. At least the variable __schemepart__ has to be declared - as that one is used to extend the variables keeping track of the registered - schemes\. - -# SCHEMES - -In addition to the commands mentioned above this package provides regular -expression to recognize URLs for a number of URL schemes\. - -For each supported scheme a namespace of the same name as the scheme itself is -provided inside of the namespace *uri* containing the variable __url__ -whose contents are a regular expression to recognize URLs of that scheme\. -Additional variables may contain regular expressions for parts of URLs for that -scheme\. - -The variable __uri::schemes__ contains a list of all registered schemes\. -Currently these are *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, -*[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap)*, *ldaps*, -*[file](\.\./\.\./\.\./\.\./index\.md\#file)*, -*[http](\.\./\.\./\.\./\.\./index\.md\#http)*, -*[https](\.\./\.\./\.\./\.\./index\.md\#https)*, -*[gopher](\.\./\.\./\.\./\.\./index\.md\#gopher)*, -*[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto)*, -*[news](\.\./\.\./\.\./\.\./index\.md\#news)*, -*[wais](\.\./\.\./\.\./\.\./index\.md\#wais)* and -*[prospero](\.\./\.\./\.\./\.\./index\.md\#prospero)*\. - -# EXTENDING - -Extending the range of schemes supported by __uri::split__ and -__uri::join__ is easy because both commands do not handle the request by -themselves but dispatch it to another command in the *uri* namespace using the -scheme of the URL as criterion\. - -__uri::split__ and __uri::join__ call __Split\[string totitle -\]__ and __Join\[string totitle \]__ respectively\. - -The provision of split and join commands is sufficient to extend the commands -__uri::canonicalize__ and __uri::geturl__ \(the latter subject to the -availability of a suitable package with a __geturl__ command\)\. In contrast, -to extend the command __uri::resolve__ to a new scheme, the command itself -must be modified\. - -To extend the range of schemes for which pattern information is available, use -the command __uri::register__\. - -An example of a package that provides both commands and pattern information for -a new scheme is __uri::urn__, which adds scheme -*[urn](\.\./\.\./\.\./\.\./index\.md\#urn)*\. - -# QUIRK OPTIONS - -The value of a "quirk option" is boolean: the value __false__ requests -conformance with RFC 3986, while __true__ requests use of the quirk\. Use -command __uri::setQuirkOption__ to access the values of quirk options\. - -Quirk options are useful both for allowing backwards compatibility when a -command specification changes, and for adding useful features that are not -included in RFC specifications\. The following quirk options are currently -defined: - - - *NoInitialSlash* - - This quirk option concerns the leading character of __path__ \(if - non\-empty\) in the schemes *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, and - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*\. - - RFC 3986 defines __path__ in an absolute URI to have an initial "/", - unless the value of __path__ is the empty string\. For the scheme - *[file](\.\./\.\./\.\./\.\./index\.md\#file)*, all versions of package - __uri__ follow this rule\. The quirk option *NoInitialSlash* does not - apply to scheme *[file](\.\./\.\./\.\./\.\./index\.md\#file)*\. - - For the schemes *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, and - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, versions of __uri__ before - 1\.2\.7 define the __path__ *NOT* to include an initial "/"\. When the - quirk option *NoInitialSlash* is __true__ \(the default\), this behavior - is also used in version 1\.2\.7\. To use instead values of __path__ as - defined by RFC 3986, set this quirk option to __false__\. - - This setting does not affect RFC 3986 conformance\. If *NoInitialSlash* is - __true__, then the value of __path__ in the schemes - *[http](\.\./\.\./\.\./\.\./index\.md\#http)*, - *[https](\.\./\.\./\.\./\.\./index\.md\#https)*, or - *[ftp](\.\./\.\./\.\./\.\./index\.md\#ftp)*, cannot distinguish between URIs in - which the full "RFC 3986 path" is the empty string "" or a single slash "/" - respectively\. The missing information is recorded in an additional - __uri::split__ key __pbare__\. - - The boolean __pbare__ is defined when quirk options *NoInitialSlash* - and *NoExtraKeys* have values __true__ and __false__ respectively\. - In this case, if the value of __path__ is the empty string "", - __pbare__ is __true__ if the full "RFC 3986 path" is "", and - __pbare__ is __false__ if the full "RFC 3986 path" is "/"\. - - Using this quirk option *NoInitialSlash* is a matter of preference\. - - - *NoExtraKeys* - - This quirk option permits full backward compatibility with versions of - __uri__ before 1\.2\.7, by omitting the __uri::split__ key - __pbare__ described above \(see quirk option *NoInitialSlash*\)\. The - outcome is greater backward compatibility of the __uri::split__ command, - but an inability to distinguish between URIs in which the full "RFC 3986 - path" is the empty string "" or a single slash "/" respectively \- i\.e\. a - minor non\-conformance with RFC 3986\. - - If the quirk option *NoExtraKeys* is __false__ \(the default\), command - __uri::split__ returns an additional key __pbare__, and the commands - comply with RFC 3986\. If the quirk option *NoExtraKeys* is __true__, - the key __pbare__ is not defined and there is not full conformance with - RFC 3986\. - - Using the quirk option *NoExtraKeys* is *NOT* recommended, because if - set to __true__ it will reduce conformance with RFC 3986\. The option is - included only for compatibility with code, written for earlier versions of - __uri__, that needs values of __path__ without a leading "/", *AND - ALSO* cannot tolerate unexpected keys in the results of __uri::split__\. - - - *HostAsDriveLetter* - - When handling the scheme *[file](\.\./\.\./\.\./\.\./index\.md\#file)* on the - Windows platform, versions of __uri__ before 1\.2\.7 use the __host__ - field to represent a Windows drive letter and the colon that follows it, and - the __path__ field to represent the filename path after the colon\. Such - URIs are invalid, and are not recognized by any RFC\. When the quirk option - *HostAsDriveLetter* is __true__, this behavior is also used in version - 1\.2\.7\. To use *[file](\.\./\.\./\.\./\.\./index\.md\#file)* URIs on Windows that - conform to RFC 3986, set this quirk option to __false__ \(the default\)\. - - Using this quirk is *NOT* recommended, because if set to __true__ it - will cause the __uri__ commands to expect and produce invalid URIs\. The - option is included only for compatibility with legacy code\. - - - *RemoveDoubleSlashes* - - When a URI is canonicalized by __uri::canonicalize__, its __path__ - is normalized by removal of segments "\." and "\.\."\. RFC 3986 does not mandate - the removal of empty segments "" \(i\.e\. the merger of double slashes, which - is a feature of filename normalization but not of URI __path__ - normalization\): it treats URIs with excess slashes as referring to different - resources\. When the quirk option *RemoveDoubleSlashes* is __true__ - \(the default\), empty segments will be removed from __path__\. To prevent - removal, and thereby conform to RFC 3986, set this quirk option to - __false__\. - - Using this quirk is a matter of preference\. A URI with double slashes in its - path was most likely generated by error, certainly so if it has a - straightforward mapping to a file on a server\. In some cases it may be - better to sanitize the URI; in others, to keep the URI and let the server - handle the possible error\. - -## BACKWARD COMPATIBILITY - -To behave as similarly as possible to versions of __uri__ earlier than -1\.2\.7, set the following quirk options: - - - __uri::setQuirkOption__ *NoInitialSlash* 1 - - - __uri::setQuirkOption__ *NoExtraKeys* 1 - - - __uri::setQuirkOption__ *HostAsDriveLetter* 1 - - - __uri::setQuirkOption__ *RemoveDoubleSlashes* 0 - -In code that can tolerate the return by __uri::split__ of an additional key -__pbare__, set - - - __uri::setQuirkOption__ *NoExtraKeys* 0 - -in order to achieve greater compliance with RFC 3986\. - -## NEW DESIGNS - -For new projects, the following settings are recommended: - - - __uri::setQuirkOption__ *NoInitialSlash* 0 - - - __uri::setQuirkOption__ *NoExtraKeys* 0 - - - __uri::setQuirkOption__ *HostAsDriveLetter* 0 - - - __uri::setQuirkOption__ *RemoveDoubleSlashes* 0|1 - -## DEFAULT VALUES - -The default values for package __uri__ version 1\.2\.7 are intended to be a -compromise between backwards compatibility and improved features\. Different -default values may be chosen in future versions of package __uri__\. - - - __uri::setQuirkOption__ *NoInitialSlash* 1 - - - __uri::setQuirkOption__ *NoExtraKeys* 0 - - - __uri::setQuirkOption__ *HostAsDriveLetter* 0 - - - __uri::setQuirkOption__ *RemoveDoubleSlashes* 1 - -# EXAMPLES - -A Windows® local filename such as "__C:\\Other Files\\startup\.txt__" is not -suitable for use as the __path__ element of a URI in the scheme -*[file](\.\./\.\./\.\./\.\./index\.md\#file)*\. - -The Tcl command __file normalize__ will convert the backslashes to forward -slashes\. To generate a valid __path__ for the scheme -*[file](\.\./\.\./\.\./\.\./index\.md\#file)*, the normalized filename must be -prepended with "__/__", and then any characters that do not match the -__regexp__ bracket expression - - [a-zA-Z0-9$_.+!*'(,)?:@&=-] - -must be percent\-encoded\. - -The result in this example is "__/C:/Other%20Files/startup\.txt__" which is a -valid value for __path__\. - - % uri::join path /C:/Other%20Files/startup.txt scheme file - - file:///C:/Other%20Files/startup.txt - - % uri::split file:///C:/Other%20Files/startup.txt - - path /C:/Other%20Files/startup.txt scheme file - -On UNIX® systems filenames begin with "__/__" which is also used as the -directory separator\. The only action needed to convert a filename to a valid -__path__ is percent\-encoding\. - -# CREDITS - -Original code \(regular expressions\) by Andreas Kupries\. Modularisation by Steve -Ball, also the split/join/resolve functionality\. RFC 3986 conformance by Keith -Nash\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *uri* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[fetching information](\.\./\.\./\.\./\.\./index\.md\#fetching\_information), -[file](\.\./\.\./\.\./\.\./index\.md\#file), [ftp](\.\./\.\./\.\./\.\./index\.md\#ftp), -[gopher](\.\./\.\./\.\./\.\./index\.md\#gopher), -[http](\.\./\.\./\.\./\.\./index\.md\#http), [https](\.\./\.\./\.\./\.\./index\.md\#https), -[ldap](\.\./\.\./\.\./\.\./index\.md\#ldap), -[mailto](\.\./\.\./\.\./\.\./index\.md\#mailto), -[news](\.\./\.\./\.\./\.\./index\.md\#news), -[prospero](\.\./\.\./\.\./\.\./index\.md\#prospero), [rfc -1630](\.\./\.\./\.\./\.\./index\.md\#rfc\_1630), [rfc -2255](\.\./\.\./\.\./\.\./index\.md\#rfc\_2255), [rfc -2396](\.\./\.\./\.\./\.\./index\.md\#rfc\_2396), [rfc -3986](\.\./\.\./\.\./\.\./index\.md\#rfc\_3986), [uri](\.\./\.\./\.\./\.\./index\.md\#uri), -[url](\.\./\.\./\.\./\.\./index\.md\#url), [wais](\.\./\.\./\.\./\.\./index\.md\#wais), -[www](\.\./\.\./\.\./\.\./index\.md\#www) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/uri/urn-scheme.md Index: embedded/md/tcllib/files/modules/uri/urn-scheme.md ================================================================== --- embedded/md/tcllib/files/modules/uri/urn-scheme.md +++ embedded/md/tcllib/files/modules/uri/urn-scheme.md @@ -1,87 +0,0 @@ - -[//000000001]: # (uri\_urn \- Tcl Uniform Resource Identifier Management) -[//000000002]: # (Generated from file 'urn\-scheme\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (uri\_urn\(n\) 1\.0\.3 tcllib "Tcl Uniform Resource Identifier Management") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uri\_urn \- URI utilities, URN scheme - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.2 -package require uri::urn ?1\.0\.3? - -[__uri::urn::quote__ *url*](#1) -[__uri::urn::unquote__ *url*](#2) - -# DESCRIPTION - -This package provides two commands to quote and unquote the disallowed -characters for url using the *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)* scheme, -registers the scheme with the package __[uri](uri\.md)__, and provides -internal helpers which will be automatically used by the commands -__uri::split__ and __uri::join__ of package __[uri](uri\.md)__ to -handle urls using the *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)* scheme\. - -# COMMANDS - - - __uri::urn::quote__ *url* - - This command quotes the characters disallowed by the - *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)* scheme \(per RFC 2141 sec2\.2\) in the - *url* and returns the modified url as its result\. - - - __uri::urn::unquote__ *url* - - This commands performs the reverse of __::uri::urn::quote__\. It takes an - *[urn](\.\./\.\./\.\./\.\./index\.md\#urn)* url, removes the quoting from all - disallowed characters, and returns the modified urls as its result\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *uri* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[rfc 2141](\.\./\.\./\.\./\.\./index\.md\#rfc\_2141), -[uri](\.\./\.\./\.\./\.\./index\.md\#uri), [url](\.\./\.\./\.\./\.\./index\.md\#url), -[urn](\.\./\.\./\.\./\.\./index\.md\#urn) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/uuid/uuid.md Index: embedded/md/tcllib/files/modules/uuid/uuid.md ================================================================== --- embedded/md/tcllib/files/modules/uuid/uuid.md +++ embedded/md/tcllib/files/modules/uuid/uuid.md @@ -1,102 +0,0 @@ - -[//000000001]: # (uuid \- uuid) -[//000000002]: # (Generated from file 'uuid\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2004, Pat Thoyts ) -[//000000004]: # (uuid\(n\) 1\.0\.6 tcllib "uuid") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -uuid \- UUID generation and comparison - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [REFERENCES](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require uuid ?1\.0\.6? - -[__::uuid::uuid generate__](#1) -[__::uuid::uuid equal__ *id1* *id2*](#2) - -# DESCRIPTION - -This package provides a generator of universally unique identifiers \(UUID\) also -known as globally unique identifiers \(GUID\)\. This implementation follows the -draft specification from \(1\) although this is actually an expired draft -document\. - -# COMMANDS - - - __::uuid::uuid generate__ - - Creates a type 4 uuid by MD5 hashing a number of bits of variant data - including the time and hostname\. Returns the string representation of the - new uuid\. - - - __::uuid::uuid equal__ *id1* *id2* - - Compares two uuids and returns true if both arguments are the same uuid\. - -# EXAMPLES - - % uuid::uuid generate - b12dc22c-5c36-41d2-57da-e29d0ef5839c - -# REFERENCES - - 1. Paul J\. Leach, "UUIDs and GUIDs", February 1998\. - \([http://www\.opengroup\.org/dce/info/draft\-leach\-uuids\-guids\-01\.txt](http://www\.opengroup\.org/dce/info/draft\-leach\-uuids\-guids\-01\.txt)\) - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *uuid* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[GUID](\.\./\.\./\.\./\.\./index\.md\#guid), [UUID](\.\./\.\./\.\./\.\./index\.md\#uuid) - -# CATEGORY - -Hashes, checksums, and encryption - -# COPYRIGHT - -Copyright © 2004, Pat Thoyts DELETED embedded/md/tcllib/files/modules/valtype/cc_amex.md Index: embedded/md/tcllib/files/modules/valtype/cc_amex.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/cc_amex.md +++ embedded/md/tcllib/files/modules/valtype/cc_amex.md @@ -1,155 +0,0 @@ - -[//000000001]: # (valtype::creditcard::amex \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::creditcard::amex\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::creditcard::amex \- Validation for AMEX creditcard number - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::creditcard::amex ?1? - -[__valtype::creditcard::amex__ __validate__ *value*](#1) -[__valtype::creditcard::amex__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for an AMEX creditcard number\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::creditcard::amex validate .... ;# Does nothing - valtype::creditcard::amex validate .... ;# Throws an error (bad American Expresss creditcard number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::creditcard::amex__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::creditcard::amex__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __CREDITCARD AMEX__\. This is then -followed by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are: - - - INVALID CREDITCARD AMEX CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an AMEX creditcard number\. - - - INVALID CREDITCARD AMEX CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID CREDITCARD AMEX LENGTH - - The input value is of the wrong length to be an AMEX creditcard number\. - - - INVALID CREDITCARD AMEX PREFIX - - The input value does not start with the magic value\(s\) required for it to be - an AMEX creditcard number\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[AMEX](\.\./\.\./\.\./\.\./index\.md\#amex), [American -Express](\.\./\.\./\.\./\.\./index\.md\#american\_express), -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[bank](\.\./\.\./\.\./\.\./index\.md\#bank), [card for -credit](\.\./\.\./\.\./\.\./index\.md\#card\_for\_credit), [credit -card](\.\./\.\./\.\./\.\./index\.md\#credit\_card), -[finance](\.\./\.\./\.\./\.\./index\.md\#finance), [isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/cc_discover.md Index: embedded/md/tcllib/files/modules/valtype/cc_discover.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/cc_discover.md +++ embedded/md/tcllib/files/modules/valtype/cc_discover.md @@ -1,154 +0,0 @@ - -[//000000001]: # (valtype::creditcard::discover \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::creditcard::discover\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::creditcard::discover \- Validation for Discover creditcard number - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::creditcard::discover ?1? - -[__valtype::creditcard::discover__ __validate__ *value*](#1) -[__valtype::creditcard::discover__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a Discover creditcard number\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::creditcard::discover validate .... ;# Does nothing - valtype::creditcard::discover validate .... ;# Throws an error (bad Discover creditcard number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::creditcard::discover__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::creditcard::discover__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __CREDITCARD DISCOVER__\. This is -then followed by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are: - - - INVALID CREDITCARD DISCOVER CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a Discover creditcard number\. - - - INVALID CREDITCARD DISCOVER CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID CREDITCARD DISCOVER LENGTH - - The input value is of the wrong length to be a Discover creditcard number\. - - - INVALID CREDITCARD DISCOVER PREFIX - - The input value does not start with the magic value\(s\) required for it to be - a Discover creditcard number\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Discover](\.\./\.\./\.\./\.\./index\.md\#discover), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[bank](\.\./\.\./\.\./\.\./index\.md\#bank), [card for -credit](\.\./\.\./\.\./\.\./index\.md\#card\_for\_credit), [credit -card](\.\./\.\./\.\./\.\./index\.md\#credit\_card), -[finance](\.\./\.\./\.\./\.\./index\.md\#finance), [isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/cc_mastercard.md Index: embedded/md/tcllib/files/modules/valtype/cc_mastercard.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/cc_mastercard.md +++ embedded/md/tcllib/files/modules/valtype/cc_mastercard.md @@ -1,155 +0,0 @@ - -[//000000001]: # (valtype::creditcard::mastercard \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::creditcard::mastercard\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::creditcard::mastercard \- Validation for Mastercard creditcard number - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::creditcard::mastercard ?1? - -[__valtype::creditcard::mastercard__ __validate__ *value*](#1) -[__valtype::creditcard::mastercard__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a Mastercard creditcard -number\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::creditcard::mastercard validate .... ;# Does nothing - valtype::creditcard::mastercard validate .... ;# Throws an error (bad Mastercard creditcard number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::creditcard::mastercard__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::creditcard::mastercard__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __CREDITCARD MASTERCARD__\. This is -then followed by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are: - - - INVALID CREDITCARD MASTERCARD CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a Mastercard creditcard number\. - - - INVALID CREDITCARD MASTERCARD CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID CREDITCARD MASTERCARD LENGTH - - The input value is of the wrong length to be a Mastercard creditcard number\. - - - INVALID CREDITCARD MASTERCARD PREFIX - - The input value does not start with the magic value\(s\) required for it to be - a Mastercard creditcard number\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[MasterCard](\.\./\.\./\.\./\.\./index\.md\#mastercard), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[bank](\.\./\.\./\.\./\.\./index\.md\#bank), [card for -credit](\.\./\.\./\.\./\.\./index\.md\#card\_for\_credit), [credit -card](\.\./\.\./\.\./\.\./index\.md\#credit\_card), -[finance](\.\./\.\./\.\./\.\./index\.md\#finance), [isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/cc_visa.md Index: embedded/md/tcllib/files/modules/valtype/cc_visa.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/cc_visa.md +++ embedded/md/tcllib/files/modules/valtype/cc_visa.md @@ -1,154 +0,0 @@ - -[//000000001]: # (valtype::creditcard::visa \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::creditcard::visa\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::creditcard::visa \- Validation for VISA creditcard number - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::creditcard::visa ?1? - -[__valtype::creditcard::visa__ __validate__ *value*](#1) -[__valtype::creditcard::visa__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a VISA creditcard number\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::creditcard::visa validate .... ;# Does nothing - valtype::creditcard::visa validate .... ;# Throws an error (bad VISA creditcard number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::creditcard::visa__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::creditcard::visa__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __CREDITCARD VISA__\. This is then -followed by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are: - - - INVALID CREDITCARD VISA CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a VISA creditcard number\. - - - INVALID CREDITCARD VISA CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID CREDITCARD VISA LENGTH - - The input value is of the wrong length to be a VISA creditcard number\. - - - INVALID CREDITCARD VISA PREFIX - - The input value does not start with the magic value\(s\) required for it to be - a VISA creditcard number\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[VISA](\.\./\.\./\.\./\.\./index\.md\#visa), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[bank](\.\./\.\./\.\./\.\./index\.md\#bank), [card for -credit](\.\./\.\./\.\./\.\./index\.md\#card\_for\_credit), [credit -card](\.\./\.\./\.\./\.\./index\.md\#credit\_card), -[finance](\.\./\.\./\.\./\.\./index\.md\#finance), [isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/ean13.md Index: embedded/md/tcllib/files/modules/valtype/ean13.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/ean13.md +++ embedded/md/tcllib/files/modules/valtype/ean13.md @@ -1,148 +0,0 @@ - -[//000000001]: # (valtype::gs1::ean13 \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::gs1::ean13\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::gs1::ean13 \- Validation for EAN13 - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::gs1::ean13 ?1? - -[__valtype::gs1::ean13__ __validate__ *value*](#1) -[__valtype::gs1::ean13__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for an EAN13\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::gs1::ean13 validate .... ;# Does nothing - valtype::gs1::ean13 validate .... ;# Throws an error (bad EAN13). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::gs1::ean13__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::gs1::ean13__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __EAN13__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID EAN13 CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an EAN13\. - - - INVALID EAN13 CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID EAN13 LENGTH - - The input value is of the wrong length to be an EAN13\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[EAN](\.\./\.\./\.\./\.\./index\.md\#ean), [EAN13](\.\./\.\./\.\./\.\./index\.md\#ean13), -[European Article Number](\.\./\.\./\.\./\.\./index\.md\#european\_article\_number), -[International Article -Number](\.\./\.\./\.\./\.\./index\.md\#international\_article\_number), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/iban.md Index: embedded/md/tcllib/files/modules/valtype/iban.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/iban.md +++ embedded/md/tcllib/files/modules/valtype/iban.md @@ -1,143 +0,0 @@ - -[//000000001]: # (valtype::iban \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::iban\(n\) 1\.7 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::iban \- Validation for IBAN - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::iban ?1\.7? - -[__valtype::iban__ __validate__ *value*](#1) -[__valtype::iban__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for an IBAN\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::iban validate .... ;# Does nothing - valtype::iban validate .... ;# Throws an error (bad International Bank Account Number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::iban__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::iban__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __IBAN__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID IBAN CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an IBAN\. - - - INVALID IBAN CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[IBAN](\.\./\.\./\.\./\.\./index\.md\#iban), [International Bank Account -Number](\.\./\.\./\.\./\.\./index\.md\#international\_bank\_account\_number), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[bank](\.\./\.\./\.\./\.\./index\.md\#bank), -[finance](\.\./\.\./\.\./\.\./index\.md\#finance), [isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/imei.md Index: embedded/md/tcllib/files/modules/valtype/imei.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/imei.md +++ embedded/md/tcllib/files/modules/valtype/imei.md @@ -1,150 +0,0 @@ - -[//000000001]: # (valtype::imei \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::imei\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::imei \- Validation for IMEI - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::imei ?1? - -[__valtype::imei__ __validate__ *value*](#1) -[__valtype::imei__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for an IMEI\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::imei validate .... ;# Does nothing - valtype::imei validate .... ;# Throws an error (bad International Mobile Equipment Identity (IMEI) number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::imei__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::imei__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __IMEI__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID IMEI CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an IMEI\. - - - INVALID IMEI CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID IMEI LENGTH - - The input value is of the wrong length to be an IMEI\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[IMEI](\.\./\.\./\.\./\.\./index\.md\#imei), [International Mobile Equipment -Identity](\.\./\.\./\.\./\.\./index\.md\#international\_mobile\_equipment\_identity), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[cell\-phone](\.\./\.\./\.\./\.\./index\.md\#cell\_phone), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa), [mobile -phone](\.\./\.\./\.\./\.\./index\.md\#mobile\_phone), -[phone](\.\./\.\./\.\./\.\./index\.md\#phone) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/isbn.md Index: embedded/md/tcllib/files/modules/valtype/isbn.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/isbn.md +++ embedded/md/tcllib/files/modules/valtype/isbn.md @@ -1,159 +0,0 @@ - -[//000000001]: # (valtype::isbn \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::isbn\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::isbn \- Validation for ISBN - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::isbn ?1? - -[__valtype::isbn__ __validate__ *value*](#1) -[__valtype::isbn__ __checkdigit__ *value*](#2) -[__valtype::isbn__ __13of__ *value*](#3) - -# DESCRIPTION - -This package implements a snit validation type for an ISBN\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::isbn validate .... ;# Does nothing - valtype::isbn validate .... ;# Throws an error (bad ISBN). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::isbn__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::isbn__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - - - __valtype::isbn__ __13of__ *value* - - This method expects an old\-style 10\-digit ISBN and returns the canonical - modern 13\-digit ISBN\. This is used by __validate__ to canonicalize the - input, so that all parts of the system after the validation can expect to - work with modern 13\-digit ISBNs\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __ISBN__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID ISBN CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an ISBN\. - - - INVALID ISBN CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID ISBN LENGTH - - The input value is of the wrong length to be an ISBN\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Book Number](\.\./\.\./\.\./\.\./index\.md\#book\_number), -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[EAN](\.\./\.\./\.\./\.\./index\.md\#ean), [EAN13](\.\./\.\./\.\./\.\./index\.md\#ean13), -[European Article Number](\.\./\.\./\.\./\.\./index\.md\#european\_article\_number), -[ISBN](\.\./\.\./\.\./\.\./index\.md\#isbn), [International Article -Number](\.\./\.\./\.\./\.\./index\.md\#international\_article\_number), [International -Standard Book -Number](\.\./\.\./\.\./\.\./index\.md\#international\_standard\_book\_number), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/luhn.md Index: embedded/md/tcllib/files/modules/valtype/luhn.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/luhn.md +++ embedded/md/tcllib/files/modules/valtype/luhn.md @@ -1,142 +0,0 @@ - -[//000000001]: # (valtype::luhn \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::luhn\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::luhn \- Validation for plain number with a LUHN checkdigit - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn ?1? - -[__valtype::luhn__ __validate__ *value*](#1) -[__valtype::luhn__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a plain number with a LUHN -checkdigit\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::luhn validate .... ;# Does nothing - valtype::luhn validate .... ;# Throws an error (bad luhn checkdigit). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::luhn__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::luhn__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __LUHN__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID LUHN CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a plain number with a LUHN - checkdigit\. - - - INVALID LUHN CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa), [luhn](\.\./\.\./\.\./\.\./index\.md\#luhn) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/luhn5.md Index: embedded/md/tcllib/files/modules/valtype/luhn5.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/luhn5.md +++ embedded/md/tcllib/files/modules/valtype/luhn5.md @@ -1,143 +0,0 @@ - -[//000000001]: # (valtype::luhn5 \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::luhn5\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::luhn5 \- Validation for plain number with a LUHN5 checkdigit - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn5 ?1? - -[__valtype::luhn5__ __validate__ *value*](#1) -[__valtype::luhn5__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a plain number with a LUHN5 -checkdigit\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::luhn5 validate .... ;# Does nothing - valtype::luhn5 validate .... ;# Throws an error (bad luhn5 checkdigit). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::luhn5__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::luhn5__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __LUHN5__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID LUHN5 CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a plain number with a LUHN5 - checkdigit\. - - - INVALID LUHN5 CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa), [luhn](\.\./\.\./\.\./\.\./index\.md\#luhn), -[luhn\-5](\.\./\.\./\.\./\.\./index\.md\#luhn\_5) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/usnpi.md Index: embedded/md/tcllib/files/modules/valtype/usnpi.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/usnpi.md +++ embedded/md/tcllib/files/modules/valtype/usnpi.md @@ -1,149 +0,0 @@ - -[//000000001]: # (valtype::usnpi \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::usnpi\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::usnpi \- Validation for USNPI - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::luhn -package require valtype::usnpi ?1? - -[__valtype::usnpi__ __validate__ *value*](#1) -[__valtype::usnpi__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for an USNPI\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::usnpi validate .... ;# Does nothing - valtype::usnpi validate .... ;# Throws an error (bad US National Provider Identifier (US-NPI) number). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::usnpi__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::usnpi__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __USNPI__\. This is then followed by -values detailing the reason for the failure\. The full set of __\-errorCode__s -which can be thrown by this package are: - - - INVALID USNPI CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be an USNPI\. - - - INVALID USNPI CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID USNPI LENGTH - - The input value is of the wrong length to be an USNPI\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[NPI](\.\./\.\./\.\./\.\./index\.md\#npi), [National Provider -Identifier](\.\./\.\./\.\./\.\./index\.md\#national\_provider\_identifier), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[US\-NPI](\.\./\.\./\.\./\.\./index\.md\#us\_npi), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa), -[medicare](\.\./\.\./\.\./\.\./index\.md\#medicare) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/valtype_common.md Index: embedded/md/tcllib/files/modules/valtype/valtype_common.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/valtype_common.md +++ embedded/md/tcllib/files/modules/valtype/valtype_common.md @@ -1,159 +0,0 @@ - -[//000000001]: # (valtype::common \- Validation types) -[//000000002]: # (Generated from file 'valtype\_common\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::common\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::common \- Validation, common code - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require valtype::common ?1? - -[__valtype::common::reject__ *code* *text*](#1) -[__valtype::common::badchar__ *code* ?*text*?](#2) -[__valtype::common::badcheck__ *code* ?*text*?](#3) -[__valtype::common::badlength__ *code* *lengths* ?*text*?](#4) -[__valtype::common::badprefix__ *code* *prefixes* ?*text*?](#5) - -# DESCRIPTION - -This package implements a number of common commands used by the validation types -in this module\. These commands essentially encapsulate the throwing of -validation errors, ensuring that a proper __\-errorcode__ is used\. See -section [Error Codes](#section3)\. - -# API - - - __valtype::common::reject__ *code* *text* - - The core command of this package it throws an __INVALID__ error with the - specified *text*\. The first argument is a list of codes extending the - __INVALID__ with detail information\. - - - __valtype::common::badchar__ *code* ?*text*? - - This command throws an __INVALID CHAR__ error with the specified - *text*\. The first argument is a list of codes providing details\. These are - inserted between the codes __INVALID__ and __CHARACTER__\. - - - __valtype::common::badcheck__ *code* ?*text*? - - This command throws an __INVALID CHECK\-DIGIT__ error with the specified - *text*, if any, extended by the standard text "the check digit is - incorrect"\. The first argument is a list of codes providing details\. These - are inserted between the codes __INVALID__ and __CHECK\_DIGIT__\. - - - __valtype::common::badlength__ *code* *lengths* ?*text*? - - This command throws an __INVALID LENGTH__ error with the specified - *text*, if any, extended by the standard text "incorrect length, expected - \.\.\. character\(s\)"\. The first argument is a list of codes providing details\. - These are inserted between the codes __INVALID__ and __LENGTH__\. The - argument *lengths* is a list of the input lengths which had been expected, - i\.e\. these are the valid lengths\. - - - __valtype::common::badprefix__ *code* *prefixes* ?*text*? - - This command throws an __INVALID PREFIX__ error with the specified - *text*, if any, extended by the standard text "incorrect prefix, expected - \.\.\."\. The first argument is a list of codes providing details\. These are - inserted between the codes __INVALID__ and __PREFIX__\. The argument - *prefixes* is a list of the input prefixes which had been expected, i\.e\. - these are the valid prefixes\. - -# Error Codes - -The errors thrown by the commands of this package all use the __\-errorcode__ -__INVALID__ to distinguish the input validation failures they represent from -package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. This is supplied by the caller\. This is then followed -by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are shown below, with -__<>__ a placeholder for both the caller\-supplied type\-information, the type -description\. - - - INVALID __<>__ CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a __<>__\. - - - INVALID __<>__ CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - - - INVALID __<>__ LENGTH - - The input value is of the wrong length to be a __<>__\. - - - INVALID __<>__ PREFIX - - The input value does not start with the magic value\(s\) required for it to be - a __<>__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/valtype/verhoeff.md Index: embedded/md/tcllib/files/modules/valtype/verhoeff.md ================================================================== --- embedded/md/tcllib/files/modules/valtype/verhoeff.md +++ embedded/md/tcllib/files/modules/valtype/verhoeff.md @@ -1,143 +0,0 @@ - -[//000000001]: # (valtype::verhoeff \- Validation types) -[//000000002]: # (Generated from file 'vtype\.inc' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (valtype::verhoeff\(n\) 1 tcllib "Validation types") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -valtype::verhoeff \- Validation for plain number with a VERHOEFF checkdigit - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Error Codes](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require snit 2 -package require valtype::common -package require valtype::verhoeff ?1? - -[__valtype::verhoeff__ __validate__ *value*](#1) -[__valtype::verhoeff__ __checkdigit__ *value*](#2) - -# DESCRIPTION - -This package implements a snit validation type for a plain number with a -VERHOEFF checkdigit\. - -A validation type is an object that can be used to validate Tcl values of a -particular kind\. For example, __snit::integer__, a validation type defined -by the __[snit](\.\./snit/snit\.md)__ package is used to validate that a -Tcl value is an integer\. - -Every validation type has a __validate__ method which is used to do the -validation\. This method must take a single argument, the value to be validated; -further, it must do nothing if the value is valid, but throw an error if the -value is invalid: - - valtype::verhoeff validate .... ;# Does nothing - valtype::verhoeff validate .... ;# Throws an error (bad verhoeff checkdigit). - -The __validate__ method will always return the validated value on success, -and throw the __\-errorcode__ INVALID on error, possibly with additional -elements which provide more details about the problem\. - -# API - -The API provided by this package satisfies the specification of snit validation -types found in the documentation of *[Snit's Not Incr -Tcl](\.\./snit/snit\.md)*\. - - - __valtype::verhoeff__ __validate__ *value* - - This method validates the *value* and returns it, possibly in a canonical - form, if it passes\. If the value does not pass the validation an error is - thrown\. - - - __valtype::verhoeff__ __checkdigit__ *value* - - This method computes a check digit for the *value*\. Before doing so it is - validated, except for a checkdigit\. If the value does not pass the - validation no check digit is calculated and an error is thrown instead\. - -# Error Codes - -As said in the package description, the errors thrown by the commands of this -package in response to input validation failures use the __\-errorcode__ -INVALID to distinguish themselves from package internal errors\. - -To provide more detailed information about why the validation failed the -__\-errorCode__ goes actually beyond that\. First, it will contain a code -detailing the type itself\. Here this is __VERHOEFF__\. This is then followed -by values detailing the reason for the failure\. The full set of -__\-errorCode__s which can be thrown by this package are: - - - INVALID VERHOEFF CHARACTER - - The input value contained one or more bad characters, i\.e\. characters which - must not occur in the input for it to be a plain number with a VERHOEFF - checkdigit\. - - - INVALID VERHOEFF CHECK\-DIGIT - - The check digit of the input value is wrong\. This usually signals a - data\-entry error, with digits transposed, forgotten, etc\. Of course, th - input may be an outright fake too\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *valtype* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Checking](\.\./\.\./\.\./\.\./index\.md\#checking), -[Testing](\.\./\.\./\.\./\.\./index\.md\#testing), [Type -checking](\.\./\.\./\.\./\.\./index\.md\#type\_checking), -[Validation](\.\./\.\./\.\./\.\./index\.md\#validation), [Value -checking](\.\./\.\./\.\./\.\./index\.md\#value\_checking), -[isA](\.\./\.\./\.\./\.\./index\.md\#isa), -[verhoeff](\.\./\.\./\.\./\.\./index\.md\#verhoeff) - -# CATEGORY - -Validation, Type checking - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/cat.md Index: embedded/md/tcllib/files/modules/virtchannel_base/cat.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/cat.md +++ embedded/md/tcllib/files/modules/virtchannel_base/cat.md @@ -1,98 +0,0 @@ - -[//000000001]: # (tcl::chan::cat \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'cat\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (tcl::chan::cat\(n\) 1\.0\.3 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::cat \- Concatenation channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::core ?1? -package require tcl::chan::cat ?1\.0\.3? - -[__::tcl::chan::cat__ *chan*\.\.\.](#1) - -# DESCRIPTION - -The __tcl::chan::cat__ package provides a command creating concatenation -channels\. These are non\-seekable channels owning a list of subordinate channels -whose contents they return in order, until all are exhausted\. In this manner the -channel is the concatentation of the contents of all the sub\-ordinate channels\. - -Note that the created channels take ownership of the channels they were -constructed with\. Whenever they have exhausted one of their channel it will be -closed\. Similarly, closing the cat channel will close all the sub\-ordinates it -still has\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::core](\.\./virtchannel\_core/core\.md)__ framework\. - -Event handling is delegated to the currently active sub\-channel\. - -# API - - - __::tcl::chan::cat__ *chan*\.\.\. - - This command creates the concatenation channel using all the provided - channels, and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[concatenation channel](\.\./\.\./\.\./\.\./index\.md\#concatenation\_channel), -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/facade.md Index: embedded/md/tcllib/files/modules/virtchannel_base/facade.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/facade.md +++ embedded/md/tcllib/files/modules/virtchannel_base/facade.md @@ -1,126 +0,0 @@ - -[//000000001]: # (tcl::chan::facade \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'facade\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (tcl::chan::facade\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::facade \- Facade channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require logger -package require tcl::chan::core ?1? -package require tcl::chan::facade ?1? - -[__::tcl::chan::facade__ *chan*](#1) - -# DESCRIPTION - -The __tcl::chan::facade__ package provides a command creating facades to -other channels\. These are channels which own a single subordinate channel and -delegate all operations to\. - -The main use for facades is the debugging of actions on a channel\. While most of -the information could be tracked by a virtual channel transformation it does not -have access to the event\-related operation, and furthermore they are only -available in Tcl 8\.6\. - -Therefore this channel, usable with Tcl 8\.5, and having access to everything -going on for a channel\. - -The intercepted actions on channel are logged through package -__[logger](\.\./log/logger\.md)__\. - -Beyond that facades provide the following additional channel configuration -options: - - - __\-self__ - - The TclOO object handling the facade\. - - - __\-fd__ - - The handle of the subordinate, i\.e\. wrapped channel\. - - - __\-used__ - - The last time the wrapped channel was read from or written to by the facade, - as per __clock milliseconds__\. A value of __0__ indicates that the - subordinate channel was not accessed at all, yet\. - - - __\-created__ - - The time the facade was created, as per __clock milliseconds__\. - - - __\-user__ - - A free\-form value identifying the user of the facade and its wrapped - channel\. - -Of these only option __\-user__ is writable\. - -# API - - - __::tcl::chan::facade__ *chan* - - This command creates the facade channel around the provided channel - *chan*, and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[concatenation channel](\.\./\.\./\.\./\.\./index\.md\#concatenation\_channel), -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md Index: embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md +++ embedded/md/tcllib/files/modules/virtchannel_base/halfpipe.md @@ -1,128 +0,0 @@ - -[//000000001]: # (tcl::chan::halfpipe \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'halfpipe\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009, 2019 Andreas Kupries ) -[//000000004]: # (tcl::chan::halfpipe\(n\) 1\.0\.1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::halfpipe \- In\-memory channel, half of a fifo2 - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Options](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::halfpipe ?1\.0\.1? - -[__::tcl::chan::halfpipe__ ?__\-option__ *value*\.\.\.?](#1) -[*objectCmd* __put__ *bytes*](#2) - -# DESCRIPTION - -The __tcl::chan::halfpipe__ package provides a command creating one half of -a __[tcl::chan::fifo2](tcllib\_fifo2\.md)__ pair\. Writing into such a -channel invokes a set of callbacks which then handle the data\. This is similar -to a channel handler, except having a much simpler API\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::halfpipe__ ?__\-option__ *value*\.\.\.? - - This command creates a halfpipe channel and configures it with the callbacks - to run when the channel is closed, data was written to it, or ran empty\. See - the section [Options](#section3) for the list of options and associated - semantics\. The result of the command is a list containing two elements, the - handle of the new channel, and the object command of the channel handler, in - this order\. The latter is supplied to the caller to provide her with access - to the __put__ method for adding data to the channel\. - - Two halfpipes with a bit of glue logic in the callbacks make for one - __[tcl::chan::fifo2](tcllib\_fifo2\.md)__\. - - - *objectCmd* __put__ *bytes* - - This method of the channel handler object puts the data *bytes* into the - channel so that it can be read from it\. - -# Options - - - __\-close\-command__ cmdprefix - - This callback is invoked when the channel is closed\. A single argument is - supplied, the handle of the channel being closed\. The result of the callback - is ignored\. - - - __\-write\-command__ cmdprefix - - This callback is invoked when data is written to the channel\. Two arguments - are supplied, the handle of the channel written to, and the data written\. - The result of the callback is ignored\. - - - __\-empty\-command__ cmdprefix - - This callback is invoked when the channel has run out of data to read\. A - single argument is supplied, the handle of the channel\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[callbacks](\.\./\.\./\.\./\.\./index\.md\#callbacks), -[fifo](\.\./\.\./\.\./\.\./index\.md\#fifo), [in\-memory -channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009, 2019 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md Index: embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md +++ embedded/md/tcllib/files/modules/virtchannel_base/nullzero.md @@ -1,96 +0,0 @@ - -[//000000001]: # (tcl::chan::nullzero \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'nullzero\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::nullzero\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::nullzero \- Null/Zero channel combination - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::nullzero ?1? - -[__::tcl::chan::nullzero__](#1) - -# DESCRIPTION - -The __tcl::chan::nullzero__ package provides a command creating channels, -which are a combination of null and zero devices\. They immediately forget -whatever is written to them, and on reading return an infinite stream of null -characters\. - -Packages related to this are __[tcl::chan::null](tcllib\_null\.md)__ and -__[tcl::chan::zero](tcllib\_zero\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::nullzero__ - - This command creates a new nullzero channel and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[/dev/null](\.\./\.\./\.\./\.\./index\.md\#\_dev\_null), -[/dev/zero](\.\./\.\./\.\./\.\./index\.md\#\_dev\_zero), -[null](\.\./\.\./\.\./\.\./index\.md\#null), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel), -[zero](\.\./\.\./\.\./\.\./index\.md\#zero) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/randseed.md Index: embedded/md/tcllib/files/modules/virtchannel_base/randseed.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/randseed.md +++ embedded/md/tcllib/files/modules/virtchannel_base/randseed.md @@ -1,95 +0,0 @@ - -[//000000001]: # (tcl::randomseed \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'randseed\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::randomseed\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::randomseed \- Utilities for random channels - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::randomseed ?1? - -[__::tcl::randomseed__](#1) -[__::tcl::combine__ *seed1* *seed2*](#2) - -# DESCRIPTION - -The __tcl::randomseed__ package provides a a few utility commands to help -with the seeding of __[tcl::chan::random](tcllib\_random\.md)__ channels\. - -# API - - - __::tcl::randomseed__ - - This command creates returns a list of seed integers suitable as seed - argument for random channels\. The numbers are derived from the process id, - current time, and Tcl random number generator\. - - - __::tcl::combine__ *seed1* *seed2* - - This command takes to seed lists and combines them into a single list by - XORing them elementwise, modulo 256\. If the lists are not of equial length - the shorter of the two is padded with 0s before merging\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[/dev/random](\.\./\.\./\.\./\.\./index\.md\#\_dev\_random), -[merge](\.\./\.\./\.\./\.\./index\.md\#merge), -[random](\.\./\.\./\.\./\.\./index\.md\#random), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), -[seed](\.\./\.\./\.\./\.\./index\.md\#seed), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/std.md Index: embedded/md/tcllib/files/modules/virtchannel_base/std.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/std.md +++ embedded/md/tcllib/files/modules/virtchannel_base/std.md @@ -1,94 +0,0 @@ - -[//000000001]: # (tcl::chan::std \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'std\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2011 Andreas Kupries ) -[//000000004]: # (tcl::chan::std\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::std \- Standard I/O, unification of stdin and stdout - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::core ?1? -package require tcl::chan::std ?1? - -[__::tcl::chan::std__](#1) - -# DESCRIPTION - -The __tcl::chan::std__ package provides a command creating a standard -channel which unifies stdin and stdout into a single read\- and writable channel\. -The result is not seek\-able, like the original standard channels\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::core](\.\./virtchannel\_core/core\.md)__ framework\. - -# API - - - __::tcl::chan::std__ - - This command creates the std channel and returns its handle\. - - The channel is created only once, on the first call, and all future calls - simply return this handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [standard -io](\.\./\.\./\.\./\.\./index\.md\#standard\_io), -[stdin](\.\./\.\./\.\./\.\./index\.md\#stdin), -[stdout](\.\./\.\./\.\./\.\./index\.md\#stdout), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2011 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo.md @@ -1,94 +0,0 @@ - -[//000000001]: # (tcl::chan::fifo \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_fifo\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::fifo\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::fifo \- In\-memory fifo channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::fifo ?1? - -[__::tcl::chan::fifo__](#1) - -# DESCRIPTION - -The __tcl::chan::fifo__ package provides a command creating channels which -live purely in memory\. Access is fifo\-like, i\.e\. things are read out of the -channel in the order they were written to it\. This is equivalent to the fifo -channels provided by the package __Memchan__, except that this is written in -pure Tcl, not C\. On the other hand, __Memchan__ is usable with Tcl 8\.4 and -before, whereas this package requires Tcl 8\.5 or higher, and -__[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::fifo__ - - This command creates a new fifo channel and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[fifo](\.\./\.\./\.\./\.\./index\.md\#fifo), [in\-memory -channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_fifo2.md @@ -1,100 +0,0 @@ - -[//000000001]: # (tcl::chan::fifo2 \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_fifo2\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::fifo2\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::fifo2 \- In\-memory interconnected fifo channels - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::halfpipe ?1? -package require tcl::chan::fifo2 ?1? - -[__::tcl::chan::fifo2__](#1) - -# DESCRIPTION - -The __tcl::chan::fifo2__ package provides a command creating pairs of -channels which live purely in memory and are connected to each other in a fifo -manner\. What is written to one half of the pair can be read from the other half, -in the same order\. One particular application for this is communication between -threads, with one half of the pair moved to the thread to talk to\. This is -equivalent to the fifo2 channels provided by the package __Memchan__, except -that this is written in pure Tcl, not C\. On the other hand, __Memchan__ is -usable with Tcl 8\.4 and before, whereas this package requires Tcl 8\.5 or higher, -and __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::fifo2__ - - This command creates a new connected pair of fifo channels and returns their - handles, as a list containing two elements\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[connected fifos](\.\./\.\./\.\./\.\./index\.md\#connected\_fifos), -[fifo](\.\./\.\./\.\./\.\./index\.md\#fifo), [in\-memory -channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [inter\-thread -communication](\.\./\.\./\.\./\.\./index\.md\#inter\_thread\_communication), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_memchan.md @@ -1,95 +0,0 @@ - -[//000000001]: # (tcl::chan::memchan \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_memchan\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009\-2017 Andreas Kupries ) -[//000000004]: # (tcl::chan::memchan\(n\) 1\.0\.4 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::memchan \- In\-memory channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::memchan ?1\.0\.4? - -[__::tcl::chan::memchan__](#1) - -# DESCRIPTION - -The __tcl::chan::memchan__ package provides a command creating channels -which live purely in memory\. They provide random\-access, i\.e\. are seekable\. This -is equivalent to the memchan channels provided by the package __Memchan__, -except that this is written in pure Tcl, not C\. On the other hand, -__Memchan__ is usable with Tcl 8\.4 and before, whereas this package requires -Tcl 8\.5 or higher, and __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__\. - -Packages related to this are __[tcl::chan::string](tcllib\_string\.md)__ -and __[tcl::chan::variable](tcllib\_variable\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::memchan__ - - This command creates a new memchan channel and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[in\-memory channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009\-2017 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_null.md @@ -1,96 +0,0 @@ - -[//000000001]: # (tcl::chan::null \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_null\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::null\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::null \- Null channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::null ?1? - -[__::tcl::chan::null__](#1) - -# DESCRIPTION - -The __tcl::chan::null__ package provides a command creating null channels, -i\.e\. write\-only channels which immediately forget whatever is written to them\. -This is equivalent to the null channels provided by the package __Memchan__, -except that this is written in pure Tcl, not C\. On the other hand, -__Memchan__ is usable with Tcl 8\.4 and before, whereas this package requires -Tcl 8\.5 or higher, and __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__\. - -Packages related to this are __[tcl::chan::zero](tcllib\_zero\.md)__ and -__[tcl::chan::nullzero](nullzero\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::null__ - - This command creates a new null channel and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[/dev/null](\.\./\.\./\.\./\.\./index\.md\#\_dev\_null), -[null](\.\./\.\./\.\./\.\./index\.md\#null), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_random.md @@ -1,96 +0,0 @@ - -[//000000001]: # (tcl::chan::random \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_random\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::random\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::random \- Random channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::random ?1? - -[__::tcl::chan::random__ *seed*](#1) - -# DESCRIPTION - -The __tcl::chan::random__ package provides a command creating random -channels, i\.e\. read\-only channels which return an infinite stream of -pseudo\-random characters upon reading\. This is similar to the random channels -provided by the package __Memchan__, except that this is written in pure -Tcl, not C, and uses a much simpler generator as well\. On the other hand, -__Memchan__ is usable with Tcl 8\.4 and before, whereas this package requires -Tcl 8\.5 or higher, and TclOO\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::random__ *seed* - - This command creates a new random channel and returns its handle\. The seed - is a list of integer numbers used to initialize the internal feedback shift - register of the generator\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[/dev/random](\.\./\.\./\.\./\.\./index\.md\#\_dev\_random), -[random](\.\./\.\./\.\./\.\./index\.md\#random), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_string.md @@ -1,95 +0,0 @@ - -[//000000001]: # (tcl::chan::string \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_string\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::string\(n\) 1\.0\.3 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::string \- Read\-only in\-memory channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::string ?1\.0\.3? - -[__::tcl::chan::string__ *content*](#1) - -# DESCRIPTION - -The __tcl::chan::string__ package provides a command creating channels which -live purely in memory\. They provide random\-access, i\.e\. are seekable\. In -contrast to the channels created by -__[tcl::chan::memchan](tcllib\_memchan\.md)__ they are read\-only however, -their content is provided at the time of construction and immutable afterward\. - -Packages related to this are __[tcl::chan::memchan](tcllib\_memchan\.md)__ -and __[tcl::chan::variable](tcllib\_variable\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::string__ *content* - - This command creates a new string channel and returns its handle\. The - channel provides random read\-only access to the *content* string\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[in\-memory channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_variable.md @@ -1,97 +0,0 @@ - -[//000000001]: # (tcl::chan::variable \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_variable\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::variable\(n\) 1\.0\.4 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::variable \- In\-memory channel using variable for storage - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::variable ?1\.0\.4? - -[__::tcl::chan::variable__ *varname*](#1) - -# DESCRIPTION - -The __tcl::chan::variable__ package provides a command creating channels -which live purely in memory\. They provide random\-access, i\.e\. are seekable\. In -contrast to the channels created by -__[tcl::chan::memchan](tcllib\_memchan\.md)__ the data is not hidden in -the channel however, but stored in an associated variable, specified at the time -of construction\. - -Packages related to this are __[tcl::chan::memchan](tcllib\_memchan\.md)__ -and __[tcl::chan::string](tcllib\_string\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::variable__ *varname* - - This command creates a new variable channel and returns its handle\. The - content of the channel is stored in the associated namespace variable - *varname*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[in\-memory channel](\.\./\.\./\.\./\.\./index\.md\#in\_memory\_channel), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md Index: embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md +++ embedded/md/tcllib/files/modules/virtchannel_base/tcllib_zero.md @@ -1,96 +0,0 @@ - -[//000000001]: # (tcl::chan::zero \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_zero\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::zero\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::zero \- Zero channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::zero ?1? - -[__::tcl::chan::zero__](#1) - -# DESCRIPTION - -The __tcl::chan::zero__ package provides a command creating zero channels, -i\.e\. read\-only channels which return an infinite stream of null characters upon -reading\. This is equivalent to the zero channels provided by the package -__Memchan__, except that this is written in pure Tcl, not C\. On the other -hand, __Memchan__ is usable with Tcl 8\.4 and before, whereas this package -requires Tcl 8\.5 or higher, and TclOO\. - -Packages related to this are __[tcl::chan::null](tcllib\_null\.md)__ and -__[tcl::chan::nullzero](nullzero\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::zero__ - - This command creates a new zero channel and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[/dev/zero](\.\./\.\./\.\./\.\./index\.md\#\_dev\_zero), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel), -[zero](\.\./\.\./\.\./\.\./index\.md\#zero) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md Index: embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md +++ embedded/md/tcllib/files/modules/virtchannel_base/textwindow.md @@ -1,91 +0,0 @@ - -[//000000001]: # (tcl::chan::textwindow \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'textwindow\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::textwindow\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::textwindow \- Textwindow channel - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::events ?1? -package require tcl::chan::textwindow ?1? - -[__::tcl::chan::textwindow__ *widget*](#1) - -# DESCRIPTION - -The __tcl::chan::textwindow__ package provides a command creating write\-only -channels connected to text widgets\. Anything written to the channel is printed -into the associated widget\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the channel handler is a sub\-class of the -__[tcl::chan::events](\.\./virtchannel\_core/events\.md)__ framework\. - -# API - - - __::tcl::chan::textwindow__ *widget* - - This command creates a new textwindow channel and returns its handle\. Data - written to this channel will appear in the associated *widget*\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[Tk](\.\./\.\./\.\./\.\./index\.md\#tk), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [text -widget](\.\./\.\./\.\./\.\./index\.md\#text\_widget), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_core/core.md Index: embedded/md/tcllib/files/modules/virtchannel_core/core.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_core/core.md +++ embedded/md/tcllib/files/modules/virtchannel_core/core.md @@ -1,124 +0,0 @@ - -[//000000001]: # (tcl::chan::core \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'core\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::core\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::core \- Basic reflected/virtual channel support - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instance API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::core ?1? - -[__::tcl::chan::core__ *objectName*](#1) -[*objectName* __initialize__ *thechannel* *mode*](#2) -[*objectName* __finalize__ *thechannel*](#3) -[*objectName* __destroy__](#4) - -# DESCRIPTION - -The __tcl::chan::core__ package provides a -__[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing common -behaviour needed by virtually every reflected or virtual channel -\(initialization, finalization\)\. - -This class expects to be used as either superclass of a concrete channel class, -or to be mixed into such a class\. - -# Class API - - - __::tcl::chan::core__ *objectName* - - This command creates a new channel core object with an associated global Tcl - command whose name is *objectName*\. This command may be used to invoke - various operations on the object, as described in the section for the - [Instance API](#section3)\. - -# Instance API - -The API of channel core instances provides only two methods, both corresponding -to channel handler commands \(For reference see [TIP -219](http:/tip\.tcl\.tk/219)\)\. They expect to be called from whichever object -instance the channel core was made a part of\. - - - *objectName* __initialize__ *thechannel* *mode* - - This method implements standard behaviour for the __initialize__ method - of channel handlers\. Using introspection it finds the handler methods - supported by the instance and returns a list containing their names, as - expected by the support for reflected channels in the Tcl core\. - - It further remembers the channel handle in an instance variable for access - by sub\-classes\. - - - *objectName* __finalize__ *thechannel* - - This method implements standard behaviour for the __finalize__ method of - channel handlers\. It simply destroys itself\. - - - *objectName* __destroy__ - - Destroying the channel core instance closes the channel it was initialized - for, see the method __initialize__\. When destroyed from within a call of - __finalize__ this does not happen, under the assumption that the channel - is being destroyed by Tcl\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_core/events.md Index: embedded/md/tcllib/files/modules/virtchannel_core/events.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_core/events.md +++ embedded/md/tcllib/files/modules/virtchannel_core/events.md @@ -1,132 +0,0 @@ - -[//000000001]: # (tcl::chan::events \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'events\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::chan::events\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::chan::events \- Event support for reflected/virtual channels - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instance API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::chan::core ?1? -package require tcl::chan::events ?1? - -[__::tcl::chan::events__ *objectName*](#1) -[*objectName* __finalize__ *thechannel*](#2) -[*objectName* __watch__ *thechannel* *eventmask*](#3) -[*objectName* __allow__ *eventname*\.\.\.](#4) -[*objectName* __disallow__ *eventname*\.\.\.](#5) - -# DESCRIPTION - -The __tcl::chan::events__ package provides a -__[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing common -behaviour needed by virtually every reflected or virtual channel supporting -event driven IO\. It is a sub\-class of __[tcl::chan::core](core\.md)__, -inheriting all of its behaviour\. - -This class expects to be used as either superclass of a concrete channel class, -or to be mixed into such a class\. - -# Class API - - - __::tcl::chan::events__ *objectName* - - This command creates a new channel event core object with an associated - global Tcl command whose name is *objectName*\. This command may be used to - invoke various operations on the object, as described in the section for the - [Instance API](#section3)\. - -# Instance API - -The API of channel event core instances provides only four methods, two -corresponding to channel handler commands \(For reference see [TIP -219](http:/tip\.tcl\.tk/219)\), and the other two for use by sub\-classes to -control event generation\. They former expect to be called from whichever object -instance the channel event core was made a part of\. - - - *objectName* __finalize__ *thechannel* - - This method implements standard behaviour for the __finalize__ method of - channel handlers\. It overrides the behaviour inherited from - __[tcl::chan::core](core\.md)__ and additionally disables any and all - event generation before destroying itself\. - - - *objectName* __watch__ *thechannel* *eventmask* - - This method implements standard behaviour for the __watch__ method of - channel handlers\. Called by the IO system whenever the interest in event - changes it updates the instance state to activate and/or suppress the - generation of the events of \(non\-\)interest\. - - - *objectName* __allow__ *eventname*\.\.\. - - - *objectName* __disallow__ *eventname*\.\.\. - - These two methods are exported to sub\-classes, so that their instances can - notify their event core of the events the channel they implement can \(allow\) - or cannot \(disallow\) generate\. Together with the information about the - events requested by Tcl's IO system coming in through the __watch__ - method the event core is able to determine which events it should \(not\) - generate and act accordingly\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[event management](\.\./\.\./\.\./\.\./index\.md\#event\_management), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md Index: embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md +++ embedded/md/tcllib/files/modules/virtchannel_core/transformcore.md @@ -1,124 +0,0 @@ - -[//000000001]: # (tcl::transform::core \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'transformcore\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::core\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::core \- Basic reflected/virtual channel transform support - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instance API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.5 -package require TclOO -package require tcl::transform::core ?1? - -[__::tcl::transform::core__ *objectName*](#1) -[*objectName* __initialize__ *thechannel* *mode*](#2) -[*objectName* __finalize__ *thechannel*](#3) -[*objectName* __destroy__](#4) - -# DESCRIPTION - -The __tcl::transform::core__ package provides a -__[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing common -behaviour needed by virtually every reflected or virtual channel transformation -\(initialization, finalization\)\. - -This class expects to be used as either superclass of a concrete channel class, -or to be mixed into such a class\. - -# Class API - - - __::tcl::transform::core__ *objectName* - - This command creates a new transform core object with an associated global - Tcl command whose name is *objectName*\. This command may be used to invoke - various operations on the object, as described in the section for the - [Instance API](#section3)\. - -# Instance API - -The API of transform core instances provides only two methods, both -corresponding to transform handler commands \(For reference see [TIP -230](http:/tip\.tcl\.tk/230)\)\. They expect to be called from whichever object -instance the transform core was made a part of\. - - - *objectName* __initialize__ *thechannel* *mode* - - This method implements standard behaviour for the __initialize__ method - of transform handlers\. Using introspection it finds the handler methods - supported by the instance and returns a list containing their names, as - expected by the support for reflected transformation in the Tcl core\. - - It further remembers the channel handle in an instance variable for access - by sub\-classes\. - - - *objectName* __finalize__ *thechannel* - - This method implements standard behaviour for the __finalize__ method of - channel handlers\. It simply destroys itself\. - - - *objectName* __destroy__ - - Destroying the transform core instance closes the channel and transform it - was initialized for, see the method __initialize__\. When destroyed from - within a call of __finalize__ this does not happen, under the assumption - that the channel and transform are being destroyed by Tcl\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -219](\.\./\.\./\.\./\.\./index\.md\#tip\_219), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/adler32.md @@ -1,119 +0,0 @@ - -[//000000001]: # (tcl::transform::adler32 \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'adler32\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::adler32\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::adler32 \- Adler32 transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::adler32 ?1? - -[__::tcl::transform::adler32__ *chan* __\-option__ *value*\.\.\.](#1) - -# DESCRIPTION - -The __tcl::transform::adler32__ package provides a command creating a -channel transformation which passes the read and written bytes through unchanged -\(like __[tcl::transform::identity](identity\.md)__\), but additionally -continuously computes the adler32 checksums of the data it has seen for each -direction and stores them in Tcl variables specified at construction time\. - -Related transformations in this module are -__[tcl::transform::counter](vt\_counter\.md)__, -__[tcl::transform::crc32](vt\_crc32\.md)__, -__[tcl::transform::identity](identity\.md)__, and -__[tcl::transform::observe](observe\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::adler32__ *chan* __\-option__ *value*\.\.\. - - This command creates an adler32 checksumming transformation on top of the - channel *chan* and returns its handle\. The accepted options are - - * __\-read\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the adler32 checksum - of the data read from the channel\. - - If not specified, or the empty string, the checksum of the read - direction is not saved\. - - * __\-write\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the adler32 checksum - of the data written to the channel\. - - If not specified, or the empty string, the checksum of the write - direction is not saved\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[adler32](\.\./\.\./\.\./\.\./index\.md\#adler32), [channel -transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/hex.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/hex.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/hex.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/hex.md @@ -1,95 +0,0 @@ - -[//000000001]: # (tcl::transform::hex \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'hex\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::hex\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::hex \- Hexadecimal encoding transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::hex ?1? - -[__::tcl::transform::hex__ *chan*](#1) - -# DESCRIPTION - -The __tcl::transform::hex__ package provides a command creating a channel -transformation which hex encodes data written to it, and decodes the data read -from it\. - -A related transformations in this module is -__[tcl::transform::base64](vt\_base64\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::hex__ *chan* - - This command creates a hex transformation on top of the channel *chan* and - returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[hexadecimal](\.\./\.\./\.\./\.\./index\.md\#hexadecimal), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/identity.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/identity.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/identity.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/identity.md @@ -1,100 +0,0 @@ - -[//000000001]: # (tcl::transform::identity \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'identity\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::identity\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::identity \- Identity transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::identity ?1? - -[__::tcl::transform::identity__ *chan*](#1) - -# DESCRIPTION - -The __tcl::transform::identity__ package provides a command creating an -identity channel transformation, which does nothing but pass the read and -written bytes through it unchanged\. Not really useful in an application, however -as the prototypical observer transformation its code is a useful starting point -for any other observers people may wish to write\. - -The transformations in this module which derived from identity's code are -__[tcl::transform::adler32](adler32\.md)__, -__[tcl::transform::counter](vt\_counter\.md)__, -__[tcl::transform::crc32](vt\_crc32\.md)__, and -__[tcl::transform::observe](observe\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::identity__ *chan* - - This command creates an identity transformation on top of the channel - *chan* and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[identity](\.\./\.\./\.\./\.\./index\.md\#identity), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/limitsize.md @@ -1,97 +0,0 @@ - -[//000000001]: # (tcl::transform::limitsize \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'limitsize\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::limitsize\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::limitsize \- limiting input - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::limitsize ?1? - -[__::tcl::transform::limitsize__ *chan* *max*](#1) - -# DESCRIPTION - -The __tcl::transform::limitsize__ package provides a command creating a -channel transformation which limits the number of characters which can be read -from the channel\. A generator for an artificial EOF\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::limitsize__ *chan* *max* - - This command creates a size limiting transformation on top of the channel - *chan* and returns its handle\. - - *max* is the number of bytes which can be read from the channel before EOF - is signaled by the transformation\. Note that popping the transformation - clears the EOF it generated as well\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[limitsize](\.\./\.\./\.\./\.\./index\.md\#limitsize), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [size -limit](\.\./\.\./\.\./\.\./index\.md\#size\_limit), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/observe.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/observe.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/observe.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/observe.md @@ -1,102 +0,0 @@ - -[//000000001]: # (tcl::transform::observe \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'observe\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::observe\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::observe \- Observer transformation, stream copy - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::observe ?1? - -[__::tcl::transform::observe__ *chan* *logw* *logr*](#1) - -# DESCRIPTION - -The __tcl::transform::observer__ package provides a command creating a -channel transformation which passes the read and written bytes through unchanged -\(like __[tcl::transform::identity](identity\.md)__\), but additionally -copies the data it has seen for each direction into channels specified at -construction time\. - -Related transformations in this module are -__[tcl::transform::adler32](adler32\.md)__, -__[tcl::transform::counter](vt\_counter\.md)__, -__[tcl::transform::crc32](vt\_crc32\.md)__, and -__[tcl::transform::identity](identity\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::observe__ *chan* *logw* *logr* - - This command creates an observer transformation on top of the channel - *chan* and returns its handle\. The channel handles *logr* and *logw* - are there the data is copied to\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[observer](\.\./\.\./\.\./\.\./index\.md\#observer), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [stream -copy](\.\./\.\./\.\./\.\./index\.md\#stream\_copy), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/rot.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/rot.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/rot.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/rot.md @@ -1,107 +0,0 @@ - -[//000000001]: # (tcl::transform::rot \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'rot\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::rot\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::rot \- rot\-encryption - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::rot ?1? - -[__::tcl::transform::rot__ *chan* *key*](#1) - -# DESCRIPTION - -The __tcl::transform::rot__ package provides a command creating a channel -transformation which performs primitive encryption \(on writing\) and decryption -\(on reading\) on the alphabetic characters\. The algorithm is the Caesar\-cipher, a -specific variant of which is rot13\. - -A related transformations in this module is -__[tcl::transform::otp](vt\_otp\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::rot__ *chan* *key* - - This command creates a rot encryption transformation on top of the channel - *chan* and returns its handle\. - - The "*key*" specifies how far characters are rotated in the alphabet, and - is wrapped to the range "0\.\.\.25"\. - - Note that this transformation affects only bytes in the ranges ASCII - 65\.\.\.90, and 97\.\.\.122, i\.e\. the upper\- and lower\-case alphabetic characters, - i\.e\. "A\.\.\.Z" and "a\.\.\.z"\. All other bytes are passed through unchanged\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[caesar cipher](\.\./\.\./\.\./\.\./index\.md\#caesar\_cipher), [channel -transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[cipher](\.\./\.\./\.\./\.\./index\.md\#cipher), -[decryption](\.\./\.\./\.\./\.\./index\.md\#decryption), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), -[rot](\.\./\.\./\.\./\.\./index\.md\#rot), [rot13](\.\./\.\./\.\./\.\./index\.md\#rot13), -[tip 230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/spacer.md @@ -1,97 +0,0 @@ - -[//000000001]: # (tcl::transform::spacer \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'spacer\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::spacer\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::spacer \- Space insertation and removal - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::spacer ?1? - -[__::tcl::transform::spacer__ *chan* *n* ?*space*?](#1) - -# DESCRIPTION - -The __tcl::transform::spacer__ package provides a command creating a channel -transformation which adds spacing to the data written to it, and removes such -spacing from the data read from it\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::spacer__ *chan* *n* ?*space*? - - This command creates a spacer transformation on top of the channel *chan* - and returns its handle\. - - The *space* character sequence will be added every *n* bytes of data - written, and on the read side the same is done in reverse, removing the - spacing\. If *space* is not specified it defaults to a single space - character \(ASCII 32\)\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), -[spacing](\.\./\.\./\.\./\.\./index\.md\#spacing), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/tcllib_zlib.md @@ -1,98 +0,0 @@ - -[//000000001]: # (tcl::transform::zlib \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'tcllib\_zlib\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::zlib\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::zlib \- zlib \(de\)compression - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::zlib ?1? - -[__::tcl::transform::zlib__ *chan* ?*level*?](#1) - -# DESCRIPTION - -The __tcl::transform::zlib__ package provides a command creating a channel -transformation which zlib compresses the written data, and decompresses on -reading\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::zlib__ *chan* ?*level*? - - This command creates a zlib compressor transformation on top of the channel - *chan* and returns its handle\. - - The *level* specifies how much effort is put into the compression, from - __0__ to __9__, and defaults to __4__\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[compression](\.\./\.\./\.\./\.\./index\.md\#compression), -[decompression](\.\./\.\./\.\./\.\./index\.md\#decompression), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), [tip -234](\.\./\.\./\.\./\.\./index\.md\#tip\_234), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel), -[zlib](\.\./\.\./\.\./\.\./index\.md\#zlib) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_base64.md @@ -1,96 +0,0 @@ - -[//000000001]: # (tcl::transform::base64 \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'vt\_base64\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::base64\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::base64 \- Base64 encoding transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::base64 ?1? - -[__::tcl::transform::base64__ *chan*](#1) - -# DESCRIPTION - -The __tcl::transform::base64__ package provides a command creating a channel -transformation which base64 encodes data written to it, and decodes the data -read from it\. - -A related transformations in this module is -__[tcl::transform::hex](hex\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::base64__ *chan* - - This command creates a base64 transformation on top of the channel *chan* - and returns its handle\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[base64](\.\./\.\./\.\./\.\./index\.md\#base64), [channel -transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), [tip -317](\.\./\.\./\.\./\.\./index\.md\#tip\_317), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_counter.md @@ -1,118 +0,0 @@ - -[//000000001]: # (tcl::transform::counter \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'vt\_counter\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::counter\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::counter \- Counter transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::counter ?1? - -[__::tcl::transform::counter__ *chan* __\-option__ *value*\.\.\.](#1) - -# DESCRIPTION - -The __tcl::transform::counterr__ package provides a command creating a -channel transformation which passes the read and written bytes through unchanged -\(like __[tcl::transform::identity](identity\.md)__\), but additionally -counts the bytes it has seen for each direction and stores these counts in Tcl -variables specified at construction time\. - -Related transformations in this module are -__[tcl::transform::adler32](adler32\.md)__, -__[tcl::transform::crc32](vt\_crc32\.md)__, -__[tcl::transform::identity](identity\.md)__, and -__[tcl::transform::observe](observe\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::counter__ *chan* __\-option__ *value*\.\.\. - - This command creates a counter transformation on top of the channel *chan* - and returns its handle\. The accepted options are - - * __\-read\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the byte count of the - data read from the channel\. - - If not specified, or the empty string, the counter of the read direction - is not saved\. - - * __\-write\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the byte count of the - data written to the channel\. - - If not specified, or the empty string, the counter of the write - direction is not saved\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[counter](\.\./\.\./\.\./\.\./index\.md\#counter), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_crc32.md @@ -1,120 +0,0 @@ - -[//000000001]: # (tcl::transform::crc32 \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'vt\_crc32\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::crc32\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::crc32 \- Crc32 transformation - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::crc32 ?1? - -[__::tcl::transform::crc32__ *chan* __\-option__ *value*\.\.\.](#1) - -# DESCRIPTION - -The __tcl::transform::crc32__ package provides a command creating a channel -transformation which passes the read and written bytes through unchanged \(like -__[tcl::transform::identity](identity\.md)__\), but additionally -continuously computes the crc32 checksums of the data it has seen for each -direction and stores them in Tcl variables specified at construction time\. The -checksum in question is zlib's crc32\. - -Related transformations in this module are -__[tcl::transform::adler32](adler32\.md)__, -__[tcl::transform::counter](vt\_counter\.md)__, -__[tcl::transform::identity](identity\.md)__, and -__[tcl::transform::observe](observe\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::crc32__ *chan* __\-option__ *value*\.\.\. - - This command creates a crc32 checksumming transformation on top of the - channel *chan* and returns its handle\. The accepted options are - - * __\-read\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the crc32 checksum of - the data read from the channel\. - - If not specified, or the empty string, the checksum of the read - direction is not saved\. - - * __\-write\-variable__ varname - - The value of the option is the name of a global or namespaced variable, - the location where the transformation has to store the crc32 checksum of - the data written to the channel\. - - If not specified, or the empty string, the checksum of the write - direction is not saved\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[checksum](\.\./\.\./\.\./\.\./index\.md\#checksum), -[crc32](\.\./\.\./\.\./\.\./index\.md\#crc32), [reflected -channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md Index: embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md ================================================================== --- embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md +++ embedded/md/tcllib/files/modules/virtchannel_transform/vt_otp.md @@ -1,103 +0,0 @@ - -[//000000001]: # (tcl::transform::otp \- Reflected/virtual channel support) -[//000000002]: # (Generated from file 'vt\_otp\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Andreas Kupries ) -[//000000004]: # (tcl::transform::otp\(n\) 1 tcllib "Reflected/virtual channel support") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -tcl::transform::otp \- Encryption via one\-time pad - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require tcl::transform::core ?1? -package require tcl::transform::otp ?1? - -[__::tcl::transform::otp__ *chan* *keychanw* *keychanr*](#1) - -# DESCRIPTION - -The __tcl::transform::otp__ package provides a command creating a channel -transformation which uses externally provided one\-time pads to perform -encryption \(on writing\) and decryption \(on reading\)\. - -A related transformations in this module is -__[tcl::transform::rot](rot\.md)__\. - -The internal __[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo)__ class implementing -the transform handler is a sub\-class of the -__[tcl::transform::core](\.\./virtchannel\_core/transformcore\.md)__ -framework\. - -# API - - - __::tcl::transform::otp__ *chan* *keychanw* *keychanr* - - This command creates a one\-time pad based encryption transformation on top - of the channel *chan* and returns its handle\. - - The two channels *keychanw* and *keychanr* contain the one\-time pads for - the write and read directions, respectively\. Their contents are reads and - xored with the bytes written to and read from the channel\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *virtchannel* of the -[Tcllib Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report -any ideas for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[channel transformation](\.\./\.\./\.\./\.\./index\.md\#channel\_transformation), -[cipher](\.\./\.\./\.\./\.\./index\.md\#cipher), -[decryption](\.\./\.\./\.\./\.\./index\.md\#decryption), -[encryption](\.\./\.\./\.\./\.\./index\.md\#encryption), [one time -pad](\.\./\.\./\.\./\.\./index\.md\#one\_time\_pad), [otp](\.\./\.\./\.\./\.\./index\.md\#otp), -[reflected channel](\.\./\.\./\.\./\.\./index\.md\#reflected\_channel), [tip -230](\.\./\.\./\.\./\.\./index\.md\#tip\_230), -[transformation](\.\./\.\./\.\./\.\./index\.md\#transformation), [virtual -channel](\.\./\.\./\.\./\.\./index\.md\#virtual\_channel), -[xor](\.\./\.\./\.\./\.\./index\.md\#xor) - -# CATEGORY - -Channels - -# COPYRIGHT - -Copyright © 2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/websocket/websocket.md Index: embedded/md/tcllib/files/modules/websocket/websocket.md ================================================================== --- embedded/md/tcllib/files/modules/websocket/websocket.md +++ embedded/md/tcllib/files/modules/websocket/websocket.md @@ -1,508 +0,0 @@ - -[//000000001]: # (websocket \- websocket client and server) -[//000000002]: # (Generated from file 'websocket\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (websocket\(n\) 1\.3\.1 tcllib "websocket client and server") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -websocket \- Tcl implementation of the websocket protocol - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Callbacks](#section2) - - - [API](#section3) - - - [Examples](#section4) - - - [TLS Security Considerations](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Category](#category) - -# SYNOPSIS - -package require Tcl 8\.4 -package require http 2\.7 -package require logger -package require sha1 -package require base64 -package require websocket ?1\.3\.1? - -[__::websocket::open__ *url* *handler* ?*options*?](#1) -[__::websocket::send__ *sock* *type* ?*msg*? ?*final*?](#2) -[__::websocket::server__ *sock*](#3) -[__::websocket::live__ *sock* *path* *cb* ?*proto*?](#4) -[__::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*?](#5) -[__::websocket::upgrade__ *sock*](#6) -[__::websocket::takeover__ *sock* *handler* ?*server*?](#7) -[__::websocket::conninfo__ *sock* *what*](#8) -[__::websocket::find__ ?*host*? ?*port*?](#9) -[__::websocket::configure__ *sock* *args*](#10) -[__::websocket::loglevel__ ?*loglvl*?](#11) -[__::websocket::close__ *sock* ?*code*? ?*reason*?](#12) - -# DESCRIPTION - -NOTE: THIS DOCUMENTATION IS WORK IN PROGRESS\.\.\. - -The websocket library is a pure Tcl implementation of the WebSocket -specification covering the needs of both clients and servers\. Websockets provide -a way to upgrade a regular HTTP connection into a long\-lived and continuous -binary or text communication between the client and the server\. The library -offers a high\-level interface to receive and send data as specified in RFC 6455 -\(v\. 13 of the protocol\), relieving callers from all necessary protocol framing -and reassembly\. It implements the ping facility specified by the standard, -together with levers to control it\. Pings are server\-driven and ensure the -liveness of the connection across home \(NAT\) networks\. The library has a number -of introspection facilities to inquire about the current state of the -connection, but also to receive notifications of incoming pings, if necessary\. -Finally, the library contains a number of helper procedures to facilitate the -upgrading handshaking in existing web servers\. - -Central to the library is the procedure __websocket::takeover__ that will -take over a regular socket and treat it as a WebSocket, thus performing all -necessary protocol framing, packetisation and reassembly in servers and clients\. -The procedure also takes a handler, a command that will be called back each time -a \(possibly reassembled\) packet from the remote end is ready for delivery at the -original caller\. While exported by the package, the command -__websocket::takeover__ is seldom called in applications, since the package -provides other commands that are specifically tuned for the needs of clients and -servers\. - -Typically, clients will open a connection to a remote server by providing a -WebSocket URL \(*ws:* or *wss:* schemes\) and the handler described above to -the command __websocket::open__\. The opening procedure is a wrapper around -the latest http::geturl implementations: it arranges to keep the socket created -within the http library opened for reuse, but confiscates it from its \(internal\) -map of known sockets for its own use\. - -Servers will start by registering themselves through the command -__::websocket::server__ and a number of handlers for paths using the command -__::websocket::live__\. Then for each incoming client connection, they should -test the incoming request to detect if it is an upgrade request using -__::websocket::test__ and perform the final handshake to place the socket -connection under the control of the websocket library and its central procedure -using __::websocket::upgrade__\. - -Apart from these main commands, the package provides a number of commands for -introspection and basic operations on the websockets that it has under its -control\. As WebSockets connections are long\-lived, most remaining communication -with the library will be by way of callbacks, i\.e\. commands that are triggered -whenever important events within the library have occur, but mostly whenever -data has been received on a WebSocket\. - -# Callbacks - -A number of commands of the library take a handler handler command as an -argument, a command which will be called back upon reception of data, but also -upon important events within the library or events resulting from control -messages sent by the remote end\. For each callback being performed, the -following arguments will be appended: - - - *sock* - - The identifier of the WebSocket, as returned for example by - __::websocket::open__ - - - *type* - - A textual type describing the event or message content, can be one of the - following - - * __text__ - - Complete text message - - * __binary__ - - Complete binary message - - * __ping__ - - Incoming ping message - - * __connect__ - - Notification of successful connection to server - - * __disconnect__ - - Disconnection from remote end - - * __close__ - - Pending closure of connection - - - *msg* - - Will contain the data of the message, whenever this is relevant, i\.e\. when - the *type* is __text__, __binary__ or __ping__ and whenever - there is data available\. - -# API - - - __::websocket::open__ *url* *handler* ?*options*? - - This command is used in clients to open a WebSocket to a remote - websocket\-enabled HTTP server\. The URL provided as an argument in *url* - should start with ws: or wss:, which are the WebSockets counterpart of http: - and https:\. The *handler* is a command that will be called back on data - reception or whenever important events occur during the life of the - websocket\. __::websocket::open__ will return a socket which serves as - both the identifier of the websocket and of the physical low\-level socket to - the server\. This socket can be used in a number of other commands for - introspection or for controlling the behaviour of the library\. Being - essentially a wrapper around the __::http::geturl__ command, this - command provides mostly the same set of dash\-led options than - __::http::geturl__\. Documented below are the options that differ from - __::http::geturl__ and which are specific to the WebSocket library\. - - * \-headers - - This option is supported, knowing that a number of headers will be - automatically added internally in the library in order to be able to - handshake the upgrading of the socket from a regular HTTP socket to a - WebSocket with the server\. - - * \-validate - - This option is not supported as it has no real point for WebSockets\. - - * \-handler - - This option is used internally by the websocket library and cannot be - used\. - - * \-command - - This option is used internally by the websocket library and cannot be - used\. - - * \-protocol - - This option specifies a list of application protocols to handshake with - the server\. This protocols might help the server triggering application - specific features\. - - * \-timeout - - This option is supported, but will implemented as part of the library to - enable a number of finalising cleanups\. - - - __::websocket::send__ *sock* *type* ?*msg*? ?*final*? - - This command will send a fragment or a control message to the remote end of - the WebSocket identified by *sock*\. The type of the message specified in - *type* can either be an integer according to the specification or - \(preferrably\) one of the following case insensitive strings: "text", - "binary" or "ping"\. The content of the message to send to the remote end is - contained in *msg* and message fragmentation is made possible by the - setting the argument *final* to non\-true, knowing that the type of each - fragment has then to be the same\. The command returns the number of bytes - that were effectively sent, or \-1 on errors\. Serious errors, such as when - *sock* does not identify a known WebSocket or when the connection is not - stable yet will generate errors that must be catched\. - - - __::websocket::server__ *sock* - - This command registers the \(accept\) socket *sock* as the identifier fo an - HTTP server that is capable of doing WebSockets\. Paths onto which this - server will listen for incoming connections should be declared using - __::websocket::live__\. - - - __::websocket::live__ *sock* *path* *cb* ?*proto*? - - This procedure registers callbacks that will be performed on a WebSocket - compliant server registered with __::websocket::server__ whenever a - client connects to a matching path and protocol\. *sock* is the listening - socket of the websocket compliant server declared using - __::websocket::server__\. *path* is a glob\-style path to match in - client request, whenever this will occur\. *cb* is the command to callback - \(see Callbacks\)\. *proto* is a glob\-style protocol name matcher\. - - - __::websocket::test__ *srvSock* *cliSock* *path* ?*hdrs*? ?*qry*? - - This procedure will test if the connection from an incoming client on socket - *cliSock* and on the path *path* is the opening of a WebSocket stream - within a known server *srvSock*\. The incoming request is not upgraded at - once, instead a \(temporary\) context for the incoming connection is created\. - This allows server code to perform a number of actions, if necessary, before - the WebSocket stream connection goes live\. The text is made by analysing the - content of the headers *hdrs* which should contain a dictionary list of - the HTTP headers of the incoming client connection\. The command will return - __1__ if this is an incoming WebSocket upgrade request and __0__ - otherwise\. - - - __::websocket::upgrade__ *sock* - - Upgrade the socket *sock* that had been deemed by - __::websocket::test__ to be a WebSocket connection request to a true - WebSocket as recognised by this library\. As a result, the necessary - connection handshake will be sent to the client, and the command will - arrange for relevant callbacks to be made during the life of the WebSocket, - notably using the specifications described by __::websocket::live__\. - - - __::websocket::takeover__ *sock* *handler* ?*server*? - - Take over the existing opened socket *sock* to implement sending and - receiving WebSocket framing on top of the socket\. The procedure arranges for - *handler* to be called back whenever messages, control messages or other - important internal events are received or occured\. *server* defaults to - __0__ and can be set to __1__ \(or a boolean that evaluates to true\) - to specify that this is a WebSocket within a server\. Apart from - specificities in the protocol, servers should ping their clients at regular - intervals in order to keep the connection opened at all time\. When - *server* is set to true, the library will arrange to send these pings - automatically\. - - - __::websocket::conninfo__ *sock* *what* - - Provides callers with some introspection facilities in order to get some - semi\-internal information about an existing websocket connection\. Depending - on the value of the *what* argument, the procedure returns the following - piece of information: - - * __peername__ - - Name \(preferred\) or IP of remote end\. - - * __sockname__ - - or __name__ Name or IP of local end\. - - * __closed__ - - __1__ if the connection is closed, __0__ otherwise - - * __client__ - - __1__ if the connection is a client websocket, __0__ otherwise - - * __server__ - - __1__ if the connection is a server websocket, __0__ otherwise - - * __type__ - - __server__ if the connection is a server websocket, __client__ - otherwise\. - - * __handler__ - - The handler command associated to the websocket - - * __state__ - - The state of the websocket, which can be one of: - - + __CONNECTING__ - - Connection to remote end is in progress\. - - + __CONNECTED__ - - Connection is connected to remote end\. - - + __CLOSED__ - - Connection is closed\. - - - __::websocket::find__ ?*host*? ?*port*? - - Look among existing websocket connections for the ones that match the - hostname and port number filters passed as parameters\. This lookup takes the - remote end into account and the *host* argument is matched both against - the hostname \(whenever available\) and the IP address of the remote end\. Both - the *host* and *port* arguments are glob\-style string matching filters - and default to __\*__, i\.e\. will match any host and/or port number\. - - - __::websocket::configure__ *sock* *args* - - This command takes a number of dash\-led options \(and their values\) to - configure the behaviour of an existing websocket connection\. The recognised - options are the following \(they can be shortened to the lowest common - denominator\): - - * __\-keepalive__ - - is the number of seconds between each keepalive pings being sent along - the connection\. A zero or negative number will effectively turn off the - feature\. In servers, __\-keepalive__ defaults to 30 seconds, and in - clients, no pings are initiated\. - - * __\-ping__ - - is the text that is used during the automated pings\. This text defaults - to the empty string, leading to an empty ping\. - - - __::websocket::loglevel__ ?*loglvl*? - - Set or query the log level of the library, which defaults to error\. Logging - is built on top of the logger module, and the library makes use of the - following levels: __debug__, __info__, __notice__, __warn__ - and __error__\. When called with no argument, this procedure will simply - return the current log level\. Otherwise *loglvl* should contain the - desired log level\. - - - __::websocket::close__ *sock* ?*code*? ?*reason*? - - Gracefully close a websocket that was directly or indirectly passed to - __::websocket::takeover__\. The procedure will optionally send the - *code* and describing *reason* as part of the closure handshake\. Good - defaults are provided, so that reasons for a number of known codes will be - sent back\. Only the first 125 characters of a reason string will be kept and - sent as part of the handshake\. The known codes are: - - * __1000__ - - Normal closure \(the default *code* when none provided\)\. - - * __1001__ - - Endpoint going away - - * __1002__ - - Protocol Error - - * __1003__ - - Received incompatible data type - - * __1006__ - - Abnormal closure - - * __1007__ - - Received data not consistent with type - - * __1008__ - - Policy violation - - * __1009__ - - Received message too big - - * __1010__ - - Missing extension - - * __1011__ - - Unexpected condition - - * __1015__ - - TLS handshake error - -# Examples - -The following example opens a websocket connection to the echo service, waits -400ms to ensure that the connection is really established and sends a single -textual message which should be echoed back by the echo service\. A real example -would probably use the __connect__ callback to know when connection to the -remote server has been establish and would only send data at that time\. - - package require websocket - ::websocket::loglevel debug - - proc handler { sock type msg } { - switch -glob -nocase -- $type { - co* { - puts "Connected on $sock" - } - te* { - puts "RECEIVED: $msg" - } - cl* - - dis* { - } - } - - } - - proc test { sock } { - puts "[::websocket::conninfo $sock type] from [::websocket::conninfo $sock sockname] to [::websocket::conninfo $sock peername]" - - ::websocket::send $sock text "Testing, testing..." - } - - set sock [::websocket::open ws://echo.websocket.org/ handler] - after 400 test $sock - vwait forever - -# TLS Security Considerations - -This package uses the __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ package to -handle the security for __https__ urls and other socket connections\. - -Policy decisions like the set of protocols to support and what ciphers to use -are not the responsibility of __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__, nor -of this package itself however\. Such decisions are the responsibility of -whichever application is using the package, and are likely influenced by the set -of servers the application will talk to as well\. - -For example, in light of the recent [POODLE -attack](http://googleonlinesecurity\.blogspot\.co\.uk/2014/10/this\-poodle\-bites\-exploiting\-ssl\-30\.html) -discovered by Google many servers will disable support for the SSLv3 protocol\. -To handle this change the applications using -__[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ must be patched, and not this -package, nor __[TLS](\.\./\.\./\.\./\.\./index\.md\#tls)__ itself\. Such a patch -may be as simple as generally activating __tls1__ support, as shown in the -example below\. - - package require tls - tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol - - ... your own application code ... - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *websocket* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[http](\.\./\.\./\.\./\.\./index\.md\#http) - -# KEYWORDS - -[http](\.\./\.\./\.\./\.\./index\.md\#http), -[internet](\.\./\.\./\.\./\.\./index\.md\#internet), -[net](\.\./\.\./\.\./\.\./index\.md\#net), [rfc -6455](\.\./\.\./\.\./\.\./index\.md\#rfc\_6455) - -# CATEGORY - -Networking DELETED embedded/md/tcllib/files/modules/wip/wip.md Index: embedded/md/tcllib/files/modules/wip/wip.md ================================================================== --- embedded/md/tcllib/files/modules/wip/wip.md +++ embedded/md/tcllib/files/modules/wip/wip.md @@ -1,398 +0,0 @@ - -[//000000001]: # (wip \- Word Interpreter) -[//000000002]: # (Generated from file 'wip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2007\-2010 Andreas Kupries ) -[//000000004]: # (wip\(n\) 2\.2 tcllib "Word Interpreter") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -wip \- Word Interpreter - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [GENERAL BEHAVIOUR](#section2) - - - [CLASS API](#section3) - - - [OBJECT API](#section4) - - - [EXAMPLES](#section5) - - - [Bugs, Ideas, Feedback](#section6) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require wip ?2\.2? -package require snit ?1\.3? -package require struct::set - -[__::wip__ *wipName* *engine* *arg*\.\.\.](#1) -[__def__ *name*](#2) -[__def__ *name* *method\_prefix*](#3) -[__wipName__ *option* ?*arg arg \.\.\.*?](#4) -[__wip::dsl__ ?*suffix*?](#5) -[*wipName* __def__ *name* ?*method\_prefix*?](#6) -[*wipName* __defl__ *names*](#7) -[*wipName* __defd__ *dict*](#8) -[*wipName* __deflva__ *name*\.\.\.](#9) -[*wipName* __defdva__ \(*name* *method\_prefix*\)\.\.\.](#10) -[*wipName* __undefl__ *names*](#11) -[*wipName* __undefva__ *name*\.\.\.](#12) -[*wipName* __unknown__ *cmdprefix*](#13) -[*wipName* __runl__ *wordlist*](#14) -[*wipName* __run__ *word*\.\.\.](#15) -[*wipName* __run\_next__](#16) -[*wipName* __run\_next\_while__ *acceptable*](#17) -[*wipName* __run\_next\_until__ *rejected*](#18) -[*wipName* __run\_next\_if__ *acceptable*](#19) -[*wipName* __run\_next\_ifnot__ *rejected*](#20) -[*wipName* __next__](#21) -[*wipName* __peek__](#22) -[*wipName* __peekall__](#23) -[*wipName* __insertl__ *at* *wordlist*](#24) -[*wipName* __replacel__ *wordlist*](#25) -[*wipName* __pushl__ *wordlist*](#26) -[*wipName* __addl__ *wordlist*](#27) -[*wipName* __insert__ *at* *word*\.\.\.](#28) -[*wipName* __replace__ *word*\.\.\.](#29) -[*wipName* __push__ *word*\.\.\.](#30) -[*wipName* __add__ *word*\.\.\.](#31) - -# DESCRIPTION - -This package provides a micro interpreter for lists of words\. Domain specific -languages based on this will have a bit of a Forth feel, with the input stream -segmented into words and any other structuring left to whatever the language -desired\. Note that we have here in essence only the core dispatch loop, and no -actual commands whatsoever, making this definitely only a Forth feel and not an -actual Forth\. - -The idea is derived from Colin McCormack's -__[treeql](\.\./treeql/treeql\.md)__ processor, modified to require less -boiler plate within the command implementations, at the expense of, likely, -execution speed\. In addition the interface between processor core and commands -is more complex too\. - -# GENERAL BEHAVIOUR - -Word interpreters have a mappping from the names of the language commands they -shall recognize to the methods in the engine to invoke for them, and possibly -fixed arguments for these methods\. This mapping is largely static, however it is -possible to change it during the execution of a word list \(= program\)\. - -At the time a language command is defined the word interpreter will use -__[snit](\.\./snit/snit\.md)__'s introspection capabilities to determine -the number of arguments expected by the method of the egnine, and together with -the number of fixed arguments supplied in the method prefix of the mapping it -then knows how many arguments the language command is expecting\. This is the -command's *arity*\. Variable\-argument methods \(i\.e\. with the last argument -named *args*\) are *not* allowed and will cause the word interpreter to throw -an error at definition time\. - -Note that while I said __[snit](\.\./snit/snit\.md)__'s abilities the -engine object can be written in any way, as long as it understands the method -__info args__, which takes a method name and returns the list of arguments -for that method\. - -When executing a list of words \(aka program\) the first word is always taken as -the name of a language command, and the next words as its arguments, per the -*arity* of the command\. Command and argument words are removed from the list -and then associated method of the engine is executed with the argument words\. -The process then repeats using the then\-first word of the list\. - -Note that the methods implementing the language commands may have full access to -the list of words and are allowed to manipulate as they see fit\. - - 1. This means, for example, that while we cannot specify variable\-argument - methods directly they can consume words after their fixed arguments before - returning to the execution loop\. This may be under the control of their - fixed arguments\. - - 1. Another possibility is the use of method __run\_next__ and its variants - to execute commands coming after the current command, changing the order of - execution\. - - 1. Execution can be further changed by use of the program accessor methods - which allow a command implementation to modify the remaining list of words - \(insert, replace, prepend, append words\) without executing them - immediately\. - - 1. At last the basic __run__ methods save and restore an existing list of - words when used, enabling recursive use from within command - implementations\. - -# CLASS API - -The main command of the package is: - - - __::wip__ *wipName* *engine* *arg*\.\.\. - - The command creates a new word interpreter object with an associated global - Tcl command whose name is *wipName*\. If however the string __%AUTO%__ - was used as object name the package will generate its own unique name for - the object\. - - The *engine* is the object the word interpreter will dispatch all - recognized commands to, and the *arg*uments are a word list which defines - an initial mapping from language words to engine methods\. - - The recognized language of this word list is - - * __def__ *name* - - Defines *name* as command of the language, to be mapped to a method of - the *engine* having the same name\. - - * __def__ *name* *method\_prefix* - - Defines *name* as command of the language, to be mapped to the method - of the *engine* named in the *method\_prefix*\. - - The returned command may be used to invoke various operations on the object\. - It has the following general form: - - * __wipName__ *option* ?*arg arg \.\.\.*? - - *Option* and the *arg*s determine the exact behavior of the command\. - -The package additionally exports the command: - - - __wip::dsl__ ?*suffix*? - - This command is for use within snit types which wish to use one or more wip - interpreters as a component\. Use within the type definition installs most of - the boilerplate needed to setup and use a word interpreter\. - - It installs a component named *wip*, and a method __wip\_setup__ for - initializing it\. This method has to be called from within the constructor of - the type using the word interpreter\. If further installs a series of - procedures which make the object API of the word interpreter directly - available to the type's methods, without having to specify the component\. - - *Note* that this does and cannot install the language to interpret, i\.e\. - the mapping from words to engine methods\. - - It is possible to instantiate multiple word interpreter components within a - type by using different suffices as arguments to the command\. In that case - the name of the component changes to 'wip\___$suffix__', the setup - command becomes 'wip\___$suffix__\_setup' and all the procedures also get - the suffix '\___$suffix__'\. - -# OBJECT API - -The following commands are possible for word interpreter objects: - - - *wipName* __def__ *name* ?*method\_prefix*? - - Defines a language command *name* and maps it to the method named in the - engine's *method\_prefix*\. If the *method\_prefix* name is not specified - it is simply the name of the language command\. - - - *wipName* __defl__ *names* - - Defines a series of language commands, specified through the list of - *names*, all of which are mapped to engine methods of the same name\. - - - *wipName* __defd__ *dict* - - Defines a series of language commands, specified through the dictionary - *dict* of names and method prefixes\. - - - *wipName* __deflva__ *name*\.\.\. - - As method __defl__, however the list of names is specified through - multiple arguments\. - - - *wipName* __defdva__ \(*name* *method\_prefix*\)\.\.\. - - As method __defd__, however the dictionary of names and method prefixes - is specified through multiple arguments\. - - - *wipName* __undefl__ *names* - - Removes the named series of language commands from the mapping\. - - - *wipName* __undefva__ *name*\.\.\. - - As method __undefl__, however the list of names is specified through - multiple arguments\. - - - *wipName* __unknown__ *cmdprefix* - - Sets the handler for unknown words to *cmdprefix*\. This command prefix - takes one argument, the current word, and either throws some error, or - returns the result of executing the word, as defined by the handler\. The - default handler simply throws an error\. - - - *wipName* __runl__ *wordlist* - - Treats the list of words in *wordlist* as a program and executes the - contained command one by one\. The result of the command executed last is - returned as the result of this command\. - - The *wordlist* is stored in the object for access by the other - *run*\-methods, and the general program accessor methods \(see below\)\. A - previously stored wordlist is saved during the execution of this method and - restored before it returns\. This enables the recursive execution of word - lists within word lists\. - - - *wipName* __run__ *word*\.\.\. - - As method __runl__, however the list of words to execute is specified - through multiple arguments\. - - - *wipName* __run\_next__ - - Low\-level method\. Determines the next word in the list of words, and its - arguments, and then executes it\. The result of the executed word is the - result of this method\. - - Exposed for use within command implementations\. The methods __run__ and - __runl__ use it to execute words until their word list is exhausted\. - - - *wipName* __run\_next\_while__ *acceptable* - - Low\-level method\. Invokes the method __run\_next__ as long as the next - word is in the set of *acceptable* words, and the program is not empty\. - The result of the command executed last is returned as the result of this - command\. - - Exposed for use within command implementations to change the order of - execution\. - - - *wipName* __run\_next\_until__ *rejected* - - Low\-level method\. Invokes the method __run\_next__ until the next word is - in the set of *rejected* words, and the program is not empty\. The result - of the command executed last is returned as the result of this command\. - - Exposed for use within command implementations to change the order of - execution\. - - - *wipName* __run\_next\_if__ *acceptable* - - Low\-level method\. Invokes the method __run\_next__ if the next word is in - the set of *acceptable* words, and the program is not empty\. The result of - the command executed last is returned as the result of this command\. - - Exposed for use within command implementations to change the order of - execution\. - - - *wipName* __run\_next\_ifnot__ *rejected* - - Low\-level method\. Invokes the method __run\_next__ if the next word is - not in the set of *rejected* words, and the program is not empty\. The - result of the command executed last is returned as the result of this - command\. - - Exposed for use within command implementations to change the order of - execution\. - - - *wipName* __next__ - - Returns the next word in the programm\. The word is also removed\. - - - *wipName* __peek__ - - Returns the next word in the programm without removing it - - - *wipName* __peekall__ - - Returns the remaining programm in toto\. - - - *wipName* __insertl__ *at* *wordlist* - - Basic programm accessor method\. Inserts the specified *wordlist* into the - program, just before the word at position *at*\. Positions are counted from - __zero__\. - - - *wipName* __replacel__ *wordlist* - - Basic programm accessor method\. Replaces the whole stored program with the - specified *wordlist*\. - - - *wipName* __pushl__ *wordlist* - - Program accessor method\. The specified *wordlist* is added to the front of - the remaining program\. Equivalent to - - $wip insertl 0 $wordlist - - - *wipName* __addl__ *wordlist* - - Program accessor method\. The specified *wordlist* is appended at the end - of the remaining program\. Equivalent to - - $wip insertl end $wordlist - - - *wipName* __insert__ *at* *word*\.\.\. - - Like method __insertl__, except the words are specified through multiple - arguments\. - - - *wipName* __replace__ *word*\.\.\. - - Like method __setl__, except the words are specified through multiple - arguments\. - - - *wipName* __push__ *word*\.\.\. - - Like method __pushl__, except the words are specified through multiple - arguments\. - - - *wipName* __add__ *word*\.\.\. - - Like method __addl__, except the words are specified through multiple - arguments\. - -# EXAMPLES - -No examples yet\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *wip* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[interpreter](\.\./\.\./\.\./\.\./index\.md\#interpreter), -[list](\.\./\.\./\.\./\.\./index\.md\#list), [word](\.\./\.\./\.\./\.\./index\.md\#word) - -# CATEGORY - -Programming tools - -# COPYRIGHT - -Copyright © 2007\-2010 Andreas Kupries DELETED embedded/md/tcllib/files/modules/yaml/huddle.md Index: embedded/md/tcllib/files/modules/yaml/huddle.md ================================================================== --- embedded/md/tcllib/files/modules/yaml/huddle.md +++ embedded/md/tcllib/files/modules/yaml/huddle.md @@ -1,642 +0,0 @@ - -[//000000001]: # (huddle \- HUDDLE) -[//000000002]: # (Generated from file 'huddle\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008\-2011 KATO Kanryu ) -[//000000004]: # (Copyright © 2015 Miguel Martínez López ) -[//000000005]: # (huddle\(n\) 0\.3 tcllib "HUDDLE") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -huddle \- Create and manipulate huddle object - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [TYPE CALLBACK](#section3) - - - [How to add type](#section4) - - - [WORKING SAMPLE](#section5) - - - [LIMITATIONS](#section6) - - - [Bugs, Ideas, Feedback](#section7) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require huddle ?0\.3? - -[__huddle create__ *key* *value* ?*key value \.\.\.*?](#1) -[__huddle list__ ?*value value \.\.\.*?](#2) -[__huddle number__ *number*](#3) -[__huddle string__ *string*](#4) -[__huddle boolean__ *expression to evaluate as true or false*](#5) -[__huddle true__](#6) -[__huddle false__](#7) -[__huddle null__](#8) -[__huddle get__ *object* *key* ?*key \.\.\.*?](#9) -[__huddle gets__ *object* *key* ?*key \.\.\.*?](#10) -[__huddle set__ *objectVar* *key* ?*key \.\.\.*? *value*](#11) -[__huddle remove__ *object* *key* ?*key \.\.\.*?](#12) -[__huddle combine__ *object1* *object2* ?*object3 \.\.\.*?](#13) -[__huddle equal__ *object1* *object2*](#14) -[__huddle append__ *objectVar* *key* *value* ?*key value \.\.\.*?](#15) -[__huddle append__ *objectVar* *value* ?*value \.\.\.*?](#16) -[__huddle keys__ *object*](#17) -[__huddle llength__ *object*](#18) -[__huddle type__ *object* ?*key key\.\.\.*?](#19) -[__huddle strip__ *object*](#20) -[__huddle jsondump__ *object* ?*offset*? ?*newline*? ?*begin\_offset*?](#21) -[__huddle compile__ *spec* *data*](#22) -[__huddle isHuddle__ *object*](#23) -[__huddle checkHuddle__ *object*](#24) -[__huddle to\_node__ *object* ?*tag*?](#25) -[__huddle wrap__ *tag* *src*](#26) -[__huddle call__ *tag* *command* *args*](#27) -[__huddle addType__ *callback*](#28) -[__[callback](\.\./\.\./\.\./\.\./index\.md\#callback)__ *command* ?*args*?](#29) -[__setting__](#30) -[__get\_sub__ *src* *key*](#31) -[__strip__ *src*](#32) -[__[set](\.\./\.\./\.\./\.\./index\.md\#set)__ *src* *key* *value*](#33) -[__[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *src* *key* *value*](#34) - -# DESCRIPTION - -Huddle provides a generic Tcl\-based serialization/intermediary format\. -Currently, each node is wrapped in a tag with simple type information\. - -When converting huddle\-notation to other serialization formats like JSON or YAML -this type information is used to select the proper notation\. And when going from -JSON/YAML/\.\.\. to huddle their notation can be used to select the proper huddle -type\. - -In that manner huddle can serve as a common intermediary format\. - - huddle-format: > - {HUDDLE {huddle-node}} - huddle-node: > - {tag content} - each content of tag means: - s: (content is a) string - L: list, each sub node is a huddle-node - D: dict, each sub node is a huddle-node - confirmed: - - JSON - - YAML(generally, but cannot discribe YAML-tags) - limitation: - - cannot discribe aliases from a node to other node. - -The __huddle__ package returns data as a Tcl -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__\. Either the -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ package or Tcl 8\.5 is required for -use\. - -# COMMANDS - - - __huddle create__ *key* *value* ?*key value \.\.\.*? - - Create a huddle object as a dict\. It can contain other huddle objects\. - - - __huddle list__ ?*value value \.\.\.*? - - Create a huddle object as a list\. It can contain other huddle objects\. - - - __huddle number__ *number* - - Create a huddle object as a number\. - - - __huddle string__ *string* - - Create a huddle object as a string\. - - - __huddle boolean__ *expression to evaluate as true or false* - - Create a huddle object as a boolean evaluating an expression as true or - false\- - - - __huddle true__ - - Create a huddle object as a boolean true\. - - - __huddle false__ - - Create a huddle object as a boolean false\. - - - __huddle null__ - - Create a huddle object as a null\. - - - __huddle get__ *object* *key* ?*key \.\.\.*? - - Almost the same as __dict get__\. Get a sub\-object from the huddle - object\. *key* can be used to huddle\-list's index\. - - - __huddle gets__ *object* *key* ?*key \.\.\.*? - - Get a sub\-object from the huddle object, stripped\. - - - __huddle set__ *objectVar* *key* ?*key \.\.\.*? *value* - - Almost the same as __dict set__\. Set a sub\-object from the huddle - object\. *key* can be used to huddle\-list's index\. - - - __huddle remove__ *object* *key* ?*key \.\.\.*? - - Almost the same as __dict remove__\. Remove a sub\-object from the huddle - object\. *key* can be used to huddle\-list's index\. - - - __huddle combine__ *object1* *object2* ?*object3 \.\.\.*? - - Merging huddle objects given\. - - % set aa [huddle create a b c d] - HUDDLE {D {a {s b} c {s d}}} - % set bb [huddle create a k l m] - HUDDLE {D {a {s k} l {s m}}} - % huddle combine $aa $bb - HUDDLE {D {a {s k} c {s d} l {s m}}} - - - __huddle equal__ *object1* *object2* - - Comparing two huddle objects recursively\. When to equal, returns 1, - otherwise 0\. - - % set aa [huddle create a b c d] - HUDDLE {D {a {s b} c {s d}}} - % set bb [huddle create c d a b] - HUDDLE {D {c {s d} a {s b}}} - % huddle equal $aa $bb - 1 - - - __huddle append__ *objectVar* *key* *value* ?*key value \.\.\.*? - - - __huddle append__ *objectVar* *value* ?*value \.\.\.*? - - Appending child elements\. When for dicts, giving key/value\. When for lists, - giving values\. - - % set aa [huddle create a b c d] - HUDDLE {D {a {s b} c {s d}}} - % huddle append aa a k l m - HUDDLE {D {a {s k} c {s d} l {s m}}} - % set bb [huddle list i j k l] - HUDDLE {L {{s i} {s j} {s k} {s l}}} - % huddle append bb g h i - HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}} - - - __huddle keys__ *object* - - The same as __dict keys__\. - - - __huddle llength__ *object* - - The same as __llength__\. - - - __huddle type__ *object* ?*key key\.\.\.*? - - Return the element type of specified by keys\. if ?key? is not given, returns - the type of root node\. - - * ____string____ - - the node is a tcl's string\. - - * ____dict____ - - the node is a dict\. - - * ____list____ - - the node is a list\. - - * ____number____ - - the node is a number\. - - * ____boolean____ - - the node is a boolean\. - - * ____null____ - - the node is a null\. - - % huddle type {HUDDLE {s str}} - string - % huddle type {HUDDLE {L {{s a} {s b} {s c}}}} - list - % huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc - string - - - __huddle strip__ *object* - - Stripped all tags\. Converted to normal Tcl's list/dict\. - - - __huddle jsondump__ *object* ?*offset*? ?*newline*? ?*begin\_offset*? - - dump a json\-stream from the huddle\-object\. - - * ____offset__ ""__ - - begin offset as spaces " "\. - - # normal output has some indents. some strings are escaped. - % huddle jsondump {HUDDLE {L {{L {{s i} {s baa} {s \\k} {L {{s 1.0} {s true} {s /g} {s h}}} {L {{s g}}}}} {s t}}}} - [ - [ - "i", - "baa", - "\\k", - [ - 1.0, - true, - "\/g", - "h" - ], - ["g"] - ], - "t" - ] - # stripped output - % huddle jsondump {HUDDLE {D {dd {D {bb {D {a {s baa} c {s {d - a}}}} cc {D {g {s h}}}}} ee {D {i {s j} k {s 1} j {s { m\a}}}}}}} "" "" - {"dd": {"bb": {"a": "baa","c": "d\na"},"cc": {"g": "h"}},"ee": {"i": "j","k": 1,"j": " m\\a"}} - - - __huddle compile__ *spec* *data* - - construct a huddle object from plain old tcl values\. *spec* is defined as - follows: - - * __string__ - - data is simply a string - - * __list__ - - data is a tcl list of strings - - * __dict__ - - data is a tcl dict of strings - - * list list - - data is a tcl list of lists - - * list dict - - data is a tcl list of dicts - - * dict xx list - - data is a tcl dict where the value of key xx is a tcl list - - * dict \* list - - data is a tcl dict of lists *data* is plain old tcl values - - % huddle compile {dict * list} {a {1 2 3} b {4 5}} - HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}} - % huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}} - HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}} - - - __huddle isHuddle__ *object* - - if *object* is a huddle, returns 1\. the other, returns 0\. - - - __huddle checkHuddle__ *object* - - if *object* is not a huddle, rises an error\. - - - __huddle to\_node__ *object* ?*tag*? - - for type\-callbacks\. - - if *object* is a huddle, returns root\-node\. the other, returns __\[list s - $object\]__\. - - % huddle to_node str - s str - % huddle to_node str !!str - !!str str - % huddle to_node {HUDDLE {s str}} - s str - % huddle to_node {HUDDLE {l {a b c}}} - l {a b c} - - - __huddle wrap__ *tag* *src* - - for type\-callbacks\. - - Create a huddle object from *src* with specified *tag*\. - - % huddle wrap "" str - HUDDLE str - % huddle wrap s str - HUDDLE {s str} - - - __huddle call__ *tag* *command* *args* - - for type\-callbacks\. - - devolving *command* to default *tag*\-callback - - - __huddle addType__ *callback* - - add a user\-specified\-type/tag to the huddle library\. To see "Additional - Type"\. - - * __callback__ - - callback function name for additional type\. - -# TYPE CALLBACK - -The definition of callback for user\-type\. - - - __[callback](\.\./\.\./\.\./\.\./index\.md\#callback)__ *command* ?*args*? - - * __command__ - - huddle subcomand which is needed to reply by the callback\. - - * __args__ - - arguments of subcommand\. The number of list of arguments is different - for each subcommand\. - -The callback procedure shuould reply the following subcommands\. - - - __setting__ - - only returns a fixed dict of the type infomation for setting the user\-tag\. - - * __type__ typename - - typename of the type - - * __method__ \{method1 method2 method3 \.\.\.\} - - method list as huddle subcommand\. Then, you can call __\[huddle method1 - \.\.\.\]__ - - * __tag__ \{tag1 child/parent tag2 child/parent \.\.\.\} - - tag list for huddle\-node as a dict\. if the type has child\-nodes, use - "parent", otherwise use "child"\. - - - __get\_sub__ *src* *key* - - returns a sub node specified by *key*\. - - * __src__ - - a node content in huddle object\. - - - __strip__ *src* - - returns stripped node contents\. if the type has child nodes, every node must - be stripped\. - - - __[set](\.\./\.\./\.\./\.\./index\.md\#set)__ *src* *key* *value* - - sets a sub\-node from the tagged\-content, and returns self\. - - - __[remove](\.\./\.\./\.\./\.\./index\.md\#remove)__ *src* *key* *value* - - removes a sub\-node from the tagged\-content, and returns self\. - -__strip__ must be defined at all types\. __get\_sub__ must be defined at -container types\. __set/remove__ shuould be defined, if you call them\. - - # callback sample for my-dict - proc my_dict_setting {command args} { - switch -- $command { - setting { ; # type definition - return { - type dict - method {create keys} - tag {d child D parent} - constructor create - str s - } - # type: the type-name - # method: add methods to huddle's subcommand. - # "get_sub/strip/set/remove/equal/append" called by huddle module. - # "strip" must be defined at all types. - # "get_sub" must be defined at container types. - # "set/remove/equal/append" shuould be defined, if you call them. - # tag: tag definition("child/parent" word is maybe obsoleted) - } - get_sub { ; # get a sub-node specified by "key" from the tagged-content - foreach {src key} $args break - return [dict get $src $key] - } - strip { ; # strip from the tagged-content - foreach {src nop} $args break - foreach {key val} $src { - lappend result $key [huddle strip $val] - } - return $result - } - set { ; # set a sub-node from the tagged-content - foreach {src key value} $args break - dict set src $key $value - return $src - } - remove { ; # remove a sub-node from the tagged-content - foreach {src key value} $args break - return [dict remove $src $key] - } - equal { ; # check equal for each node - foreach {src1 src2} $args break - if {[llength $src1] != [llength $src2]} {return 0} - foreach {key1 val1} $src1 { - if {![dict exists $src2 $key1]} {return 0} - if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0} - } - return 1 - } - append { ; # append nodes - foreach {str src list} $args break - if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}} - set resultL $src - foreach {key value} $list { - if {$str ne ""} { - lappend resultL $key [huddle to_node $value $str] - } else { - lappend resultL $key $value - } - } - return [eval dict create $resultL] - } - create { ; # $args: all arguments after "huddle create" - if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}} - set resultL {} - foreach {key value} $args { - lappend resultL $key [huddle to_node $value] - } - return [huddle wrap D $resultL] - } - keys { - foreach {src nop} $args break - return [dict keys [lindex [lindex $src 1] 1]] - } - default { - error "$command is not callback for dict" - } - } - } - - # inheritance sample from default dict-callback - proc ::yaml::_huddle_mapping {command args} { - switch -- $command { - setting { ; # type definition - return { - type dict - method {mapping} - tag {!!map parent} - constructor mapping - str !!str - } - } - mapping { ; # $args: all arguments after "huddle mapping" - if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}} - set resultL {} - foreach {key value} $args { - lappend resultL $key [huddle to_node $value !!str] - } - return [huddle wrap !!map $resultL] - } - default { ; # devolving to default dict-callback - return [huddle call D $command $args] - } - } - } - -# How to add type - -You can add huddle\-node types e\.g\. ::struct::tree\. To do so, first, define a -callback\-procedure for additional tagged\-type\. The proc get argments as -*command* and ?*args*?\. It has some switch\-sections\. - -And, addType subcommand will called\. - - huddle addType my_dict_setting - -# WORKING SAMPLE - - # create as a dict - % set bb [huddle create a b c d] - HUDDLE {D {a {s b} c {s d}}} - - # create as a list - % set cc [huddle list e f g h] - HUDDLE {L {{s e} {s f} {s g} {s h}}} - % set bbcc [huddle create bb $bb cc $cc] - HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} - % set folding [huddle list $bbcc p [huddle list q r] s] - HUDDLE {L {{D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}} - - # normal Tcl's notation - % huddle strip $folding - {bb {a b c d} cc {e f g h}} p {q r} s - - # get a sub node - % huddle get $folding 0 bb - HUDDLE {D {a {s b} c {s d}}} - % huddle gets $folding 0 bb - a b c d - - # overwrite a node - % huddle set folding 0 bb c kkk - HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}} - - # remove a node - % huddle remove $folding 2 1 - HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q}}} {s s}}} - % huddle strip $folding - {bb {a b c kkk} cc {e f g h}} p {q r} s - - # dump as a JSON stream - % huddle jsondump $folding - [ - { - "bb": { - "a": "b", - "c": "kkk" - }, - "cc": [ - "e", - "f", - "g", - "h" - ] - }, - "p", - [ - "q", - "r" - ], - "s" - ] - -# LIMITATIONS - -now printing\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *huddle* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[yaml](yaml\.md) - -# KEYWORDS - -[data exchange](\.\./\.\./\.\./\.\./index\.md\#data\_exchange), [exchange -format](\.\./\.\./\.\./\.\./index\.md\#exchange\_format), -[huddle](\.\./\.\./\.\./\.\./index\.md\#huddle), -[json](\.\./\.\./\.\./\.\./index\.md\#json), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), -[yaml](\.\./\.\./\.\./\.\./index\.md\#yaml) - -# COPYRIGHT - -Copyright © 2008\-2011 KATO Kanryu -Copyright © 2015 Miguel Martínez López DELETED embedded/md/tcllib/files/modules/yaml/yaml.md Index: embedded/md/tcllib/files/modules/yaml/yaml.md ================================================================== --- embedded/md/tcllib/files/modules/yaml/yaml.md +++ embedded/md/tcllib/files/modules/yaml/yaml.md @@ -1,242 +0,0 @@ - -[//000000001]: # (yaml \- YAML processing) -[//000000002]: # (Generated from file 'yaml\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008 KATO Kanryu ) -[//000000004]: # (yaml\(n\) 0\.4\.1 tcllib "YAML processing") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -yaml \- YAML Format Encoder/Decoder - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [COMMANDS](#section2) - - - [EXAMPLES](#section3) - - - [LIMITATIONS](#section4) - - - [Bugs, Ideas, Feedback](#section5) - - - [See Also](#seealso) - - - [Keywords](#keywords) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require yaml ?0\.4\.1? - -[__::yaml::yaml2dict__ ?*options*? *txt*](#1) -[__::yaml::yaml2huddle__ ?*options*? *txt*](#2) -[__::yaml::setOption__ ?*options*?](#3) -[__::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*?](#4) -[__::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*?](#5) -[__::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*?](#6) - -# DESCRIPTION - -The __yaml__ package provides a simple Tcl\-only library for parsing the YAML -[http://www\.yaml\.org/](http://www\.yaml\.org/) data exchange format as -specified in [http://www\.yaml\.org/spec/1\.1/](http://www\.yaml\.org/spec/1\.1/)\. - -The __yaml__ package returns data as a Tcl -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__\. Either the -__[dict](\.\./\.\./\.\./\.\./index\.md\#dict)__ package or Tcl 8\.5 is required for -use\. - -# COMMANDS - - - __::yaml::yaml2dict__ ?*options*? *txt* - - - __::yaml::yaml2huddle__ ?*options*? *txt* - - Parse yaml formatted text *txt* into a Tcl dict/huddle and return the - value\. - - * ____\-file____ - - *txt* is a filename of YAML\-stream\. - - * ____\-stream____ - - *txt* is just a YAML\-stream\. - - * ____\-types__ *list*__ - - The *list* is a type list for the yaml\-scalar types\.\(e\.g\. \!\!str - \!\!timestamp \!\!integer \!\!true \.\.\.\) - - -types {timestamp integer null true false} - - In this case, if a string matched "timestamp", converted to the TCL - internal timestamp\.\(e\.g\. "2001\-12\-15T02:59:43\.1Z" => 1008385183\) - - * ____\-m:true__ *param*__ - - The *param* is two elements of list for the value of true, and - considered strings\. - - -m:true {1 {true on + yes y}} - - In this case, the string "yes" found in YAML Stream, automatically - converted 1\. - - * ____\-m:false__ *param*__ - - The *param* is two elements of list for the value of false, and - considered strings\. - - -m:false {0 {false off - no n}} - - * ____\-m:null__ *param*__ - - The *param* is two elements of list for the value of null, and - considered strings\. - - -m:null {"" {null nil "" ~}} - - * ____\-validate____ - - Experiment,old: Output stream contains YAML's\-tag, each node\. - - % puts [::yaml::load -validate {[aaa, bbb]}] - => - !!seq {{!!str aaa} {!!str bbb}} - - - __::yaml::setOption__ ?*options*? - - Change implicit options for the library\. Now, the params are the same as - __::yaml::yaml2dict__\. Arguments of__::yaml::yaml2dict__ is more - priority than this setting\. - - - __::yaml::dict2yaml__ *dict* ?*indent*? ?*wordwrap*? - - - __::yaml::list2yaml__ *list* ?*indent*? ?*wordwrap*? - - - __::yaml::huddle2yaml__ *huddle* ?*indent*? ?*wordwrap*? - - Convert a dict/list/huddle object into YAML stream\. - - * indent - - spaces indent of each block node\. currently default is 2\. - - * wordwrap - - word wrap for YAML stream\. currently default is 40\. - -# EXAMPLES - -An example of a yaml stream converted to Tcl\. A yaml stream is returned as a -single item with multiple elements\. - - { - --- ! - invoice: 34843 - date : 2001-01-23 - bill-to: &id001 - given : Chris - family : Dumars - address: - lines: | - 458 Walkman Dr. - Suite #292 - city : Royal Oak - state : MI - postal : 48046 - ship-to: *id001 - product: - - sku : BL394D - quantity : 4 - description : Basketball - price : 450.00 - - sku : BL4438H - quantity : 1 - description : Super Hoop - price : 2392.00 - tax : 251.42 - total: 4443.52 - comments: - Late afternoon is best. - Backup contact is Nancy - Billsmer @ 338-4338. - } - => - invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr. - Suite #292 - } city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr. - Suite #292 - } city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.} - -An example of a yaml object converted to Tcl\. A yaml object is returned as a -multi\-element list \(a dict\)\. - - { - --- - - [name , hr, avg ] - - [Mark McGwire, 65, 0.278] - - [Sammy Sosa , 63, 0.288] - - - Mark McGwire: {hr: 65, avg: 0.278} - Sammy Sosa: { hr: 63, avg: 0.288} - } - => - {name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}} - -# LIMITATIONS - -tag parser not implemented\. currentry, tags are merely ignored\. - -Only Anchor => Aliases ordering\. back alias\-referring is not supported\. - -Too many braces, or too few braces\. - -Not enough character set of line feeds\. Please use only "\\n" as line breaks\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *yaml* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# SEE ALSO - -[base64](\.\./base64/base64\.md), [huddle](huddle\.md), -[json](\.\./json/json\.md) - -# KEYWORDS - -[data exchange](\.\./\.\./\.\./\.\./index\.md\#data\_exchange), -[huddle](\.\./\.\./\.\./\.\./index\.md\#huddle), -[parsing](\.\./\.\./\.\./\.\./index\.md\#parsing), [text -processing](\.\./\.\./\.\./\.\./index\.md\#text\_processing), -[yaml](\.\./\.\./\.\./\.\./index\.md\#yaml) - -# COPYRIGHT - -Copyright © 2008 KATO Kanryu DELETED embedded/md/tcllib/files/modules/zip/decode.md Index: embedded/md/tcllib/files/modules/zip/decode.md ================================================================== --- embedded/md/tcllib/files/modules/zip/decode.md +++ embedded/md/tcllib/files/modules/zip/decode.md @@ -1,170 +0,0 @@ - -[//000000001]: # (zipfile::decode \- Zip archive handling) -[//000000002]: # (Generated from file 'decode\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008\-2016 Andreas Kupries) -[//000000004]: # (zipfile::decode\(n\) 0\.7\.1 tcllib "Zip archive handling") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -zipfile::decode \- Access to zip archives - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require fileutil::decode 0\.2\.1 -package require Trf -package require zlibtcl -package require zipfile::decode ?0\.7\.1? - -[__::zipfile::decode::archive__](#1) -[__::zipfile::decode::close__](#2) -[__::zipfile::decode::comment__ *adict*](#3) -[__::zipfile::decode::content__ *archive*](#4) -[__::zipfile::decode::copyfile__ *adict* *path* *dst*](#5) -[__::zipfile::decode::files__ *adict*](#6) -[__::zipfile::decode::getfile__ *zdict* *path*](#7) -[__::zipfile::decode::hasfile__ *adict* *path*](#8) -[__::zipfile::decode::iszip__ *archive*](#9) -[__::zipfile::decode::open__ *archive*](#10) -[__::zipfile::decode::unzip__ *adict* *dstdir*](#11) -[__::zipfile::decode::unzipfile__ *archive* *dstdir*](#12) - -# DESCRIPTION - -Note: packages Trf and zlibtcl are not required if TCL 8\.6 is available\. This -package provides commands to decompress and access the contents of zip archives\. - -# API - - - __::zipfile::decode::archive__ - - This command decodes the last opened \(and not yet closed\) zip archive file\. - The result of the command is a dictionary describing the contents of the - archive\. The structure of this dictionary is not public\. Proper access - should be made through the provided accessor command of this package\. - - - __::zipfile::decode::close__ - - This command releases all state associated with the last call of - __::zipfile::decode::open__\. The result of the command is the empty - string\. - - - __::zipfile::decode::comment__ *adict* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and returns the - global comment of the archive\. - - - __::zipfile::decode::content__ *archive* - - This is a convenience command which decodes the specified zip *archive* - file and returns the list of paths found in it as its result\. - - - __::zipfile::decode::copyfile__ *adict* *path* *dst* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and copies the - decompressed contents of the file *path* in the archive to the the file - *dst*\. An error is thrown if the file is not found in the archive\. - - - __::zipfile::decode::files__ *adict* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and returns the - list of files found in the archive\. - - - __::zipfile::decode::getfile__ *zdict* *path* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and returns the - decompressed contents of the file *path* in the archive\. An error is - thrown if the file is not found in the archive\. - - - __::zipfile::decode::hasfile__ *adict* *path* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and check if the - specified *path* is found in the archive\. The result of the command is a - boolean flag, __true__ if the path is found, and __false__ - otherwise\. - - - __::zipfile::decode::iszip__ *archive* - - This command takes the path of a presumed zip *archive* file and returns a - boolean flag as the result of the command telling us if it actually is a zip - archive \(__true__\), or not \(__false__\)\. - - - __::zipfile::decode::open__ *archive* - - This command takes the path of a zip *archive* file and prepares it for - decoding\. The result of the command is the empty string\. All important - information is stored in global state\. If multiple open calls are made one - after the other only the state of the last call is available to the other - commands\. - - - __::zipfile::decode::unzip__ *adict* *dstdir* - - This command takes a dictionary describing the currently open zip archive - file, as returned by __::zipfile::decode::archive__, and unpacks the - archive in the given destination directory *dstdir*\. The result of the - command is the empty string\. - - - __::zipfile::decode::unzipfile__ *archive* *dstdir* - - This is a convenience command which unpacks the specified zip *archive* - file in the given destination directory *dstdir*\. - - The result of the command is the empty string\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *zipfile* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[decompression](\.\./\.\./\.\./\.\./index\.md\#decompression), -[zip](\.\./\.\./\.\./\.\./index\.md\#zip) - -# CATEGORY - -File - -# COPYRIGHT - -Copyright © 2008\-2016 Andreas Kupries DELETED embedded/md/tcllib/files/modules/zip/encode.md Index: embedded/md/tcllib/files/modules/zip/encode.md ================================================================== --- embedded/md/tcllib/files/modules/zip/encode.md +++ embedded/md/tcllib/files/modules/zip/encode.md @@ -1,126 +0,0 @@ - -[//000000001]: # (zipfile::encode \- Zip archive handling) -[//000000002]: # (Generated from file 'encode\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2008\-2009 Andreas Kupries) -[//000000004]: # (zipfile::encode\(n\) 0\.4 tcllib "Zip archive handling") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -zipfile::encode \- Generation of zip archives - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [Class API](#section2) - - - [Instance API](#section3) - - - [Bugs, Ideas, Feedback](#section4) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.4 -package require logger -package require Trf -package require crc32 -package require snit -package require zlibtcl -package require fileutil -package require zipfile::encode ?0\.4? - -[__::zipfile::encode__ ?*objectName*?](#1) -[____ __comment:__ *text*](#2) -[____ __file:__ *dst* *owned* *src* ?*noCompress*?](#3) -[____ __write__ *archive*](#4) - -# DESCRIPTION - -This package provides a class for the generation of zip archives\. - -# Class API - - - __::zipfile::encode__ ?*objectName*? - - The class command constructs encoder instances, i\.e\. objects\. The result of - the command is the fully\-qualified name of the instance command\. - - If no *objectName* is specified the class will generate and use an - automatic name\. If the *objectName* was specified, but is not fully - qualified the command will be created in the current namespace\. - -# Instance API - - - ____ __comment:__ *text* - - This method specifies the text of the global comment for the archive\. The - result of the method is the empty string\. In case of multiple calls to this - method for the same encoder the data from the last call prevails over all - previous texts\. - - - ____ __file:__ *dst* *owned* *src* ?*noCompress*? - - This method adds a new file to the archive\. The contents of the file are - found in the filesystem at *src*, and will be stored in the archive under - path *dst*\. If the file is declared as *owned* by the archive the - original file will be deleted when the archive is constructed and written\. - If *noCompress* is set to __true__ the file will not be compressed on - writing\. Otherwise \(the default\) the file is compressed if it is - advantageous\. The result of the method is an empty string\. - - - ____ __write__ *archive* - - This method takes the global comment and all added files, encodes them as a - zip archive and stores the result at path *archive* in the filesystem\. All - added files which were owned by the archive are deleted at this point\. On - the issue of ordering, the files are added to the archive in the same order - as they were specified via __file:__\. *Note* that this behaviour is - new for version 0\.4 and higher\. Before 0\.4 no specific order was documented\. - It was lexicographically sorted\. The change was made to support - __[zip](\.\./\.\./\.\./\.\./index\.md\#zip)__\-based file formats which require - a specific order of files in the archive, for example "\.epub"\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *zipfile* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[compression](\.\./\.\./\.\./\.\./index\.md\#compression), -[zip](\.\./\.\./\.\./\.\./index\.md\#zip) - -# CATEGORY - -File - -# COPYRIGHT - -Copyright © 2008\-2009 Andreas Kupries DELETED embedded/md/tcllib/files/modules/zip/mkzip.md Index: embedded/md/tcllib/files/modules/zip/mkzip.md ================================================================== --- embedded/md/tcllib/files/modules/zip/mkzip.md +++ embedded/md/tcllib/files/modules/zip/mkzip.md @@ -1,149 +0,0 @@ - -[//000000001]: # (zipfile::mkzip \- Zip archive creation) -[//000000002]: # (Generated from file 'mkzip\.man' by tcllib/doctools with format 'markdown') -[//000000003]: # (Copyright © 2009 Pat Thoyts) -[//000000004]: # (zipfile::mkzip\(n\) 1\.2\.1 tcllib "Zip archive creation") - -
[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]
- -# NAME - -zipfile::mkzip \- Build a zip archive - -# Table Of Contents - - - [Table Of Contents](#toc) - - - [Synopsis](#synopsis) - - - [Description](#section1) - - - [API](#section2) - - - [Bugs, Ideas, Feedback](#section3) - - - [Keywords](#keywords) - - - [Category](#category) - - - [Copyright](#copyright) - -# SYNOPSIS - -package require Tcl 8\.6 -package require zipfile::mkzip ?1\.2\.1? - -[__::zipfile::mkzip::mkzip__ *zipfile* ?__\-zipkit__? ?__\-runtime__ *prefix*? ?__\-comment__ *string*? ?__\-directory__ *rootpath*? ?__\-exclude__ *exclude*? ?__\-\-__? ?*path*\.\.\.?](#1) - -# DESCRIPTION - -This package utilizes the zlib functions in Tcl 8\.6 to build zip archives\. - -# API - - - __::zipfile::mkzip::mkzip__ *zipfile* ?__\-zipkit__? ?__\-runtime__ *prefix*? ?__\-comment__ *string*? ?__\-directory__ *rootpath*? ?__\-exclude__ *exclude*? ?__\-\-__? ?*path*\.\.\.? - - From [http://wiki\.tcl\.tk/15158](http://wiki\.tcl\.tk/15158) - - This command constructs a zip archive from a directory tree using nothing - but Tcl 8\.6 core features\. The resulting zip file should be compatible with - other __[zip](\.\./\.\./\.\./\.\./index\.md\#zip)__ programs \- with the - possible exception of unicode support\. The files generated by this command - use utf\-8 encoding for all filenames and comments and it has been noticed - particularly on Windows the __info\-zip__ and the Windows built\-in zip - view have rather poor support for this part of the ZIP file specification\. - The __7\-Zip__ program does correctly display utf8 filenames however and - the __vfs::zip__ package will use these of course\. - - If you use - - > __::mkzip::mkzip__ mystuff\.tm \-zipkit \-directory mystuff\.vfs - - it will pack your "mystuff\.vfs/" virtual filesystem tree into a zip archive - with a suitable header such that on unix you may mark it executable and it - should run with tclkit\. Or you can run it with __tclsh__ or __wish__ - 8\.6 if you like\. - - To change the executable header, specify the __\-runtime__ "preface" - where preface is a file containing code you want prefixed\. For instance, on - Windows you can create a self\-extracting zip archive using - - mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe - - The "unzipsfx\.exe" is the Info\-Zip self\-extracting stub\. - - Accepted options: - - * __\-runtime__ path - - This option specifies a file to use as prefix to the actual zip archive\. - If specified __\-zipkit__ will be ignored\. - - * __\-zipkit__ - - Instructs the command to generate a prefix which makes the archive a - zip\-based starkit\. Ignored if __\-runtime__ is present\. - - * __\-comment__ string - - This options specifies a global comment to place into the generated - archive\. - - * __\-directory__ path - - This option specifies the directory to place into the generated archive\. - If specified any argument *path*s are *ignored*\. - - * __\-exclude__ list - - This option specifies a list of glob patterns\. All paths matching at - least one of the patterns are not placed into the generated archive\. - This option defaults to - - CVS/* */CVS/* *~ ".#*" "*/.#*" - - * __\-\-__ - - This option signals the end of the options, forcing processing of all - further words as arguments, even if they begin with a dash character\. - - Accepted arguments: - - * path *path* - - Each path is a directory or file to place into the generated archive\. - Note however that these will be ignored when option __\-directory__ - is specified\. - -# Bugs, Ideas, Feedback - -This document, and the package it describes, will undoubtedly contain bugs and -other problems\. Please report such in the category *zipfile* of the [Tcllib -Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas -for enhancements you may have for either package and/or documentation\. - -When proposing code changes, please provide *unified diffs*, i\.e the output of -__diff \-u__\. - -Note further that *attachments* are strongly preferred over inlined patches\. -Attachments can be made by going to the __Edit__ form of the ticket -immediately after its creation, and then using the left\-most button in the -secondary navigation bar\. - -# KEYWORDS - -[decompression](\.\./\.\./\.\./\.\./index\.md\#decompression), -[zip](\.\./\.\./\.\./\.\./index\.md\#zip) - -# CATEGORY - -File - -# COPYRIGHT - -Copyright © 2009 Pat Thoyts DELETED embedded/md/tcllib/toc.md Index: embedded/md/tcllib/toc.md ================================================================== --- embedded/md/tcllib/toc.md +++ embedded/md/tcllib/toc.md @@ -1,890 +0,0 @@ - -[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') - -# Table Of Contents \-\- tcllib - - - [aes](tcllib/files/modules/aes/aes\.md) Implementation of the AES block cipher - - - [ascii85](tcllib/files/modules/base64/ascii85\.md) ascii85\-encode/decode binary data - - - [asn](tcllib/files/modules/asn/asn\.md) ASN\.1 BER encoder/decoder - - - [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication - - - [base32](tcllib/files/modules/base32/base32\.md) base32 standard encoding - - - [base32::core](tcllib/files/modules/base32/base32core\.md) Expanding basic base32 maps - - - [base32::hex](tcllib/files/modules/base32/base32hex\.md) base32 extended hex encoding - - - [base64](tcllib/files/modules/base64/base64\.md) base64\-encode/decode binary data - - - [bee](tcllib/files/modules/bee/bee\.md) BitTorrent Serialization Format Encoder/Decoder - - - [bench](tcllib/files/modules/bench/bench\.md) bench \- Processing benchmark suites - - - [bench::in](tcllib/files/modules/bench/bench\_read\.md) bench::in \- Reading benchmark results - - - [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) bench::out::csv \- Formatting benchmark results as CSV - - - [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) bench::out::text \- Formatting benchmark results as human readable text - - - [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) bench introduction - - - [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) bench language introduction - - - [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) bench language specification - - - [bibtex](tcllib/files/modules/bibtex/bibtex\.md) Parse bibtex files - - - [blowfish](tcllib/files/modules/blowfish/blowfish\.md) Implementation of the Blowfish block cipher - - - [cache::async](tcllib/files/modules/cache/async\.md) Asynchronous in\-memory cache - - - [cksum](tcllib/files/modules/crc/cksum\.md) Calculate a cksum\(1\) compatible checksum - - - [clay](tcllib/files/modules/clay/clay\.md) A minimalist framework for large scale OO Projects - - - [clock\_iso8601](tcllib/files/modules/clock/iso8601\.md) Parsing ISO 8601 dates/times - - - [clock\_rfc2822](tcllib/files/modules/clock/rfc2822\.md) Parsing RFC 2822 dates/times - - - [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. - - - [comm](tcllib/files/modules/comm/comm\.md) A remote communication facility for Tcl \(8\.3 and later\) - - - [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) The comm wire protocol - - - [control](tcllib/files/modules/control/control\.md) Procedures for control flow structures\. - - - [coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) Coroutine based event and IO handling - - - [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) Automatic event and IO coroutine awareness - - - [counter](tcllib/files/modules/counter/counter\.md) Procedures for counters and histograms - - - [crc16](tcllib/files/modules/crc/crc16\.md) Perform a 16bit Cyclic Redundancy Check - - - [crc32](tcllib/files/modules/crc/crc32\.md) Perform a 32bit Cyclic Redundancy Check - - - [cron](tcllib/files/modules/cron/cron\.md) Tool for automating the period callback of commands - - - [csv](tcllib/files/modules/csv/csv\.md) Procedures to handle CSV data\. - - - [debug](tcllib/files/modules/debug/debug\.md) debug narrative \- core - - - [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) debug narrative \- caller - - - [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) debug narrative \- heartbeat - - - [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) debug narrative \- timestamping - - - [defer](tcllib/files/modules/defer/defer\.md) Defered execution - - - [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) Creation of comm delegates \(snit methods\) - - - [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) Creation of comm delegates \(procedures\) - - - [des](tcllib/files/modules/des/des\.md) Implementation of the DES and triple\-DES ciphers - - - [dicttool](tcllib/files/modules/dicttool/dicttool\.md) Dictionary Tools - - - [dns](tcllib/files/modules/dns/tcllib\_dns\.md) Tcl Domain Name Service Client - - - [docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) docidx introduction - - - [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) docidx language command reference - - - [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) docidx language faq - - - [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) docidx language introduction - - - [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) docidx language syntax - - - [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) docidx plugin API reference - - - [docstrip](tcllib/files/modules/docstrip/docstrip\.md) Docstrip style source code extraction - - - [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) Docstrip\-related utilities - - - [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) doctoc introduction - - - [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) doctoc language command reference - - - [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) doctoc language faq - - - [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) doctoc language introduction - - - [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) doctoc language syntax - - - [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) doctoc plugin API reference - - - [doctools](tcllib/files/modules/doctools/doctools\.md) doctools \- Processing documents - - - [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) DocTools \- Keyword indices - - - [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) DocTools \- Tables of Contents - - - [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) Processing text in Emacs ChangeLog format - - - [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) Processing text in 'cvs log' format - - - [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) Default CSS style for HTML export plugins - - - [doctools::idx](tcllib/files/modules/doctools/docidx\.md) docidx \- Processing indices - - - [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) Holding keyword indices - - - [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) Exporting keyword indices - - - [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) docidx export plugin - - - [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) HTML export plugin - - - [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) JSON export plugin - - - [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) nroff export plugin - - - [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) plain text export plugin - - - [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) wiki export plugin - - - [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) Importing keyword indices - - - [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) docidx import plugin - - - [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) JSON import plugin - - - [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) Parsing text in docidx format - - - [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) Docidx serialization utilities - - - [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) Message catalog management for the various document parsers - - - [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) Message catalog for the docidx parser \(C\) - - - [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) Message catalog for the docidx parser \(DE\) - - - [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) Message catalog for the docidx parser \(EN\) - - - [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) Message catalog for the docidx parser \(FR\) - - - [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) Message catalog for the doctoc parser \(C\) - - - [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) Message catalog for the doctoc parser \(DE\) - - - [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) Message catalog for the doctoc parser \(EN\) - - - [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) Message catalog for the doctoc parser \(FR\) - - - [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) Default CSS style for NROFF export plugins - - - [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) Processing text in 'subst \-novariables' format - - - [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) Holding tables of contents - - - [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) doctoc \- Processing tables of contents - - - [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) Exporting tables of contents - - - [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) doctoc export plugin - - - [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) HTML export plugin - - - [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) JSON export plugin - - - [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) nroff export plugin - - - [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) plain text export plugin - - - [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) wiki export plugin - - - [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) Importing keyword indices - - - [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) doctoc import plugin - - - [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) JSON import plugin - - - [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) Parsing text in doctoc format - - - [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) Doctoc serialization utilities - - - [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) doctools introduction - - - [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) doctools language command reference - - - [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) doctools language faq - - - [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) doctools language introduction - - - [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) doctools language syntax - - - [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) doctools plugin API reference - - - [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) Lightweight DocTools Markup Processor - - - [dtplite](tcllib/files/apps/dtplite\.md) Lightweight DocTools Markup Processor - - - [fileutil](tcllib/files/modules/fileutil/fileutil\.md) Procedures implementing some file utilities - - - [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) Generator core for compiler of magic\(5\) files - - - [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) Generator core for compiler of magic\(5\) files - - - [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) Procedures implementing file\-type recognition - - - [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) Runtime core for file type recognition engines written in pure Tcl - - - [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) Multi\-file operation, scatter/gather, standard object - - - [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) Multi\-file operation, scatter/gather - - - [fileutil::paths](tcllib/files/modules/fileutil/paths\.md) Manage search path pools - - - [fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md) Iterative directory traversal - - - [ftp](tcllib/files/modules/ftp/ftp\.md) Client\-side tcl implementation of the ftp protocol - - - [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) Uri handler for ftp urls - - - [ftpd](tcllib/files/modules/ftpd/ftpd\.md) Tcl FTP server implementation - - - [generator](tcllib/files/modules/generator/generator\.md) Procedures for creating and using generators\. - - - [gpx](tcllib/files/modules/gpx/gpx\.md) Extracts waypoints, tracks and routes from GPX files - - - [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) Aycock\-Horspool\-Earley parser generator for Tcl - - - [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) Create and manipulate finite automatons - - - [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) Create and use deterministic acceptors - - - [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) Execute deterministic finite automatons - - - [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) Operations on finite automatons - - - [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) Virtual machine implementation II for parsing token streams - - - [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) ME virtual machine state manipulation - - - [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) ME assembler - - - [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) Virtual machine implementation I for parsing token streams - - - [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) AST utilities - - - [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md) Various representations of ASTs - - - [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) Introduction to virtual machines for parsing token streams - - - [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) Virtual machine for parsing token streams - - - [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) Create and manipulate parsing expression grammars - - - [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) Interpreter for parsing expression grammars - - - [hook](tcllib/files/modules/hook/hook\.md) Hooks - - - [html](tcllib/files/modules/html/html\.md) Procedures to generate HTML structures - - - [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) Procedures to parse HTML strings - - - [httpd](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - - - [huddle](tcllib/files/modules/yaml/huddle\.md) Create and manipulate huddle object - - - [ident](tcllib/files/modules/ident/ident\.md) Ident protocol client - - - [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - - - [inifile](tcllib/files/modules/inifile/ini\.md) Parsing of Windows INI files - - - [interp](tcllib/files/modules/interp/tcllib\_interp\.md) Interp creation and aliasing - - - [irc](tcllib/files/modules/irc/irc\.md) Create IRC connection and interface\. - - - [javascript](tcllib/files/modules/javascript/javascript\.md) Procedures to generate HTML and Java Script structures\. - - - [jpeg](tcllib/files/modules/jpeg/jpeg\.md) JPEG querying and manipulation of meta data - - - [json](tcllib/files/modules/json/json\.md) JSON parser - - - [json::write](tcllib/files/modules/json/json\_write\.md) JSON generation - - - [lambda](tcllib/files/modules/lambda/lambda\.md) Utility commands for anonymous procedures - - - [lazyset](tcllib/files/modules/lazyset/lazyset\.md) Lazy evaluation - - - [ldap](tcllib/files/modules/ldap/ldap\.md) LDAP client - - - [ldapx](tcllib/files/modules/ldap/ldapx\.md) LDAP extended object interface - - - [log](tcllib/files/modules/log/log\.md) Procedures to log messages of libraries and applications\. - - - [logger](tcllib/files/modules/log/logger\.md) System to control logging of events\. - - - [logger::appender](tcllib/files/modules/log/loggerAppender\.md) Collection of predefined appenders for logger - - - [logger::utils](tcllib/files/modules/log/loggerUtils\.md) Utilities for logger - - - [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) Resolving geographical names with a Nominatim service - - - [map::slippy](tcllib/files/modules/map/map\_slippy\.md) Common code for slippy based map packages - - - [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) Management of a tile cache in the local filesystem - - - [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) Accessing a server providing tiles for slippy\-based maps - - - [mapproj](tcllib/files/modules/mapproj/mapproj\.md) Map projection routines - - - [markdown](tcllib/files/modules/markdown/markdown\.md) Converts Markdown text to HTML - - - [math](tcllib/files/modules/math/math\.md) Tcl Math Library - - - [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) Arbitrary precision floating\-point numbers - - - [math::bignum](tcllib/files/modules/math/bignum\.md) Arbitrary precision integer numbers - - - [math::calculus](tcllib/files/modules/math/calculus\.md) Integration and ordinary differential equations - - - [math::calculus::romberg](tcllib/files/modules/math/romberg\.md) Romberg integration - - - [math::calculus::symdiff](tcllib/files/modules/math/symdiff\.md) Symbolic differentiation for Tcl - - - [math::changepoint](tcllib/files/modules/math/changepoint\.md) Change point detection methods - - - [math::combinatorics](tcllib/files/modules/math/combinatorics\.md) Combinatorial functions in the Tcl Math Library - - - [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) Straightforward complex number package - - - [math::constants](tcllib/files/modules/math/constants\.md) Mathematical and numerical constants - - - [math::decimal](tcllib/files/modules/math/decimal\.md) General decimal arithmetic - - - [math::exact](tcllib/files/modules/math/exact\.md) Exact Real Arithmetic - - - [math::filters](tcllib/files/modules/math/filtergen\.md) Digital filters - - - [math::fourier](tcllib/files/modules/math/fourier\.md) Discrete and fast fourier transforms - - - [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) Fuzzy comparison of floating\-point numbers - - - [math::geometry](tcllib/files/modules/math/math\_geometry\.md) Geometrical computations - - - [math::interpolate](tcllib/files/modules/math/interpolate\.md) Interpolation routines - - - [math::linearalgebra](tcllib/files/modules/math/linalg\.md) Linear Algebra - - - [math::machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - - - [math::numtheory](tcllib/files/modules/math/numtheory\.md) Number Theory - - - [math::optimize](tcllib/files/modules/math/optimize\.md) Optimisation routines - - - [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis - - - [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions - - - [math::probopt](tcllib/files/modules/math/probopt\.md) Probabilistic optimisation methods - - - [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) Quasi\-random points for integration and Monte Carlo type methods - - - [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) Polynomial functions - - - [math::roman](tcllib/files/modules/math/roman\.md) Tools for creating and manipulating roman numerals - - - [math::special](tcllib/files/modules/math/special\.md) Special mathematical functions - - - [math::statistics](tcllib/files/modules/math/statistics\.md) Basic statistical functions and procedures - - - [math::trig](tcllib/files/modules/math/trig\.md) Trigonometric anf hyperbolic functions - - - [md4](tcllib/files/modules/md4/md4\.md) MD4 Message\-Digest Algorithm - - - [md5](tcllib/files/modules/md5/md5\.md) MD5 Message\-Digest Algorithm - - - [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) MD5\-based password encryption - - - [mime](tcllib/files/modules/mime/mime\.md) Manipulation of MIME body parts - - - [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) Markup processor - - - [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) One\-to\-many communication with sockets\. - - - [nameserv](tcllib/files/modules/nns/nns\_client\.md) Name service facility, Client - - - [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) Name service facility, Client Extension - - - [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) Name service facility, shared definitions - - - [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) Name service facility, client/server protocol - - - [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) Name service facility, Server - - - [namespacex](tcllib/files/modules/namespacex/namespacex\.md) Namespace utility commands - - - [ncgi](tcllib/files/modules/ncgi/ncgi\.md) Procedures to manipulate CGI values\. - - - [nettool](tcllib/files/modules/nettool/nettool\.md) Tools for networked applications - - - [nmea](tcllib/files/modules/nmea/nmea\.md) Process NMEA data - - - [nns](tcllib/files/apps/nns\.md) Name service facility, Commandline Client Application - - - [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) Name service facility, introduction - - - [nnsd](tcllib/files/apps/nnsd\.md) Name service facility, Commandline Server Application - - - [nnslog](tcllib/files/apps/nnslog\.md) Name service facility, Commandline Logging Client Application - - - [nntp](tcllib/files/modules/nntp/nntp\.md) Tcl client for the NNTP protocol - - - [ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md) Tcl Time Service Client - - - [oauth](tcllib/files/modules/oauth/oauth\.md) oauth API base signature - - - [oo::util](tcllib/files/modules/tool/meta\.md) Utility commands for TclOO - - - [oo::util](tcllib/files/modules/ooutil/ooutil\.md) Utility commands for TclOO - - - [oometa](tcllib/files/modules/oometa/oometa\.md) oo::meta A data registry for classess - - - [otp](tcllib/files/modules/otp/otp\.md) One\-Time Passwords - - - [page](tcllib/files/apps/page\.md) Parser Generator - - - [page\_intro](tcllib/files/modules/page/page\_intro\.md) page introduction - - - [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) page plugin manager - - - [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) page dataflow/treewalker utility - - - [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) page AST normalization, LEMON - - - [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) page AST normalization, PEG - - - [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) page PEG transformation utilities - - - [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) page character quoting utilities - - - [picoirc](tcllib/files/modules/irc/picoirc\.md) Small and simple embeddable IRC client\. - - - [pki](tcllib/files/modules/pki/pki\.md) Implementation of the public key cipher - - - [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md) Manage a plugin - - - [png](tcllib/files/modules/png/png\.md) PNG querying and manipulation of meta data - - - [pop3](tcllib/files/modules/pop3/pop3\.md) Tcl client for POP3 email protocol - - - [pop3d](tcllib/files/modules/pop3d/pop3d\.md) Tcl POP3 server implementation - - - [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) Simple mailbox database for pop3d - - - [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) Simple user database for pop3d - - - [practcl](tcllib/files/modules/practcl/practcl\.md) The Practcl Module - - - [processman](tcllib/files/modules/processman/processman\.md) Tool for automating the period callback of commands - - - [profiler](tcllib/files/modules/profiler/profiler\.md) Tcl source code profiler - - - [pt](tcllib/files/apps/pt\.md) Parser Tools Application - - - [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) Abstract Syntax Tree Serialization - - - [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) C/PARAM, Canned configuration, Critcl - - - [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) C/PARAM, Canned configuration, TEA - - - [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) The JSON Grammar Exchange Format - - - [pt::param](tcllib/files/modules/pt/pt\_param\.md) PackRat Machine Specification - - - [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) Parsing Expression Serialization - - - [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) Parsing Expression Utilities - - - [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) Parsing Expression Grammar Serialization - - - [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) PEG Storage - - - [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) PEG Storage\. Canned PEG grammar specification - - - [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) PEG Export - - - [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) PEG Export Plugin\. Write CONTAINER format - - - [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) PEG Export Plugin\. Write JSON format - - - [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) PEG Export Plugin\. Write PEG format - - - [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) PEG Conversion\. From CONTAINER format - - - [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) PEG Conversion\. Read JSON format - - - [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) PEG Conversion\. Read PEG format - - - [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) PEG Import - - - [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) PEG Import Plugin\. From CONTAINER format - - - [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) PEG Import Plugin\. Read JSON format - - - [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) PEG Import Plugin\. Read PEG format - - - [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) Interpreter for parsing expression grammars - - - [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) PEG Conversion\. Write CONTAINER format - - - [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) PEG Conversion\. Write CPARAM format - - - [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) PEG Conversion\. Write JSON format - - - [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) PEG Conversion\. Write PARAM format - - - [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) PEG Conversion\. Write PEG format - - - [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) PEG Conversion\. Write TCLPARAM format - - - [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) PEG Language Tutorial - - - [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) Introduction to Parsing Expression Grammars - - - [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) Parser Generator - - - [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) Parsing Runtime Support, PARAM based - - - [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) Tcl/PARAM, Canned configuration, NX - - - [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) Tcl/PARAM, Canned configuration, Snit - - - [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) Tcl/PARAM, Canned configuration, Tcloo - - - [pt::util](tcllib/files/modules/pt/pt\_util\.md) General utilities - - - [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) Parser Tools Export API - - - [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) Parser Tools Import API - - - [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) Introduction to Parser Tools - - - [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) Parser Tools PEG Parser - - - [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) Parser API - - - [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) Parser Tools PE Grammar Utility Operations - - - [rc4](tcllib/files/modules/rc4/rc4\.md) Implementation of the RC4 stream cipher - - - [rcs](tcllib/files/modules/rcs/rcs\.md) RCS low level utilities - - - [report](tcllib/files/modules/report/report\.md) Create and manipulate report objects - - - [rest](tcllib/files/modules/rest/rest\.md) define REST web APIs and call them inline or asychronously - - - [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) RIPEMD\-128 Message\-Digest Algorithm - - - [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) RIPEMD\-160 Message\-Digest Algorithm - - - [S3](tcllib/files/modules/amazon\-s3/S3\.md) Amazon S3 Web Service Interface - - - [SASL](tcllib/files/modules/sasl/sasl\.md) Implementation of SASL mechanisms for Tcl - - - [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) Implementation of SASL NTLM mechanism for Tcl - - - [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) Implementation of SASL SCRAM mechanism for Tcl - - - [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md) Implementation of SASL NTLM mechanism for Tcl - - - [sha1](tcllib/files/modules/sha1/sha1\.md) SHA1 Message\-Digest Algorithm - - - [sha256](tcllib/files/modules/sha1/sha256\.md) SHA256 Message\-Digest Algorithm - - - [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) Simulated annealing - - - [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) Monte Carlo simulations - - - [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md) Pseudo\-random number generators - - - [smtp](tcllib/files/modules/mime/smtp\.md) Client\-side tcl implementation of the smtp protocol - - - [smtpd](tcllib/files/modules/smtpd/smtpd\.md) Tcl SMTP server implementation - - - [snit](tcllib/files/modules/snit/snit\.md) Snit's Not Incr Tcl - - - [snitfaq](tcllib/files/modules/snit/snitfaq\.md) Snit Frequently Asked Questions - - - [soundex](tcllib/files/modules/soundex/soundex\.md) Soundex - - - [stooop](tcllib/files/modules/stooop/stooop\.md) Object oriented extension\. - - - [string::token](tcllib/files/modules/string/token\.md) Regex based iterative lexing - - - [string::token::shell](tcllib/files/modules/string/token\_shell\.md) Parsing of shell command line - - - [stringprep](tcllib/files/modules/stringprep/stringprep\.md) Implementation of stringprep - - - [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) stringprep data tables, generated, internal - - - [struct::disjointset](tcllib/files/modules/struct/disjointset\.md) Disjoint set data structure - - - [struct::graph](tcllib/files/modules/struct/graph\.md) Create and manipulate directed graph objects - - - [struct::graph::op](tcllib/files/modules/struct/graphops\.md) Operation for \(un\)directed graph objects - - - [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) Create and manipulate directed graph objects - - - [struct::list](tcllib/files/modules/struct/struct\_list\.md) Procedures for manipulating lists - - - [struct::map](tcllib/files/modules/struct/struct\_map\.md) Manage key/value maps - - - [struct::matrix](tcllib/files/modules/struct/matrix\.md) Create and manipulate matrix objects - - - [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) Create and manipulate matrix objects - - - [struct::pool](tcllib/files/modules/struct/pool\.md) Create and manipulate pool objects \(of discrete items\) - - - [struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) Create and manipulate prioqueue objects - - - [struct::queue](tcllib/files/modules/struct/queue\.md) Create and manipulate queue objects - - - [struct::record](tcllib/files/modules/struct/record\.md) Define and create records \(similar to 'C' structures\) - - - [struct::set](tcllib/files/modules/struct/struct\_set\.md) Procedures for manipulating sets - - - [struct::skiplist](tcllib/files/modules/struct/skiplist\.md) Create and manipulate skiplists - - - [struct::stack](tcllib/files/modules/struct/stack\.md) Create and manipulate stack objects - - - [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) Create and manipulate tree objects - - - [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) Create and manipulate tree objects - - - [sum](tcllib/files/modules/crc/sum\.md) Calculate a sum\(1\) compatible checksum - - - [switched](tcllib/files/modules/stooop/switched\.md) switch/option management\. - - - [tar](tcllib/files/modules/tar/tar\.md) Tar file creation, extraction & manipulation - - - [tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) Concatenation channel - - - [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) Basic reflected/virtual channel support - - - [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) Event support for reflected/virtual channels - - - [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) Facade channel - - - [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) In\-memory fifo channel - - - [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) In\-memory interconnected fifo channels - - - [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) In\-memory channel, half of a fifo2 - - - [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) In\-memory channel - - - [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) Null channel - - - [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) Null/Zero channel combination - - - [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) Random channel - - - [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) Standard I/O, unification of stdin and stdout - - - [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) Read\-only in\-memory channel - - - [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) Textwindow channel - - - [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) In\-memory channel using variable for storage - - - [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) Zero channel - - - [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) Utilities for random channels - - - [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) Adler32 transformation - - - [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) Base64 encoding transformation - - - [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) Basic reflected/virtual channel transform support - - - [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) Counter transformation - - - [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) Crc32 transformation - - - [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) Hexadecimal encoding transformation - - - [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) Identity transformation - - - [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) limiting input - - - [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) Observer transformation, stream copy - - - [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) Encryption via one\-time pad - - - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption - - - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal - - - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression - - - [tcl\_community\_communication](tcllib/files/devdoc/tcl\_community\_communication\.md) Tcl Community \- Kind Communication - - - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers - - - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers - - - [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor - - - [tcllib\_devguide](tcllib/files/devdoc/tcllib\_devguide\.md) Tcllib \- The Developer's Guide - - - [tcllib\_install\_guide](tcllib/files/devdoc/tcllib\_installer\.md) Tcllib \- The Installer's Guide - - - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation - - - [tcllib\_license](tcllib/files/devdoc/tcllib\_license\.md) Tcllib \- License - - - [tcllib\_releasemgr](tcllib/files/devdoc/tcllib\_releasemgr\.md) Tcllib \- The Release Manager's Guide - - - [tcllib\_sources](tcllib/files/devdoc/tcllib\_sources\.md) Tcllib \- How To Get The Sources - - - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager - - - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual - - - [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual - - - [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md) TEPAM procedure, reference manual - - - [term](tcllib/files/modules/term/term\.md) General terminal control - - - [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) Helper for control sequences - - - [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) ANSI attribute sequences - - - [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) ANSI control sequences - - - [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) Macro sequences - - - [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) Control operations and queries - - - [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) Output of ANSI control sequences to terminals - - - [term::interact::menu](tcllib/files/modules/term/imenu\.md) Terminal widget, menu - - - [term::interact::pager](tcllib/files/modules/term/ipager\.md) Terminal widget, paging - - - [term::receive](tcllib/files/modules/term/receive\.md) General input from terminals - - - [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) Keyboard dispatch from terminals - - - [term::send](tcllib/files/modules/term/term\_send\.md) General output to terminals - - - [textutil](tcllib/files/modules/textutil/textutil\.md) Procedures to manipulate texts and strings\. - - - [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) Procedures to adjust, indent, and undent paragraphs - - - [textutil::expander](tcllib/files/modules/textutil/expander\.md) Procedures to process templates and expand text\. - - - [textutil::patch](tcllib/files/modules/textutil/patch\.md) Application of uni\-diff patches to directory trees - - - [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) Procedures to repeat strings\. - - - [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) Procedures to split texts - - - [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) Procedures to manipulate texts and strings\. - - - [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) Procedures to \(un\)tabify strings - - - [textutil::trim](tcllib/files/modules/textutil/trim\.md) Procedures to trim strings - - - [throw](tcllib/files/modules/try/tcllib\_throw\.md) throw \- Throw an error exception with a message - - - [tie](tcllib/files/modules/tie/tie\_std\.md) Array persistence, standard data sources - - - [tie](tcllib/files/modules/tie/tie\.md) Array persistence - - - [tiff](tcllib/files/modules/tiff/tiff\.md) TIFF reading, writing, and querying and manipulation of meta data - - - [tool](tcllib/files/modules/tool/tool\.md) TclOO Library \(TOOL\) Framework - - - [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md) Dictionary Tools - - - [transfer::connect](tcllib/files/modules/transfer/connect\.md) Connection setup - - - [transfer::copy](tcllib/files/modules/transfer/copyops\.md) Data transfer foundation - - - [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) Queued transfers - - - [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) Data destination - - - [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) Data source - - - [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) Data source - - - [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md) Data source - - - [treeql](tcllib/files/modules/treeql/treeql\.md) Query tree objects - - - [try](tcllib/files/modules/try/tcllib\_try\.md) try \- Trap and process errors and exceptions - - - [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md) UDP Peer\-to\-Peer cluster - - - [uevent](tcllib/files/modules/uev/uevent\.md) User events - - - [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time - - - [unicode](tcllib/files/modules/stringprep/unicode\.md) Implementation of Unicode normalization - - - [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md) unicode data tables, generated, internal - - - [units](tcllib/files/modules/units/units\.md) unit conversion - - - [uri](tcllib/files/modules/uri/uri\.md) URI utilities - - - [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md) URI utilities, URN scheme - - - [uuencode](tcllib/files/modules/base64/uuencode\.md) UU\-encode/decode binary data - - - [uuid](tcllib/files/modules/uuid/uuid\.md) UUID generation and comparison - - - [valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) Validation, common code - - - [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) Validation for AMEX creditcard number - - - [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) Validation for Discover creditcard number - - - [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) Validation for Mastercard creditcard number - - - [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) Validation for VISA creditcard number - - - [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) Validation for EAN13 - - - [valtype::iban](tcllib/files/modules/valtype/iban\.md) Validation for IBAN - - - [valtype::imei](tcllib/files/modules/valtype/imei\.md) Validation for IMEI - - - [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) Validation for ISBN - - - [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) Validation for plain number with a LUHN checkdigit - - - [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) Validation for plain number with a LUHN5 checkdigit - - - [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) Validation for USNPI - - - [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md) Validation for plain number with a VERHOEFF checkdigit - - - [websocket](tcllib/files/modules/websocket/websocket\.md) Tcl implementation of the websocket protocol - - - [wip](tcllib/files/modules/wip/wip\.md) Word Interpreter - - - [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md) eXtremely Simple Xml Parser - - - [yaml](tcllib/files/modules/yaml/yaml\.md) YAML Format Encoder/Decoder - - - [yencode](tcllib/files/modules/base64/yencode\.md) Y\-encode/decode binary data - - - [zipfile::decode](tcllib/files/modules/zip/decode\.md) Access to zip archives - - - [zipfile::encode](tcllib/files/modules/zip/encode\.md) Generation of zip archives - - - [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md) Build a zip archive DELETED embedded/md/toc.md Index: embedded/md/toc.md ================================================================== --- embedded/md/toc.md +++ embedded/md/toc.md @@ -1,2068 +0,0 @@ - -[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') - -# Table Of Contents \-\- - - - [By Categories]() - - * [Argument entry form, mega widget]() - - + [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual - - * [Benchmark tools]() - - + [bench](tcllib/files/modules/bench/bench\.md) bench \- Processing benchmark suites - - + [bench::in](tcllib/files/modules/bench/bench\_read\.md) bench::in \- Reading benchmark results - - + [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) bench::out::csv \- Formatting benchmark results as CSV - - + [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) bench::out::text \- Formatting benchmark results as human readable text - - + [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) bench introduction - - + [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) bench language introduction - - + [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) bench language specification - - * [CGI programming]() - - + [html](tcllib/files/modules/html/html\.md) Procedures to generate HTML structures - - + [javascript](tcllib/files/modules/javascript/javascript\.md) Procedures to generate HTML and Java Script structures\. - - + [json](tcllib/files/modules/json/json\.md) JSON parser - - + [json::write](tcllib/files/modules/json/json\_write\.md) JSON generation - - + [ncgi](tcllib/files/modules/ncgi/ncgi\.md) Procedures to manipulate CGI values\. - - * [Channels]() - - + [tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) Concatenation channel - - + [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) Basic reflected/virtual channel support - - + [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) Event support for reflected/virtual channels - - + [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) Facade channel - - + [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) In\-memory fifo channel - - + [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) In\-memory interconnected fifo channels - - + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) In\-memory channel, half of a fifo2 - - + [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) In\-memory channel - - + [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) Null channel - - + [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) Null/Zero channel combination - - + [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) Random channel - - + [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) Standard I/O, unification of stdin and stdout - - + [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) Read\-only in\-memory channel - - + [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) Textwindow channel - - + [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) In\-memory channel using variable for storage - - + [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) Zero channel - - + [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) Utilities for random channels - - + [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) Adler32 transformation - - + [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) Base64 encoding transformation - - + [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) Basic reflected/virtual channel transform support - - + [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) Counter transformation - - + [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) Crc32 transformation - - + [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) Hexadecimal encoding transformation - - + [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) Identity transformation - - + [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) limiting input - - + [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) Observer transformation, stream copy - - + [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) Encryption via one\-time pad - - + [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption - - + [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal - - + [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression - - * [Coroutine]() - - + [coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) Coroutine based event and IO handling - - + [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) Automatic event and IO coroutine awareness - - * [Data structures]() - - + [counter](tcllib/files/modules/counter/counter\.md) Procedures for counters and histograms - - + [report](tcllib/files/modules/report/report\.md) Create and manipulate report objects - - + [struct::disjointset](tcllib/files/modules/struct/disjointset\.md) Disjoint set data structure - - + [struct::graph](tcllib/files/modules/struct/graph\.md) Create and manipulate directed graph objects - - + [struct::graph::op](tcllib/files/modules/struct/graphops\.md) Operation for \(un\)directed graph objects - - + [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) Create and manipulate directed graph objects - - + [struct::list](tcllib/files/modules/struct/struct\_list\.md) Procedures for manipulating lists - - + [struct::matrix](tcllib/files/modules/struct/matrix\.md) Create and manipulate matrix objects - - + [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) Create and manipulate matrix objects - - + [struct::pool](tcllib/files/modules/struct/pool\.md) Create and manipulate pool objects \(of discrete items\) - - + [struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) Create and manipulate prioqueue objects - - + [struct::queue](tcllib/files/modules/struct/queue\.md) Create and manipulate queue objects - - + [struct::record](tcllib/files/modules/struct/record\.md) Define and create records \(similar to 'C' structures\) - - + [struct::set](tcllib/files/modules/struct/struct\_set\.md) Procedures for manipulating sets - - + [struct::skiplist](tcllib/files/modules/struct/skiplist\.md) Create and manipulate skiplists - - + [struct::stack](tcllib/files/modules/struct/stack\.md) Create and manipulate stack objects - - + [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) Create and manipulate tree objects - - + [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) Create and manipulate tree objects - - + [treeql](tcllib/files/modules/treeql/treeql\.md) Query tree objects - - * [debugging, tracing, and logging]() - - + [debug](tcllib/files/modules/debug/debug\.md) debug narrative \- core - - + [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) debug narrative \- caller - - + [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) debug narrative \- heartbeat - - + [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) debug narrative \- timestamping - - * [Documentation tools]() - - + [docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) docidx introduction - - + [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) docidx language command reference - - + [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) docidx language faq - - + [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) docidx language introduction - - + [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) docidx language syntax - - + [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) docidx plugin API reference - - + [docstrip](tcllib/files/modules/docstrip/docstrip\.md) Docstrip style source code extraction - - + [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) Docstrip\-related utilities - - + [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) doctoc introduction - - + [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) doctoc language command reference - - + [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) doctoc language faq - - + [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) doctoc language introduction - - + [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) doctoc language syntax - - + [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) doctoc plugin API reference - - + [doctools](tcllib/files/modules/doctools/doctools\.md) doctools \- Processing documents - - + [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) DocTools \- Keyword indices - - + [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) DocTools \- Tables of Contents - - + [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) Processing text in Emacs ChangeLog format - - + [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) Processing text in 'cvs log' format - - + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) Default CSS style for HTML export plugins - - + [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) Holding keyword indices - - + [doctools::idx](tcllib/files/modules/doctools/docidx\.md) docidx \- Processing indices - - + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) Exporting keyword indices - - + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) Importing keyword indices - - + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) Parsing text in docidx format - - + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) Docidx serialization utilities - - + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) Message catalog management for the various document parsers - - + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) Message catalog for the docidx parser \(C\) - - + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) Message catalog for the docidx parser \(DE\) - - + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) Message catalog for the docidx parser \(EN\) - - + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) Message catalog for the docidx parser \(FR\) - - + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) Message catalog for the doctoc parser \(C\) - - + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) Message catalog for the doctoc parser \(DE\) - - + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) Message catalog for the doctoc parser \(EN\) - - + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) Message catalog for the doctoc parser \(FR\) - - + [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) Default CSS style for NROFF export plugins - - + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) Processing text in 'subst \-novariables' format - - + [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) Holding tables of contents - - + [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) doctoc \- Processing tables of contents - - + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) Exporting tables of contents - - + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) Importing keyword indices - - + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) Parsing text in doctoc format - - + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) Doctoc serialization utilities - - + [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) doctools introduction - - + [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) doctools language command reference - - + [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) doctools language faq - - + [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) doctools language introduction - - + [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) doctools language syntax - - + [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) doctools plugin API reference - - + [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) Lightweight DocTools Markup Processor - - + [dtplite](tcllib/files/apps/dtplite\.md) Lightweight DocTools Markup Processor - - + [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) Markup processor - - + [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor - - + [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual - - + [textutil::expander](tcllib/files/modules/textutil/expander\.md) Procedures to process templates and expand text\. - - * [File]() - - + [zipfile::decode](tcllib/files/modules/zip/decode\.md) Access to zip archives - - + [zipfile::encode](tcllib/files/modules/zip/encode\.md) Generation of zip archives - - + [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md) Build a zip archive - - * [File formats]() - - + [gpx](tcllib/files/modules/gpx/gpx\.md) Extracts waypoints, tracks and routes from GPX files - - + [jpeg](tcllib/files/modules/jpeg/jpeg\.md) JPEG querying and manipulation of meta data - - + [png](tcllib/files/modules/png/png\.md) PNG querying and manipulation of meta data - - + [tar](tcllib/files/modules/tar/tar\.md) Tar file creation, extraction & manipulation - - + [tiff](tcllib/files/modules/tiff/tiff\.md) TIFF reading, writing, and querying and manipulation of meta data - - * [Grammars and finite automata]() - - + [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) Aycock\-Horspool\-Earley parser generator for Tcl - - + [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) Create and manipulate finite automatons - - + [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) Create and use deterministic acceptors - - + [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) Execute deterministic finite automatons - - + [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) Operations on finite automatons - - + [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) Virtual machine implementation II for parsing token streams - - + [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) ME virtual machine state manipulation - - + [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) ME assembler - - + [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) Virtual machine implementation I for parsing token streams - - + [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) AST utilities - - + [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md) Various representations of ASTs - - + [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) Introduction to virtual machines for parsing token streams - - + [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) Virtual machine for parsing token streams - - + [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) Create and manipulate parsing expression grammars - - + [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) Interpreter for parsing expression grammars - - * [Hashes, checksums, and encryption]() - - + [aes](tcllib/files/modules/aes/aes\.md) Implementation of the AES block cipher - - + [blowfish](tcllib/files/modules/blowfish/blowfish\.md) Implementation of the Blowfish block cipher - - + [cksum](tcllib/files/modules/crc/cksum\.md) Calculate a cksum\(1\) compatible checksum - - + [crc16](tcllib/files/modules/crc/crc16\.md) Perform a 16bit Cyclic Redundancy Check - - + [crc32](tcllib/files/modules/crc/crc32\.md) Perform a 32bit Cyclic Redundancy Check - - + [des](tcllib/files/modules/des/des\.md) Implementation of the DES and triple\-DES ciphers - - + [md4](tcllib/files/modules/md4/md4\.md) MD4 Message\-Digest Algorithm - - + [md5](tcllib/files/modules/md5/md5\.md) MD5 Message\-Digest Algorithm - - + [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) MD5\-based password encryption - - + [otp](tcllib/files/modules/otp/otp\.md) One\-Time Passwords - - + [pki](tcllib/files/modules/pki/pki\.md) Implementation of the public key cipher - - + [rc4](tcllib/files/modules/rc4/rc4\.md) Implementation of the RC4 stream cipher - - + [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) RIPEMD\-128 Message\-Digest Algorithm - - + [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) RIPEMD\-160 Message\-Digest Algorithm - - + [sha1](tcllib/files/modules/sha1/sha1\.md) SHA1 Message\-Digest Algorithm - - + [sha256](tcllib/files/modules/sha1/sha256\.md) SHA256 Message\-Digest Algorithm - - + [soundex](tcllib/files/modules/soundex/soundex\.md) Soundex - - + [sum](tcllib/files/modules/crc/sum\.md) Calculate a sum\(1\) compatible checksum - - + [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers - - + [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers - - + [uuid](tcllib/files/modules/uuid/uuid\.md) UUID generation and comparison - - * [Mathematics]() - - + [math](tcllib/files/modules/math/math\.md) Tcl Math Library - - + [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) Arbitrary precision floating\-point numbers - - + [math::bignum](tcllib/files/modules/math/bignum\.md) Arbitrary precision integer numbers - - + [math::calculus](tcllib/files/modules/math/calculus\.md) Integration and ordinary differential equations - - + [math::calculus::romberg](tcllib/files/modules/math/romberg\.md) Romberg integration - - + [math::changepoint](tcllib/files/modules/math/changepoint\.md) Change point detection methods - - + [math::combinatorics](tcllib/files/modules/math/combinatorics\.md) Combinatorial functions in the Tcl Math Library - - + [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) Straightforward complex number package - - + [math::constants](tcllib/files/modules/math/constants\.md) Mathematical and numerical constants - - + [math::decimal](tcllib/files/modules/math/decimal\.md) General decimal arithmetic - - + [math::exact](tcllib/files/modules/math/exact\.md) Exact Real Arithmetic - - + [math::filters](tcllib/files/modules/math/filtergen\.md) Digital filters - - + [math::fourier](tcllib/files/modules/math/fourier\.md) Discrete and fast fourier transforms - - + [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) Fuzzy comparison of floating\-point numbers - - + [math::geometry](tcllib/files/modules/math/math\_geometry\.md) Geometrical computations - - + [math::interpolate](tcllib/files/modules/math/interpolate\.md) Interpolation routines - - + [math::linearalgebra](tcllib/files/modules/math/linalg\.md) Linear Algebra - - + [math::numtheory](tcllib/files/modules/math/numtheory\.md) Number Theory - - + [math::optimize](tcllib/files/modules/math/optimize\.md) Optimisation routines - - + [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis - - + [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions - - + [math::probopt](tcllib/files/modules/math/probopt\.md) Probabilistic optimisation methods - - + [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) Quasi\-random points for integration and Monte Carlo type methods - - + [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) Polynomial functions - - + [math::roman](tcllib/files/modules/math/roman\.md) Tools for creating and manipulating roman numerals - - + [math::special](tcllib/files/modules/math/special\.md) Special mathematical functions - - + [math::statistics](tcllib/files/modules/math/statistics\.md) Basic statistical functions and procedures - - + [math::trig](tcllib/files/modules/math/trig\.md) Trigonometric anf hyperbolic functions - - + [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) Simulated annealing - - + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) Monte Carlo simulations - - + [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md) Pseudo\-random number generators - - * [Networking]() - - + [asn](tcllib/files/modules/asn/asn\.md) ASN\.1 BER encoder/decoder - - + [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication - - + [bee](tcllib/files/modules/bee/bee\.md) BitTorrent Serialization Format Encoder/Decoder - - + [dns](tcllib/files/modules/dns/tcllib\_dns\.md) Tcl Domain Name Service Client - - + [ftp](tcllib/files/modules/ftp/ftp\.md) Client\-side tcl implementation of the ftp protocol - - + [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) Uri handler for ftp urls - - + [ftpd](tcllib/files/modules/ftpd/ftpd\.md) Tcl FTP server implementation - - + [httpd](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - - + [ident](tcllib/files/modules/ident/ident\.md) Ident protocol client - - + [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - - + [irc](tcllib/files/modules/irc/irc\.md) Create IRC connection and interface\. - - + [ldap](tcllib/files/modules/ldap/ldap\.md) LDAP client - - + [ldapx](tcllib/files/modules/ldap/ldapx\.md) LDAP extended object interface - - + [nameserv](tcllib/files/modules/nns/nns\_client\.md) Name service facility, Client - - + [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) Name service facility, Client Extension - - + [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) Name service facility, shared definitions - - + [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) Name service facility, client/server protocol - - + [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) Name service facility, Server - - + [nmea](tcllib/files/modules/nmea/nmea\.md) Process NMEA data - - + [nns](tcllib/files/apps/nns\.md) Name service facility, Commandline Client Application - - + [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) Name service facility, introduction - - + [nnsd](tcllib/files/apps/nnsd\.md) Name service facility, Commandline Server Application - - + [nnslog](tcllib/files/apps/nnslog\.md) Name service facility, Commandline Logging Client Application - - + [nntp](tcllib/files/modules/nntp/nntp\.md) Tcl client for the NNTP protocol - - + [ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md) Tcl Time Service Client - - + [oauth](tcllib/files/modules/oauth/oauth\.md) oauth API base signature - - + [picoirc](tcllib/files/modules/irc/picoirc\.md) Small and simple embeddable IRC client\. - - + [pop3](tcllib/files/modules/pop3/pop3\.md) Tcl client for POP3 email protocol - - + [pop3d](tcllib/files/modules/pop3d/pop3d\.md) Tcl POP3 server implementation - - + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) Simple mailbox database for pop3d - - + [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) Simple user database for pop3d - - + [S3](tcllib/files/modules/amazon\-s3/S3\.md) Amazon S3 Web Service Interface - - + [SASL](tcllib/files/modules/sasl/sasl\.md) Implementation of SASL mechanisms for Tcl - - + [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) Implementation of SASL NTLM mechanism for Tcl - - + [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) Implementation of SASL SCRAM mechanism for Tcl - - + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md) Implementation of SASL NTLM mechanism for Tcl - - + [smtp](tcllib/files/modules/mime/smtp\.md) Client\-side tcl implementation of the smtp protocol - - + [smtpd](tcllib/files/modules/smtpd/smtpd\.md) Tcl SMTP server implementation - - + [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation - - + [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md) UDP Peer\-to\-Peer cluster - - + [uri](tcllib/files/modules/uri/uri\.md) URI utilities - - + [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md) URI utilities, URN scheme - - + [websocket](tcllib/files/modules/websocket/websocket\.md) Tcl implementation of the websocket protocol - - * [Page Parser Generator]() - - + [page](tcllib/files/apps/page\.md) Parser Generator - - + [page\_intro](tcllib/files/modules/page/page\_intro\.md) page introduction - - + [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) page plugin manager - - + [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) page dataflow/treewalker utility - - + [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) page AST normalization, LEMON - - + [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) page AST normalization, PEG - - + [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) page PEG transformation utilities - - + [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) page character quoting utilities - - * [Parsing and Grammars]() - - + [pt](tcllib/files/apps/pt\.md) Parser Tools Application - - + [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) Abstract Syntax Tree Serialization - - + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) C/PARAM, Canned configuration, Critcl - - + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) C/PARAM, Canned configuration, TEA - - + [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) The JSON Grammar Exchange Format - - + [pt::param](tcllib/files/modules/pt/pt\_param\.md) PackRat Machine Specification - - + [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) Parsing Expression Serialization - - + [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) Parsing Expression Utilities - - + [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) Parsing Expression Grammar Serialization - - + [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) PEG Storage - - + [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) PEG Storage\. Canned PEG grammar specification - - + [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) PEG Export - - + [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) PEG Export Plugin\. Write CONTAINER format - - + [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) PEG Export Plugin\. Write JSON format - - + [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) PEG Export Plugin\. Write PEG format - - + [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) PEG Conversion\. From CONTAINER format - - + [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) PEG Conversion\. Read JSON format - - + [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) PEG Conversion\. Read PEG format - - + [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) PEG Import - - + [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) PEG Import Plugin\. From CONTAINER format - - + [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) PEG Import Plugin\. Read JSON format - - + [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) PEG Import Plugin\. Read PEG format - - + [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) Interpreter for parsing expression grammars - - + [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) PEG Conversion\. Write CONTAINER format - - + [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) PEG Conversion\. Write CPARAM format - - + [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) PEG Conversion\. Write JSON format - - + [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) PEG Conversion\. Write PARAM format - - + [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) PEG Conversion\. Write PEG format - - + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) PEG Conversion\. Write TCLPARAM format - - + [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) PEG Language Tutorial - - + [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) Introduction to Parsing Expression Grammars - - + [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) Parser Generator - - + [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) Parsing Runtime Support, PARAM based - - + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) Tcl/PARAM, Canned configuration, NX - - + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) Tcl/PARAM, Canned configuration, Snit - - + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) Tcl/PARAM, Canned configuration, Tcloo - - + [pt::util](tcllib/files/modules/pt/pt\_util\.md) General utilities - - + [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) Parser Tools Export API - - + [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) Parser Tools Import API - - + [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) Introduction to Parser Tools - - + [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) Parser Tools PEG Parser - - + [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) Parser API - - + [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) Parser Tools PE Grammar Utility Operations - - * [Procedures, arguments, parameters, options]() - - + [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager - - + [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md) TEPAM procedure, reference manual - - * [Programming tools]() - - + [clay](tcllib/files/modules/clay/clay\.md) A minimalist framework for large scale OO Projects - - + [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. - - + [comm](tcllib/files/modules/comm/comm\.md) A remote communication facility for Tcl \(8\.3 and later\) - - + [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) The comm wire protocol - - + [control](tcllib/files/modules/control/control\.md) Procedures for control flow structures\. - - + [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) Creation of comm delegates \(snit methods\) - - + [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) Creation of comm delegates \(procedures\) - - + [fileutil](tcllib/files/modules/fileutil/fileutil\.md) Procedures implementing some file utilities - - + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) Procedures implementing file\-type recognition - - + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) Runtime core for file type recognition engines written in pure Tcl - - + [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) Multi\-file operation, scatter/gather, standard object - - + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) Multi\-file operation, scatter/gather - - + [fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md) Iterative directory traversal - - + [hook](tcllib/files/modules/hook/hook\.md) Hooks - - + [interp](tcllib/files/modules/interp/tcllib\_interp\.md) Interp creation and aliasing - - + [log](tcllib/files/modules/log/log\.md) Procedures to log messages of libraries and applications\. - - + [logger](tcllib/files/modules/log/logger\.md) System to control logging of events\. - - + [logger::appender](tcllib/files/modules/log/loggerAppender\.md) Collection of predefined appenders for logger - - + [logger::utils](tcllib/files/modules/log/loggerUtils\.md) Utilities for logger - - + [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) One\-to\-many communication with sockets\. - - + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md) Manage a plugin - - + [profiler](tcllib/files/modules/profiler/profiler\.md) Tcl source code profiler - - + [snit](tcllib/files/modules/snit/snit\.md) Snit's Not Incr Tcl - - + [snitfaq](tcllib/files/modules/snit/snitfaq\.md) Snit Frequently Asked Questions - - + [stooop](tcllib/files/modules/stooop/stooop\.md) Object oriented extension\. - - + [switched](tcllib/files/modules/stooop/switched\.md) switch/option management\. - - + [tie](tcllib/files/modules/tie/tie\.md) Array persistence - - + [tie](tcllib/files/modules/tie/tie\_std\.md) Array persistence, standard data sources - - + [uevent](tcllib/files/modules/uev/uevent\.md) User events - - + [wip](tcllib/files/modules/wip/wip\.md) Word Interpreter - - * [System]() - - + [cron](tcllib/files/modules/cron/cron\.md) Tool for automating the period callback of commands - - + [nettool](tcllib/files/modules/nettool/nettool\.md) Tools for networked applications - - + [processman](tcllib/files/modules/processman/processman\.md) Tool for automating the period callback of commands - - * [TclOO]() - - + [oometa](tcllib/files/modules/oometa/oometa\.md) oo::meta A data registry for classess - - + [practcl](tcllib/files/modules/practcl/practcl\.md) The Practcl Module - - + [tool](tcllib/files/modules/tool/tool\.md) TclOO Library \(TOOL\) Framework - - * [Terminal control]() - - + [term](tcllib/files/modules/term/term\.md) General terminal control - - + [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) Helper for control sequences - - + [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) ANSI attribute sequences - - + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) ANSI control sequences - - + [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) Macro sequences - - + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) Control operations and queries - - + [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) Output of ANSI control sequences to terminals - - + [term::interact::menu](tcllib/files/modules/term/imenu\.md) Terminal widget, menu - - + [term::interact::pager](tcllib/files/modules/term/ipager\.md) Terminal widget, paging - - + [term::receive](tcllib/files/modules/term/receive\.md) General input from terminals - - + [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) Keyboard dispatch from terminals - - + [term::send](tcllib/files/modules/term/term\_send\.md) General output to terminals - - * [Text formatter plugin]() - - + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) docidx export plugin - - + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) HTML export plugin - - + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) JSON export plugin - - + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) nroff export plugin - - + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) plain text export plugin - - + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) wiki export plugin - - + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) docidx import plugin - - + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) JSON import plugin - - + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) doctoc export plugin - - + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) HTML export plugin - - + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) JSON export plugin - - + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) nroff export plugin - - + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) plain text export plugin - - + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) wiki export plugin - - + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) doctoc import plugin - - + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) JSON import plugin - - * [Text processing]() - - + [ascii85](tcllib/files/modules/base64/ascii85\.md) ascii85\-encode/decode binary data - - + [base32](tcllib/files/modules/base32/base32\.md) base32 standard encoding - - + [base32::core](tcllib/files/modules/base32/base32core\.md) Expanding basic base32 maps - - + [base32::hex](tcllib/files/modules/base32/base32hex\.md) base32 extended hex encoding - - + [base64](tcllib/files/modules/base64/base64\.md) base64\-encode/decode binary data - - + [bibtex](tcllib/files/modules/bibtex/bibtex\.md) Parse bibtex files - - + [clock\_iso8601](tcllib/files/modules/clock/iso8601\.md) Parsing ISO 8601 dates/times - - + [clock\_rfc2822](tcllib/files/modules/clock/rfc2822\.md) Parsing RFC 2822 dates/times - - + [csv](tcllib/files/modules/csv/csv\.md) Procedures to handle CSV data\. - - + [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) Procedures to parse HTML strings - - + [inifile](tcllib/files/modules/inifile/ini\.md) Parsing of Windows INI files - - + [markdown](tcllib/files/modules/markdown/markdown\.md) Converts Markdown text to HTML - - + [mime](tcllib/files/modules/mime/mime\.md) Manipulation of MIME body parts - - + [rcs](tcllib/files/modules/rcs/rcs\.md) RCS low level utilities - - + [string::token](tcllib/files/modules/string/token\.md) Regex based iterative lexing - - + [string::token::shell](tcllib/files/modules/string/token\_shell\.md) Parsing of shell command line - - + [textutil](tcllib/files/modules/textutil/textutil\.md) Procedures to manipulate texts and strings\. - - + [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) Procedures to adjust, indent, and undent paragraphs - - + [textutil::patch](tcllib/files/modules/textutil/patch\.md) Application of uni\-diff patches to directory trees - - + [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) Procedures to repeat strings\. - - + [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) Procedures to split texts - - + [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) Procedures to manipulate texts and strings\. - - + [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) Procedures to \(un\)tabify strings - - + [textutil::trim](tcllib/files/modules/textutil/trim\.md) Procedures to trim strings - - + [uuencode](tcllib/files/modules/base64/uuencode\.md) UU\-encode/decode binary data - - + [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md) eXtremely Simple Xml Parser - - + [yencode](tcllib/files/modules/base64/yencode\.md) Y\-encode/decode binary data - - * [Transfer module]() - - + [transfer::connect](tcllib/files/modules/transfer/connect\.md) Connection setup - - + [transfer::copy](tcllib/files/modules/transfer/copyops\.md) Data transfer foundation - - + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) Queued transfers - - + [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) Data destination - - + [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) Data source - - + [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) Data source - - + [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md) Data source - - * [Unfiled]() - - + [cache::async](tcllib/files/modules/cache/async\.md) Asynchronous in\-memory cache - - + [fileutil::paths](tcllib/files/modules/fileutil/paths\.md) Manage search path pools - - + [generator](tcllib/files/modules/generator/generator\.md) Procedures for creating and using generators\. - - + [huddle](tcllib/files/modules/yaml/huddle\.md) Create and manipulate huddle object - - + [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) Resolving geographical names with a Nominatim service - - + [map::slippy](tcllib/files/modules/map/map\_slippy\.md) Common code for slippy based map packages - - + [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) Management of a tile cache in the local filesystem - - + [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) Accessing a server providing tiles for slippy\-based maps - - + [mapproj](tcllib/files/modules/mapproj/mapproj\.md) Map projection routines - - + [math::calculus::symdiff](tcllib/files/modules/math/symdiff\.md) Symbolic differentiation for Tcl - - + [math::machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - - + [namespacex](tcllib/files/modules/namespacex/namespacex\.md) Namespace utility commands - - + [rest](tcllib/files/modules/rest/rest\.md) define REST web APIs and call them inline or asychronously - - + [stringprep](tcllib/files/modules/stringprep/stringprep\.md) Implementation of stringprep - - + [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) stringprep data tables, generated, internal - - + [struct::map](tcllib/files/modules/struct/struct\_map\.md) Manage key/value maps - - + [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time - - + [unicode](tcllib/files/modules/stringprep/unicode\.md) Implementation of Unicode normalization - - + [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md) unicode data tables, generated, internal - - + [units](tcllib/files/modules/units/units\.md) unit conversion - - + [yaml](tcllib/files/modules/yaml/yaml\.md) YAML Format Encoder/Decoder - - * [Utilities]() - - + [dicttool](tcllib/files/modules/dicttool/dicttool\.md) Dictionary Tools - - * [Utility]() - - + [defer](tcllib/files/modules/defer/defer\.md) Defered execution - - + [lambda](tcllib/files/modules/lambda/lambda\.md) Utility commands for anonymous procedures - - + [lazyset](tcllib/files/modules/lazyset/lazyset\.md) Lazy evaluation - - + [oo::util](tcllib/files/modules/ooutil/ooutil\.md) Utility commands for TclOO - - + [oo::util](tcllib/files/modules/tool/meta\.md) Utility commands for TclOO - - + [throw](tcllib/files/modules/try/tcllib\_throw\.md) throw \- Throw an error exception with a message - - + [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md) Dictionary Tools - - + [try](tcllib/files/modules/try/tcllib\_try\.md) try \- Trap and process errors and exceptions - - * [Validation, Type checking]() - - + [valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) Validation, common code - - + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) Validation for AMEX creditcard number - - + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) Validation for Discover creditcard number - - + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) Validation for Mastercard creditcard number - - + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) Validation for VISA creditcard number - - + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) Validation for EAN13 - - + [valtype::iban](tcllib/files/modules/valtype/iban\.md) Validation for IBAN - - + [valtype::imei](tcllib/files/modules/valtype/imei\.md) Validation for IMEI - - + [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) Validation for ISBN - - + [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) Validation for plain number with a LUHN checkdigit - - + [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) Validation for plain number with a LUHN5 checkdigit - - + [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) Validation for USNPI - - + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md) Validation for plain number with a VERHOEFF checkdigit - - - [By Type]() - - * [Applications]() - - + [dtplite](tcllib/files/apps/dtplite\.md) Lightweight DocTools Markup Processor - - + [nns](tcllib/files/apps/nns\.md) Name service facility, Commandline Client Application - - + [nnsd](tcllib/files/apps/nnsd\.md) Name service facility, Commandline Server Application - - + [nnslog](tcllib/files/apps/nnslog\.md) Name service facility, Commandline Logging Client Application - - + [page](tcllib/files/apps/page\.md) Parser Generator - - + [pt](tcllib/files/apps/pt\.md) Parser Tools Application - - + [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor - - * [Modules]() - - + [aes]() - - - [aes](tcllib/files/modules/aes/aes\.md) Implementation of the AES block cipher - - + [amazon\-s3]() - - - [S3](tcllib/files/modules/amazon\-s3/S3\.md) Amazon S3 Web Service Interface - - - [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md) eXtremely Simple Xml Parser - - + [asn]() - - - [asn](tcllib/files/modules/asn/asn\.md) ASN\.1 BER encoder/decoder - - + [base32]() - - - [base32](tcllib/files/modules/base32/base32\.md) base32 standard encoding - - - [base32::core](tcllib/files/modules/base32/base32core\.md) Expanding basic base32 maps - - - [base32::hex](tcllib/files/modules/base32/base32hex\.md) base32 extended hex encoding - - + [base64]() - - - [ascii85](tcllib/files/modules/base64/ascii85\.md) ascii85\-encode/decode binary data - - - [base64](tcllib/files/modules/base64/base64\.md) base64\-encode/decode binary data - - - [uuencode](tcllib/files/modules/base64/uuencode\.md) UU\-encode/decode binary data - - - [yencode](tcllib/files/modules/base64/yencode\.md) Y\-encode/decode binary data - - + [bee]() - - - [bee](tcllib/files/modules/bee/bee\.md) BitTorrent Serialization Format Encoder/Decoder - - + [bench]() - - - [bench](tcllib/files/modules/bench/bench\.md) bench \- Processing benchmark suites - - - [bench::in](tcllib/files/modules/bench/bench\_read\.md) bench::in \- Reading benchmark results - - - [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) bench::out::csv \- Formatting benchmark results as CSV - - - [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) bench::out::text \- Formatting benchmark results as human readable text - - - [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) bench introduction - - - [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) bench language introduction - - - [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) bench language specification - - + [bibtex]() - - - [bibtex](tcllib/files/modules/bibtex/bibtex\.md) Parse bibtex files - - + [blowfish]() - - - [blowfish](tcllib/files/modules/blowfish/blowfish\.md) Implementation of the Blowfish block cipher - - + [cache]() - - - [cache::async](tcllib/files/modules/cache/async\.md) Asynchronous in\-memory cache - - + [clay]() - - - [clay](tcllib/files/modules/clay/clay\.md) A minimalist framework for large scale OO Projects - - + [clock]() - - - [clock\_iso8601](tcllib/files/modules/clock/iso8601\.md) Parsing ISO 8601 dates/times - - - [clock\_rfc2822](tcllib/files/modules/clock/rfc2822\.md) Parsing RFC 2822 dates/times - - + [cmdline]() - - - [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. - - + [comm]() - - - [comm](tcllib/files/modules/comm/comm\.md) A remote communication facility for Tcl \(8\.3 and later\) - - - [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) The comm wire protocol - - + [control]() - - - [control](tcllib/files/modules/control/control\.md) Procedures for control flow structures\. - - + [coroutine]() - - - [coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) Coroutine based event and IO handling - - - [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) Automatic event and IO coroutine awareness - - + [counter]() - - - [counter](tcllib/files/modules/counter/counter\.md) Procedures for counters and histograms - - + [crc]() - - - [cksum](tcllib/files/modules/crc/cksum\.md) Calculate a cksum\(1\) compatible checksum - - - [crc16](tcllib/files/modules/crc/crc16\.md) Perform a 16bit Cyclic Redundancy Check - - - [crc32](tcllib/files/modules/crc/crc32\.md) Perform a 32bit Cyclic Redundancy Check - - - [sum](tcllib/files/modules/crc/sum\.md) Calculate a sum\(1\) compatible checksum - - + [cron]() - - - [cron](tcllib/files/modules/cron/cron\.md) Tool for automating the period callback of commands - - + [csv]() - - - [csv](tcllib/files/modules/csv/csv\.md) Procedures to handle CSV data\. - - + [debug]() - - - [debug](tcllib/files/modules/debug/debug\.md) debug narrative \- core - - - [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) debug narrative \- caller - - - [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) debug narrative \- heartbeat - - - [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) debug narrative \- timestamping - - + [defer]() - - - [defer](tcllib/files/modules/defer/defer\.md) Defered execution - - + [des]() - - - [des](tcllib/files/modules/des/des\.md) Implementation of the DES and triple\-DES ciphers - - - [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers - - - [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers - - + [dicttool]() - - - [dicttool](tcllib/files/modules/dicttool/dicttool\.md) Dictionary Tools - - + [dns]() - - - [dns](tcllib/files/modules/dns/tcllib\_dns\.md) Tcl Domain Name Service Client - - - [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation - - + [docstrip]() - - - [docstrip](tcllib/files/modules/docstrip/docstrip\.md) Docstrip style source code extraction - - - [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) Docstrip\-related utilities - - + [doctools]() - - - [docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) docidx introduction - - - [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) docidx language command reference - - - [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) docidx language faq - - - [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) docidx language introduction - - - [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) docidx language syntax - - - [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) docidx plugin API reference - - - [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) doctoc introduction - - - [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) doctoc language command reference - - - [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) doctoc language faq - - - [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) doctoc language introduction - - - [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) doctoc language syntax - - - [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) doctoc plugin API reference - - - [doctools](tcllib/files/modules/doctools/doctools\.md) doctools \- Processing documents - - - [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) Processing text in Emacs ChangeLog format - - - [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) Processing text in 'cvs log' format - - - [doctools::idx](tcllib/files/modules/doctools/docidx\.md) docidx \- Processing indices - - - [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) doctoc \- Processing tables of contents - - - [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) doctools introduction - - - [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) doctools language command reference - - - [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) doctools language faq - - - [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) doctools language introduction - - - [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) doctools language syntax - - - [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) doctools plugin API reference - - - [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) Markup processor - - + [doctools2base]() - - - [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) Default CSS style for HTML export plugins - - - [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) Message catalog management for the various document parsers - - - [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) Default CSS style for NROFF export plugins - - - [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) Processing text in 'subst \-novariables' format - - + [doctools2idx]() - - - [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) DocTools \- Keyword indices - - - [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) Holding keyword indices - - - [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) Exporting keyword indices - - - [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) docidx export plugin - - - [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) HTML export plugin - - - [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) JSON export plugin - - - [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) nroff export plugin - - - [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) plain text export plugin - - - [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) wiki export plugin - - - [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) Importing keyword indices - - - [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) docidx import plugin - - - [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) JSON import plugin - - - [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) Parsing text in docidx format - - - [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) Docidx serialization utilities - - - [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) Message catalog for the docidx parser \(C\) - - - [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) Message catalog for the docidx parser \(DE\) - - - [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) Message catalog for the docidx parser \(EN\) - - - [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) Message catalog for the docidx parser \(FR\) - - + [doctools2toc]() - - - [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) DocTools \- Tables of Contents - - - [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) Message catalog for the doctoc parser \(C\) - - - [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) Message catalog for the doctoc parser \(DE\) - - - [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) Message catalog for the doctoc parser \(EN\) - - - [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) Message catalog for the doctoc parser \(FR\) - - - [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) Holding tables of contents - - - [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) Exporting tables of contents - - - [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) doctoc export plugin - - - [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) HTML export plugin - - - [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) JSON export plugin - - - [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) nroff export plugin - - - [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) plain text export plugin - - - [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) wiki export plugin - - - [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) Importing keyword indices - - - [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) doctoc import plugin - - - [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) JSON import plugin - - - [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) Parsing text in doctoc format - - - [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) Doctoc serialization utilities - - + [dtplite]() - - - [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) Lightweight DocTools Markup Processor - - + [fileutil]() - - - [fileutil](tcllib/files/modules/fileutil/fileutil\.md) Procedures implementing some file utilities - - - [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) Multi\-file operation, scatter/gather, standard object - - - [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) Multi\-file operation, scatter/gather - - - [fileutil::paths](tcllib/files/modules/fileutil/paths\.md) Manage search path pools - - - [fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md) Iterative directory traversal - - + [ftp]() - - - [ftp](tcllib/files/modules/ftp/ftp\.md) Client\-side tcl implementation of the ftp protocol - - - [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) Uri handler for ftp urls - - + [ftpd]() - - - [ftpd](tcllib/files/modules/ftpd/ftpd\.md) Tcl FTP server implementation - - + [fumagic]() - - - [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) Generator core for compiler of magic\(5\) files - - - [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) Generator core for compiler of magic\(5\) files - - - [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) Procedures implementing file\-type recognition - - - [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) Runtime core for file type recognition engines written in pure Tcl - - + [generator]() - - - [generator](tcllib/files/modules/generator/generator\.md) Procedures for creating and using generators\. - - + [gpx]() - - - [gpx](tcllib/files/modules/gpx/gpx\.md) Extracts waypoints, tracks and routes from GPX files - - + [grammar\_aycock]() - - - [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) Aycock\-Horspool\-Earley parser generator for Tcl - - + [grammar\_fa]() - - - [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) Create and manipulate finite automatons - - - [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) Create and use deterministic acceptors - - - [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) Execute deterministic finite automatons - - - [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) Operations on finite automatons - - + [grammar\_me]() - - - [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) Virtual machine implementation II for parsing token streams - - - [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) ME virtual machine state manipulation - - - [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) ME assembler - - - [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) Virtual machine implementation I for parsing token streams - - - [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) AST utilities - - - [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md) Various representations of ASTs - - - [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) Introduction to virtual machines for parsing token streams - - - [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) Virtual machine for parsing token streams - - + [grammar\_peg]() - - - [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) Create and manipulate parsing expression grammars - - - [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) Interpreter for parsing expression grammars - - + [hook]() - - - [hook](tcllib/files/modules/hook/hook\.md) Hooks - - + [html]() - - - [html](tcllib/files/modules/html/html\.md) Procedures to generate HTML structures - - + [htmlparse]() - - - [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) Procedures to parse HTML strings - - + [http]() - - - [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication - - + [httpd]() - - - [httpd](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - - + [ident]() - - - [ident](tcllib/files/modules/ident/ident\.md) Ident protocol client - - + [imap4]() - - - [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - - + [inifile]() - - - [inifile](tcllib/files/modules/inifile/ini\.md) Parsing of Windows INI files - - + [interp]() - - - [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) Creation of comm delegates \(snit methods\) - - - [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) Creation of comm delegates \(procedures\) - - - [interp](tcllib/files/modules/interp/tcllib\_interp\.md) Interp creation and aliasing - - + [irc]() - - - [irc](tcllib/files/modules/irc/irc\.md) Create IRC connection and interface\. - - - [picoirc](tcllib/files/modules/irc/picoirc\.md) Small and simple embeddable IRC client\. - - + [javascript]() - - - [javascript](tcllib/files/modules/javascript/javascript\.md) Procedures to generate HTML and Java Script structures\. - - + [jpeg]() - - - [jpeg](tcllib/files/modules/jpeg/jpeg\.md) JPEG querying and manipulation of meta data - - + [json]() - - - [json](tcllib/files/modules/json/json\.md) JSON parser - - - [json::write](tcllib/files/modules/json/json\_write\.md) JSON generation - - + [lambda]() - - - [lambda](tcllib/files/modules/lambda/lambda\.md) Utility commands for anonymous procedures - - + [lazyset]() - - - [lazyset](tcllib/files/modules/lazyset/lazyset\.md) Lazy evaluation - - + [ldap]() - - - [ldap](tcllib/files/modules/ldap/ldap\.md) LDAP client - - - [ldapx](tcllib/files/modules/ldap/ldapx\.md) LDAP extended object interface - - + [log]() - - - [log](tcllib/files/modules/log/log\.md) Procedures to log messages of libraries and applications\. - - - [logger](tcllib/files/modules/log/logger\.md) System to control logging of events\. - - - [logger::appender](tcllib/files/modules/log/loggerAppender\.md) Collection of predefined appenders for logger - - - [logger::utils](tcllib/files/modules/log/loggerUtils\.md) Utilities for logger - - + [map]() - - - [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) Resolving geographical names with a Nominatim service - - - [map::slippy](tcllib/files/modules/map/map\_slippy\.md) Common code for slippy based map packages - - - [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) Management of a tile cache in the local filesystem - - - [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) Accessing a server providing tiles for slippy\-based maps - - + [mapproj]() - - - [mapproj](tcllib/files/modules/mapproj/mapproj\.md) Map projection routines - - + [markdown]() - - - [markdown](tcllib/files/modules/markdown/markdown\.md) Converts Markdown text to HTML - - + [math]() - - - [math](tcllib/files/modules/math/math\.md) Tcl Math Library - - - [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) Arbitrary precision floating\-point numbers - - - [math::bignum](tcllib/files/modules/math/bignum\.md) Arbitrary precision integer numbers - - - [math::calculus](tcllib/files/modules/math/calculus\.md) Integration and ordinary differential equations - - - [math::calculus::romberg](tcllib/files/modules/math/romberg\.md) Romberg integration - - - [math::calculus::symdiff](tcllib/files/modules/math/symdiff\.md) Symbolic differentiation for Tcl - - - [math::changepoint](tcllib/files/modules/math/changepoint\.md) Change point detection methods - - - [math::combinatorics](tcllib/files/modules/math/combinatorics\.md) Combinatorial functions in the Tcl Math Library - - - [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) Straightforward complex number package - - - [math::constants](tcllib/files/modules/math/constants\.md) Mathematical and numerical constants - - - [math::decimal](tcllib/files/modules/math/decimal\.md) General decimal arithmetic - - - [math::exact](tcllib/files/modules/math/exact\.md) Exact Real Arithmetic - - - [math::filters](tcllib/files/modules/math/filtergen\.md) Digital filters - - - [math::fourier](tcllib/files/modules/math/fourier\.md) Discrete and fast fourier transforms - - - [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) Fuzzy comparison of floating\-point numbers - - - [math::geometry](tcllib/files/modules/math/math\_geometry\.md) Geometrical computations - - - [math::interpolate](tcllib/files/modules/math/interpolate\.md) Interpolation routines - - - [math::linearalgebra](tcllib/files/modules/math/linalg\.md) Linear Algebra - - - [math::machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - - - [math::numtheory](tcllib/files/modules/math/numtheory\.md) Number Theory - - - [math::optimize](tcllib/files/modules/math/optimize\.md) Optimisation routines - - - [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis - - - [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions - - - [math::probopt](tcllib/files/modules/math/probopt\.md) Probabilistic optimisation methods - - - [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) Quasi\-random points for integration and Monte Carlo type methods - - - [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) Polynomial functions - - - [math::roman](tcllib/files/modules/math/roman\.md) Tools for creating and manipulating roman numerals - - - [math::special](tcllib/files/modules/math/special\.md) Special mathematical functions - - - [math::statistics](tcllib/files/modules/math/statistics\.md) Basic statistical functions and procedures - - - [math::trig](tcllib/files/modules/math/trig\.md) Trigonometric anf hyperbolic functions - - + [md4]() - - - [md4](tcllib/files/modules/md4/md4\.md) MD4 Message\-Digest Algorithm - - + [md5]() - - - [md5](tcllib/files/modules/md5/md5\.md) MD5 Message\-Digest Algorithm - - + [md5crypt]() - - - [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) MD5\-based password encryption - - + [mime]() - - - [mime](tcllib/files/modules/mime/mime\.md) Manipulation of MIME body parts - - - [smtp](tcllib/files/modules/mime/smtp\.md) Client\-side tcl implementation of the smtp protocol - - + [multiplexer]() - - - [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) One\-to\-many communication with sockets\. - - + [namespacex]() - - - [namespacex](tcllib/files/modules/namespacex/namespacex\.md) Namespace utility commands - - + [ncgi]() - - - [ncgi](tcllib/files/modules/ncgi/ncgi\.md) Procedures to manipulate CGI values\. - - + [nettool]() - - - [nettool](tcllib/files/modules/nettool/nettool\.md) Tools for networked applications - - + [nmea]() - - - [nmea](tcllib/files/modules/nmea/nmea\.md) Process NMEA data - - + [nns]() - - - [nameserv](tcllib/files/modules/nns/nns\_client\.md) Name service facility, Client - - - [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) Name service facility, Client Extension - - - [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) Name service facility, shared definitions - - - [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) Name service facility, client/server protocol - - - [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) Name service facility, Server - - - [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) Name service facility, introduction - - + [nntp]() - - - [nntp](tcllib/files/modules/nntp/nntp\.md) Tcl client for the NNTP protocol - - + [ntp]() - - - [ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md) Tcl Time Service Client - - + [oauth]() - - - [oauth](tcllib/files/modules/oauth/oauth\.md) oauth API base signature - - + [oometa]() - - - [oometa](tcllib/files/modules/oometa/oometa\.md) oo::meta A data registry for classess - - + [ooutil]() - - - [oo::util](tcllib/files/modules/ooutil/ooutil\.md) Utility commands for TclOO - - + [otp]() - - - [otp](tcllib/files/modules/otp/otp\.md) One\-Time Passwords - - + [page]() - - - [page\_intro](tcllib/files/modules/page/page\_intro\.md) page introduction - - - [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) page plugin manager - - - [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) page dataflow/treewalker utility - - - [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) page AST normalization, LEMON - - - [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) page AST normalization, PEG - - - [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) page PEG transformation utilities - - - [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) page character quoting utilities - - + [pki]() - - - [pki](tcllib/files/modules/pki/pki\.md) Implementation of the public key cipher - - + [pluginmgr]() - - - [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md) Manage a plugin - - + [png]() - - - [png](tcllib/files/modules/png/png\.md) PNG querying and manipulation of meta data - - + [pop3]() - - - [pop3](tcllib/files/modules/pop3/pop3\.md) Tcl client for POP3 email protocol - - + [pop3d]() - - - [pop3d](tcllib/files/modules/pop3d/pop3d\.md) Tcl POP3 server implementation - - - [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) Simple mailbox database for pop3d - - - [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) Simple user database for pop3d - - + [practcl]() - - - [practcl](tcllib/files/modules/practcl/practcl\.md) The Practcl Module - - + [processman]() - - - [processman](tcllib/files/modules/processman/processman\.md) Tool for automating the period callback of commands - - + [profiler]() - - - [profiler](tcllib/files/modules/profiler/profiler\.md) Tcl source code profiler - - + [pt]() - - - [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) Abstract Syntax Tree Serialization - - - [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) C/PARAM, Canned configuration, Critcl - - - [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) C/PARAM, Canned configuration, TEA - - - [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) The JSON Grammar Exchange Format - - - [pt::param](tcllib/files/modules/pt/pt\_param\.md) PackRat Machine Specification - - - [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) Parsing Expression Serialization - - - [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) Parsing Expression Utilities - - - [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) Parsing Expression Grammar Serialization - - - [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) PEG Storage - - - [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) PEG Storage\. Canned PEG grammar specification - - - [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) PEG Export - - - [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) PEG Export Plugin\. Write CONTAINER format - - - [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) PEG Export Plugin\. Write JSON format - - - [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) PEG Export Plugin\. Write PEG format - - - [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) PEG Conversion\. From CONTAINER format - - - [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) PEG Conversion\. Read JSON format - - - [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) PEG Conversion\. Read PEG format - - - [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) PEG Import - - - [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) PEG Import Plugin\. From CONTAINER format - - - [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) PEG Import Plugin\. Read JSON format - - - [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) PEG Import Plugin\. Read PEG format - - - [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) Interpreter for parsing expression grammars - - - [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) PEG Conversion\. Write CONTAINER format - - - [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) PEG Conversion\. Write CPARAM format - - - [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) PEG Conversion\. Write JSON format - - - [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) PEG Conversion\. Write PARAM format - - - [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) PEG Conversion\. Write PEG format - - - [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) PEG Conversion\. Write TCLPARAM format - - - [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) PEG Language Tutorial - - - [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) Introduction to Parsing Expression Grammars - - - [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) Parser Generator - - - [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) Parsing Runtime Support, PARAM based - - - [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) Tcl/PARAM, Canned configuration, NX - - - [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) Tcl/PARAM, Canned configuration, Snit - - - [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) Tcl/PARAM, Canned configuration, Tcloo - - - [pt::util](tcllib/files/modules/pt/pt\_util\.md) General utilities - - - [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) Parser Tools Export API - - - [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) Parser Tools Import API - - - [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) Introduction to Parser Tools - - - [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) Parser Tools PEG Parser - - - [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) Parser API - - - [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) Parser Tools PE Grammar Utility Operations - - + [rc4]() - - - [rc4](tcllib/files/modules/rc4/rc4\.md) Implementation of the RC4 stream cipher - - + [rcs]() - - - [rcs](tcllib/files/modules/rcs/rcs\.md) RCS low level utilities - - + [report]() - - - [report](tcllib/files/modules/report/report\.md) Create and manipulate report objects - - + [rest]() - - - [rest](tcllib/files/modules/rest/rest\.md) define REST web APIs and call them inline or asychronously - - + [ripemd]() - - - [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) RIPEMD\-128 Message\-Digest Algorithm - - - [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) RIPEMD\-160 Message\-Digest Algorithm - - + [sasl]() - - - [SASL](tcllib/files/modules/sasl/sasl\.md) Implementation of SASL mechanisms for Tcl - - - [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) Implementation of SASL NTLM mechanism for Tcl - - - [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) Implementation of SASL SCRAM mechanism for Tcl - - - [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md) Implementation of SASL NTLM mechanism for Tcl - - + [sha1]() - - - [sha1](tcllib/files/modules/sha1/sha1\.md) SHA1 Message\-Digest Algorithm - - - [sha256](tcllib/files/modules/sha1/sha256\.md) SHA256 Message\-Digest Algorithm - - + [simulation]() - - - [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) Simulated annealing - - - [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) Monte Carlo simulations - - - [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md) Pseudo\-random number generators - - + [smtpd]() - - - [smtpd](tcllib/files/modules/smtpd/smtpd\.md) Tcl SMTP server implementation - - + [snit]() - - - [snit](tcllib/files/modules/snit/snit\.md) Snit's Not Incr Tcl - - - [snitfaq](tcllib/files/modules/snit/snitfaq\.md) Snit Frequently Asked Questions - - + [soundex]() - - - [soundex](tcllib/files/modules/soundex/soundex\.md) Soundex - - + [stooop]() - - - [stooop](tcllib/files/modules/stooop/stooop\.md) Object oriented extension\. - - - [switched](tcllib/files/modules/stooop/switched\.md) switch/option management\. - - + [string]() - - - [string::token](tcllib/files/modules/string/token\.md) Regex based iterative lexing - - - [string::token::shell](tcllib/files/modules/string/token\_shell\.md) Parsing of shell command line - - + [stringprep]() - - - [stringprep](tcllib/files/modules/stringprep/stringprep\.md) Implementation of stringprep - - - [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) stringprep data tables, generated, internal - - - [unicode](tcllib/files/modules/stringprep/unicode\.md) Implementation of Unicode normalization - - - [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md) unicode data tables, generated, internal - - + [struct]() - - - [struct::disjointset](tcllib/files/modules/struct/disjointset\.md) Disjoint set data structure - - - [struct::graph](tcllib/files/modules/struct/graph\.md) Create and manipulate directed graph objects - - - [struct::graph::op](tcllib/files/modules/struct/graphops\.md) Operation for \(un\)directed graph objects - - - [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) Create and manipulate directed graph objects - - - [struct::list](tcllib/files/modules/struct/struct\_list\.md) Procedures for manipulating lists - - - [struct::map](tcllib/files/modules/struct/struct\_map\.md) Manage key/value maps - - - [struct::matrix](tcllib/files/modules/struct/matrix\.md) Create and manipulate matrix objects - - - [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) Create and manipulate matrix objects - - - [struct::pool](tcllib/files/modules/struct/pool\.md) Create and manipulate pool objects \(of discrete items\) - - - [struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) Create and manipulate prioqueue objects - - - [struct::queue](tcllib/files/modules/struct/queue\.md) Create and manipulate queue objects - - - [struct::record](tcllib/files/modules/struct/record\.md) Define and create records \(similar to 'C' structures\) - - - [struct::set](tcllib/files/modules/struct/struct\_set\.md) Procedures for manipulating sets - - - [struct::skiplist](tcllib/files/modules/struct/skiplist\.md) Create and manipulate skiplists - - - [struct::stack](tcllib/files/modules/struct/stack\.md) Create and manipulate stack objects - - - [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) Create and manipulate tree objects - - - [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) Create and manipulate tree objects - - + [tar]() - - - [tar](tcllib/files/modules/tar/tar\.md) Tar file creation, extraction & manipulation - - + [tepam]() - - - [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager - - - [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual - - - [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual - - - [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md) TEPAM procedure, reference manual - - + [term]() - - - [term](tcllib/files/modules/term/term\.md) General terminal control - - - [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) Helper for control sequences - - - [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) ANSI attribute sequences - - - [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) ANSI control sequences - - - [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) Macro sequences - - - [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) Control operations and queries - - - [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) Output of ANSI control sequences to terminals - - - [term::interact::menu](tcllib/files/modules/term/imenu\.md) Terminal widget, menu - - - [term::interact::pager](tcllib/files/modules/term/ipager\.md) Terminal widget, paging - - - [term::receive](tcllib/files/modules/term/receive\.md) General input from terminals - - - [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) Keyboard dispatch from terminals - - - [term::send](tcllib/files/modules/term/term\_send\.md) General output to terminals - - + [textutil]() - - - [textutil](tcllib/files/modules/textutil/textutil\.md) Procedures to manipulate texts and strings\. - - - [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) Procedures to adjust, indent, and undent paragraphs - - - [textutil::expander](tcllib/files/modules/textutil/expander\.md) Procedures to process templates and expand text\. - - - [textutil::patch](tcllib/files/modules/textutil/patch\.md) Application of uni\-diff patches to directory trees - - - [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) Procedures to repeat strings\. - - - [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) Procedures to split texts - - - [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) Procedures to manipulate texts and strings\. - - - [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) Procedures to \(un\)tabify strings - - - [textutil::trim](tcllib/files/modules/textutil/trim\.md) Procedures to trim strings - - + [tie]() - - - [tie](tcllib/files/modules/tie/tie\.md) Array persistence - - - [tie](tcllib/files/modules/tie/tie\_std\.md) Array persistence, standard data sources - - + [tiff]() - - - [tiff](tcllib/files/modules/tiff/tiff\.md) TIFF reading, writing, and querying and manipulation of meta data - - + [tool]() - - - [oo::util](tcllib/files/modules/tool/meta\.md) Utility commands for TclOO - - - [tool](tcllib/files/modules/tool/tool\.md) TclOO Library \(TOOL\) Framework - - - [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md) Dictionary Tools - - + [transfer]() - - - [transfer::connect](tcllib/files/modules/transfer/connect\.md) Connection setup - - - [transfer::copy](tcllib/files/modules/transfer/copyops\.md) Data transfer foundation - - - [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) Queued transfers - - - [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) Data destination - - - [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) Data source - - - [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) Data source - - - [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md) Data source - - + [treeql]() - - - [treeql](tcllib/files/modules/treeql/treeql\.md) Query tree objects - - + [try]() - - - [throw](tcllib/files/modules/try/tcllib\_throw\.md) throw \- Throw an error exception with a message - - - [try](tcllib/files/modules/try/tcllib\_try\.md) try \- Trap and process errors and exceptions - - + [udpcluster]() - - - [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md) UDP Peer\-to\-Peer cluster - - + [uev]() - - - [uevent](tcllib/files/modules/uev/uevent\.md) User events - - - [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time - - + [units]() - - - [units](tcllib/files/modules/units/units\.md) unit conversion - - + [uri]() - - - [uri](tcllib/files/modules/uri/uri\.md) URI utilities - - - [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md) URI utilities, URN scheme - - + [uuid]() - - - [uuid](tcllib/files/modules/uuid/uuid\.md) UUID generation and comparison - - + [valtype]() - - - [valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) Validation, common code - - - [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) Validation for AMEX creditcard number - - - [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) Validation for Discover creditcard number - - - [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) Validation for Mastercard creditcard number - - - [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) Validation for VISA creditcard number - - - [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) Validation for EAN13 - - - [valtype::iban](tcllib/files/modules/valtype/iban\.md) Validation for IBAN - - - [valtype::imei](tcllib/files/modules/valtype/imei\.md) Validation for IMEI - - - [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) Validation for ISBN - - - [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) Validation for plain number with a LUHN checkdigit - - - [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) Validation for plain number with a LUHN5 checkdigit - - - [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) Validation for USNPI - - - [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md) Validation for plain number with a VERHOEFF checkdigit - - + [virtchannel\_base]() - - - [tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) Concatenation channel - - - [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) Facade channel - - - [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) In\-memory fifo channel - - - [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) In\-memory interconnected fifo channels - - - [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) In\-memory channel, half of a fifo2 - - - [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) In\-memory channel - - - [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) Null channel - - - [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) Null/Zero channel combination - - - [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) Random channel - - - [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) Standard I/O, unification of stdin and stdout - - - [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) Read\-only in\-memory channel - - - [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) Textwindow channel - - - [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) In\-memory channel using variable for storage - - - [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) Zero channel - - - [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) Utilities for random channels - - + [virtchannel\_core]() - - - [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) Basic reflected/virtual channel support - - - [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) Event support for reflected/virtual channels - - - [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) Basic reflected/virtual channel transform support - - + [virtchannel\_transform]() - - - [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) Adler32 transformation - - - [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) Base64 encoding transformation - - - [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) Counter transformation - - - [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) Crc32 transformation - - - [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) Hexadecimal encoding transformation - - - [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) Identity transformation - - - [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) limiting input - - - [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) Observer transformation, stream copy - - - [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) Encryption via one\-time pad - - - [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption - - - [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal - - - [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression - - + [websocket]() - - - [websocket](tcllib/files/modules/websocket/websocket\.md) Tcl implementation of the websocket protocol - - + [wip]() - - - [wip](tcllib/files/modules/wip/wip\.md) Word Interpreter - - + [yaml]() - - - [huddle](tcllib/files/modules/yaml/huddle\.md) Create and manipulate huddle object - - - [yaml](tcllib/files/modules/yaml/yaml\.md) YAML Format Encoder/Decoder - - + [zip]() - - - [zipfile::decode](tcllib/files/modules/zip/decode\.md) Access to zip archives - - - [zipfile::encode](tcllib/files/modules/zip/encode\.md) Generation of zip archives - - - [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md) Build a zip archive DELETED embedded/md/toc0.md Index: embedded/md/toc0.md ================================================================== --- embedded/md/toc0.md +++ embedded/md/toc0.md @@ -1,936 +0,0 @@ - -[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') - -# Table Of Contents \-\- - - - [By Categories]() - - * [Argument entry form, mega widget]() - - + [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual - - * [Benchmark tools]() - - + [bench](tcllib/files/modules/bench/bench\.md) bench \- Processing benchmark suites - - + [bench::in](tcllib/files/modules/bench/bench\_read\.md) bench::in \- Reading benchmark results - - + [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) bench::out::csv \- Formatting benchmark results as CSV - - + [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) bench::out::text \- Formatting benchmark results as human readable text - - + [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) bench introduction - - + [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) bench language introduction - - + [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) bench language specification - - * [CGI programming]() - - + [html](tcllib/files/modules/html/html\.md) Procedures to generate HTML structures - - + [javascript](tcllib/files/modules/javascript/javascript\.md) Procedures to generate HTML and Java Script structures\. - - + [json](tcllib/files/modules/json/json\.md) JSON parser - - + [json::write](tcllib/files/modules/json/json\_write\.md) JSON generation - - + [ncgi](tcllib/files/modules/ncgi/ncgi\.md) Procedures to manipulate CGI values\. - - * [Channels]() - - + [tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) Concatenation channel - - + [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) Basic reflected/virtual channel support - - + [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) Event support for reflected/virtual channels - - + [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) Facade channel - - + [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) In\-memory fifo channel - - + [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) In\-memory interconnected fifo channels - - + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) In\-memory channel, half of a fifo2 - - + [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) In\-memory channel - - + [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) Null channel - - + [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) Null/Zero channel combination - - + [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) Random channel - - + [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) Standard I/O, unification of stdin and stdout - - + [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) Read\-only in\-memory channel - - + [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) Textwindow channel - - + [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) In\-memory channel using variable for storage - - + [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) Zero channel - - + [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) Utilities for random channels - - + [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) Adler32 transformation - - + [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) Base64 encoding transformation - - + [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) Basic reflected/virtual channel transform support - - + [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) Counter transformation - - + [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) Crc32 transformation - - + [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) Hexadecimal encoding transformation - - + [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) Identity transformation - - + [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) limiting input - - + [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) Observer transformation, stream copy - - + [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) Encryption via one\-time pad - - + [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption - - + [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal - - + [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression - - * [Coroutine]() - - + [coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) Coroutine based event and IO handling - - + [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) Automatic event and IO coroutine awareness - - * [Data structures]() - - + [counter](tcllib/files/modules/counter/counter\.md) Procedures for counters and histograms - - + [report](tcllib/files/modules/report/report\.md) Create and manipulate report objects - - + [struct::disjointset](tcllib/files/modules/struct/disjointset\.md) Disjoint set data structure - - + [struct::graph](tcllib/files/modules/struct/graph\.md) Create and manipulate directed graph objects - - + [struct::graph::op](tcllib/files/modules/struct/graphops\.md) Operation for \(un\)directed graph objects - - + [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) Create and manipulate directed graph objects - - + [struct::list](tcllib/files/modules/struct/struct\_list\.md) Procedures for manipulating lists - - + [struct::matrix](tcllib/files/modules/struct/matrix\.md) Create and manipulate matrix objects - - + [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) Create and manipulate matrix objects - - + [struct::pool](tcllib/files/modules/struct/pool\.md) Create and manipulate pool objects \(of discrete items\) - - + [struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) Create and manipulate prioqueue objects - - + [struct::queue](tcllib/files/modules/struct/queue\.md) Create and manipulate queue objects - - + [struct::record](tcllib/files/modules/struct/record\.md) Define and create records \(similar to 'C' structures\) - - + [struct::set](tcllib/files/modules/struct/struct\_set\.md) Procedures for manipulating sets - - + [struct::skiplist](tcllib/files/modules/struct/skiplist\.md) Create and manipulate skiplists - - + [struct::stack](tcllib/files/modules/struct/stack\.md) Create and manipulate stack objects - - + [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) Create and manipulate tree objects - - + [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) Create and manipulate tree objects - - + [treeql](tcllib/files/modules/treeql/treeql\.md) Query tree objects - - * [debugging, tracing, and logging]() - - + [debug](tcllib/files/modules/debug/debug\.md) debug narrative \- core - - + [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) debug narrative \- caller - - + [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) debug narrative \- heartbeat - - + [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) debug narrative \- timestamping - - * [Documentation tools]() - - + [docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) docidx introduction - - + [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) docidx language command reference - - + [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) docidx language faq - - + [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) docidx language introduction - - + [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) docidx language syntax - - + [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) docidx plugin API reference - - + [docstrip](tcllib/files/modules/docstrip/docstrip\.md) Docstrip style source code extraction - - + [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) Docstrip\-related utilities - - + [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) doctoc introduction - - + [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) doctoc language command reference - - + [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) doctoc language faq - - + [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) doctoc language introduction - - + [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) doctoc language syntax - - + [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) doctoc plugin API reference - - + [doctools](tcllib/files/modules/doctools/doctools\.md) doctools \- Processing documents - - + [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) DocTools \- Keyword indices - - + [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) DocTools \- Tables of Contents - - + [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) Processing text in Emacs ChangeLog format - - + [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) Processing text in 'cvs log' format - - + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) Default CSS style for HTML export plugins - - + [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) Holding keyword indices - - + [doctools::idx](tcllib/files/modules/doctools/docidx\.md) docidx \- Processing indices - - + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) Exporting keyword indices - - + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) Importing keyword indices - - + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) Parsing text in docidx format - - + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) Docidx serialization utilities - - + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) Message catalog management for the various document parsers - - + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) Message catalog for the docidx parser \(C\) - - + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) Message catalog for the docidx parser \(DE\) - - + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) Message catalog for the docidx parser \(EN\) - - + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) Message catalog for the docidx parser \(FR\) - - + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) Message catalog for the doctoc parser \(C\) - - + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) Message catalog for the doctoc parser \(DE\) - - + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) Message catalog for the doctoc parser \(EN\) - - + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) Message catalog for the doctoc parser \(FR\) - - + [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) Default CSS style for NROFF export plugins - - + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) Processing text in 'subst \-novariables' format - - + [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) Holding tables of contents - - + [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) doctoc \- Processing tables of contents - - + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) Exporting tables of contents - - + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) Importing keyword indices - - + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) Parsing text in doctoc format - - + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) Doctoc serialization utilities - - + [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) doctools introduction - - + [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) doctools language command reference - - + [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) doctools language faq - - + [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) doctools language introduction - - + [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) doctools language syntax - - + [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) doctools plugin API reference - - + [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) Lightweight DocTools Markup Processor - - + [dtplite](tcllib/files/apps/dtplite\.md) Lightweight DocTools Markup Processor - - + [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) Markup processor - - + [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor - - + [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual - - + [textutil::expander](tcllib/files/modules/textutil/expander\.md) Procedures to process templates and expand text\. - - * [File]() - - + [zipfile::decode](tcllib/files/modules/zip/decode\.md) Access to zip archives - - + [zipfile::encode](tcllib/files/modules/zip/encode\.md) Generation of zip archives - - + [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md) Build a zip archive - - * [File formats]() - - + [gpx](tcllib/files/modules/gpx/gpx\.md) Extracts waypoints, tracks and routes from GPX files - - + [jpeg](tcllib/files/modules/jpeg/jpeg\.md) JPEG querying and manipulation of meta data - - + [png](tcllib/files/modules/png/png\.md) PNG querying and manipulation of meta data - - + [tar](tcllib/files/modules/tar/tar\.md) Tar file creation, extraction & manipulation - - + [tiff](tcllib/files/modules/tiff/tiff\.md) TIFF reading, writing, and querying and manipulation of meta data - - * [Grammars and finite automata]() - - + [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) Aycock\-Horspool\-Earley parser generator for Tcl - - + [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) Create and manipulate finite automatons - - + [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) Create and use deterministic acceptors - - + [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) Execute deterministic finite automatons - - + [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) Operations on finite automatons - - + [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) Virtual machine implementation II for parsing token streams - - + [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) ME virtual machine state manipulation - - + [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) ME assembler - - + [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) Virtual machine implementation I for parsing token streams - - + [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) AST utilities - - + [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md) Various representations of ASTs - - + [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) Introduction to virtual machines for parsing token streams - - + [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) Virtual machine for parsing token streams - - + [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) Create and manipulate parsing expression grammars - - + [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) Interpreter for parsing expression grammars - - * [Hashes, checksums, and encryption]() - - + [aes](tcllib/files/modules/aes/aes\.md) Implementation of the AES block cipher - - + [blowfish](tcllib/files/modules/blowfish/blowfish\.md) Implementation of the Blowfish block cipher - - + [cksum](tcllib/files/modules/crc/cksum\.md) Calculate a cksum\(1\) compatible checksum - - + [crc16](tcllib/files/modules/crc/crc16\.md) Perform a 16bit Cyclic Redundancy Check - - + [crc32](tcllib/files/modules/crc/crc32\.md) Perform a 32bit Cyclic Redundancy Check - - + [des](tcllib/files/modules/des/des\.md) Implementation of the DES and triple\-DES ciphers - - + [md4](tcllib/files/modules/md4/md4\.md) MD4 Message\-Digest Algorithm - - + [md5](tcllib/files/modules/md5/md5\.md) MD5 Message\-Digest Algorithm - - + [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) MD5\-based password encryption - - + [otp](tcllib/files/modules/otp/otp\.md) One\-Time Passwords - - + [pki](tcllib/files/modules/pki/pki\.md) Implementation of the public key cipher - - + [rc4](tcllib/files/modules/rc4/rc4\.md) Implementation of the RC4 stream cipher - - + [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) RIPEMD\-128 Message\-Digest Algorithm - - + [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) RIPEMD\-160 Message\-Digest Algorithm - - + [sha1](tcllib/files/modules/sha1/sha1\.md) SHA1 Message\-Digest Algorithm - - + [sha256](tcllib/files/modules/sha1/sha256\.md) SHA256 Message\-Digest Algorithm - - + [soundex](tcllib/files/modules/soundex/soundex\.md) Soundex - - + [sum](tcllib/files/modules/crc/sum\.md) Calculate a sum\(1\) compatible checksum - - + [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers - - + [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers - - + [uuid](tcllib/files/modules/uuid/uuid\.md) UUID generation and comparison - - * [Mathematics]() - - + [math](tcllib/files/modules/math/math\.md) Tcl Math Library - - + [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) Arbitrary precision floating\-point numbers - - + [math::bignum](tcllib/files/modules/math/bignum\.md) Arbitrary precision integer numbers - - + [math::calculus](tcllib/files/modules/math/calculus\.md) Integration and ordinary differential equations - - + [math::calculus::romberg](tcllib/files/modules/math/romberg\.md) Romberg integration - - + [math::changepoint](tcllib/files/modules/math/changepoint\.md) Change point detection methods - - + [math::combinatorics](tcllib/files/modules/math/combinatorics\.md) Combinatorial functions in the Tcl Math Library - - + [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) Straightforward complex number package - - + [math::constants](tcllib/files/modules/math/constants\.md) Mathematical and numerical constants - - + [math::decimal](tcllib/files/modules/math/decimal\.md) General decimal arithmetic - - + [math::exact](tcllib/files/modules/math/exact\.md) Exact Real Arithmetic - - + [math::filters](tcllib/files/modules/math/filtergen\.md) Digital filters - - + [math::fourier](tcllib/files/modules/math/fourier\.md) Discrete and fast fourier transforms - - + [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) Fuzzy comparison of floating\-point numbers - - + [math::geometry](tcllib/files/modules/math/math\_geometry\.md) Geometrical computations - - + [math::interpolate](tcllib/files/modules/math/interpolate\.md) Interpolation routines - - + [math::linearalgebra](tcllib/files/modules/math/linalg\.md) Linear Algebra - - + [math::numtheory](tcllib/files/modules/math/numtheory\.md) Number Theory - - + [math::optimize](tcllib/files/modules/math/optimize\.md) Optimisation routines - - + [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis - - + [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions - - + [math::probopt](tcllib/files/modules/math/probopt\.md) Probabilistic optimisation methods - - + [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) Quasi\-random points for integration and Monte Carlo type methods - - + [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) Polynomial functions - - + [math::roman](tcllib/files/modules/math/roman\.md) Tools for creating and manipulating roman numerals - - + [math::special](tcllib/files/modules/math/special\.md) Special mathematical functions - - + [math::statistics](tcllib/files/modules/math/statistics\.md) Basic statistical functions and procedures - - + [math::trig](tcllib/files/modules/math/trig\.md) Trigonometric anf hyperbolic functions - - + [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) Simulated annealing - - + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) Monte Carlo simulations - - + [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md) Pseudo\-random number generators - - * [Networking]() - - + [asn](tcllib/files/modules/asn/asn\.md) ASN\.1 BER encoder/decoder - - + [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication - - + [bee](tcllib/files/modules/bee/bee\.md) BitTorrent Serialization Format Encoder/Decoder - - + [dns](tcllib/files/modules/dns/tcllib\_dns\.md) Tcl Domain Name Service Client - - + [ftp](tcllib/files/modules/ftp/ftp\.md) Client\-side tcl implementation of the ftp protocol - - + [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) Uri handler for ftp urls - - + [ftpd](tcllib/files/modules/ftpd/ftpd\.md) Tcl FTP server implementation - - + [httpd](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - - + [ident](tcllib/files/modules/ident/ident\.md) Ident protocol client - - + [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - - + [irc](tcllib/files/modules/irc/irc\.md) Create IRC connection and interface\. - - + [ldap](tcllib/files/modules/ldap/ldap\.md) LDAP client - - + [ldapx](tcllib/files/modules/ldap/ldapx\.md) LDAP extended object interface - - + [nameserv](tcllib/files/modules/nns/nns\_client\.md) Name service facility, Client - - + [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) Name service facility, Client Extension - - + [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) Name service facility, shared definitions - - + [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) Name service facility, client/server protocol - - + [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) Name service facility, Server - - + [nmea](tcllib/files/modules/nmea/nmea\.md) Process NMEA data - - + [nns](tcllib/files/apps/nns\.md) Name service facility, Commandline Client Application - - + [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) Name service facility, introduction - - + [nnsd](tcllib/files/apps/nnsd\.md) Name service facility, Commandline Server Application - - + [nnslog](tcllib/files/apps/nnslog\.md) Name service facility, Commandline Logging Client Application - - + [nntp](tcllib/files/modules/nntp/nntp\.md) Tcl client for the NNTP protocol - - + [ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md) Tcl Time Service Client - - + [oauth](tcllib/files/modules/oauth/oauth\.md) oauth API base signature - - + [picoirc](tcllib/files/modules/irc/picoirc\.md) Small and simple embeddable IRC client\. - - + [pop3](tcllib/files/modules/pop3/pop3\.md) Tcl client for POP3 email protocol - - + [pop3d](tcllib/files/modules/pop3d/pop3d\.md) Tcl POP3 server implementation - - + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) Simple mailbox database for pop3d - - + [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) Simple user database for pop3d - - + [S3](tcllib/files/modules/amazon\-s3/S3\.md) Amazon S3 Web Service Interface - - + [SASL](tcllib/files/modules/sasl/sasl\.md) Implementation of SASL mechanisms for Tcl - - + [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) Implementation of SASL NTLM mechanism for Tcl - - + [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) Implementation of SASL SCRAM mechanism for Tcl - - + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md) Implementation of SASL NTLM mechanism for Tcl - - + [smtp](tcllib/files/modules/mime/smtp\.md) Client\-side tcl implementation of the smtp protocol - - + [smtpd](tcllib/files/modules/smtpd/smtpd\.md) Tcl SMTP server implementation - - + [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation - - + [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md) UDP Peer\-to\-Peer cluster - - + [uri](tcllib/files/modules/uri/uri\.md) URI utilities - - + [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md) URI utilities, URN scheme - - + [websocket](tcllib/files/modules/websocket/websocket\.md) Tcl implementation of the websocket protocol - - * [Page Parser Generator]() - - + [page](tcllib/files/apps/page\.md) Parser Generator - - + [page\_intro](tcllib/files/modules/page/page\_intro\.md) page introduction - - + [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) page plugin manager - - + [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) page dataflow/treewalker utility - - + [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) page AST normalization, LEMON - - + [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) page AST normalization, PEG - - + [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) page PEG transformation utilities - - + [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) page character quoting utilities - - * [Parsing and Grammars]() - - + [pt](tcllib/files/apps/pt\.md) Parser Tools Application - - + [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) Abstract Syntax Tree Serialization - - + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) C/PARAM, Canned configuration, Critcl - - + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) C/PARAM, Canned configuration, TEA - - + [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) The JSON Grammar Exchange Format - - + [pt::param](tcllib/files/modules/pt/pt\_param\.md) PackRat Machine Specification - - + [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) Parsing Expression Serialization - - + [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) Parsing Expression Utilities - - + [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) Parsing Expression Grammar Serialization - - + [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) PEG Storage - - + [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) PEG Storage\. Canned PEG grammar specification - - + [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) PEG Export - - + [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) PEG Export Plugin\. Write CONTAINER format - - + [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) PEG Export Plugin\. Write JSON format - - + [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) PEG Export Plugin\. Write PEG format - - + [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) PEG Conversion\. From CONTAINER format - - + [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) PEG Conversion\. Read JSON format - - + [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) PEG Conversion\. Read PEG format - - + [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) PEG Import - - + [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) PEG Import Plugin\. From CONTAINER format - - + [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) PEG Import Plugin\. Read JSON format - - + [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) PEG Import Plugin\. Read PEG format - - + [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) Interpreter for parsing expression grammars - - + [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) PEG Conversion\. Write CONTAINER format - - + [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) PEG Conversion\. Write CPARAM format - - + [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) PEG Conversion\. Write JSON format - - + [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) PEG Conversion\. Write PARAM format - - + [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) PEG Conversion\. Write PEG format - - + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) PEG Conversion\. Write TCLPARAM format - - + [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) PEG Language Tutorial - - + [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) Introduction to Parsing Expression Grammars - - + [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) Parser Generator - - + [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) Parsing Runtime Support, PARAM based - - + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) Tcl/PARAM, Canned configuration, NX - - + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) Tcl/PARAM, Canned configuration, Snit - - + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) Tcl/PARAM, Canned configuration, Tcloo - - + [pt::util](tcllib/files/modules/pt/pt\_util\.md) General utilities - - + [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) Parser Tools Export API - - + [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) Parser Tools Import API - - + [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) Introduction to Parser Tools - - + [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) Parser Tools PEG Parser - - + [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) Parser API - - + [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) Parser Tools PE Grammar Utility Operations - - * [Procedures, arguments, parameters, options]() - - + [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager - - + [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md) TEPAM procedure, reference manual - - * [Programming tools]() - - + [clay](tcllib/files/modules/clay/clay\.md) A minimalist framework for large scale OO Projects - - + [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. - - + [comm](tcllib/files/modules/comm/comm\.md) A remote communication facility for Tcl \(8\.3 and later\) - - + [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) The comm wire protocol - - + [control](tcllib/files/modules/control/control\.md) Procedures for control flow structures\. - - + [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) Creation of comm delegates \(snit methods\) - - + [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) Creation of comm delegates \(procedures\) - - + [fileutil](tcllib/files/modules/fileutil/fileutil\.md) Procedures implementing some file utilities - - + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) Procedures implementing file\-type recognition - - + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) Runtime core for file type recognition engines written in pure Tcl - - + [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) Multi\-file operation, scatter/gather, standard object - - + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) Multi\-file operation, scatter/gather - - + [fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md) Iterative directory traversal - - + [hook](tcllib/files/modules/hook/hook\.md) Hooks - - + [interp](tcllib/files/modules/interp/tcllib\_interp\.md) Interp creation and aliasing - - + [log](tcllib/files/modules/log/log\.md) Procedures to log messages of libraries and applications\. - - + [logger](tcllib/files/modules/log/logger\.md) System to control logging of events\. - - + [logger::appender](tcllib/files/modules/log/loggerAppender\.md) Collection of predefined appenders for logger - - + [logger::utils](tcllib/files/modules/log/loggerUtils\.md) Utilities for logger - - + [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) One\-to\-many communication with sockets\. - - + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md) Manage a plugin - - + [profiler](tcllib/files/modules/profiler/profiler\.md) Tcl source code profiler - - + [snit](tcllib/files/modules/snit/snit\.md) Snit's Not Incr Tcl - - + [snitfaq](tcllib/files/modules/snit/snitfaq\.md) Snit Frequently Asked Questions - - + [stooop](tcllib/files/modules/stooop/stooop\.md) Object oriented extension\. - - + [switched](tcllib/files/modules/stooop/switched\.md) switch/option management\. - - + [tie](tcllib/files/modules/tie/tie\.md) Array persistence - - + [tie](tcllib/files/modules/tie/tie\_std\.md) Array persistence, standard data sources - - + [uevent](tcllib/files/modules/uev/uevent\.md) User events - - + [wip](tcllib/files/modules/wip/wip\.md) Word Interpreter - - * [System]() - - + [cron](tcllib/files/modules/cron/cron\.md) Tool for automating the period callback of commands - - + [nettool](tcllib/files/modules/nettool/nettool\.md) Tools for networked applications - - + [processman](tcllib/files/modules/processman/processman\.md) Tool for automating the period callback of commands - - * [TclOO]() - - + [oometa](tcllib/files/modules/oometa/oometa\.md) oo::meta A data registry for classess - - + [practcl](tcllib/files/modules/practcl/practcl\.md) The Practcl Module - - + [tool](tcllib/files/modules/tool/tool\.md) TclOO Library \(TOOL\) Framework - - * [Terminal control]() - - + [term](tcllib/files/modules/term/term\.md) General terminal control - - + [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) Helper for control sequences - - + [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) ANSI attribute sequences - - + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) ANSI control sequences - - + [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) Macro sequences - - + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) Control operations and queries - - + [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) Output of ANSI control sequences to terminals - - + [term::interact::menu](tcllib/files/modules/term/imenu\.md) Terminal widget, menu - - + [term::interact::pager](tcllib/files/modules/term/ipager\.md) Terminal widget, paging - - + [term::receive](tcllib/files/modules/term/receive\.md) General input from terminals - - + [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) Keyboard dispatch from terminals - - + [term::send](tcllib/files/modules/term/term\_send\.md) General output to terminals - - * [Text formatter plugin]() - - + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) docidx export plugin - - + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) HTML export plugin - - + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) JSON export plugin - - + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) nroff export plugin - - + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) plain text export plugin - - + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) wiki export plugin - - + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) docidx import plugin - - + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) JSON import plugin - - + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) doctoc export plugin - - + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) HTML export plugin - - + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) JSON export plugin - - + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) nroff export plugin - - + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) plain text export plugin - - + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) wiki export plugin - - + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) doctoc import plugin - - + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) JSON import plugin - - * [Text processing]() - - + [ascii85](tcllib/files/modules/base64/ascii85\.md) ascii85\-encode/decode binary data - - + [base32](tcllib/files/modules/base32/base32\.md) base32 standard encoding - - + [base32::core](tcllib/files/modules/base32/base32core\.md) Expanding basic base32 maps - - + [base32::hex](tcllib/files/modules/base32/base32hex\.md) base32 extended hex encoding - - + [base64](tcllib/files/modules/base64/base64\.md) base64\-encode/decode binary data - - + [bibtex](tcllib/files/modules/bibtex/bibtex\.md) Parse bibtex files - - + [clock\_iso8601](tcllib/files/modules/clock/iso8601\.md) Parsing ISO 8601 dates/times - - + [clock\_rfc2822](tcllib/files/modules/clock/rfc2822\.md) Parsing RFC 2822 dates/times - - + [csv](tcllib/files/modules/csv/csv\.md) Procedures to handle CSV data\. - - + [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) Procedures to parse HTML strings - - + [inifile](tcllib/files/modules/inifile/ini\.md) Parsing of Windows INI files - - + [markdown](tcllib/files/modules/markdown/markdown\.md) Converts Markdown text to HTML - - + [mime](tcllib/files/modules/mime/mime\.md) Manipulation of MIME body parts - - + [rcs](tcllib/files/modules/rcs/rcs\.md) RCS low level utilities - - + [string::token](tcllib/files/modules/string/token\.md) Regex based iterative lexing - - + [string::token::shell](tcllib/files/modules/string/token\_shell\.md) Parsing of shell command line - - + [textutil](tcllib/files/modules/textutil/textutil\.md) Procedures to manipulate texts and strings\. - - + [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) Procedures to adjust, indent, and undent paragraphs - - + [textutil::patch](tcllib/files/modules/textutil/patch\.md) Application of uni\-diff patches to directory trees - - + [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) Procedures to repeat strings\. - - + [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) Procedures to split texts - - + [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) Procedures to manipulate texts and strings\. - - + [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) Procedures to \(un\)tabify strings - - + [textutil::trim](tcllib/files/modules/textutil/trim\.md) Procedures to trim strings - - + [uuencode](tcllib/files/modules/base64/uuencode\.md) UU\-encode/decode binary data - - + [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md) eXtremely Simple Xml Parser - - + [yencode](tcllib/files/modules/base64/yencode\.md) Y\-encode/decode binary data - - * [Transfer module]() - - + [transfer::connect](tcllib/files/modules/transfer/connect\.md) Connection setup - - + [transfer::copy](tcllib/files/modules/transfer/copyops\.md) Data transfer foundation - - + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) Queued transfers - - + [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) Data destination - - + [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) Data source - - + [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) Data source - - + [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md) Data source - - * [Unfiled]() - - + [cache::async](tcllib/files/modules/cache/async\.md) Asynchronous in\-memory cache - - + [fileutil::paths](tcllib/files/modules/fileutil/paths\.md) Manage search path pools - - + [generator](tcllib/files/modules/generator/generator\.md) Procedures for creating and using generators\. - - + [huddle](tcllib/files/modules/yaml/huddle\.md) Create and manipulate huddle object - - + [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) Resolving geographical names with a Nominatim service - - + [map::slippy](tcllib/files/modules/map/map\_slippy\.md) Common code for slippy based map packages - - + [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) Management of a tile cache in the local filesystem - - + [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) Accessing a server providing tiles for slippy\-based maps - - + [mapproj](tcllib/files/modules/mapproj/mapproj\.md) Map projection routines - - + [math::calculus::symdiff](tcllib/files/modules/math/symdiff\.md) Symbolic differentiation for Tcl - - + [math::machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - - + [namespacex](tcllib/files/modules/namespacex/namespacex\.md) Namespace utility commands - - + [rest](tcllib/files/modules/rest/rest\.md) define REST web APIs and call them inline or asychronously - - + [stringprep](tcllib/files/modules/stringprep/stringprep\.md) Implementation of stringprep - - + [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) stringprep data tables, generated, internal - - + [struct::map](tcllib/files/modules/struct/struct\_map\.md) Manage key/value maps - - + [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time - - + [unicode](tcllib/files/modules/stringprep/unicode\.md) Implementation of Unicode normalization - - + [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md) unicode data tables, generated, internal - - + [units](tcllib/files/modules/units/units\.md) unit conversion - - + [yaml](tcllib/files/modules/yaml/yaml\.md) YAML Format Encoder/Decoder - - * [Utilities]() - - + [dicttool](tcllib/files/modules/dicttool/dicttool\.md) Dictionary Tools - - * [Utility]() - - + [defer](tcllib/files/modules/defer/defer\.md) Defered execution - - + [lambda](tcllib/files/modules/lambda/lambda\.md) Utility commands for anonymous procedures - - + [lazyset](tcllib/files/modules/lazyset/lazyset\.md) Lazy evaluation - - + [oo::util](tcllib/files/modules/ooutil/ooutil\.md) Utility commands for TclOO - - + [oo::util](tcllib/files/modules/tool/meta\.md) Utility commands for TclOO - - + [throw](tcllib/files/modules/try/tcllib\_throw\.md) throw \- Throw an error exception with a message - - + [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md) Dictionary Tools - - + [try](tcllib/files/modules/try/tcllib\_try\.md) try \- Trap and process errors and exceptions - - * [Validation, Type checking]() - - + [valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) Validation, common code - - + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) Validation for AMEX creditcard number - - + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) Validation for Discover creditcard number - - + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) Validation for Mastercard creditcard number - - + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) Validation for VISA creditcard number - - + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) Validation for EAN13 - - + [valtype::iban](tcllib/files/modules/valtype/iban\.md) Validation for IBAN - - + [valtype::imei](tcllib/files/modules/valtype/imei\.md) Validation for IMEI - - + [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) Validation for ISBN - - + [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) Validation for plain number with a LUHN checkdigit - - + [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) Validation for plain number with a LUHN5 checkdigit - - + [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) Validation for USNPI - - + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md) Validation for plain number with a VERHOEFF checkdigit DELETED embedded/md/toc1.md Index: embedded/md/toc1.md ================================================================== --- embedded/md/toc1.md +++ embedded/md/toc1.md @@ -1,1118 +0,0 @@ - -[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') - -# Table Of Contents \-\- - - - [Modules]() - - * [aes]() - - + [aes](tcllib/files/modules/aes/aes\.md) Implementation of the AES block cipher - - * [amazon\-s3]() - - + [S3](tcllib/files/modules/amazon\-s3/S3\.md) Amazon S3 Web Service Interface - - + [xsxp](tcllib/files/modules/amazon\-s3/xsxp\.md) eXtremely Simple Xml Parser - - * [asn]() - - + [asn](tcllib/files/modules/asn/asn\.md) ASN\.1 BER encoder/decoder - - * [base32]() - - + [base32](tcllib/files/modules/base32/base32\.md) base32 standard encoding - - + [base32::core](tcllib/files/modules/base32/base32core\.md) Expanding basic base32 maps - - + [base32::hex](tcllib/files/modules/base32/base32hex\.md) base32 extended hex encoding - - * [base64]() - - + [ascii85](tcllib/files/modules/base64/ascii85\.md) ascii85\-encode/decode binary data - - + [base64](tcllib/files/modules/base64/base64\.md) base64\-encode/decode binary data - - + [uuencode](tcllib/files/modules/base64/uuencode\.md) UU\-encode/decode binary data - - + [yencode](tcllib/files/modules/base64/yencode\.md) Y\-encode/decode binary data - - * [bee]() - - + [bee](tcllib/files/modules/bee/bee\.md) BitTorrent Serialization Format Encoder/Decoder - - * [bench]() - - + [bench](tcllib/files/modules/bench/bench\.md) bench \- Processing benchmark suites - - + [bench::in](tcllib/files/modules/bench/bench\_read\.md) bench::in \- Reading benchmark results - - + [bench::out::csv](tcllib/files/modules/bench/bench\_wcsv\.md) bench::out::csv \- Formatting benchmark results as CSV - - + [bench::out::text](tcllib/files/modules/bench/bench\_wtext\.md) bench::out::text \- Formatting benchmark results as human readable text - - + [bench\_intro](tcllib/files/modules/bench/bench\_intro\.md) bench introduction - - + [bench\_lang\_intro](tcllib/files/modules/bench/bench\_lang\_intro\.md) bench language introduction - - + [bench\_lang\_spec](tcllib/files/modules/bench/bench\_lang\_spec\.md) bench language specification - - * [bibtex]() - - + [bibtex](tcllib/files/modules/bibtex/bibtex\.md) Parse bibtex files - - * [blowfish]() - - + [blowfish](tcllib/files/modules/blowfish/blowfish\.md) Implementation of the Blowfish block cipher - - * [cache]() - - + [cache::async](tcllib/files/modules/cache/async\.md) Asynchronous in\-memory cache - - * [clay]() - - + [clay](tcllib/files/modules/clay/clay\.md) A minimalist framework for large scale OO Projects - - * [clock]() - - + [clock\_iso8601](tcllib/files/modules/clock/iso8601\.md) Parsing ISO 8601 dates/times - - + [clock\_rfc2822](tcllib/files/modules/clock/rfc2822\.md) Parsing RFC 2822 dates/times - - * [cmdline]() - - + [cmdline](tcllib/files/modules/cmdline/cmdline\.md) Procedures to process command lines and options\. - - * [comm]() - - + [comm](tcllib/files/modules/comm/comm\.md) A remote communication facility for Tcl \(8\.3 and later\) - - + [comm\_wire](tcllib/files/modules/comm/comm\_wire\.md) The comm wire protocol - - * [control]() - - + [control](tcllib/files/modules/control/control\.md) Procedures for control flow structures\. - - * [coroutine]() - - + [coroutine](tcllib/files/modules/coroutine/tcllib\_coroutine\.md) Coroutine based event and IO handling - - + [coroutine::auto](tcllib/files/modules/coroutine/coro\_auto\.md) Automatic event and IO coroutine awareness - - * [counter]() - - + [counter](tcllib/files/modules/counter/counter\.md) Procedures for counters and histograms - - * [crc]() - - + [cksum](tcllib/files/modules/crc/cksum\.md) Calculate a cksum\(1\) compatible checksum - - + [crc16](tcllib/files/modules/crc/crc16\.md) Perform a 16bit Cyclic Redundancy Check - - + [crc32](tcllib/files/modules/crc/crc32\.md) Perform a 32bit Cyclic Redundancy Check - - + [sum](tcllib/files/modules/crc/sum\.md) Calculate a sum\(1\) compatible checksum - - * [cron]() - - + [cron](tcllib/files/modules/cron/cron\.md) Tool for automating the period callback of commands - - * [csv]() - - + [csv](tcllib/files/modules/csv/csv\.md) Procedures to handle CSV data\. - - * [debug]() - - + [debug](tcllib/files/modules/debug/debug\.md) debug narrative \- core - - + [debug::caller](tcllib/files/modules/debug/debug\_caller\.md) debug narrative \- caller - - + [debug::heartbeat](tcllib/files/modules/debug/debug\_heartbeat\.md) debug narrative \- heartbeat - - + [debug::timestamp](tcllib/files/modules/debug/debug\_timestamp\.md) debug narrative \- timestamping - - * [defer]() - - + [defer](tcllib/files/modules/defer/defer\.md) Defered execution - - * [des]() - - + [des](tcllib/files/modules/des/des\.md) Implementation of the DES and triple\-DES ciphers - - + [tclDES](tcllib/files/modules/des/tcldes\.md) Implementation of the DES and triple\-DES ciphers - - + [tclDESjr](tcllib/files/modules/des/tcldesjr\.md) Implementation of the DES and triple\-DES ciphers - - * [dicttool]() - - + [dicttool](tcllib/files/modules/dicttool/dicttool\.md) Dictionary Tools - - * [dns]() - - + [dns](tcllib/files/modules/dns/tcllib\_dns\.md) Tcl Domain Name Service Client - - + [tcllib\_ip](tcllib/files/modules/dns/tcllib\_ip\.md) IPv4 and IPv6 address manipulation - - * [docstrip]() - - + [docstrip](tcllib/files/modules/docstrip/docstrip\.md) Docstrip style source code extraction - - + [docstrip\_util](tcllib/files/modules/docstrip/docstrip\_util\.md) Docstrip\-related utilities - - * [doctools]() - - + [docidx\_intro](tcllib/files/modules/doctools/docidx\_intro\.md) docidx introduction - - + [docidx\_lang\_cmdref](tcllib/files/modules/doctools/docidx\_lang\_cmdref\.md) docidx language command reference - - + [docidx\_lang\_faq](tcllib/files/modules/doctools/docidx\_lang\_faq\.md) docidx language faq - - + [docidx\_lang\_intro](tcllib/files/modules/doctools/docidx\_lang\_intro\.md) docidx language introduction - - + [docidx\_lang\_syntax](tcllib/files/modules/doctools/docidx\_lang\_syntax\.md) docidx language syntax - - + [docidx\_plugin\_apiref](tcllib/files/modules/doctools/docidx\_plugin\_apiref\.md) docidx plugin API reference - - + [doctoc\_intro](tcllib/files/modules/doctools/doctoc\_intro\.md) doctoc introduction - - + [doctoc\_lang\_cmdref](tcllib/files/modules/doctools/doctoc\_lang\_cmdref\.md) doctoc language command reference - - + [doctoc\_lang\_faq](tcllib/files/modules/doctools/doctoc\_lang\_faq\.md) doctoc language faq - - + [doctoc\_lang\_intro](tcllib/files/modules/doctools/doctoc\_lang\_intro\.md) doctoc language introduction - - + [doctoc\_lang\_syntax](tcllib/files/modules/doctools/doctoc\_lang\_syntax\.md) doctoc language syntax - - + [doctoc\_plugin\_apiref](tcllib/files/modules/doctools/doctoc\_plugin\_apiref\.md) doctoc plugin API reference - - + [doctools](tcllib/files/modules/doctools/doctools\.md) doctools \- Processing documents - - + [doctools::changelog](tcllib/files/modules/doctools/changelog\.md) Processing text in Emacs ChangeLog format - - + [doctools::cvs](tcllib/files/modules/doctools/cvs\.md) Processing text in 'cvs log' format - - + [doctools::idx](tcllib/files/modules/doctools/docidx\.md) docidx \- Processing indices - - + [doctools::toc](tcllib/files/modules/doctools/doctoc\.md) doctoc \- Processing tables of contents - - + [doctools\_intro](tcllib/files/modules/doctools/doctools\_intro\.md) doctools introduction - - + [doctools\_lang\_cmdref](tcllib/files/modules/doctools/doctools\_lang\_cmdref\.md) doctools language command reference - - + [doctools\_lang\_faq](tcllib/files/modules/doctools/doctools\_lang\_faq\.md) doctools language faq - - + [doctools\_lang\_intro](tcllib/files/modules/doctools/doctools\_lang\_intro\.md) doctools language introduction - - + [doctools\_lang\_syntax](tcllib/files/modules/doctools/doctools\_lang\_syntax\.md) doctools language syntax - - + [doctools\_plugin\_apiref](tcllib/files/modules/doctools/doctools\_plugin\_apiref\.md) doctools plugin API reference - - + [mpexpand](tcllib/files/modules/doctools/mpexpand\.md) Markup processor - - * [doctools2base]() - - + [doctools::html::cssdefaults](tcllib/files/modules/doctools2base/html\_cssdefaults\.md) Default CSS style for HTML export plugins - - + [doctools::msgcat](tcllib/files/modules/doctools2base/tcllib\_msgcat\.md) Message catalog management for the various document parsers - - + [doctools::nroff::man\_macros](tcllib/files/modules/doctools2base/nroff\_manmacros\.md) Default CSS style for NROFF export plugins - - + [doctools::tcl::parse](tcllib/files/modules/doctools2base/tcl\_parse\.md) Processing text in 'subst \-novariables' format - - * [doctools2idx]() - - + [doctools2idx\_introduction](tcllib/files/modules/doctools2idx/idx\_introduction\.md) DocTools \- Keyword indices - - + [doctools::idx](tcllib/files/modules/doctools2idx/idx\_container\.md) Holding keyword indices - - + [doctools::idx::export](tcllib/files/modules/doctools2idx/idx\_export\.md) Exporting keyword indices - - + [doctools::idx::export::docidx](tcllib/files/modules/doctools2idx/export\_docidx\.md) docidx export plugin - - + [doctools::idx::export::html](tcllib/files/modules/doctools2idx/idx\_export\_html\.md) HTML export plugin - - + [doctools::idx::export::json](tcllib/files/modules/doctools2idx/idx\_export\_json\.md) JSON export plugin - - + [doctools::idx::export::nroff](tcllib/files/modules/doctools2idx/idx\_export\_nroff\.md) nroff export plugin - - + [doctools::idx::export::text](tcllib/files/modules/doctools2idx/idx\_export\_text\.md) plain text export plugin - - + [doctools::idx::export::wiki](tcllib/files/modules/doctools2idx/idx\_export\_wiki\.md) wiki export plugin - - + [doctools::idx::import](tcllib/files/modules/doctools2idx/idx\_import\.md) Importing keyword indices - - + [doctools::idx::import::docidx](tcllib/files/modules/doctools2idx/import\_docidx\.md) docidx import plugin - - + [doctools::idx::import::json](tcllib/files/modules/doctools2idx/idx\_import\_json\.md) JSON import plugin - - + [doctools::idx::parse](tcllib/files/modules/doctools2idx/idx\_parse\.md) Parsing text in docidx format - - + [doctools::idx::structure](tcllib/files/modules/doctools2idx/idx\_structure\.md) Docidx serialization utilities - - + [doctools::msgcat::idx::c](tcllib/files/modules/doctools2idx/idx\_msgcat\_c\.md) Message catalog for the docidx parser \(C\) - - + [doctools::msgcat::idx::de](tcllib/files/modules/doctools2idx/idx\_msgcat\_de\.md) Message catalog for the docidx parser \(DE\) - - + [doctools::msgcat::idx::en](tcllib/files/modules/doctools2idx/idx\_msgcat\_en\.md) Message catalog for the docidx parser \(EN\) - - + [doctools::msgcat::idx::fr](tcllib/files/modules/doctools2idx/idx\_msgcat\_fr\.md) Message catalog for the docidx parser \(FR\) - - * [doctools2toc]() - - + [doctools2toc\_introduction](tcllib/files/modules/doctools2toc/toc\_introduction\.md) DocTools \- Tables of Contents - - + [doctools::msgcat::toc::c](tcllib/files/modules/doctools2toc/toc\_msgcat\_c\.md) Message catalog for the doctoc parser \(C\) - - + [doctools::msgcat::toc::de](tcllib/files/modules/doctools2toc/toc\_msgcat\_de\.md) Message catalog for the doctoc parser \(DE\) - - + [doctools::msgcat::toc::en](tcllib/files/modules/doctools2toc/toc\_msgcat\_en\.md) Message catalog for the doctoc parser \(EN\) - - + [doctools::msgcat::toc::fr](tcllib/files/modules/doctools2toc/toc\_msgcat\_fr\.md) Message catalog for the doctoc parser \(FR\) - - + [doctools::toc](tcllib/files/modules/doctools2toc/toc\_container\.md) Holding tables of contents - - + [doctools::toc::export](tcllib/files/modules/doctools2toc/toc\_export\.md) Exporting tables of contents - - + [doctools::toc::export::doctoc](tcllib/files/modules/doctools2toc/export\_doctoc\.md) doctoc export plugin - - + [doctools::toc::export::html](tcllib/files/modules/doctools2toc/toc\_export\_html\.md) HTML export plugin - - + [doctools::toc::export::json](tcllib/files/modules/doctools2toc/toc\_export\_json\.md) JSON export plugin - - + [doctools::toc::export::nroff](tcllib/files/modules/doctools2toc/toc\_export\_nroff\.md) nroff export plugin - - + [doctools::toc::export::text](tcllib/files/modules/doctools2toc/toc\_export\_text\.md) plain text export plugin - - + [doctools::toc::export::wiki](tcllib/files/modules/doctools2toc/toc\_export\_wiki\.md) wiki export plugin - - + [doctools::toc::import](tcllib/files/modules/doctools2toc/toc\_import\.md) Importing keyword indices - - + [doctools::toc::import::doctoc](tcllib/files/modules/doctools2toc/import\_doctoc\.md) doctoc import plugin - - + [doctools::toc::import::json](tcllib/files/modules/doctools2toc/toc\_import\_json\.md) JSON import plugin - - + [doctools::toc::parse](tcllib/files/modules/doctools2toc/toc\_parse\.md) Parsing text in doctoc format - - + [doctools::toc::structure](tcllib/files/modules/doctools2toc/toc\_structure\.md) Doctoc serialization utilities - - * [dtplite]() - - + [dtplite](tcllib/files/modules/dtplite/pkg\_dtplite\.md) Lightweight DocTools Markup Processor - - * [fileutil]() - - + [fileutil](tcllib/files/modules/fileutil/fileutil\.md) Procedures implementing some file utilities - - + [fileutil::multi](tcllib/files/modules/fileutil/multi\.md) Multi\-file operation, scatter/gather, standard object - - + [fileutil::multi::op](tcllib/files/modules/fileutil/multiop\.md) Multi\-file operation, scatter/gather - - + [fileutil::paths](tcllib/files/modules/fileutil/paths\.md) Manage search path pools - - + [fileutil\_traverse](tcllib/files/modules/fileutil/traverse\.md) Iterative directory traversal - - * [ftp]() - - + [ftp](tcllib/files/modules/ftp/ftp\.md) Client\-side tcl implementation of the ftp protocol - - + [ftp::geturl](tcllib/files/modules/ftp/ftp\_geturl\.md) Uri handler for ftp urls - - * [ftpd]() - - + [ftpd](tcllib/files/modules/ftpd/ftpd\.md) Tcl FTP server implementation - - * [fumagic]() - - + [fileutil::magic::cfront](tcllib/files/modules/fumagic/cfront\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::cgen](tcllib/files/modules/fumagic/cgen\.md) Generator core for compiler of magic\(5\) files - - + [fileutil::magic::filetype](tcllib/files/modules/fumagic/filetypes\.md) Procedures implementing file\-type recognition - - + [fileutil::magic::rt](tcllib/files/modules/fumagic/rtcore\.md) Runtime core for file type recognition engines written in pure Tcl - - * [generator]() - - + [generator](tcllib/files/modules/generator/generator\.md) Procedures for creating and using generators\. - - * [gpx]() - - + [gpx](tcllib/files/modules/gpx/gpx\.md) Extracts waypoints, tracks and routes from GPX files - - * [grammar\_aycock]() - - + [grammar::aycock](tcllib/files/modules/grammar\_aycock/aycock\.md) Aycock\-Horspool\-Earley parser generator for Tcl - - * [grammar\_fa]() - - + [grammar::fa](tcllib/files/modules/grammar\_fa/fa\.md) Create and manipulate finite automatons - - + [grammar::fa::dacceptor](tcllib/files/modules/grammar\_fa/dacceptor\.md) Create and use deterministic acceptors - - + [grammar::fa::dexec](tcllib/files/modules/grammar\_fa/dexec\.md) Execute deterministic finite automatons - - + [grammar::fa::op](tcllib/files/modules/grammar\_fa/faop\.md) Operations on finite automatons - - * [grammar\_me]() - - + [grammar::me::cpu](tcllib/files/modules/grammar\_me/me\_cpu\.md) Virtual machine implementation II for parsing token streams - - + [grammar::me::cpu::core](tcllib/files/modules/grammar\_me/me\_cpucore\.md) ME virtual machine state manipulation - - + [grammar::me::cpu::gasm](tcllib/files/modules/grammar\_me/gasm\.md) ME assembler - - + [grammar::me::tcl](tcllib/files/modules/grammar\_me/me\_tcl\.md) Virtual machine implementation I for parsing token streams - - + [grammar::me::util](tcllib/files/modules/grammar\_me/me\_util\.md) AST utilities - - + [grammar::me\_ast](tcllib/files/modules/grammar\_me/me\_ast\.md) Various representations of ASTs - - + [grammar::me\_intro](tcllib/files/modules/grammar\_me/me\_intro\.md) Introduction to virtual machines for parsing token streams - - + [grammar::me\_vm](tcllib/files/modules/grammar\_me/me\_vm\.md) Virtual machine for parsing token streams - - * [grammar\_peg]() - - + [grammar::peg](tcllib/files/modules/grammar\_peg/peg\.md) Create and manipulate parsing expression grammars - - + [grammar::peg::interp](tcllib/files/modules/grammar\_peg/peg\_interp\.md) Interpreter for parsing expression grammars - - * [hook]() - - + [hook](tcllib/files/modules/hook/hook\.md) Hooks - - * [html]() - - + [html](tcllib/files/modules/html/html\.md) Procedures to generate HTML structures - - * [htmlparse]() - - + [htmlparse](tcllib/files/modules/htmlparse/htmlparse\.md) Procedures to parse HTML strings - - * [http]() - - + [autoproxy](tcllib/files/modules/http/autoproxy\.md) Automatic HTTP proxy usage and authentication - - * [httpd]() - - + [httpd](tcllib/files/modules/httpd/httpd\.md) A TclOO and coroutine based web server - - * [ident]() - - + [ident](tcllib/files/modules/ident/ident\.md) Ident protocol client - - * [imap4]() - - + [imap4](tcllib/files/modules/imap4/imap4\.md) imap client\-side tcl implementation of imap protocol - - * [inifile]() - - + [inifile](tcllib/files/modules/inifile/ini\.md) Parsing of Windows INI files - - * [interp]() - - + [deleg\_method](tcllib/files/modules/interp/deleg\_method\.md) Creation of comm delegates \(snit methods\) - - + [deleg\_proc](tcllib/files/modules/interp/deleg\_proc\.md) Creation of comm delegates \(procedures\) - - + [interp](tcllib/files/modules/interp/tcllib\_interp\.md) Interp creation and aliasing - - * [irc]() - - + [irc](tcllib/files/modules/irc/irc\.md) Create IRC connection and interface\. - - + [picoirc](tcllib/files/modules/irc/picoirc\.md) Small and simple embeddable IRC client\. - - * [javascript]() - - + [javascript](tcllib/files/modules/javascript/javascript\.md) Procedures to generate HTML and Java Script structures\. - - * [jpeg]() - - + [jpeg](tcllib/files/modules/jpeg/jpeg\.md) JPEG querying and manipulation of meta data - - * [json]() - - + [json](tcllib/files/modules/json/json\.md) JSON parser - - + [json::write](tcllib/files/modules/json/json\_write\.md) JSON generation - - * [lambda]() - - + [lambda](tcllib/files/modules/lambda/lambda\.md) Utility commands for anonymous procedures - - * [lazyset]() - - + [lazyset](tcllib/files/modules/lazyset/lazyset\.md) Lazy evaluation - - * [ldap]() - - + [ldap](tcllib/files/modules/ldap/ldap\.md) LDAP client - - + [ldapx](tcllib/files/modules/ldap/ldapx\.md) LDAP extended object interface - - * [log]() - - + [log](tcllib/files/modules/log/log\.md) Procedures to log messages of libraries and applications\. - - + [logger](tcllib/files/modules/log/logger\.md) System to control logging of events\. - - + [logger::appender](tcllib/files/modules/log/loggerAppender\.md) Collection of predefined appenders for logger - - + [logger::utils](tcllib/files/modules/log/loggerUtils\.md) Utilities for logger - - * [map]() - - + [map::geocode::nominatim](tcllib/files/modules/map/map\_geocode\_nominatim\.md) Resolving geographical names with a Nominatim service - - + [map::slippy](tcllib/files/modules/map/map\_slippy\.md) Common code for slippy based map packages - - + [map::slippy::cache](tcllib/files/modules/map/map\_slippy\_cache\.md) Management of a tile cache in the local filesystem - - + [map::slippy::fetcher](tcllib/files/modules/map/map\_slippy\_fetcher\.md) Accessing a server providing tiles for slippy\-based maps - - * [mapproj]() - - + [mapproj](tcllib/files/modules/mapproj/mapproj\.md) Map projection routines - - * [markdown]() - - + [markdown](tcllib/files/modules/markdown/markdown\.md) Converts Markdown text to HTML - - * [math]() - - + [math](tcllib/files/modules/math/math\.md) Tcl Math Library - - + [math::bigfloat](tcllib/files/modules/math/bigfloat\.md) Arbitrary precision floating\-point numbers - - + [math::bignum](tcllib/files/modules/math/bignum\.md) Arbitrary precision integer numbers - - + [math::calculus](tcllib/files/modules/math/calculus\.md) Integration and ordinary differential equations - - + [math::calculus::romberg](tcllib/files/modules/math/romberg\.md) Romberg integration - - + [math::calculus::symdiff](tcllib/files/modules/math/symdiff\.md) Symbolic differentiation for Tcl - - + [math::changepoint](tcllib/files/modules/math/changepoint\.md) Change point detection methods - - + [math::combinatorics](tcllib/files/modules/math/combinatorics\.md) Combinatorial functions in the Tcl Math Library - - + [math::complexnumbers](tcllib/files/modules/math/qcomplex\.md) Straightforward complex number package - - + [math::constants](tcllib/files/modules/math/constants\.md) Mathematical and numerical constants - - + [math::decimal](tcllib/files/modules/math/decimal\.md) General decimal arithmetic - - + [math::exact](tcllib/files/modules/math/exact\.md) Exact Real Arithmetic - - + [math::filters](tcllib/files/modules/math/filtergen\.md) Digital filters - - + [math::fourier](tcllib/files/modules/math/fourier\.md) Discrete and fast fourier transforms - - + [math::fuzzy](tcllib/files/modules/math/fuzzy\.md) Fuzzy comparison of floating\-point numbers - - + [math::geometry](tcllib/files/modules/math/math\_geometry\.md) Geometrical computations - - + [math::interpolate](tcllib/files/modules/math/interpolate\.md) Interpolation routines - - + [math::linearalgebra](tcllib/files/modules/math/linalg\.md) Linear Algebra - - + [math::machineparameters](tcllib/files/modules/math/machineparameters\.md) Compute double precision machine parameters\. - - + [math::numtheory](tcllib/files/modules/math/numtheory\.md) Number Theory - - + [math::optimize](tcllib/files/modules/math/optimize\.md) Optimisation routines - - + [math::PCA](tcllib/files/modules/math/pca\.md) Package for Principal Component Analysis - - + [math::polynomials](tcllib/files/modules/math/polynomials\.md) Polynomial functions - - + [math::probopt](tcllib/files/modules/math/probopt\.md) Probabilistic optimisation methods - - + [math::quasirandom](tcllib/files/modules/math/quasirandom\.md) Quasi\-random points for integration and Monte Carlo type methods - - + [math::rationalfunctions](tcllib/files/modules/math/rational\_funcs\.md) Polynomial functions - - + [math::roman](tcllib/files/modules/math/roman\.md) Tools for creating and manipulating roman numerals - - + [math::special](tcllib/files/modules/math/special\.md) Special mathematical functions - - + [math::statistics](tcllib/files/modules/math/statistics\.md) Basic statistical functions and procedures - - + [math::trig](tcllib/files/modules/math/trig\.md) Trigonometric anf hyperbolic functions - - * [md4]() - - + [md4](tcllib/files/modules/md4/md4\.md) MD4 Message\-Digest Algorithm - - * [md5]() - - + [md5](tcllib/files/modules/md5/md5\.md) MD5 Message\-Digest Algorithm - - * [md5crypt]() - - + [md5crypt](tcllib/files/modules/md5crypt/md5crypt\.md) MD5\-based password encryption - - * [mime]() - - + [mime](tcllib/files/modules/mime/mime\.md) Manipulation of MIME body parts - - + [smtp](tcllib/files/modules/mime/smtp\.md) Client\-side tcl implementation of the smtp protocol - - * [multiplexer]() - - + [multiplexer](tcllib/files/modules/multiplexer/multiplexer\.md) One\-to\-many communication with sockets\. - - * [namespacex]() - - + [namespacex](tcllib/files/modules/namespacex/namespacex\.md) Namespace utility commands - - * [ncgi]() - - + [ncgi](tcllib/files/modules/ncgi/ncgi\.md) Procedures to manipulate CGI values\. - - * [nettool]() - - + [nettool](tcllib/files/modules/nettool/nettool\.md) Tools for networked applications - - * [nmea]() - - + [nmea](tcllib/files/modules/nmea/nmea\.md) Process NMEA data - - * [nns]() - - + [nameserv](tcllib/files/modules/nns/nns\_client\.md) Name service facility, Client - - + [nameserv::auto](tcllib/files/modules/nns/nns\_auto\.md) Name service facility, Client Extension - - + [nameserv::common](tcllib/files/modules/nns/nns\_common\.md) Name service facility, shared definitions - - + [nameserv::protocol](tcllib/files/modules/nns/nns\_protocol\.md) Name service facility, client/server protocol - - + [nameserv::server](tcllib/files/modules/nns/nns\_server\.md) Name service facility, Server - - + [nns\_intro](tcllib/files/modules/nns/nns\_intro\.md) Name service facility, introduction - - * [nntp]() - - + [nntp](tcllib/files/modules/nntp/nntp\.md) Tcl client for the NNTP protocol - - * [ntp]() - - + [ntp\_time](tcllib/files/modules/ntp/ntp\_time\.md) Tcl Time Service Client - - * [oauth]() - - + [oauth](tcllib/files/modules/oauth/oauth\.md) oauth API base signature - - * [oometa]() - - + [oometa](tcllib/files/modules/oometa/oometa\.md) oo::meta A data registry for classess - - * [ooutil]() - - + [oo::util](tcllib/files/modules/ooutil/ooutil\.md) Utility commands for TclOO - - * [otp]() - - + [otp](tcllib/files/modules/otp/otp\.md) One\-Time Passwords - - * [page]() - - + [page\_intro](tcllib/files/modules/page/page\_intro\.md) page introduction - - + [page\_pluginmgr](tcllib/files/modules/page/page\_pluginmgr\.md) page plugin manager - - + [page\_util\_flow](tcllib/files/modules/page/page\_util\_flow\.md) page dataflow/treewalker utility - - + [page\_util\_norm\_lemon](tcllib/files/modules/page/page\_util\_norm\_lemon\.md) page AST normalization, LEMON - - + [page\_util\_norm\_peg](tcllib/files/modules/page/page\_util\_norm\_peg\.md) page AST normalization, PEG - - + [page\_util\_peg](tcllib/files/modules/page/page\_util\_peg\.md) page PEG transformation utilities - - + [page\_util\_quote](tcllib/files/modules/page/page\_util\_quote\.md) page character quoting utilities - - * [pki]() - - + [pki](tcllib/files/modules/pki/pki\.md) Implementation of the public key cipher - - * [pluginmgr]() - - + [pluginmgr](tcllib/files/modules/pluginmgr/pluginmgr\.md) Manage a plugin - - * [png]() - - + [png](tcllib/files/modules/png/png\.md) PNG querying and manipulation of meta data - - * [pop3]() - - + [pop3](tcllib/files/modules/pop3/pop3\.md) Tcl client for POP3 email protocol - - * [pop3d]() - - + [pop3d](tcllib/files/modules/pop3d/pop3d\.md) Tcl POP3 server implementation - - + [pop3d::dbox](tcllib/files/modules/pop3d/pop3d\_dbox\.md) Simple mailbox database for pop3d - - + [pop3d::udb](tcllib/files/modules/pop3d/pop3d\_udb\.md) Simple user database for pop3d - - * [practcl]() - - + [practcl](tcllib/files/modules/practcl/practcl\.md) The Practcl Module - - * [processman]() - - + [processman](tcllib/files/modules/processman/processman\.md) Tool for automating the period callback of commands - - * [profiler]() - - + [profiler](tcllib/files/modules/profiler/profiler\.md) Tcl source code profiler - - * [pt]() - - + [pt::ast](tcllib/files/modules/pt/pt\_astree\.md) Abstract Syntax Tree Serialization - - + [pt::cparam::configuration::critcl](tcllib/files/modules/pt/pt\_cparam\_config\_critcl\.md) C/PARAM, Canned configuration, Critcl - - + [pt::cparam::configuration::tea](tcllib/files/modules/pt/pt\_cparam\_config\_tea\.md) C/PARAM, Canned configuration, TEA - - + [pt::json\_language](tcllib/files/modules/pt/pt\_json\_language\.md) The JSON Grammar Exchange Format - - + [pt::param](tcllib/files/modules/pt/pt\_param\.md) PackRat Machine Specification - - + [pt::pe](tcllib/files/modules/pt/pt\_pexpression\.md) Parsing Expression Serialization - - + [pt::pe::op](tcllib/files/modules/pt/pt\_pexpr\_op\.md) Parsing Expression Utilities - - + [pt::peg](tcllib/files/modules/pt/pt\_pegrammar\.md) Parsing Expression Grammar Serialization - - + [pt::peg::container](tcllib/files/modules/pt/pt\_peg\_container\.md) PEG Storage - - + [pt::peg::container::peg](tcllib/files/modules/pt/pt\_peg\_container\_peg\.md) PEG Storage\. Canned PEG grammar specification - - + [pt::peg::export](tcllib/files/modules/pt/pt\_peg\_export\.md) PEG Export - - + [pt::peg::export::container](tcllib/files/modules/pt/pt\_peg\_export\_container\.md) PEG Export Plugin\. Write CONTAINER format - - + [pt::peg::export::json](tcllib/files/modules/pt/pt\_peg\_export\_json\.md) PEG Export Plugin\. Write JSON format - - + [pt::peg::export::peg](tcllib/files/modules/pt/pt\_peg\_export\_peg\.md) PEG Export Plugin\. Write PEG format - - + [pt::peg::from::container](tcllib/files/modules/pt/pt\_peg\_from\_container\.md) PEG Conversion\. From CONTAINER format - - + [pt::peg::from::json](tcllib/files/modules/pt/pt\_peg\_from\_json\.md) PEG Conversion\. Read JSON format - - + [pt::peg::from::peg](tcllib/files/modules/pt/pt\_peg\_from\_peg\.md) PEG Conversion\. Read PEG format - - + [pt::peg::import](tcllib/files/modules/pt/pt\_peg\_import\.md) PEG Import - - + [pt::peg::import::container](tcllib/files/modules/pt/pt\_peg\_import\_container\.md) PEG Import Plugin\. From CONTAINER format - - + [pt::peg::import::json](tcllib/files/modules/pt/pt\_peg\_import\_json\.md) PEG Import Plugin\. Read JSON format - - + [pt::peg::import::peg](tcllib/files/modules/pt/pt\_peg\_import\_peg\.md) PEG Import Plugin\. Read PEG format - - + [pt::peg::interp](tcllib/files/modules/pt/pt\_peg\_interp\.md) Interpreter for parsing expression grammars - - + [pt::peg::to::container](tcllib/files/modules/pt/pt\_peg\_to\_container\.md) PEG Conversion\. Write CONTAINER format - - + [pt::peg::to::cparam](tcllib/files/modules/pt/pt\_peg\_to\_cparam\.md) PEG Conversion\. Write CPARAM format - - + [pt::peg::to::json](tcllib/files/modules/pt/pt\_peg\_to\_json\.md) PEG Conversion\. Write JSON format - - + [pt::peg::to::param](tcllib/files/modules/pt/pt\_peg\_to\_param\.md) PEG Conversion\. Write PARAM format - - + [pt::peg::to::peg](tcllib/files/modules/pt/pt\_peg\_to\_peg\.md) PEG Conversion\. Write PEG format - - + [pt::peg::to::tclparam](tcllib/files/modules/pt/pt\_peg\_to\_tclparam\.md) PEG Conversion\. Write TCLPARAM format - - + [pt::peg\_language](tcllib/files/modules/pt/pt\_peg\_language\.md) PEG Language Tutorial - - + [pt::pegrammar](tcllib/files/modules/pt/pt\_peg\_introduction\.md) Introduction to Parsing Expression Grammars - - + [pt::pgen](tcllib/files/modules/pt/pt\_pgen\.md) Parser Generator - - + [pt::rde](tcllib/files/modules/pt/pt\_rdengine\.md) Parsing Runtime Support, PARAM based - - + [pt::tclparam::configuration::nx](tcllib/files/modules/pt/pt\_tclparam\_config\_nx\.md) Tcl/PARAM, Canned configuration, NX - - + [pt::tclparam::configuration::snit](tcllib/files/modules/pt/pt\_tclparam\_config\_snit\.md) Tcl/PARAM, Canned configuration, Snit - - + [pt::tclparam::configuration::tcloo](tcllib/files/modules/pt/pt\_tclparam\_config\_tcloo\.md) Tcl/PARAM, Canned configuration, Tcloo - - + [pt::util](tcllib/files/modules/pt/pt\_util\.md) General utilities - - + [pt\_export\_api](tcllib/files/modules/pt/pt\_to\_api\.md) Parser Tools Export API - - + [pt\_import\_api](tcllib/files/modules/pt/pt\_from\_api\.md) Parser Tools Import API - - + [pt\_introduction](tcllib/files/modules/pt/pt\_introduction\.md) Introduction to Parser Tools - - + [pt\_parse\_peg](tcllib/files/modules/pt/pt\_parse\_peg\.md) Parser Tools PEG Parser - - + [pt\_parser\_api](tcllib/files/modules/pt/pt\_parser\_api\.md) Parser API - - + [pt\_peg\_op](tcllib/files/modules/pt/pt\_peg\_op\.md) Parser Tools PE Grammar Utility Operations - - * [rc4]() - - + [rc4](tcllib/files/modules/rc4/rc4\.md) Implementation of the RC4 stream cipher - - * [rcs]() - - + [rcs](tcllib/files/modules/rcs/rcs\.md) RCS low level utilities - - * [report]() - - + [report](tcllib/files/modules/report/report\.md) Create and manipulate report objects - - * [rest]() - - + [rest](tcllib/files/modules/rest/rest\.md) define REST web APIs and call them inline or asychronously - - * [ripemd]() - - + [ripemd128](tcllib/files/modules/ripemd/ripemd128\.md) RIPEMD\-128 Message\-Digest Algorithm - - + [ripemd160](tcllib/files/modules/ripemd/ripemd160\.md) RIPEMD\-160 Message\-Digest Algorithm - - * [sasl]() - - + [SASL](tcllib/files/modules/sasl/sasl\.md) Implementation of SASL mechanisms for Tcl - - + [SASL::NTLM](tcllib/files/modules/sasl/ntlm\.md) Implementation of SASL NTLM mechanism for Tcl - - + [SASL::SCRAM](tcllib/files/modules/sasl/scram\.md) Implementation of SASL SCRAM mechanism for Tcl - - + [SASL::XGoogleToken](tcllib/files/modules/sasl/gtoken\.md) Implementation of SASL NTLM mechanism for Tcl - - * [sha1]() - - + [sha1](tcllib/files/modules/sha1/sha1\.md) SHA1 Message\-Digest Algorithm - - + [sha256](tcllib/files/modules/sha1/sha256\.md) SHA256 Message\-Digest Algorithm - - * [simulation]() - - + [simulation::annealing](tcllib/files/modules/simulation/annealing\.md) Simulated annealing - - + [simulation::montecarlo](tcllib/files/modules/simulation/montecarlo\.md) Monte Carlo simulations - - + [simulation::random](tcllib/files/modules/simulation/simulation\_random\.md) Pseudo\-random number generators - - * [smtpd]() - - + [smtpd](tcllib/files/modules/smtpd/smtpd\.md) Tcl SMTP server implementation - - * [snit]() - - + [snit](tcllib/files/modules/snit/snit\.md) Snit's Not Incr Tcl - - + [snitfaq](tcllib/files/modules/snit/snitfaq\.md) Snit Frequently Asked Questions - - * [soundex]() - - + [soundex](tcllib/files/modules/soundex/soundex\.md) Soundex - - * [stooop]() - - + [stooop](tcllib/files/modules/stooop/stooop\.md) Object oriented extension\. - - + [switched](tcllib/files/modules/stooop/switched\.md) switch/option management\. - - * [string]() - - + [string::token](tcllib/files/modules/string/token\.md) Regex based iterative lexing - - + [string::token::shell](tcllib/files/modules/string/token\_shell\.md) Parsing of shell command line - - * [stringprep]() - - + [stringprep](tcllib/files/modules/stringprep/stringprep\.md) Implementation of stringprep - - + [stringprep::data](tcllib/files/modules/stringprep/stringprep\_data\.md) stringprep data tables, generated, internal - - + [unicode](tcllib/files/modules/stringprep/unicode\.md) Implementation of Unicode normalization - - + [unicode::data](tcllib/files/modules/stringprep/unicode\_data\.md) unicode data tables, generated, internal - - * [struct]() - - + [struct::disjointset](tcllib/files/modules/struct/disjointset\.md) Disjoint set data structure - - + [struct::graph](tcllib/files/modules/struct/graph\.md) Create and manipulate directed graph objects - - + [struct::graph::op](tcllib/files/modules/struct/graphops\.md) Operation for \(un\)directed graph objects - - + [struct::graph\_v1](tcllib/files/modules/struct/graph1\.md) Create and manipulate directed graph objects - - + [struct::list](tcllib/files/modules/struct/struct\_list\.md) Procedures for manipulating lists - - + [struct::map](tcllib/files/modules/struct/struct\_map\.md) Manage key/value maps - - + [struct::matrix](tcllib/files/modules/struct/matrix\.md) Create and manipulate matrix objects - - + [struct::matrix\_v1](tcllib/files/modules/struct/matrix1\.md) Create and manipulate matrix objects - - + [struct::pool](tcllib/files/modules/struct/pool\.md) Create and manipulate pool objects \(of discrete items\) - - + [struct::prioqueue](tcllib/files/modules/struct/prioqueue\.md) Create and manipulate prioqueue objects - - + [struct::queue](tcllib/files/modules/struct/queue\.md) Create and manipulate queue objects - - + [struct::record](tcllib/files/modules/struct/record\.md) Define and create records \(similar to 'C' structures\) - - + [struct::set](tcllib/files/modules/struct/struct\_set\.md) Procedures for manipulating sets - - + [struct::skiplist](tcllib/files/modules/struct/skiplist\.md) Create and manipulate skiplists - - + [struct::stack](tcllib/files/modules/struct/stack\.md) Create and manipulate stack objects - - + [struct::tree](tcllib/files/modules/struct/struct\_tree\.md) Create and manipulate tree objects - - + [struct::tree\_v1](tcllib/files/modules/struct/struct\_tree1\.md) Create and manipulate tree objects - - * [tar]() - - + [tar](tcllib/files/modules/tar/tar\.md) Tar file creation, extraction & manipulation - - * [tepam]() - - + [tepam](tcllib/files/modules/tepam/tepam\_introduction\.md) An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager - - + [tepam::argument\_dialogbox](tcllib/files/modules/tepam/tepam\_argument\_dialogbox\.md) TEPAM argument\_dialogbox, reference manual - - + [tepam::doc\_gen](tcllib/files/modules/tepam/tepam\_doc\_gen\.md) TEPAM DOC Generation, reference manual - - + [tepam::procedure](tcllib/files/modules/tepam/tepam\_procedure\.md) TEPAM procedure, reference manual - - * [term]() - - + [term](tcllib/files/modules/term/term\.md) General terminal control - - + [term::ansi::code](tcllib/files/modules/term/ansi\_code\.md) Helper for control sequences - - + [term::ansi::code::attr](tcllib/files/modules/term/ansi\_cattr\.md) ANSI attribute sequences - - + [term::ansi::code::ctrl](tcllib/files/modules/term/ansi\_cctrl\.md) ANSI control sequences - - + [term::ansi::code::macros](tcllib/files/modules/term/ansi\_cmacros\.md) Macro sequences - - + [term::ansi::ctrl::unix](tcllib/files/modules/term/ansi\_ctrlu\.md) Control operations and queries - - + [term::ansi::send](tcllib/files/modules/term/ansi\_send\.md) Output of ANSI control sequences to terminals - - + [term::interact::menu](tcllib/files/modules/term/imenu\.md) Terminal widget, menu - - + [term::interact::pager](tcllib/files/modules/term/ipager\.md) Terminal widget, paging - - + [term::receive](tcllib/files/modules/term/receive\.md) General input from terminals - - + [term::receive::bind](tcllib/files/modules/term/term\_bind\.md) Keyboard dispatch from terminals - - + [term::send](tcllib/files/modules/term/term\_send\.md) General output to terminals - - * [textutil]() - - + [textutil](tcllib/files/modules/textutil/textutil\.md) Procedures to manipulate texts and strings\. - - + [textutil::adjust](tcllib/files/modules/textutil/adjust\.md) Procedures to adjust, indent, and undent paragraphs - - + [textutil::expander](tcllib/files/modules/textutil/expander\.md) Procedures to process templates and expand text\. - - + [textutil::patch](tcllib/files/modules/textutil/patch\.md) Application of uni\-diff patches to directory trees - - + [textutil::repeat](tcllib/files/modules/textutil/repeat\.md) Procedures to repeat strings\. - - + [textutil::split](tcllib/files/modules/textutil/textutil\_split\.md) Procedures to split texts - - + [textutil::string](tcllib/files/modules/textutil/textutil\_string\.md) Procedures to manipulate texts and strings\. - - + [textutil::tabify](tcllib/files/modules/textutil/tabify\.md) Procedures to \(un\)tabify strings - - + [textutil::trim](tcllib/files/modules/textutil/trim\.md) Procedures to trim strings - - * [tie]() - - + [tie](tcllib/files/modules/tie/tie\.md) Array persistence - - + [tie](tcllib/files/modules/tie/tie\_std\.md) Array persistence, standard data sources - - * [tiff]() - - + [tiff](tcllib/files/modules/tiff/tiff\.md) TIFF reading, writing, and querying and manipulation of meta data - - * [tool]() - - + [oo::util](tcllib/files/modules/tool/meta\.md) Utility commands for TclOO - - + [tool](tcllib/files/modules/tool/tool\.md) TclOO Library \(TOOL\) Framework - - + [tool::dict\_ensemble](tcllib/files/modules/tool/tool\_dict\_ensemble\.md) Dictionary Tools - - * [transfer]() - - + [transfer::connect](tcllib/files/modules/transfer/connect\.md) Connection setup - - + [transfer::copy](tcllib/files/modules/transfer/copyops\.md) Data transfer foundation - - + [transfer::copy::queue](tcllib/files/modules/transfer/tqueue\.md) Queued transfers - - + [transfer::data::destination](tcllib/files/modules/transfer/ddest\.md) Data destination - - + [transfer::data::source](tcllib/files/modules/transfer/dsource\.md) Data source - - + [transfer::receiver](tcllib/files/modules/transfer/receiver\.md) Data source - - + [transfer::transmitter](tcllib/files/modules/transfer/transmitter\.md) Data source - - * [treeql]() - - + [treeql](tcllib/files/modules/treeql/treeql\.md) Query tree objects - - * [try]() - - + [throw](tcllib/files/modules/try/tcllib\_throw\.md) throw \- Throw an error exception with a message - - + [try](tcllib/files/modules/try/tcllib\_try\.md) try \- Trap and process errors and exceptions - - * [udpcluster]() - - + [udpcluster](tcllib/files/modules/udpcluster/udpcluster\.md) UDP Peer\-to\-Peer cluster - - * [uev]() - - + [uevent](tcllib/files/modules/uev/uevent\.md) User events - - + [uevent::onidle](tcllib/files/modules/uev/uevent\_onidle\.md) Request merging and deferal to idle time - - * [units]() - - + [units](tcllib/files/modules/units/units\.md) unit conversion - - * [uri]() - - + [uri](tcllib/files/modules/uri/uri\.md) URI utilities - - + [uri\_urn](tcllib/files/modules/uri/urn\-scheme\.md) URI utilities, URN scheme - - * [uuid]() - - + [uuid](tcllib/files/modules/uuid/uuid\.md) UUID generation and comparison - - * [valtype]() - - + [valtype::common](tcllib/files/modules/valtype/valtype\_common\.md) Validation, common code - - + [valtype::creditcard::amex](tcllib/files/modules/valtype/cc\_amex\.md) Validation for AMEX creditcard number - - + [valtype::creditcard::discover](tcllib/files/modules/valtype/cc\_discover\.md) Validation for Discover creditcard number - - + [valtype::creditcard::mastercard](tcllib/files/modules/valtype/cc\_mastercard\.md) Validation for Mastercard creditcard number - - + [valtype::creditcard::visa](tcllib/files/modules/valtype/cc\_visa\.md) Validation for VISA creditcard number - - + [valtype::gs1::ean13](tcllib/files/modules/valtype/ean13\.md) Validation for EAN13 - - + [valtype::iban](tcllib/files/modules/valtype/iban\.md) Validation for IBAN - - + [valtype::imei](tcllib/files/modules/valtype/imei\.md) Validation for IMEI - - + [valtype::isbn](tcllib/files/modules/valtype/isbn\.md) Validation for ISBN - - + [valtype::luhn](tcllib/files/modules/valtype/luhn\.md) Validation for plain number with a LUHN checkdigit - - + [valtype::luhn5](tcllib/files/modules/valtype/luhn5\.md) Validation for plain number with a LUHN5 checkdigit - - + [valtype::usnpi](tcllib/files/modules/valtype/usnpi\.md) Validation for USNPI - - + [valtype::verhoeff](tcllib/files/modules/valtype/verhoeff\.md) Validation for plain number with a VERHOEFF checkdigit - - * [virtchannel\_base]() - - + [tcl::chan::cat](tcllib/files/modules/virtchannel\_base/cat\.md) Concatenation channel - - + [tcl::chan::facade](tcllib/files/modules/virtchannel\_base/facade\.md) Facade channel - - + [tcl::chan::fifo](tcllib/files/modules/virtchannel\_base/tcllib\_fifo\.md) In\-memory fifo channel - - + [tcl::chan::fifo2](tcllib/files/modules/virtchannel\_base/tcllib\_fifo2\.md) In\-memory interconnected fifo channels - - + [tcl::chan::halfpipe](tcllib/files/modules/virtchannel\_base/halfpipe\.md) In\-memory channel, half of a fifo2 - - + [tcl::chan::memchan](tcllib/files/modules/virtchannel\_base/tcllib\_memchan\.md) In\-memory channel - - + [tcl::chan::null](tcllib/files/modules/virtchannel\_base/tcllib\_null\.md) Null channel - - + [tcl::chan::nullzero](tcllib/files/modules/virtchannel\_base/nullzero\.md) Null/Zero channel combination - - + [tcl::chan::random](tcllib/files/modules/virtchannel\_base/tcllib\_random\.md) Random channel - - + [tcl::chan::std](tcllib/files/modules/virtchannel\_base/std\.md) Standard I/O, unification of stdin and stdout - - + [tcl::chan::string](tcllib/files/modules/virtchannel\_base/tcllib\_string\.md) Read\-only in\-memory channel - - + [tcl::chan::textwindow](tcllib/files/modules/virtchannel\_base/textwindow\.md) Textwindow channel - - + [tcl::chan::variable](tcllib/files/modules/virtchannel\_base/tcllib\_variable\.md) In\-memory channel using variable for storage - - + [tcl::chan::zero](tcllib/files/modules/virtchannel\_base/tcllib\_zero\.md) Zero channel - - + [tcl::randomseed](tcllib/files/modules/virtchannel\_base/randseed\.md) Utilities for random channels - - * [virtchannel\_core]() - - + [tcl::chan::core](tcllib/files/modules/virtchannel\_core/core\.md) Basic reflected/virtual channel support - - + [tcl::chan::events](tcllib/files/modules/virtchannel\_core/events\.md) Event support for reflected/virtual channels - - + [tcl::transform::core](tcllib/files/modules/virtchannel\_core/transformcore\.md) Basic reflected/virtual channel transform support - - * [virtchannel\_transform]() - - + [tcl::transform::adler32](tcllib/files/modules/virtchannel\_transform/adler32\.md) Adler32 transformation - - + [tcl::transform::base64](tcllib/files/modules/virtchannel\_transform/vt\_base64\.md) Base64 encoding transformation - - + [tcl::transform::counter](tcllib/files/modules/virtchannel\_transform/vt\_counter\.md) Counter transformation - - + [tcl::transform::crc32](tcllib/files/modules/virtchannel\_transform/vt\_crc32\.md) Crc32 transformation - - + [tcl::transform::hex](tcllib/files/modules/virtchannel\_transform/hex\.md) Hexadecimal encoding transformation - - + [tcl::transform::identity](tcllib/files/modules/virtchannel\_transform/identity\.md) Identity transformation - - + [tcl::transform::limitsize](tcllib/files/modules/virtchannel\_transform/limitsize\.md) limiting input - - + [tcl::transform::observe](tcllib/files/modules/virtchannel\_transform/observe\.md) Observer transformation, stream copy - - + [tcl::transform::otp](tcllib/files/modules/virtchannel\_transform/vt\_otp\.md) Encryption via one\-time pad - - + [tcl::transform::rot](tcllib/files/modules/virtchannel\_transform/rot\.md) rot\-encryption - - + [tcl::transform::spacer](tcllib/files/modules/virtchannel\_transform/spacer\.md) Space insertation and removal - - + [tcl::transform::zlib](tcllib/files/modules/virtchannel\_transform/tcllib\_zlib\.md) zlib \(de\)compression - - * [websocket]() - - + [websocket](tcllib/files/modules/websocket/websocket\.md) Tcl implementation of the websocket protocol - - * [wip]() - - + [wip](tcllib/files/modules/wip/wip\.md) Word Interpreter - - * [yaml]() - - + [huddle](tcllib/files/modules/yaml/huddle\.md) Create and manipulate huddle object - - + [yaml](tcllib/files/modules/yaml/yaml\.md) YAML Format Encoder/Decoder - - * [zip]() - - + [zipfile::decode](tcllib/files/modules/zip/decode\.md) Access to zip archives - - + [zipfile::encode](tcllib/files/modules/zip/encode\.md) Generation of zip archives - - + [zipfile::mkzip](tcllib/files/modules/zip/mkzip\.md) Build a zip archive DELETED embedded/md/toc2.md Index: embedded/md/toc2.md ================================================================== --- embedded/md/toc2.md +++ embedded/md/toc2.md @@ -1,20 +0,0 @@ - -[//000000001]: # (Table of contents generated by tcllib/doctools/toc with format 'markdown') - -# Table Of Contents \-\- - - - [Applications]() - - * [dtplite](tcllib/files/apps/dtplite\.md) Lightweight DocTools Markup Processor - - * [nns](tcllib/files/apps/nns\.md) Name service facility, Commandline Client Application - - * [nnsd](tcllib/files/apps/nnsd\.md) Name service facility, Commandline Server Application - - * [nnslog](tcllib/files/apps/nnslog\.md) Name service facility, Commandline Logging Client Application - - * [page](tcllib/files/apps/page\.md) Parser Generator - - * [pt](tcllib/files/apps/pt\.md) Parser Tools Application - - * [tcldocstrip](tcllib/files/apps/tcldocstrip\.md) Tcl\-based Docstrip Processor ADDED embedded/www/image/arch_core_container.png Index: embedded/www/image/arch_core_container.png ================================================================== --- embedded/www/image/arch_core_container.png +++ embedded/www/image/arch_core_container.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_eplugins.png Index: embedded/www/image/arch_core_eplugins.png ================================================================== --- embedded/www/image/arch_core_eplugins.png +++ embedded/www/image/arch_core_eplugins.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_export.png Index: embedded/www/image/arch_core_export.png ================================================================== --- embedded/www/image/arch_core_export.png +++ embedded/www/image/arch_core_export.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_import.png Index: embedded/www/image/arch_core_import.png ================================================================== --- embedded/www/image/arch_core_import.png +++ embedded/www/image/arch_core_import.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_iplugins.png Index: embedded/www/image/arch_core_iplugins.png ================================================================== --- embedded/www/image/arch_core_iplugins.png +++ embedded/www/image/arch_core_iplugins.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_support.png Index: embedded/www/image/arch_core_support.png ================================================================== --- embedded/www/image/arch_core_support.png +++ embedded/www/image/arch_core_support.png cannot compute difference between binary files ADDED embedded/www/image/arch_core_transform.png Index: embedded/www/image/arch_core_transform.png ================================================================== --- embedded/www/image/arch_core_transform.png +++ embedded/www/image/arch_core_transform.png cannot compute difference between binary files ADDED embedded/www/image/arch_user_app.png Index: embedded/www/image/arch_user_app.png ================================================================== --- embedded/www/image/arch_user_app.png +++ embedded/www/image/arch_user_app.png cannot compute difference between binary files ADDED embedded/www/image/arch_user_pkg.png Index: embedded/www/image/arch_user_pkg.png ================================================================== --- embedded/www/image/arch_user_pkg.png +++ embedded/www/image/arch_user_pkg.png cannot compute difference between binary files ADDED embedded/www/image/architecture.png Index: embedded/www/image/architecture.png ================================================================== --- embedded/www/image/architecture.png +++ embedded/www/image/architecture.png cannot compute difference between binary files ADDED embedded/www/image/expr_ast.png Index: embedded/www/image/expr_ast.png ================================================================== --- embedded/www/image/expr_ast.png +++ embedded/www/image/expr_ast.png cannot compute difference between binary files ADDED embedded/www/image/flow.png Index: embedded/www/image/flow.png ================================================================== --- embedded/www/image/flow.png +++ embedded/www/image/flow.png cannot compute difference between binary files ADDED embedded/www/image/gen_options.png Index: embedded/www/image/gen_options.png ================================================================== --- embedded/www/image/gen_options.png +++ embedded/www/image/gen_options.png cannot compute difference between binary files ADDED embedded/www/index.html Index: embedded/www/index.html ================================================================== --- embedded/www/index.html +++ embedded/www/index.html @@ -0,0 +1,4390 @@ +
+ +
[ + Table Of Contents +| Categories +| Modules +| Applications + ]
+

Keyword Index

+
+ . · / · 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Keywords: . +
.ddt + docstrip_util +
.dtx + docstrip · docstrip_util · tcldocstrip +
+Keywords: / +
/dev/null + tcl::chan::null · tcl::chan::nullzero +
/dev/random + tcl::chan::random · tcl::randomseed +
/dev/zero + tcl::chan::nullzero · tcl::chan::zero +
+Keywords: 3 +
3DES + des · tclDES · tclDESjr +
+Keywords: A +
abstract syntax tree + grammar::me::util · grammar::me_ast +
acceptance + grammar::fa::dacceptor +
acceptor + grammar::fa::dacceptor +
active + transfer::connect +
adaptors + snit · snitfaq +
adjacency list + struct::graph::op +
adjacency matrix + struct::graph::op +
adjacent + struct::graph · struct::graph::op +
adjusting + textutil::adjust +
adler32 + tcl::transform::adler32 +
aes + aes +
after + coroutine · coroutine::auto +
alias + interp +
amazon + S3 +
ambiguous + grammar::aycock +
American Express + valtype::creditcard::amex +
AMEX + valtype::creditcard::amex +
angle + math::geometry · units +
anonymous procedure + lambda +
ansi + term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix +
appender + logger::appender · logger::utils +
application + nns · nnsd · nnslog +
approximation algorithm + struct::graph::op +
arc + struct::graph · struct::graph::op +
arcfour + rc4 +
archive + tar +
argument integrity + tepam · tepam::procedure +
argument processing + cmdline +
argument validation + tepam · tepam::procedure +
arguments + tepam · tepam::procedure +
argv + cmdline +
argv0 + cmdline +
array + tie · tie +
articulation point + struct::graph::op +
ascii85 + ascii85 +
asn + asn +
assembler + grammar::me::cpu::gasm +
assert + control +
assign + struct::list +
AST + grammar::me_ast +
asynchronous + cache::async +
attribute control + term::ansi::code::attr · term::ansi::code::ctrl +
augmenting network + struct::graph::op +
augmenting path + struct::graph::op +
authentication + autoproxy · SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken +
automatic + nameserv::auto +
automatic documentation + tepam::doc_gen +
automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
aycock + grammar::aycock +
+Keywords: B +
bank + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban +
base32 + base32 · base32::core · base32::hex +
base64 + base64 · tcl::transform::base64 +
bash + string::token::shell +
bee + bee +
bench language + bench_intro · bench_lang_intro · bench_lang_spec +
benchmark + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec +
ber + asn +
Bessel functions + math::special +
bfs + struct::graph::op +
bibliography + bibtex +
bibtex + bibtex +
bignums + math::bignum +
bind + uevent +
bipartite + struct::graph::op +
BitTorrent + bee +
bittorrent + bee +
blanks + textutil::repeat +
block cipher + aes · blowfish · des · tclDES · tclDESjr +
blocking flow + struct::graph::op +
blowfish + blowfish +
Book Number + valtype::isbn +
breadth-first + struct::tree +
bridge + struct::graph::op +
BWidget + snit · snitfaq +
+Keywords: C +
C + doctools::msgcat::idx::c · doctools::msgcat::toc::c +
C++ + snit · snitfaq · stooop · switched +
cache + cache::async · map::slippy::cache +
caesar cipher + tcl::transform::rot +
calculus + math::calculus +
callback + cache::async · hook · lambda · oo::util · oo::util · uevent::onidle +
callbacks + tcl::chan::halfpipe +
capitalize + textutil::string +
card for credit + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa +
cardinality + struct::set +
cat + fileutil +
catalog package + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
catalogue + docstrip_util +
cell-phone + valtype::imei +
cer + asn +
CFG + grammar::me_intro +
CFL + grammar::me_intro +
CGI + ncgi +
cgraph + struct::graph · struct::graph_v1 +
changelog + doctools::changelog · doctools::cvs +
channel + coroutine · coroutine::auto · transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
channel transformation + tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
character input + term::receive · term::receive::bind +
character output + term::ansi::send · term::send +
chat + irc · multiplexer · picoirc +
checkbox + html · javascript +
checkbutton + html +
Checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
checksum + cksum · crc16 · crc32 · sum · tcl::transform::adler32 · tcl::transform::crc32 +
chop + textutil::string +
cipher + pki · tcl::transform::otp · tcl::transform::rot +
cksum + cksum · crc16 · crc32 · sum +
class + snit · snitfaq · stooop · switched +
class methods + oo::util · oo::util +
class variables + oo::util · oo::util +
cleanup + try +
client + nameserv · nameserv::auto · nameserv::common · nns · nns_intro · nnslog +
cloud + S3 +
cmdline processing + cmdline +
color control + term::ansi::code::attr · term::ansi::code::ctrl +
columns + term::ansi::ctrl::unix +
comm + comm · comm_wire · deleg_method · deleg_proc · nameserv::protocol +
command + doctools::tcl::parse +
command line processing + cmdline +
command prefix + lambda · oo::util · oo::util +
comment + jpeg · png +
common + struct::list +
common prefix + textutil::string +
communication + comm · comm_wire +
comparison + struct::list +
complete graph + struct::graph::op +
complex numbers + math::complexnumbers · math::fourier +
compression + tcl::transform::zlib · zipfile::encode +
computations + math::bigfloat +
concatenation channel + tcl::chan::cat · tcl::chan::facade +
connected component + struct::graph::op +
connected fifos + tcl::chan::fifo2 +
connection + transfer::connect +
constants + math::constants · units +
CONTAINER + pt::peg::export::container · pt::peg::to::container +
contents + doctools2toc_introduction +
context-free grammar + grammar::me_intro +
context-free languages + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
control + control · term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send +
control structure + generator +
conversion + doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · dtplite · dtplite · math::roman · mpexpand · pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · tcldocstrip · units +
cooked + term::ansi::ctrl::unix +
cookie + ncgi +
copy + fileutil::multi · fileutil::multi::op · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
coroutine + coroutine · coroutine::auto · generator +
Cost + treeql +
counter + tcl::transform::counter +
counting + counter +
CPARAM + pt::peg::to::cparam +
crc + cksum · crc16 · crc32 · sum +
crc16 + crc16 +
crc32 + cksum · crc16 · crc32 · sum · tcl::transform::crc32 +
credit card + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa +
cron + cron +
cryptography + blowfish +
CSS + doctools::html::cssdefaults +
csv + bench::in · bench::out::csv · csv +
currying + lambda · oo::util · oo::util +
cut edge + struct::graph::op +
cut vertex + struct::graph::op +
CVS + rcs +
cvs + doctools::cvs +
cvs log + doctools::cvs +
cyclic redundancy check + cksum · crc16 · crc32 · sum +
+Keywords: D +
data analysis + math::statistics +
data destination + transfer::data::destination · transfer::receiver +
data entry form + tepam::argument_dialogbox +
data exchange + huddle · json · json::write · yaml +
data integrity + aes · cksum · crc16 · crc32 · des · pki · rc4 · sum · tclDES · tclDESjr +
data source + transfer::data::source · transfer::transmitter +
data structures + struct::record +
database + tie · tie +
dataflow + page_util_flow +
DE + doctools::msgcat::idx::de · doctools::msgcat::toc::de +
debug + debug · debug::caller · debug::heartbeat · debug::timestamp +
decimal + math::decimal +
declare + term::ansi::code +
decompression + tcl::transform::zlib · zipfile::decode · zipfile::mkzip +
decryption + tcl::transform::otp · tcl::transform::rot +
deferal + uevent::onidle +
define + term::ansi::code +
degree + struct::graph · struct::graph::op +
degree constrained spanning tree + struct::graph::op +
degrees + math::constants +
delegation + deleg_method · deleg_proc +
depth-first + struct::tree +
der + asn +
DES + des · tclDES · tclDESjr +
deserialization + doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::structure · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::structure +
diameter + struct::graph::op +
dict + dicttool +
diff + docstrip_util · struct::list +
diff -n format + rcs +
difference + struct::set +
differential + struct::list +
differential equations + math::calculus +
dijkstra + struct::graph::op +
directory access + ldap · ldapx +
directory traversal + fileutil_traverse +
Discover + valtype::creditcard::discover +
discrete items + struct::pool +
disjoint set + struct::disjointset +
dispatcher + term::receive::bind +
distance + math::geometry · struct::graph::op · units +
DNS + dns +
do + control +
docidx + doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · dtplite · dtplite +
docidx commands + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docidx language + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docidx markup + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · doctools::idx +
docidx syntax + docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docstrip + docstrip · docstrip_util · tcldocstrip +
doctoc + doctools::msgcat · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite +
doctoc commands + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctoc language + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctoc markup + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctools::toc +
doctoc syntax + doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctools + docstrip_util · doctools::changelog · doctools::html::cssdefaults · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::nroff::man_macros · doctools::tcl::parse · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite +
doctools commands + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools language + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools markup + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools syntax + doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
document + doctools_plugin_apiref +
documentation + docstrip · docstrip_util · doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · tcldocstrip · tepam::doc_gen +
DOM + treeql +
dom + xsxp +
domain name service + dns +
+Keywords: E +
e + math::constants +
EAN + valtype::gs1::ean13 · valtype::isbn +
EAN13 + valtype::gs1::ean13 · valtype::isbn +
earley + grammar::aycock +
EBNF + pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
eccentricity + struct::graph::op +
edge + struct::graph · struct::graph::op +
emacs + doctools::changelog · doctools::cvs +
email + imap4 · mime · pop3 · smtp +
emptiness + struct::set +
empty interpreter + interp +
EN + doctools::msgcat::idx::en · doctools::msgcat::toc::en +
encoding + ascii85 · base64 · uuencode · yencode +
encryption + aes · blowfish · des · pki · rc4 · tcl::transform::otp · tcl::transform::rot · tclDES · tclDESjr +
entry mask + tepam +
equal + struct::list +
equality + struct::list +
equivalence class + struct::disjointset +
error + throw · try +
error function + math::special +
European Article Number + valtype::gs1::ean13 · valtype::isbn +
event + hook · uevent · uevent::onidle +
event management + tcl::chan::events +
events + coroutine · coroutine::auto +
examples + bench_lang_intro · docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq +
exception + try +
exchange format + huddle · json · json::write +
exclusion + struct::set +
execution + grammar::fa::dexec +
exif + jpeg +
exit + coroutine · coroutine::auto +
export + doctools::html::cssdefaults · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::nroff::man_macros · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg +
expression + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
extended namespace + namespacex +
+Keywords: F +
faq + docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq +
fetching information + uri +
FFT + math::fourier +
fifo + tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe +
file + tie · tie · uri +
file recognition + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt +
file type + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt +
file utilities + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · fileutil::multi · fileutil::multi::op +
filesystem + map::slippy::cache +
filter + generator · struct::list +
final + try +
finance + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban +
find + struct::disjointset +
finite + struct::pool +
finite automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
FIPS 180-1 + sha1 · sha256 +
first permutation + struct::list +
Fisher-Yates + struct::list +
flatten + struct::list +
floating-point + math::bigfloat · math::fuzzy +
flow + control +
flow network + struct::graph::op +
folding + struct::list +
foldl + generator +
foldr + generator +
foreach + generator +
form + html · ncgi +
format conversion + pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam +
formatter + doctools_plugin_apiref +
formatting + bench::in · bench::out::csv · bench::out::text · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export · textutil · textutil::adjust · textutil::string · textutil::tabify +
formatting engine + docidx_plugin_apiref · doctoc_plugin_apiref · doctools_plugin_apiref +
Fourier transform + math::fourier +
FR + doctools::msgcat::idx::fr · doctools::msgcat::toc::fr +
frame + term::ansi::code::macros +
ftp + ftp · ftp::geturl · ftpd · uri +
ftpd + ftpd +
ftpserver + ftpd +
full outer join + struct::list +
+Keywords: G +
generate event + uevent +
generate permutations + struct::list +
generation + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
generator + generator +
geocoding + map::geocode::nominatim +
geodesy + map::slippy · mapproj +
geography + map::slippy +
get character + term::receive +
gets + coroutine · coroutine::auto +
global + coroutine · coroutine::auto +
gopher + uri +
gps + gpx · nmea +
gpx + gpx +
grammar + grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
graph + grammar::me::cpu::gasm · struct::graph · struct::graph::op · struct::graph_v1 · struct::queue · struct::stack +
graph walking + page_util_flow · page_util_norm_lemon · page_util_norm_peg +
green threads + coroutine · coroutine::auto +
grep + fileutil +
GUID + uuid +
+Keywords: H +
hashing + md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 +
heartbeat + debug::heartbeat +
heuristic + struct::graph::op +
hex + base32::hex +
hexadecimal + tcl::transform::hex +
histogram + counter +
hook + hook · uevent +
horspool + grammar::aycock +
HTML + doctools · doctools::html::cssdefaults · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::html · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::html · dtplite · dtplite · mpexpand +
html + html · htmlparse · javascript · ncgi +
http + autoproxy · map::geocode::nominatim · map::slippy::fetcher · uri · websocket +
huddle + huddle · yaml +
human readable + bench::in · bench::out::text +
hyphenation + textutil · textutil::adjust +
+Keywords: I +
i18n + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
IBAN + valtype::iban +
ident + ident +
identification + ident +
identity + tcl::transform::identity +
idle + uevent::onidle +
image + jpeg · png · tiff +
imap + imap4 +
IMEI + valtype::imei +
import + doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json · pt::peg::import::json · pt::peg::import::peg +
in-memory channel + tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::string · tcl::chan::variable +
in-order + struct::tree +
inclusion + struct::set +
Incr Tcl + snit · snitfaq +
indenting + textutil · textutil::adjust +
independent set + struct::graph::op +
index + docidx_intro · docidx_plugin_apiref · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json +
index formatter + docidx_plugin_apiref +
info + namespacex +
inner join + struct::list +
input mode + term::ansi::ctrl::unix +
integer + math::roman +
integration + math::calculus +
inter-thread communication + tcl::chan::fifo2 +
International Article Number + valtype::gs1::ean13 · valtype::isbn +
International Bank Account Number + valtype::iban +
International Mobile Equipment Identity + valtype::imei +
International Standard Book Number + valtype::isbn +
internationalization + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
internet + asn · ftp · ftp::geturl · imap4 · ldap · ldapx · mime · pop3d · pop3d::dbox · pop3d::udb · smtp · websocket +
internet address + tcllib_ip +
interpolation + math::interpolate +
interpreter + deleg_method · deleg_proc · interp · wip +
intersection + struct::set +
interval + math::bigfloat +
ip + tcllib_ip +
ipc + comm · comm_wire +
ipv4 + tcllib_ip +
ipv6 + tcllib_ip +
irc + irc · picoirc +
isA + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
ISBN + valtype::isbn +
isthmus + struct::graph::op +
iterator + generator +
+Keywords: J +
javascript + javascript · json · json::write +
jfif + jpeg +
join + struct::list +
jpeg + jpeg +
JSON + doctools::idx::export::json · doctools::idx::import::json · doctools::toc::export::json · doctools::toc::import::json · pt::peg::export::json · pt::peg::from::json · pt::peg::import::json · pt::peg::to::json +
json + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · huddle · json · json::write +
justification + textutil::adjust +
+Keywords: K +
keyword index + docidx_intro · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import +
keywords + docidx_plugin_apiref +
knuth + soundex +
+Keywords: L +
l10n + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
lambda + lambda +
LaTeX + docstrip · docstrip_util · tcldocstrip +
latex + doctools::idx · doctools::idx · doctools::toc · doctools::toc +
latitute + map::slippy +
ldap + ldap · ldapx · uri +
ldap client + ldap · ldapx +
ldif + ldapx +
least squares + math::linearalgebra +
left outer join + struct::list +
lemon + page_util_norm_lemon +
level graph + struct::graph::op +
lexer + doctools::idx::parse · doctools::toc::parse +
lexing + string::token · string::token::shell +
limitsize + tcl::transform::limitsize +
line + math::geometry +
linear algebra + math::linearalgebra +
linear equations + math::linearalgebra +
linear program + math::optimize +
lines + term::ansi::ctrl::unix +
list + struct::list · struct::queue · wip +
listener + term::receive · term::receive::bind +
literate programming + docstrip · docstrip_util · tcldocstrip +
LL(k) + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
local searching + struct::graph::op +
localization + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
location + map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher +
log + debug · debug::caller · debug::heartbeat · debug::timestamp · doctools::cvs · log · logger +
log level + log · logger +
logger + logger · logger::appender · logger::utils +
longest common subsequence + struct::list +
longitude + map::slippy +
loop + struct::graph · struct::graph::op +
luhn + valtype::luhn · valtype::luhn5 +
luhn-5 + valtype::luhn5 +
+Keywords: M +
macros + doctools::nroff::man_macros +
mail + imap4 · mime · pop3 · smtp +
mailto + uri +
man_macros + doctools::nroff::man_macros +
manpage + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_plugin_apiref · dtplite · dtplite · mpexpand +
map + generator · map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher · mapproj · struct::list +
markup + docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref · dtplite · dtplite · mpexpand · tcldocstrip +
MasterCard + valtype::creditcard::mastercard +
matching + grammar::me_intro · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · struct::graph::op +
math + math · math::bigfloat · math::bignum · math::calculus · math::complexnumbers · math::constants · math::decimal · math::fuzzy · math::geometry · math::interpolate · math::linearalgebra · math::optimize · math::polynomials · math::rationalfunctions · math::special · simulation::annealing · simulation::montecarlo · simulation::random +
mathematics + math::fourier · math::statistics +
matrices + math::linearalgebra +
matrix + csv · math::linearalgebra · report · struct::matrix · struct::matrix_v1 · struct::queue · struct::stack +
max cut + struct::graph::op +
maximum + math::optimize +
maximum flow + struct::graph::op +
md4 + md4 · ripemd128 · ripemd160 +
md5 + md5 · md5crypt +
md5crypt + md5crypt +
medicare + valtype::usnpi +
mega widget + snit · snitfaq +
membership + struct::set +
menu + term::ansi::code::macros · term::interact::menu +
merge + tcl::randomseed · uevent::onidle +
merge find + struct::disjointset +
merging + bench +
message + comm · comm_wire · log +
message catalog + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
message level + log +
message package + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
message-digest + md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 +
metakit + tie · tie +
method + deleg_method · interp +
method reference + oo::util · oo::util +
mime + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::rt · mime · smtp +
minimal spanning tree + struct::graph::op +
minimum + math::optimize +
minimum cost flow + struct::graph::op +
minimum degree spanning tree + struct::graph::op +
minimum diameter spanning tree + struct::graph::op +
mobile phone + valtype::imei +
module + docstrip_util +
montecarlo simulation + simulation::montecarlo +
move + fileutil::multi · fileutil::multi::op +
multi-file + fileutil::multi · fileutil::multi::op +
multiplexer + multiplexer +
multiprecision + math::bigfloat · math::bignum +
my method + oo::util · oo::util +
+Keywords: N +
name service + nameserv · nameserv::auto · nameserv::common · nameserv::protocol · nameserv::server · nns · nns_intro · nnsd · nnslog · udpcluster +
namespace unknown + namespacex +
namespace utilities + namespacex +
narrative + debug · debug::caller · debug::heartbeat · debug::timestamp +
National Provider Identifier + valtype::usnpi +
neighbour + struct::graph · struct::graph::op +
net + ftp · ftp::geturl · imap4 · mime · smtp · websocket +
nettool + nettool +
network + pop3d · pop3d::dbox · pop3d::udb +
news + nntp · uri +
next permutation + struct::list +
nmea + nmea +
nntp + nntp +
nntpclient + nntp +
no-op + control +
node + struct::graph · struct::graph::op · struct::tree +
nominatim + map::geocode::nominatim +
normalization + bench · page_util_norm_lemon · page_util_norm_peg · unicode +
NPI + valtype::usnpi +
nroff + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::nroff · doctools::nroff::man_macros · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::nroff · dtplite · dtplite · mpexpand +
NTLM + SASL::NTLM +
NTP + ntp_time +
null + tcl::chan::null · tcl::chan::nullzero +
number theory + math::numtheory +
+Keywords: O +
oauth + oauth +
object + snit · snitfaq · stooop · switched +
object oriented + snit · snitfaq · stooop · switched +
observer + hook · tcl::transform::observe +
odie + cron · nettool · processman +
on-idle + uevent::onidle +
one time pad + tcl::transform::otp +
optimization + math::optimize · simulation::annealing +
ordered list + struct::prioqueue +
otp + tcl::transform::otp +
outer join + struct::list +
+Keywords: P +
package + csv +
package indexing + docstrip_util +
page + page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote +
pager + term::interact::pager +
paragraph + textutil · textutil::adjust +
PARAM + pt::peg::to::param +
parameter entry form + tepam · tepam::argument_dialogbox +
parser + doctools::idx::parse · doctools::tcl::parse · doctools::toc::parse · grammar::aycock · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · xsxp +
parser generator + page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote +
parsing + bench::in · bibtex · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::import · doctools::toc · doctools::toc::import · grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · htmlparse · huddle · string::token::shell · yaml +
parsing expression + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
parsing expression grammar + grammar::me_intro · grammar::peg · grammar::peg::interp · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
partial application + lambda +
partition + struct::disjointset +
partitioned set + struct::disjointset +
passive + transfer::connect +
password + otp +
patch + docstrip_util +
patching + rcs +
PEG + grammar::me_intro · page_util_norm_peg · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
performance + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec · profiler +
permutation + struct::list +
persistence + tie · tie +
phone + valtype::imei +
pi + math::constants +
plain text + doctools::idx::export::text · doctools::toc::export::text +
plane geometry + math::geometry +
plugin + docidx_plugin_apiref · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools::html::cssdefaults · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::nroff::man_macros · doctools::toc · doctools::toc::export · doctools::toc::import · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::import::json · pt::peg::import::peg +
plugin management + pluginmgr +
plugin search + pluginmgr +
png + png +
point + math::geometry +
polynomial functions + math::polynomials +
pool + struct::pool · struct::queue +
pop + pop3 +
pop3 + pop3 · pop3d · pop3d::dbox · pop3d::udb +
post-order + struct::tree +
practcl + practcl +
pre-order + struct::tree +
prefix + textutil::string · textutil::trim +
prime + math::numtheory +
prioqueue + struct::prioqueue · struct::queue +
priority queue + struct::prioqueue +
proc + lambda +
procedure + deleg_proc · tepam · tepam::procedure +
procedure documentation + tepam::doc_gen +
processman + processman +
producer + hook +
profile + profiler +
projection + mapproj +
prospero + uri +
protocol + asn · ldap · ldapx · nameserv::protocol · pop3d · pop3d::dbox · pop3d::udb +
proxy + autoproxy +
public key cipher + pki +
publisher + hook +
push down automaton + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
+Keywords: Q +
queue + csv · htmlparse · struct::stack · transfer::copy::queue +
quoting + page_util_quote +
+Keywords: R +
radians + math::constants · units +
radiobutton + html +
radius + struct::graph::op +
random + tcl::chan::random · tcl::randomseed +
random numbers + simulation::random +
rational functions + math::rationalfunctions +
raw + term::ansi::ctrl::unix +
rc4 + rc4 +
RCS + rcs +
RCS patch + rcs +
read + coroutine · coroutine::auto +
reading + bench::in +
receiver + term::receive · term::receive::bind · transfer::receiver +
reconnect + nameserv::auto +
record + struct::queue · struct::record +
recursive descent + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
reduce + generator · struct::list +
reference + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import +
reflected channel + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
regex + string::token +
regular expression + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · textutil · textutil::split · textutil::trim +
regular grammar + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
regular languages + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
remote communication + comm · comm_wire +
remote execution + comm · comm_wire +
remove + fileutil::multi · fileutil::multi::op +
repeating + struct::list +
repetition + struct::list · textutil::repeat +
report + report +
reshuffle + struct::list +
residual graph + struct::graph::op +
resolver + dns +
resource management + try +
restore + nameserv::auto +
return + throw +
reverse + struct::list +
rfc 821 + mime · smtp · smtpd +
rfc 822 + mime · pop3d::dbox · smtp +
rfc 868 + ntp_time +
rfc 959 + ftp · ftp::geturl · ftpd +
rfc 977 + nntp +
rfc 1034 + dns +
rfc 1035 + dns +
rfc 1036 + nntp +
rfc 1320 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1321 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1413 + ident +
rfc 1886 + dns +
rfc 1939 + pop3 · pop3d +
rfc 2030 + ntp_time +
rfc 2045 + mime +
rfc 2046 + mime +
rfc 2049 + mime +
rfc 2104 + md4 · md5 · ripemd128 · ripemd160 · sha1 · sha256 +
rfc 2141 + uri_urn +
rfc 2251 + ldap · ldapx +
rfc 2255 + uri +
rfc 2289 + otp +
rfc 2396 + uri +
rfc 2554 + smtp +
RFC 2718 + oauth +
rfc 2821 + smtp · smtpd +
rfc 2849 + ldapx +
rfc 3207 + smtp +
rfc 3513 + tcllib_ip +
rfc 4511 + ldap +
RFC 5849 + oauth +
rfc 6455 + websocket +
rfc3501 + imap4 +
rfc3548 + base32 · base32::hex +
right outer join + struct::list +
RIPEMD + ripemd128 · ripemd160 +
roman numeral + math::roman +
roots + math::calculus +
rot + tcl::transform::rot +
rot13 + tcl::transform::rot +
rounding + math::fuzzy +
rows + term::ansi::ctrl::unix +
rpc + comm · comm_wire +
rsa + pki +
running + grammar::fa::dexec +
+Keywords: S +
s3 + S3 +
SASL + SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken +
scanl + generator +
SCCS + rcs +
SCRAM + SASL::SCRAM +
secure + comm · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter +
security + aes · blowfish · cksum · crc16 · crc32 · des · md4 · md5 · md5crypt · otp · pki · rc4 · ripemd128 · ripemd160 · sha1 · sha256 · sum · tclDES · tclDESjr +
seed + tcl::randomseed +
selectionbox + javascript +
semantic markup + docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref +
send + comm +
serialization + bee · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::structure · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::structure · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::json · pt::peg::from::peg · pt::peg::import::json · pt::peg::import::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · struct::graph · struct::tree +
server + map::geocode::nominatim · map::slippy::fetcher · nameserv::common · nameserv::server · nns_intro · nnsd · udpcluster +
service + logger +
services + ftpd · smtpd +
set + struct::queue · struct::set +
sha1 + sha1 +
sha256 + sha256 +
shell + string::token::shell +
shortest path + struct::graph::op +
shuffle + struct::list +
simulated annealing + simulation::annealing +
simulation + simulation::random +
singleton + oo::util · oo::util +
size limit + tcl::transform::limitsize +
skiplist + struct::queue · struct::skiplist +
slippy + map::slippy · map::slippy::cache · map::slippy::fetcher +
smtp + mime · smtp · smtpd +
smtpd + smtpd +
Snit + snit +
snit + deleg_method · interp +
SNTP + ntp_time +
socket + comm · comm_wire · smtpd +
soundex + soundex +
source + docstrip · docstrip_util · tcldocstrip +
spacing + tcl::transform::spacer +
spatial interpolation + math::interpolate +
special functions + math::special +
specification + bench_lang_spec +
speed + profiler +
split + textutil::split +
squared graph + struct::graph::op +
ssl + comm · imap4 · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter +
stack + struct::queue +
standard io + tcl::chan::std +
state + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
state (de)serialization + namespacex +
statistical distribution + simulation::random +
statistics + counter · math · math::statistics +
stdin + tcl::chan::std +
stdout + tcl::chan::std +
stochastic modelling + simulation::montecarlo +
stream cipher + rc4 +
stream copy + tcl::transform::observe +
string + string::token · string::token::shell · textutil · textutil::adjust · textutil::expander · textutil::repeat · textutil::split · textutil::string · textutil::tabify · textutil::trim +
stringprep + stringprep · stringprep::data · unicode::data +
strongly connected component + struct::graph::op +
struct + struct::pool · struct::record +
structure + control +
structured queries + treeql +
style + doctools::html::cssdefaults +
subcommand + tepam · tepam::procedure +
subgraph + struct::graph · struct::graph::op +
subject + hook +
submitbutton + javascript +
subscriber + hook +
subsequence + struct::list +
subst + doctools::tcl::parse +
sum + sum +
swapping + struct::list +
symmetric difference + struct::set +
synchronous + cache::async +
syntax tree + grammar::me::util +
+Keywords: T +
table + doctools::toc · doctools::toc::export · doctools::toc::import · html · report +
table of contents + doctoc_intro · doctoc_plugin_apiref · doctools2toc_introduction · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json +
tabstops + textutil::tabify +
tallying + counter +
tape archive + tar +
tar + tar +
tcl + math::bigfloat · math::bignum · math::decimal +
Tcl module + docstrip_util +
Tcl syntax + doctools::tcl::parse +
tcler's wiki + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
tcllib + csv +
TclOO + oo::util · oo::util · tool · tool::dict_ensemble +
TCLPARAM + pt::peg::to::tclparam +
TDPL + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
temp file + fileutil +
template processing + textutil::expander +
terminal + term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send +
test + fileutil +
Testing + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
testing + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec +
TeX + textutil · textutil::adjust +
text + bench::in · bench::out::text · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
text comparison + soundex +
text conversion + rcs +
text differences + rcs +
text display + term::interact::menu · term::interact::pager +
text expansion + textutil::expander +
text likeness + soundex +
text processing + bibtex · huddle · page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote · yaml +
text widget + tcl::chan::textwindow +
threads + coroutine · coroutine::auto +
throw + throw +
thumbnail + jpeg +
tie + tie · tie +
tif + tiff +
tiff + tiff +
tile + map::slippy::cache · map::slippy::fetcher +
time + ntp_time +
timestamp + png +
timestamps + debug::timestamp +
tip 219 + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::core +
tip 230 + tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
tip 234 + tcl::transform::zlib +
tip 317 + tcl::transform::base64 +
Tk + tcl::chan::textwindow +
tls + comm · imap4 · pop3 · pop3d · smtp · transfer::connect · transfer::receiver · transfer::transmitter +
TMML + doctools · doctools::idx · doctools::idx · doctools::toc · doctools::toc · dtplite · dtplite · mpexpand +
toc + doctoc_intro · doctoc_plugin_apiref · doctools::toc · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json +
toc formatter + doctoc_plugin_apiref +
tokenization + string::token · string::token::shell +
TOOL + tool · tool::dict_ensemble +
top-down parsing languages + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
torrent + bee +
touch + fileutil +
TPDL + grammar::me_intro +
trace + debug · debug::caller · debug::heartbeat · debug::timestamp +
transducer + grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
transfer + transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
transformation + page_util_peg · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
transmitter + transfer::transmitter +
travelling salesman + struct::graph::op +
traversal + fileutil_traverse +
tree + grammar::me::cpu::gasm · grammar::me::util · htmlparse · struct::queue · struct::stack · struct::tree · struct::tree_v1 · treeql +
tree query language + treeql +
tree walking + page_util_flow · page_util_norm_lemon · page_util_norm_peg +
TreeQL + treeql +
trimming + textutil · textutil::trim +
twitter + oauth +
type + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · snit +
Type checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
+Keywords: U +
uevent + hook +
unbind + uevent +
uncapitalize + textutil::string +
undenting + textutil::adjust +
unicode + stringprep · stringprep::data · unicode · unicode::data +
union + struct::disjointset · struct::set +
unit + units +
unknown hooking + namespacex +
untie + tie · tie +
update + coroutine · coroutine::auto +
uri + uri · uri_urn +
url + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc::export · doctools::toc::import · map::geocode::nominatim · map::slippy::fetcher · uri · uri_urn +
urn + uri_urn +
US-NPI + valtype::usnpi +
utilities + namespacex +
uuencode + uuencode +
UUID + uuid +
+Keywords: V +
Validation + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
Value checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
vectors + math::linearalgebra +
verhoeff + valtype::verhoeff +
vertex + struct::graph · struct::graph::op +
vertex cover + struct::graph::op +
virtual channel + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
virtual machine + grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg::interp · pt::param +
VISA + valtype::creditcard::visa +
vwait + coroutine · coroutine::auto · smtpd +
+Keywords: W +
wais + uri +
widget + snit · snitfaq +
widget adaptors + snit · snitfaq +
wiki + doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::wiki · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::wiki +
word + doctools::tcl::parse · wip +
www + uri +
+Keywords: X +
x.208 + asn +
x.209 + asn +
x.500 + ldap +
XGoogleToken + SASL::XGoogleToken +
xml + xsxp +
xor + tcl::transform::otp +
XPath + treeql +
XSLT + treeql +
+Keywords: Y +
yaml + huddle · yaml +
ydecode + yencode +
yEnc + yencode +
yencode + yencode +
+Keywords: Z +
zero + tcl::chan::nullzero · tcl::chan::zero +
zip + zipfile::decode · zipfile::encode · zipfile::mkzip +
zlib + tcl::transform::zlib +
zoom + map::slippy · map::slippy::cache · map::slippy::fetcher +
ADDED embedded/www/tcllib/files/apps/dtplite.html Index: embedded/www/tcllib/files/apps/dtplite.html ================================================================== --- embedded/www/tcllib/files/apps/dtplite.html +++ embedded/www/tcllib/files/apps/dtplite.html @@ -0,0 +1,427 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

dtplite(n) 1.0.5 tcllib "Documentation toolbox"

+

Name

+

dtplite - Lightweight DocTools Markup Processor

+
+ + +

Description

+

The application described by this document, dtplite, is the +successor to the extremely simple mpexpand. Influenced in its +functionality by the dtp doctools processor it is much more +powerful than mpexpand, yet still as easy to use; definitely +easier than dtp with its myriad of subcommands and options.

+

dtplite is based upon the package doctools, like +the other two processors.

+

USE CASES

+

dtplite was written with the following three use cases in +mind.

+
    +

  1. Validation of a single document, i.e. checking that it was written in +valid doctools format. This mode can also be used to get a preliminary +version of the formatted output for a single document, for display in +a browser, nroff, etc., allowing proofreading of the formatting.

    2. +

  2. Generation of the formatted documentation for a single package, +i.e. all the manpages, plus a table of contents and an index of +keywords.

    3. +

  3. An extension of the previous mode of operation, a method for the easy +generation of one documentation tree for several packages, and +especially of a unified table of contents and keyword index.

    4. +
+

Beyond the above we also want to make use of the customization +features provided by the HTML formatter. It is not the only format the +application should be able to generate, but we anticipiate it to be +the most commonly used, and it is one of the few which do provide +customization hooks.

+

We allow the caller to specify a header string, footer string, a +stylesheet, and data for a bar of navigation links at the top of the +generated document. +While all can be set as long as the formatting engine provides an +appropriate engine parameter (See section OPTIONS) the last +two have internal processing which make them specific to HTML.

+
+

COMMAND LINE

+
+
dtplite -o output ?options? format inputfile
+

This is the form for use case [1]. The options will be +explained later, in section OPTIONS.

+
+
path output (in)
+

This argument specifies where to write the generated document. It can +be the path to a file or directory, or -. +The last value causes the application to write the generated +documented to stdout.

+

If the output does not exist then [file dirname $output] +has to exist and must be a writable directory. +The generated document will be written to a file in that directory, +and the name of that file will be derived from the inputfile, +the format, and the value given to option -ext (if +present).

+
(path|handle) format (in)
+

This argument specifies the formatting engine to use when processing +the input, and thus the format of the generated document. See section +FORMATS for the possibilities recognized by the application.

+
path inputfile (in)
+

This argument specifies the path to the file to process. It has to +exist, must be readable, and written in doctools format.

+
+
dtplite validate inputfile
+

This is a simpler form for use case [1]. The "validate" format +generates no output at all, only syntax checks are performed. As such +the specification of an output file or other options is not necessary +and left out.

+
dtplite -o output ?options? format inputdirectory
+

This is the form for use case [2]. It differs from the form for +use case [1] by having the input documents specified through a +directory instead of a file. The other arguments are identical, except +for output, which now has to be the path to an existing and +writable directory.

+

The input documents are all files in inputdirectory or any of +its subdirectories which were recognized by fileutil::fileType +as containing text in doctools format.

+
dtplite -merge -o output ?options? format inputdirectory
+

This is the form for use case [3]. The only difference to the +form for use case [2] is the additional option -merge.

+

Each such call will merge the generated documents coming from +processing the input documents under inputdirectory or any of +its subdirectories to the files under output. In this manner it +is possible to incrementally build the unified documentation for any +number of packages. Note that it is necessary to run through all the +packages twice to get fully correct cross-references (for formats +supporting them).

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application, with +the exception of the options -o and -merge. These +two were described already, in section COMMAND LINE.

+
+
-exclude string
+

This option specifies an exclude (glob) pattern. Any files identified +as manpages to process which match the exclude pattern are +ignored. The option can be provided multiple times, each usage adding +an additional pattern to the list of exclusions.

+
-ext string
+

If the name of an output file has to be derived from the name of an +input file it will use the name of the format as the extension +by default. This option here will override this however, forcing it to +use string as the file extension. This option is ignored if the +name of the output file is fully specified through option -o.

+

When used multiple times only the last definition is relevant.

+
-header file
+

This option can be used if and only if the selected format +provides an engine parameter named "header". It takes the contents of +the specified file and assign them to that parameter, for whatever use +by the engine. The HTML engine will insert the text just after the tag +<body>. +If navigation buttons are present (see option -nav below), +then the HTML generated for them is appended to the header data +originating here before the final assignment to the parameter.

+

When used multiple times only the last definition is relevant.

+
-footer file
+

Like -header, except that: Any navigation buttons are ignored, +the corresponding required engine parameter is named "footer", and the +data is inserted just before the tag </body>.

+

When used multiple times only the last definition is relevant.

+
-style file
+

This option can be used if and only if the selected format +provides an engine parameter named "meta". When specified it will +generate a piece of HTML code declaring the file as the +stylesheet for the generated document and assign that to the +parameter. The HTML engine will insert this inot the document, just +after the tag <head>.

+

When processing an input directory the stylesheet file is copied into +the output directory and the generated HTML will refer to the copy, to +make the result more self-contained. When processing an input file we +have no location to copy the stylesheet to and so just reference it as +specified.

+

When used multiple times only the last definition is relevant.

+
-toc path
+

This option specifies a doctoc file to use for the table of contents +instead of generating our own.

+

When used multiple times only the last definition is relevant.

+
-pre+toc label path|text
+
+
-post+toc label path|text
+

This option specifies additional doctoc files (or texts) to use in +the navigation bar.

+

Positioning and handling of multiple uses is like for options +-prenav and -postnav, see below.

+
-nav label url
+
+
-prenav label url
+

Use this option to specify a navigation button with label to +display and the url to link to. This option can be used if and +only if the selected format provides an engine parameter named +"header". The HTML generated for this is appended to whatever data we +got from option -header before it is inserted into the +generated documents.

+

When used multiple times all definitions are collected and a +navigation bar is created, with the first definition shown at the left +edge and the last definition to the right.

+

The url can be relative. In that case it is assumed to be relative +to the main files (TOC and Keyword index), and will be transformed for +all others to still link properly.

+
-postnav label url
+

Use this option to specify a navigation button with label to +display and the url to link to. This option can be used if and +only if the selected format provides an engine parameter named +"header". The HTML generated for this is appended to whatever data we +got from option -header before it is inserted into the +generated documents.

+

When used multiple times all definitions are collected and a +navigation bar is created, with the last definition shown at the right +edge and the first definition to the left.

+

The url can be relative. In that case it is assumed to be relative +to the main files (TOC and Keyword index), and will be transformed for +all others to still link properly.

+
+
+

FORMATS

+

At first the format argument will be treated as a path to a tcl +file containing the code for the requested formatting engine. The +argument will be treated as the name of one of the predefined formats +listed below if and only if the path does not exist.

+

Note a limitation: If treating the format as path to the tcl +script implementing the engine was sucessful, then this script has to +implement not only the engine API for doctools, i.e. +doctools_api, but for doctoc_api and docidx_api +as well. Otherwise the generation of a table of contents and of a +keyword index will fail.

+

List of predefined formats, i.e. as provided by the +package doctools:

+
+
nroff
+

The processor generates *roff output, the standard format for unix +manpages.

+
html
+

The processor generates HTML output, for usage in and display by web +browsers. This engine is currently the only one providing the various +engine parameters required for the additional customaization of the +output.

+
tmml
+

The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML.

+
latex
+

The processor generates LaTeX output.

+
wiki
+

The processor generates Wiki markup as understood by wikit.

+
list
+

The processor extracts the information provided by manpage_begin. +This format is used internally to extract the meta data from which +both table of contents and keyword index are derived from.

+
null
+

The processor does not generate any output. This is equivalent to +validate.

+
+
+

DIRECTORY STRUCTURES

+

In this section we describe the directory structures generated by the +application under output when processing all documents in an +inputdirectory. In other words, this is only relevant to the use +cases [2] and [3].

+
+
[2]
+

The following directory structure is created when processing a single +set of input documents. The file extension used is for output in +HTML, but that is not relevant to the structure and was just used to +have proper file names.

+
+    output/
+        toc.html
+        index.html
+        files/
+            path/to/FOO.html
+
+

The last line in the example shows the document +generated for a file FOO located at

+
+    inputdirectory/path/to/FOO
+
+
+
[3]
+

When merging many packages into a unified set of documents the +generated directory structure is a bit deeper:

+
+    output
+        .toc
+        .idx
+        .tocdoc
+        .idxdoc
+        .xrf
+        toc.html
+        index.html
+        FOO1/
+            ...
+        FOO2/
+            toc.html
+            files/
+                path/to/BAR.html
+
+

Each of the directories FOO1, ... contains the documents generated for +the package FOO1, ... and follows the structure shown for use case +[2]. The only exception is that there is no per-package index.

+

The files ".toc", ".idx", and ".xrf" contain the +internal status of the whole output and will be read and updated by +the next invokation. Their contents will not be documented. Remove +these files when all packages wanted for the output have been +processed, i.e. when the output is complete.

+

The files ".tocdoc", and ".idxdoc", are intermediate files +in doctoc and docidx markup, respectively, containing the main table +of contents and keyword index for the set of documents before their +conversion to the chosen output format. +They are left in place, i.e. not deleted, to serve as demonstrations +of doctoc and docidx markup.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/apps/nns.html Index: embedded/www/tcllib/files/apps/nns.html ================================================================== --- embedded/www/tcllib/files/apps/nns.html +++ embedded/www/tcllib/files/apps/nns.html @@ -0,0 +1,229 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nns(n) 1.1 tcllib "Name service facility"

+

Name

+

nns - Name service facility, Commandline Client Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

The application described by this document, nns, is a simple +command line client for the nano name service facility provided by the +Tcllib packages nameserv, and nameserv::server. +Beyond that the application's sources also serve as an example of how +to use the client package nameserv. All abilities of a +client are covered, from configuration to registration of names to +searching.

+

This name service facility has nothing to do with the Internet's +Domain Name System, otherwise known as DNS. If the +reader is looking for a package dealing with that please see either of +the packages dns and resolv, both found in Tcllib +too.

+

USE CASES

+

nns was written with the following two main use cases in +mind.

+
    +

  1. Registration of a name/data pair in the name service.

    2. +

  2. Searching the name service for entries matching a glob pattern.

    3. +
+

Beyond the above we also want to be able to identify the client, and +get information about the name service.

+
+

COMMAND LINE

+
+
nns bind ?-host host? ?-port port? name data
+

This form registers the name/data pair in the specified +name service. In this form the command will not exit to keep +the registration alive. The user has to kill it explicitly, either by +sending a signal, or through the job-control facilities of the shell +in use. It will especially survive the loss of the connection to the +name service and reestablish the name/data pair when the +connection is restored.

+

The options to specify the name service will be explained later, in +section OPTIONS.

+
nns search ?-host host? ?-port port? ?-continuous? ?pattern?
+

This form searches the specified name service for entries matching the +glob-pattern and prints them to stdout, with each entry on its +own line. If no pattern is specified it defaults to *, +matching everything.

+

The options to specify the name service will be explained later, in +section OPTIONS.

+

If the option -continuous is specified the client will not +exit after performing the search, but start to continuously monitor +the service for changes to the set of matching entries, appropriately +updating the display as changes arrive. In that form it will +especially also survive the loss of the connection to the name service +and reestablish the search when the connection is restored.

+
nns ident ?-host host? ?-port port?
+

This form asks the specified name service for the version and features +of the name service protocol it supports and prints the results to +stdout.

+

The options to specify the name service will be explained later, in +section OPTIONS.

+
nns who
+

This form prints name, version, and protocol version of the +application to stdout.

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application

+
+
-host name|ipaddress
+

If this option is not specified it defaults to localhost. It +specifies the name or ip-address of the host the name service to talk +to is running on.

+
-port number
+

If this option is not specified it defaults to 38573. It +specifies the TCP port the name service to talk to is listening on for +requests.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/nnsd.html Index: embedded/www/tcllib/files/apps/nnsd.html ================================================================== --- embedded/www/tcllib/files/apps/nnsd.html +++ embedded/www/tcllib/files/apps/nnsd.html @@ -0,0 +1,197 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nnsd(n) 1.0.1 tcllib "Name service facility"

+

Name

+

nnsd - Name service facility, Commandline Server Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

The application described by this document, nns, is a simple +command line server for the nano name service facility provided by the +Tcllib packages nameserv, and nameserv::server. +Beyond that the application's sources also serve as an example of how +to use the server package nameserv::server.

+

This name service facility has nothing to do with the Internet's +Domain Name System, otherwise known as DNS. If the +reader is looking for a package dealing with that please see either of +the packages dns and resolv, both found in Tcllib +too.

+

USE CASES

+

nnsd was written with the following main use case in +mind.

+
    +

  1. Run a nano name service on some host.

    2. +
+
+

COMMAND LINE

+
+
nnsd ?-localonly flag? ?-port port?
+

The command configures a server per the specified options and starts +it. The command will not exit on its own, as it keeps the name service +database wholly in memory. The user has to kill it explicitly, either +by sending a a signal, or through the job-control facilities of the +shell in use.

+

The options to configure the name service are explained in section +OPTIONS.

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application

+
+
-localonly bool
+

If this option is not specified it defaults to true, i.e. +acceptance of only local connections. The server will accept remote +connections, i.e. connections from other hosts, if and only if this +option is configured to false.

+
-port number
+

If this option is not specified it defaults to 38573. It +specifies the TCP port the server has to listen on for requests.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/nnslog.html Index: embedded/www/tcllib/files/apps/nnslog.html ================================================================== --- embedded/www/tcllib/files/apps/nnslog.html +++ embedded/www/tcllib/files/apps/nnslog.html @@ -0,0 +1,200 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nnslog(n) 1.0 tcllib "Name service facility"

+

Name

+

nnslog - Name service facility, Commandline Logging Client Application

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

The application described by this document, nnslog, is a +simple command line client for the nano name service facility provided +by the Tcllib packages nameserv, and nameserv::server.

+

It essentially implements "nns search -continuous *", but +uses a different output formatting. Instead of continuously showing +the current contents of the server in the terminal it simply logs all +received add/remove events to stdout.

+

This name service facility has nothing to do with the Internet's +Domain Name System, otherwise known as DNS. If the +reader is looking for a package dealing with that please see either of +the packages dns and resolv, both found in Tcllib +too.

+

USE CASES

+

nnslog was written with the following main use case in mind.

+
    +

  1. Monitoring the name service for all changes and logging them in a text +terminal.

    2. +
+
+

COMMAND LINE

+
+
nnslog ?-host host? ?-port port?
+

The command connects to the specified name service, sets up a search +for all changes and then prints all received events to stdout, with +each events on its own line. The command will not exit until it is +explicitly terminated by the user. It will especially survive the loss +of the connection to the name service and reestablish the search and +log when the connection is restored.

+

The options to specify the name service will be explained later, in +section OPTIONS.

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application

+
+
-host name|ipaddress
+

If this option is not specified it defaults to localhost. It +specifies the name or ip-address of the host the name service to talk +to is running on.

+
-port number
+

If this option is not specified it defaults to 38573. It +specifies the TCP port the name service to talk to is listening on for +requests.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/apps/page.html Index: embedded/www/tcllib/files/apps/page.html ================================================================== --- embedded/www/tcllib/files/apps/page.html +++ embedded/www/tcllib/files/apps/page.html @@ -0,0 +1,467 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page(n) 1.0 tcllib "Development Tools"

+

Name

+

page - Parser Generator

+
+ + +

Description

+

The application described by this document, page, is actually +not just a parser generator, as the name implies, but a generic tool +for the execution of arbitrary transformations on texts.

+

Its genericity comes through the use of plugins for reading, +transforming, and writing data, and the predefined set of plugins +provided by Tcllib is for the generation of memoizing recursive +descent parsers (aka packrat parsers) from grammar +specifications (Parsing Expression Grammars).

+

page is written on top of the package +page::pluginmgr, wrapping its functionality into a command +line based application. All the other page::* packages are +plugin and/or supporting packages for the generation of parsers. The +parsers themselves are based on the packages grammar::peg, +grammar::peg::interp, and grammar::mengine.

+

COMMAND LINE

+
+
page ?options...? ?input ?output??
+

This is general form for calling page. The application will +read the contents of the file input, process them under the +control of the specified options, and then write the result to +the file output.

+

If input is the string - the data to process will be +read from stdin instead of a file. Analogously the result will +be written to stdout instead of a file if output is the +string -. A missing output or input specification causes the +application to assume -.

+

The detailed specifications of the recognized options are +provided in section OPTIONS.

+
+
path input (in)
+

This argument specifies the path to the file to be processed by the +application, or -. The last value causes the application to +read the text from stdin. Otherwise it has to exist, and be +readable. If the argument is missing - is assumed.

+
path output (in)
+

This argument specifies where to write the generated text. It can be +the path to a file, or -. The last value causes the +application to write the generated documented to stdout.

+

If the file output does not exist then +[file dirname $output] has to exist and must be a writable +directory, as the application will create the fileto write to.

+

If the argument is missing - is assumed.

+
+
+
+

OPERATION

+

... reading ... transforming ... writing - plugins - pipeline ...

+
+

OPTIONS

+

This section describes all the options available to the user of the +application. Options are always processed in order. I.e. of both +--help and --version are specified the option +encountered first has precedence.

+

Unknown options specified before any of the options -rd, +-wr, or -tr will cause processing to abort with an +error. Unknown options coming in between these options, or after the +last of them are assumed to always take a single argument and are +associated with the last plugin option coming before them. They will +be checked after all the relevant plugins, and thus the options they +understand, are known. I.e. such unknown options cause error if and +only if the plugin option they are associated with does not understand +them, and was not superceded by a plugin option coming after.

+

Default options are used if and only if the command line did not +contain any options at all. They will set the application up as a +PEG-based parser generator. The exact list of options is

+
-c peg
+

And now the recognized options and their arguments, if they have any:

+
+
--help
+
+
-h
+
+
-?
+

When one of these options is found on the command line all arguments +coming before or after are ignored. The application will print a short +description of the recognized options and exit.

+
--version
+
+
-V
+

When one of these options is found on the command line all arguments +coming before or after are ignored. The application will print its +own revision and exit.

+
-P
+

This option signals the application to activate visual feedback while +reading the input.

+
-T
+

This option signals the application to collect statistics while +reading the input and to print them after reading has completed, +before processing started.

+
-D
+

This option signals the application to activate logging in the Safe +base, for the debugging of problems with plugins.

+
-r parser
+
+
-rd parser
+
+
--reader parser
+

These options specify the plugin the application has to use for +reading the input. If the options are used multiple times the +last one will be used.

+
-w generator
+
+
-wr generator
+
+
--writer generator
+

These options specify the plugin the application has to use for +generating and writing the final output. If the options are used +multiple times the last one will be used.

+
-t process
+
+
-tr process
+
+
--transform process
+

These options specify a plugin to run on the input. In contrast to +readers and writers each use will not supersede previous +uses, but add each chosen plugin to a list of transformations, either +at the front, or the end, per the last seen use of either option +-p or -a. The initial default is to append the new +transformations.

+
-a
+
+
--append
+

These options signal the application that all following +transformations should be added at the end of the list of +transformations.

+
-p
+
+
--prepend
+

These options signal the application that all following +transformations should be added at the beginning of the list of +transformations.

+
--reset
+

This option signals the application to clear the list of +transformations. This is necessary to wipe out the default +transformations used.

+
-c file
+
+
--configuration file
+

This option causes the application to load a configuration file and/or +plugin. This is a plugin which in essence provides a pre-defined set +of commandline options. They are processed exactly as if they have +been specified in place of the option and its arguments. This means +that unknown options found at the beginning of the configuration file +are associated with the last plugin, even if that plugin was specified +before the configuration file itself. Conversely, unknown options +coming after the configuration file can be associated with a plugin +specified in the file.

+

If the argument is a file which cannot be loaded as a plugin the +application will assume that its contents are a list of options and +their arguments, separated by space, tabs, and newlines. Options and +argumentes containing spaces can be quoted via double-quotes (") and +quotes ('). The quote character can be specified within in a quoted +string by doubling it. Newlines in a quoted string are accepted as is.

+
+
+

PLUGINS

+

page makes use of four different types of plugins, namely: +readers, writers, transformations, and configurations. Here we provide +only a basic introduction on how to use them from page. The +exact APIs provided to and expected from the plugins can be found in +the documentation for page::pluginmgr, for those who wish to +write their own plugins.

+

Plugins are specified as arguments to the options -r, +-w, -t, -c, and their equivalent longer +forms. See the section OPTIONS for reference.

+

Each such argument will be first treated as the name of a file and +this file is loaded as the plugin. If however there is no file with +that name, then it will be translated into the name of a package, and +this package is then loaded. For each type of plugins the package +management searches not only the regular paths, but a set application- +and type-specific paths as well. Please see the section +PLUGIN LOCATIONS for a listing of all paths and their +sources.

+
+
-c name
+

Configurations. The name of the package for the plugin name is +"page::config::name".

+

We have one predefined plugin:

+
+
peg
+

It sets the application up as a parser generator accepting parsing +expression grammars and writing a packrat parser in Tcl. The actual +arguments it specifies are:

+
+	--reset
+	--append
+	--reader    peg
+	--transform reach
+	--transform use
+	--writer    me
+
+
+
+
-r name
+

Readers. The name of the package for the plugin name is +"page::reader::name".

+

We have five predefined plugins:

+
+
peg
+

Interprets the input as a parsing expression grammar (PEG) and +generates a tree representation for it. Both the syntax of PEGs and +the structure of the tree representation are explained in their own +manpages.

+
hb
+

Interprets the input as Tcl code as generated by the writer plugin +hb and generates its tree representation.

+
ser
+

Interprets the input as the serialization of a PEG, as generated by +the writer plugin ser, using the package +grammar::peg.

+
lemon
+

Interprets the input as a grammar specification as understood by +Richard Hipp's LEMON parser generator and generates a tree +representation for it. Both the input syntax and the structure of the +tree representation are explained in their own manpages.

+
treeser
+

Interprets the input as the serialization of a +struct::tree. It is validated as such, +but nothing else. It is not assumed to +be the tree representation of a grammar.

+
+
-w name
+

Writers. The name of the package for the plugin name is +"page::writer::name".

+

We have eight predefined plugins:

+
+
identity
+

Simply writes the incoming data as it is, without making any +changes. This is good for inspecting the raw result of a reader or +transformation.

+
null
+

Generates nothing, and ignores the incoming data structure.

+
tree
+

Assumes that the incoming data structure is a struct::tree +and generates an indented textual representation of all nodes, their +parental relationships, and their attribute information.

+
peg
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar and writes it out as a PEG. The +result is nicely formatted and partially simplified (strings as +sequences of characters). A pretty printer in essence, but can also be +used to obtain a canonical representation of the input grammar.

+
tpc
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar and writes out Tcl code defining a +package which defines a grammar::peg object containing the +grammar when it is loaded into an interpreter.

+
hb
+

This is like the writer plugin tpc, but it writes only the +statements which define stat expression and grammar rules. The code +making the result a package is left out.

+
ser
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar, transforms it internally into a +grammar::peg object and writes out its serialization.

+
me
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar and writes out Tcl code defining a +package which implements a memoizing recursive descent parser based on +the match engine (ME) provided by the package grammar::mengine.

+
+
-t name
+

Transformers. The name of the package for the plugin name is +"page::transform::name".

+

We have two predefined plugins:

+
+
reach
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar. It determines which nonterminal +symbols and rules are reachable from start-symbol/expression. All +nonterminal symbols which were not reached are removed.

+
use
+

Assumes that the incoming data structure is a tree representation of a +PEG or other other grammar. It determines which nonterminal +symbols and rules are able to generate a finite sequences of +terminal symbols (in the sense for a Context Free Grammar). All +nonterminal symbols which were not deemed useful in this sense are +removed.

+
+
+
+

PLUGIN LOCATIONS

+

The application-specific paths searched by page either are, +or come from:

+
    +

  1. The directory "~/.page/plugin"

    2. +

  2. The environment variable PAGE_PLUGINS

    3. +

  3. The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\PLUGINS

    4. +

  4. The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\PLUGINS

    5. +
+

The type-specific paths searched by page either are, or come +from:

+
    +

  1. The directory "~/.page/plugin/<TYPE>"

    2. +

  2. The environment variable PAGE_<TYPE>_PLUGINS

    3. +

  3. The registry entry HKEY_LOCAL_MACHINE\SOFTWARE\PAGE\<TYPE>\PLUGINS

    4. +

  4. The registry entry HKEY_CURRENT_USER\SOFTWARE\PAGE\<TYPE>\PLUGINS

    5. +
+

Where the placeholder <TYPE> is always one of the values below, +properly capitalized.

+
    +

  1. reader

    2. +

  2. writer

    3. +

  3. transform

    4. +

  4. config

    5. +
+

The registry entries are specific to the Windows(tm) platform, all +other platforms will ignore them.

+

The contents of both environment variables and registry entries are +interpreted as a list of paths, with the elements separated by either +colon (Unix), or semicolon (Windows).

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

page::pluginmgr

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/apps/pt.html Index: embedded/www/tcllib/files/apps/pt.html ================================================================== --- embedded/www/tcllib/files/apps/pt.html +++ embedded/www/tcllib/files/apps/pt.html @@ -0,0 +1,680 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt(n) 1 tcllib "Parser Tools"

+

Name

+

pt - Parser Tools Application

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes pt, the main application of the module, +a parser generator. Its intended audience are people who wish +to create a parser for some language of theirs. Should you wish to +modify the application instead, please see the section about the +application's Internals for the basic references.

+

It resides in the User Application Layer of Parser Tools.

+

arch_user_app

+
+

Command Line

+
+
pt generate resultformat ?options...? resultfile inputformat inputfile
+

This sub-command of the application reads the parsing expression +grammar stored in the inputfile in the format inputformat, +converts it to the resultformat under the direction of the +(format-specific) set of options specified by the user and stores the +result in the resultfile.

+

The inputfile has to exist, while the resultfile may be +created, overwriting any pre-existing content of the file. Any missing +directory in the path to the resultfile will be created as well.

+

The exact form of the result for, and the set of options supported by +the known result-formats, are explained in the upcoming sections of +this document, with the list below providing an index mapping between +format name and its associated section. In alphabetical order:

+
+
c
+

A resultformat. See section C Parser.

+
container
+

A resultformat. See section Grammar Container.

+
critcl
+

A resultformat. See section C Parser Embedded In Tcl.

+
json
+

A input- and resultformat. See section JSON Grammar Exchange.

+
oo
+

A resultformat. See section TclOO Parser.

+
peg
+

A input- and resultformat. See section PEG Specification Language.

+
snit
+

A resultformat. See section Snit Parser.

+
+
+

Of the seven possible results four are parsers outright (c, +critcl, oo, and snit), one (container) +provides code which can be used in conjunction with a generic parser +(also known as a grammar interpreter), and the last two (json +and peg) are doing double-duty as input formats, allowing the +transformation of grammars for exchange, reformatting, and the like.

+

The created parsers fall into three categories:

+

gen_options

+
+
Specialized parsers implemented in C
+

The fastest parsers are created when using the result formats +c and critcl. The first returns the raw C code for the +parser, while the latter wraps it into a Tcl package using +CriTcl.

+

This makes the latter much easier to use than the former. On the other +hand, the former can be adapted to the users' requirements through a +multitude of options, allowing for things like usage of the parser +outside of a Tcl environment, something the critcl format +doesn't support. As such the c format is meant for more +advanced users, or users with special needs.

+

A disadvantage of all the parsers in this section is the need to run +them through a C compiler to make them actually executable. This is +not something everyone has the necessary tools for. The parsers in the +next section are for people under such restrictions.

+
Specialized parsers implemented in Tcl
+

As the parsers in this section are implemented in Tcl they are quite a +bit slower than anything from the previous section. On the other hand +this allows them to be used in pure-Tcl environments, or in +environments which allow only a limited set of binary packages. In the +latter case it will be advantageous to lobby for the inclusion of the +C-based runtime support (notes below) into the environment to reduce +the impact of Tcl's on the speed of these parsers.

+

The relevant formats are snit and oo. Both place their +result into a Tcl package containing a snit::type, or TclOO +class respectively.

+

Of the supporting runtime, which is the package pt::rde, the +user has to know nothing but that it does exist and that the parsers +are dependent on it. Knowledge of the API exported by the runtime for +the parsers' consumption is not required by the parsers' users.

+
Interpreted parsing implemented in Tcl
+

The last category, grammar interpretation. This means that an +interpreter for parsing expression grammars takes the description of +the grammar to parse input for, and uses it guide the parsing process. +This is the slowest of the available options, as the interpreter has +to continually run through the configured grammar, whereas the +specialized parsers of the previous sections have the relevant +knowledge about the grammar baked into them.

+

The only places where using interpretation make sense is where the +grammar for some input may be changed interactively by the user, as +the interpretation allows for quick turnaround after each change, +whereas the previous methods require the generation of a whole new +parser, which is not as fast. +On the other hand, wherever the grammar to use is fixed, the previous +methods are much more advantageous as the time to generate the parser +is minuscule compared to the time the parser code is in use.

+

The relevant result format is container. +It (quickly) generates grammar descriptions (instead of a full parser) +which match the API expected by ParserTools' grammar interpreter. +The latter is provided by the package pt::peg::interp.

+
+

All the parsers generated by critcl, snit, and +oo, and the grammar interpreter share a common API for access +to the actual parsing functionality, making them all +plug-compatible. +It is described in the Parser API specification document.

+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

For either an introduction to or the formal specification of the +language, please go and read the PEG Language Tutorial.

+

When used as a result-format this format supports the following +options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put the generated +text and the values of the other options. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated text.

+
+
+
+

JSON Grammar Exchange

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

For the formal specification of the JSON grammar exchange format, +please go and read The JSON Grammar Exchange Format.

+

When used as a result-format this format supports the following +options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-indented boolean
+

If this option is set the system will break the generated JSON across +lines and indent it according to its inner structure, with each key of +a dictionary on a separate line.

+

If the option is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
-aligned boolean
+

If this option is set the system will ensure that the values for the +keys in a dictionary are vertically aligned with each other, for a +nice table effect. +To make this work this also implies that -indented is set.

+

If the option is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+
+

C Parser Embedded In Tcl

+

The critcl format is executable code, a parser for the +grammar. It is a Tcl package with the actual parser implementation +written in C and embedded in Tcl via the critcl package.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-class string
+

The value of this option is the name of the class to generate, without +leading colons. +The default value is CLASS.

+

For a simple value X without colons, like CLASS, the parser +command will be X::X. Whereas for a namespaced value +X::Y the parser command will be X::Y.

+
-package string
+

The value of this option is the name of the package to generate. +The default value is PACKAGE.

+
-version string
+

The value of this option is the version of the package to generate. +The default value is 1.

+
+
+

C Parser

+

The c format is executable code, a parser for the grammar. The +parser implementation is written in C and can be tweaked to the users' +needs through a multitude of options.

+

The critcl format, for example, is implemented as a canned +configuration of these options on top of the generator for c.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant C/PARAM.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated Tcl code.

+
+

The following options are special, in that they will +occur within the generated code, and are replaced there as well.

+
+
@statedecl@
+

To be replaced with the value of the option state-decl.

+
@stateref@
+

To be replaced with the value of the option state-ref.

+
@strings@
+

To be replaced with the value of the option string-varname.

+
@self@
+

To be replaced with the value of the option self-command.

+
@def@
+

To be replaced with the value of the option fun-qualifier.

+
@ns@
+

To be replaced with the value of the option namespace.

+
@main@
+

To be replaced with the value of the option main.

+
@prelude@
+

To be replaced with the value of the option prelude.

+
+
-state-decl string
+

A C string representing the argument declaration to use in the +generated parsing functions to refer to the parsing state. In essence +type and argument name. +The default value is the string RDE_PARAM p.

+
-state-ref string
+

A C string representing the argument named used in the generated +parsing functions to refer to the parsing state. +The default value is the string p.

+
-self-command string
+

A C string representing the reference needed to call the generated +parser function (methods ...) from another parser fonction, per the +chosen framework (template). +The default value is the empty string.

+
-fun-qualifier string
+

A C string containing the attributes to give to the generated +functions (methods ...), per the chosen framework (template). +The default value is static.

+
-namespace string
+

The name of the C namespace the parser functions (methods, ...) shall +reside in, or a general prefix to add to the function names. +The default value is the empty string.

+
-main string
+

The name of the main function (method, ...) to be called by the chosen +framework (template) to start parsing input. +The default value is __main.

+
-string-varname string
+

The name of the variable used for the table of strings used by the +generated parser, i.e. error messages, symbol names, etc. +The default value is p_string.

+
-prelude string
+

A snippet of code to be inserted at the head of each generated parsing +function. +The default value is the empty string.

+
-indent integer
+

The number of characters to indent each line of the generated code by. +The default value is 0.

+
-comments boolean
+

A flag controlling the generation of code comments containing the +original parsing expression a parsing function is for. +The default value is on.

+
+
+

Snit Parser

+

The snit format is executable code, a parser for the +grammar. It is a Tcl package holding a snit::type, i.e. a class, +whose instances are parsers for the input grammar.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-class string
+

The value of this option is the name of the class to generate, without +leading colons. Note, it serves double-duty as the name of the package +to generate too, if option -package is not specified, see below. +The default value is CLASS, applying if neither option +-class nor -package were specified.

+
-package string
+

The value of this option is the name of the package to generate, without +leading colons. Note, it serves double-duty as the name of the class +to generate too, if option -class is not specified, see above. +The default value is PACKAGE, applying if neither option +-package nor -class were specified.

+
-version string
+

The value of this option is the version of the package to generate. +The default value is 1.

+
+
+

TclOO Parser

+

The oo format is executable code, a parser for the grammar. It +is a Tcl package holding a TclOO class, whose instances are +parsers for the input grammar.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-class string
+

The value of this option is the name of the class to generate, without +leading colons. Note, it serves double-duty as the name of the package +to generate too, if option -package is not specified, see below. +The default value is CLASS, applying if neither option +-class nor -package were specified.

+
-package string
+

The value of this option is the name of the package to generate, without +leading colons. Note, it serves double-duty as the name of the class +to generate too, if option -class is not specified, see above. +The default value is PACKAGE, applying if neither option +-package nor -class were specified.

+
-version string
+

The value of this option is the version of the package to generate. +The default value is 1.

+
+
+

Grammar Container

+

The container format is another form of describing parsing +expression grammars. While data in this format is executable it does +not constitute a parser for the grammar. It always has to be used in +conjunction with the package pt::peg::interp, a grammar +interpreter.

+

The format represents grammars by a snit::type, i.e. class, +whose instances are API-compatible to the instances of the +pt::peg::container package, and which are preloaded with the +grammar in question.

+

This result-format supports the following options:

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-mode bulk|incremental
+

The value of this option controls which methods of +pt::peg::container instances are used to specify the +grammar, i.e. preload it into the container. There are two legal +values, as listed below. The default is bulk.

+
+
bulk
+

In this mode the methods start, add, modes, +and rules are used to specify the grammar in a bulk manner, +i.e. as a set of nonterminal symbols, and two dictionaries mapping +from the symbols to their semantic modes and parsing expressions.

+

This mode is the default.

+
incremental
+

In this mode the methods start, add, mode, +and rule are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands.

+
+
-template string
+

The value of this option is a string into which to put the generated +code and the other configuration settings. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant CONTAINER.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@mode@
+

To be replaced with the value of the option -mode.

+
@code@
+

To be replaced with the generated code.

+
+
+
+

Example

+

In this section we are working a complete example, starting with a PEG +grammar and ending with running the parser generated from it over some +input, following the outline shown in the figure below:

+

flow

+

Our grammar, assumed to the stored in the file "calculator.peg" +is

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

From this we create a snit-based parser +via

+
+pt generate snit calculator.tcl -class calculator -name calculator peg calculator.peg
+
+

which leaves us with the parser package and class written to the file +"calculator.tcl". +Assuming that this package is then properly installed in a place where +Tcl can find it we can now use this class via a script like

+
+    package require calculator
+    lassign $argv input
+    set channel [open $input r]
+    set parser [calculator]
+    set ast [$parser parse $channel]
+    $parser destroy
+    close $channel
+    ... now process the returned abstract syntax tree ...
+
+

where the abstract syntax tree stored in the variable will look like

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

assuming that the input file and channel contained the text

+
 120+5
+

A more graphical representation of the tree would be

+

expr_ast

+

Regardless, at this point it is the user's responsibility to work with +the tree to reach whatever goal she desires. I.e. analyze it, +transform it, etc. The package pt::ast should be of help +here, providing commands to walk such ASTs structures in various ways.

+

One important thing to note is that the parsers used here return a +data structure representing the structure of the input per the grammar +underlying the parser. There are no callbacks during the +parsing process, i.e. no parsing actions, as most other +parsers will have.

+

Going back to the last snippet of code, the execution of the parser +for some input, note how the parser instance follows the specified +Parser API.

+
+

Internals

+

This section is intended for users of the application which wish to +modify or extend it. Users only interested in the generation of +parsers can ignore it.

+

The main functionality of the application is encapsulated in the +package pt::pgen. Please read it for more information.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/apps/tcldocstrip.html Index: embedded/www/tcllib/files/apps/tcldocstrip.html ================================================================== --- embedded/www/tcllib/files/apps/tcldocstrip.html +++ embedded/www/tcllib/files/apps/tcldocstrip.html @@ -0,0 +1,270 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

+

Name

+

tcldocstrip - Tcl-based Docstrip Processor

+
+ + +

Description

+

The application described by this document, tcldocstrip, is a +relative of docstrip, a simple literate programming tool for +LaTeX.

+

tcldocstrip is based upon the package docstrip.

+

USE CASES

+

tcldocstrip was written with the following three use cases in +mind.

+
    +

  1. Conversion of a single input file according to the listed guards into +the stripped output. This handles the most simple case of a set of +guards specifying a single document found in a single input file.

    2. +

  2. Stitching, or the assembly of an output from several sets of guards, +in a specific order, and possibly from different files. This is the +second common case. One document spread over several inputs, and/or +spread over different guard sets.

    3. +

  3. Extraction and listing of all the unique guard expressions and guards +used within a document to help a person which did not author the +document in question in familiarizing itself with it.

    4. +
+
+

COMMAND LINE

+
+
tcldocstrip output ?options? input ?guards?
+

This is the form for use case [1]. It converts the input +file according to the specified guards and options. The result +is written to the named output file. +Usage of the string - as the name of the output signals that +the result should be written to stdout. The guards are +document-specific and have to be known to the caller. The +options will be explained later, in section OPTIONS.

+
+
path output (in)
+

This argument specifies where to write the generated document. It can +be the path to a file or directory, or -. +The last value causes the application to write the generated +documented to stdout.

+

If the output does not exist then [file dirname $output] +has to exist and must be a writable directory.

+
path inputfile (in)
+

This argument specifies the path to the file to process. It has to +exist, must be readable, and written in docstrip format.

+
+
tcldocstrip ?options? output (?options? input guards)...
+

This is the form for use case [2]. It differs from the form for +use case [1] by the possibility of having options before the +output file, which apply in general, and specifying more than one +inputfile, each with its own set of input specific options and guards.

+

It extracts data from the various input files, according to the +specified options and guards, and writes the result to the +given output, in the order of their specification on the command +line. Options specified before the output are global settings, whereas +the options specified before each input are valid only just for this +input file. Unspecified values are taken from the global settings, or +defaults. As for form [1] using the string - as output +causes the application to write to stdout. +Using the string . for an input file signals that the last +input file should be used again. This enables the assembly of the +output from one input file using multiple and different sets of +guards, without having to specify the full name of the file every +time.

+
tcldocstrip -guards input
+

This is the form for use case [3]. +It determines the guards, and unique guard expressions used within the +provided input document. The found strings are written to +stdout, one string per line.

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application, with the exception of the option -guards. This +option was described already, in section COMMAND LINE.

+
+
-metaprefix string
+

This option is inherited from the command docstrip::extract +provided by the package docstrip.

+

It specifies the string by which the '%%' prefix of a metacomment line +will be replaced. Defaults to '%%'. For Tcl code this would typically +be '#'.

+
-onerror mode
+

This option is inherited from the command docstrip::extract +provided by the package docstrip.

+

It controls what will be done when a format error in the text +being processed is detected. The settings are:

+
+
ignore
+

Just ignore the error; continue as if nothing happened.

+
puts
+

Write an error message to stderr, then continue processing.

+
throw
+

Throw an error. ::errorCode is set to a list whose first element +is DOCSTRIP, second element is the type of error, and third +element is the line number where the error is detected. This is the +default.

+
+
-trimlines bool
+

This option is inherited from the command docstrip::extract +provided by the package docstrip.

+

Controls whether spaces at the end of a line should be trimmed +away before the line is processed. Defaults to true.

+
-preamble text
+
+
-postamble text
+
+
-nopreamble
+
+
-nopostamble
+

The -no*amble options deactivate file pre- and postambles altogether, +whereas the -*amble options specify the user part of the file +pre- and postambles. This part can be empty, in that case only the +standard parts are shown. This is the default.

+

Preambles, when active, are written before the actual content of a +generated file. In the same manner postambles are, when active, +written after the actual content of a generated file.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category docstrip of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/aes/aes.html Index: embedded/www/tcllib/files/modules/aes/aes.html ================================================================== --- embedded/www/tcllib/files/modules/aes/aes.html +++ embedded/www/tcllib/files/modules/aes/aes.html @@ -0,0 +1,259 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

aes(n) 1.2.1 tcllib "Advanced Encryption Standard (AES)"

+

Name

+

aes - Implementation of the AES block cipher

+
+ + +

Description

+

This is an implementation in Tcl of the Advanced Encryption Standard +(AES) as published by the U.S. National Institute of Standards and +Technology [1]. AES is a 128-bit block cipher with a variable +key size of 128, 192 or 256 bits. This implementation supports ECB and +CBC modes.

+
+

COMMANDS

+
+
::aes::aes ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-hex? ?-out channel? ?-chunksize size? [ -in channel | ?--? data ]
+

Perform the aes algorithm on either the data provided +by the argument or on the data read from the -in channel. If +an -out channel is given then the result will be written to +this channel.

+

The -key option must be given. This parameter takes a binary +string of either 16, 24 or 32 bytes in length and is used to generate the +key schedule.

+

The -mode and -dir options are optional and default to cbc +mode and encrypt respectively. The initialization vector -iv +takes a 16 byte binary argument which defaults to all zeros. +See MODES OF OPERATION for more about available modes and +their uses.

+

AES is a 128-bit block cipher. This means that the data must be +provided in units that are a multiple of 16 bytes.

+
+
+

PROGRAMMING INTERFACE

+

Internal state is maintained in an opaque structure that is returned +from the Init function. In ECB mode the state is not affected by +the input but for CBC mode some input dependent state is maintained +and may be reset by calling the Reset function with a new +initialization vector value.

+
+
::aes::Init mode keydata iv
+

Construct a new AES key schedule using the specified key data and the +given initialization vector. The initialization vector is not used +with ECB mode but is important for CBC mode. +See MODES OF OPERATION for details about cipher modes.

+
::aes::Encrypt Key data
+

Use a prepared key acquired by calling Init to encrypt the +provided data. The data argument should be a binary array that is a +multiple of the AES block size of 16 bytes. The result is a binary +array the same size as the input of encrypted data.

+
::aes::Decrypt Key data
+

Decipher data using the key. Note that the same key may be used to +encrypt and decrypt data provided that the initialization vector is +reset appropriately for CBC mode.

+
::aes::Reset Key iv
+

Reset the initialization vector. This permits the programmer to re-use +a key and avoid the cost of re-generating the key schedule where the +same key data is being used multiple times.

+
::aes::Final Key
+

This should be called to clean up resources associated with Key. +Once this function has been called the key may not be used again.

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

ECB is the basic mode of all block ciphers. Each block is encrypted +independently and so identical plain text will produce identical +output when encrypted with the same key. Any encryption errors will +only affect a single block however this is vulnerable to known +plaintext attacks.

+
Cipher Block Chaining (CBC)
+

CBC mode uses the output of the last block encryption to affect the +current block. An initialization vector of the same size as the cipher +block size is used to handle the first block. The initialization +vector should be chosen randomly and transmitted as the first block of +the output. Errors in encryption affect the current block and the next +block after which the cipher will correct itself. CBC is the most +commonly used mode in software encryption. This is the default mode +of operation for this module.

+
+
+

EXAMPLES

+
+% set nil_block [string repeat \\0 16]
+% aes::aes -hex -mode cbc -dir encrypt -key $nil_block $nil_block
+66e94bd4ef8a2c3b884cfa59ca342b2e
+
+
+set Key [aes::Init cbc $sixteen_bytes_key_data $sixteen_byte_iv]
+append ciphertext [aes::Encrypt $Key $plaintext]
+append ciphertext [aes::Encrypt $Key $additional_plaintext]
+aes::Final $Key
+
+
+

REFERENCES

+
    +

  1. "Advanced Encryption Standard", + Federal Information Processing Standards Publication 197, 2001 + (http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf)

    2. +
+
+

AUTHORS

+

Thorsten Schloermann, Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category aes of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/amazon-s3/S3.html Index: embedded/www/tcllib/files/modules/amazon-s3/S3.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/S3.html +++ embedded/www/tcllib/files/modules/amazon-s3/S3.html @@ -0,0 +1,1280 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

S3(n) 1.0.3 tcllib "Amazon S3 Web Service Utilities"

+

Name

+

S3 - Amazon S3 Web Service Interface

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require S3 ?1.0.3?
    • +
  • package require sha1 1.0
    • +
  • package require md5 2.0
    • +
  • package require base64 2.3
    • +
  • package require xsxp 1.0
    • +
+ +
+
+

Description

+

This package provides access to Amazon's Simple Storage Solution web service.

+

As a quick summary, Amazon Simple Storage Solution +provides a for-fee web service allowing the storage of arbitrary data as +"resources" within "buckets" online. +See http://www.amazonaws.com/ for details on that system. +Access to the service is via HTTP (SOAP or REST). Much of this +documentation will not make sense if you're not familiar with +the terms and functionality of the Amazon S3 service.

+

This package provides services for reading and writing +the data items via the REST interface. It also provides some +higher-level operations. Other packages in the same distribution +provide for even more functionality.

+

Copyright 2006 Darren New. All Rights Reserved. +NO WARRANTIES OF ANY TYPE ARE PROVIDED. +COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. +This software is licensed under essentially the same +terms as Tcl. See LICENSE.txt for the terms.

+
+

ERROR REPORTING

+

The error reporting from this package makes use of $errorCode to +provide more details on what happened than simply throwing an error. +Any error caught by the S3 package (and we try to catch them all) +will return with an $errorCode being a list having at least three +elements. In all cases, the first element will be "S3". The second +element will take on one of six values, with that element defining +the value of the third and subsequent elements. S3::REST does not +throw an error, but rather returns a dictionary with the keys "error", +"errorInfo", and "errorCode" set. This allows for reliable background +use. The possible second elements are these:

+
+
usage
+

The usage of the package is incorrect. For example, +a command has been invoked which requires the library to be configured +before the library has been configured, or an invalid combination of +options has been specified. The third element of $errorCode supplies +the name of the parameter that was wrong. The fourth usually provides +the arguments that were actually supplied to the throwing proc, unless +the usage error isn't confined to a single proc.

+
local
+

Something happened on the local system which threw +an error. For example, a request to upload or download a file was made +and the file permissions denied that sort of access. The third element +of $errorCode is the original $errorCode.

+
socket
+

Something happened with the socket. It closed +prematurely, or some other condition of failure-to-communicate-with-Amazon +was detected. The third element of $errorCode is the original $errorCode, +or sometimes the message from fcopy, or ...?

+
remote
+

The Amazon web service returned an error code outside +the 2xx range in the HTTP header. In other words, everything went as +documented, except this particular case was documented not to work. +The third element is the dictionary returned from ::S3::REST. +Note that S3::REST itself never throws this error, but just returns +the dictionary. Most of the higher-level commands throw for convenience, +unless an argument indicates they should not. If something is documented +as "not throwing an S3 remote error", it means a status return is set +rather than throwing an error if Amazon returns a non-2XX HTTP result code.

+
notyet
+

The user obeyed the documentation, but the author +has not yet gotten around to implementing this feature. (Right now, +only TLS support and sophisticated permissions fall into this category, +as well as the S3::Acl command.)

+
xml
+

The service has returned invalid XML, or XML whose +schema is unexpected. For the high-level commands that accept +service XML as input for parsing, this may also be thrown.

+
+
+

COMMANDS

+

This package provides several separate levels of complexity.

+
    +

  • The lowest level simply takes arguments to be sent to the service, +sends them, retrieves the result, and provides it to the caller. +Note: This layer allows both synchronous and event-driven +processing. It depends on the MD5 and SHA1 and base64 packages +from Tcllib (available at http://core.tcl.tk/tcllib/). +Note that S3::Configure is required for S3::REST to +work due to the authentication portion, so we put that in the "lowest level."

    • +

  • The next layer parses the results of calls, allowing for functionality +such as uploading only changed files, synchronizing directories, +and so on. This layer depends on the TclXML package as well as the +included xsxp package. These packages are package required when +these more-sophisticated routines are called, so nothing breaks if +they are not correctly installed.

    • +

  • Also included is a separate program that uses the library. +It provides code to parse $argv0 and $argv from the +command line, allowing invocation as a tclkit, etc. +(Not yet implmented.)

    • +

  • Another separate program provides a GUI interface allowing drag-and-drop +and other such functionality. (Not yet implemented.)

    • +

  • Also built on this package is the OddJob program. It is +a separate program designed to allow distribution of +computational work units over Amazon's Elastic Compute +Cloud web service.

    • +
+

The goal is to have at least the bottom-most layers implemented in +pure Tcl using only that which comes from widely-available sources, +such as Tcllib.

+
+

LOW LEVEL COMMANDS

+

These commands do not require any packages not listed above. +They talk directly to the service, or they are utility or +configuration routines. Note that the "xsxp" package was +written to support this package, so it should be available +wherever you got this package.

+
+
S3::Configure ?-reset boolean? ?-retries integer? ?-accesskeyid idstring? ?-secretaccesskey idstring? ?-service-access-point FQDN? ?-use-tls boolean? ?-default-compare always|never|exists|missing|newer|date|checksum|different? ?-default-separator string? ?-default-acl private|public-read|public-read-write|authenticated-read|keep|calc? ?-default-bucket bucketname?
+

There is one command for configuration, and that is S3::Configure. +If called with no arguments, it returns a +dictionary of key/value pairs listing all current settings. If called +with one argument, it returns the value of that single argument. If +called with two or more arguments, it must be called with pairs of +arguments, and it applies the changes in order. There is only one set +of configuration information per interpreter.

+

The following options are accepted:

+
+
-reset boolean
+

By default, false. If true, any previous changes and any changes on the +same call before the reset option will be returned to default values.

+
-retries integer
+

Default value is 3. +If Amazon returns a 500 error, a retry after an exponential +backoff delay will be tried this many times before finally +throwing the 500 error. This applies to each call to S3::REST +from the higher-level commands, but not to S3::REST itself. +That is, S3::REST will always return httpstatus 500 if that's +what it receives. Functions like S3::Put will retry the PUT call, +and will also retry the GET and HEAD calls used to do content comparison. +Changing this to 0 will prevent retries and their associated delays. +In addition, socket errors (i.e., errors whose errorCode starts with +"S3 socket") will be similarly retried after backoffs.

+
-accesskeyid idstring
+
+
-secretaccesskey idstring
+

Each defaults to an empty string. +These must be set before any calls are made. This is your S3 ID. +Once you sign up for an account, go to http://www.amazonaws.com/, +sign in, go to the "Your Web Services Account" button, pick "AWS +Access Identifiers", and your access key ID and secret access keys +will be available. All S3::REST calls are authenticated. +Blame Amazon for the poor choice of names.

+
-service-access-point FQDN
+

Defaults to "s3.amazonaws.com". This is the fully-qualified domain +name of the server to contact for S3::REST calls. You should +probably never need to touch this, unless someone else implements +a compatible service, or you wish to test something by pointing +the library at your own service.

+
-slop-seconds integer
+

When comparing dates between Amazon and the local machine, +two dates within this many seconds of each other are considered +the same. Useful for clock drift correction, processing overhead +time, and so on.

+
-use-tls boolean
+

Defaults to false. This is not yet implemented. If true, S3::REST will +negotiate a TLS connection to Amazon. If false, unencrypted connections +are used.

+
-bucket-prefix string
+

Defaults to "TclS3". This string is used by S3::SuggestBucketName +if that command is passed an empty string as an argument. It is used +to distinguish different applications using the Amazon service. +Your application should always set this to keep from interfering with +the buckets of other users of Amazon S3 or with other buckets of the +same user.

+
-default-compare always|never|exists|missing|newer|date|checksum|different
+

Defaults to "always." If no -compare is specified on +S3::Put, S3::Get, or S3::Delete, this comparison is used. +See those commands for a description of the meaning.

+
-default-separator string
+

Defaults to "/". This is currently unused. It might make sense to use +this for S3::Push and S3::Pull, but allowing resources to +have slashes in their names that aren't marking directories would be +problematic. Hence, this currently does nothing.

+
-default-acl private|public-read|public-read-write|authenticated-read|keep|calc
+

Defaults to an empty string. If no -acl argument is provided to S3::Put or +S3::Push, this string is used +(given as the x-amz-acl header if not keep or calc). If this is also +empty, no x-amz-acl header is generated. +This is not used by S3::REST.

+
-default-bucket bucketname
+

If no bucket is given to S3::GetBucket, S3::PutBucket, +S3::Get, S3::Put, +S3::Head, S3::Acl, +S3::Delete, S3::Push, +S3::Pull, or S3::Toss, and if this configuration variable +is not an empty string (and not simply "/"), then this value +will be used for the bucket. This is useful if one program does +a large amount of resource manipulation within a single bucket.

+
+
S3::SuggestBucket ?name?
+

The S3::SuggestBucket command accepts an optional string as +a prefix and returns a valid bucket containing the name argument +and the Access Key ID. This makes the name unique to the owner and +to the application (assuming the application picks a good name argument). +If no name is provided, +the name from S3::Configure -bucket-prefix is used. +If that too is empty (which is not the default), an error is thrown.

+
S3::REST dict
+

The S3::REST command takes as an argument a dictionary and +returns a dictionary. The return dictionary has the same keys +as the input dictionary, and includes additional keys as the result. +The presence or absence of keys in the input dictionary can control +the behavior of the routine. It never throws an error directly, but +includes keys "error", "errorInfo", and "errorCode" if necessary. +Some keys are required, some optional. The routine can run either +in blocking or non-blocking mode, based on the presense +of resultvar in the input dictionary. This requires +the -accesskeyid and -secretaccesskey to be configured via +S3::Configure before being called.

+

The possible input keys are these:

+
+
verb GET|PUT|DELETE|HEAD
+

This required item indicates the verb to be used.

+
resource string
+

This required item indicates the resource to be accessed. +A leading / is added if not there already. It will +be URL-encoded for you if necessary. Do not supply a +resource name that is already URL-encoded.

+
?rtype torrent|acl?
+

This indicates a torrent or acl resource is being manipulated. +Do not include this in the resource key, or the +"?" separator will get URL-encoded.

+
?parameters dict?
+

This optional dictionary provides parameters added to the URL +for the transaction. The keys must be in the correct case +(which is confusing in the Amazon documentation) and the +values must be valid. This can be an empty dictionary or +omitted entirely if no parameters are desired. No other +error checking on parameters is performed.

+
?headers dict?
+

This optional dictionary provides headers to be added +to the HTTP request. The keys must be in lower case +for the authentication to work. The values must not contain +embedded newlines or carriage returns. This is primarily +useful for adding x-amz-* headers. Since authentication +is calculated by S3::REST, do not add that header here. +Since content-type gets its own key, also do not add +that header here.

+
?inbody contentstring?
+

This optional item, if provided, gives the content that will +be sent. It is sent with a tranfer encoding of binary, and +only the low bytes are used, so use [encoding convertto utf-8] +if the string is a utf-8 string. This is written all in one blast, +so if you are using non-blocking mode and the inbody is +especially large, you may wind up blocking on the write socket.

+
?infile filename?
+

This optional item, if provided, and if inbody is not provided, +names the file from which the body of the HTTP message will be +constructed. The file is opened for reading and sent progressively +by [fcopy], so it should not block in non-blocking mode +even if the file is very large. The file is transfered in +binary mode, so the bytes on your disk will match the bytes +in your resource. Due to HTTP restrictions, it must be possible to +use [file size] on this file to determine the size at the +start of the transaction.

+
?S3chan channel?
+

This optional item, if provided, indicates the already-open socket +over which the transaction should be conducted. If not provided, +a connection is made to the service access point specified via +S3::Configure, which is normally s3.amazonaws.com. If this +is provided, the channel is not closed at the end of the transaction.

+
?outchan channel?
+

This optional item, if provided, indicates the already-open channel +to which the body returned from S3 should be written. That is, +to retrieve a large resource, open a file, set the translation mode, +and pass the channel as the value of the key outchan. Output +will be written to the channel in pieces so memory does not fill +up unnecessarily. The channel is not closed at the end of the transaction.

+
?resultvar varname?
+

This optional item, if provided, indicates that S3::REST should +run in non-blocking mode. The varname should be fully qualified +with respect to namespaces and cannot be local to a proc. If provided, +the result of the S3::REST call is assigned to this variable once +everything has completed; use trace or vwait to know when this has happened. +If this key is not provided, the result is simply returned from the +call to S3::REST and no calls to the eventloop are invoked from +within this call.

+
?throwsocket throw|return?
+

This optional item, if provided, indicates that S3::REST should +throw an error if throwmode is throw and a socket error is encountered. +It indicates that S3::REST should return the error code in the +returned dictionary if a socket error is encountered and this is +set to return. If throwsocket is set to return or +if the call is not blocking, then a socket error (i.e., an error +whose error code starts with "S3 socket" will be returned in the +dictionary as error, errorInfo, and errorCode. +If a foreground call is made (i.e., resultvar is not provided), +and this option is not provided or is set to throw, then +error will be invoked instead.

+
+

Once the call to S3::REST completes, a new dict is returned, +either in the resultvar or as the result of execution. This dict is +a copy of the original dict with the results added as new keys. The possible +new keys are these:

+
+
error errorstring
+
+
errorInfo errorstring
+
+
errorCode errorstring
+

If an error is caught, these three keys will be set in the result. +Note that S3::REST does not consider a non-2XX HTTP +return code as an error. The errorCode value will be +formatted according to the ERROR REPORTING description. +If these are present, other keys described here might not be.

+
httpstatus threedigits
+

The three-digit code from the HTTP transaction. 2XX for good, +5XX for server error, etc.

+
httpmessage text
+

The textual result after the status code. "OK" or "Forbidden" +or etc.

+
outbody contentstring
+

If outchan was not specified, this key will hold a +reference to the (unencoded) contents of the body returned. +If Amazon returned an error (a la the httpstatus not a 2XX value), +the error message will be in outbody or written to +outchan as appropriate.

+
outheaders dict
+

This contains a dictionary of headers returned by Amazon. +The keys are always lower case. It's mainly useful for +finding the x-amz-meta-* headers, if any, although things +like last-modified and content-type are also useful. +The keys of this dictionary are always lower case. +Both keys and values are trimmed of extraneous whitespace.

+
+
+
+

HIGH LEVEL COMMANDS

+

The routines in this section all make use of one or more calls +to S3::REST to do their work, then parse and manage the data +in a convenient way. All these commands throw errors +as described in ERROR REPORTING unless otherwise noted.

+

In all these commands, all arguments are presented as name/value pairs, +in any order. All the argument names start with a hyphen.

+

There are a few options that are common to many +of the commands, and those common options are documented here.

+
+
-blocking boolean
+

If provided and specified as false, +then any calls to S3:REST will be non-blocking, +and internally these routines will call [vwait] to get +the results. In other words, these routines will return the +same value, but they'll have event loops running while waiting +for Amazon.

+
-parse-xml xmlstring
+

If provided, the routine skips actually communicating with +Amazon, and instead behaves as if the XML string provided +was returned as the body of the call. Since several of +these routines allow the return of data in various formats, +this argument can be used to parse existing XML to extract +the bits of information that are needed. It's also helpful +for testing.

+
-bucket bucketname
+

Almost every high-level command needs to know what bucket +the resources are in. This option specifies that. (Only the +command to list available buckets does not require this parameter.) +This does not need to be URL-encoded, even if it contains +special or non-ASCII characters. May or may not contain leading +or trailing spaces - commands normalize the bucket. If this is +not supplied, the value is taken from S3::Configure -default-bucket +if that string isn't empty. Note that spaces and slashes are +always trimmed from both ends and the rest must leave a valid bucket.

+
-resource resourcename
+

This specifies the resource of interest within the bucket. +It may or may not start with a slash - both cases are handled. +This does not need to be URL-encoded, even if it contains +special or non-ASCII characters.

+
-compare always|never|exists|missing|newer|date|checksum|different
+

When commands copy resources to files or files to resources, the caller may specify that the copy should be skipped if the contents are the same. This argument specifies the conditions under which the files should be copied. If it is not passed, the result of S3::Configure -default-compare is used, which in turn defaults to "always." The meanings of the various values are these:

+
+
always
+

Always copy the data. This is the default.

+
never
+

Never copy the data. This is essentially a no-op, except in S3::Push and S3::Pull where the -delete flag might make a difference.

+
exists
+

Copy the data only if the destination already exists.

+
missing
+

Copy the data only if the destination does not already exist.

+
newer
+

Copy the data if the destination is missing, or if the date on the source is +newer than the date on the destination by at +least S3::Configure -slop-seconds seconds. If the source is +Amazon, the date is taken from the Last-Modified header. If the +source is local, it is taken as the mtime of the file. If the source data +is specified in a string rather than a file, it is taken as right now, +via [clock seconds].

+
date
+

Like newer, except copy if the date is newer or older.

+
checksum
+

Calculate the MD5 checksum on the local file or string, ask Amazon for the eTag +of the resource, and copy the data if they're different. Copy the data +also if the destination is missing. Note that this can be slow with +large local files unless the C version of the MD5 support is available.

+
different
+

Copy the data if the destination does not exist. +If the destination exists and an actual file name was specified +(rather than a content string), +and the date on the file differs from the date on the resource, +copy the data. +If the data is provided as a content string, the "date" is treated +as "right now", so it will likely always differ unless slop-seconds is large. +If the dates are the same, the MD5 checksums are compared, and the +data is copied if the checksums differ.

+
+

Note that "newer" and "date" don't care about the contents, and "checksum" doesn't care about the dates, but "different" checks both.

+
S3::ListAllMyBuckets ?-blocking boolean? ?-parse-xml xmlstring? ?-result-type REST|xml|pxml|dict|names|owner?
+

This routine performs a GET on the Amazon S3 service, which is +defined to return a list of buckets owned by the account identified +by the authorization header. (Blame Amazon for the dumb names.)

+
+
-blocking boolean
+

See above for standard definition.

+
-parse-xml xmlstring
+

See above for standard definition.

+
-result-type REST
+

The dictionary returned by S3::REST is the return value of S3::ListAllMyBuckets. In this case, a non-2XX httpstatus will not throw an error. You may not combine this with -parse-xml.

+
-result-type xml
+

The raw XML of the body is returned as the result (with no encoding applied).

+
-result-type pxml
+

The XML of the body as parsed by xsxp::parse is returned.

+
-result-type dict
+

A dictionary of interesting portions of the XML is returned. The dictionary contains the following keys:

+
+
Owner/ID
+

The Amazon AWS ID (in hex) of the owner of the bucket.

+
Owner/DisplayName
+

The Amazon AWS ID's Display Name.

+
Bucket/Name
+

A list of names, one for each bucket.

+
Bucket/CreationDate
+

A list of dates, one for each bucket, +in the same order as Bucket/Name, in ISO format (as returned by Amazon).

+
+
-result-type names
+

A list of bucket names is returned with all other information stripped out. +This is the default result type for this command.

+
-result-type owner
+

A list containing two elements is returned. The first element is +the owner's ID, and the second is the owner's display name.

+
+
S3::PutBucket ?-bucket bucketname? ?-blocking boolean? ?-acl {}|private|public-read|public-read-write|authenticated-read?
+

This command creates a bucket if it does not already exist. Bucket names are +globally unique, so you may get a "Forbidden" error from Amazon even if you +cannot see the bucket in S3::ListAllMyBuckets. See S3::SuggestBucket for ways to minimize this risk. The x-amz-acl header comes from the -acl option, or from S3::Configure -default-acl if not specified.

+
S3::DeleteBucket ?-bucket bucketname? ?-blocking boolean?
+

This command deletes a bucket if it is empty and you have such permission. +Note that Amazon's list of buckets is a global resource, requiring +far-flung synchronization. If you delete a bucket, it may be quite +a few minutes (or hours) before you can recreate it, yielding "Conflict" +errors until then.

+
S3::GetBucket ?-bucket bucketname? ?-blocking boolean? ?-parse-xml xmlstring? ?-max-count integer? ?-prefix prefixstring? ?-delimiter delimiterstring? ?-result-type REST|xml|pxml|names|dict?
+

This lists the contents of a bucket. That is, it returns a directory +listing of resources within a bucket, rather than transfering any +user data.

+
+
-bucket bucketname
+

The standard bucket argument.

+
-blocking boolean
+

The standard blocking argument.

+
-parse-xml xmlstring
+

The standard parse-xml argument.

+
-max-count integer
+

If supplied, this is the most number of records to be returned. +If not supplied, the code will iterate until all records have been found. +Not compatible with -parse-xml. Note that if this is supplied, only +one call to S3::REST will be made. Otherwise, enough calls +will be made to exhaust the listing, buffering results in memory, +so take care if you may have huge buckets.

+
-prefix prefixstring
+

If present, restricts listing to resources with a particular prefix. One +leading / is stripped if present.

+
-delimiter delimiterstring
+

If present, specifies a delimiter for the listing. +The presence of this will summarize multiple resources +into one entry, as if S3 supported directories. See the +Amazon documentation for details.

+
-result-type REST|xml|pxml|names|dict
+

This indicates the format of the return result of the command.

+
+
REST
+

If -max-count is specified, the dictionary returned +from S3::REST is returned. If -max-count is +not specified, a list of all the dictionaries returned from +the one or more calls to S3::REST is returned.

+
xml
+

If -max-count is specified, the body returned +from S3::REST is returned. If -max-count is +not specified, a list of all the bodies returned from +the one or more calls to S3::REST is returned.

+
pxml
+

If -max-count is specified, the body returned +from S3::REST is passed throught xsxp::parse and then returned. +If -max-count is +not specified, a list of all the bodies returned from +the one or more calls to S3::REST are each passed through +xsxp::parse and then returned.

+
names
+

Returns a list of all names found in either the Contents/Key fields or +the CommonPrefixes/Prefix fields. If no -delimiter is specified +and no -max-count is specified, this returns a list of all +resources with the specified -prefix.

+
dict
+

Returns a dictionary. (Returns only one dictionary even if -max-count +wasn't specified.) The keys of the dictionary are as follows:

+
+
Name
+

The name of the bucket (from the final call to S3::REST).

+
Prefix
+

From the final call to S3::REST.

+
Marker
+

From the final call to S3::REST.

+
MaxKeys
+

From the final call to S3::REST.

+
IsTruncated
+

From the final call to S3::REST, so +always false if -max-count is not specified.

+
NextMarker
+

Always provided if IsTruncated is true, and +calculated of Amazon does not provide it. May be empty if IsTruncated is false.

+
Key
+

A list of names of resources in the bucket matching the -prefix and -delimiter restrictions.

+
LastModified
+

A list of times of resources in the bucket, in the same +order as Key, in the format returned by Amazon. (I.e., it is not parsed into +a seconds-from-epoch.)

+
ETag
+

A list of entity tags (a.k.a. MD5 checksums) in the same order as Key.

+
Size
+

A list of sizes in bytes of the resources, in the same order as Key.

+
Owner/ID
+

A list of owners of the resources in the bucket, in the same order as Key.

+
Owner/DisplayName
+

A list of owners of the resources in the bucket, in the same order as Key. These are the display names.

+
CommonPrefixes/Prefix
+

A list of prefixes common to multiple entities. This is present only if -delimiter was supplied.

+
+
+
+
S3::Put ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-file filename? ?-content contentstring? ?-acl private|public-read|public-read-write|authenticated-read|calc|keep? ?-content-type contenttypestring? ?-x-amz-meta-* metadatatext? ?-compare comparemode?
+

This command sends data to a resource on Amazon's servers for storage, +using the HTTP PUT command. It returns 0 if the -compare mode +prevented the transfer, 1 if the transfer worked, or throws an error +if the transfer was attempted but failed. +Server 5XX errors and S3 socket errors are retried +according to S3:Configure -retries settings before throwing an error; +other errors throw immediately.

+
+
-bucket
+

This specifies the bucket into which the resource will be written. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-blocking
+

The standard blocking flag.

+
-file
+

If this is specified, the filename must exist, must be readable, +and must not be a special or directory file. [file size] must +apply to it and must not change for the lifetime of the call. The +default content-type is calculated based on the name and/or contents +of the file. Specifying this is an error if -content is +also specified, but at least one of -file or -content must +be specified. (The file is allowed to not exist or not be readable if +-compare never is specified.)

+
-content
+

If this is specified, the contentstring is sent as the body +of the resource. The content-type defaults to "application/octet-string". +Only the low bytes are sent, so non-ASCII should use the appropriate encoding +(such as [encoding convertto utf-8]) before passing it +to this routine, if necessary. Specifying this is an error if -file +is also specified, but at least one of -file or -content must +be specified.

+
-acl
+

This defaults to S3::Configure -default-acl if not specified. +It sets the x-amz-acl header on the PUT operation. +If the value provided is calc, the x-amz-acl header is +calculated based on the I/O permissions of the file to be uploaded; +it is an error to specify calc and -content. +If the value provided is keep, the acl of the resource +is read before the PUT (or the default is used if the +resource does not exist), then set back to what it +was after the PUT (if it existed). An error will occur if +the resource is successfully written but the kept ACL cannot +be then applied. This should never happen. +Note: calc is not currently fully implemented.

+
-x-amz-meta-*
+

If any header starts with "-x-amz-meta-", its contents are added to the +PUT command to be stored as metadata with the resource. Again, no +encoding is performed, and the metadata should not contain characters +like newlines, carriage returns, and so on. It is best to stick with +simple ASCII strings, or to fix the library in several places.

+
-content-type
+

This overrides the content-type calculated by -file or +sets the content-type for -content.

+
-compare
+

This is the standard compare mode argument. S3::Put returns +1 if the data was copied or 0 if the data was skipped due to +the comparison mode so indicating it should be skipped.

+
+
S3::Get ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-compare comparemode? ?-file filename? ?-content contentvarname? ?-timestamp aws|now? ?-headers headervarname?
+

This command retrieves data from a resource on Amazon's S3 servers, +using the HTTP GET command. It returns 0 if the -compare mode +prevented the transfer, 1 if the transfer worked, or throws an error +if the transfer was attempted but failed. Server 5XX errors and S3 socket +errors are are retried +according to S3:Configure settings before throwing an error; +other errors throw immediately. Note that this is always authenticated +as the user configured in via S3::Configure -accesskeyid. Use +the Tcllib http for unauthenticated GETs.

+
+
-bucket
+

This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-blocking
+

The standard blocking flag.

+
-file
+

If this is specified, the body of the resource will be read into this file, +incrementally without pulling it entirely into memory first. The parent +directory must already exist. If the file already exists, it must be +writable. If an error is thrown part-way through the process and the +file already existed, it may be clobbered. If an error is thrown part-way +through the process and the file did not already exist, any partial +bits will be deleted. Specifying this is an error if -content +is also specified, but at least one of -file or -content must +be specified.

+
-timestamp
+

This is only valid in conjunction with -file. It may be specified +as now or aws. The default is now. If now, the file's +modification date is left up to the system. If aws, the file's +mtime is set to match the Last-Modified header on the resource, synchronizing +the two appropriately for -compare date or +-compare newer.

+
-content
+

If this is specified, the contentvarname is a variable in the caller's +scope (not necessarily global) that receives the value of the body of +the resource. No encoding is done, so if the resource (for example) represents +a UTF-8 byte sequence, use [encoding convertfrom utf-8] to get a valid +UTF-8 string. If this is specified, the -compare is ignored unless +it is never, in which case no assignment to contentvarname is +performed. Specifying this is an error if -file is also specified, +but at least one of -file or -content must be specified.

+
-compare
+

This is the standard compare mode argument. S3::Get returns +1 if the data was copied or 0 if the data was skipped due to +the comparison mode so indicating it should be skipped.

+
-headers
+

If this is specified, the headers resulting from the fetch are stored +in the provided variable, as a dictionary. This will include content-type +and x-amz-meta-* headers, as well as the usual HTTP headers, the x-amz-id +debugging headers, and so on. If no file is fetched (due to -compare +or other errors), no assignment to this variable is performed.

+
+
S3::Head ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-dict dictvarname? ?-headers headersvarname? ?-status statusvarname?
+

This command requests HEAD from the resource. +It returns whether a 2XX code was returned as a result +of the request, never throwing an S3 remote error. +That is, if this returns 1, the resource exists and is +accessible. If this returns 0, something went wrong, and the +-status result can be consulted for details.

+
+
-bucket
+

This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-blocking
+

The standard blocking flag.

+
-dict
+

If specified, the resulting dictionary from the S3::REST +call is assigned to the indicated (not necessarily global) variable +in the caller's scope.

+
-headers
+

If specified, the dictionary of headers from the result are assigned +to the indicated (not necessarily global) variable in the caller's scope.

+
-status
+

If specified, the indicated (not necessarily global) variable in +the caller's scope is assigned a 2-element list. The first element is +the 3-digit HTTP status code, while the second element is +the HTTP message (such as "OK" or "Forbidden").

+
+
S3::GetAcl ?-blocking boolean? ?-bucket bucketname? -resource resourcename ?-result-type REST|xml|pxml?
+

This command gets the ACL of the indicated resource or throws an +error if it is unavailable.

+
+
-blocking boolean
+

See above for standard definition.

+
-bucket
+

This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-parse-xml xml
+

The XML from a previous GetACL can be passed in to be parsed into +dictionary form. In this case, -result-type must be pxml or dict.

+
-result-type REST
+

The dictionary returned by S3::REST is the return value of +S3::GetAcl. In this case, a non-2XX httpstatus will not throw an +error.

+
-result-type xml
+

The raw XML of the body is returned as the result (with no encoding applied).

+
-result-type pxml
+

The XML of the body as parsed by xsxp::parse is returned.

+
-result-type dict
+

This fetches the ACL, parses it, and returns a dictionary of two elements.

+

The first element has the key "owner" whose value is the canonical ID of the owner of the resource.

+

The second element has the key "acl" whose value is a dictionary. Each +key in the dictionary is one of Amazon's permissions, namely "READ", +"WRITE", "READ_ACP", "WRITE_ACP", or "FULL_CONTROL". Each value of each +key is a list of canonical IDs or group URLs that have that permission. +Elements are not in the list in any particular order, and not all keys +are necessarily present. Display names are not returned, as they are +not especially useful; use pxml to obtain them if necessary.

+
+
S3::PutAcl ?-blocking boolean? ?-bucket bucketname? -resource resourcename ?-acl new-acl?
+

This sets the ACL on the indicated resource. It returns the XML written to the ACL, or throws an error if anything went wrong.

+
+
-blocking boolean
+

See above for standard definition.

+
-bucket
+

This specifies the bucket from which the resource will be read. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-owner
+

If this is provided, it is assumed to match the owner of the resource. +Otherwise, a GET may need to be issued against the resource to find +the owner. If you already have the owner (such as from a call +to S3::GetAcl, you can pass the value of the "owner" key +as the value of this option, and it will be used in the construction +of the XML.

+
-acl
+

If this option is specified, it provides the ACL the caller wishes +to write to the resource. If this is not supplied or is empty, +the value is taken from S3::Configure -default-acl. +The ACL is written with a PUT to the ?acl resource.

+

If the value passed to this option +starts with "<", it is taken to be a body to be PUT to the ACL resource.

+

If the value matches one of the standard Amazon x-amz-acl headers (i.e., +a canned access policy), that header is translated to XML and then +applied. The canned access policies are private, public-read, +public-read-write, and authenticated-read (in lower case).

+

Otherwise, the value is assumed to be a dictionary formatted as the +"acl" sub-entry within the dict returns by S3::GetAcl -result-type dict. +The proper XML is generated and applied to the resource. Note that a +value containing "//" is assumed to be a group, a value containing "@" +is assumed to be an AmazonCustomerByEmail, and otherwise the value is +assumed to be a canonical Amazon ID.

+

Note that you cannot change the owner, so calling GetAcl on a resource +owned by one user and applying it via PutAcl on a resource owned by +another user may not do exactly what you expect.

+
+
S3::Delete ?-bucket bucketname? -resource resourcename ?-blocking boolean? ?-status statusvar?
+

This command deletes the specified resource from the specified bucket. +It returns 1 if the resource was deleted successfully, 0 otherwise. +It returns 0 rather than throwing an S3 remote error.

+
+
-bucket
+

This specifies the bucket from which the resource will be deleted. +Leading and/or trailing slashes are removed for you, as are spaces.

+
-resource
+

This is the full name of the resource within the bucket. A single +leading slash is removed, but not a trailing slash. +Spaces are not trimmed.

+
-blocking
+

The standard blocking flag.

+
-status
+

If specified, the indicated (not necessarily global) variable +in the caller's scope is set to a two-element list. The first +element is the 3-digit HTTP status code. The second element +is the HTTP message (such as "OK" or "Forbidden"). Note that +Amazon's DELETE result is 204 on success, that being the +code indicating no content in the returned body.

+
+
S3::Push ?-bucket bucketname? -directory directoryname ?-prefix prefixstring? ?-compare comparemode? ?-x-amz-meta-* metastring? ?-acl aclcode? ?-delete boolean? ?-error throw|break|continue? ?-progress scriptprefix?
+

This synchronises a local directory with a remote bucket +by pushing the differences using S3::Put. Note that +if something has changed in the bucket but not locally, +those changes could be lost. Thus, this is not a general +two-way synchronization primitive. (See S3::Sync +for that.) Note too that resource names are case sensitive, +so changing the case of a file on a Windows machine may lead +to otherwise-unnecessary transfers. +Note that only regular files are considered, so devices, pipes, symlinks, +and directories are not copied.

+
+
-bucket
+

This names the bucket into which data will be pushed.

+
-directory
+

This names the local directory from which files will be taken. +It must exist, be readable via [glob] and so on. If only +some of the files therein are readable, S3::Push will PUT +those files that are readable and return in its results the list +of files that could not be opened.

+
-prefix
+

This names the prefix that will be added to all resources. +That is, it is the remote equivalent of -directory. +If it is not specified, the root of the bucket will be treated +as the remote directory. An example may clarify.

+
+S3::Push -bucket test -directory /tmp/xyz -prefix hello/world
+
+

In this example, /tmp/xyz/pdq.html will be stored as +http://s3.amazonaws.com/test/hello/world/pdq.html in Amazon's servers. Also, +/tmp/xyz/abc/def/Hello will be stored as +http://s3.amazonaws.com/test/hello/world/abc/def/Hello in Amazon's servers. +Without the -prefix option, /tmp/xyz/pdq.html would be stored +as http://s3.amazonaws.com/test/pdq.html.

+
-blocking
+

This is the standard blocking option.

+
-compare
+

If present, this is passed to each invocation of S3::Put. +Naturally, S3::Configure -default-compare is used +if this is not specified.

+
-x-amz-meta-*
+

If present, this is passed to each invocation of S3::Put. All copied +files will have the same metadata.

+
-acl
+

If present, this is passed to each invocation of S3::Put.

+
-delete
+

This defaults to false. If true, resources in the destination that +are not in the source directory are deleted with S3::Delete. +Since only regular files are considered, the existance of a symlink, +pipe, device, or directory in the local source will not +prevent the deletion of a remote resource with a corresponding name.

+
-error
+

This controls the behavior of S3::Push in the event that +S3::Put throws an error. Note that +errors encountered on the local file system or in reading the +list of resources in the remote bucket always throw errors. +This option allows control over "partial" errors, when some +files were copied and some were not. S3::Delete is always +finished up, with errors simply recorded in the return result.

+
+
throw
+

The error is rethrown with the same errorCode.

+
break
+

Processing stops without throwing an error, the error is recorded +in the return value, and the command returns with a normal return. +The calls to S3::Delete are not started.

+
continue
+

This is the default. Processing continues without throwing, +recording the error in the return result, and resuming with the +next file in the local directory to be copied.

+
+
-progress
+

If this is specified and the indicated script prefix is not empty, the +indicated script prefix will be invoked several times in the caller's +context with additional arguments at various points in the processing. +This allows progress reporting without backgrounding. The provided +prefix will be invoked with additional arguments, with the first +additional argument indicating what part of the process is being +reported on. The prefix is initially invoked with args as the +first additional argument and a dictionary representing the normalized +arguments to the S3::Push call as the second additional argument. +Then the prefix is invoked with local as the first additional +argument and a list of suffixes of the files to be considered as the +second argument. Then the prefix is invoked with remote as the +first additional argument and a list of suffixes existing in the remote +bucket as the second additional argument. Then, for each file in the +local list, the prefix will be invoked with start as the first +additional argument and the common suffix as the second additional +argument. When S3::Put returns for that file, the prefix will be +invoked with copy as the first additional argument, the common +suffix as the second additional argument, and a third argument that will +be "copied" (if S3::Put sent the resource), "skipped" (if +S3::Put decided not to based on -compare), or the errorCode +that S3::Put threw due to unexpected errors (in which case the +third argument is a list that starts with "S3"). When all files have +been transfered, the prefix may be invoked zero or more times with +delete as the first additional argument and the suffix of the +resource being deleted as the second additional argument, with a third +argument being either an empty string (if the delete worked) or the +errorCode from S3::Delete if it failed. Finally, the prefix +will be invoked with finished as the first additional argument +and the return value as the second additional argument.

+
+

The return result from this command is a dictionary. They keys are the +suffixes (i.e., the common portion of the path after the -directory +and -prefix), while the values are either "copied", "skipped" (if +-compare indicated not to copy the file), or the errorCode +thrown by S3::Put, as appropriate. If -delete was true, +there may also be entries for suffixes with the value "deleted" or +"notdeleted", indicating whether the attempted S3::Delete +worked or not, respectively. There is one additional pair in the return +result, whose key is the empty string and whose value is a nested dictionary. +The keys of this nested dictionary include "filescopied" (the number of +files successfully copied), "bytescopied" (the number of data bytes in +the files copied, excluding headers, metadata, etc), "compareskipped" (the +number of files not copied due to -compare mode), "errorskipped" +(the number of files not copied due to thrown errors), "filesdeleted" +(the number of resources deleted due to not having corresponding files +locally, or 0 if -delete is false), and "filesnotdeleted" +(the number of resources whose deletion was attempted but failed).

+

Note that this is currently implemented somewhat inefficiently. +It fetches the bucket listing (including timestamps and eTags), +then calls S3::Put, which uses HEAD to find the timestamps +and eTags again. Correcting this with no API change +is planned for a future upgrade.

+
S3::Pull ?-bucket bucketname? -directory directoryname ?-prefix prefixstring? ?-blocking boolean? ?-compare comparemode? ?-delete boolean? ?-timestamp aws|now? ?-error throw|break|continue? ?-progress scriptprefix?
+

This synchronises a remote bucket with a local directory by pulling the +differences using S3::Get If something has been changed locally but not +in the bucket, those difference may be lost. This is not a general two-way +synchronization mechanism. (See S3::Sync for that.) +This creates directories +if needed; new directories are created with default permissions. Note that +resource names are case sensitive, so changing the case of a file on a +Windows machine may lead to otherwise-unnecessary transfers. Also, try not +to store data in resources that end with a slash, or which are prefixes of +resources that otherwise would start with a slash; i.e., don't use this if +you store data in resources whose names have to be directories locally.

+

Note that this is currently implemented somewhat inefficiently. +It fetches the bucket listing (including timestamps and eTags), +then calls S3::Get, which uses HEAD to find the timestamps +and eTags again. Correcting this with no API change +is planned for a future upgrade.

+
+
-bucket
+

This names the bucket from which data will be pulled.

+
-directory
+

This names the local directory into which files will be written +It must exist, be readable via [glob], writable for file creation, +and so on. If only some of the files therein are writable, +S3::Pull will GET +those files that are writable and return in its results the list +of files that could not be opened.

+
-prefix
+

The prefix of resources that will be considered for retrieval. +See S3::Push for more details, examples, etc. (Of course, +S3::Pull reads rather than writes, but the prefix is +treated similarly.)

+
-blocking
+

This is the standard blocking option.

+
-compare
+

This is passed to each invocation of S3::Get if provided. +Naturally, S3::Configure -default-compare is +used if this is not provided.

+
-timestamp
+

This is passed to each invocation of S3::Get if provided.

+
-delete
+

If this is specified and true, files that exist in the -directory +that are not in the -prefix will be deleted after all resources +have been copied. In addition, empty directories (other than the +top-level -directory) will be deleted, as +Amazon S3 has no concept of an empty directory.

+
-error
+

See S3::Push for a description of this option.

+
-progress
+

See S3::Push for a description of this option. +It differs slightly in that local directories may be included +with a trailing slash to indicate they are directories.

+
+

The return value from this command is a dictionary. It +is identical in form and meaning to the description of the +return result of S3::Push. It differs only in that +directories may be included, with a trailing slash in their name, +if they are empty and get deleted.

+
S3::Toss ?-bucket bucketname? -prefix prefixstring ?-blocking boolean? ?-error throw|break|continue? ?-progress scriptprefix?
+

This deletes some or all resources within a bucket. It would be +considered a "recursive delete" had Amazon implemented actual +directories.

+
+
-bucket
+

The bucket from which resources will be deleted.

+
-blocking
+

The standard blocking option.

+
-prefix
+

The prefix for resources to be deleted. Any resource that +starts with this string will be deleted. This is required. +To delete everything in the bucket, pass an empty string +for the prefix.

+
-error
+

If this is "throw", S3::Toss rethrows any errors +it encounters. If this is "break", S3::Toss returns +with a normal return after the first error, recording that +error in the return result. If this is "continue", which is +the default, S3::Toss continues on and lists all +errors in the return result.

+
-progress
+

If this is specified and not an empty string, the script +prefix will be invoked several times in the context of the caller +with additional arguments appended. Initially, it will be invoked +with the first additional argument being args and the second +being the processed list of arguments to S3::Toss. Then it +is invoked with remote as the first additional argument and +the list of suffixes in the bucket to be deleted as the second +additional argument. Then it is invoked with the first additional +argument being delete and the second additional argument being +the suffix deleted and the third additional argument being "deleted" +or "notdeleted" depending on whether S3::Delete threw an error. +Finally, the script prefix is invoked with a first additional argument +of "finished" and a second additional argument of the return value.

+
+

The return value is a dictionary. The keys are the suffixes of files +that S3::Toss attempted to delete, and whose values are either +the string "deleted" or "notdeleted". There is also one additional +pair, whose key is the empty string and whose value is an embedded +dictionary. The keys of this embedded dictionary include +"filesdeleted" and "filesnotdeleted", each of which has integer values.

+
+
+

LIMITATIONS

+
    +

  • The pure-Tcl MD5 checking is slow. If you are processing +files in the megabyte range, consider ensuring binary support is available.

    • +

  • The commands S3::Pull and S3::Push fetch a +directory listing which includes timestamps and MD5 hashes, +then invoke S3::Get and S3::Put. If +a complex -compare mode is specified, S3::Get and +S3::Put will invoke a HEAD operation for each file to fetch +timestamps and MD5 hashes of each resource again. It is expected that +a future release of this package will solve this without any API changes.

    • +

  • The commands S3::Pull and S3::Push fetch a +directory listing without using -max-count. The entire +directory is pulled into memory at once. For very large buckets, +this could be a performance problem. The author, at this time, +does not plan to change this behavior. Welcome to Open Source.

    • +

  • S3::Sync is neither designed nor implemented yet. +The intention would be to keep changes synchronised, so changes +could be made to both the bucket and the local directory and +be merged by S3::Sync.

    • +

  • Nor is +-compare calc fully implemented. This is primarily due to +Windows not providing a convenient method for distinguishing between +local files that are "public-read" or "public-read-write". Assistance +figuring out TWAPI for this would be appreciated. The U**X semantics +are difficult to map directly as well. See the source for details. +Note that there are not tests for calc, since it isn't done yet.

    • +

  • The HTTP processing is implemented within the library, +rather than using a "real" HTTP package. Hence, multi-line headers +are not (yet) handled correctly. Do not include carriage returns or +linefeeds in x-amz-meta-* headers, content-type values, and so on. +The author does not at this time expect to improve this.

    • +

  • Internally, S3::Push and S3::Pull and S3::Toss +are all very similar and should be refactored.

    • +

  • The idea of using -compare never +-delete true to delete files that have been +deleted from one place but not the other yet not copying +changed files is untested.

    • +
+
+

USAGE SUGGESTIONS

+

To fetch a "directory" out of a bucket, make changes, and store it back:

+
+file mkdir ./tempfiles
+S3::Pull -bucket sample -prefix of/interest -directory ./tempfiles \
+  -timestamp aws
+do_my_process ./tempfiles other arguments
+S3::Push -bucket sample -prefix of/interest -directory ./tempfiles \
+  -compare newer -delete true
+
+

To delete files locally that were deleted off of S3 but not otherwise +update files:

+
+S3::Pull -bucket sample -prefix of/interest -directory ./myfiles \
+  -compare never -delete true
+
+
+

FUTURE DEVELOPMENTS

+

The author intends to work on several additional projects related to +this package, in addition to finishing the unfinished features.

+

First, a command-line program allowing browsing of buckets and +transfer of files from shell scripts and command prompts is useful.

+

Second, a GUI-based program allowing visual manipulation of +bucket and resource trees not unlike Windows Explorer would +be useful.

+

Third, a command-line (and perhaps a GUI-based) program called +"OddJob" that will use S3 to synchronize computation amongst +multiple servers running OddJob. An S3 bucket will be set up +with a number of scripts to run, and the OddJob program can +be invoked on multiple machines to run scripts on all the machines, +each moving on to the next unstarted task as it finishes each. +This is still being designed, and it is intended primarily +to be run on Amazon's Elastic Compute Cloud.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category amazon-s3 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/amazon-s3/xsxp.html Index: embedded/www/tcllib/files/modules/amazon-s3/xsxp.html ================================================================== --- embedded/www/tcllib/files/modules/amazon-s3/xsxp.html +++ embedded/www/tcllib/files/modules/amazon-s3/xsxp.html @@ -0,0 +1,238 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

xsxp(n) 1.0 tcllib "Amazon S3 Web Service Utilities"

+

Name

+

xsxp - eXtremely Simple Xml Parser

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require xsxp 1
    • +
  • package require xml
    • +
+ +
+
+

Description

+

This package provides a simple interface to parse XML into a pure-value list. +It also provides accessor routines to pull out specific subtags, +not unlike DOM access. +This package was written for and is used by Darren New's Amazon S3 access package.

+

This is pretty lame, but I needed something like this for S3, +and at the time, TclDOM would not work with the new 8.5 Tcl +due to version number problems.

+

In addition, this is a pure-value implementation. There is no +garbage to clean up in the event of a thrown error, for example. +This simplifies the code for sufficiently small XML documents, +which is what Amazon's S3 guarantees.

+

Copyright 2006 Darren New. All Rights Reserved. +NO WARRANTIES OF ANY TYPE ARE PROVIDED. +COPYING OR USE INDEMNIFIES THE AUTHOR IN ALL WAYS. +This software is licensed under essentially the same +terms as Tcl. See LICENSE.txt for the terms.

+
+

COMMANDS

+

The package implements five rather simple procedures. +One parses, one is for debugging, and the rest pull various +parts of the parsed document out for processing.

+
+
xsxp::parse xml
+

This parses an XML document (using the standard xml tcllib module in a SAX sort of way) and builds a data structure which it returns if the parsing succeeded. The return value is referred to herein as a "pxml", or "parsed xml". The list consists of two or more elements:

+
    +

  • The first element is the name of the tag.

    • +

  • The second element is an array-get formatted list of key/value pairs. The keys are attribute names and the values are attribute values. This is an empty list if there are no attributes on the tag.

    • +

  • The third through end elements are the children of the node, if any. Each child is, recursively, a pxml.

    • +

  • Note that if the zero'th element, i.e. the tag name, is "%PCDATA", then +the attributes will be empty and the third element will be the text of the element. In addition, if an element's contents consists only of PCDATA, it will have only one child, and all the PCDATA will be concatenated. In other words, +this parser works poorly for XML with elements that contain both child tags and PCDATA. Since Amazon S3 does not do this (and for that matter most +uses of XML where XML is a poor choice don't do this), this is probably +not a serious limitation.

    • +
+
xsxp::fetch pxml path ?part?
+

pxml is a parsed XML, as returned from xsxp::parse. +path is a list of element tag names. Each element is the name +of a child to look up, optionally followed by a +hash ("#") and a string of digits. An empty list or an initial empty element +selects pxml. If no hash sign is present, the behavior is as if "#0" +had been appended to that element. (In addition to a list, slashes can separate subparts where convenient.)

+

An element of path scans the children at the indicated level +for the n'th instance of a child whose tag matches the part of the +element before the hash sign. If an element is simply "#" followed +by digits, that indexed child is selected, regardless of the tags +in the children. Hence, an element of "#3" will always select +the fourth child of the node under consideration.

+

part defaults to "%ALL". It can be one of the following case-sensitive terms:

+
+
%ALL
+

returns the entire selected element.

+
%TAGNAME
+

returns lindex 0 of the selected element.

+
%ATTRIBUTES
+

returns index 1 of the selected element.

+
%CHILDREN
+

returns lrange 2 through end of the selected element, +resulting in a list of elements being returned.

+
%PCDATA
+

returns a concatenation of all the bodies of +direct children of this node whose tag is %PCDATA. +It throws an error if no such children are found. That +is, part=%PCDATA means return the textual content found +in that node but not its children nodes.

+
%PCDATA?
+

is like %PCDATA, but returns an empty string if +no PCDATA is found.

+
+

For example, to fetch the first bold text from the fifth paragraph of the body of your HTML file,

+
xsxp::fetch $pxml {body p#4 b} %PCDATA
+
+
xsxp::fetchall pxml_list path ?part?
+

This iterates over each PXML in pxml_list (which must be a list +of pxmls) selecting the indicated path from it, building a new list +with the selected data, and returning that new list.

+

For example, pxml_list might be +the %CHILDREN of a particular element, and the path and part +might select from each child a sub-element in which we're interested.

+
xsxp::only pxml tagname
+

This iterates over the direct children of pxml and selects only +those with tagname as their tag. Returns a list of matching +elements.

+
xsxp::prettyprint pxml ?chan?
+

This outputs to chan (default stdout) a pretty-printed +version of pxml.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category amazon-s3 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/asn/asn.html Index: embedded/www/tcllib/files/modules/asn/asn.html ================================================================== --- embedded/www/tcllib/files/modules/asn/asn.html +++ embedded/www/tcllib/files/modules/asn/asn.html @@ -0,0 +1,498 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

asn(n) 0.8 tcllib "ASN.1 processing"

+

Name

+

asn - ASN.1 BER encoder/decoder

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require asn ?0.8.4?
    • +
+ +
+
+

Description

+

The asn package provides partial de- and encoder +commands for BER encoded ASN.1 data. It can also be used for +decoding DER, which is a restricted subset of BER.

+

ASN.1 is a standard Abstract Syntax Notation, and BER are its +Basic Encoding Rules.

+

See http://asn1.elibel.tm.fr/en/standards/index.htm for more +information about the standard.

+

Also see http://luca.ntop.org/Teaching/Appunti/asn1.html for +A Layman's Guide to a Subset of ASN.1, BER, and DER, an RSA +Laboratories Technical Note by Burton S. Kaliski Jr. (Revised November +1, 1993). A text version of this note is part of the module sources +and should be read by any implementor.

+
+

PUBLIC API

+

ENCODER

+
+
::asn::asnSequence evalue...
+

Takes zero or more encoded values, packs them into an ASN sequence and +returns its encoded binary form.

+
::asn::asnSequenceFromList elist
+

Takes a list of encoded values, packs them into an ASN sequence and +returns its encoded binary form.

+
::asn::asnSet evalue...
+

Takes zero or more encoded values, packs them into an ASN set and +returns its encoded binary form.

+
::asn::asnSetFromList elist
+

Takes a list of encoded values, packs them into an ASN set and +returns its encoded binary form.

+
::asn::asnApplicationConstr appNumber evalue...
+

Takes zero or more encoded values, packs them into an ASN application +construct and returns its encoded binary form.

+
::asn::asnApplication appNumber data
+

Takes a single encoded value data, packs it into an ASN +application construct and returns its encoded binary form.

+
::asn::asnChoice appNumber evalue...
+

Takes zero or more encoded values, packs them into an ASN choice +construct and returns its encoded binary form.

+
::asn::asnChoiceConstr appNumber evalue...
+

Takes zero or more encoded values, packs them into an ASN choice +construct and returns its encoded binary form.

+
::asn::asnInteger number
+

Returns the encoded form of the specified integer +number.

+
::asn::asnEnumeration number
+

Returns the encoded form of the specified enumeration id +number.

+
::asn::asnBoolean bool
+

Returns the encoded form of the specified boolean value +bool.

+
::asn::asnContext context data
+

Takes an encoded value and packs it into a constructed value with +application tag, the context number.

+
::asn::asnContextConstr context evalue...
+

Takes zero or more encoded values and packs them into a constructed +value with application tag, the context number.

+
::asn::asnObjectIdentifier idlist
+

Takes a list of at least 2 integers describing an object identifier +(OID) value, and returns the encoded value.

+
::asn::asnUTCTime utcstring
+

Returns the encoded form of the specified UTC time string.

+
::asn::asnNull
+

Returns the NULL encoding.

+
::asn::asnBitString string
+

Returns the encoded form of the specified string.

+
::asn::asnOctetString string
+

Returns the encoded form of the specified string.

+
::asn::asnNumericString string
+

Returns the string encoded as ASN.1 NumericString. Raises an +error if the string contains characters other than decimal +numbers and space.

+
::asn::asnPrintableString string
+

Returns the string encoding as ASN.1 PrintableString. Raises an +error if the string contains characters which are not allowed by +the Printable String datatype. The allowed characters are A-Z, a-z, +0-9, space, apostrophe, colon, parentheses, plus, minus, comma, +period, forward slash, question mark, and the equals sign.

+
::asn::asnIA5String string
+

Returns the string encoded as ASN.1 IA5String. Raises an error +if the string contains any characters outside of the US-ASCII +range.

+
::asn::asnBMPString string
+

Returns the string encoded as ASN.1 Basic Multilingual Plane +string (Which is essentialy big-endian UCS2).

+
::asn::asnUTF8String string
+

Returns the string encoded as UTF8 String. Note that some legacy +applications such as Windows CryptoAPI do not like UTF8 strings. Use +BMPStrings if you are not sure.

+
::asn::asnString string
+

Returns an encoded form of string, choosing the most restricted +ASN.1 string type possible. If the string contains non-ASCII +characters, then there is more than one string type which can be +used. See ::asn::defaultStringType.

+
::asn::defaultStringType ?type?
+

Selects the string type to use for the encoding of non-ASCII +strings. Returns current default when called without argument. If the +argument type is supplied, it should be either UTF8 or +BMP to choose UTF8String or BMPString respectively.

+
+
+

DECODER

+

General notes:

+
    +

  1. Nearly all decoder commands take two arguments. These arguments are variable +names, except for ::asn::asnGetResponse. The first variable +contains the encoded ASN value to decode at the beginning, and more, +and the second variable is where the value is stored to. The remainder +of the input after the decoded value is stored back into the +datavariable.

    2. +

  2. After extraction the data variable is always modified first, before by +writing the extracted value to its variable. This means that if both +arguments refer to the same variable, it will always contain the +extracted value after the call, and not the remainder of the input.

    3. +
+
+
::asn::asnPeekByte data_var byte_var
+

Retrieve the first byte of the data, without modifing data_var. +This can be used to check for implicit tags.

+
::asn::asnGetLength data_var length_var
+

Decode the length information for a block of BER data. The tag has already +to be removed from the data.

+
::asn::asnGetResponse chan data_var
+

Reads an encoded ASN sequence from the channel chan and +stores it into the variable named by data_var.

+
::asn::asnGetInteger data_var int_var
+

Assumes that an encoded integer value is at the front of the data +stored in the variable named data_var, extracts and stores it +into the variable named by int_var. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands.

+
::asn::asnGetEnumeration data_var enum_var
+

Assumes that an enumeration id is at the front of the data stored in +the variable named data_var, and stores it into the variable +named by enum_var. Additionally removes all bytes associated +with the value from the data for further processing by the following +decoder commands.

+
::asn::asnGetOctetString data_var string_var
+

Assumes that a string is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by string_var. Additionally removes all bytes associated with +the value from the data for further processing by the following +decoder commands.

+
::asn::asnGetString data_var string_var ?type_var?
+

Decodes a user-readable string. This is a convenience function which +is able to automatically distinguish all supported ASN.1 string types +and convert the input value appropriately. +See ::asn::asnGetPrintableString, ::asnGetIA5String, etc. +below for the type-specific conversion commands.

+

If the optional third argument type_var is supplied, then the +type of the incoming string is stored in the variable named by it.

+

The function throws the error +"Invalid command name asnGetSomeUnsupportedString" if the +unsupported string type Unsupported is encountered. You can +create the appropriate function +"asn::asnGetSomeUnsupportedString" in your application if +neccessary.

+
::asn::asnGetNumericString data_var string_var
+

Assumes that a numeric string value is at the front of the data stored +in the variable named data_var, and stores it into the variable +named by string_var. Additionally removes all bytes associated +with the value from the data for further processing by the following +decoder commands.

+
::asn::asnGetPrintableString data_var string_var
+

Assumes that a printable string value is at the front of the data +stored in the variable named data_var, and stores it into the +variable named by string_var. Additionally removes all bytes +associated with the value from the data for further processing by the +following decoder commands.

+
::asn::asnGetIA5String data_var string_var
+

Assumes that a IA5 (ASCII) string value is at the front of the data +stored in the variable named data_var, and stores it into the +variable named by string_var. Additionally removes all bytes +associated with the value from the data for further processing by the +following decoder commands.

+
::asn::asnGetBMPString data_var string_var
+

Assumes that a BMP (two-byte unicode) string value is at the front of +the data stored in the variable named data_var, and stores it +into the variable named by string_var, converting it into a +proper Tcl string. Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+
::asn::asnGetUTF8String data_var string_var
+

Assumes that a UTF8 string value is at the front of the data stored in +the variable named data_var, and stores it into the variable +named by string_var, converting it into a proper Tcl string. +Additionally removes all bytes associated with the value from the data +for further processing by the following decoder commands.

+
::asn::asnGetUTCTime data_var utc_var
+

Assumes that a UTC time value is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by utc_var. The UTC time value is stored as a string, which has to +be decoded with the usual clock scan commands. +Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+
::asn::asnGetBitString data_var bits_var
+

Assumes that a bit string value is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by bits_var as a string containing only 0 and 1. +Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+
::asn::asnGetObjectIdentifier data_var oid_var
+

Assumes that a object identifier (OID) value is at the front of the data +stored in the variable named data_var, and stores it into the variable +named by oid_var as a list of integers. +Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+
::asn::asnGetBoolean data_var bool_var
+

Assumes that a boolean value is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by bool_var. Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+
::asn::asnGetNull data_var
+

Assumes that a NULL value is at the front of the data stored in the +variable named data_var and removes the bytes used to encode it +from the data.

+
::asn::asnGetSequence data_var sequence_var
+

Assumes that an ASN sequence is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by sequence_var. Additionally removes all bytes associated with +the value from the data for further processing by the following +decoder commands.

+

The data in sequence_var is encoded binary and has to be +further decoded according to the definition of the sequence, using the +decoder commands here.

+
::asn::asnGetSet data_var set_var
+

Assumes that an ASN set is at the front of the data stored in the +variable named data_var, and stores it into the variable named +by set_var. Additionally removes all bytes associated with the +value from the data for further processing by the following decoder +commands.

+

The data in set_var is encoded binary and has to be further +decoded according to the definition of the set, using the decoder +commands here.

+
::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var?
+

Assumes that an ASN application construct is at the front of the data +stored in the variable named data_var, and stores its id into +the variable named by appNumber_var. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands. +If a content_var is specified, then the command places all data +associated with it into the named variable, in the binary form which +can be processed using the decoder commands of this package. +If a encodingType_var is specified, then that var is set to 1 if +the encoding is constructed and 0 if it is primitive.

+

Otherwise it is the responsibility of the caller to decode the +remainder of the application construct based on the id retrieved by +this command, using the decoder commands of this package.

+
::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var?
+

Assumes that an ASN context tag construct is at the front of the data +stored in the variable named data_var, and stores its id into +the variable named by contextNumber_var. Additionally removes all +bytes associated with the value from the data for further processing +by the following decoder commands. +If a content_var is specified, then the command places all data +associated with it into the named variable, in the binary form which +can be processed using the decoder commands of this package. +If a encodingType_var is specified, then that var is set to 1 if +the encoding is constructed and 0 if it is primitive.

+

Otherwise it is the responsibility of the caller to decode the +remainder of the construct based on the id retrieved by this command, +using the decoder commands of this package.

+
+
+

HANDLING TAGS

+

Working with ASN.1 you often need to decode tagged values, which use a tag thats different +from the universal tag for a type. In those cases you have to replace the tag with the universal tag +used for the type, to decode the value. +To decode a tagged value use the ::asn::asnRetag to change the tag to the appropriate type +to use one of the decoders for primitive values. +To help with this the module contains three functions:

+
+
::asn::asnPeekTag data_var tag_var tagtype_var constr_var
+

The ::asn::asnPeekTag command can be used to take a peek at the data and decode the tag value, without +removing it from the data. The tag_var gets set to the tag number, while the tagtype_var gets set +to the class of the tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The constr_var is set to 1 if the +tag is for a constructed value, and to 0 for not constructed. It returns the length of the tag.

+
::asn::asnTag tagnumber ?class? ?tagstyle?
+

The ::asn::asnTag can be used to create a tag value. The tagnumber gives the number of the tag, while +the class gives one of the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to just the first letter (U,C,A,P), +default is UNIVERSAL. +The tagstyle is either C for Constructed encoding, or P for primitve encoding. It defaults to P. You can also use 1 instead of C and +0 instead of P for direct use of the values returned by ::asn::asnPeekTag.

+
::asn::asnRetag data_var newTag
+

Replaces the tag in front of the data in data_var with newTag. The new Tag can be created using the ::asn::asnTag command.

+
+
+
+

EXAMPLES

+

Examples for the usage of this package can be found in the +implementation of package ldap.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category asn of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32.html Index: embedded/www/tcllib/files/modules/base32/base32.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32.html +++ embedded/www/tcllib/files/modules/base32/base32.html @@ -0,0 +1,194 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

base32(n) 0.1 tcllib "Base32 encoding"

+

Name

+

base32 - base32 standard encoding

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require base32::core ?0.1?
    • +
  • package require base32 ?0.1?
    • +
+ +
+
+

Description

+

This package provides commands for encoding and decoding of strings +into and out of the standard base32 encoding as specified in RFC 3548.

+
+

API

+
+
::base32::encode string
+

This command encodes the given string in base32 and returns the +encoded string as its result. The result may be padded with the +character = to signal a partial encoding at the end of the +input string.

+
::base32::decode estring
+

This commands takes the estring and decodes it under the +assumption that it is a valid base32 encoded string. The result of the +decoding is returned as the result of the command.

+

Note that while the encoder will generate only uppercase characters +this decoder accepts input in lowercase as well.

+

The command will always throw an error whenever encountering +conditions which signal some type of bogus input, namely if

+
    +

  1. the input contains characters which are not valid output of a base32 encoder,

    2. +

  2. the length of the input is not a multiple of eight,

    3. +

  3. padding appears not at the end of input, but in the middle,

    4. +

  4. the padding has not of length six, four, three, or one characters,

    5. +
+
+
+

Code map

+

The code map used to convert 5-bit sequences is shown below, with the +numeric id of the bit sequences to the left and the character used to +encode it to the right. It should be noted that the characters "0" and +"1" are not used by the encoding. This is done as these characters can +be easily confused with "O", "o" and "l" (L).

+
+	0 A    9 J   18 S   27 3
+	1 B   10 K   19 T   28 4
+	2 C   11 L   20 U   29 5
+	3 D   12 M   21 V   30 6
+	4 E   13 N   22 W   31 7
+	5 F   14 O   23 X
+	6 G   15 P   24 Y
+	7 H   16 Q   25 Z
+	8 I   17 R   26 2
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base32 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32core.html Index: embedded/www/tcllib/files/modules/base32/base32core.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32core.html +++ embedded/www/tcllib/files/modules/base32/base32core.html @@ -0,0 +1,184 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

base32::core(n) 0.1 tcllib "Base32 encoding"

+

Name

+

base32::core - Expanding basic base32 maps

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require base32::core ?0.1?
    • +
+ +
+
+

Description

+

This package provides generic commands for the construction of full +base32 mappings from a basic mapping listing just the codes and +associated characters. The full mappings, regular and inverse, created +here map to and from bit sequences, and also handle the partial +mappings at the end of a string.

+

This is in essence an internal package to be used by implementors of a +base32 en- and decoder. A regular user has no need of this package at +all.

+
+

API

+
+
::base32::core::define map forwvar backwvar ivar
+

This command computes full forward and backward (inverse) mappings +from the basic map and stores them in the variables named by +forwvar and backwvar resp. It also constructs a regexp +pattern for the detection of invalid characters in supposedly base32 +encoded input and stores it in the variable named by ivar.

+
::base32::core::valid string pattern mvar
+

This command checks if the input string is a valid base32 +encoded string, based on the pattern of invalid characters as +generated by ::base32::core::define, and some other general +rules.

+

The result of the command is a boolean flag. Its value is True +for a valid string, and False otherwise. In the latter +case an error message describing the problem with the input is stored +into the variable named by mvar. The variable is not touched if +the input was found to be valid.

+

The rules checked by the command, beyond rejection of bad characters, +are:

+
    +

  1. The length of the input is not a multiple of eight,

    2. +

  2. The padding appears not at the end of input, but in the middle,

    3. +

  3. The padding has not of length six, four, three, or one characters,

    4. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base32 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base32/base32hex.html Index: embedded/www/tcllib/files/modules/base32/base32hex.html ================================================================== --- embedded/www/tcllib/files/modules/base32/base32hex.html +++ embedded/www/tcllib/files/modules/base32/base32hex.html @@ -0,0 +1,196 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

base32::hex(n) 0.1 tcllib "Base32 encoding"

+

Name

+

base32::hex - base32 extended hex encoding

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require base32::core ?0.1?
    • +
  • package require base32::hex ?0.1?
    • +
+ +
+
+

Description

+

This package provides commands for encoding and decoding of strings +into and out of the extended hex base32 encoding as specified in the +RFC 3548bis draft.

+
+

API

+
+
::base32::hex::encode string
+

This command encodes the given string in extended hex base32 and +returns the encoded string as its result. The result may be padded +with the character = to signal a partial encoding at the end +of the input string.

+
::base32::hex::decode estring
+

This commands takes the estring and decodes it under the +assumption that it is a valid extended hex base32 encoded string. The +result of the decoding is returned as the result of the command.

+

Note that while the encoder will generate only uppercase characters +this decoder accepts input in lowercase as well.

+

The command will always throw an error whenever encountering +conditions which signal some type of bogus input, namely if

+
    +

  1. the input contains characters which are not valid output + of a extended hex base32 encoder,

    2. +

  2. the length of the input is not a multiple of eight,

    3. +

  3. padding appears not at the end of input, but in the middle,

    4. +

  4. the padding has not of length six, four, three, or one characters,

    5. +
+
+
+

Code map

+

The code map used to convert 5-bit sequences is shown below, with the +numeric id of the bit sequences to the left and the character used to +encode it to the right. The important feature of the extended hex +mapping is that the first 16 codes map to the digits and hex +characters.

+
+	0 0    9 9        18 I   27 R
+	1 1   10 A        19 J   28 S
+	2 2   11 B        20 K   29 T
+	3 3   12 C        21 L   30 U
+	4 4   13 D        22 M   31 V
+	5 5   14 E        23 N
+	6 6   15 F        24 O
+	7 7        16 G   25 P
+	8 8        17 H   26 Q
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base32 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/ascii85.html Index: embedded/www/tcllib/files/modules/base64/ascii85.html ================================================================== --- embedded/www/tcllib/files/modules/base64/ascii85.html +++ embedded/www/tcllib/files/modules/base64/ascii85.html @@ -0,0 +1,192 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ascii85(n) 1.0 tcllib "Text encoding & decoding binary data"

+

Name

+

ascii85 - ascii85-encode/decode binary data

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require ascii85 ?1.0?
    • +
+ +
+
+

Description

+

This package provides procedures to encode binary data into ascii85 and back.

+
+
::ascii85::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string
+

Ascii85 encodes the given binary string and returns the encoded +result. Inserts the character wrapchar every maxlen +characters of output. wrapchar defaults to newline. maxlen +defaults to 76.

+

Note well: If your string is not simple ascii you should fix +the string encoding before doing ascii85 encoding. See the examples.

+

The command will throw an error for negative values of maxlen, +or if maxlen is not an integer number.

+
::ascii85::decode string
+

Ascii85 decodes the given string and returns the binary data. +The decoder ignores whitespace in the string, as well as tabs and +newlines.

+
+
+

EXAMPLES

+
+% ascii85::encode "Hello, world"
+87cURD_*#TDfTZ)
+
+
+% ascii85::encode [string repeat xyz 24]
+G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G
+^4U[H$X^\H?a^]
+% ascii85::encode -wrapchar "" [string repeat xyz 24]
+G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]G^4U[H$X^\H?a^]
+
+
+# NOTE: ascii85 encodes BINARY strings.
+% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
+% set encoded [ascii85::encode $chemical]
+6fN]R8E,5Pidu\UiduhZidua
+% set caffeine [encoding convertfrom utf-8 [ascii85::decode $encoded]]
+
+
+

References

+
    +

  1. http://en.wikipedia.org/wiki/Ascii85

    2. +

  2. Postscript Language Reference Manual, 3rd Edition, page 131. + http://www.adobe.com/devnet/postscript/pdfs/PLRM.pdf

    3. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base64 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/base64.html Index: embedded/www/tcllib/files/modules/base64/base64.html ================================================================== --- embedded/www/tcllib/files/modules/base64/base64.html +++ embedded/www/tcllib/files/modules/base64/base64.html @@ -0,0 +1,186 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

base64(n) 2.4.2 tcllib "Text encoding & decoding binary data"

+

Name

+

base64 - base64-encode/decode binary data

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8
    • +
  • package require base64 ?2.4.2?
    • +
+ +
+
+

Description

+

This package provides procedures to encode binary data into base64 and back.

+
+
::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string
+

Base64 encodes the given binary string and returns the encoded +result. Inserts the character wrapchar every maxlen +characters of output. wrapchar defaults to newline. maxlen +defaults to 76.

+

Note that if maxlen is set to 0, the +output will not be wrapped at all.

+

Note well: If your string is not simple ascii you should fix +the string encoding before doing base64 encoding. See the examples.

+

The command will throw an error for negative values of maxlen, +or if maxlen is not an integer number.

+
::base64::decode string
+

Base64 decodes the given string and returns the binary data. +The decoder ignores whitespace in the string.

+
+
+

EXAMPLES

+
+% base64::encode "Hello, world"
+SGVsbG8sIHdvcmxk
+
+
+% base64::encode [string repeat xyz 20]
+eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
+eHl6eHl6eHl6
+% base64::encode -wrapchar "" [string repeat xyz 20]
+eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
+
+
+# NOTE: base64 encodes BINARY strings.
+% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
+% set encoded [base64::encode $chemical]
+Q+KCiEjigoHigoBO4oKET+KCgg==
+% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base64 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/uuencode.html Index: embedded/www/tcllib/files/modules/base64/uuencode.html ================================================================== --- embedded/www/tcllib/files/modules/base64/uuencode.html +++ embedded/www/tcllib/files/modules/base64/uuencode.html @@ -0,0 +1,208 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uuencode(n) 1.1.4 tcllib "Text encoding & decoding binary data"

+

Name

+

uuencode - UU-encode/decode binary data

+
+ + +

Description

+

This package provides a Tcl-only implementation of the +uuencode(1) and uudecode(1) commands. This encoding +packs binary data into printable ASCII characters.

+
+
::uuencode::encode string
+

returns the uuencoded data. This will encode all the data passed in +even if this is longer than the uuencode maximum line length. If the +number of input bytes is not a multiple of 3 then additional 0 bytes +are added to pad the string.

+
::uuencode::decode string
+

Decodes the given encoded data. This will return any padding +characters as well and it is the callers responsibility to deal with +handling the actual length of the encoded data. (see uuencode).

+
::uuencode::uuencode ?-name string? ?-mode octal? (-file filename | ?--? string)
+
+
::uuencode::uudecode (-file filename | ?--? string)
+

UUDecode a file or block of data. A file may contain more than one +embedded file so the result is a list where each element is a three +element list of filename, mode value and data.

+
+
+

OPTIONS

+
+
-filename name
+

Cause the uuencode or uudecode commands to read their data from the +named file rather that taking a string parameter.

+
-name string
+

The uuencoded data header line contains the suggested file name to be +used when unpacking the data. Use this option to change this from the +default of "data.dat".

+
-mode octal
+

The uuencoded data header line contains a suggested permissions bit +pattern expressed as an octal string. To change the default of 0644 +you can set this option. For instance, 0755 would be suitable for an +executable. See chmod(1).

+
+
+

EXAMPLES

+
+% set d [uuencode::encode "Hello World!"]
+2&5L;&\\@5V]R;&0A
+
+
+% uuencode::uudecode $d
+Hello World!
+
+
+% set d [uuencode::uuencode -name hello.txt "Hello World"]
+begin 644 hello.txt
++2&5L;&\@5V]R;&0`
+`
+end
+
+
+% uuencode::uudecode $d
+{hello.txt 644 {Hello World}}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base64 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/base64/yencode.html Index: embedded/www/tcllib/files/modules/base64/yencode.html ================================================================== --- embedded/www/tcllib/files/modules/base64/yencode.html +++ embedded/www/tcllib/files/modules/base64/yencode.html @@ -0,0 +1,201 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

yencode(n) 1.1.2 tcllib "Text encoding & decoding binary data"

+

Name

+

yencode - Y-encode/decode binary data

+
+ + +

Description

+

This package provides a Tcl-only implementation of the yEnc file +encoding. This is a recently introduced method of encoding binary +files for transmission through Usenet. This encoding packs binary data +into a format that requires an 8-bit clean transmission layer but that +escapes characters special to the NNTP posting protocols. See +http://www.yenc.org/ for details concerning the algorithm.

+
+
::yencode::encode string
+

returns the yEnc encoded data.

+
::yencode::decode string
+

Decodes the given yEnc encoded data.

+
::yencode::yencode ?-name string? ?-line integer? ?-crc32 boolean? (-file filename | ?--? string)
+

Encode a file or block of data.

+
::yencode::ydecode (-file filename | ?--? string)
+

Decode a file or block of data. A file may contain more than one +embedded file so the result is a list where each element is a three +element list of filename, file size and data.

+
+
+

OPTIONS

+
+
-filename name
+

Cause the yencode or ydecode commands to read their data from the +named file rather that taking a string parameter.

+
-name string
+

The encoded data header line contains the suggested file name to be +used when unpacking the data. Use this option to change this from the +default of "data.dat".

+
-line integer
+

The yencoded data header line contains records the line length used +during the encoding. Use this option to select a line length other +that the default of 128. Note that NNTP imposes a 1000 character line +length limit and some gateways may have trouble with more than 255 +characters per line.

+
-crc32 boolean
+

The yEnc specification recommends the inclusion of a cyclic redundancy +check value in the footer. Use this option to change the default from +true to false.

+
+
+% set d [yencode::yencode -file testfile.txt]
+=ybegin line=128 size=584 name=testfile.txt
+ -o- data not shown -o-
+=yend size=584 crc32=ded29f4f
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category base64 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/bee/bee.html Index: embedded/www/tcllib/files/modules/bee/bee.html ================================================================== --- embedded/www/tcllib/files/modules/bee/bee.html +++ embedded/www/tcllib/files/modules/bee/bee.html @@ -0,0 +1,372 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bee(n) 0.1 tcllib "BitTorrent"

+

Name

+

bee - BitTorrent Serialization Format Encoder/Decoder

+
+ + +

Description

+

The bee package provides de- and encoder commands for data +in bencoding (speak 'bee'), the serialization format for data and +messages used by the BitTorrent protocol.

+
+

PUBLIC API

+

ENCODER

+

The package provides one encoder command for each of the basic forms, +and two commands per container, one taking a proper tcl data structure +to encode in the container, the other taking the same information as +several arguments.

+
+
::bee::encodeString string
+

Returns the bee-encoding of the string.

+
::bee::encodeNumber integer
+

Returns the bee-encoding of the integer number.

+
::bee::encodeListArgs value...
+

Takes zero or more bee-encoded values and returns the bee-encoding of +their list.

+
::bee::encodeList list
+

Takes a list of bee-encoded values and returns the bee-encoding of the +list.

+
::bee::encodeDictArgs key value...
+

Takes zero or more pairs of keys and values and returns the +bee-encoding of the dictionary they form. The values are expected to +be already bee-encoded, but the keys must not be. Their encoding will +be done by the command itself.

+
::bee::encodeDict dict
+

Takes a dictionary list of string keys and bee-encoded values and +returns the bee-encoding of the list. Note that the keys in the input +must not be bee-encoded already. This will be done by the command +itself.

+
+
+

DECODER

+

The package provides two main decoder commands, one for decoding a +string expected to contain a complete data structure, the other for +the incremental decoding of bee-values arriving on a channel. The +latter command is asynchronous and provides the completed decoded +values to the user through a command callback.

+
+
::bee::decode string ?endvar? ?start?
+

Takes the bee-encoding in the string and returns one decoded value. In +the case of this being a container all contained values are decoded +recursively as well and the result is a properly nested tcl list +and/or dictionary.

+

If the optional endvar is set then it is the name of a variable +to store the index of the first character after the decoded +value into. In other words, if the string contains more than one value +then endvar can be used to obtain the position of the bee-value +after the bee-value currently decoded. together with start, see +below, it is possible to iterate over the string to extract all +contained values.

+

The optional start index defaults to 0, i.e. the +beginning of the string. It is the index of the first character of the +bee-encoded value to extract.

+
::bee::decodeIndices string ?endvar? ?start?
+

Takes the same arguments as ::bee::decode and returns the same +information in endvar. The result however is different. Instead +of the tcl value contained in the string it returns a list +describing the value with respect to type and location (indices for +the first and last character of the bee-value). In case of a container +the structure also contains the same information for all the embedded +values.

+

Formally the results for the various types of bee-values are:

+
+
string
+

A list containing three elements:

+
    +

  • The constant string string, denoting the type of the value.

    • +

  • An integer number greater than or equal to zero. This is the index of +the first character of the bee-value in the input string.

    • +

  • An integer number greater than or equal to zero. This is the index of +the last character of the bee-value in the input string.

    • +
+

Note that this information is present in the results for all +four types of bee-values, with only the first element changing +according to the type of the value.

+
integer
+

The result is like for strings, except that the type element contains +the constant string integer.

+
list
+

The result is like before, with two exceptions: One, the type element +contains the constant string list. And two, the result +actually contains four elements. The last element is new, and contains +the index data as described here for all elements of the bee-list.

+
dictionary
+

The result is like for strings, except that the type element contains +the constant string dict. A fourth element is present as well, +with a slightly different structure than for lists. The element is a +dictionary mapping from the strings keys of the bee-dictionary to a +list containing two elements. The first of them is the index +information for the key, and the second element is the index +information for the value the key maps to. This structure is the only +which contains not only index data, but actual values from the +bee-string. While the index information of the keys is unique enough, +i.e. serviceable as keys, they are not easy to navigate when trying to +find particular element. Using the actual keys makes this much easier.

+
+
::bee::decodeChannel chan -command cmdprefix ?-exact? ?-prefix data?
+

The command creates a decoder for a series of bee-values arriving on +the channel chan and returns its handle. This handle can be used +to remove the decoder again. +Setting up another bee decoder on chan while a bee decoder is +still active will fail with an error message.

+
+
-command
+

The command prefix cmdprefix specified by the required +option -command is used to report extracted values and +exceptional situations (error, and EOF on the channel). +The callback will be executed at the global level of the interpreter, +with two or three arguments. The exact call signatures are

+
+
cmdprefix eof token
+

The decoder has reached eof on the channel chan. No further +invocations of the callback will be made after this. The channel has +already been closed at the time of the call, and the token is +not valid anymore as well.

+
cmdprefix error token message
+

The decoder encountered an error, which is not eof. For example a +malformed bee-value. The message provides details about the +error. The decoder token is in the same state as for eof, +i.e. invalid. The channel however is kept open.

+
cmdprefix value token value
+

The decoder received and successfully decoded a bee-value. +The format of the equivalent tcl value is the same as returned +by ::bee::decode. The channel is still open and the decoder +token is valid. This means that the callback is able to remove the +decoder.

+
+
-exact
+

By default the decoder assumes that the remainder of the data in the +channel consists only of bee-values, and reads as much as possible per +event, without regard for boundaries between bee-values. This means +that if the the input contains non-bee data after a series of +bee-value the beginning of that data may be lost because it was +already read by the decoder, but not processed.

+

The -exact was made for this situation. When specified the +decoder will take care to not read any characters behind the currently +processed bee-value, so that any non-bee data is kept in the channel +for further processing after removal of the decoder.

+
-prefix
+

If this option is specified its value is assumed to be the beginning +of the bee-value and used to initialize the internal decoder +buffer. This feature is required if the creator of the decoder used +data from the channel to determine if it should create the decoder or +not. Without the option this data would be lost to the decoding.

+
+
::bee::decodeCancel token
+

This command cancels the decoder set up by ::bee::decodeChannel +and represented by the handle token.

+
::bee::decodePush token string
+

This command appends the string to the internal decoder +buffer. It is the runtime equivalent of the option -prefix of +::bee::decodeChannel. Use it to push data back into the decoder +when the value callback used data from the channel to +determine if it should decode another bee-value or not.

+
+
+
+

FORMAT DEFINITION

+

Data in the bee serialization format is constructed from two basic +forms, and two container forms. The basic forms are strings and +integer numbers, and the containers are lists and dictionaries.

+
+
String S
+

A string S of length L is encoded by the string +"L:S", where the length is written out in textual +form.

+
Integer N
+

An integer number N is encoded by the string +"iNe".

+
List v1 ... vn
+

A list of the values v1 to vn is encoded by the string +"lBV1...BVne" +where "BVi" is the bee-encoding of the value "vi".

+
Dict k1 -> v1 ...
+

A dictionary mapping the string key ki to the value +vi, for i in 1 ... n +is encoded by the string +"dBKiBVi...e" +for i in 1 ... n, where "BKi" is the bee-encoding +of the key string "ki". and "BVi" is the bee-encoding of +the value "vi".

+

Note: The bee-encoding does not retain the order of the keys in +the input, but stores in a sorted order. The sorting is done for the +"raw strings".

+
+

Note that the type of each encoded item can be determined immediately +from the first character of its representation:

+
+
i
+

Integer.

+
l
+

List.

+
d
+

Dictionary.

+
[0-9]
+

String.

+
+

By wrapping an integer number into i...e the format +makes sure that they are different from strings, which all begin with +a digit.

+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bee of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench.html Index: embedded/www/tcllib/files/modules/bench/bench.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench.html +++ embedded/www/tcllib/files/modules/bench/bench.html @@ -0,0 +1,329 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench(n) 0.4 tcllib "Benchmarking/Performance tools"

+

Name

+

bench - bench - Processing benchmark suites

+
+ + +

Description

+

This package provides commands for the execution of benchmarks written +in the bench language, and for the processing of results generated by +such execution.

+

A reader interested in the bench language itself should start with the +bench language introduction and proceed from there to the +formal bench language specification.

+
+

PUBLIC API

+

Benchmark execution

+
+
::bench::locate pattern paths
+

This command locates Tcl interpreters and returns a list containing +their paths. It searches them in the list of paths specified by +the caller, using the glob pattern.

+

The command resolves soft links to find the actual executables +matching the pattern. Note that only interpreters which are marked as +executable and are actually executable on the current platform are put +into the result.

+
::bench::run ?option value...? interp_list file...
+

This command executes the benchmarks declared in the set of files, +once per Tcl interpreter specified via the interp_list, and per +the configuration specified by the options, and then returns the +accumulated timing results. The format of this result is described in +section Result format.

+

It is assumed that the contents of the files are written in the bench +language.

+

The available options are

+
+
-errors flag
+

The argument is a boolean value. If set errors in benchmarks are +propagated to the command, aborting benchmark execution. Otherwise +they are recorded in the timing result via a special result code. The +default is to propagate and abort.

+
-threads n
+

The argument is a non-negative integer value declaring the number of +threads to use while executing the benchmarks. The default value is +0, to not use threads.

+
-match pattern
+

The argument is a glob pattern. Only benchmarks whose description +matches the pattern are executed. The default is the empty string, to +execute all patterns.

+
-rmatch pattern
+

The argument is a regular expression pattern. Only benchmarks whose +description matches the pattern are executed. The default is the empty +string, to execute all patterns.

+
-iters n
+

The argument is positive integer number, the maximal number of +iterations for any benchmark. The default is 1000. Individual +benchmarks can override this.

+
-pkgdir path
+

The argument is a path to an existing, readable directory. Multiple +paths can be specified, simply use the option multiple times, each +time with one of the paths to use.

+

If no paths were specified the system will behave as before. +If one or more paths are specified, say N, each of the specified +interpreters will be invoked N times, with one of the specified +paths. The chosen path is put into the interpreters' auto_path, +thus allowing it to find specific versions of a package.

+

In this way the use of -pkgdir allows the user to benchmark +several different versions of a package, against one or more interpreters.

+

Note: The empty string is allowed as a path and causes the system to +run the specified interpreters with an unmodified auto_path. In case +the package in question is available there as well.

+
+
::bench::versions interp_list
+

This command takes a list of Tcl interpreters, identified by their +path, and returns a dictionary mapping from the interpreters to their +versions. Interpreters which are not actually executable, or fail when +interrogated, are not put into the result. I.e the result may contain +less interpreters than there in the input list.

+

The command uses builtin command info patchlevel to determine +the version of each interpreter.

+
+
+

Result manipulation

+
+
::bench::del bench_result column
+

This command removes a column, i.e. all benchmark results for a +specific Tcl interpreter, from the specified benchmark result and +returns the modified result.

+

The benchmark results are in the format described in section +Result format.

+

The column is identified by an integer number.

+
::bench::edit bench_result column newvalue
+

This command renames a column in the specified benchmark result and +returns the modified result. This means that the path of the Tcl +interpreter in the identified column is changed to an arbitrary +string.

+

The benchmark results are in the format described in section +Result format.

+

The column is identified by an integer number.

+
::bench::merge bench_result...
+

This commands takes one or more benchmark results, merges them into +one big result, and returns that as its result.

+

All benchmark results are in the format described in section +Result format.

+
::bench::norm bench_result column
+

This command normalizes the timing results in the specified benchmark +result and returns the modified result. This means that the cell +values are not times anymore, but factors showing how much faster or +slower the execution was relative to the baseline.

+

The baseline against which the command normalizes are the timing +results in the chosen column. This means that after the normalization +the values in this column are all 1, as these benchmarks are +neither faster nor slower than the baseline.

+

A factor less than 1 indicates a benchmark which was faster +than the baseline, whereas a factor greater than 1 indicates a +slower execution.

+

The benchmark results are in the format described in section +Result format.

+

The column is identified by an integer number.

+
::bench::out::raw bench_result
+

This command formats the specified benchmark result for output to a +file, socket, etc. This specific command does no formatting at all, +it passes the input through unchanged.

+

For other formatting styles see the packages bench::out::text +and bench::out::csv which provide commands to format +benchmark results for human consumption, or as CSV data importable by +spread sheets, respectively.

+

Complementary, to read benchmark results from files, sockets etc. look +for the package bench::in and the commands provided by it.

+
+
+

Result format

+

After the execution of a set of benchmarks the raw result returned by +this package is a Tcl dictionary containing all the relevant +information. +The dictionary is a compact representation, i.e. serialization, of a +2-dimensional table which has Tcl interpreters as columns and +benchmarks as rows. The cells of the table contain the timing +results. +The Tcl interpreters / columns are identified by their paths. +The benchmarks / rows are identified by their description.

+

The possible keys are all valid Tcl lists of two or three elements and +have one of the following forms:

+
+
{interp *}
+

The set of keys matching this glob pattern capture the information +about all the Tcl interpreters used to run the benchmarks. The second +element of the key is the path to the interpreter.

+

The associated value is the version of the Tcl interpreter.

+
{desc *}
+

The set of keys matching this glob pattern capture the information +about all the benchmarks found in the executed benchmark suite. The +second element of the key is the description of the benchmark, which +has to be unique.

+

The associated value is irrelevant, and set to the empty string.

+
{usec * *}
+

The set of keys matching this glob pattern capture the performance +information, i.e. timing results. The second element of the key is the +description of the benchmark, the third element the path of the Tcl +interpreter which was used to run it.

+

The associated value is either one of several special result codes, or +the time it took to execute the benchmark, in microseconds. The +possible special result codes are

+
+
ERR
+

Benchmark could not be executed, failed with a Tcl error.

+
BAD_RES
+

The benchmark could be executed, however the result from its body did +not match the declared expectations.

+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

bench_intro, bench_lang_intro, bench_lang_spec, bench_read, bench_wcsv, bench_wtext

+
+ +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_intro.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_intro.html +++ embedded/www/tcllib/files/modules/bench/bench_intro.html @@ -0,0 +1,171 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench_intro(n) 1.0 tcllib "Benchmarking/Performance tools"

+

Name

+

bench_intro - bench introduction

+
+ +

Description

+

The bench (short for benchmark tools), is a set of +related, yet different, entities which are working together for the +easy creation and execution of performance test suites, also known as +benchmarks. These are

+
    +

  1. A tcl based language for the declaration of test cases. A test case is +represented by a tcl command declaring the various parts needed to +execute it, like setup, cleanup, the commands to test, etc.

    2. +

  2. A package providing the ability to execute test cases written in that +language.

    3. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the benchmarking process.

+
    +

  1. A writer of benchmarks has to understand the bench language +itself. A beginner to bench should read the more informally written +bench language introduction first. Having digested this the +formal bench language specification should become +understandable. A writer experienced with bench may only need this +last document from time to time, to refresh her memory.

    2. +

  2. A user of benchmark suites written in the bench language +has to know which tools are available for use. +At the bottom level sits the package bench, providing the +basic facilities to read and execute files containing benchmarks +written in the bench language, and to manipulate benchmark results.

    3. +
+
+

HISTORICAL NOTES

+

This module and package have been derived from Jeff Hobbs' +tclbench application for the benchmarking of the Tcl core and +its ancestor "runbench.tcl".

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_lang_intro.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_lang_intro.html +++ embedded/www/tcllib/files/modules/bench/bench_lang_intro.html @@ -0,0 +1,247 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench_lang_intro(n) 1.0 tcllib "Benchmarking/Performance tools"

+

Name

+

bench_lang_intro - bench language introduction

+
+ +

Description

+

This document is an informal introduction to version 1 of the bench +language based on a multitude of examples. After reading this a +benchmark writer should be ready to understand the formal +bench language specification.

+

Fundamentals

+

In the broadest terms possible the bench language is +essentially Tcl, plus a number of commands to support the declaration +of benchmarks. +A document written in this language is a Tcl script and has the same +syntax.

+
+

Basics

+

One of the most simplest benchmarks which can be written in bench is

+
+bench -desc LABEL -body {
+    set a b
+}
+
+

This code declares a benchmark named LABEL which measures the +time it takes to assign a value to a variable. The Tcl code doing this +assignment is the -body of the benchmark.

+
+

Pre- and postprocessing

+

Our next example demonstrates how to declare initialization and +cleanup code, i.e. code computing information for the use of +the -body, and for releasing such resources after the +measurement is done. +They are the -pre- and the -post-body, respectively.

+

In our example, directly drawn from the benchmark suite of Tcllib's +aes package, the concrete initialization code constructs the +key schedule used by the encryption command whose speed we measure, +and the cleanup code releases any resources bound to that schedule.

+
+bench -desc "AES-${len} ECB encryption core" -pre {
+    set key [aes::Init ecb $k $i]
+} -body {
+    aes::Encrypt $key $p
+} -post {
+    aes::Final $key
+}
+
+
+

Advanced pre- and postprocessing

+

Our last example again deals with initialization and cleanup code. To +see the difference to the regular initialization and cleanup discussed +in the last section it is necessary to know a bit more about how bench +actually measures the speed of the the -body.

+

Instead of running the -body just once the system actually +executes the -body several hundred times and then returns the +average of the found execution times. This is done to remove +environmental effects like machine load from the result as much as +possible, with outliers canceling each other out in the average.

+

The drawback of doing things this way is that when we measure +operations which are not idempotent we will most likely not measure +the time for the operation we want, but of the state(s) the system is +in after the first iteration, a mixture of things we have no interest +in.

+

Should we wish, for example, to measure the time it takes to include +an element into a set, with the element not yet in the set, and the +set having specific properties like being a shared Tcl_Obj, then the +first iteration will measure the time for this. However all +subsequent iterations will measure the time to include an element +which is already in the set, and the Tcl_Obj holding the set will not +be shared anymore either. In the end the timings taken for the several +hundred iterations of this state will overwhelm the time taken from +the first iteration, the only one which actually measured what we +wanted.

+

The advanced initialization and cleanup codes, -ipre- and the +-ipost-body respectively, are present to solve this very +problem. While the regular initialization and cleanup codes are +executed before and after the whole series of iterations the advanced +codes are executed before and after each iteration of the body, +without being measured themselves. This allows them to bring the +system into the exact state the body wishes to measure.

+

Our example, directly drawn from the benchmark suite of Tcllib's +struct::set package, is for exactly the example we used +above to demonstrate the necessity for the advanced initialization and +cleanup. Its concrete initialization code constructs a variable +refering to a set with specific properties (The set has a string +representation, which is shared) affecting the speed of the inclusion +command, and the cleanup code releases the temporary variables created +by this initialization.

+
+bench -desc "set include, missing <SC> x$times $n" -ipre {
+    set A $sx($times,$n)
+    set B $A
+} -body {
+    struct::set include A x
+} -ipost {
+    unset A B
+}
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of benchmarks, he should be fortified enough to be able +to understand the formal bench language specfication. It will +also serve as the detailed specification and cheat sheet for all +available commands and their syntax.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_lang_spec.html Index: embedded/www/tcllib/files/modules/bench/bench_lang_spec.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_lang_spec.html +++ embedded/www/tcllib/files/modules/bench/bench_lang_spec.html @@ -0,0 +1,227 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench_lang_spec(n) 1.0 tcllib "Documentation tools"

+

Name

+

bench_lang_spec - bench language specification

+
+ + +

Description

+

This document specifies both names and syntax of all the commands +which together are the bench language, version 1. +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. +A beginner should read the more informally written +bench language introduction first.

+
+

Commands

+
+
bench_rm path...
+

This command silently removes the files specified as its arguments and +then returns the empty string as its result. +The command is trusted, there is no checking if the specified +files are outside of whatever restricted area the benchmarks are run +in.

+
bench_tmpfile
+

This command returns the path to a bench specific unique temporary +file. The uniqueness means that multiple calls will return different +paths. While the path may exist from previous runs, the command itself +does not create aynthing.

+

The base location of the temporary files is platform dependent:

+
+
Unix, and indeterminate platform
+

"/tmp"

+
Windows
+

$TEMP

+
Anything else
+

The current working directory.

+
+
bench options...
+

This command declares a single benchmark. Its result is the empty +string. All parts of the benchmark are declared via options, and their +values. The options can occur in any order. The accepted options are:

+
+
-body script
+

The argument of this option declares the body of the benchmark, the +Tcl script whose performance we wish to measure. This option, and +-desc, are the two required parts of each benchmark.

+
-desc msg
+

The argument of this option declares the name of the benchmark. It has +to be unique, or timing data from different benchmarks will be mixed +together.

+

Beware! This requirement is not checked when benchmarks are +executed, and the system will silently produce bogus data. This +option, and -body, are the two required parts of each +benchmark.

+
-ipost script
+

The argument of this option declares a script which is run immediately +after each iteration of the body. Its responsibility is to +release resources created by the body, or -ipre-bodym which +we do not wish to live into the next iteration.

+
-ipre script
+

The argument of this option declares a script which is run immediately +before each iteration of the body. Its responsibility is to +create the state of the system expected by the body so that we measure +the right thing.

+
-iterations num
+

The argument of this option declares the maximum number of times to +run the -body of the benchmark. During execution this and the +global maximum number of iterations are compared and the smaller of +the two values is used.

+

This option should be used only for benchmarks which are expected or +known to take a long time per run. I.e. reduce the number of times +they are run to keep the overall time for the execution of the whole +benchmark within manageable limits.

+
-post script
+

The argument of this option declares a script which is run +after all iterations of the body have been run. Its +responsibility is to release resources created by the body, +or -pre-body.

+
-pre script
+

The argument of this option declares a script which is run +before any of the iterations of the body are run. Its +responsibility is to create whatever resources are needed by the body +to run without failing.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_read.html Index: embedded/www/tcllib/files/modules/bench/bench_read.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_read.html +++ embedded/www/tcllib/files/modules/bench/bench_read.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench::in(n) 0.1 tcllib "Benchmarking/Performance tools"

+

Name

+

bench::in - bench::in - Reading benchmark results

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require csv
    • +
  • package require bench::in ?0.1?
    • +
+ +
+
+

Description

+

This package provides a command for reading benchmark results from +files, sockets, etc.

+

A reader interested in the creation, processing or writing of such +results should go and read +bench - Processing benchmark suites instead.

+

If the bench language itself is the actual interest please start with +the bench language introduction and then proceed from there +to the formal bench language specification.

+
+

PUBLIC API

+
+
::bench::in::read file
+

This command reads a benchmark result from the specified file +and returns it as its result. The command understands the three +formats created by the commands

+
+
bench::out::raw
+

Provided by package bench.

+
bench::out::csv
+

Provided by package bench::out::csv.

+
bench::out::text
+

Provided by package bench::out::text.

+
+

and automatically detects which format is used by the input file.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_wcsv.html Index: embedded/www/tcllib/files/modules/bench/bench_wcsv.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_wcsv.html +++ embedded/www/tcllib/files/modules/bench/bench_wcsv.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench::out::csv(n) 0.1.2 tcllib "Benchmarking/Performance tools"

+

Name

+

bench::out::csv - bench::out::csv - Formatting benchmark results as CSV

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require bench::out::csv ?0.1.2?
    • +
+ +
+
+

Description

+

This package provides commands for fomatting of benchmark results into +a CSV table importable by spread sheets.

+

A reader interested in the generation or processing of such results should +go and read bench - Processing benchmark suites instead.

+

If the bench language itself is the actual interest please start with +the bench language introduction and then proceed from there +to the formal bench language specification.

+
+

PUBLIC API

+
+
::bench::out::csv bench_result
+

This command formats the specified benchmark result for output to a +file, socket, etc. This specific command generates CSV data importable +by spread sheets.

+

For other formatting styles see the packages bench and +bench::out::text which provide commands to format benchmark +results in raw form, or for human consumption, respectively.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bench/bench_wtext.html Index: embedded/www/tcllib/files/modules/bench/bench_wtext.html ================================================================== --- embedded/www/tcllib/files/modules/bench/bench_wtext.html +++ embedded/www/tcllib/files/modules/bench/bench_wtext.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bench::out::text(n) 0.1.2 tcllib "Benchmarking/Performance tools"

+

Name

+

bench::out::text - bench::out::text - Formatting benchmark results as human readable text

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require bench::out::text ?0.1.2?
    • +
+ +
+
+

Description

+

This package provides commands for fomatting of benchmark results into +human readable text.

+

A reader interested in the generation or processing of such results should +go and read bench - Processing benchmark suites instead.

+

If the bench language itself is the actual interest please start with +the bench language introduction and then proceed from there +to the formal bench language specification.

+
+

PUBLIC API

+
+
::bench::out::text bench_result
+

This command formats the specified benchmark result for output to a +file, socket, etc. This specific command generates human readable +text.

+

For other formatting styles see the packages bench and +bench::out::csv which provide commands to format benchmark +results in raw form, or as importable CSV data, respectively.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bench of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Benchmark tools

+
+ +
ADDED embedded/www/tcllib/files/modules/bibtex/bibtex.html Index: embedded/www/tcllib/files/modules/bibtex/bibtex.html ================================================================== --- embedded/www/tcllib/files/modules/bibtex/bibtex.html +++ embedded/www/tcllib/files/modules/bibtex/bibtex.html @@ -0,0 +1,253 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

bibtex(n) 0.6 tcllib "bibtex"

+

Name

+

bibtex - Parse bibtex files

+
+ + +

Description

+

This package provides commands for the parsing of bibliographies in +BibTeX format.

+
+
::bibtex::parse ?options? ?text?
+

This is the general form of the command for parsing a +bibliography. Depending on the options used to invoke it it will +either return a token for the parser, or the parsed entries of the +input bibliography. Instead of performing an immediate parse returning +a predefined format the command can also enter an event-based parsing +style where all relevant entries in the input are reported through +callback commands, in the style of SAX.

+
::bibtex::parse text
+

In this form the command will assume that the specified text is +a bibliography in BibTeX format, parse it, and then return a list +containing one element per record found in the bibliography. Note that +comments, string definitions, preambles, etc. will not show up in the +result. Each element will be a list containing record type, +bibliography key and record data, in this order. The record data will +be a dictionary, its keys the keys of the record, with the associated +values.

+
::bibtex::parse ?-command cmd? -channel chan
+

In this form the command will reads the bibliography from the +specified Tcl channel chan and then returns the same data +structure as described above.

+

If however the option -command is specified the result will be a +handle for the parser instead and all processing will be incremental +and happen in the background. When the input has been exhausted the +callback cmd will be invoked with the result of the parse. The +exact definition for the callback is

+
+
cmd token parseresult
+

The parse result will have the structure explained above, for the +simpler forms of the parser.

+
+

Note that the parser will not close the channel after it +has exhausted it. This is still the responsibility of the user of the +parser.

+
::bibtex::parse ?-recordcommand recordcmd? ?-preamblecommand preamblecmd? ?-stringcommand stringcmd? ?-commentcommand commentcmd? ?-progresscommand progresscmd? ?-casesensitivestrings bool? (text | -channel chan)
+

This is the most low-level form for the parser. The returned result +will be a handle for the parser. During processing it will invoke the +invoke the specified callback commands for each type of data found in +the bibliography.

+

The processing will be incremental and happen in the background if, +and only if a Tcl channel chan is specified. For a text +the processing will happen immediately and all callbacks will be +invoked before the command itself returns.

+

The callbacks, i.e. *cmd, are all command prefixes and will be +invoked with additional arguments appended to them. The meaning of the +arguments depends on the callback and is explained below. The first +argument will however always be the handle of the parser invoking the +callback.

+
+
-casesensitivestrings
+

This option takes a boolean value. When set string macro processing +becomes case-sensitive. The default is case-insensitive string macro +processing.

+
recordcmd token type key recorddict
+

This callback is invoked whenever the parser detects a bibliography +record in the input. Its arguments are the record type, the +bibliography key for the record, and a dictionary containing the keys +and values describing the record. Any string macros known to the +parser have already been expanded.

+
preamblecmd token preambletext
+

This callback is invoked whenever the parser detects an @preamble +block in the input. The only additional argument is the text found in +the preamble block. By default such entries are ignored.

+
stringcmd token stringdict
+

This callback is invoked whenever the parser detects an @string-based +macro definition in the input. The argument is a dictionary with the +macro names as keys and their replacement strings as values. By +default such definitions are added to the parser state for use in +future bibliography records.

+
commentcmd token commenttext
+

This callback is invoked whenever the parser detects a comment in the +input. The only additional argument is the comment text. By default +such entries are ignored.

+
progresscmd token percent
+

This callback is invoked during processing to tell the user about the +progress which has been made. Its argument is the percentage of data +processed, as integer number between 0 and 100. +In the case of incremental processing the perecentage will always be +-1 as the total number of entries is not known beforehand.

+
+
::bibtex::wait token
+

This command waits for the parser represented by the token to +complete and then returns. The returned result is the empty string.

+
::bibtex::destroy token
+

This command cleans up all internal state associated with the parser +represented by the handle token, effectively destroying it. This +command can be called from within the parser callbacks to terminate +processing.

+
::bibtex::addStrings token stringdict
+

This command adds the macro definitions stored in the +dictionary stringdict to the parser represented +by the handle token.

+

The dictionary keys are the macro names and the values their +replacement strings. This command has the correct signature for use as +a -stringcommand callback in an invokation of the command +::bibtex::parse.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category bibtex of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/blowfish/blowfish.html Index: embedded/www/tcllib/files/modules/blowfish/blowfish.html ================================================================== --- embedded/www/tcllib/files/modules/blowfish/blowfish.html +++ embedded/www/tcllib/files/modules/blowfish/blowfish.html @@ -0,0 +1,258 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

blowfish(n) 1.0.3 tcllib "Blowfish Block Cipher"

+

Name

+

blowfish - Implementation of the Blowfish block cipher

+
+ + +

Description

+

This package is an implementation in Tcl of the Blowfish algorithm +developed by Bruce Schneier [1]. Blowfish is a 64-bit block cipher +designed to operate quickly on 32 bit architectures and accepting a +variable key length. This implementation supports ECB and CBC mode +blowfish encryption.

+
+

COMMANDS

+
+
::blowfish::blowfish ?-mode [ecb|cbc]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-out channel? ?-chunksize size? ?-pad padchar? [ -in channel | ?--? data ]
+

Perform the blowfish algorithm on either the data provided +by the argument or on the data read from the -in channel. If +an -out channel is given then the result will be written to +this channel.

+

The -key option must be given. This parameter takes a binary +string of variable length and is used to generate the blowfish +key schedule. You should be aware that creating a key +schedule is quite an expensive operation in blowfish so it is worth +reusing the key where possible. See Reset.

+

The -mode and -dir options are optional and default to cbc +mode and encrypt respectively. The initialization vector -iv +takes an 8 byte binary argument which defaults to 8 zeros. +See MODES OF OPERATION for more about available modes and +their uses.

+

Blowfish is a 64-bit block cipher. This means that the data must be +provided in units that are a multiple of 8 bytes. The blowfish +command will by default add nul characters to pad the input data to a +multiple of 8 bytes if necessary. The programming api commands will +never add padding and instead will raise an error if the input is not +a multiple of the block size. The -pad option can be used to +change the padding character or to disable padding if the empty string +is provided as the argument.

+
+
+

PROGRAMMING INTERFACE

+
+
::blowfish::Init mode keydata iv
+

Construct a new blowfish key schedule using the specified key data and +the given initialization vector. The initialization vector is not used +with ECB mode but is important for CBC mode. +See MODES OF OPERATION for details about cipher modes.

+
::blowfish::Encrypt Key data
+

Use a prepared key acquired by calling Init to encrypt the +provided data. The data argument should be a binary array that is a +multiple of the block size of 8 bytes. The result is a binary +array the same size as the input of encrypted data.

+
::blowfish::Decrypt Key data
+

Decipher data using the key. Note that the same key may be used to +encrypt and decrypt data provided that the initialization vector is +reset appropriately for CBC mode.

+
::blowfish::Reset Key iv
+

Reset the initialization vector. This permits the programmer to re-use +a key and avoid the cost of re-generating the key schedule where the +same key data is being used multiple times.

+
::blowfish::Final Key
+

This should be called to clean up resources associated with Key. +Once this function has been called the key may not be used again.

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

ECB is the basic mode of all block ciphers. Each block is encrypted +independently and so identical plain text will produce identical +output when encrypted with the same key. Any encryption errors will +only affect a single block however this is vulnerable to known +plaintext attacks.

+
Cipher Block Chaining (CBC)
+

CBC mode uses the output of the last block encryption to affect the +current block. An initialization vector of the same size as the cipher +block size is used to handle the first block. The initialization +vector should be chosen randomly and transmitted as the first block of +the output. Errors in encryption affect the current block and the next +block after which the cipher will correct itself. CBC is the most +commonly used mode in software encryption.

+
+
+

EXAMPLES

+
+% blowfish::blowfish -hex -mode ecb -dir encrypt -key secret01 "hello, world!"
+d0d8f27e7a374b9e2dbd9938dd04195a
+
+
+ set Key [blowfish::Init cbc $eight_bytes_key_data $eight_byte_iv]
+ append ciphertext [blowfish::Encrypt $Key $plaintext]
+ append ciphertext [blowfish::Encrypt $Key $additional_plaintext]
+ blowfish::Final $Key
+
+
+

REFERENCES

+
    +

  1. Schneier, B. "Applied Cryptography, 2nd edition", 1996, + ISBN 0-471-11709-9, pub. John Wiley & Sons.

    2. +
+
+

AUTHORS

+

Frank Pilhofer, Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category blowfish of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

3des, des, rc4

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/cache/async.html Index: embedded/www/tcllib/files/modules/cache/async.html ================================================================== --- embedded/www/tcllib/files/modules/cache/async.html +++ embedded/www/tcllib/files/modules/cache/async.html @@ -0,0 +1,232 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

cache::async(n) 0.3 tcllib "In-memory caches"

+

Name

+

cache::async - Asynchronous in-memory cache

+
+ + +

Description

+

This package provides objects which cache data in memory, and operate +asynchronously with regard to request and responses. The objects are +agnostic with regard to cache keys and values, and unknown methods are +delegated to the provider of cached data. These two properties make it +easy to use caches as a facade for any data provider.

+
+

API

+

The package exports a class, cache::async, as specified +below.

+
+
::cache::async objectName commandprefix ?options...?
+

The command creates a new cache object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object.

+

The commandprefix is the action to perform when an user asks for +data in the cache and the cache doesn't yet know about the key. When +run the commandprefix is given three additional arguments, the string +get, the key requested, and the cache object itself, in the +form of its object command, in this order. The execution of the action +is done in an idle-handler, decoupling it from the original request.

+

The only supported option is

+
+
-full-async-results
+

This option defines the behaviour of the cache for when requested keys +are known to the cache at the time of get request. By default +such requeste are responded to asynchronously as well. Setting this +option to false forces the cache to respond to them +synchronuously, although still through the specified callback.

+
+
+

The object commands created by the class commands above have +the form:

+
+
objectName get key donecmdprefix
+

This method requests the data for the key from the cache. If the +data is not yet known the command prefix specified during construction +of the cache object is used to ask for this information.

+

Whenever the information is/becomes available the donecmdprefix +will be run to transfer the result to the caller. This command prefix +is invoked with either 2 or 3 arguments, i.e.

+
    +

  1. The string set, the key, and the value.

    2. +

  2. The string unset, and the key.

    3. +
+

These two possibilities are used to either signal the value for the +key, or that the key has no value defined for it. The +latter is distinct from the cache not knowing about the key.

+

For a cache object configured to be fully asynchronous (default) the +donecmdprefix is always run in an idle-handler, decoupling it +from the request. Otherwise the callback will be invoked synchronously +when the key is known to the cache at the time of the +invokation.

+

Another important part of the cache's behaviour, as it is asynchronous +it is possible that multiple get requests are issued for the +same key before it can respond. In that case the cache will +issue only one data request to the provider, for the first of these, +and suspend the others, and then notify all of them when the data +becomes available.

+
objectName set key value
+
+
objectName unset key
+

These two methods are provided to allow users of the cache to make +keys known to the cache, as either having a value, or as +undefined.

+

It is expected that the data provider (see commandprefix of the +constructor) uses them in response to data requests for unknown keys.

+

Note how this matches the cache's own API towards its caller, calling +the donecmd of get-requests issued to itself with +either "set key value" or "unset key", versus issuing +get-requests to its own provider with itself in the place of +the donecmd, expecting to be called with either "set key value" +or "unset key".

+

This also means that these methods invoke the donecmd of all +get-requests waiting for information about the modified +key.

+
objectName exists key
+

This method queries the cache for knowledge about the key and +returns a boolean value. The result is true if the key is +known, and false otherwise.

+
objectName clear ?key?
+

This method resets the state of either the specified key or of +all keys known to the cache, making it unkown. This forces future +get-requests to reload the information from the provider.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category cache of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/clock/iso8601.html Index: embedded/www/tcllib/files/modules/clock/iso8601.html ================================================================== --- embedded/www/tcllib/files/modules/clock/iso8601.html +++ embedded/www/tcllib/files/modules/clock/iso8601.html @@ -0,0 +1,162 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

clock_iso8601(n) 0.1 tcllib "Date/Time Utilities"

+

Name

+

clock_iso8601 - Parsing ISO 8601 dates/times

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require clock::iso8601 ?0.1?
    • +
+ +
+
+

Description

+

This package provides functionality to parse dates and times in +ISO 8601 format.

+
+
::clock::iso8601 parse_date date options...
+

This command parses an ISO8601 date string in an unknown variant and +returns the given date/time in seconds since epoch.

+

The acceptable options are +-base, +-gmt, +-locale, and +-timezone +of the builtin command clock scan.

+
::clock::iso8601 parse_time time options...
+

This command parses a full ISO8601 timestamp string (date and time) in +an unknown variant and returns the given time in seconds since epoch.

+

The acceptable options are +-base, +-gmt, +-locale, and +-timezone +of the builtin command clock scan.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category clock::iso8601 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/clock/rfc2822.html Index: embedded/www/tcllib/files/modules/clock/rfc2822.html ================================================================== --- embedded/www/tcllib/files/modules/clock/rfc2822.html +++ embedded/www/tcllib/files/modules/clock/rfc2822.html @@ -0,0 +1,147 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

clock_rfc2822(n) 0.1 tcllib "Date/Time Utilities"

+

Name

+

clock_rfc2822 - Parsing ISO 8601 dates/times

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require clock::rfc2822 ?0.1?
    • +
+ +
+
+

Description

+

This package provides functionality to parse dates in +RFC 2822 format.

+
+
::clock::rfc2822 parse_date date
+

This command parses an RFC2822 date string and returns +the given date in seconds since epoch. An error is thrown +if the command is unable to parse the date.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category clock::rfc2822 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/cmdline/cmdline.html Index: embedded/www/tcllib/files/modules/cmdline/cmdline.html ================================================================== --- embedded/www/tcllib/files/modules/cmdline/cmdline.html +++ embedded/www/tcllib/files/modules/cmdline/cmdline.html @@ -0,0 +1,285 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

cmdline(n) 1.5 tcllib "Command line and option processing"

+

Name

+

cmdline - Procedures to process command lines and options.

+
+ + +

Description

+

This package provides commands to parse command lines and options.

+
+

::argv handling

+

One of the most common variables this package will be used with is +::argv, which holds the command line of the current +application. This variable has a companion ::argc which is +initialized to the number of elements in ::argv at the beginning +of the application.

+

The commands in this package will not modify the ::argc +companion when called with ::argv. Keeping the value consistent, +if such is desired or required, is the responsibility of the caller.

+
+

API

+
+
::cmdline::getopt argvVar optstring optVar valVar
+

This command works in a fashion like the standard C based getopt +function. Given an option string and a pointer to an array of args +this command will process the first argument and return info on how to +proceed. The command returns 1 if an option was found, 0 if no more +options were found, and -1 if an error occurred.

+

argvVar contains the name of the list of arguments to +process. If options are found the list is modified and the processed +arguments are removed from the start of the list.

+

optstring contains a list of command options that the +application will accept. If the option ends in ".arg" the command +will use the next argument as an argument to the option, or extract it +from the current argument, if it is of the form "option=value". +Otherwise the option is a boolean that is set to 1 if present.

+

optVar refers to the variable the command will store the found +option into (without the leading '-' and without the .arg extension).

+

valVar refers to the variable to store either the value for the +specified option into upon success or an error message in the case of +failure. The stored value comes from the command line for .arg +options, otherwise the value is 1.

+
::cmdline::getKnownOpt argvVar optstring optVar valVar
+

Like ::cmdline::getopt, but ignores any unknown options in the +input.

+
::cmdline::getoptions arglistVar optlist ?usage?
+

Processes the set of command line options found in the list variable +named by arglistVar and fills in defaults for those not +specified. This also generates an error message that lists the +allowed flags if an incorrect flag is specified. The optional +usage-argument contains a string to include in front of the +generated message. If not present it defaults to "options:".

+

optlist contains a list of lists where each element specifies an +option in the form: flag default comment.

+

If flag ends in ".arg" then the value is taken from the command +line. Otherwise it is a boolean and appears in the result if present +on the command line. If flag ends in ".secret", it will not be +displayed in the usage.

+

The options -?, -help, and -- are +implicitly understood. The first two abort option processing by +throwing an error and force the generation of the usage message, +whereas the the last aborts option processing without an error, +leaving all arguments coming after for regular processing, even if +starting with a dash.

+

The result of the command is a dictionary mapping all options to their +values, be they user-specified or defaults.

+
::cmdline::getKnownOptions arglistVar optlist ?usage?
+

Like ::cmdline::getoptions, but ignores any unknown options in the +input.

+
::cmdline::usage optlist ?usage?
+

Generates and returns an error message that lists the allowed +flags. optlist is defined as for +::cmdline::getoptions. The optional usage-argument +contains a string to include in front of the generated message. If not +present it defaults to "options:".

+
::cmdline::getfiles patterns quiet
+

Given a list of file patterns this command computes the set of +valid files. On windows, file globbing is performed on each argument. +On Unix, only file existence is tested. If a file argument produces +no valid files, a warning is optionally generated (set quiet to +true).

+

This code also uses the full path for each file. If not given it +prepends the current working directory to the filename. This ensures +that these files will never conflict with files in a wrapped zip +file. The last sentence refers to the pro-tools.

+
::cmdline::getArgv0
+

This command returns the "sanitized" version of argv0. It will +strip off the leading path and removes the extension ".bin". The +latter is used by the pro-apps because they must be wrapped by a shell +script.

+
+

Error Codes

+

Starting with version 1.5 all errors thrown by the package have a +proper ::errorCode for use with Tcl's try command. This +code always has the word CMDLINE as its first element.

+
+
+

EXAMPLES

+
+        package require Tcl 8.5
+        package require try         ;# Tcllib.
+        package require cmdline 1.5 ;# First version with proper error-codes.
+        # Notes:
+        # - Tcl 8.6+ has 'try' as a builtin command and therefore does not
+        #   need the 'try' package.
+        # - Before Tcl 8.5 we cannot support 'try' and have to use 'catch'.
+        #   This then requires a dedicated test (if) on the contents of
+        #   ::errorCode to separate the CMDLINE USAGE signal from actual errors.
+        set options {
+            {a          "set the atime only"}
+            {m          "set the mtime only"}
+            {c          "do not create non-existent files"}
+            {r.arg  ""  "use time from ref_file"}
+            {t.arg  -1  "use specified time"}
+        }
+        set usage ": MyCommandName \[options] filename ...\noptions:"
+        try {
+            array set params [::cmdline::getoptions argv $options $usage]
+        } trap {CMDLINE USAGE} {msg o} {
+            # Trap the usage signal, print the message, and exit the application.
+            # Note: Other errors are not caught and passed through to higher levels!
+	    puts $msg
+	    exit 1
+        }
+        if {  $params(a) } { set set_atime "true" }
+        set has_t [expr {$params(t) != -1}]
+        set has_r [expr {[string length $params(r)] > 0}]
+        if {$has_t && $has_r} {
+            return -code error "Cannot specify both -r and -t"
+        } elseif {$has_t} {
+	    ...
+        }
+
+

This example, taken (and slightly modified) from the package +fileutil, shows how to use cmdline. First, a list of +options is created, then the 'args' list is passed to cmdline for +processing. Subsequently, different options are checked to see if +they have been passed to the script, and what their value is.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category cmdline of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/comm/comm.html Index: embedded/www/tcllib/files/modules/comm/comm.html ================================================================== --- embedded/www/tcllib/files/modules/comm/comm.html +++ embedded/www/tcllib/files/modules/comm/comm.html @@ -0,0 +1,1032 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

comm(n) 4.6.3 tcllib "Remote communication"

+

Name

+

comm - A remote communication facility for Tcl (8.3 and later)

+
+ + +

Description

+

The comm command provides an inter-interpreter remote +execution facility much like Tk's send(n), except that it uses +sockets rather than the X server for the communication path. As a +result, comm works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path.

+

These commands work just like send and winfo interps :

+
+    ::comm::comm send ?-async? id cmd ?arg arg ...?
+    ::comm::comm interps
+
+

This is all that is really needed to know in order to use +comm

+

Commands

+

The package initializes ::comm::comm as the default chan.

+

comm names communication endpoints with an id unique +to each machine. Before sending commands, the id of another +interpreter is needed. Unlike Tk's send, comm doesn't +implicitly know the id's of all the interpreters on the system. +The following four methods make up the basic comm interface.

+
+
::comm::comm send ?-async? ?-command callback? id cmd ?arg arg ...?
+

This invokes the given command in the interpreter named by id. The +command waits for the result and remote errors are returned unless the +-async or -command option is given. If -async +is given, send returns immediately and there is no further notification of +result. If -command is used, callback specifies a command +to invoke when the result is received. These options are mutually +exclusive. The callback will receive arguments in the form +-option value, suitable for array set. +The options are: -id, the comm id of the interpreter that received +the command; -serial, a unique serial for each command sent to a +particular comm interpreter; -chan, the comm channel name; +-code, the result code of the command; -errorcode, the +errorcode, if any, of the command; -errorinfo, the errorinfo, if +any, of the command; and -result, the return value of the command. +If connection is lost before a reply is received, the callback will be +invoked with a connection lost message with -code equal to -1. When +-command is used, the command returns the unique serial for the +command.

+
::comm::comm self
+

Returns the id for this channel.

+
::comm::comm interps
+

Returns a list of all the remote id's to which this channel is +connected. comm learns a new remote id when a command +is first issued it, or when a remote id first issues a command +to this comm channel. ::comm::comm ids is an alias for this +method.

+
::comm::comm connect ?id?
+

Whereas ::comm::comm send will automatically connect to the +given id, this forces a connection to a remote id without +sending a command. After this, the remote id will appear in +::comm::comm interps.

+
+
+

Eval Semantics

+

The evaluation semantics of ::comm::comm send are intended to +match Tk's send exactly. This means that comm +evaluates arguments on the remote side.

+

If you find that ::comm::comm send doesn't work for a +particular command, try the same thing with Tk's send and see if the +result is different. If there is a problem, please report it. For +instance, there was had one report that this command produced an +error. Note that the equivalent send command also produces the +same error.

+
+    % ::comm::comm send id llength {a b c}
+    wrong # args: should be "llength list"
+    % send name llength {a b c}
+    wrong # args: should be "llength list"
+
+

The eval hook (described below) can be used to change from +send's double eval semantics to single eval semantics.

+
+

Multiple Channels

+

More than one comm channel (or listener) can be created +in each Tcl interpreter. This allows flexibility to create full and +restricted channels. For instance, hook scripts are specific +to the channel they are defined against.

+
+
::comm::comm new chan ?name value ...?
+

This creates a new channel and Tcl command with the given channel +name. This new command controls the new channel and takes all the +same arguments as ::comm::comm. Any remaining arguments are +passed to the config method. The fully qualified channel +name is returned.

+
::comm::comm channels
+

This lists all the channels allocated in this Tcl interpreter.

+
+

The default configuration parameters for a new channel are:

+
+    "-port 0 -local 1 -listen 0 -silent 0"
+
+

The default channel ::comm::comm is created with:

+
+    "::comm::comm new ::comm::comm -port 0 -local 1 -listen 1 -silent 0"
+
+
+

Channel Configuration

+

The config method acts similar to fconfigure in that it +sets or queries configuration variables associated with a channel.

+
+
::comm::comm config
+
+
::comm::comm config name
+
+
::comm::comm config ?name value ...?
+

When given no arguments, config returns a list of all variables +and their value With one argument, config returns the value of +just that argument. With an even number of arguments, the given +variables are set to the given values.

+
+

These configuration variables can be changed (descriptions of them are +elsewhere in this manual page):

+
+
-listen ?0|1?
+
+
-local ?0|1?
+
+
-port ?port?
+
+
-silent ?0|1?
+
+
-socketcmd ?commandname?
+
+
-interp ?interpreter?
+
+
-events ?eventlist?
+
+
+

These configuration variables are read only:

+
+
-chan chan
+
+
-serial n
+
+
-socket sockIn
+
+
+

When config changes the parameters of an existing channel (with +the exception of -interp and -events), it closes and +reopens the listening socket. +An automatically assigned channel id will change when this +happens. +Recycling the socket is done by invoking ::comm::comm abort, +which causes all active sends to terminate.

+
+

Id/port Assignments

+

comm uses a TCP port for endpoint id. The +interps (or ids) method merely lists all the TCP ports +to which the channel is connected. By default, each channel's +id is randomly assigned by the operating system (but usually +starts at a low value around 1024 and increases each time a new socket +is opened). This behavior is accomplished by giving the +-port config option a value of 0. Alternately, a specific +TCP port number may be provided for a given channel. As a special +case, comm contains code to allocate a a high-numbered TCP port +(>10000) by using -port {}. Note that a channel won't be +created and initialized unless the specific port can be allocated.

+

As a special case, if the channel is configured with +-listen 0, then it will not create a listening socket and +will use an id of 0 for itself. Such a channel is only good +for outgoing connections (although once a connection is established, +it can carry send traffic in both directions). +As another special case, if the channel is configured with +-silent 0, then the listening side will ignore connection +attempts where the protocol negotiation phase failed, instead of +throwing an error.

+
+

Execution Environment

+

A communication channel in its default configuration will use the +current interpreter for the execution of all received scripts, and of +the event scripts associated with the various hooks.

+

This insecure setup can be changed by the user via the two options +-interp, and -events.

+

When -interp is set all received scripts are executed in the +slave interpreter specified as the value of the option. This +interpreter is expected to exist before configuration. I.e. it is the +responsibility of the user to create it. However afterward the +communication channel takes ownership of this interpreter, and will +destroy it when the communication channel is destroyed. +Note that reconfiguration of the communication channel to either a +different interpreter or the empty string will release the ownership +without destroying the previously configured interpreter. The +empty string has a special meaning, it restores the default behaviour +of executing received scripts in the current interpreter.

+

Also of note is that replies and callbacks (a special form of +reply) are not considered as received scripts. They are +trusted, part of the internal machinery of comm, and therefore always +executed in the current interpreter.

+

Even if an interpreter has been configured as the execution +environment for received scripts the event scripts associated with the +various hooks will by default still be executed in the current +interpreter. To change this use the option -events to declare +a list of the events whose scripts should be executed in the declared +interpreter as well. The contents of this option are ignored if the +communication channel is configured to execute received scripts in the +current interpreter.

+
+

Remote Interpreters

+

By default, each channel is restricted to accepting connections from +the local system. This can be overridden by using the +-local 0 configuration option For such channels, the +id parameter takes the form { id host }.

+

WARNING: The host must always be specified in the same +form (e.g., as either a fully qualified domain name, plain hostname or +an IP address).

+
+

Closing Connections

+

These methods give control over closing connections:

+
+
::comm::comm shutdown id
+

This closes the connection to id, aborting all outstanding +commands in progress. Note that nothing prevents the connection from +being immediately reopened by another incoming or outgoing command.

+
::comm::comm abort
+

This invokes shutdown on all open connections in this comm channel.

+
::comm::comm destroy
+

This aborts all connections and then destroys the this comm channel +itself, including closing the listening socket. Special code allows +the default ::comm::comm channel to be closed such that the +::comm::comm command it is not destroyed. Doing so closes the +listening socket, preventing both incoming and outgoing commands on +the channel. This sequence reinitializes the default channel:

+
+    "::comm::comm destroy; ::comm::comm new ::comm::comm"
+
+
+
+

When a remote connection is lost (because the remote exited or called +shutdown), comm can invoke an application callback. +This can be used to cleanup or restart an ancillary process, for +instance. See the lost callback below.

+
+

Callbacks

+

This is a mechanism for setting hooks for particular events:

+
+
::comm::comm hook event ?+? ?script?
+

This uses a syntax similar to Tk's bind command. Prefixing +script with a + causes the new script to be appended. +Without this, a new script replaces any existing script. When +invoked without a script, no change is made. In all cases, the new +hook script is returned by the command.

+

When an event occurs, the script associated with it is +evaluated with the listed variables in scope and available. The +return code (not the return value) of the script is commonly +used decide how to further process after the hook.

+

Common variables include:

+
+
chan
+

the name of the comm channel (and command)

+
id
+

the id of the remote in question

+
fid
+

the file id for the socket of the connection

+
+
+

These are the defined events:

+
+
connecting
+

Variables: +chan, id

+

This hook is invoked before making a connection to the remote named in +id. An error return (via error) will abort the connection +attempt with the error. Example:

+
+    % ::comm::comm hook connecting {
+        if {[string match {*[02468]} $id]} {
+            error "Can't connect to even ids"
+        }
+    }
+    % ::comm::comm send 10000 puts ok
+    Connect to remote failed: Can't connect to even ids
+    %
+
+
+
connected
+

Variables: +chan, fid, id, host, and port.

+

This hook is invoked immediately after making a remote connection to +id, allowing arbitrary authentication over the socket named by +fid. An error return (via error ) will close the +connection with the error. host and port are merely +extracted from the id; changing any of these will have no effect +on the connection, however. It is also possible to substitute and +replace fid.

+
incoming
+

Variables: +chan, fid, addr, and remport.

+

Hook invoked when receiving an incoming connection, allowing arbitrary +authentication over socket named by fid. An error return (via +error) will close the connection with the error. Note that the +peer is named by remport and addr but that the remote +id is still unknown. Example:

+
+    ::comm::comm hook incoming {
+        if {[string match 127.0.0.1 $addr]} {
+            error "I don't talk to myself"
+        }
+    }
+
+
+
eval
+

Variables: +chan, id, cmd, and buffer.

+

This hook is invoked after collecting a complete script from a remote +but before evaluating it. This allows complete control over +the processing of incoming commands. cmd contains either +send or async. buffer holds the script to +evaluate. At the time the hook is called, $chan remoteid is +identical in value to id.

+

By changing buffer, the hook can change the script to be +evaluated. The hook can short circuit evaluation and cause a value to +be immediately returned by using return result (or, from +within a procedure, return -code return result). An +error return (via error) will return an error result, as is if +the script caused the error. Any other return will evaluate the +script in buffer as normal. For compatibility with 3.2, +break and return -code break result is supported, +acting similarly to return {} and return -code return +result.

+

Examples:

+
    +

  1. augmenting a command

    +
    +    % ::comm::comm send [::comm::comm self] pid
+    5013
+    % ::comm::comm hook eval {puts "going to execute $buffer"}
+    % ::comm::comm send [::comm::comm self] pid
+    going to execute pid
+    5013
+
    +
    2. +

  2. short circuiting a command

    +
    +    % ::comm::comm hook eval {puts "would have executed $buffer"; return 0}
+    % ::comm::comm send [::comm::comm self] pid
+    would have executed pid
+    0
+
    +
    3. +

  3. Replacing double eval semantics

    +
    +    % ::comm::comm send [::comm::comm self] llength {a b c}
+    wrong # args: should be "llength list"
+    % ::comm::comm hook eval {return [uplevel #0 $buffer]}
+    return [uplevel #0 $buffer]
+    % ::comm::comm send [::comm::comm self] llength {a b c}
+    3
+
    +
    4. +

  4. Using a slave interpreter

    +
    +    % interp create foo
+    % ::comm::comm hook eval {return [foo eval $buffer]}
+    % ::comm::comm send [::comm::comm self] set myvar 123
+    123
+    % set myvar
+    can't read "myvar": no such variable
+    % foo eval set myvar
+    123
+
    +
    5. +

  5. Using a slave interpreter (double eval)

    +
    +    % ::comm::comm hook eval {return [eval foo eval $buffer]}
+
    +
    6. +

  6. Subverting the script to execute

    +
    +    % ::comm::comm hook eval {
+        switch -- $buffer {
+            a {return A-OK}
+            b {return B-OK}
+            default {error "$buffer is a no-no"}
+        }
+    }
+    % ::comm::comm send [::comm::comm self] pid
+    pid is a no-no
+    % ::comm::comm send [::comm::comm self] a
+    A-OK
+
    +
    7. +
+
reply
+

Variables: +chan, id, buffer, ret, and return().

+

This hook is invoked after collecting a complete reply script from a +remote but before evaluating it. This allows complete +control over the processing of replies to sent commands. The reply +buffer is in one of the following forms

+
    +

  • return result

    • +

  • return -code code result

    • +

  • return -code code -errorinfo info -errorcode ecode msg

    • +
+

For safety reasons, this is decomposed. The return result is in +ret, and the return switches are in the return array:

+
    +

  • return(-code)

    • +

  • return(-errorinfo)

    • +

  • return(-errorcode)

    • +
+

Any of these may be the empty string. Modifying these four variables +can change the return value, whereas modifying buffer has no +effect.

+
callback
+

Variables: +chan, id, buffer, ret, and return().

+

Similar to reply, but used for callbacks.

+
lost
+

Variables: +chan, id, and reason.

+

This hook is invoked when the connection to id is lost. Return +value (or thrown error) is ignored. reason is an explanatory +string indicating why the connection was lost. Example:

+
+    ::comm::comm hook lost {
+        global myvar
+        if {$myvar(id) == $id} {
+            myfunc
+            return
+        }
+    }
+
+
+
+
+

Unsupported

+

These interfaces may change or go away in subsequence releases.

+
+
::comm::comm remoteid
+

Returns the id of the sender of the last remote command +executed on this channel. If used by a proc being invoked remotely, +it must be called before any events are processed. Otherwise, another +command may get invoked and change the value.

+
::comm::comm_send
+

Invoking this procedure will substitute the Tk send and +winfo interps commands with these equivalents that use +::comm::comm.

+
+    proc send {args} {
+        eval ::comm::comm send $args
+    }
+    rename winfo tk_winfo
+    proc winfo {cmd args} {
+        if {![string match in* $cmd]} {
+            return [eval [list tk_winfo $cmd] $args]
+        }
+        return [::comm::comm interps]
+    }
+
+
+
+
+

Security

+

Starting with version 4.6 of the package an option -socketcmd +is supported, allowing the user of a comm channel to specify which +command to use when opening a socket. Anything which is API-compatible +with the builtin ::socket (the default) can be used.

+

The envisioned main use is the specification of the tls::socket +command, see package tls, to secure the communication.

+
+	# Load and initialize tls
+	package require tls
+	tls::init  -cafile /path/to/ca/cert -keyfile ...
+	# Create secured comm channel
+	::comm::comm new SECURE -socketcmd tls::socket -listen 1
+	...
+
+

The sections Execution Environment and Callbacks +are also relevant to the security of the system, providing means to +restrict the execution to a specific environment, perform additional +authentication, and the like.

+
+

Blocking Semantics

+

There is one outstanding difference between comm and +send. When blocking in a synchronous remote command, send +uses an internal C hook (Tk_RestrictEvents) to the event loop to look +ahead for send-related events and only process those without +processing any other events. In contrast, comm uses the +vwait command as a semaphore to indicate the return message has +arrived. The difference is that a synchronous send will block +the application and prevent all events (including window related ones) +from being processed, while a synchronous ::comm::comm send +will block the application but still allow other events to get +processed. In particular, after idle handlers will fire +immediately when comm blocks.

+

What can be done about this? First, note that this behavior will come +from any code using vwait to block and wait for an event to +occur. At the cost of multiple channel support, comm could +be changed to do blocking I/O on the socket, giving send-like blocking +semantics. However, multiple channel support is a very useful feature +of comm that it is deemed too important to lose. The remaining +approaches involve a new loadable module written in C (which is +somewhat against the philosophy of comm) One way would be to +create a modified version of the vwait command that allow the +event flags passed to Tcl_DoOneEvent to be specified. For comm, +just the TCL_FILE_EVENTS would be processed. Another way would be to +implement a mechanism like Tk_RestrictEvents, but apply it to the Tcl +event loop (since comm doesn't require Tk). One of these +approaches will be available in a future comm release as an +optional component.

+
+

Asynchronous Result Generation

+

By default the result returned by a remotely invoked command is the +result sent back to the invoker. This means that the result is +generated synchronously, and the server handling the call is blocked +for the duration of the command.

+

While this is tolerable as long as only short-running commands are +invoked on the server long-running commands, like database queries +make this a problem. One command can prevent the processing requests +of all other clients for an arbitrary period of time.

+

Before version 4.5 of comm the only solution was to rewrite the server +command to use the Tcl builtin command vwait, or one of its +relatives like tkwait, to open a new event loop which processes +requests while the long-running operation is executed. This however +has its own perils, as this makes it possible to both overflow the Tcl +stack with a large number of event loop, and to have a newer requests +block the return of older ones, as the eventloop have to be unwound in +the order of their creation.

+

The proper solution is to have the invoked command indicate to +comm that it cannot or will not deliver an immediate, +synchronous result, but will do so later. At that point the framework +can put sending the actual result on hold and continue processing +requests using the main event loop. No blocking, no nesting of event +loops. At some future date the long running operation delivers the +result to comm, via the future object, which is then forwarded to the +invoker as usual.

+

The necessary support for this solution has been added to comm since +version 4.5, in the form of the new method return_async.

+
+
::comm::comm return_async
+

This command is used by a remotely invoked script to notify the comm +channel which invoked it that the result to send back to the invoker +is not generated synchronously. If this command is not called the +default/standard behaviour of comm is to send the synchronously +generated result of the script itself to the invoker.

+

The result of return_async is an object. This object, called a +future is where the result of the script has to be delivered to +when it becomes ready. When that happens it will take all the +necessary actions to deliver the result to the invoker of the script, +and then destroy itself. Should comm have lost the connection to the +invoker while the result is being computed the future will not try to +deliver the result it got, but just destroy itself. The future can be +configured with a command to call when the invoker is lost. This +enables the user to implement an early abort of the long-running +operation, should this be supported by it.

+

An example:

+
+# Procedure invoked by remote clients to run database operations.
+proc select {sql} {
+    # Signal the async generation of the result
+    set future [::comm::comm return_async]
+    # Generate an async db operation and tell it where to deliver the result.
+    set query [db query -command [list $future return] $sql]
+    # Tell the database system which query to cancel if the connection
+    # goes away while it is running.
+    $future configure -command [list db cancel $query]
+    # Note: The above will work without problem only if the async
+    # query will nover run its completion callback immediately, but
+    # only from the eventloop. Because otherwise the future we wish to
+    # configure may already be gone. If that is possible use 'catch'
+    # to prevent the error from propagating.
+    return
+}
+
+

The API of a future object is:

+
+
$future return ?-code code? ?value?
+

Use this method to tell the future that long-running operation has +completed. Arguments are an optional return value (defaults to the +empty string), and the Tcl return code (defaults to OK).

+

The future will deliver this information to invoker, if the connection +was not lost in the meantime, and then destroy itself. If the +connection was lost it will do nothing but destroy itself.

+
$future configure ?-command ?cmdprefix??
+
+
$future cget -command
+

These methods allow the user to retrieve and set a command to be +called if the connection the future belongs to has been lost.

+
+
+
+

Compatibility

+

comm exports itself as a package. The package version number +is in the form major . minor, where the major version will +only change when a non-compatible change happens to the API or +protocol. Minor bug fixes and changes will only affect the minor +version. To load comm this command is usually used:

+
+    package require comm 3
+
+

Note that requiring no version (or a specific version) can also be done.

+

The revision history of comm includes these releases:

+
+
4.6.3
+

Fixed ticket [ced0d60fc9]. Added proper detection of eof on a +socket, properly closing it.

+
4.6.2
+

Fixed bugs 2972571 and 3066872, the first a misdetection of quoted +brace after double backslash, the other a blocking gets making for an +obvious (hinsight) DoS attack on comm channels.

+
4.6.1
+

Changed the implementation of comm::commCollect to emulate +lindex's pre-Tcl 8 behaviour, i.e. it was given the ability to parse +out the first word of a list, even if the whole buffer is not a +well-formed list. Without this change the first word could only be +extracted if the whole buffer was a well-formed list (ever since Tcl +8), and in a ver-high-load situation, i.e. a server sending lots +and/or large commands very fast, this may never happen, eventually +crashing the receiver when it runs out of memory. With the change the +receiver is always able to process the first word when it becomes +well-formed, regardless of the structure of the remainder of the +buffer.

+
4.6
+

Added the option -socketcmd enabling users to override how a +socket is opened. The envisioned main use is the specification of the +tls::socket command, see package tls, to secure the +communication.

+
4.5.7
+

Changed handling of ports already in use to provide a proper error +message.

+
4.5.6
+

Bugfix in the replacement for vwait, made robust against of +variable names containing spaces.

+
4.5.5
+

Bugfix in the handling of hooks, typo in variable name.

+
4.5.4
+

Bugfix in the handling of the result received by the send +method. Replaced an after idle unset result with an immediate +unset, with the information saved to a local variable.

+

The after idle can spill into a forked child process if there +is no event loop between its setup and the fork. This may bork the +child if the next event loop is the vwait of comm's +send a few lines above the after idle, and the child +used the same serial number for its next request. In that case the +parent's after idle unset will delete the very array element +the child is waiting for, unlocking the vwait, causing it to +access a now missing array element, instead of the expected result.

+
4.5.3
+

Bugfixes in the wrappers for the builtin update and vwait +commands.

+
4.5.2
+

Bugfix in the wrapper for the builtin update command.

+
4.5.1
+

Bugfixes in the handling of -interp for regular scripts. The handling +of the buffer was wrong for scripts which are a single statement as +list. Fixed missing argument to new command commSendReply, +introduced by version 4.5. Affected debugging.

+
4.5
+

New server-side feature. The command invoked on the server can now +switch comm from the standard synchronous return of its result to an +asynchronous (defered) return. Due to the use of snit to implement the +future objects used by this feature from this version on comm +requires at least Tcl 8.3 to run. Please read the section +Asynchronous Result Generation for more details.

+
4.4.1
+

Bugfix in the execution of hooks.

+
4.4
+

Bugfixes in the handling of -interp for regular and hook +scripts. Bugfixes in channel cleanup.

+
4.3.1
+

Introduced -interp and -events to enable easy use of a slave interp +for execution of received scripts, and of event scripts.

+
4.3
+

Bugfixes, and introduces -silent to allow the user to force the +server/listening side to silently ignore connection attempts where the +protocol negotiation failed.

+
4.2
+

Bugfixes, and most important, switched to utf-8 as default encoding +for full i18n without any problems.

+
4.1
+

Rewrite of internal code to remove old pseudo-object model. Addition +of send -command asynchronous callback option.

+
4.0
+

Per request by John LoVerso. Improved handling of error for async +invoked commands.

+
3.7
+

Moved into tcllib and placed in a proper namespace.

+
3.6
+

A bug in the looking up of the remoteid for a executed command could +be triggered when the connection was closed while several asynchronous +sends were queued to be executed.

+
3.5
+

Internal change to how reply messages from a send are handled. +Reply messages are now decoded into the value to pass to +return; a new return statement is then cons'd up to with this +value. Previously, the return code was passed in from the remote as a +command to evaluate. Since the wire protocol has not changed, this is +still the case. Instead, the reply handling code decodes the +reply message.

+
3.4
+

Added more source commentary, as well as documenting config variables +in this man page. Fixed bug were loss of connection would give error +about a variable named pending rather than the message about +the lost connection. comm ids is now an alias for +comm interps (previously, it an alias for comm chans). +Since the method invocation change of 3.0, break and other exceptional +conditions were not being returned correctly from comm send. +This has been fixed by removing the extra level of indirection into +the internal procedure commSend. Also added propagation of +the errorCode variable. This means that these commands return +exactly as they would with send:

+
+    comm send id break
+    catch {comm send id break}
+    comm send id expr 1 / 0
+
+

Added a new hook for reply messages. Reworked method invocation to +avoid the use of comm:* procedures; this also cut the invocation time +down by 40%. Documented comm config (as this manual page +still listed the defunct comm init!)

+
3.3
+

Some minor bugs were corrected and the documentation was cleaned up. +Added some examples for hooks. The return semantics of the eval +hook were changed.

+
3.2
+

A new wire protocol, version 3, was added. This is backwards +compatible with version 2 but adds an exchange of supported protocol +versions to allow protocol negotiation in the future. Several bugs +with the hook implementation were fixed. A new section of the man +page on blocking semantics was added.

+
3.1
+

All the documented hooks were implemented. commLostHook was +removed. A bug in comm new was fixed.

+
3.0
+

This is a new version of comm with several major changes. +There is a new way of creating the methods available under the +comm command. The comm init method has been retired +and is replaced by comm configure which allows access to many +of the well-defined internal variables. This also generalizes the +options available to comm new. Finally, there is now a +protocol version exchanged when a connection is established. This +will allow for future on-wire protocol changes. Currently, the +protocol version is set to 2.

+
2.3
+

comm ids was renamed to comm channels. General +support for comm hook was fully implemented, but only the +lost hook exists, and it was changed to follow the general +hook API. commLostHook was unsupported (replaced by +comm hook lost) and commLost was removed.

+
2.2
+

The died hook was renamed lost, to be accessed by +commLostHook and an early implementation of +comm lost hook. As such, commDied is now +commLost.

+
2.1
+

Unsupported method comm remoteid was added.

+
2.0
+

comm has been rewritten from scratch (but is fully compatible +with Comm 1.0, without the requirement to use obTcl).

+
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Author

+

John LoVerso, John@LoVerso.Southborough.MA.US

+

http://www.opengroup.org/~loverso/tcl-tk/#comm

+
+

License

+

Please see the file comm.LICENSE that accompanied this source, +or +http://www.opengroup.org/www/dist_client/caubweb/COPYRIGHT.free.html.

+

This license for comm, new as of version 3.2, allows it to be +used for free, without any licensing fee or royalty.

+
+

Bugs

+
    +

  • If there is a failure initializing a channel created with +::comm::comm new, then the channel should be destroyed. +Currently, it is left in an inconsistent state.

    • +

  • There should be a way to force a channel to quiesce when changing the +configuration.

    • +
+

The following items can be implemented with the existing hooks and are +listed here as a reminder to provide a sample hook in a future +version.

+
    +

  • Allow easier use of a slave interp for actual command execution +(especially when operating in "not local" mode).

    • +

  • Add host list (xhost-like) or "magic cookie" (xauth-like) +authentication to initial handshake.

    • +
+

The following are outstanding todo items.

+
    +

  • Add an interp discovery and name->port mapping. This is likely to be +in a separate, optional nameserver. (See also the related work, +below.)

    • +

  • Fix the {id host} form so as not to be dependent upon +canonical hostnames. This requires fixes to Tcl to resolve hostnames!

    • +
+

This man page is bigger than the source file.

+
+

On Using Old Versions Of Tcl

+

Tcl7.5 under Windows contains a bug that causes the interpreter to +hang when EOF is reached on non-blocking sockets. This can be +triggered with a command such as this:

+
+    "comm send $other exit"
+
+

Always make sure the channel is quiescent before closing/exiting or +use at least Tcl7.6 under Windows.

+

Tcl7.6 on the Mac contains several bugs. It is recommended you use +at least Tcl7.6p2.

+

Tcl8.0 on UNIX contains a socket bug that can crash Tcl. It is recommended +you use Tcl8.0p1 (or Tcl7.6p2).

+
+

Related Work

+

Tcl-DP provides an RPC-based remote execution interface, but is a +compiled Tcl extension. See +http://www.cs.cornell.edu/Info/Projects/zeno/Projects/Tcl-DP.html.

+

Michael Doyle <miked@eolas.com> has code that implements the Tcl-DP +RPC interface using standard Tcl sockets, much like comm.

+

Andreas Kupries <andreas_kupries@users.sourceforge.net> uses +comm and has built a simple nameserver as part of his Pool +library. See http://www.purl.org/net/akupries/soft/pool/index.htm.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category comm of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

send(n)

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/comm/comm_wire.html Index: embedded/www/tcllib/files/modules/comm/comm_wire.html ================================================================== --- embedded/www/tcllib/files/modules/comm/comm_wire.html +++ embedded/www/tcllib/files/modules/comm/comm_wire.html @@ -0,0 +1,274 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

comm_wire(n) 3 tcllib "Remote communication"

+

Name

+

comm_wire - The comm wire protocol

+
+ +

Synopsis

+
+
    +
  • package require comm
    • +
+
+
+

Description

+

The comm command provides an inter-interpreter remote +execution facility much like Tk's send(n), except that it uses +sockets rather than the X server for the communication path. As a +result, comm works with multiple interpreters, works on +Windows and Macintosh systems, and provides control over the remote +execution path.

+

This document contains a specification of the various versions of the +wire protocol used by comm internally for the communication between +its endpoints. It has no relevance to users of comm, only to +developers who wish to modify the package, write a compatible facility +in a different language, or some other facility based on the same +protocol.

+
+

Wire Protocol Version 3

+

Basic Layer

+

The basic encoding for all data is UTF-8. Because of this +binary data, including the NULL character, can be sent over the wire +as is, without the need for armoring it.

+
+

Basic Message Layer

+

On top of the Basic Layer we have a +message oriented exchange of data. +The totality of all characters written to the channel is a Tcl list, +with each element a separate message, each itself a list. The +messages in the overall list are separated by EOL. Note that EOL +characters can occur within the list as well. They can be +distinguished from the message-separating EOL by the fact that the +data from the beginning up to their location is not a valid Tcl list.

+

EOL is signaled through the linefeed character, i.e LF, or, +hex 0x0a. This is following the unix convention for +line-endings.

+

As a list each message is composed of words. Their meaning +depends on when the message was sent in the overall exchange. This is +described in the upcoming sections.

+
+

Negotiation Messages - Initial Handshake

+

The command protocol is defined like this:

+
    +

  • The first message send by a client to a server, when opening the +connection, contains two words. The first word is a list as well, and +contains the versions of the wire protocol the client is willing to +accept, with the most preferred version first. The second word is the +TCP port the client is listening on for connections to itself. The +value 0 is used here to signal that the client will not listen +for connections, i.e. that it is purely for sending commands, and not +receiving them.

    • +

  • The first message sent by the server to the client, in response to the +message above contains only one word. This word is a list, containing +the string vers as its first element, and the version of the +wire protocol the server has selected from the offered versions as the +second.

    • +
+
+

Script/Command Messages

+

All messages coming after the initial handshake +consist of three words. These are an instruction, a transaction id, +and the payload. The valid instructions are shown below. The +transaction ids are used by the client to match any incoming replies +to the command messages it sent. This means that a server has to copy +the transaction id from a command message to the reply it sends for +that message.

+
+
send
+
+
async
+
+
command
+

The payload is the Tcl script to execute on the server. It is actually +a list containing the script fragments. These fragment are +concatenated together by the server to form the full script to +execute on the server side. +This emulates the Tcl "eval" semantics. +In most cases it is best to have only one word in the list, a list +containing the exact command.

+

Examples:

+
+    (a)     {send 1 {{array get tcl_platform}}}
+    (b)     {send 1 {array get tcl_platform}}
+    (c)     {send 1 {array {get tcl_platform}}}
+    are all valid representations of the same command. They are
+    generated via
+    (a')    send {array get tcl_platform}
+    (b')    send array get tcl_platform
+    (c')    send array {get tcl_platform}
+    respectively
+
+

Note that (a), generated by (a'), is the usual form, if only single +commands are sent by the client. +For example constructed using list, if the command contains +variable arguments. Like

+
+    send [list array get $the_variable]
+
+

These three instructions all invoke the script on the server +side. Their difference is in the treatment of result values, and thus +determines if a reply is expected.

+
+
send
+

A reply is expected. The sender is waiting for the result.

+
async
+

No reply is expected, the sender has no interest in the result and is +not waiting for any.

+
command
+

A reply is expected, but the sender is not waiting for it. It has +arranged to get a process-internal notification when the result +arrives.

+
+
reply
+

Like the previous three command, however the tcl script in the payload +is highly restricted. +It has to be a syntactically valid Tcl return command. This +contains result code, value, error code, and error info.

+

Examples:

+
+    {reply 1 {return -code 0 {}}}
+    {reply 1 {return -code 0 {osVersion 2.4.21-99-default byteOrder littleEndian machine i686 platform unix os Linux user andreask wordSize 4}}}
+
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category comm of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/control/control.html Index: embedded/www/tcllib/files/modules/control/control.html ================================================================== --- embedded/www/tcllib/files/modules/control/control.html +++ embedded/www/tcllib/files/modules/control/control.html @@ -0,0 +1,252 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

control(n) 0.1.3 tcllib "Tcl Control Flow Commands"

+

Name

+

control - Procedures for control flow structures.

+
+ + +

Description

+

The control package provides a variety of commands that provide +additional flow of control structures beyond the built-in ones +provided by Tcl. These are commands that in many programming +languages might be considered keywords, or a part of the +language itself. In Tcl, control flow structures are just commands +like everything else.

+
+

COMMANDS

+
+
control::control command option ?arg arg ...?
+

The control command is used as a configuration command for +customizing the other public commands of the control package. The +command argument names the command to be customized. The set of +valid option and subsequent arguments are determined by the +command being customized, and are documented with the command.

+
control::assert expr ?arg arg ...?
+

When disabled, the assert command behaves exactly like the +no-op command.

+

When enabled, the assert command evaluates expr as an +expression (in the same way that expr evaluates its argument). +If evaluation reveals that expr is not a valid boolean +expression (according to [string is boolean -strict]), +an error is raised. If expr evaluates to a true boolean value +(as recognized by if), then assert returns an empty +string. Otherwise, the remaining arguments to assert are used +to construct a message string. If there are no arguments, the message +string is "assertion failed: $expr". If there are arguments, they are +joined by join to form the message string. The message string +is then appended as an argument to a callback command, and the +completed callback command is evaluated in the global namespace.

+

The assert command can be customized by the control +command in two ways:

+

[control::control assert enabled ?boolean?] +queries or sets whether control::assert is enabled. When called +without a boolean argument, a boolean value is returned +indicating whether the control::assert command is enabled. When +called with a valid boolean value as the boolean argument, the +control::assert command is enabled or disabled to match the +argument, and an empty string is returned.

+

[control::control assert callback ?command?] +queries or sets the callback command that will be called by an enabled +assert on assertion failure. When called without a +command argument, the current callback command is returned. +When called with a command argument, that argument becomes the +new assertion failure callback command. Note that an assertion +failure callback command is always defined, even when assert +is disabled. The default callback command is +[return -code error].

+

Note that control::assert has been written so that in +combination with [namespace import], it is possible to +use enabled assert commands in some namespaces and disabled +assert commands in other namespaces at the same time. This +capability is useful so that debugging efforts can be independently +controlled module by module.

+
+% package require control
+% control::control assert enabled 1
+% namespace eval one namespace import ::control::assert
+% control::control assert enabled 0
+% namespace eval two namespace import ::control::assert
+% one::assert {1 == 0}
+assertion failed: 1 == 0
+% two::assert {1 == 0}
+
+
+
control::do body ?option test?
+

The do command evaluates the script body repeatedly +until the expression test becomes true or as long as +(while) test is true, depending on the value of +option being until or while. If +option and test are omitted the body is evaluated exactly +once. After normal completion, do returns an empty string. +Exceptional return codes (break, continue, error, +etc.) during the evaluation of body are handled in the same way +the while command handles them, except as noted in +LIMITATIONS, below.

+
control::no-op ?arg arg ...?
+

The no-op command takes any number of arguments and does +nothing. It returns an empty string.

+
+
+

LIMITATIONS

+

Several of the commands provided by the control package accept +arguments that are scripts to be evaluated. Due to fundamental +limitations of Tcl's catch and return commands, it is not +possible for these commands to properly evaluate the command +[return -code $code] within one of those script +arguments for any value of $code other than ok. In this +way, the commands of the control package are limited as compared +to Tcl's built-in control flow commands (such as if, +while, etc.) and those control flow commands that can be +provided by packages coded in C. An example of this difference:

+
+% package require control
+% proc a {} {while 1 {return -code error a}}
+% proc b {} {control::do {return -code error b} while 1}
+% catch a
+1
+% catch b
+0
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category control of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

break, continue, expr, if, join, namespace, return, string, while

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/coroutine/coro_auto.html Index: embedded/www/tcllib/files/modules/coroutine/coro_auto.html ================================================================== --- embedded/www/tcllib/files/modules/coroutine/coro_auto.html +++ embedded/www/tcllib/files/modules/coroutine/coro_auto.html @@ -0,0 +1,168 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

coroutine::auto(n) 1.1.3 tcllib "Coroutine utilities"

+

Name

+

coroutine::auto - Automatic event and IO coroutine awareness

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require coroutine::auto 1.1.3
    • +
  • package require coroutine 1.1
    • +
+
+
+

Description

+

The coroutine::auto package provides no commands or other +directly visible functionality. +Built on top of the package coroutine, it intercepts various +builtin commands of the Tcl core to make any code using them +coroutine-oblivious, i.e. able to run inside and outside of a +coroutine without changes.

+

The commands so affected by this package are

+
+
after
+
+
exit
+
+
gets
+
+
global
+
+
read
+
+
update
+
+
vwait
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category coroutine of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Coroutine

+
+ +
ADDED embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html Index: embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html ================================================================== --- embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html +++ embedded/www/tcllib/files/modules/coroutine/tcllib_coroutine.html @@ -0,0 +1,213 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

coroutine(n) 1.1.3 tcllib "Coroutine utilities"

+

Name

+

coroutine - Coroutine based event and IO handling

+
+ + +

Description

+

The coroutine package provides coroutine-aware +implementations of various event- and channel related commands. It can +be in multiple modes:

+
    +

  1. Call the commands through their ensemble, in code which is +explicitly written for use within coroutines.

    2. +

  2. Import the commands into a namespace, either directly, or +through namespace path. This allows the use from within code +which is not coroutine-aware per se and restricted to specific +namespaces.

    3. +
+

A more agressive form of making code coroutine-oblivious than point 2 +above is available through the package coroutine::auto, +which intercepts the relevant builtin commands and changes their +implementation dependending on the context they are run in, i.e. +inside or outside of a coroutine.

+
+

API

+

All the commands listed below are synchronous with respect to the +coroutine invoking them, i.e. this coroutine blocks until the result +is available. The overall eventloop is not blocked however.

+
+
coroutine::util after delay
+

This command delays the coroutine invoking it by delay +milliseconds.

+
coroutine::util await varname...
+

This command is an extension form of the coroutine::util vwait +command (see below) which waits on a write to one of many named +namespace variables.

+
coroutine::util create arg...
+

This command creates a new coroutine with an automatically assigned +name and causes it to run the code specified by the arguments.

+
coroutine::util exit ?status?
+

This command exits the current coroutine, causing it to return +status. If no status was specified the default 0 is +returned.

+
coroutine::util gets chan ?varname?
+

This command reads a line from the channel chan and returns it +either as its result, or, if a varname was specified, writes it +to the named variable and returns the number of characters read.

+
coroutine::util global varname...
+

This command imports the named global variables of the coroutine into +the current scope. From the technical point of view these variables +reside in level #1 of the Tcl stack. I.e. these are not the +regular global variable in to the global namespace, and each coroutine +can have their own set, independent of all others.

+
coroutine::util read -nonewline chan ?n?
+

This command reads n characters from the channel chan and +returns them as its result. If n is not specified the command +will read the channel until EOF is reached.

+
coroutine::util update ?idletasks?
+

This command causes the coroutine invoking it to run pending events or +idle handlers before proceeding.

+
coroutine::util vwait varname
+

This command causes the coroutine calling it to wait for a write to +the named namespace variable varname.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category coroutine of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Coroutine

+
+ +
ADDED embedded/www/tcllib/files/modules/counter/counter.html Index: embedded/www/tcllib/files/modules/counter/counter.html ================================================================== --- embedded/www/tcllib/files/modules/counter/counter.html +++ embedded/www/tcllib/files/modules/counter/counter.html @@ -0,0 +1,293 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

counter(n) 2.0.4 tcllib "Counters and Histograms"

+

Name

+

counter - Procedures for counters and histograms

+
+ + +

Description

+

The counter package provides a counter facility and can +compute statistics and histograms over the collected data.

+
+
::counter::init tag args
+

This defines a counter with the name tag. The args +determines the characteristics of the counter. The args are

+
+
-group name
+

Keep a grouped counter where the name of the histogram bucket is +passed into ::counter::count.

+
-hist bucketsize
+

Accumulate the counter into histogram buckets of size +bucketsize. For example, if the samples are millisecond time +values and bucketsize is 10, then each histogram bucket +represents time values of 0 to 10 msec, 10 to 20 msec, 20 to 30 msec, +and so on.

+
-hist2x bucketsize
+

Accumulate the statistic into histogram buckets. The size of the +first bucket is bucketsize, each other bucket holds values 2 +times the size of the previous bucket. For example, if +bucketsize is 10, then each histogram bucket represents time +values of 0 to 10 msec, 10 to 20 msec, 20 to 40 msec, 40 to 80 msec, +and so on.

+
-hist10x bucketsize
+

Accumulate the statistic into histogram buckets. The size of the +first bucket is bucketsize, each other bucket holds values 10 +times the size of the previous bucket. For example, if +bucketsize is 10, then each histogram bucket represents time +values of 0 to 10 msec, 10 to 100 msec, 100 to 1000 msec, and so on.

+
-lastn N
+

Save the last N values of the counter to maintain a "running +average" over the last N values.

+
-timehist secsPerMinute
+

Keep a time-based histogram. The counter is summed into a histogram +bucket based on the current time. There are 60 per-minute buckets +that have a size determined by secsPerMinute, which is normally +60, but for testing purposes can be less. Every "hour" (i.e., 60 +"minutes") the contents of the per-minute buckets are summed into the +next hourly bucket. Every 24 "hours" the contents of the per-hour +buckets are summed into the next daily bucket. The counter package +keeps all time-based histograms in sync, so the first +secsPerMinute value seen by the package is used for all +subsequent time-based histograms.

+
+
::counter::count tag ?delta? ?instance?
+

Increment the counter identified by tag. The default increment +is 1, although you can increment by any value, integer or real, by +specifying delta. You must declare each counter with +::counter::init to define the characteristics of counter before +you start to use it. If the counter type is -group, then the +counter identified by instance is incremented.

+
::counter::start tag instance
+

Record the starting time of an interval. The tag is the name of +the counter defined as a -hist value-based histogram. The +instance is used to distinguish this interval from any other +intervals that might be overlapping this one.

+
::counter::stop tag instance
+

Record the ending time of an interval. The delta time since the +corresponding ::counter::start call for instance is +recorded in the histogram identified by tag.

+
::counter::get tag args
+

Return statistics about a counter identified by tag. The +args determine what value to return:

+
+
-total
+

Return the total value of the counter. This is the default if +args is not specified.

+
-totalVar
+

Return the name of the total variable. Useful for specifying with +-textvariable in a Tk widget.

+
-N
+

Return the number of samples accumulated into the counter.

+
-avg
+

Return the average of samples accumulated into the counter.

+
-avgn
+

Return the average over the last N samples taken. The N +value is set in the ::counter::init call.

+
-hist bucket
+

If bucket is specified, then the value in that bucket of the +histogram is returned. Otherwise the complete histogram is returned +in array get format sorted by bucket.

+
-histVar
+

Return the name of the histogram array variable.

+
-histHour
+

Return the complete hourly histogram in array get format sorted by +bucket.

+
-histHourVar
+

Return the name of the hourly histogram array variable.

+
-histDay
+

Return the complete daily histogram in array get format sorted by +bucket.

+
-histDayVar
+

Return the name of the daily histogram array variable.

+
-resetDate
+

Return the clock seconds value recorded when the +counter was last reset.

+
-all
+

Return an array get of the array used to store the counter. This +includes the total, the number of samples (N), and any type-specific +information. This does not include the histogram array.

+
+
::counter::exists tag
+

Returns 1 if the counter is defined.

+
::counter::names
+

Returns a list of all counters defined.

+
::counter::histHtmlDisplay tag args
+

Generate HTML to display a histogram for a counter. The args +control the format of the display. They are:

+
+
-title string
+

Label to display above bar chart

+
-unit unit
+

Specify minutes, hours, or days for the +time-base histograms. For value-based histograms, the unit is +used in the title.

+
-images url
+

URL of /images directory.

+
-gif filename
+

Image for normal histogram bars. The filename is relative to +the -images directory.

+
-ongif filename
+

Image for the active histogram bar. The filename is relative to +the -images directory.

+
-max N
+

Maximum number of value-based buckets to display.

+
-height N
+

Pixel height of the highest bar.

+
-width N
+

Pixel width of each bar.

+
-skip N
+

Buckets to skip when labeling value-based histograms.

+
-format string
+

Format used to display labels of buckets.

+
-text boolean
+

If 1, a text version of the histogram is dumped, otherwise a graphical +one is generated.

+
+
::counter::reset tag args
+

Resets the counter with the name tag to an initial state. The +args determine the new characteristics of the counter. They have +the same meaning as described for ::counter::init.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category counter of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/crc/cksum.html Index: embedded/www/tcllib/files/modules/crc/cksum.html ================================================================== --- embedded/www/tcllib/files/modules/crc/cksum.html +++ embedded/www/tcllib/files/modules/crc/cksum.html @@ -0,0 +1,233 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

cksum(n) 1.1.4 tcllib "Cyclic Redundancy Checks"

+

Name

+

cksum - Calculate a cksum(1) compatible checksum

+
+ + +

Description

+

This package provides a Tcl implementation of the cksum(1) algorithm +based upon information provided at in the GNU implementation of this +program as part of the GNU Textutils 2.0 package.

+
+

COMMANDS

+
+
::crc::cksum ?-format format? ?-chunksize size? [ -channel chan | -filename file | string ]
+

The command takes string data or a channel or file name and returns a +checksum value calculated using the cksum(1) algorithm. The +result is formatted using the format(n) specifier provided or as +an unsigned integer (%u) by default.

+
+
+

OPTIONS

+
+
-channel name
+

Return a checksum for the data read from a channel. The command will +read data from the channel until the eof is true. If you need +to be able to process events during this calculation see the +PROGRAMMING INTERFACE section

+
-filename name
+

This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the -channel option had +been used. The file is closed on completion.

+
-format string
+

Return the checksum using an alternative format template.

+
+
+

PROGRAMMING INTERFACE

+

The cksum package implements the checksum using a context variable to +which additional data can be added at any time. This is expecially +useful in an event based environment such as a Tk application or a web +server package. Data to be checksummed may be handled incrementally +during a fileevent handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption.

+
+
::crc::CksumInit
+

Begins a new cksum context. Returns a token ID that must be used for the +remaining functions. An optional seed may be specified if required.

+
::crc::CksumUpdate token data
+

Add data to the checksum identified by token. Calling +CksumUpdate $token "abcd" is equivalent to calling +CksumUpdate $token "ab" followed by +CksumUpdate $token "cb". See EXAMPLES.

+
::crc::CksumFinal token
+

Returns the checksum value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a 32 bit integer value.

+
+
+

EXAMPLES

+
+% crc::cksum "Hello, World!"
+2609532967
+
+
+% crc::cksum -format 0x%X "Hello, World!"
+0x9B8A5027
+
+
+% crc::cksum -file cksum.tcl
+1828321145
+
+
+% set tok [crc::CksumInit]
+% crc::CksumUpdate $tok "Hello, "
+% crc::CksumUpdate $tok "World!"
+% crc::CksumFinal $tok
+2609532967
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category crc of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/crc16.html Index: embedded/www/tcllib/files/modules/crc/crc16.html ================================================================== --- embedded/www/tcllib/files/modules/crc/crc16.html +++ embedded/www/tcllib/files/modules/crc/crc16.html @@ -0,0 +1,243 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

crc16(n) 1.1.2 tcllib "Cyclic Redundancy Checks"

+

Name

+

crc16 - Perform a 16bit Cyclic Redundancy Check

+
+ + +

Description

+

This package provides a Tcl-only implementation of the CRC +algorithms based upon information provided at +http://www.microconsultants.com/tips/crc/crc.txt +There are a number of permutations available for calculating CRC +checksums and this package can handle all of them. Defaults are set up +for the most common cases.

+
+

COMMANDS

+
+
::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::crc16 ?-format format? ?-seed value? ?-implementation procname? -filename file
+
+
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::crc-ccitt ?-format format? ?-seed value? ?-implementation procname? -filename file
+
+
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? message
+
+
::crc::xmodem ?-format format? ?-seed value? ?-implementation procname? -filename file
+

The command takes either string data or a file name and returns a checksum +value calculated using the CRC algorithm. The command used sets up the +CRC polynomial, initial value and bit ordering for the desired +standard checksum calculation. The result is formatted +using the format(n) specifier provided or as an unsigned integer +(%u) by default.

+

A number of common polynomials are in use with the CRC algorithm and +the most commonly used of these are included in this package. For +convenience each of these has a command alias in the crc namespace.

+

It is possible to implement the CRC-32 checksum using this crc16 +package as the implementation is sufficiently generic to extend to 32 +bit checksums. As an example this has been done already - however this +is not the fastest method to implement this algorithm in Tcl and a +separate crc32 package is available.

+
+
+

OPTIONS

+
+
-filename name
+

Return a checksum for the file contents instead of for parameter data.

+
-format string
+

Return the checksum using an alternative format template.

+
-seed value
+

Select an alternative seed value for the CRC calculation. The default +is 0 for the CRC16 calculation and 0xFFFF for the CCITT version. +This can be useful for calculating the CRC for data +structures without first converting the whole structure into a +string. The CRC of the previous member can be used as the seed for +calculating the CRC of the next member. It is also used for +accumulating a checksum from fragments of a large message (or file)

+
-implementation procname
+

This hook is provided to allow users to provide their own +implementation (perhaps a C compiled extension). The +procedure specfied is called with two parameters. The first is the +data to be checksummed and the second is the seed value. An +integer is expected as the result.

+

The package provides some implementations of standard CRC polynomials +for the XMODEM, CCITT and the usual CRC-16 checksum. For convenience, +additional commands have been provided that make use of these +implementations.

+
--
+

Terminate option processing.

+
+
+

EXAMPLES

+
+% crc::crc16 "Hello, World!"
+64077
+
+
+% crc::crc-ccitt "Hello, World!"
+26586
+
+
+% crc::crc16 -format 0x%X "Hello, World!"
+0xFA4D
+
+
+% crc::crc16 -file crc16.tcl
+51675
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category crc of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/crc32.html Index: embedded/www/tcllib/files/modules/crc/crc32.html ================================================================== --- embedded/www/tcllib/files/modules/crc/crc32.html +++ embedded/www/tcllib/files/modules/crc/crc32.html @@ -0,0 +1,248 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

crc32(n) 1.3.2 tcllib "Cyclic Redundancy Checks"

+

Name

+

crc32 - Perform a 32bit Cyclic Redundancy Check

+
+ + +

Description

+

This package provides a Tcl implementation of the CRC-32 +algorithm based upon information provided at +http://www.naaccr.org/standard/crc32/document.html +If either the critcl package or the Trf package +are available then a compiled version may be used internally to +accelerate the checksum calculation.

+
+

COMMANDS

+
+
::crc::crc32 ?-format format? ?-seed value? [ -channel chan | -filename file | message ]
+

The command takes either string data or a channel or file name and +returns a checksum value calculated using the CRC-32 algorithm. The +result is formatted using the format(n) specifier provided. The +default is to return the value as an unsigned integer (format %u).

+
+
+

OPTIONS

+
+
-channel name
+

Return a checksum for the data read from a channel. The command will +read data from the channel until the eof is true. If you need +to be able to process events during this calculation see the +PROGRAMMING INTERFACE section

+
-filename name
+

This is a convenience option that opens the specified file, sets the +encoding to binary and then acts as if the -channel option had +been used. The file is closed on completion.

+
-format string
+

Return the checksum using an alternative format template.

+
-seed value
+

Select an alternative seed value for the CRC calculation. The default +is 0xffffffff. This can be useful for calculating the CRC for data +structures without first converting the whole structure into a +string. The CRC of the previous member can be used as the seed for +calculating the CRC of the next member. +Note that the crc32 algorithm includes a final XOR step. If +incremental processing is desired then this must be undone before +using the output of the algorithm as the seed for further +processing. A simpler alternative is to use the +PROGRAMMING INTERFACE which is intended for this mode of +operation.

+
+
+

PROGRAMMING INTERFACE

+

The CRC-32 package implements the checksum using a context variable to +which additional data can be added at any time. This is expecially +useful in an event based environment such as a Tk application or a web +server package. Data to be checksummed may be handled incrementally +during a fileevent handler in discrete chunks. This can improve +the interactive nature of a GUI application and can help to avoid +excessive memory consumption.

+
+
::crc::Crc32Init ?seed?
+

Begins a new CRC32 context. Returns a token ID that must be used for the +remaining functions. An optional seed may be specified if required.

+
::crc::Crc32Update token data
+

Add data to the checksum identified by token. Calling +Crc32Update $token "abcd" is equivalent to calling +Crc32Update $token "ab" followed by +Crc32Update $token "cb". See EXAMPLES.

+
::crc::Crc32Final token
+

Returns the checksum value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a 32 bit integer value.

+
+
+

EXAMPLES

+
+% crc::crc32 "Hello, World!"
+3964322768
+
+
+% crc::crc32 -format 0x%X "Hello, World!"
+0xEC4AC3D0
+
+
+% crc::crc32 -file crc32.tcl
+483919716
+
+
+% set tok [crc::Crc32Init]
+% crc::Crc32Update $tok "Hello, "
+% crc::Crc32Update $tok "World!"
+% crc::Crc32Final $tok
+3964322768
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category crc of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/crc/sum.html Index: embedded/www/tcllib/files/modules/crc/sum.html ================================================================== --- embedded/www/tcllib/files/modules/crc/sum.html +++ embedded/www/tcllib/files/modules/crc/sum.html @@ -0,0 +1,208 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

sum(n) 1.1.2 tcllib "Cyclic Redundancy Checks"

+

Name

+

sum - Calculate a sum(1) compatible checksum

+
+ + +

Description

+

This package provides a Tcl-only implementation of the sum(1) command +which calculates a 16 bit checksum value from the input data. The BSD +sum algorithm is used by default but the SysV algorithm is also +available.

+
+

COMMANDS

+
+
::crc::sum ?-bsd | -sysv? ?-format fmt? ?-chunksize size? [ -filename file | -channel chan | string ]
+

The command takes string data or a file name or a channel and returns +a checksum value calculated using the sum(1) algorithm. The +result is formatted using the format(n) specifier provided or as +an unsigned integer (%u) by default.

+
+
+

OPTIONS

+
+
-sysv
+

The SysV algorithm is fairly naive. The byte values are summed and any +overflow is discarded. The lowest 16 bits are returned as the +checksum. Input with the same content but different ordering will +give the same result.

+
-bsd
+

This algorithm is similar to the SysV version but includes a bit rotation +step which provides a dependency on the order of the data values.

+
-filename name
+

Return a checksum for the file contents instead of for parameter data.

+
-channel chan
+

Return a checksum for the contents of the specified channel. The +channel must be open for reading and should be configured for binary +translation. The channel will no be closed on completion.

+
-chunksize size
+

Set the block size used when reading data from either files or +channels. This value defaults to 4096.

+
-format string
+

Return the checksum using an alternative format template.

+
+
+

EXAMPLES

+
+% crc::sum "Hello, World!"
+37287
+
+
+% crc::sum -format 0x%X "Hello, World!"
+0x91A7
+
+
+% crc::sum -file sum.tcl
+13392
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category crc of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/cron/cron.html Index: embedded/www/tcllib/files/modules/cron/cron.html ================================================================== --- embedded/www/tcllib/files/modules/cron/cron.html +++ embedded/www/tcllib/files/modules/cron/cron.html @@ -0,0 +1,292 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

cron(n) 2.0 tcllib "cron"

+

Name

+

cron - Tool for automating the period callback of commands

+
+ + +

Description

+

The cron package provides a Pure-tcl set of tools to allow +programs to schedule tasks to occur at regular intervals. Rather than +force each task to issue it's own call to the event loop, the cron +system mimics the cron utility in Unix: on task periodically checks to +see if something is to be done, and issues all commands for a given +time step at once.

+

Changes in version 2.0

+

While cron was originally designed to handle time scales > 1 second, the +latest version's internal understand time granularity down to the millisecond, +making it easier to integrate with other timed events. +Version 2.0 also understands how to properly integrate coroutines and objects. +It also adds a facility for an external (or script driven) clock. Note that vwait style events +won't work very well with an external clock.

+
+

Commands

+
+
::cron::at ?processname? timecode command
+

This command registers a command to be called at the time specified by timecode. +If timecode is expressed as an integer, the timecode is assumed to be in unixtime. All +other inputs will be interpreted by clock scan and converted to unix time. +This task can be modified by subsequent calls to +this package's commands by referencing processname. If processname exists, +it will be replaced. +If processname is not given, one is generated and returned by the command.

+
+::cron::at start_coffee {Tomorrow at 9:00am}  {remote::exec::coffeepot power on}
+::cron::at shutdown_coffee {Tomorrow at 12:00pm}  {remote::exec::coffeepot power off}
+
+
+
::cron::cancel processname
+

This command unregisters the process processname and cancels any pending commands. +Note: processname can be a process created by either ::cron::at or ::cron::every.

+
+::cron::cancel check_mail
+
+
+
::cron::every processname frequency command
+

This command registers a command to be called at the interval of frequency. +frequency is given in seconds. This task can be modified by subsequent calls to +this package's commands by referencing processname. If processname exists, +it will be replaced.

+
+::cron::every check_mail 900  ::imap_client::check_mail
+::cron::every backup_db  3600 {::backup_procedure ::mydb}
+
+
+
::cron::in ?processname? timecode command
+

This command registers a command to be called after a delay of time specified by timecode. +timecode is expressed as an seconds. +This task can be modified by subsequent calls to +this package's commands by referencing processname. If processname exists, +it will be replaced. +If processname is not given, one is generated and returned by the command.

+
::cron::object_coroutine object coroutine ?info?
+

This command registers a coroutine, associated with object to be called +given the parameters of info. If now parameters are given, the coroutine is assumed +to be an idle task which will self-terminate. info can be given in any form compadible with +::cron::task set

+
::cron::sleep milliseconds
+

When run within a coroutine, this command will register the coroutine for a callback +at the appointed time, and immediately yield.

+

If the ::cron::time variable is > 0 this command will advance the internal time, +100ms at a time.

+

In all other cases this command will generate a fictious variable, generate an +after call, and vwait the variable:

+
+set eventid [incr ::cron::eventcount]
+set var ::cron::event_#$eventid
+set $var 0
+::after $ms "set $var 1"
+::vwait $var
+::unset $var
+
+

Usage:

+
+::cron::sleep 250
+
+
+
::cron::task delete process
+

Delete the process specified the process

+
::cron::task exists process
+

Returns true if process is registered with cron.

+
::cron::task info process
+

Returns a dict describing process. See ::cron::task set for a description of the options.

+
::cron::task set process field value ?field...? ?value...?
+

If process does not exist, it is created. Options Include:

+
+command +If coroutine is black, a global command which implements this process. If coroutine is not +black, the command to invoke to create or recreate the coroutine. +coroutine +The name of the coroutine (if any) which implements this process. +frequency +If -1, this process is terminated after the next event. If 0 this process should be called during every +idle event. If positive, this process should generate events periodically. The frequency is an interger number +of milleseconds between events. +object +The object associated with this process or coroutine. +scheduled +If non-zero, the absolute time from the epoch (in milleseconds) that this process will trigger an event. +If zero, and the frequency is also zero, this process is called every idle loop. +running +A boolean flag. If true it indicates the process never returned or yielded during the event loop, +and will not be called again until it does so. +
+
::cron::wake ?who?
+

Wake up cron, and arrange for its event loop to be run during the next Idle cycle.

+
+::cron::wake {I just did something important}
+
+
+
+

Several utility commands are provided that are used internally within cron and for +testing cron, but may or may not be useful in the general cases.

+
+
::cron::clock_step milleseconds
+

Return a clock time absolute to the epoch which falls on the next +border between one second and the next for the value of milleseconds

+
::cron::clock_delay milleseconds
+

Return a clock time absolute to the epoch which falls on the next +border between one second and the next milleseconds in the future.

+
::cron::clock_sleep seconds ?offset?
+

Return a clock time absolute to the epoch which falls exactly seconds in +the future. If offset is given it may be positive or negative, and will shift +the final time to before or after the second would flip.

+
::cron::clock_set newtime
+

Sets the internal clock for cron. This command will advance the time in 100ms +increment, triggering events, until the internal time catches up with newtime.

+

newtime is expressed in absolute milleseconds since the beginning of the epoch.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category odie of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

System

+
+ +
ADDED embedded/www/tcllib/files/modules/csv/csv.html Index: embedded/www/tcllib/files/modules/csv/csv.html ================================================================== --- embedded/www/tcllib/files/modules/csv/csv.html +++ embedded/www/tcllib/files/modules/csv/csv.html @@ -0,0 +1,313 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

csv(n) 0.8.1 tcllib "CSV processing"

+

Name

+

csv - Procedures to handle CSV data.

+
+ + +

Description

+

The csv package provides commands to manipulate information +in CSV FORMAT (CSV = Comma Separated Values).

+
+

COMMANDS

+

The following commands are available:

+
+
::csv::iscomplete data
+

A predicate checking if the argument data is a complete csv +record. The result is a boolean flag indicating the completeness of +the data. The result is true if the data is complete.

+
::csv::join values ?sepChar? ?delChar? ?delMode?
+

Takes a list of values and returns a string in CSV format containing +these values. The separator character can be defined by the caller, +but this is optional. The default is ",". The quoting aka delimiting character can +be defined by the caller, but this is optional. The default is '"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead.

+
::csv::joinlist values ?sepChar? ?delChar? ?delMode?
+

Takes a list of lists of values and returns a string in CSV format +containing these values. The separator character can be defined by the +caller, but this is optional. The default is ",". The quoting character +can be defined by the caller, but this is optional. The default is '"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead. +Each element of the outer list is considered a record, these are +separated by newlines in the result. The elements of each record are +formatted as usual (via ::csv::join).

+
::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?
+

Takes a matrix object following the API specified for the +struct::matrix package and returns a string in CSV format containing +these values. The separator character can be defined by the caller, +but this is optional. The default is ",". The quoting character +can be defined by the caller, but this is optional. The default is +'"'. +By default the quoting mode delMode is "auto", surrounding +values with delChar only when needed. When set to "always" +however, values are always surrounded by the delChar instead. +Each row of the matrix is considered a record, these are +separated by newlines in the result. The elements of each record are +formatted as usual (via ::csv::join).

+
::csv::read2matrix ?-alternate? chan m {sepChar ,} {expand none}
+

A wrapper around ::csv::split2matrix (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given matrix. For an explanation of the expand +argument see ::csv::split2matrix.

+
::csv::read2queue ?-alternate? chan q {sepChar ,}
+

A wrapper around ::csv::split2queue (see below) reading +CSV-formatted lines from the specified channel (until EOF) and adding +them to the given queue.

+
::csv::report cmd matrix ?chan?
+

A report command which can be used by the matrix methods +format 2string and format 2chan. For the latter this +command delegates the work to ::csv::writematrix. cmd is +expected to be either printmatrix or +printmatrix2channel. The channel argument, chan, has +to be present for the latter and must not be present for the first.

+
::csv::split ?-alternate? line ?sepChar? ?delChar?
+

converts a line in CSV format into a list of the values +contained in the line. The character used to separate the values from +each other can be defined by the caller, via sepChar, but this +is optional. The default is ",". The quoting character can be defined +by the caller, but this is optional. The default is '"'.

+

If the option -alternate is specified a slightly different +syntax is used to parse the input. This syntax is explained below, in +the section FORMAT.

+
::csv::split2matrix ?-alternate? m line {sepChar ,} {expand none}
+

The same as ::csv::split, but appends the resulting list as a +new row to the matrix m, using the method add row. The +expansion mode specified via expand determines how the command +handles a matrix with less columns than contained in line. The +allowed modes are:

+
+
none
+

This is the default mode. In this mode it is the responsibility of the +caller to ensure that the matrix has enough columns to contain the +full line. If there are not enough columns the list of values is +silently truncated at the end to fit.

+
empty
+

In this mode the command expands an empty matrix to hold all columns +of the specified line, but goes no further. The overall effect is that +the first of a series of lines determines the number of columns in the +matrix and all following lines are truncated to that size, as if mode +none was set.

+
auto
+

In this mode the command expands the matrix as needed to hold all +columns contained in line. The overall effect is that after +adding a series of lines the matrix will have enough columns to hold +all columns of the longest line encountered so far.

+
+
::csv::split2queue ?-alternate? q line {sepChar ,}
+

The same as ::csv::split, but appending the resulting list as a +single item to the queue q, using the method put.

+
::csv::writematrix m chan ?sepChar? ?delChar?
+

A wrapper around ::csv::join taking all rows in the matrix +m and writing them CSV formatted into the channel chan.

+
::csv::writequeue q chan ?sepChar? ?delChar?
+

A wrapper around ::csv::join taking all items in the queue +q (assumes that they are lists) and writing them CSV formatted +into the channel chan.

+
+
+

FORMAT

+

The format of regular CSV files is specified as

+
    +

  1. Each record of a csv file (comma-separated values, as exported e.g. by +Excel) is a set of ASCII values separated by ",". For other languages +it may be ";" however, although this is not important for this case as +the functions provided here allow any separator character.

    2. +

  2. If and only if a value contains itself the separator ",", then it (the +value) has to be put between "". If the value does not contain the +separator character then quoting is optional.

    3. +

  3. If a value contains the character ", that character is represented by "".

    4. +

  4. The output string "" represents the value ". In other words, it is +assumed that it was created through rule 3, and only this rule, +i.e. that the value was not quoted.

    5. +
+

An alternate format definition mainly used by MS products specifies +that the output string "" is a representation of the empty +string. In other words, it is assumed that the output was generated +out of the empty string by quoting it (i.e. rule 2), and not through +rule 3. This is the only difference between the regular and the +alternate format.

+

The alternate format is activated through specification of the option +-alternate to the various split commands.

+
+

EXAMPLE

+

Using the regular format the record

+
+123,"123,521.2","Mary says ""Hello, I am Mary""",""
+
+

is parsed into the items

+
+a) 123
+b) 123,521.2
+c) Mary says "Hello, I am Mary"
+d) "
+
+

Using the alternate format the result is

+
+a) 123
+b) 123,521.2
+c) Mary says "Hello, I am Mary"
+d) (the empty string)
+
+

instead. As can be seen only item (d) is different, now the empty string +instead of a ".

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category csv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/debug/debug.html Index: embedded/www/tcllib/files/modules/debug/debug.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug.html +++ embedded/www/tcllib/files/modules/debug/debug.html @@ -0,0 +1,300 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

debug(n) 1.0.6 tcllib "debug narrative"

+

Name

+

debug - debug narrative - core

+
+ + +

Description

+

Debugging areas of interest are represented by 'tags' which have +independently settable levels of interest (an integer, higher is more +detailed).

+
+

API

+
+
debug.tag message ?level?
+

For each known tag the package creates a command with this signature +the user can then use to provide the debug narrative of the tag. +The narrative message is provided as a Tcl script whose value is +substed in the caller's scope if and only if the current level of +interest for the tag matches or exceeds the call's level +of detail. This is useful, as one can place arbitrarily complex +narrative in code without unnecessarily evaluating it.

+

See methods level and setting for querying +and manipulating the current level of detail for tags.

+

The actually printed text consists of not only the +message, but also global and tag-specific prefix and suffix, +should they exist, with each line in the message having the specified +headers and trailers.

+

All these parts are substableTcl scripts, which are +substituted once per message before assembly.

+
debug 2array
+

This method returns a dictionary mapping the names of all debug tags +currently known to the package to their state and log level. The +latter are encoded in a single numeric value, where a negative number +indicates an inactive tag at the level given by the absolute value, and +a positive number is an active tag at that level.

+

See also method settings below.

+
debug define tag
+

This method registers the named tag with the package. If the +tag was not known before it is placed in an inactive state. The state +of an already known tag is left untouched.

+

The result of the method is the empty string.

+
debug header text
+

This method defines a global substable Tcl script which provides +a text printed before each line of output.

+

Note how this is tag-independent.

+

Further note that the header substitution happens only once per +actual printed message, i.e. all lines of the same message will have +the same actual heading text.

+

The result of the method is the specified text.

+
debug level tag ?level? ?fd?
+

This method sets the detail-level for the tag, and the +channel fd to write the tags narration into. +The level is an integer value >= 0 defaulting to 1. +The channel defaults to stderr.

+

The result of the method is the new detail-level for the tag.

+
debug names
+

This method returns a list containing the names of all debug tags +currently known to the package.

+
debug off tag
+

This method registers the named tag with the package and sets it +inactive.

+

The result of the method is the empty string.

+
debug on tag
+

This method registers the named tag with the package, as active.

+

The result of the method is the empty string.

+
debug parray arrayvarname
+

This is a convenience method formatting the named array like the +builtin command parray, except it returns the resulting string +instead of writing it directly to stdout.

+

This makes it suitable for use in debug messages.

+
debug pdict dict
+

This is a convenience method formatting the dictionary similarly to +how the builtin command parray does for array, and returns the +resulting string.

+

This makes it suitable for use in debug messages.

+
debug hexl data ?prefix?
+

This is a convenience method formatting arbitrary data into a hex-dump +and returns the resulting string.

+

This makes it suitable for use in debug messages.

+

Each line of the dump is prefixed with prefix. This prefix +defaults to the empty string.

+
debug nl
+

This is a convenience method to insert a linefeed character (ASCII 0x0a) +into a debug message.

+
debug tab
+

This is a convenience method to insert a TAB character (ASCII 0x09) +into a debug message.

+
debug prefix tag ?text?
+

This method is similar to the method header above, in that it +defines substable Tcl script which provides more text for debug +messages.

+

In contrast to header the generated text is added to the +user's message before it is split into lines, making it a per-message +extension.

+

Furthermore the script is tag-dependent.

+

In exception to that, a script for tag :: is applied +to all messages.

+

If both global and tag-dependent prefix exist, both are +applied, with the global prefix coming before the tag-dependent +prefix.

+

Note that the prefix substitution happens only once per +actual printed message.

+

The result of the method is the empty string.

+

If the tag was not known at the time of the call it is +registered, and set inactive.

+
debug setting (tag level) ... ?fd?
+

This method is a multi-tag variant of method level above, +with the functionality of methods on, and off also +folded in.

+

Each named tag is set to the detail-level following +it, with a negative level deactivating the tag, and a positive level +activating it.

+

If the last argument is not followed by a level it is not +treated as tag name, but as the channel all the named tags should +print their messages to.

+

The result of the method is the empty string.

+
debug suffix tag ?text?
+

This method is similar to the method trailer below, in that +it defines substable Tcl script which provides more text for +debug messages.

+

In contrast to trailer the generated text is added to +the user's message before it is split into lines, making it a +per-message extension.

+

Furthermore the script is tag-dependent.

+

In exception to that, a script for tag :: is applied +to all messages.

+

If both global and tag-dependent suffix exist, both are +applied, with the global suffix coming after the tag-dependent suffix.

+

Note that the suffix substitution happens only once per actual +printed message.

+

The result of the method is the empty string.

+

If the tag was not known at the time of the call it is +registered, and set inactive.

+
debug trailer text
+

This method defines a global substable Tcl script which provides +a text printed after each line of output (before the EOL however).

+

Note how this is tag-independent.

+

Further note that the trailer substitution happens only once +per actual printed message, i.e. all lines of the same message will +have the same actual trailing text.

+

The result of the method is the specified text.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category debug of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

debugging, tracing, and logging

+
+ +
ADDED embedded/www/tcllib/files/modules/debug/debug_caller.html Index: embedded/www/tcllib/files/modules/debug/debug_caller.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_caller.html +++ embedded/www/tcllib/files/modules/debug/debug_caller.html @@ -0,0 +1,166 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

debug::caller(n) 1.1 tcllib "debug narrative"

+

Name

+

debug::caller - debug narrative - caller

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require debug::caller ?1.1?
    • +
+
    +
  • debug caller ?args...?
    • +
+
+
+ +

API

+
+
debug caller ?args...?
+

This method is useful in a tag-specific prefix to automatically +provide caller information for all uses of the tag. Or in a message, +when only specific places need such detail.

+

Beyond that it recognizing the various internal forms of method +calls generated by the snit OO system and rewrites these to +their original form, for better readability. +Similarly for TclOO.

+

If args are specified then they are treated as the +integer indices of command arguments to not show in the +output. The referenced arguments are replaced by * instead. +The main anticipiated use case for this is the exclusion of arguments +expected to contain large Tcl values, i.e. long lists, large +dictionaries, etc. to prevent them from overwhelming the narrative.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category debug of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

debugging, tracing, and logging

+
+ +
ADDED embedded/www/tcllib/files/modules/debug/debug_heartbeat.html Index: embedded/www/tcllib/files/modules/debug/debug_heartbeat.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_heartbeat.html +++ embedded/www/tcllib/files/modules/debug/debug_heartbeat.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

debug::heartbeat(n) 1 tcllib "debug narrative"

+

Name

+

debug::heartbeat - debug narrative - heartbeat

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require debug::heartbeat ?1?
    • +
  • package require debug ?1?
    • +
+
    +
  • debug heartbeat ?delta?
    • +
+
+
+ +

API

+
+
debug heartbeat ?delta?
+

This method activates or disables a heartbeat with which to monitor +the event loop of an event-based Tcl application.

+

It reserves the debug tag heartbeat for its operation +and writes a message every delta milliseconds.

+

A delta-value <= 0 disables the heartbeat.

+

The message produced by the heartbeat contains a sequence +counter and the time in milliseconds since the last beat, thus +providing insight into timing variationsn and deviations from the +nominal delta.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category debug of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

debugging, tracing, and logging

+
+ +
ADDED embedded/www/tcllib/files/modules/debug/debug_timestamp.html Index: embedded/www/tcllib/files/modules/debug/debug_timestamp.html ================================================================== --- embedded/www/tcllib/files/modules/debug/debug_timestamp.html +++ embedded/www/tcllib/files/modules/debug/debug_timestamp.html @@ -0,0 +1,159 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

debug::timestamp(n) 1 tcllib "debug narrative"

+

Name

+

debug::timestamp - debug narrative - timestamping

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require debug::timestamp ?1?
    • +
  • package require debug ?1?
    • +
+ +
+
+ +

API

+
+
debug timestamp
+

This method returns millisecond timing information since a baseline or +last call, making it useful in a tag-specific prefix to automatically +provide caller information for all uses of the tag. Or in a message, +when only specific places need such detail.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category debug of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

debugging, tracing, and logging

+
+ +
ADDED embedded/www/tcllib/files/modules/des/des.html Index: embedded/www/tcllib/files/modules/des/des.html ================================================================== --- embedded/www/tcllib/files/modules/des/des.html +++ embedded/www/tcllib/files/modules/des/des.html @@ -0,0 +1,286 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

des(n) 1.1 tcllib "Data Encryption Standard (DES)"

+

Name

+

des - Implementation of the DES and triple-DES ciphers

+
+ + +

Description

+

This is an implementation in Tcl of the Data Encryption Standard (DES) +as published by the U.S. National Institute of Standards and +Technology (NIST) [1]. This implementation also supports triple +DES (3DES) extension to DES. DES is a 64-bit block cipher that uses a +56-bit key. 3DES uses a 168-bit key. DES has now officially been +superceeded by AES but is in common use in many protocols.

+

The tcllib implementation of DES and 3DES uses an implementation by +Mac Cody and is available as a separate download from [2]. For +anyone concerned about the details of exporting this code please see +the TclDES web pages. The tcllib specific code is a wrapper to the +TclDES API that presents same API for the DES cipher as for other +ciphers in the library.

+
+

COMMANDS

+
+
::DES::des ?-mode [ecb|cbc|cfb|ofb]? ?-dir [encrypt|decrypt]? -key keydata ?-iv vector? ?-hex? ?-weak? ?-out channel? ?-chunksize size? [ -in channel | data ]
+

Perform the DES algorithm on either the data provided +by the argument or on the data read from the -in channel. If +an -out channel is given then the result will be written to +this channel.

+

The -key option must be given. This parameter takes a binary +string of 8 bytes in length and is used to generate the key schedule. +In DES only 56 bits of key data are used. The highest bit from each +byte is discarded.

+

The -mode and -dir options are optional and default to cbc +mode and encrypt respectively. The initialization vector -iv +takes an 8 byte binary argument. This defaults to all zeros. See +MODES OF OPERATION for more about -mode and the use +of the initialization vector.

+

DES is a 64-bit block cipher. This means that the data must be +provided in units that are a multiple of 8 bytes.

+
+
+

PROGRAMMING INTERFACE

+

Internal state is maintained in an opaque structure that is returned +from the Init function. In ECB mode the state is not affected by +the input but for other modes some input dependent state is maintained +and may be reset by calling the Reset function with a new +initialization vector value.

+
+
::DES::Init mode keydata iv ?weak?
+

Construct a new DES key schedule using the specified key data and the +given initialization vector. The initialization vector is not used +with ECB mode but is important for other usage modes. +See MODES OF OPERATION.

+

There are a small number of keys that are known to be weak when used +with DES. By default if such a key is passed in then an error will be +raised. If there is a need to accept such keys then the weak +parameter can be set true to avoid the error being thrown.

+
::DES::Encrypt Key data
+

Use a prepared key acquired by calling Init to encrypt the +provided data. The data argument should be a binary array that is a +multiple of the DES block size of 8 bytes. The result is a binary +array the same size as the input of encrypted data.

+
::DES::Decrypt Key data
+

Decipher data using the key. Note that the same key may be used to +encrypt and decrypt data provided that the initialization vector is +reset appropriately for CBC mode.

+
::DES::Reset Key iv
+

Reset the initialization vector. This permits the programmer to re-use +a key and avoid the cost of re-generating the key schedule where the +same key data is being used multiple times.

+
::DES::Final Key
+

This should be called to clean up resources associated with Key. +Once this function has been called the key may not be used again.

+
+
+

MODES OF OPERATION

+
+
Electronic Code Book (ECB)
+

ECB is the basic mode of all block ciphers. Each block is encrypted +independently and so identical plain text will produce identical +output when encrypted with the same key. Any encryption errors will +only affect a single block however this is vulnerable to known +plaintext attacks.

+
Cipher Block Chaining (CBC)
+

CBC mode uses the output of the last block encryption to affect the +current block. An initialization vector of the same size as the cipher +block size is used to handle the first block. The initialization +vector should be chosen randomly and transmitted as the first block of +the output. Errors in encryption affect the current block and the next +block after which the cipher will correct itself. CBC is the most +commonly used mode in software encryption.

+
Cipher Feedback (CFB)
+

CFB mode can be used to convert block ciphers into stream ciphers. In +CFB mode the initialization vector is encrypted and the output is then +xor'd with the plaintext stream. The result is then used as the +initialization vector for the next round. Errors will affect the +current block and the next block.

+
Output Feedback (OFB)
+

OFB is similar to CFB except that the output of the cipher is fed back +into the next round and not the xor'd plain text. This means that +errors only affect a single block but the cipher is more vulnerable to +attack.

+
+
+

EXAMPLES

+
+% set ciphertext [DES::des -mode cbc -dir encrypt -key $secret $plaintext]
+% set plaintext [DES::des -mode cbc -dir decrypt -key $secret $ciphertext]
+
+
+set iv [string repeat \\0 8]
+set Key [DES::Init cbc \\0\\1\\2\\3\\4\\5\\6\\7 $iv]
+set ciphertext [DES::Encrypt $Key "somedata"]
+append ciphertext [DES::Encrypt $Key "moredata"]
+DES::Reset $Key $iv
+set plaintext [DES::Decrypt $Key $ciphertext]
+DES::Final $Key
+
+
+

REFERENCES

+
    +

  1. "Data Encryption Standard", + Federal Information Processing Standards Publication 46-3, 1999, + (http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf)

    2. +

  2. "TclDES: munitions-grade Tcl scripting" + http://tcldes.sourceforge.net/

    3. +
+
+

AUTHORS

+

Jochen C Loewer, +Mac Cody, +Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category des of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/des/tcldes.html Index: embedded/www/tcllib/files/modules/des/tcldes.html ================================================================== --- embedded/www/tcllib/files/modules/des/tcldes.html +++ embedded/www/tcllib/files/modules/des/tcldes.html @@ -0,0 +1,150 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tclDES(n) 1.1 tcllib "Data Encryption Standard (DES)"

+

Name

+

tclDES - Implementation of the DES and triple-DES ciphers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require tclDES 1.1
    • +
+
+
+

Description

+

The tclDES package is a helper package for des.

+

Please see the documentation of des for details.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category des of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/des/tcldesjr.html Index: embedded/www/tcllib/files/modules/des/tcldesjr.html ================================================================== --- embedded/www/tcllib/files/modules/des/tcldesjr.html +++ embedded/www/tcllib/files/modules/des/tcldesjr.html @@ -0,0 +1,150 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tclDESjr(n) 1.1 tcllib "Data Encryption Standard (DES)"

+

Name

+

tclDESjr - Implementation of the DES and triple-DES ciphers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require tclDESjr 1.1
    • +
+
+
+

Description

+

The tclDESjr package is a helper package for des.

+

Please see the documentation of des for details.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category des of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/dicttool/dicttool.html Index: embedded/www/tcllib/files/modules/dicttool/dicttool.html ================================================================== --- embedded/www/tcllib/files/modules/dicttool/dicttool.html +++ embedded/www/tcllib/files/modules/dicttool/dicttool.html @@ -0,0 +1,198 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

dicttool(n) 1.0 tcllib "Extensions to the standard "dict" command"

+

Name

+

dicttool - Dictionary Tools

+
+ + +

Description

+

The dicttool package enhances the standard dict command with several new +commands. In addition, the package also defines several "creature comfort" list commands as well. +Each command checks to see if a command already exists of the same name before adding itself, +just in case any of these slip into the core.

+
+
ladd varname args
+

This command will add a new instance of each element in args to varname, but only if that element +is not already present.

+
ldelete varname args
+

This command will add a delete all instances of each element in args from varname.

+
dict getnull args
+

Operates like dict get, however if the key args does not exist, it returns an empty +list instead of throwing an error.

+
dict print dict
+

This command will produce a string representation of dict, with each nested branch on +a newline, and indented with two spaces for every level.

+
dict is_dict value
+

This command will return true if value can be interpreted as a dict. The command operates in +such a way as to not force an existing dict representation to shimmer into another internal rep.

+
rmerge args
+

Return a dict which is the product of a recursive merge of all of the arguments. Unlike dict merge, +this command descends into all of the levels of a dict. Dict keys which end in a : indicate a leaf, which +will be interpreted as a literal value, and not descended into further.

+
+set items [dict merge {
+  option {color {default: green}}
+} {
+  option {fruit {default: mango}}
+} {
+  option {color {default: blue} fruit {widget: select values: {mango apple cherry grape}}}
+}]
+puts [dict print $items]
+
+

Prints the following result:

+
+option {
+  color {
+    default: blue
+  }
+  fruit {
+    widget: select
+    values: {mango apple cherry grape}
+  }
+}
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category dict of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Utilites

+
+ +
ADDED embedded/www/tcllib/files/modules/dns/tcllib_dns.html Index: embedded/www/tcllib/files/modules/dns/tcllib_dns.html ================================================================== --- embedded/www/tcllib/files/modules/dns/tcllib_dns.html +++ embedded/www/tcllib/files/modules/dns/tcllib_dns.html @@ -0,0 +1,327 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

dns(n) 1.3.5 tcllib "Domain Name Service"

+

Name

+

dns - Tcl Domain Name Service Client

+
+ + +

Description

+

The dns package provides a Tcl only Domain Name Service client. You +should refer to (1) and (2) for information about the DNS protocol or +read resolver(3) to find out how the C library resolves domain names. +The intention of this package is to insulate Tcl scripts +from problems with using the system library resolver for slow name servers. +It may or may not be of practical use. Internet name resolution is a +complex business and DNS is only one part of the resolver. You may +find you are supposed to be using hosts files, NIS or WINS to name a +few other systems. This package is not a substitute for the C library +resolver - it does however implement name resolution over DNS. +The package also extends the package uri to support DNS URIs +(4) of the form dns:what.host.com or +dns://my.nameserver/what.host.com. The dns::resolve +command can handle DNS URIs or simple domain names as a query.

+

Note: The package defaults to using DNS over TCP +connections. If you wish to use UDP you will need to have the +tcludp package installed and have a version that +correctly handles binary data (> 1.0.4). +This is available at http://tcludp.sourceforge.net/. +If the udp package is present then UDP will be used by default.

+
+

COMMANDS

+
+
::dns::resolve query ?options?
+

Resolve a domain name using the DNS protocol. query is +the domain name to be lookup up. This should be either a fully +qualified domain name or a DNS URI.

+
+
-nameserver hostname or -server hostname
+

Specify an alternative name server for this request.

+
-protocol tcp|udp
+

Specify the network protocol to use for this request. Can be one of + tcp or udp.

+
-port portnum
+

Specify an alternative port.

+
-search domainlist
+
+
-timeout milliseconds
+

Override the default timeout.

+
-type TYPE
+

Specify the type of DNS record you are interested in. Valid values + are A, NS, MD, MF, CNAME, SOA, MB, MG, MR, NULL, WKS, PTR, HINFO, + MINFO, MX, TXT, SPF, SRV, AAAA, AXFR, MAILB, MAILA and *. + See RFC1035 for details about the return values. + See http://spf.pobox.com/ about SPF. + See (3) about AAAA records and RFC2782 for details of SRV records.

+
-class CLASS
+

Specify the class of domain name. This is usually IN but may be one + of IN for internet domain names, CS, CH, HS or * for any class.

+
-recurse boolean
+

Set to false if you do not want the name server to recursively + act upon your request. Normally set to true.

+
-command procname
+

Set a procedure to be called upon request completion. The procedure + will be passed the token as its only argument.

+
+
::dns::configure ?options?
+

The ::dns::configure command is used to setup the dns +package. The server to query, the protocol and domain search path are +all set via this command. If no arguments are provided then a list of +all the current settings is returned. If only one argument then it +must the the name of an option and the value for that option is +returned.

+
+
-nameserver hostname
+

Set the default name server to be used by all queries. The default is + localhost.

+
-protocol tcp|udp
+

Set the default network protocol to be used. Default is tcp.

+
-port portnum
+

Set the default port to use on the name server. The default is 53.

+
-search domainlist
+

Set the domain search list. This is currently not used.

+
-timeout milliseconds
+

Set the default timeout value for DNS lookups. Default is 30 seconds.

+
-loglevel level
+

Set the log level used for emitting diagnostic messages from this + package. The default is warn. See the log package + for details of the available levels.

+
+
::dns::name token
+

Returns a list of all domain names returned as an answer to your query.

+
::dns::address token
+

Returns a list of the address records that match your query.

+
::dns::cname token
+

Returns a list of canonical names (usually just one) matching your query.

+
::dns::result token
+

Returns a list of all the decoded answer records provided for your + query. This permits you to extract the result for more unusual query types.

+
::dns::status token
+

Returns the status flag. For a successfully completed query this will be + ok. May be error or timeout or eof. + See also ::dns::error

+
::dns::error token
+

Returns the error message provided for requests whose status is error. + If there is no error message then an empty string is returned.

+
::dns::reset token
+

Reset or cancel a DNS query.

+
::dns::wait token
+

Wait for a DNS query to complete and return the status upon completion.

+
::dns::cleanup token
+

Remove all state variables associated with the request.

+
::dns::nameservers
+

Attempts to return a list of the nameservers currently configured +for the users system. On a unix machine this parses the +/etc/resolv.conf file for nameservers (if it exists) and on Windows +systems we examine certain parts of the registry. If no nameserver can +be found then the loopback address (127.0.0.1) is used as a default.

+
+
+

EXAMPLES

+
+% set tok [dns::resolve www.tcl.tk]
+::dns::1
+% dns::status $tok
+ok
+% dns::address $tok
+199.175.6.239
+% dns::name $tok
+www.tcl.tk
+% dns::cleanup $tok
+
+

Using DNS URIs as queries:

+
+% set tok [dns::resolve "dns:tcl.tk;type=MX"]
+% set tok [dns::resolve "dns://l.root-servers.net/www.tcl.tk"]
+
+

Reverse address lookup:

+
+% set tok [dns::resolve 127.0.0.1]
+::dns::1
+% dns::name $tok
+localhost
+% dns::cleanup $tok
+
+
+

REFERENCES

+
    +

  1. Mockapetris, P., "Domain Names - Concepts and Facilities", + RFC 1034, November 1987. + (http://www.ietf.org/rfc/rfc1034.txt)

    2. +

  2. Mockapetris, P., "Domain Names - Implementation and Specification", + RFC 1035, November 1087. + (http://www.ietf.org/rfc/rfc1035.txt)

    3. +

  3. Thompson, S. and Huitema, C., "DNS Extensions to support IP version 6", + RFC 1886, December 1995. + (http://www.ietf.org/rfc/rfc1886.txt)

    4. +

  4. Josefsson, S., "Domain Name System Uniform Resource Identifiers", + Internet-Draft, October 2003, + (http://www.ietf.org/internet-drafts/draft-josefsson-dns-url-09.txt)

    5. +

  5. Gulbrandsen, A., Vixie, P. and Esibov, L., + "A DNS RR for specifying the location of services (DNS SRV)", + RFC 2782, February 2000, + (http://www.ietf.org/rfc/rfc2782.txt)

    6. +

  6. Ohta, M. "Incremental Zone Transfer in DNS", + RFC 1995, August 1996, + (http://www.ietf.org/rfc/rfc1995.txt)

    7. +
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category dns of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

resolver(5)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/dns/tcllib_ip.html Index: embedded/www/tcllib/files/modules/dns/tcllib_ip.html ================================================================== --- embedded/www/tcllib/files/modules/dns/tcllib_ip.html +++ embedded/www/tcllib/files/modules/dns/tcllib_ip.html @@ -0,0 +1,472 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcllib_ip(n) 1.4 tcllib "Domain Name Service"

+

Name

+

tcllib_ip - IPv4 and IPv6 address manipulation

+
+ + +

Description

+

This package provides a set of commands to help in parsing, displaying +and comparing internet addresses. The package can handle both IPv4 (1) +and IPv6 (2) address types.

+
+

COMMANDS

+
+
::ip::version address
+

Returns the protocol version of the address (4 or 6) or 0 if the +address is neither IPv4 or IPv6.

+
::ip::is class address
+

Returns true if the address is a member of the given protocol +class. The class parameter may be either ipv4 or ipv6 +This is effectively a boolean equivalent of the version +command. The class argument may be shortened to 4 or +6.

+
::ip::equal address address
+

Compare two address specifications for equivalence. The arguments are +normalized and the address prefix determined (if a mask is +supplied). The normalized addresses are then compared bit-by-bit and +the procedure returns true if they match.

+
::ip::normalize address
+

Convert an IPv4 or IPv6 address into a fully expanded version. There +are various shorthand ways to write internet addresses, missing out +redundant parts or digits. This procedure is the opposite of +contract.

+
::ip::contract address
+

Convert a normalized internet address into a more compact form +suitable for displaying to users.

+
::ip::distance ipaddr1 ipaddr2
+

This command computes the (integer) distance from IPv4 address +ipaddr1 to IPv4 address ipaddr2, i.e. "ipaddr2 - ipaddr1"

+
+   % ::ip::distance 1.1.1.1  1.1.1.5
+   4
+
+
+
::ip::nextIp ipaddr ?offset?
+

This command adds the integer offset to the IPv4 address ipaddr +and returns the new IPv4 address.

+
+   % ::ip::distance 1.1.1.1  4
+   1.1.1.5
+
+
+
::ip::prefix address
+

Returns the address prefix generated by masking the address part with +the mask if provided. If there is no mask then it is equivalent to +calling normalize

+
::ip::type address
+
+
::ip::mask address
+

If the address supplied includes a mask then this is returned +otherwise returns an empty string.

+
::ip::prefixToNative prefix
+

This command converts the string prefix from dotted form +(<ipaddr>/<mask> format) to native (hex) form. Returns a list +containing two elements, ipaddress and mask, in this order, in +hexadecimal notation.

+
+   % ip::prefixToNative 1.1.1.0/24
+   0x01010100 0xffffff00
+
+
+
::ip::nativeToPrefix nativeList|native ?-ipv4?
+

This command converts from native (hex) form to dotted form. +It is the complement of ::ip::prefixToNative.

+
+
list nativeList (in)
+

List of several ip addresses in native form. The native form is a list +as returned by ::ip::prefixToNative.

+
list native (in)
+

A list as returned by ::ip::prefixToNative.

+
+

The command returns a list of addresses in dotted form if it was +called with a list of addresses. Otherwise a single address in dotted +form is returned.

+
+   % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
+   1.1.1.0/24
+
+
+
::ip::intToString number ?-ipv4?
+

This command converts from an ip address specified as integer number +to dotted form.

+
+       ip::intToString 4294967295
+       255.255.255.255
+
+
+
::ip::toInteger ipaddr
+

This command converts a dotted form ip into an integer number.

+
+   % ::ip::toInteger 1.1.1.0
+   16843008
+
+
+
::ip::toHex ipaddr
+

This command converts dotted form ip into a hexadecimal number.

+
+   % ::ip::toHex 1.1.1.0
+   0x01010100
+
+
+
::ip::maskToInt ipmask
+

This command convert an ipmask in either dotted (255.255.255.0) form +or mask length form (24) into an integer number.

+
+   ::ip::maskToInt 24
+   4294967040
+
+
+
::ip::broadcastAddress prefix ?-ipv4?
+

This commands returns a broadcast address in dotted form for the given +route prefix, either in the form "addr/mask", or in native +form. The result is in dotted form.

+
+   ::ip::broadcastAddress 1.1.1.0/24
+   1.1.1.255
+   ::ip::broadcastAddress {0x01010100 0xffffff00}
+   0x010101ff
+
+
+
::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
+

This command converts the dotted or integer form of an ipmask to +the mask length form.

+
+   ::ip::maskToLength 0xffffff00 -ipv4
+   24
+   % ::ip::maskToLength 255.255.255.0
+   24
+
+
+
::ip::lengthToMask maskLength ?-ipv4?
+

This command converts an ipmask in mask length form to its dotted +form.

+
+   ::ip::lengthToMask 24
+   255.255.255.0
+
+
+
::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
+

This command returns an ipaddress in the same position in the +count next network. The default value for count is +1.

+

The address can be specified as either integer number or in dotted +form. The mask can be specified as either integer number, dotted form, +or mask length form.

+

The result is in hex form.

+
::ip::isOverlap prefix prefix...
+

This command checks if the given ip prefixes overlap. All arguments +are in dotted "addr/mask" form. All arguments after the first prefix +are compared against the first prefix. The result is a boolean +value. It is true if an overlap was found for any of the prefixes.

+
+  % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
+  0
+  ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
+  1
+
+
+
::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hexiplist
+

This command is similar to ::ip::isOverlap, however the +arguments are in the native form, and the form of the result is under +greater control of the caller. +If the option -all is specified it checks all addresses for +overlap, not only until the first one is found. +If the option -inline is specified the command returns the +overlapping prefix instead of index values.

+

The result of the command is, depending on the specified options,

+
+
no options
+

The index of the first overlap found, or 0 if there is none.

+
-all
+

A list containing the indices of all overlaps found, or an empty list +if there are none.

+
-inline
+

The first overlapping prefix, or an empoty string if there is none.

+
-all -inline
+

A list containing the prefixes of all overlaps found, or an empty list +if there are none.

+
+
+  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
+  0
+  % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
+  2
+
+
+
::ip::ipToLayer2Multicast ipaddr
+

This command an converts ipv4 address in dotted form into a layer 2 +multicast address, also in dotted form.

+
+  % ::ip::ipToLayer2Multicast 224.0.0.2
+  01.00.5e.00.00.02
+
+
+
::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
+

This command returns a host address from a prefix in the form +"ipaddr/masklen", also making sure that the result is not an address +found in the prefixExcludeList. +The result is an ip address in dotted form.

+
+  %::ip::ipHostFromPrefix  1.1.1.5/24
+  1.1.1.1
+  %::ip::ipHostFromPrefix  1.1.1.1/32
+  1.1.1.1
+
+
+
::ip::reduceToAggregates prefixlist
+

This command finds nets that overlap and filters out the more specific +nets. The prefixes are in either addr/mask form or in native format. +The result is a list containing the non-overlapping ip prefixes from +the input.

+
+  % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8  2.1.1.0/24 1.1.1.1/32 }
+  1.0.0.0/8 2.1.1.0/24
+
+
+
::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
+

This command finds longest prefix match from set of prefixes, given a +specific host address. The prefixes in the list are in either native +or dotted form, whereas the host address is in either ipprefix format, +dotted form, or integer form. +The result is the prefix which is the most specific match to the host +address.

+
+  % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8  2.1.1.0/24 1.1.1.0/28 }
+  1.1.1.0/28
+
+
+
::ip::collapse prefixlist
+

This commands takes a list of prefixes and returns a list prefixes +with the largest possible subnet masks covering the input, in this +manner collapsing adjacent prefixes into larger ranges.

+

This is different from ::ip::reduceToAggregates in that +the latter only removes specific nets from a list when they are +covered by other elements of the input whereas this command actively +merges nets into larger ranges when they are adjacent to each other.

+
+% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
+1.2.2.0/23
+
+
+
::ip::subtract prefixlist
+

This command takes a list of prefixes, some of which are prefixed by a +dash. These latter negative prefixes are used to punch holes +into the ranges described by the other, positive, +prefixes. I.e. the negative prefixes are subtracted frrom the positive +ones, resulting in a larger list of describes describing the covered +ranges only as positives.

+
+
+

EXAMPLES

+
+% ip::version ::1
+6
+% ip::version 127.0.0.1
+4
+
+
+% ip::normalize 127/8
+127.0.0.0/8
+% ip::contract 192.168.0.0
+192.168
+%
+% ip::normalize fec0::1
+fec0:0000:0000:0000:0000:0000:0000:0001
+% ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
+fec0::1
+
+
+% ip::equal 192.168.0.4/16 192.168.0.0/16
+1
+% ip::equal fec0::1/10 fec0::fe01/10
+1
+
+
+

REFERENCES

+
    +

  1. Postel, J. "Internet Protocol." RFC 791, September 1981, + (http://www.ietf.org/rfc/rfc791.txt)

    2. +

  2. Hinden, R. and Deering, S., + "Internet Protocol Version 6 (IPv6) Addressing Architecture", + RFC 3513, April 2003 + (http://www.ietf.org/rfc/rfc3513.txt)

    3. +
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category dns of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

inet(3), ip(7), ipv6(7)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/docstrip/docstrip.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip.html ================================================================== --- embedded/www/tcllib/files/modules/docstrip/docstrip.html +++ embedded/www/tcllib/files/modules/docstrip/docstrip.html @@ -0,0 +1,518 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docstrip(n) 1.2 tcllib "Literate programming tool"

+

Name

+

docstrip - Docstrip style source code extraction

+
+ + +

Description

+

Docstrip is a tool created to support a brand of Literate +Programming. It is most common in the (La)TeX community, where it +is being used for pretty much everything from the LaTeX core and up, +but there is nothing about docstrip which prevents using it +for other types of software.

+

In short, the basic principle of literate programming is that program +source should primarily be written and structured to suit the +developers (and advanced users who want to peek "under the hood"), not +to suit the whims of a compiler or corresponding source code consumer. +This means literate sources often need some kind of "translation" to an +illiterate form that dumb software can understand. +The docstrip Tcl package handles this translation.

+

Even for those who do not whole-hartedly subscribe to the philosophy +behind literate programming, docstrip can bring greater +clarity to in particular:

+
    + +

  • programs employing non-obvious mathematics

    • +

  • projects where separate pieces of code, perhaps in + different languages, need to be closely coordinated.

    • +
+

The first is by providing access to much more powerful typographical +features for source code comments than are possible in plain text. +The second is because all the separate pieces of code can be kept +next to each other in the same source file.

+

The way it works is that the programmer edits directly only one or +several "master" source code files, from which docstrip +generates the more traditional "source" files compilers or the like +would expect. The master sources typically contain a large amount of +documentation of the code, sometimes even in places where the code +consumers would not allow any comments. The etymology of "docstrip" +is that this documentation was stripped away (although +"code extraction" might be a better description, as it has always +been a matter of copying selected pieces of the master source rather +than deleting text from it). +The docstrip Tcl package contains a reimplementation of +the basic extraction functionality from the docstrip +program, and thus makes it possible for a Tcl interpreter to read +and interpret the master source files directly.

+

Readers who are not previously familiar with docstrip but +want to know more about it may consult the following sources.

+
    +

  1. The tclldoc package and class, + http://ctan.org/tex-archive/macros/latex/contrib/tclldoc/.

    2. +

  2. The DocStrip utility, + http://ctan.org/tex-archive/macros/latex/base/docstrip.dtx.

    3. +

  3. The doc and shortvrb Packages, + http://ctan.org/tex-archive/macros/latex/base/doc.dtx.

    4. +

  4. Chapter 14 of + The LaTeX Companion (second edition), + Addison-Wesley, 2004; ISBN 0-201-36299-6.

    5. +
+
+

File format

+

The basic unit docstrip operates on are the lines of +a master source file. Extraction consists of selecting some of these +lines to be copied from input text to output text. The basic +distinction is that between code lines (which are copied and +do not begin with a percent character) and comment lines +(which begin with a percent character and are not copied).

+
+   docstrip::extract [join {
+     {% comment}
+     {% more comment !"#$%&/(}
+     {some command}
+     { % blah $blah "Not a comment."}
+     {% abc; this is comment}
+     {# def; this is code}
+     {ghi}
+     {% jkl}
+   } \n] {}
+
+

returns the same sequence of lines as

+
+   join {
+     {some command}
+     { % blah $blah "Not a comment."}
+     {# def; this is code}
+     {ghi} ""
+   } \n
+
+

It does not matter to docstrip what format is used for the +documentation in the comment lines, but in order to do better than +plain text comments, one typically uses some markup language. Most +commonly LaTeX is used, as that is a very established standard and +also provides the best support for mathematical formulae, but the +docstrip::util package also gives some support for +doctools-like markup.

+

Besides the basic code and comment lines, there are also +guard lines, which begin with the two characters '%<', and +meta-comment lines, which begin with the two characters +'%%'. Within guard lines there is furthermore the distinction between +verbatim guard lines, which begin with '%<<', and ordinary +guard lines, where the '%<' is not followed by another '<'. The last +category is by far the most common.

+

Ordinary guard lines conditions extraction of the code line(s) they +guard by the value of a boolean expression; the guarded block of +code lines will only be included if the expression evaluates to true. +The syntax of an ordinary guard line is one of

+
+    '%' '<' STARSLASH EXPRESSION '>'
+    '%' '<' PLUSMINUS EXPRESSION '>' CODE
+
+

where

+
+    STARSLASH  ::=  '*' | '/'
+    PLUSMINUS  ::=  | '+' | '-'
+    EXPRESSION ::= SECONDARY | SECONDARY ',' EXPRESSION
+                 | SECONDARY '|' EXPRESSION
+    SECONDARY  ::= PRIMARY | PRIMARY '&' SECONDARY
+    PRIMARY    ::= TERMINAL | '!' PRIMARY | '(' EXPRESSION ')'
+    CODE       ::= { any character except end-of-line }
+
+

Comma and vertical bar both denote 'or'. Ampersand denotes 'and'. +Exclamation mark denotes 'not'. A TERMINAL can be any nonempty string +of characters not containing '>', '&', '|', comma, '(', or ')', +although the docstrip manual is a bit restrictive and only +guarantees proper operation for strings of letters (although even +the LaTeX core sources make heavy use also of digits in TERMINALs). +The second argument of docstrip::extract is the list of those +TERMINALs that should count as having the value 'true'; all other +TERMINALs count as being 'false' when guard expressions are evaluated.

+

In the case of a '%<*EXPRESSION>' guard, the lines guarded are +all lines up to the next '%</EXPRESSION>' guard with the same +EXPRESSION (compared as strings). The blocks of code delimited +by such '*' and '/' guard lines must be properly nested.

+
+   set text [join {
+      {begin}
+      {%<*foo>}
+      {1}
+      {%<*bar>}
+      {2}
+      {%</bar>}
+      {%<*!bar>}
+      {3}
+      {%</!bar>}
+      {4}
+      {%</foo>}
+      {5}
+      {%<*bar>}
+      {6}
+      {%</bar>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text foo]
+   append res [docstrip::extract $text {foo bar}]
+   append res [docstrip::extract $text bar]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      {1}
+      {3}
+      {4}
+      {5}
+      {end}
+      {begin}
+      {1}
+      {2}
+      {4}
+      {5}
+      {6}
+      {end}
+      {begin}
+      {5}
+      {6}
+      {end} ""
+   } \n
+
+

In guard lines without a '*', '/', '+', or '-' modifier after the +'%<', the guard applies only to the CODE following the '>' on that +single line. A '+' modifier is equivalent to no modifier. A '-' +modifier is like the case with no modifier, but the expression is +implicitly negated, i.e., the CODE of a '%<-' guard line is only +included if the expression evaluates to false.

+

Metacomment lines are "comment lines which should not be stripped +away", but be extracted like code lines; these are sometimes used for +copyright notices and similar material. The '%%' prefix is however +not kept, but substituted by the current -metaprefix, which +is customarily set to some "comment until end of line" character (or +character sequence) of the language of the code being extracted.

+
+   set text [join {
+      {begin}
+      {%<foo> foo}
+      {%<+foo>plusfoo}
+      {%<-foo>minusfoo}
+      {middle}
+      {%% some metacomment}
+      {%<*foo>}
+      {%%another metacomment}
+      {%</foo>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text foo -metaprefix {# }]
+   append res [docstrip::extract $text bar -metaprefix {#}]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      { foo}
+      {plusfoo}
+      {middle}
+      {#  some metacomment}
+      {# another metacomment}
+      {end}
+      {begin}
+      {minusfoo}
+      {middle}
+      {# some metacomment}
+      {end} ""
+   } \n
+
+

Verbatim guards can be used to force code line +interpretation of a block of lines even if some of them happen to look +like any other type of lines to docstrip. A verbatim guard has the +form '%<<END-TAG' and the verbatim block is terminated by the +first line that is exactly '%END-TAG'.

+
+   set text [join {
+      {begin}
+      {%<*myblock>}
+      {some stupid()}
+      {   #computer<program>}
+      {%<<QQQ-98765}
+      {% These three lines are copied verbatim (including percents}
+      {%% even if -metaprefix is something different than %%).}
+      {%</myblock>}
+      {%QQQ-98765}
+      {   using*strange@programming<language>}
+      {%</myblock>}
+      {end}
+   } \n]
+   set res [docstrip::extract $text myblock -metaprefix {# }]
+   append res [docstrip::extract $text {}]
+
+

sets $res to the result of

+
+   join {
+      {begin}
+      {some stupid()}
+      {   #computer<program>}
+      {% These three lines are copied verbatim (including percents}
+      {%% even if -metaprefix is something different than %%).}
+      {%</myblock>}
+      {   using*strange@programming<language>}
+      {end}
+      {begin}
+      {end} ""
+   } \n
+
+

The processing of verbatim guards takes place also inside blocks of +lines which due to some outer block guard will not be copied.

+

The final piece of docstrip syntax is that extraction +stops at a line that is exactly "\endinput"; this is often used to +avoid copying random whitespace at the end of a file. In the unlikely +case that one wants such a code line, one can protect it with a +verbatim guard.

+
+

Commands

+

The package defines two commands.

+
+
docstrip::extract text terminals ?option value ...?
+

The extract command docstrips the text and returns the + extracted lines of code, as a string with each line terminated with + a newline. The terminals is the list of those guard + expression terminals which should evaluate to true. + The available options are:

+
+ +
-annotate lines
+

Requests the specified number of lines of annotation to follow + each extracted line in the result. Defaults to 0. Annotation lines + are mostly useful when the extracted lines are to undergo some + further transformation. A first annotation line is a list of three + elements: line type, prefix removed in extraction, and prefix + inserted in extraction. The line type is one of: 'V' (verbatim), + 'M' (metacomment), '+' (+ or no modifier guard line), '-' (- + modifier guard line), '.' (normal line). A second annotation line + is the source line number. A third annotation line is the current + stack of block guards. Requesting more than three lines of + annotation is currently not supported.

+
-metaprefix string
+

The string by which the '%%' prefix of a metacomment line will + be replaced. Defaults to '%%'. For Tcl code this would typically + be '#'.

+
-onerror keyword
+

Controls what will be done when a format error in the text + being processed is detected. The settings are:

+
+ +
ignore
+

Just ignore the error; continue as if nothing happened.

+
puts
+

Write an error message to stderr, then continue + processing.

+
throw
+

Throw an error. The -errorcode is set to a list whose + first element is DOCSTRIP, second element is the + type of error, and third element is the line number where + the error is detected. This is the default.

+
+
-trimlines boolean
+

Controls whether spaces at the end of a line should be + trimmed away before the line is processed. Defaults to true.

+
+

It should be remarked that the terminals are often called + "options" in the context of the docstrip program, since + these specify which optional code fragments should be included.

+
docstrip::sourcefrom filename terminals ?option value ...?
+

The sourcefrom command is a docstripping emulation of + source. It opens the file filename, reads it, closes it, + docstrips the contents as specified by the terminals, and + evaluates the result in the local context of the caller, during + which time the info script value will be the + filename. The options are passed on to fconfigure to + configure the file before its contents are read. The + -metaprefix is set to '#', all other extract + options have their default values.

+
+
+

Document structure

+

The file format (as described above) determines whether a master +source code file can be processed correctly by docstrip, +but the usefulness of the format is to no little part also dependent +on that the code and comment lines together constitute a well-formed +document.

+

For a document format that does not require any non-Tcl software, see +the ddt2man command in the docstrip::util package. It +is suggested that files employing that document format are given the +suffix ".ddt", to distinguish them from the more traditional +LaTeX-based ".dtx" files.

+

Master source files with ".dtx" extension are usually set up so +that they can be typeset directly by latex without any +support from other files. This is achieved by beginning the file +with the lines

+
+   % \iffalse
+   %<*driver>
+   \documentclass{tclldoc}
+   \begin{document}
+   \DocInput{filename.dtx}
+   \end{document}
+   %</driver>
+   % \fi
+
+

or some variation thereof. The trick is that the file gets read twice. +With normal LaTeX reading rules, the first two lines are comments and +therefore ignored. The third line is the document preamble, the fourth +line begins the document body, and the sixth line ends the document, +so LaTeX stops there — non-comments below that point in +the file are never subjected to the normal LaTeX reading rules. Before +that, however, the \DocInput command on the fifth line is processed, +and that does two things: it changes the interpretation of '%' from +"comment" to "ignored", and it inputs the file specified in the +argument (which is normally the name of the file the command is in). +It is this second time that the file is being read that the comments +and code in it are typeset.

+

The function of the \iffalse ... \fi is to skip lines two to seven +on this second time through; this is similar to the "if 0 { ... }" +idiom for block comments in Tcl code, and it is needed here because +(amongst other things) the \documentclass command may only be +executed once. The function of the <driver> guards is to prevent this +short piece of LaTeX code from being extracted by docstrip. +The total effect is that the file can function both as a LaTeX +document and as a docstrip master source code file.

+

It is not necessary to use the tclldoc document class, but that does +provide a number of features that are convenient for ".dtx" +files containing Tcl code. More information on this matter can be +found in the references above.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/docstrip/docstrip_util.html Index: embedded/www/tcllib/files/modules/docstrip/docstrip_util.html ================================================================== --- embedded/www/tcllib/files/modules/docstrip/docstrip_util.html +++ embedded/www/tcllib/files/modules/docstrip/docstrip_util.html @@ -0,0 +1,674 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docstrip_util(n) 1.3.1 tcllib "Literate programming tool"

+

Name

+

docstrip_util - Docstrip-related utilities

+
+ + +

Description

+

The docstrip::util package is meant for collecting various +utility procedures that are mainly useful at installation or +development time. It is separate from the base package to avoid +overhead when the latter is used to source code.

+
+

Package indexing commands

+

Like raw ".tcl" files, code lines in docstrip source files can +be searched for package declarations and corresponding indices +constructed. A complication is however that one cannot tell from the +code blocks themselves which will fit together to make a working +package; normally that information would be found in an accompanying +".ins" file, but parsing one of those is not an easy task. +Therefore docstrip::util introduces an alternative encoding +of such information, in the form of a declarative Tcl script: the +catalogue (of the contents in a source file).

+

The special commands which are available inside a catalogue are:

+
+
pkgProvide name version terminals
+

Declares that the code for a package with name name and + version version is made up from those modules in the source + file which are selected by the terminals list of guard + expression terminals. This code should preferably not contain a + package provide command for the package, as one + will be provided by the package loading mechanisms.

+
pkgIndex ?terminal ...?
+

Declares that the code for a package is made up from those modules + in the source file which are selected by the listed guard + expression terminals. The name and version of this package is + determined from package provide command(s) found + in that code (hence there must be such a command in there).

+
fileoptions ?option value ...?
+

Declares the fconfigure options that should be in force when + reading the source; this can usually be ignored for pure ASCII + files, but if the file needs to be interpreted according to some + other -encoding then this is how to specify it. The + command should normally appear first in the catalogue, as it takes + effect only for commands following it.

+
+

Other Tcl commands are supported too — a catalogue is +parsed by being evaluated in a safe interpreter — but they +are rarely needed. To allow for future extensions, unknown commands +in the catalogue are silently ignored.

+

To simplify distribution of catalogues together with their source +files, the catalogue is stored in the source file itself as +a module selected by the terminal 'docstrip.tcl::catalogue'. +This supports both the style of collecting all catalogue lines in one +place and the style of putting each catalogue line in close proximity +of the code that it declares.

+

Putting catalogue entries next to the code they declare may look as +follows

+
+%    First there's the catalogue entry
+%    \begin{tcl}
+%<docstrip.tcl::catalogue>pkgProvide foo::bar 1.0 {foobar load}
+%    \end{tcl}
+%    second a metacomment used to include a copyright message
+%    \begin{macrocode}
+%<*foobar>
+%% This file is placed in the public domain.
+%    \end{macrocode}
+%    third the package implementation
+%    \begin{tcl}
+namespace eval foo::bar {
+   # ... some clever piece of Tcl code elided ...
+%    \end{tcl}
+%    which at some point may have variant code to make use of a
+%    |load|able extension
+%    \begin{tcl}
+%<*load>
+   load [file rootname [info script]][info sharedlibextension]
+%</load>
+%<*!load>
+   # ... even more clever scripted counterpart of the extension
+   # also elided ...
+%</!load>
+}
+%</foobar>
+%    \end{tcl}
+%    and that's it!
+
+

The corresponding set-up with pkgIndex would be

+
+%    First there's the catalogue entry
+%    \begin{tcl}
+%<docstrip.tcl::catalogue>pkgIndex foobar load
+%    \end{tcl}
+%    second a metacomment used to include a copyright message
+%    \begin{tcl}
+%<*foobar>
+%% This file is placed in the public domain.
+%    \end{tcl}
+%    third the package implementation
+%    \begin{tcl}
+package provide foo::bar 1.0
+namespace eval foo::bar {
+   # ... some clever piece of Tcl code elided ...
+%    \end{tcl}
+%    which at some point may have variant code to make use of a
+%    |load|able extension
+%    \begin{tcl}
+%<*load>
+   load [file rootname [info script]][info sharedlibextension]
+%</load>
+%<*!load>
+   # ... even more clever scripted counterpart of the extension
+   # also elided ...
+%</!load>
+}
+%</foobar>
+%    \end{tcl}
+%    and that's it!
+
+
+
docstrip::util::index_from_catalogue dir pattern ?option value ...?
+

This command is a sibling of the standard pkg_mkIndex + command, in that it adds package entries to "pkgIndex.tcl" + files. The difference is that it indexes docstrip-style + source files rather than raw ".tcl" or loadable library files. + Only packages listed in the catalogue of a file are considered.

+

The dir argument is the directory in which to look for files + (and whose "pkgIndex.tcl" file should be amended). + The pattern argument is a glob pattern of files to look + into; a typical value would be *.dtx or + *.{dtx,ddt}. Remaining arguments are option-value pairs, + where the supported options are:

+
+ +
-recursein dirpattern
+

If this option is given, then the index_from_catalogue + operation will be repeated in each subdirectory whose name + matches the dirpattern. -recursein * will + cause the entire subtree rooted at dir to be indexed.

+
-sourceconf dictionary
+

Specify fileoptions to use when reading the catalogues of + files (and also for reading the packages if the catalogue does + not contain a fileoptions command). Defaults to being + empty. Primarily useful if your system encoding is very different + from that of the source file (e.g., one is a two-byte encoding + and the other is a one-byte encoding). ascii and + utf-8 are not very different in that sense.

+
-options terminals
+

The terminals is a list of terminals in addition to + docstrip.tcl::catalogue that should be held as true when + extracting the catalogue. Defaults to being empty. This makes it + possible to make use of "variant sections" in the catalogue + itself, e.g. gaurd some entries with an extra "experimental" and + thus prevent them from appearing in the index unless that is + generated with "experimental" among the -options.

+
-report boolean
+

If the boolean is true then the return value will be a + textual, probably multiline, report on what was done. Defaults + to false, in which case there is no particular return value.

+
-reportcmd commandPrefix
+

Every item in the report is handed as an extra argument to the + command prefix. Since index_from_catalogue would typically + be used at a rather high level in installation scripts and the + like, the commandPrefix defaults to + "puts stdout". + Use list to effectively disable this feature. The return + values from the prefix are ignored.

+
+

The package ifneeded scripts that are generated contain + one package require docstrip command and one + docstrip::sourcefrom command. If the catalogue entry was + of the pkgProvide kind then the package ifneeded + script also contains the package provide command.

+

Note that index_from_catalogue never removes anything from an + existing "pkgIndex.tcl" file. Hence you may need to delete it + (or have pkg_mkIndex recreate it from scratch) before running + index_from_catalogue to update some piece of information, such + as a package version number.

+
docstrip::util::modules_from_catalogue target source ?option value ...?
+

This command is an alternative to index_from_catalogue which + creates Tcl Module (".tm") files rather than + "pkgIndex.tcl" entries. Since this action is more similar to + what docstrip classically does, it has features for + putting pre- and postambles on the generated files.

+

The source argument is the name of the source file to + generate ".tm" files from. The target argument is the + directory which should count as a module path, i.e., this is what + the relative paths derived from package names are joined to. The + supported options are:

+
+ +
-preamble message
+

A message to put in the preamble (initial block of comments) of + generated files. Defaults to a space. May be several lines, which + are then separated by newlines. Traditionally used for copyright + notices or the like, but metacomment lines provide an alternative + to that.

+
-postamble message
+

Like -preamble, but the message is put at the end of the + file instead of the beginning. Defaults to being empty.

+
-sourceconf dictionary
+

Specify fileoptions to use when reading the catalogue of + the source (and also for reading the packages if the + catalogue does not contain a fileoptions command). Defaults + to being empty. Primarily useful if your system encoding is very + different from that of the source file (e.g., one is a two-byte + encoding and the other is a one-byte encoding). ascii and + utf-8 are not very different in that sense.

+
-options terminals
+

The terminals is a list of terminals in addition to + docstrip.tcl::catalogue that should be held as true when + extracting the catalogue. Defaults to being empty. This makes it + possible to make use of "variant sections" in the catalogue + itself, e.g. gaurd some entries with an extra "experimental" guard + and thus prevent them from contributing packages unless those are + generated with "experimental" among the -options.

+
-formatpreamble commandPrefix
+

Command prefix used to actually format the preamble. Takes four + additional arguments message, targetFilename, + sourceFilename, and terminalList and returns a fully + formatted preamble. Defaults to using classical_preamble + with a metaprefix of '##'.

+
-formatpostamble commandPrefix
+

Command prefix used to actually format the postamble. Takes four + additional arguments message, targetFilename, + sourceFilename, and terminalList and returns a fully + formatted postamble. Defaults to using classical_postamble + with a metaprefix of '##'.

+
-report boolean
+

If the boolean is true (which is the default) then the return + value will be a textual, probably multiline, report on what was + done. If it is false then there is no particular return value.

+
-reportcmd commandPrefix
+

Every item in the report is handed as an extra argument to this + command prefix. Defaults to list, which effectively disables + this feature. The return values from the prefix are ignored. Use + for example "puts stdout" to get report items + written immediately to the terminal.

+
+

An existing file of the same name as one to be created will be + overwritten.

+
docstrip::util::classical_preamble metaprefix message target ?source terminals ...?
+

This command returns a preamble in the classical + docstrip style

+
+##
+## This is `TARGET',
+## generated by the docstrip::util package.
+##
+## The original source files were:
+##
+## SOURCE (with options: `foo,bar')
+##
+## Some message line 1
+## line2
+## line3
+
+

if called as

+
+docstrip::util::classical_preamble {##}\
+  "\nSome message line 1\nline2\nline3" TARGET SOURCE {foo bar}
+
+

The command supports preambles for files generated from multiple + sources, even though modules_from_catalogue at present does + not need that.

+
docstrip::util::classical_postamble metaprefix message target ?source terminals ...?
+

This command returns a postamble in the classical + docstrip style

+
+## Some message line 1
+## line2
+## line3
+##
+## End of file `TARGET'.
+
+

if called as

+
+docstrip::util::classical_postamble {##}\
+  "Some message line 1\nline2\nline3" TARGET SOURCE {foo bar}
+
+

In other words, the source and terminals arguments are + ignored, but supported for symmetry with classical_preamble.

+
docstrip::util::packages_provided text ?setup-script?
+

This command returns a list where every even index element is the + name of a package provided by text when that is + evaluated as a Tcl script, and the following odd index element is + the corresponding version. It is used to do package indexing of + extracted pieces of code, in the manner of pkg_mkIndex.

+

One difference to pkg_mkIndex is that the text gets + evaluated in a safe interpreter. package require commands + are silently ignored, as are unknown commands (which includes + source and load). Other errors cause + processing of the text to stop, in which case only those + package declarations that had been encountered before the error + will be included in the return value.

+

The setup-script argument can be used to customise the + evaluation environment, if the code in text has some very + special needs. The setup-script is evaluated in the local + context of the packages_provided procedure just before the + text is processed. At that time, the name of the slave + command for the safe interpreter that will do this processing is + kept in the local variable c. To for example copy the + contents of the ::env array to the safe interpreter, one + might use a setup-script of

+
  $c eval [list array set env [array get ::env]]
+
+
+
+

Source processing commands

+

Unlike the previous group of commands, which would use +docstrip::extract to extract some code lines and then process +those further, the following commands operate on text consisting of +all types of lines.

+
+
docstrip::util::ddt2man text
+

The ddt2man command reformats text from the general + docstrip format to doctools ".man" format + (Tcl Markup Language for Manpages). The different line types are + treated as follows:

+
+ +
comment and metacomment lines
+

The '%' and '%%' prefixes are removed, the rest of the text is + kept as it is.

+
empty lines
+

These are kept as they are. (Effectively this means that they will + count as comment lines after a comment line and as code lines + after a code line.)

+
code lines
+

example_begin and example_end commands are placed + at the beginning and end of every block of consecutive code + lines. Brackets in a code line are converted to lb and + rb commands.

+
verbatim guards
+

These are processed as usual, so they do not show up in the + result but every line in a verbatim block is treated as a code + line.

+
other guards
+

These are treated as code lines, except that the actual guard is + emphasised.

+
+

At the time of writing, no project has employed doctools + markup in master source files, so experience of what works well is + not available. A source file could however look as follows

+
+% [manpage_begin gcd n 1.0]
+% [keywords divisor]
+% [keywords math]
+% [moddesc {Greatest Common Divisor}]
+% [require gcd [opt 1.0]]
+% [description]
+%
+% [list_begin definitions]
+% [call [cmd gcd] [arg a] [arg b]]
+%   The [cmd gcd] procedure takes two arguments [arg a] and [arg b] which
+%   must be integers and returns their greatest common divisor.
+proc gcd {a b} {
+%   The first step is to take the absolute values of the arguments.
+%   This relieves us of having to worry about how signs will be treated
+%   by the remainder operation.
+   set a [expr {abs($a)}]
+   set b [expr {abs($b)}]
+%   The next line does all of Euclid's algorithm! We can make do
+%   without a temporary variable, since $a is substituted before the
+%   [lb]set a $b[rb] and thus continues to hold a reference to the
+%   "old" value of [var a].
+   while {$b>0} { set b [expr { $a % [set a $b] }] }
+%   In Tcl 8.3 we might want to use [cmd set] instead of [cmd return]
+%   to get the slight advantage of byte-compilation.
+%<tcl83>  set a
+%<!tcl83>   return $a
+}
+% [list_end]
+%
+% [manpage_end]
+
+

If the above text is fed through docstrip::util::ddt2man then + the result will be a syntactically correct doctools + manpage, even though its purpose is a bit different.

+

It is suggested that master source code files with doctools + markup are given the suffix ".ddt", hence the "ddt" in + ddt2man.

+
docstrip::util::guards subcmd text
+

The guards command returns information (mostly of a + statistical nature) about the ordinary docstrip guards that occur + in the text. The subcmd selects what is returned.

+
+ +
counts
+

List the guard expression terminals with counts. The format of + the return value is a dictionary which maps the terminal name to + the number of occurencies of it in the file.

+
exprcount
+

List the guard expressions with counts. The format of the return + value is a dictionary which maps the expression to the number of + occurencies of it in the file.

+
exprerr
+

List the syntactically incorrect guard expressions (e.g. + parentheses do not match, or a terminal is missing). The return + value is a list, with the elements in no particular order.

+
expressions
+

List the guard expressions. The return value is a list, with the + elements in no particular order.

+
exprmods
+

List the guard expressions with modifiers. The format of the return + value is a dictionary where each index is a guard expression and + each entry is a string with one character for every guard line that + has this expression. The characters in the entry specify what + modifier was used in that line: +, -, *, /, or (for guard without + modifier:) space. This is the most primitive form of the + information gathered by guards.

+
names
+

List the guard expression terminals. The return value is a list, + with the elements in no particular order.

+
rotten
+

List the malformed guard lines (this does not include lines where + only the expression is malformed, though). The format of the return + value is a dictionary which maps line numbers to their contents.

+
+
docstrip::util::patch source-var terminals fromtext diff ?option value ...?
+

This command tries to apply a diff file (for example a + contributed patch) that was computed for a generated file to the + docstrip source. This can be useful if someone has + edited a generated file, thus mistaking it for being the source. + This command makes no presumptions which are specific for the case + that the generated file is a Tcl script.

+

patch requires that the source file to patch is kept as a + list of lines in a variable, and the name of that variable in the + calling context is what goes into the source-var argument. + The terminals is the list of terminals used to extract the + file that has been patched. The diff is the actual diff to + apply (in a format as explained below) and the fromtext is + the contents of the file which served as "from" when the diff was + computed. Options can be used to further control the process.

+

The process works by "lifting" the hunks in the diff from + generated to source file, and then applying them to the elements of + the source-var. In order to do this lifting, it is necessary + to determine how lines in the fromtext correspond to elements + of the source-var, and that is where the terminals come + in; the source is first extracted under the given + terminals, and the result of that is then matched against + the fromtext. This produces a map which translates line + numbers stated in the diff to element numbers in + source-var, which is what is needed to lift the hunks.

+

The reason that both the terminals and the fromtext + must be given is twofold. First, it is very difficult to keep track + of how many lines of preamble are supplied some other way than by + copying lines from source files. Second, a generated file might + contain material from several source files. Both make it impossible + to predict what line number an extracted file would have in the + generated file, so instead the algorithm for computing the line + number map looks for a block of lines in the fromtext which + matches what can be extracted from the source. This matching is + affected by the following options:

+
+ +
-matching mode
+

How equal must two lines be in order to match? The supported + modes are:

+
+ +
exact
+

Lines must be equal as strings. This is the default.

+
anyspace
+

All sequences of whitespace characters are converted to single + spaces before comparing.

+
nonspace
+

Only non-whitespace characters are considered when comparing.

+
none
+

Any two lines are considered to be equal.

+
+
-metaprefix string
+

The -metaprefix value to use when extracting. Defaults + to "%%", but for Tcl code it is more likely that "#" or "##" had + been used for the generated file.

+
-trimlines boolean
+

The -trimlines value to use when extracting. Defaults to + true.

+
+

The return value is in the form of a unified diff, containing only + those hunks which were not applied or were only partially applied; + a comment in the header of each hunk specifies which case is at + hand. It is normally necessary to manually review both the return + value from patch and the patched text itself, as this command + cannot adjust comment lines to match new content.

+

An example use would look like

+
+set sourceL [split [docstrip::util::thefile from.dtx] \n]
+set terminals {foo bar baz}
+set fromtext [docstrip::util::thefile from.tcl]
+set difftext [exec diff --unified from.tcl to.tcl]
+set leftover [docstrip::util::patch sourceL $terminals $fromtext\
+  [docstrip::util::import_unidiff $difftext] -metaprefix {#}]
+set F [open to.dtx w]; puts $F [join $sourceL \n]; close $F
+return $leftover
+
+

Here, "from.dtx" was used as source for "from.tcl", which + someone modified into "to.tcl". We're trying to construct a + "to.dtx" which can be used as source for "to.tcl".

+
docstrip::util::thefile filename ?option value ...?
+

The thefile command opens the file filename, reads it to + end, closes it, and returns the contents (dropping a final newline + if there is one). The option-value pairs are + passed on to fconfigure to configure the open file channel + before anything is read from it.

+
docstrip::util::import_unidiff diff-text ?warning-var?
+

This command parses a unified (diff flags -U and + --unified) format diff into the list-of-hunks format + expected by docstrip::util::patch. The diff-text + argument is the text to parse and the warning-var is, if + specified, the name in the calling context of a variable to which + any warnings about parsing problems will be appended.

+

The return value is a list of hunks. Each hunk is a list of + five elements "start1 end1 start2 end2 + lines". start1 and end1 are line numbers in the + "from" file of the first and last respectively lines of the hunk. + start2 and end2 are the corresponding line numbers in + the "to" file. Line numbers start at 1. The lines is a list + with two elements for each line in the hunk; the first specifies the + type of a line and the second is the actual line contents. The type + is - for lines only in the "from" file, + for lines + that are only in the "to" file, and 0 for lines that are + in both.

+
+
+

See Also

+

docstrip, doctools, doctools_fmt

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/changelog.html Index: embedded/www/tcllib/files/modules/doctools/changelog.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/changelog.html +++ embedded/www/tcllib/files/modules/doctools/changelog.html @@ -0,0 +1,204 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::changelog(n) 1.1 tcllib "Documentation tools"

+

Name

+

doctools::changelog - Processing text in Emacs ChangeLog format

+
+ + +

Description

+

This package provides Tcl commands for the processing and reformatting +of text in the "ChangeLog" format generated by emacs.

+
+

API

+
+
::doctools::changelog::scan text
+

The command takes the text and parses it under the assumption +that it contains a ChangeLog as generated by emacs. It +returns a data structure describing the contents of this ChangeLog.

+

This data structure is a list where each element describes one entry +in the ChangeLog. Each element/entry is then a list of three elements +describing the date of the entry, its author, and the comments made, +in this order. The last item in each element/entry, the comments, is a +list of sections. Each section is described by a list containing two +elements, a list of file names, and a string containing the true +comment associated with the files of the section.

+
+    {
+	{
+	    date
+	    author
+	    {
+		{
+		    {file ...}
+		    commenttext
+		}
+		...
+	    }
+	}
+	{...}
+    }
+
+
+
::doctools::changelog::flatten entries
+

This command converts a list of entries as generated by +change::scan above into a simpler list of plain +text blocks each containing all the information of a +single entry.

+
::doctools::changelog::toDoctools title module version entries
+

This command converts the pre-parsed ChangeLog entries as +generated by the command ::doctools::changelog::scan into a +document in doctools format and returns it as the result of the +command.

+

The other three arguments supply the information for the header of +that document which is not available from the changelog itself.

+
::doctools::changelog::merge entries...
+

Each argument of the command is assumed to be a pre-parsed Changelog +as generated by the command ::doctools::changelog::scan. This +command merges all of them into a single structure, and collapses +multiple entries for the same date and author into a single entry. The +new structure is returned as the result of the command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/cvs.html Index: embedded/www/tcllib/files/modules/doctools/cvs.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/cvs.html +++ embedded/www/tcllib/files/modules/doctools/cvs.html @@ -0,0 +1,202 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::cvs(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::cvs - Processing text in 'cvs log' format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil
    • +
  • package require doctools::cvs ?1?
    • +
+ +
+
+

Description

+

This package provides Tcl commands for the processing and reformatting +text in the format generated by the cvs log command.

+

The commands ::doctools::cvs::scanLog +and ::doctools::cvs::toChangeLog are derived from code found on +the Tcl'ers Wiki. See the references at the +end of the page.

+
+

API

+
+
::doctools::cvs::scanLog text evar cvar fvar
+

The command takes the text and parses it under the assumption +that it contains a CVS log as generated by cvs log. The +resulting information is stored in the variables whose names were +specified via evar, cvar, and fvar.

+

Already existing information in the referenced variables is preserved, +allowing the caller to merge data from multiple logs into one +database.

+
+
varname evar (in)
+

Has to refer to a scalar variable. After the call this variable will +contain a list of all the entries found in the log file. An entry is +identified through the combination of date and author, and can be +split over multiple physical entries, one per touched file.

+

It should be noted that the entries are listed in the same order as +they were found in the text. This is not necessarily sorted by +date or author.

+

Each item in the list is a list containing two elements, the date of +the entry, and its author, in this order. The date is formatted as +year/month/day.

+
varname cvar (in)
+

Has to refer to an array variable. Keys are strings containing the +date and author of log entries, in this order, separated by a comma.

+

The values are lists of comments made for the entry.

+
varname fvar (in)
+

Has to refer to an array variable. Keys are strings containing +date, author of a log entry, and a comment for that entry, in this +order, separated by commas.

+

The values are lists of the files the entry is touching.

+
+
::doctools::cvs::toChangeLog evar cvar fvar
+

] +The three arguments for this command are the same as the last three +arguments of the command ::doctools::cvs::scanLog. This command +however expects them to be filled with information about one or more +logs. It takes this information and converts it into a text in the +format of a ChangeLog as accepted and generated by emacs. The +constructed text is returned as the result of the command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

[uri, http://wiki.tcl.tk/log2changelog

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx.html Index: embedded/www/tcllib/files/modules/doctools/docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx.html +++ embedded/www/tcllib/files/modules/doctools/docidx.html @@ -0,0 +1,407 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx(n) 1.0.5 tcllib "Documentation tools"

+

Name

+

doctools::idx - docidx - Processing indices

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the docidx markup language +into any output format X for which a formatting engine is +available.

+

A reader interested in the markup language itself should start with +the docidx language introduction and proceed from there to +the formal specifications, i.e. the docidx language syntax +and the docidx language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the docidx plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::idx::new objectName ?-option value ...?
+

This command creates a new docidx object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::idx::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::idx::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::idx::new have the following +general form and may be used to invoke various operations on their +docidx converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in docidx format as +specified in the companion document docidx_fmt. Errors will be +thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +docidx plugin API reference which specifies the interaction +between the objects created by this package and index formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for index +formatting engines. See also the command ::doctools::idx::search +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All docidx objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_file. +This command is described in more detail in the companion document +docidx_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "idx.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "idx.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::idx::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. In other words, if the +package implementation "docidx.tcl" is installed in the directory +"/usr/local/lib/tcllib/doctools" then it will by default search +the directory "/usr/local/lib/tcllib/doctools/mpformats" for +format implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_intro.html +++ embedded/www/tcllib/files/modules/doctools/docidx_intro.html @@ -0,0 +1,190 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_intro - docidx introduction

+
+ +

Description

+

docidx (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of keyword-based +indices for documentation. These are

+
    +

  1. A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +docidx language introduction first. Having digested this +the formal docidx language syntax specification should +become understandable. A writer experienced with docidx may only +need the docidx language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them.

    2. +

  2. A processor of documentation written in the docidx +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose docidx to the +user. +At the bottom level, common to both applications, however sits the +package doctoools::idx, providing the basic facilities to +read and process files containing text in the docidx format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools::idx package and its +plugins, as described in the docidx plugin API reference.

    4. +
+
+

RELATED FORMATS

+

docidx does not stand alone, it has two companion formats. These are +called doctoc and doctools, and they are for the markup +of tables of contents, and general documentation, +respectively. +They are described in their own sets of documents, starting at the +doctoc introduction and the doctools introduction, +respectively.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_cmdref.html @@ -0,0 +1,221 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_cmdref - docidx language command reference

+
+ + +

Description

+

This document specifies both names and syntax of all the commands +which together are the docidx markup language, version 1. +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. +A beginner should read the much more informally written +docidx language introduction first.

+
+

Commands

+
+
comment plaintext
+

Index markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the docidx markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
index_begin text title
+

Document structure. The command to start an index. The arguments are a +label for the whole group of documents the index refers to +(text) and the overall title text for the index (title), +without markup.

+

The label often is the name of the package (or extension) the +documents belong to.

+
index_end
+

Document structure. Command to end an index. Anything in the document +coming after this command is in error.

+
key text
+

Index structure. This command adds the keyword text to the +index.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands.

+
manpage file text
+

Index structure. This command adds an element to the index which +refers to a document. The document is specified through the symbolic +name file. The text argument is used to label the +reference.

+

Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of the file will be inserted by +the chosen formatting engine when converting the input. This will be +based on a mapping from symbolic to actual names given to the engine.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands.

+
url url label
+

Index structure. This is the second command to add an element to the +index. To refer to a document it is not using a symbolic name however, +but a (possibly format-specific) url describing the exact location of +the document indexed here.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_faq.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_faq - docidx language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the docidx markup language +and companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document as explained in the section +Bugs, Ideas, Feedback below.

+
+
+

EXAMPLES

+

Where do I find docidx examples?

+

We have no direct examples of documents written using docidx +markup. However the doctools processor dtplite does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses docidx +markup and is not deleted when generation completes. Such files can +therefore serve as examples.

+

dtplite is distributed as part of Tcllib, so to get it you +need one of

+
    +

  1. A snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +Development Snapshots

    2. +

  2. A Tcllib release archive. They are available at the home +page.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_intro.html @@ -0,0 +1,288 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_intro - docidx language introduction

+
+ +

Description

+

This document is an informal introduction to version 1 of the docidx +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the docidx language syntax specification +and the docidx language command reference.

+

Fundamentals

+

While the docidx markup language is quite similar to the +doctools markup language, in the broadest terms possible, +there is one key difference. An index consists essentially only of +markup commands, with no plain text interspersed between them, except +for whitespace.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

+
+    ... [key {markup language}] ...
+
+
+  ... [manpage thefile \\
+          {file description}] ...
+
+
+

Basic structure

+

The most simple document which can be written in docidx is

+
+    [index_begin GROUPTITLE TITLE]
+    [index_end]
+
+

Not very useful, but valid. This also shows us that all docidx +documents consist of only one part where we will list all keys and +their references.

+

A more useful index will contain at least keywords, or short 'keys', +i.e. the phrases which were indexed. So:

+
+[index_begin GROUPTITLE TITLE]
+[key markup]
+[key {semantic markup}]]
+[key {docidx markup}]
+[key {docidx language}]
+[key {docidx commands}]
+[index_end]
+
+

In the above example the command key is used to declare the +keyword phrases we wish to be part of the index.

+

However a truly useful index does not only list the keyword phrases, +but will also contain references to documents associated with the +keywords. Here is a made-up index for all the manpages in the module +base64:

+
+[index_begin tcllib/base64 {De- & Encoding}]
+[key base64]
+[manpage base64]
+[key encoding]
+[manpage base64]
+[manpage uuencode]
+[manpage yencode]
+[key uuencode]
+[manpage uuencode]
+[key yEnc]
+[manpage yencode]
+[key ydecode]
+[manpage yencode]
+[key yencode]
+[manpage yencode]
+[index_end]
+
+

In the above example the command manpage is used to insert +references to documents, using symbolic file names, with each command +belonging to the last key command coming before it.

+

The other command to insert references is url. In contrast to +manpage it uses explicit (possibly format-specific) urls to +describe the location of the referenced document. As such this command +is intended for the creation of references to external documents which +could not be handled in any other way.

+
+

Advanced structure

+

In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the index_begin command opening the +document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[index_begin GROUPTITLE TITLE]
+...
+[index_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure.

+
+[index_begin GROUPTITLE TITLE]
+[include FILE]
+[vset VAR VALUE]
+...
+[index_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before index_begin may contain only the templating +commands vset and include, a file included after a key +may contain only manape or url references, and other keys, etc.

+
+

Escapes

+

Beyond the 6 commands shown so far we have two more available. +However their function is not the marking up of index structure, but +the insertion of characters, namely [ and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal docidx language syntax +specification as well. From here on out the +docidx language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +dtp.

+

On the other hand, docidx is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple dtplite goes, creating an index for a set of +documents behind the scenes, without the writer having to do so on +their own.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html +++ embedded/www/tcllib/files/modules/doctools/docidx_lang_syntax.html @@ -0,0 +1,208 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_lang_syntax - docidx language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +docidx markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +docidx language command reference. +A beginner should read the much more informally written +docidx language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the docidx markup language is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +docidx language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of docidx documents. The +lexical level of the language was covered in the previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +
+

The syntax:

+
+index     = defs
+            INDEX_BEGIN
+            [ contents ]
+            INDEX_END
+            { <WHITE> }
+defs      = { INCLUDE | VSET | <WHITE> }
+contents  = keyword { keyword }
+keyword   = defs KEY ref { ref }
+ref       = MANPAGE | URL | defs
+
+

At last a rule we were unable to capture in the EBNF syntax, as it is +about the arguments of the markup commands, something which is not +modeled here.

+
    +

  1. The arguments of all markup commands have to be plain text, and/or text +markup commands, i.e. one of

    +
      +

    1. lb,

      2. +

    2. rb, or

      3. +

    3. vset (1-argument form).

      4. +
    +
    2. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html +++ embedded/www/tcllib/files/modules/doctools/docidx_plugin_apiref.html @@ -0,0 +1,437 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

docidx_plugin_apiref(n) 1.0 tcllib "Documentation tools"

+

Name

+

docidx_plugin_apiref - docidx plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write an index formatting engine for some output +format X.

+

It specifies the interaction between the doctools::idx +package and its plugins, i.e. the interface any index formatting +engine has to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +docidx language introduction and proceed from there to the +formal specifications, i.e. the docidx language syntax and +the docidx language command reference.

+
+

OVERVIEW

+

The API for an index formatting engine consists of two major sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as an index formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. an index formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools::idx.

+
dt_format
+

Query command. It returns the name of the format associated with the +index formatting engine.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the index formatting +engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    idx_numpasses -> n
+    idx_listvariables -> vars
+    idx_varset var1 value1
+    idx_varset var2 value2
+    ...
+    idx_varset varK valueK
+    idx_initialize
+    idx_setup 1
+    ...
+    idx_setup 2
+    ...
+    ...
+    idx_setup n
+    ...
+    idx_postprocess
+    idx_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at idx_varset.

+

In each of the passes, i.e. after the calls of idx_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the docidx markup language, +as specified in the docidx language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first idx_varset to +idx_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with idx_setup and going until either the next +idx_setup or idx_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
idx_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
idx_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after idx_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
idx_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
idx_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
idx_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
idx_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
idx_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by idx_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the docidx markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the five markup commands specified in the +docidx language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +docidx language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the docidx +markup language, as specified in the docidx language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc.html Index: embedded/www/tcllib/files/modules/doctools/doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc.html +++ embedded/www/tcllib/files/modules/doctools/doctoc.html @@ -0,0 +1,407 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc(n) 1.1.4 tcllib "Documentation tools"

+

Name

+

doctools::toc - doctoc - Processing tables of contents

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the doctoc markup language +into any output format X for which a formatting engine is +available.

+

A reader interested in the markup language itself should start with +the doctoc language introduction and proceed from there to +the formal specifications, i.e. the doctoc language syntax +and the doctoc language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the doctoc plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::toc::new objectName ?-option value ...?
+

This command creates a new doctoc object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::toc::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::toc::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::toc::new have the following +general form and may be used to invoke various operations on their +doctoc converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in doctoc format as +specified in the companion document doctoc_fmt. Errors will be +thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +doctoc plugin API reference which specifies the interaction +between the objects created by this package and toc formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for toc +formatting engines. See also the command ::doctools::toc::search +on how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All doctoc objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_file. +This command is described in more detail in the companion document +doctoc_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "toc.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "toc.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::toc::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. In other words, if the +package implementation "doctoc.tcl" is installed in the directory +"/usr/local/lib/tcllib/doctools" then it will by default search +the directory "/usr/local/lib/tcllib/doctools/mpformats" for +format implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined formatting engines for the following +formats. Some of the formatting engines support engine +parameters. These will be explicitly highlighted.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports three parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_intro.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_intro.html @@ -0,0 +1,189 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_intro - doctoc introduction

+
+ +

Description

+

doctoc (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables of +contents for documentation. These are

+
    +

  1. A tcl based language for the semantic markup of a table of +contents. Markup is represented by Tcl commands.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +doctoc language introduction first. Having digested this +the formal doctoc language syntax specification should +become understandable. A writer experienced with doctoc may only +need the doctoc language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them.

    2. +

  2. A processor of documentation written in the doctoc +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose doctoc to the +user. +At the bottom level, common to both applications, however sits the +package doctoools::toc, providing the basic facilities to +read and process files containing text in the doctoc format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools::toc package and its +plugins, as described in the doctoc plugin API reference.

    4. +
+
+

RELATED FORMATS

+

doctoc does not stand alone, it has two companion formats. These are +called docidx and doctools, and they are for the markup +of keyword indices, and general documentation, respectively. +They are described in their own sets of documents, starting at the +docidx introduction and the doctools introduction, +respectively.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_cmdref.html @@ -0,0 +1,226 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_cmdref - doctoc language command reference

+
+ + +

Description

+

This document specifies both names and syntax of all the commands +which together are the doctoc markup language, version 1. +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. +A beginner should read the much more informally written +doctoc language introduction first.

+
+

Commands

+
+
comment plaintext
+

Toc markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
division_end
+

Toc structure. This command closes the division opened by the last +division_begin command coming before it, and not yet closed.

+
division_start text ?symfile?
+

Toc structure. This command opens a division in the table of +contents. Its counterpart is division_end. Together they allow a +user to give a table of contents additional structure.

+

The title of the new division is provided by the argument text.

+

If the symbolic filename symfile is present then the section +title should link to the referenced document, if links are supported +by the output format.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the doctoc markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
item file text desc
+

Toc structure. This command adds an individual element to the table of +contents. Each such element refers to a document. The document is +specified through the symbolic name file. The text +argument is used to label the reference, whereas the desc +provides a short descriptive text of that document.

+

The symbolic names are used to preserve the convertibility of this +format to any output format. The actual name of the file will be +inserted by the chosen formatting engine when converting the +input. This will be based on a mapping from symbolic to actual names +given to the engine.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form +text. Required to avoid interpretation of a left bracket as the start +of a markup command. Its usage is restricted to the arguments of other +markup commands.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form +text. Required to avoid interpretation of a right bracket as the end +of a markup command. Its usage is restricted to the arguments of other +commands.

+
toc_begin text title
+

Document structure. The command to start a table of contents. The +arguments are a label for the whole group of documents the index +refers to (text) and the overall title text for the index +(title), without markup.

+

The label often is the name of the package (or extension) the +documents belong to.

+
toc_end
+

Document structure. Command to end a table of contents. Anything in +the document coming after this command is in error.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_faq.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_faq - doctoc language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the doctoc markup language +and companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document as explained in the section +Bugs, Ideas, Feedback below.

+
+
+

EXAMPLES

+

Where do I find doctoc examples?

+

We have no direct examples of documents written using doctoc +markup. However the doctools processor dtplite does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses doctoc +markup and is not deleted when generation completes. Such files can +therefore serve as examples.

+

dtplite is distributed as part of Tcllib, so to get it you +need one of

+
    +

  1. A snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +Development Snapshots

    2. +

  2. A Tcllib release archive. They are available at the home +page.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_intro.html @@ -0,0 +1,353 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_intro - doctoc language introduction

+
+ +

Description

+

This document is an informal introduction to version 1.1 of the doctoc +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the doctoc language syntax specification +and the doctoc language command reference.

+

Fundamentals

+

While the doctoc markup language is quite similar to the +doctools markup language, in the broadest terms possible, +there is one key difference. A table of contents consists essentially +only of markup commands, with no plain text interspersed between them, +except for whitespace.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

+
+    ... [division_start {Appendix 1}] ...
+
+
+  ... [item thefile \\
+          label {file description}] ...
+
+
+

Basic structure

+

The most simple document which can be written in doctoc is

+
+    [toc_begin GROUPTITLE TITLE]
+    [toc_end]
+
+

This also shows us that all doctoc documents consist of only one +part where we will list items and divisions.

+

The user is free to mix these as she sees fit. This is a change from +version 1 of the language, which did not allow this mixing, but only +the use of either a series of items or a series of divisions.

+

We will discuss the commands for each of these two possibilities in +the next sections.

+
+

Items

+

Use the command item to put an item into a table of +contents. This is essentially a reference to a section, subsection, +etc. in the document, or set of documents, the table of contents is +for. The command takes three arguments, a symbolic name for the file +the item is for and two text to label the item and describe the +referenced section.

+

Symbolic names are used to preserve the convertibility of this format +to any output format. The actual name of any file will be inserted by +the chosen formatting engine when converting the input, based on a +mapping from symbolic to actual names given to the engine.

+

Here a made up example for a table of contents of this document:

+
+[toc_begin Doctoc {Language Introduction}]
+[item 1 DESCRIPTION]
+[item 1.1 {Basic structure}]
+[item 1.2 Items]
+[item 1.3 Divisions]
+[item 2 {FURTHER READING}]
+[toc_end]
+
+
+

Divisions

+

One thing of notice in the last example in the previous section is +that the referenced sections actually had a nested structure, +something which was expressed in the item labels, by using a common +prefix for all the sections nested under section 1.

+

This kind of structure can be made more explicit in the doctoc +language by using divisions. Instead of using a series of plain items +we use a series of divisions for the major references, and then place +the nested items inside of these.

+

Of course, instead of the nested items we can again use divisions and +thus nest arbitrarily deep.

+

A division is marked by two commands instead of one, one to start it, +the other to close the last opened division. They are:

+
+
division_start
+

This command opens a new division. It takes one or two arguments, the +title of the division, and the symbolic name of the file it refers +to. The latter is optional. +If the symbolic filename is present then the section title should link +to the referenced document, if links are supported by the output +format.

+
division_end
+

This command closes the last opened and not yet closed division.

+
+

Using this we can recast the last example like this

+
+[toc_begin Doctoc {Language Introduction}]
+[division_start DESCRIPTION]
+[item 1 {Basic structure}]
+[item 2 Items]
+[item 3 Divisions]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+

Or, to demonstrate deeper nesting

+
+[toc_begin Doctoc {Language Introduction}]
+[division_start DESCRIPTION]
+[division_start {Basic structure}]
+[item 1 Do]
+[item 2 Re]
+[division_end]
+[division_start Items]
+[item a Fi]
+[item b Fo]
+[item c Fa]
+[division_end]
+[division_start Divisions]
+[item 1 Sub]
+[item 1 Zero]
+[division_end]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+

And do not forget, it is possible to freely mix items and divisions, +and to have empty divisions.

+
+[toc_begin Doctoc {Language Introduction}]
+[item 1 Do]
+[division_start DESCRIPTION]
+[division_start {Basic structure}]
+[item 2 Re]
+[division_end]
+[item a Fi]
+[division_start Items]
+[item b Fo]
+[item c Fa]
+[division_end]
+[division_start Divisions]
+[division_end]
+[division_end]
+[division_start {FURTHER READING}]
+[division_end]
+[toc_end]
+
+
+

Advanced structure

+

In all previous examples we fudged a bit regarding the markup actually +allowed to be used before the toc_begin command opening the +document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the table of +contents. I.e. it is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[toc_begin GROUPTITLE TITLE]
+...
+[toc_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure.

+
+[toc_begin GROUPTITLE TITLE]
+[include FILE]
+[vset VAR VALUE]
+...
+[toc_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before toc_begin may contain only the templating +commands vset and include, a file included in a division +may contain only items or divisions commands, etc.

+
+

Escapes

+

Beyond the 6 commands shown so far we have two more available. +However their function is not the marking up of toc structure, but the +insertion of characters, namely [ and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal doctoc language syntax +specification as well. From here on out the +doctoc language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with Tclapps' ultra-configurable +dtp.

+

On the other hand, doctoc is perfectly suited for the automatic +generation from doctools documents, and this is the route Tcllib's +easy and simple dtplite goes, creating a table of contents +for a set of documents behind the scenes, without the writer having to +do so on their own.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_lang_syntax.html @@ -0,0 +1,197 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_lang_syntax - doctoc language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +doctoc markup language, version 1.1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +doctoc language command reference. +A beginner should read the much more informally written +doctoc language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the doctoc markup language is +like SGML and similar languages. A document written in this language +consists primarily of markup commands, with text embedded into it at +some places.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +doctoc language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of doctoc documents. The +lexical level of the language was covered in the previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +
+

The syntax:

+
+toc       = defs
+            TOC_BEGIN
+            contents
+            TOC_END
+            { <WHITE> }
+defs      = { INCLUDE | VSET | <WHITE> }
+contents  = { defs entry } [ defs ]
+entry     = ITEM | division
+division  = DIVISION_START
+            contents
+            DIVISION_END
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html +++ embedded/www/tcllib/files/modules/doctools/doctoc_plugin_apiref.html @@ -0,0 +1,437 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctoc_plugin_apiref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctoc_plugin_apiref - doctoc plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write a toc formatting engine for some output +format X.

+

It specifies the interaction between the doctools::toc +package and its plugins, i.e. the interface any toc formatting engine +has to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +doctoc language introduction and proceed from there to the +formal specifications, i.e. the doctoc language syntax and +the doctoc language command reference.

+
+

OVERVIEW

+

The API for a toc formatting engine consists of two major sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as a toc formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. a toc formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools::toc.

+
dt_format
+

Query command. It returns the name of the format associated with the +toc formatting engine.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the toc formatting +engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    toc_numpasses -> n
+    toc_listvariables -> vars
+    toc_varset var1 value1
+    toc_varset var2 value2
+    ...
+    toc_varset varK valueK
+    toc_initialize
+    toc_setup 1
+    ...
+    toc_setup 2
+    ...
+    ...
+    toc_setup n
+    ...
+    toc_postprocess
+    toc_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at toc_varset.

+

In each of the passes, i.e. after the calls of toc_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctoc markup language, +as specified in the doctoc language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first toc_varset to +toc_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with toc_setup and going until either the next +toc_setup or toc_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
toc_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
toc_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after toc_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
toc_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
toc_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
toc_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
toc_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
toc_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by toc_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctoc markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the five markup commands specified in the +doctoc language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +doctoc language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctoc +markup language, as specified in the doctoc language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools.html Index: embedded/www/tcllib/files/modules/doctools/doctools.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools.html +++ embedded/www/tcllib/files/modules/doctools/doctools.html @@ -0,0 +1,495 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools(n) 1.4.19 tcllib "Documentation tools"

+

Name

+

doctools - doctools - Processing documents

+
+ + +

Description

+

This package provides a class for the creation of objects able to +process and convert text written in the doctools markup +language into any output format X for which a +formatting engine is available.

+

A reader interested in the markup language itself should start with +the doctools language introduction and proceed from there to +the formal specifications, i.e. the doctools language syntax +and the doctools language command reference.

+

If on the other hand the reader wishes to write her own formatting +engine for some format, i.e. is a plugin writer then reading +and understanding the doctools plugin API reference is an +absolute necessity, as that document specifies the interaction between +this package and its plugins, i.e. the formatting engines, in detail.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::doctools::new objectName ?option value...?
+

This command creates a new doctools object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the object.

+
::doctools::help
+

This is a convenience command for applications wishing to provide +their user with a short description of the available formatting +commands and their meanings. It returns a string containing a standard +help text.

+
::doctools::search path
+

Whenever an object created by this the package has to map the name of +a format to the file containing the code for its formatting engine it +will search for the file in a number of directories stored in a +list. See section FORMAT MAPPING for more explanations.

+

This list not only contains three default directories which are +declared by the package itself, but is also extensible user of the +package. +This command is the means to do so. When given a path to an +existing and readable directory it will prepend that directory to the +list of directories to search. This means that the path added +last is later searched through first.

+

An error will be thrown if the path either does not exist, is +not a directory, or is not readable.

+
+
+

OBJECT COMMAND

+

All commands created by ::doctools::new have the following +general form and may be used to invoke various operations on their +doctools converter object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName format text
+

This method runs the text through the configured formatting +engine and returns the generated string as its result. An error will +be thrown if no -format was configured for the object.

+

The method assumes that the text is in doctools format as +specified in the companion document doctools_fmt. Errors will +be thrown otherwise.

+
objectName map symbolic actual
+

This methods add one entry to the per-object mapping from +symbolic filenames to the actual uris. +The object just stores this mapping and makes it available to the +configured formatting engine through the command dt_fmap. +This command is described in more detail in the +doctools plugin API reference which specifies the interaction +between the objects created by this package and doctools formatting +engines.

+
objectName parameters
+

This method returns a list containing the names of all engine +parameters provided by the configured formatting engine. It will +return an empty list if the object is not yet configured for a +specific format.

+
objectName search path
+

This method extends the per-object list of paths searched for doctools +formatting engines. See also the command ::doctools::search on +how to extend the per-package list of paths. Note that the path +entered last will be searched first. +For more details see section FORMAT MAPPING.

+
objectName setparam name value
+

This method sets the named engine parameter to the specified +value. +It will throw an error if the object is either not yet configured for +a specific format, or if the formatting engine for the configured +format does not provide a parameter with the given name. +The list of parameters provided by the configured formatting engine +can be retrieved through the method parameters.

+
objectName warnings
+

This method returns a list containing all the warnings which were +generated by the configured formatting engine during the last +invocation of the method format.

+
+
+

OBJECT CONFIGURATION

+

All doctools objects understand the following configuration options:

+
+
-file file
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the commands dt_file +and dt_mainfile. +These commands are described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the file containing the document which is currently processed.

+
-ibase file
+

The argument of this option is stored in the object and used as the +base path for resolution of relative include paths. If this option is +not set (empty string) the value of -file is used instead.

+

Note that -file and -ibase, while similar looking, +are actually very different. The value of -file is used by +some engines for the generation of proper relative references between +output documents (HTML). As such this is a destination +path. The -ibase on the other hand is used to resolve +relative include paths, and as such deals with source paths.

+

The default value of this option is the empty string.

+
-module text
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_module. +This command is described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as the +name of the module the file containing the document which is currently +processed belongs to.

+
-format text
+

The argument of this option specifies the format to generate and by +implication the formatting engine to use when converting text via the +method format. Its default value is the empty string. The +method format cannot be used if this option is not set to a +valid value at least once.

+

The package will immediately try to map the given name to a file +containing the code for a formatting engine generating that format. An +error will be thrown if this mapping fails. In that case a previously +configured format is left untouched.

+

The section FORMAT MAPPING explains in detail how the +package and object will look for engine implementations.

+
-deprecated boolean
+

This option is a boolean flag. The object will generate warnings if +this flag is set and the text given to method format contains +the deprecated markup command strong. +Its default value is FALSE. In other words, no warnings will +be generated.

+
-copyright text
+

The argument of this option is stored in the object and made available +to the configured formatting engine through the command dt_copyright. +This command is described in more detail in the companion document +doctools_api which specifies the API between the object and +formatting engines.

+

The default value of this option is the empty string.

+

The configured formatting engine should interpret the value as a +copyright assignment for the document which is currently processed, or +the package described by it.

+

This information must be used if and only if the engine is unable to +find any copyright assignments within the document itself. Such are +specified by the formatting command copyright. This command is +described in more detail in the companion document doctools_fmt +which specifies the doctools format itself.

+
+
+

FORMAT MAPPING

+

The package and object will perform the following algorithm when +trying to map a format name foo to a file containing an +implementation of a formatting engine for foo:

+
    +

  1. If foo is the name of an existing file then this file is +directly taken as the implementation.

    2. +

  2. If not, the list of per-object search paths is searched. For each +directory in the list the package checks if that directory contains a +file "fmt.foo". If yes, then that file is taken as the +implementation.

    +

    Note that this list of paths is initially empty and can be extended +through the object method search.

    3. +

  3. If not, the list of package paths is searched. +For each directory in the list the package checks if that directory +contains a file "fmt.foo". If yes, then that file is taken +as the implementation.

    +

    This list of paths can be extended +through the command ::doctools::search. +It contains initially one path, the subdirectory "mpformats" of +the directory the package itself is located in. +In other words, if the package implementation "doctools.tcl" is +installed in the directory "/usr/local/lib/tcllib/doctools" then +it will by default search the +directory "/usr/local/lib/tcllib/doctools/mpformats" for format +implementations.

    4. +

  4. The mapping fails.

    5. +
+
+
+

PREDEFINED ENGINES

+

The package provides predefined engines for the following +formats. Some of the engines support parameters. These will be +explained below as well.

+
+
html
+

This engine generates HTML markup, for processing by web browsers and +the like. This engine supports four parameters:

+
+
footer
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +before the </body> tag, closing the body of the generated +HTML.

+

This can be used to insert boilerplate footer markup into the +generated document.

+
header
+

The value for this parameter has to be valid selfcontained HTML markup +for the body section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <body> tag, starting the body of the generated HTML.

+

This can be used to insert boilerplate header markup into the +generated document.

+
meta
+

The value for this parameter has to be valid selfcontained HTML markup +for the header section of a HTML document. The default value is the +empty string. The value is inserted into the generated output just +after the <head> tag, starting the header section of the +generated HTML.

+

This can be used to insert boilerplate meta data markup into the +generated document, like references to a stylesheet, standard meta +keywords, etc.

+
xref
+

The value for this parameter has to be a list of triples specifying +cross-reference information. This information is used by the engine to +create more hyperlinks. Each triple is a list containing a pattern, +symbolic filename and fragment reference, in this order. If a pattern +is specified multiple times the last occurence of the pattern will be +used.

+

The engine will consult the xref database when encountering specific +commands and will create a link if the relevant text matches one of +the patterns. No link will be created if no match was found. The link +will go to the uri file#fragment listed in the relevant +triple, after conversion of the symbolic file name to the actual uri +via dt_fmap (see the doctools plugin API reference). +This file-to-uri mapping was build by calls to the method map +of the doctools object (See section OBJECT METHODS).

+

The following formatting commands will consult the xref database:

+
+
cmd word
+

The command will look for the patterns sa,word, and +word, in this order. If this fails if it will convert word +to all lowercase and try again.

+
syscmd word
+

The command will look for the patterns sa,word, and +word, in this order. If this fails if it will convert word +to all lowercase and try again.

+
term word
+

The command will look for the patterns kw,word, +sa,word, and word, in this order. If this fails if +it will convert word to all lowercase and try again.

+
package word
+

The command will look for the patterns sa,word, +kw,word, and word, in this order. If this fails if +it will convert word to all lowercase and try again.

+
see_also word...
+

The command will look for the patterns sa,word, and +word, in this order, for each word given to the +command. If this fails if it will convert word to all lowercase +and try again.

+
keywords word...
+

The command will look for the patterns kw,word, and +word, in this order, for each word given to the +command. If this fails if it will convert word to all lowercase +and try again.

+
+
+
latex
+

This engine generates output suitable for the latex text +processor coming out of the TeX world.

+
list
+

This engine retrieves version, section and title of the manpage from +the document. As such it can be used to generate a directory listing +for a set of manpages.

+
nroff
+

This engine generates nroff output, for processing by nroff, +or groff. The result will be standard man pages as they are +known in the unix world.

+
null
+

This engine generates no outout at all. This can be used if one just +wants to validate some input.

+
tmml
+

This engine generates TMML markup as specified by Joe English. The Tcl +Manpage Markup Language is a derivate of XML.

+
wiki
+

This engine generates Wiki markup as understood by Jean Claude +Wippler's wikit application.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_intro.html +++ embedded/www/tcllib/files/modules/doctools/doctools_intro.html @@ -0,0 +1,188 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_intro - doctools introduction

+
+ +

Description

+

doctools (short for documentation tools) stands for +a set of related, yet different, entities which are working together +for the easy creation and transformation of documentation. These are

+
    +

  1. A tcl based language for the semantic markup of text. Markup is +represented by Tcl commands interspersed with the actual text.

    2. +

  2. A package providing the ability to read and transform texts written in +that markup language. It is important to note that the actual +transformation of the input text is delegated to plugins.

    3. +

  3. An API describing the interface between the package above and a +plugin.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctools should read the more informally written +doctools language introduction first. Having digested this +the formal doctools language syntax specification should +become understandable. A writer experienced with doctools may only +need the doctools language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtplite application can be +used to validate it, and after completion it also performs the +conversion into the chosen system of visual markup, be it *roff, HTML, +plain text, wiki, etc.

    2. +

  2. A processor of documentation written in the doctools +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtplite application +provided by Tcllib. A more powerful one (in terms of options and +ability to configure it) is the dtp application, provided by +Tclapps. +At the bottom level, common to both applications, however sits the +package doctools, providing the basic facilities to read and +process files containing text in the doctools format.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the doctools package and its plugins, as +described in the doctools plugin API reference.

    4. +
+
+

RELATED FORMATS

+

doctools does not stand alone, it has two companion formats. These are +called docidx and doctoc, and they are for the markup of +keyword indices, and tables of contents, +respectively. +They are described in their own sets of documents, starting at the +docidx introduction and the doctoc introduction, +respectively.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_cmdref.html @@ -0,0 +1,528 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_lang_cmdref(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_cmdref - doctools language command reference

+
+ + +

Description

+

This document specifies both names and syntax of all the commands +which together are the doctools markup language, version 1. +As this document is intended to be a reference the commands are listed +in alphabetical order, and the descriptions are relatively short. +A beginner should read the much more informally written +doctools language introduction first.

+
+

Commands

+
+
arg text
+

Text markup. The argument text is marked up as the argument of +a command. Main uses are the highlighting of command arguments in +free-form text, and for the argument parameters of the markup commands +call and usage.

+
arg_def type name ?mode?
+

Text structure. List element. Argument list. Automatically closes the +previous list element. Specifies the data-type of the described +argument of a command, its name and its i/o-mode. The +latter is optional.

+
bullet
+

Deprecated. Text structure. List element. Itemized list. See +item for the canonical command to open a list item in an +itemized list.

+
call args
+

Text structure. List element. Definition list. Automatically closes +the previous list element. Defines the term as a command and its +arguments. +The first argument is the name of the command described by the +following free-form text, and all arguments coming after that are +descriptions of the command's arguments. +It is expected that the arguments are marked up with arg, +method, option etc., as is appropriate, and that the +command itself is marked up with cmd. +It is expected that the formatted term is not only printed in place, +but also in the table of contents of the document, or synopsis, +depending on the output format.

+
category text
+

Document information. Anywhere. This command registers its plain text +arguments as the category this document belongs to. If this command is +used multiple times the last value specified is used.

+
class text
+

Text markup. The argument is marked up as the name of a +class. The text may have other markup already applied to +it. Main use is the highlighting of class names in free-form text.

+
cmd text
+

Text markup. The argument text is marked up as the name of a +Tcl command. The text may have other markup already applied +to it. Main uses are the highlighting of commands in free-form text, +and for the command parameters of the markup commands call and +usage.

+
cmd_def command
+

Text structure. List element. Command list. Automatically closes the +previous list element. The argument specifies the name of the +Tcl command to be described by the list element. Expected to +be marked up in the output as if it had been formatted with cmd.

+
comment plaintext
+

Text markup. The argument text is marked up as a comment standing +outside of the actual text of the document. Main use is in free-form +text.

+
const text
+

Text markup. The argument is marked up as a constant value. The +text may have other markup already applied to it. Main use is the +highlighting of constants in free-form text.

+
copyright text
+

Document information. Anywhere. The command registers the plain text +argument as a copyright assignment for the manpage. When invoked more +than once the assignments are accumulated.

+
def text
+

Text structure. List element. Definition list. Automatically closes +the previous list element. The argument text is the term defined by +the new list element. Text markup can be applied to it.

+
description
+

Document structure. This command separates the header from the +document body. Implicitly starts a section named "DESCRIPTION" (See +command section).

+
enum
+

Text structure. List element. Enumerated list. Automatically closes +the previous list element.

+
emph text
+

Text markup. The argument text is marked up as emphasized. Main use is +for general highlighting of pieces of free-form text without attaching +special meaning to the pieces.

+
example text
+

Text structure, Text markup. This command marks its argument up as an +example. Main use is the simple embedding of examples in +free-form text. It should be used if the example does not need +special markup of its own. Otherwise use a sequence of +example_begin ... example_end.

+
example_begin
+

Text structure. This commands starts an example. All text until the +next example_end belongs to the example. Line breaks, spaces, +and tabs have to be preserved literally. Examples cannot be nested.

+
example_end
+

Text structure. This command closes the example started by the last +example_begin.

+
file text
+

Text markup. The argument is marked up as a file or +directory, i.e. in general a path. The text may have +other markup already applied to it. Main use is the highlighting of +paths in free-form text.

+
fun text
+

Text markup. The argument is marked up as the name of a +function. The text may have other markup already applied to +it. Main use is the highlighting of function names in free-form text.

+
image name ?label?
+

Text markup. The argument is the symbolic name of an image +and replaced with the image itself, if a suitable variant is found +by the backend. The second argument, should it be present, will be +interpreted the human-readable description of the image, and put +into the output in a suitable position, if such is supported by the +format. The HTML format, for example, can place it into the alt +attribute of image references.

+
include filename
+

Templating. The contents of the named file are interpreted as text +written in the doctools markup and processed in the place of the +include command. The markup in the file has to be self-contained. It +is not possible for a markup command to cross the file boundaries.

+
item
+

Text structure. List element. Itemized list. Automatically closes the +previous list element.

+
keywords args
+

Document information. Anywhere. This command registers all its plain text +arguments as keywords applying to this document. Each argument is a single +keyword. If this command is used multiple times all the arguments accumulate.

+
lb
+

Text. The command is replaced with a left bracket. Use in free-form text. +Required to avoid interpretation of a left bracket as the start of a markup +command.

+
list_begin what
+

Text structure. This command starts a list. The exact nature of the +list is determined by the argument what of the command. This +further determines which commands are have to be used to start the +list elements. Lists can be nested, i.e. it is allowed to start a new +list within a list element.

+

The allowed types (and their associated item commands) are:

+
+
arguments
+

arg_def.

+
commands
+

cmd_def.

+
definitions
+

def and call.

+
enumerated
+

enum

+
itemized
+

item

+
options
+

opt_def

+
tkoptions
+

tkoption_def

+
+

Additionally the following names are recognized as shortcuts for some +of the regular types:

+
+
args
+

Short for arguments.

+
cmds
+

Short for commands.

+
enum
+

Short for enumerated.

+
item
+

Short for itemized.

+
opts
+

Short for options.

+
+

At last the following names are still recognized for backward +compatibility, but are otherwise considered to be deprecated.

+
+
arg
+

Deprecated. See arguments.

+
bullet
+

Deprecated. See itemized.

+
cmd
+

Deprecated. See commands.

+
opt
+

Deprecated. See options.

+
tkoption
+

Deprecated. See tkoptions.

+
+
list_end
+

Text structure. This command closes the list opened by the last +list_begin command coming before it.

+
lst_item text
+

Deprecated. Text structure. List element. Definition list. See +def for the canonical command to open a general list item in a +definition list.

+
manpage_begin command section version
+

Document structure. The command to start a manpage. The arguments are +the name of the command described by the manpage, the +section of the manpages this manpage resides in, and the +version of the module containing the command. All arguments have +to be plain text, without markup.

+
manpage_end
+

Document structure. Command to end a manpage/document. Anything in the document +coming after this command is in error.

+
method text
+

Text markup. The argument text is marked up as the name of an +object method, i.e. subcommand of a Tcl command. The +text may have other markup already applied to it. Main uses are the +highlighting of method names in free-form text, and for the command +parameters of the markup commands call and usage.

+
moddesc text
+

Document information. Header. Registers the plain text argument as a short +description of the module the manpage resides in.

+
namespace text
+

Text markup. The argument text is marked up as a namespace name. The +text may have other markup already applied to it. Main use is the +highlighting of namespace names in free-form text.

+
nl
+

Deprecated. Text structure. See para for the canonical +command to insert paragraph breaks into the text.

+
opt text
+

Text markup. The argument text is marked up as optional. The text may +have other markup already applied to it. Main use is the highlighting of +optional arguments, see the command arg arg.

+
opt_def name ?arg?
+

Text structure. List element. Option list. Automatically closes the +previous list element. Specifies name and arguments of the +option described by the list element. It is expected that the +name is marked up using option.

+
option text
+

Text markup. The argument is marked up as option. The text may +have other markup already applied to it. Main use is the highlighting +of options, also known as command-switches, in either free-form text, +or the arguments of the call and usage commands.

+
package text
+

Text markup. The argument is marked up as the name of a +package. The text may have other markup already applied to +it. Main use is the highlighting of package names in free-form text.

+
para
+

Text structure. This command breaks free-form text into +paragraphs. Each command closes the paragraph coming before it and +starts a new paragraph for the text coming after it. Higher-level +forms of structure are sections and subsections.

+
rb
+

Text. The command is replaced with a right bracket. Use in free-form text. +Required to avoid interpretation of a right bracket as the end of a markup +command.

+
require package ?version?
+

Document information. Header. This command registers its argument +package as the name of a package or application required by the +described package or application. A minimum version can be provided as +well. This argument can be marked up. The usual markup is opt.

+
section name
+

Text structure. This command starts a new named document section. The +argument has to be plain text. Implicitly closes the last paragraph +coming before it and also implicitly opens the first paragraph of the +new section.

+
sectref id ?text?
+

Text markup. Formats a reference to the section identified by id. +If no text is specified the title of the referenced section is +used in the output, otherwise text is used.

+
sectref-external text
+

Text markup. Like sectref, except that the section is assumed to +be in a different document and therefore doesn't need to be identified, +nor are any checks for existence made. Only the text to format is needed.

+
see_also args
+

Document information. Anywhere. The command defines direct cross-references +to other documents. Each argument is a plain text label identifying the +referenced document. If this command is used multiple times all the arguments +accumulate.

+
strong text
+

Deprecated. Text markup. See emph for the canonical +command to emphasize text.

+
subsection name
+

Text structure. This command starts a new named subsection of a +section. The argument has to be plain text. Implicitly closes the last +paragraph coming before it and also implicitly opens the first +paragraph of the new subsection.

+
syscmd text
+

Text markup. The argument text is marked up as the name of an external +command. The text may have other markup already applied to it. Main +use is the highlighting of external commands in free-form text.

+
term text
+

Text markup. The argument is marked up as unspecific terminology. The +text may have other markup already applied to it. Main use is the +highlighting of important terms and concepts in free-form text.

+
titledesc desc
+

Document information. Header. Optional. Registers the plain text +argument as the title of the manpage. Defaults to the value registered +by moddesc.

+
tkoption_def name dbname dbclass
+

Text structure. List element. Widget option list. Automatically closes +the previous list element. Specifies the name of the option as +used in scripts, the name used by the option database (dbname), +and its class (dbclass), i.e. its type. It is expected that the +name is marked up using option.

+
type text
+

Text markup. The argument is marked up as the name of a +data type. The text may have other markup already applied to +it. Main use is the highlighting of data types in free-form text.

+
uri text ?text?
+

Text markup. The argument is marked up as an uri (i.e. a +uniform resource identifier. The text may have other markup +already applied to it. Main use is the highlighting of uris in +free-form text. The second argument, should it be present, will be +interpreted the human-readable description of the uri. In other words, +as its label. Without an explicit label the uri will be its own label.

+
usage args
+

Text markup. See call for the full description, this command is +syntactically identical, as it is in its expectations for the markup +of its arguments. +In contrast to call it is however not allowed to generate output +where this command occurs in the text. The command is silent. +The formatted text may only appear in a different section of the +output, for example a table of contents, or synopsis, depending on the +output format.

+
var text
+

Text markup. The argument is marked up as the name of a +variable. The text may have other markup already applied to +it. Main use is the highlighting of variables in free-form text.

+
vset varname value
+

Templating. In this form the command sets the named document variable +to the specified value. It does not generate output. I.e. the +command is replaced by the empty string.

+
vset varname
+

Templating. In this form the command is replaced by the value of the +named document variable

+
widget text
+

Text markup. The argument is marked up as the name of a +widget. The text may have other markup already applied to +it. Main use is the highlighting of widget names in free-form text.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_faq.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_lang_faq(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_faq - doctools language faq

+
+ + +

OVERVIEW

+

What is this document?

+

This document is currently mainly a placeholder, to be filled with +commonly asked questions about the doctools markup language +and companions, and their answers.

+

Please report any questions (and, if possible, answers) we should +consider for this document as explained in the section +Bugs, Ideas, Feedback below.

+
+
+

EXAMPLES

+

Where do I find doctools examples?

+

We have no direct examples of documents written using doctools +markup. However the doctools processor dtplite does generate +a table of contents when processing a set of documents written in +doctools markup. The intermediate file for it uses doctools +markup and is not deleted when generation completes. Such files can +therefore serve as examples.

+

dtplite is distributed as part of Tcllib, so to get it you +need one of

+
    +

  1. A snapshot of Tcllib. How to retrieve such a snapshot and the +tools required for this are described at +Development Snapshots

    2. +

  2. A Tcllib release archive. They are available at the home +page.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html @@ -0,0 +1,637 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_lang_intro(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_intro - doctools language introduction

+
+ +

Description

+

This document is an informal introduction to version 1 of the doctools +markup language based on a multitude of examples. After reading this a +writer should be ready to understand the two parts of the formal +specification, i.e. the doctools language syntax specification +and the doctools language command reference.

+

Fundamentals

+

In the broadest terms possible the doctools markup language +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it.

+

Each markup command is a Tcl command surrounded by a matching pair of +[ and ]. Inside of these delimiters the usual +rules for a Tcl command apply with regard to word quotation, nested +commands, continuation lines, etc. I.e.

+
+  ... [list_begin enumerated] ...
+
+
+  ... [call [cmd foo] \\
+          [arg bar]] ...
+
+
+  ... [term {complex concept}] ...
+
+
+  ... [opt "[arg key] [arg value]"] ...
+
+
+

Basic structure

+

The most simple document which can be written in doctools is

+
+    [manpage_begin NAME SECTION VERSION]
+[see_also doctools_intro]
+[see_also doctools_lang_cmdref]
+[see_also doctools_lang_faq]
+[see_also doctools_lang_syntax]
+[keywords {doctools commands}]
+[keywords {doctools language}]
+[keywords {doctools markup}]
+[keywords {doctools syntax}]
+[keywords markup]
+[keywords {semantic markup}]
+    [description]
+    [vset CATEGORY doctools]
+[include ../doctools2base/include/feedback.inc]
+[manpage_end]
+
+

This also shows us that all doctools documents are split into two +parts, the header and the body. Everything coming before +[description] belongs to the header, and everything coming +after belongs to the body, with the whole document bracketed by the +two manpage_* commands. Before and after these opening and +closing commands we have only whitespace.

+

In the remainder of this section we will discuss only the contents of +the header, the structure of the body will be discussed in the section +Text structure.

+

The header section can be empty, and otherwise may contain only an +arbitrary sequence of the four so-called header commands, plus +whitespace. These commands are

+
+
titledesc
+
+
moddesc
+
+
require
+
+
copyright
+
+
+

They provide, through their arguments, additional information about +the document, like its title, the title of the larger group the +document belongs to (if applicable), the requirements of the +documented packages (if applicable), and copyright assignments. All of +them can occur multiple times, including none, and they can be used in +any order. +However for titledesc and moddesc only the last occurrence +is taken. For the other two the specified information is accumulated, +in the given order. Regular text is not allowed within the header.

+

Given the above a less minimal example of a document is

+
+[manpage_begin NAME SECTION VERSION]
+[copyright {YEAR AUTHOR}]
+[titledesc TITLE]
+[moddesc   MODULE_TITLE]
+[require   PACKAGE VERSION]
+[require   PACKAGE]
+[description]
+[manpage_end]
+
+

Remember that the whitespace is optional. The document

+
+    [manpage_begin NAME SECTION VERSION]
+[see_also doctools_intro]
+[see_also doctools_lang_cmdref]
+[see_also doctools_lang_faq]
+[see_also doctools_lang_syntax]
+[keywords {doctools commands}]
+[keywords {doctools language}]
+[keywords {doctools markup}]
+[keywords {doctools syntax}]
+[keywords markup]
+[keywords {semantic markup}]
+    [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
+    [require PACKAGE VERSION][require PACKAGE][description]
+    [vset CATEGORY doctools]
+[include ../doctools2base/include/feedback.inc]
+[manpage_end]
+
+

has the same meaning as the example before.

+

On the other hand, if whitespace is present it consists not +only of any sequence of characters containing the space character, +horizontal and vertical tabs, carriage return, and newline, but it may +contain comment markup as well, in the form of the comment +command.

+
+[comment { ... }]
+[manpage_begin NAME SECTION VERSION]
+[copyright {YEAR AUTHOR}]
+[titledesc TITLE]
+[moddesc   MODULE_TITLE][comment { ... }]
+[require   PACKAGE VERSION]
+[require   PACKAGE]
+[description]
+[manpage_end]
+[comment { ... }]
+
+
+

Advanced structure

+

In the simple examples of the last section we fudged a bit regarding +the markup actually allowed to be used before the manpage_begin +command opening the document.

+

Instead of only whitespace the two templating commands include +and vset are also allowed, to enable the writer to either set +and/or import configuration settings relevant to the document. I.e. it +is possible to write

+
+[include FILE]
+[vset VAR VALUE]
+[manpage_begin NAME SECTION VERSION]
+[description]
+[manpage_end]
+
+

Even more important, these two commands are allowed anywhere where a +markup command is allowed, without regard for any other +structure. I.e. for example in the header as well.

+
+[manpage_begin NAME SECTION VERSION]
+[include FILE]
+[vset VAR VALUE]
+[description]
+[manpage_end]
+
+

The only restriction include has to obey is that the contents of +the included file must be valid at the place of the inclusion. I.e. a +file included before manpage_begin may contain only the +templating commands vset and include, a file included in +the header may contain only header commands, etc.

+
+

Text structure

+

The body of the document consists mainly of text, possibly split into +sections, subsections, and paragraphs, with parts marked up to +highlight various semantic categories of text, and additional +structure through the use of examples and (nested) lists.

+

This section explains the high-level structural commands, with +everything else deferred to the following sections.

+

The simplest way of structuring the body is through the introduction +of paragraphs. The command for doing so is para. Each occurrence +of this command closes the previous paragraph and automatically opens +the next. The first paragraph is automatically opened at the beginning +of the body, by description. In the same manner the last +paragraph automatically ends at manpage_end.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[para]
+ ...
+[para]
+ ...
+[manpage_end]
+
+

Empty paragraphs are ignored.

+

A structure coarser than paragraphs are sections, which allow the +writer to split a document into larger, and labeled, pieces. The +command for doing so is section. Each occurrence of this command +closes the previous section and automatically opens the next, +including its first paragraph. The first section is automatically +opened at the beginning of the body, by description (This +section is labeled "DESCRIPTION"). In the same manner the last section +automatically ends at manpage_end.

+

Empty sections are not ignored. We are free to (not) use +paragraphs within sections.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[section {Section A}]
+ ...
+[para]
+ ...
+[section {Section B}]
+ ...
+[manpage_end]
+
+

Between sections and paragraphs we have subsections, to split sections. +The command for doing so is subsection. Each occurrence of this +command closes the previous subsection and automatically opens the +next, including its first paragraph. A subsection is automatically +opened at the beginning of the body, by description, and at the +beginning of each section. In the same manner the last subsection +automatically ends at manpage_end.

+

Empty subsections are not ignored. We are free to (not) use +paragraphs within subsections.

+
+[manpage_begin NAME SECTION VERSION]
+[description]
+ ...
+[section {Section A}]
+ ...
+[subsection {Sub 1}]
+ ...
+[para]
+ ...
+[subsection {Sub 2}]
+ ...
+[section {Section B}]
+ ...
+[manpage_end]
+
+
+

Text markup

+

Having handled the overall structure a writer can impose on the +document we now take a closer at the text in a paragraph.

+

While most often this is just the unadorned content of the document we +do have situations where we wish to highlight parts of it as some type +of thing or other, like command arguments, command names, concepts, +uris, etc.

+

For this we have a series of markup commands which take the text to +highlight as their single argument. It should be noted that while +their predominant use is the highlighting of parts of a paragraph they +can also be used to mark up the arguments of list item commands, and +of other markup commands.

+

The commands available to us are

+
+
arg
+

Its argument is a the name of a command argument.

+
class
+

Its argument is a class name.

+
cmd
+

Its argument is a command name (Tcl command).

+
const
+

Its argument is a constant.

+
emph
+

General, non-semantic emphasis.

+
file
+

Its argument is a filename / path.

+
fun
+

Its argument is a function name.

+
method
+

Its argument is a method name

+
namespace
+

Its argument is namespace name.

+
opt
+

Its argument is some optional syntax element.

+
option
+

Its argument is a command line switch / widget option.

+
package
+

Its argument is a package name.

+
sectref
+

Its argument is the title of a section or subsection, + i.e. a section reference.

+
syscmd
+

Its argument is a command name (external, system command).

+
term
+

Its argument is a concept, or general terminology.

+
type
+

Its argument is a type name.

+
uri
+

Its argument is a uniform resource identifier, i.e an + external reference. A second argument can be used + to specify an explicit label for the reference in + question.

+
usage
+

The arguments describe the syntax of a Tcl command.

+
var
+

Its argument is a variable.

+
widget
+

Its argument is a widget name.

+
+

The example demonstrating the use of text markup is an excerpt from +the doctools language command reference, with some +highlighting added. +It shows their use within a block of text, as the arguments of a list +item command (call), and our ability to nest them.

+
+  ...
+  [call [cmd arg_def] [arg type] [arg name]] [opt [arg mode]]]
+  Text structure. List element. Argument list. Automatically closes the
+  previous list element. Specifies the data-[arg type] of the described
+  argument of a command, its [arg name] and its i/o-[arg mode]. The
+  latter is optional.
+  ...
+
+
+

Escapes

+

Beyond the 20 commands for simple markup shown in the previous section +we have two more available which are technically simple markup. +However their function is not the marking up of phrases as specific +types of things, but the insertion of characters, namely [ +and ]. +These commands, lb and rb respectively, are required +because our use of [ and ] to bracket markup commands makes it +impossible to directly use [ and ] within the text.

+

Our example of their use are the sources of the last sentence in the +previous paragraph, with some highlighting added.

+
+  ...
+  These commands, [cmd lb] and [cmd lb] respectively, are required
+  because our use of [lb] and [rb] to bracket markup commands makes it
+  impossible to directly use [lb] and [rb] within the text.
+  ...
+
+
+

Cross-references

+

The last two commands we have to discuss are for the declaration of +cross-references between documents, explicit and implicit. They are +keywords and see_also. Both take an arbitrary number of +arguments, all of which have to be plain unmarked text. I.e. it is not +allowed to use markup on them. Both commands can be used multiple +times in a document. If that is done all arguments of all occurrences +of one of them are put together into a single set.

+
+
keywords
+

The arguments of this command are interpreted as keywords describing +the document. A processor can use this information to create an index +indirectly linking the containing document to all documents with the +same keywords.

+
see_also
+

The arguments of this command are interpreted as references to other +documents. A processor can format them as direct links to these +documents.

+
+

All the cross-reference commands can occur anywhere in the document +between manpage_begin and manpage_end. As such the writer +can choose whether she wants to have them at the beginning of the +body, or at its end, maybe near the place a keyword is actually +defined by the main content, or considers them as meta data which +should be in the header, etc.

+

Our example shows the sources for the cross-references of this +document, with some highlighting added. Incidentally they are found +at the end of the body.

+
+  ...
+  [see_also doctools_intro]
+  [see_also doctools_lang_syntax]
+  [see_also doctools_lang_cmdref]
+  [keywords markup {semantic markup}]
+  [keywords {doctools markup} {doctools language}]
+  [keywords {doctools syntax} {doctools commands}]
+  [manpage_end]
+
+
+

Examples

+

Where ever we can write plain text we can write examples too. For +simple examples we have the command example which takes a single +argument, the text of the argument. The example text must not contain +markup. If we wish to have markup within an example we have to use the +2-command combination example_begin / example_end instead.

+

The first opens an example block, the other closes it, and in between +we can write plain text and use all the regular text markup commands. +Note that text structure commands are not allowed. This also means +that it is not possible to embed examples and lists within an example. +On the other hand, we can use templating commands within +example blocks to read their contents from a file (Remember section +Advanced structure).

+

The source for the very first example in this document (see section +Fundamentals), with some highlighting added, is

+
+  [example {
+    ... [list_begin enumerated] ...
+  }]
+
+

Using example_begin / example_end this would look like

+
+  [example_begin]
+    ... [list_begin enumerated] ...
+  [example_end]
+
+
+

Lists

+

Where ever we can write plain text we can write lists too. The main +commands are list_begin to start a list, and list_end to +close one. The opening command takes an argument specifying the type +of list started it, and this in turn determines which of the eight +existing list item commands are allowed within the list to start list +items.

+

After the opening command only whitespace is allowed, until the first +list item command opens the first item of the list. Each item is a +regular series of paragraphs and is closed by either the next list +item command, or the end of the list. If closed by a list item command +this command automatically opens the next list item. A consequence of +a list item being a series of paragraphs is that all regular text +markup can be used within a list item, including examples and other +lists.

+

The list types recognized by list_begin and their associated +list item commands are:

+
+
arguments
+

(arg_def) This opens an argument (declaration) list. It +is a specialized form of a term definition list where the term is an +argument name, with its type and i/o-mode.

+
commands
+

(cmd_def) This opens a command (declaration) list. It +is a specialized form of a term definition list where the term is a +command name.

+
definitions
+

(def and call) This opens a general +term definition list. The terms defined by the list items are +specified through the argument(s) of the list item commands, either +general terms, possibly with markup (def), or Tcl commands with +their syntax (call).

+
enumerated
+

(enum) This opens a general enumerated list.

+
itemized
+

(item) +This opens a general itemized list.

+
options
+

(opt_def) This opens an option (declaration) list. It +is a specialized form of a term definition list where the term is an +option name, possibly with the option's arguments.

+
tkoptions
+

(tkoption_def) This opens a +widget option (declaration) list. It is a specialized form of +a term definition list where the term is the name of a configuration +option for a widget, with its name and class in the option database.

+
+

Our example is the source of the definition list in the previous +paragraph, with most of the content in the middle removed.

+
+  ...
+  [list_begin definitions]
+  [def [const arg]]
+  ([cmd arg_def]) This opens an argument (declaration) list. It is a
+  specialized form of a definition list where the term is an argument
+  name, with its type and i/o-mode.
+  [def [const itemized]]
+  ([cmd item])
+  This opens a general itemized list.
+  ...
+  [def [const tkoption]]
+  ([cmd tkoption_def]) This opens a widget option (declaration) list. It
+  is a specialized form of a definition list where the term is the name
+  of a configuration option for a widget, with its name and class in the
+  option database.
+  [list_end]
+  ...
+
+

Note that a list cannot begin in one (sub)section and end in +another. Differently said, (sub)section breaks are not allowed within +lists and list items. An example of this illegal construct is

+
+  ...
+  [list_begin itemized]
+  [item]
+  ...
+  [section {ILLEGAL WITHIN THE LIST}]
+  ...
+  [list_end]
+  ...
+
+
+
+

FURTHER READING

+

Now that this document has been digested the reader, assumed to be a +writer of documentation should be fortified enough to be able +to understand the formal doctools language syntax +specification as well. From here on out the +doctools language command reference will also serve as the +detailed specification and cheat sheet for all available commands and +their syntax.

+

To be able to validate a document while writing it, it is also +recommended to familiarize oneself with one of the applications for +the processing and conversion of doctools documents, i.e. either +Tcllib's easy and simple dtplite, or Tclapps' +ultra-configurable dtp.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html Index: embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html +++ embedded/www/tcllib/files/modules/doctools/doctools_lang_syntax.html @@ -0,0 +1,225 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_lang_syntax(n) 1.0 tcllib "Documentation tools"

+

Name

+

doctools_lang_syntax - doctools language syntax

+
+ +

Description

+

This document contains the formal specification of the syntax of the +doctools markup language, version 1 in Backus-Naur-Form. This document +is intended to be a reference, complementing the +doctools language command reference. +A beginner should read the much more informally written +doctools language introduction first before trying to +understand either this document or the command reference.

+
+

Fundamentals

+

In the broadest terms possible the doctools markup language +is LaTeX-like, instead of like SGML and similar languages. A document +written in this language consists primarily of text, with markup +commands embedded into it.

+

Each markup command is a just Tcl command surrounded by a matching +pair of [ and ]. Which commands are available, +and their arguments, i.e. syntax is specified in the +doctools language command reference.

+

In this document we specify first the lexeme, and then the syntax, +i.e. how we can mix text and markup commands with each other.

+
+

Lexical definitions

+

In the syntax rules listed in the next section

+
    +

  1. <TEXT> stands for all text except markup commands.

    2. +

  2. Any XXX stands for the markup command [xxx] including its +arguments. Each markup command is a Tcl command surrounded by a +matching pair of [ and ]. Inside of these +delimiters the usual rules for a Tcl command apply with regard to word +quotation, nested commands, continuation lines, etc.

    3. +

  3. <WHITE> stands for all text consisting only of spaces, newlines, +tabulators and the comment markup command.

    4. +
+
+

Syntax

+

The rules listed here specify only the syntax of doctools +documents. The lexical level of the language was covered in the +previous section.

+

Regarding the syntax of the (E)BNF itself

+
    +

  1. The construct { X } stands for zero or more occurrences of X.

    2. +

  2. The construct [ X ] stands for zero or one occurrence of X.

    3. +

  3. The construct LIST_BEGIN<X> stands for the markup command +list_begin with X as its type argument.

    4. +
+

The syntax:

+
+manpage = defs
+          MANPAGE_BEGIN
+          header
+          DESCRIPTION
+          body
+          MANPAGE_END
+          { <WHITE> }
+defs    = { INCLUDE | VSET | <WHITE> }
+header  = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
+xref    = KEYWORDS | SEE_ALSO | CATEGORY
+body    = paras { SECTION    sbody  }
+sbody   = paras { SUBSECTION ssbody }
+ssbody  = paras
+paras   = tblock { (PARA | NL) tblock }
+tblock  = { <TEXT> | defs | markup | xref | an_example | a_list }
+markup  = ARG     | CLASS | CMD     | CONST     | EMPH   | FILE
+        | FUN     | LB    | METHOD  | NAMESPACE | OPT    | OPTION
+        | PACKAGE | RB    | SECTREF | STRONG    | SYSCMD | TERM
+        | TYPE    | URI   | USAGE   | VAR       | WIDGET
+example = EXAMPLE
+        | EXAMPLE_BEGIN extext EXAMPLE_END
+extext  = { <TEXT> | defs | markup }
+a_list  = LIST_BEGIN<arguments>   argd_list   LIST_END
+        | LIST_BEGIN<commands>    cmdd_list   LIST_END
+        | LIST_BEGIN<definitions> def_list    LIST_END
+        | LIST_BEGIN<enumerated>  enum_list   LIST_END
+        | LIST_BEGIN<itemized>    item_list   LIST_END
+        | LIST_BEGIN<options>     optd_list   LIST_END
+        | LIST_BEGIN<tkoptions>   tkoptd_list LIST_END
+argd_list   = [ <WHITE> ] { ARG_DEF      paras }
+cmdd_list   = [ <WHITE> ] { CMD_DEF      paras }
+def_list    = [ <WHITE> ] { (DEF|CALL)   paras }
+enum_list   = [ <WHITE> ] { ENUM         paras }
+item_list   = [ <WHITE> ] { ITEM         paras }
+optd_list   = [ <WHITE> ] { OPT_DEF      paras }
+tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html Index: embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html +++ embedded/www/tcllib/files/modules/doctools/doctools_plugin_apiref.html @@ -0,0 +1,485 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools_plugin_apiref(n) 1.1 tcllib "Documentation tools"

+

Name

+

doctools_plugin_apiref - doctools plugin API reference

+
+ + +

Description

+

This document is intended for plugin writers, i.e. developers +wishing to write a doctools formatting engine for some output +format X.

+

It specifies the interaction between the doctools package +and its plugins, i.e. the interface any doctools formatting engine has +to comply with.

+

This document deals with version 1 of the interface.

+

A reader who is on the other hand more interested in the markup +language itself should start with the +doctools language introduction and proceed from there to the +formal specifications, i.e. the doctools language syntax and +the doctools language command reference.

+
+

OVERVIEW

+

The API for a doctools formatting engine consists of two major +sections.

+

On the one side we have a set of commands through which the plugin is +able to query the frontend. These commands are provided by the +frontend and linked into the plugin interpreter. Please see section +FRONTEND COMMANDS for their detailed specification.

+

And on the other side the plugin has to provide its own set of +commands which will then be called by the frontend in a specific +sequence while processing input. They, again, fall into two +categories, management and formatting. +Please see section PLUGIN COMMANDS and its subsections for +their detailed specification.

+
+

FRONTEND COMMANDS

+

This section specifies the set of commands through which a plugin, +also known as a doctools formatting engine, is able to query the +frontend. These commands are provided by the frontend and linked into +the plugin interpreter.

+

I.e. a doctools formatting engine can assume that all of the following +commands are present when any of its own commands (as specified in +section PLUGIN COMMANDS) are executed.

+

Beyond that it can also assume that it has full access to its own safe +interpreter and thus is not able to damage the other parts of the +processor, nor can it damage the filesystem. +It is however able to either kill or hang the whole process, by +exiting, or running an infinite loop.

+

Coming back to the imported commands, all the commands with prefix +dt_ provide limited access to specific parts of the frontend, +whereas the commands with prefix ex_ provide access to the +state of the textutil::expander object which does the main +parsing of the input within the frontend. These commands should not be +except under very special circumstances.

+
+
dt_copyright
+

Query command. It returns a string containing the copyright +information the doctools processor was configured with. The relevant +option is -copyright).

+
dt_file
+

Query command. It returns the full path of the file containing the +input currently processed by the engine. This may be an included file.

+
dt_mainfile
+

Query command. It returns the full path of the toplevel file containing +the input currently processed by the engine.

+
dt_fileid
+

Query command. It returns the name of the file containing the input +currently processed by the engine, without path, nor extension.

+
dt_fmap symfname
+

Query command. It returns the actual pathname to use in the output in +place of the symbolic filename symfname. It will return the +unchanged input if no mapping was established for symfname.

+

The required mappings are established with the method map of +a frontend, as explained in section OBJECT METHODS +of the documentation for the package doctools.

+
dt_format
+

Query command. It returns the name of the format associated with the +doctools formatting engine.

+
dt_imgdata key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its data is returned as the result of the +command. Otherwise an empty string is returned.

+
dt_imgdst key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its destination path in the output is returned +as the result of the command. Otherwise an empty string is returned.

+
dt_imgsrc key extensions
+

Query command. Access to the image map. Looks for an image recorded +under the key and having on the specified extension. If a +matching image is found its origin path is returned as the result of +the command. Otherwise an empty string is returned.

+
dt_lnesting
+

Query command. It returns the number of lists currently open.

+
dt_module
+

Query command. It returns the name of the module the input currently +processed belongs to.

+
dt_read file
+

Controlled filesystem access. Returns contents of file for +whatever use desired by the plugin. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_source file
+

Controlled filesystem access. This command allows the doctools +formatting engine to load additional Tcl code it may need. +Only files which are either in the same directory as the file +containing the engine, or below it, can be loaded. Trying to load a +file outside of this directory causes an error.

+
dt_user
+

Query command. It returns the name of the current user as known to the +tcl interpreter the frontend controlling the formatting engine resides +in.

+
ex_cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
ex_cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
ex_cis cname
+

Determines whether or not the name of the current context is +cname.

+
ex_cname
+

Returns the name of the current context.

+
ex_cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
ex_cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
ex_cset varname value
+

Sets variable varname to value in the current context.

+
ex_lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
ex_rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
+
+

PLUGIN COMMANDS

+

The plugin has to provide its own set of commands which will then be +called by the frontend in a specific sequence while processing +input. They fall into two categories, management and formatting. Their +expected names, signatures, and responsibilities are specified in the +following two subsections.

+

Management commands

+

The management commands a plugin has to provide are used by the +frontend to

+
    +

  1. initialize and shutdown the plugin

    2. +

  2. determine the number of passes it has + to make over the input

    3. +

  3. initialize and shutdown each pass

    4. +

  4. query and initialize engine parameters

    5. +
+

After the plugin has been loaded and the frontend commands are +established the commands will be called in the following sequence:

+
+    fmt_numpasses -> n
+    fmt_listvariables -> vars
+    fmt_varset var1 value1
+    fmt_varset var2 value2
+    ...
+    fmt_varset varK valueK
+    fmt_initialize
+    fmt_setup 1
+    ...
+    fmt_setup 2
+    ...
+    ...
+    fmt_setup n
+    ...
+    fmt_postprocess
+    fmt_shutdown
+    ...
+
+

I.e. first the number of passes and the set of available engine +parameters is established, followed by calls setting the +parameters. That second part is optional.

+

After that the plugin is initialized, the specified number of passes +executed, the final result run through a global post processing step +and at last the plugin is shutdown again. This can be followed by more +conversions, restarting the sequence at fmt_varset.

+

In each of the passes, i.e. after the calls of fmt_setup the +frontend will process the input and call the formatting commands as +markup is encountered. This means that the sequence of formatting +commands is determined by the grammar of the doctools markup language, +as specified in the doctools language syntax specification.

+

A different way of looking at the sequence is:

+
    +

  • First some basic parameters are determined.

    • +

  • Then everything starting at the first fmt_varset to +fmt_shutdown forms a run, the formatting of a +single input. Each run can be followed by more.

    • +

  • Embedded within each run we have one or more passes, +each starting with fmt_setup and going until either the next +fmt_setup or fmt_postprocess is reached.

    +

    If more than one pass is required to perform the formatting only the +output of the last pass is relevant. The output of all the previous, +preparatory passes is ignored.

    • +
+

The commands, their names, signatures, and responsibilities are, in +detail:

+
+
fmt_initialize
+

Initialization/Shutdown. +This command is called at the beginning of every conversion run, as +the first command of that run. Note that a run is not a pass, but may +consist of multiple passes. +It has to initialize the general state of the plugin, beyond the +initialization done during the load. No return value is expected, and +any returned value is ignored.

+
fmt_listvariables
+

Initialization/Shutdown and Engine parameters. +Second command is called after the plugin code has been loaded, +i.e. immediately after fmt_numpasses. +It has to return a list containing the names of the parameters the +frontend can set to configure the engine. This list can be empty.

+
fmt_numpasses
+

Initialization/Shutdown and Pass management. +First command called after the plugin code has been loaded. No other +command of the engine will be called before it. +It has to return the number of passes this engine requires to fully +process the input document. This value has to be an integer number +greater or equal to one.

+
fmt_postprocess text
+

Initialization/Shutdown. +This command is called immediately after the last pass in a run. Its +argument is the result of the conversion generated by that pass. It is +provided to allow the engine to perform any global modifications of +the generated document. If no post-processing is required for a +specific format the command has to just return the argument.

+

Expected to return a value, the final result of formatting the input.

+
fmt_setup n
+

Initialization/Shutdown and Pass management. +This command is called at the beginning of each pass over the input in +a run. Its argument is the number of the pass which has begun. Passes +are counted from 1 upward. +The command has to set up the internal state of the plugin for this +particular pass. No return value is expected, and any returned value +is ignored.

+
fmt_shutdown
+

Initialization/Shutdown. +This command is called at the end of every conversion run. It is the +last command called in a run. It has to clean up of all the +run-specific state in the plugin. +After the call the engine has to be in a state which allows the +initiation of another run without fear that information from the last +run is leaked into this new run. +No return value is expected, and any returned value is ignored.

+
fmt_varset varname text
+

Engine parameters. +This command is called by the frontend to set an engine parameter to a +particular value. +The parameter to change is specified by varname, the value to +set in text.

+

The command has to throw an error if an unknown varname is +used. Only the names returned by fmt_listvariables have to be +considered as known.

+

The values of all engine parameters have to persist between passes and +runs.

+
+
+

Formatting commands

+

The formatting commands have to implement the formatting for the +output format, for all the markup commands of the doctools markup +language, except lb, rb, vset, include, and +comment. These exceptions are processed by the frontend and are +never seen by the plugin. In return a command for the formatting of +plain text has to be provided, something which has no markup in the +input at all.

+

This means, that each of the 49 markup commands specified in the +doctools language command reference and outside of the set of +exceptions listed above has an equivalent formatting command which +takes the same arguments as the markup command and whose name is the +name of markup command with the prefix fmt_ added to it.

+

All commands are expected to format their input in some way per the +semantics specified in the command reference and to return whatever +part of this that they deem necessary as their result, which will be +added to the output.

+

To avoid essentially duplicating the command reference we do not list +any of the command here and simply refer the reader to the +doctools language command reference for their signature and +description. The sole exception is the plain text formatter, which has +no equivalent markup command.

+

The calling sequence of formatting commands is not as rigid as for the +management commands, but determined by the grammar of the doctools +markup language, as specified in the doctools language syntax +specification.

+
+
fmt_plain_text text
+

No associated markup command.

+

Called by the frontend for any plain text encountered in the +input. It has to perform any and all special processing required for +plain text.

+

The formatted text is expected as the result of the command, +and added to the output. If no special processing is required it has +to simply return its argument without change.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools/mpexpand.html Index: embedded/www/tcllib/files/modules/doctools/mpexpand.html ================================================================== --- embedded/www/tcllib/files/modules/doctools/mpexpand.html +++ embedded/www/tcllib/files/modules/doctools/mpexpand.html @@ -0,0 +1,193 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

mpexpand(n) 1.0 tcllib "Documentation toolbox"

+

Name

+

mpexpand - Markup processor

+
+ + +

Description

+

This manpage describes a processor / converter for manpages in the +doctools format as specified in doctools_fmt. The processor +is based upon the package doctools.

+
+
mpexpand ?-module module? format infile|- outfile|-
+

The processor takes three arguments, namely the code describing which +formatting to generate as the output, the file to read the markup +from, and the file to write the generated output into. If the +infile is "-" the processor will read from +stdin. If outfile is "-" the processor will +write to stdout.

+

If the option -module is present its value overrides the internal +definition of the module name.

+

The currently known output formats are

+
+
nroff
+

The processor generates *roff output, the standard format for unix +manpages.

+
html
+

The processor generates HTML output, for usage in and display by web +browsers.

+
tmml
+

The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML.

+
latex
+

The processor generates LaTeX output.

+
wiki
+

The processor generates Wiki markup as understood by wikit.

+
list
+

The processor extracts the information provided by manpage_begin.

+
null
+

The processor does not generate any output.

+
+
mpexpand.all ?-verbose? ?module?
+

This command uses mpexpand to generate all possible output +formats for all manpages in the current directory. The manpages are +recognized through the extension ".man". If -verbose is +specified the command will list its actions before executing them.

+

The module information is passed to mpexpand.

+
+
+

NOTES

+

Possible future formats are plain text, pdf and postscript.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

expander(n), format(n), formatter(n)

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html Index: embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html +++ embedded/www/tcllib/files/modules/doctools2base/html_cssdefaults.html @@ -0,0 +1,161 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::html::cssdefaults(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::html::cssdefaults - Default CSS style for HTML export plugins

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::html::cssdefaults ?0.1?
    • +
+ +
+
+

Description

+

This package provides a single command providing access to the text of +the default CSS style to use for HTML markup generated by the various +HTML export plugins.

+

This is an internal package of doctools, for use by export plugins, +i.e. the packages converting doctools related documented into other +formats, most notably HTML.

+
+

API

+
+
::doctools::html::cssdefaults::contents
+

This command returns the text of the default CSS style to use for HTML +markup generated by the various HTML export plugins.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html Index: embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html +++ embedded/www/tcllib/files/modules/doctools2base/nroff_manmacros.html @@ -0,0 +1,161 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::nroff::man_macros(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::nroff::man_macros - Default CSS style for NROFF export plugins

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::nroff::man_macros ?0.1?
    • +
+ +
+
+

Description

+

This package provides a single command providing access to the +definition of the nroff man macro set to use for NROFF markup +generated by the various NROFF export plugins.

+

This is an internal package of doctools, for use by export plugins, +i.e. the packages converting doctools related documented into other +formats, most notably nroff.

+
+

API

+
+
::doctools::nroff::man_macros::contents
+

This command returns the text of the default CSS style to use for NROFF +generated by the various NROFF export plugins.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html Index: embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html +++ embedded/www/tcllib/files/modules/doctools2base/tcl_parse.html @@ -0,0 +1,264 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::tcl::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::tcl::parse - Processing text in 'subst -novariables' format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
  • package require struct::set
    • +
  • package require treeql
    • +
  • package require doctools::tcl::parse
    • +
+ +
+
+

Description

+

This package provides commands for parsing text with embedded Tcl +commands as accepted by the Tcl builtin command +subst -novariables. The result of the parsing is an abstract +syntax tree.

+

This is an internal package of doctools, for use by the higher level +parsers processing the docidx, doctoc, and doctools +markup languages.

+
+

API

+
+
::doctools::tcl::parse text tree text ?root?
+

The command takes the text and parses it under the assumption +that it contains a string acceptable to the Tcl builtin command +subst -novariables. Errors are thrown otherwise during the +parsing. The format used for these errors in described in section +Error format.

+

The command returns the empty string as it result. The actual result +of the parsing is entered into the tree structure tree, under +the node root. +If root is not specified the root of tree is used. The +tree has to exist and be the command of a tree object which +supports the same methods as trees created by the package +struct::tree.

+

In case of errors tree will be left in an undefined state.

+
::doctools::tcl::parse file tree path ?root?
+

The same as text, except that the text to parse is read from +the file specified by path.

+
+
+

Error format

+

When the parser encounters a problem in the input +it will throw an error using the format described +here.

+
    +

  1. The message will contain the reason for the problem (unexpected +character or end of input in input), the character in question, if +any, and the line and column the problem was found at, in a human +readable form. This part is not documented further as its format may +change as we see fit. It is intended for human consumption, not +machine.

    2. +

  2. The error code however will contain a machine-readable representation +of the problem, in the form of a 5-element list containing, in the +order listed below

    +
      +

    1. the constant string doctools::tcl::parse

      2. +

    2. the cause of the problem, one of

      +
      +
      char
      +

      Unexpected character in input

      +
      eof
      +

      Unexpected end of the input

      +
      +
      3. +

    3. The location of the problem as offset from the beginning of the input, +counted in characters. Note: Line markers count as one character.

      4. +

    4. The line the problem was found on (counted from 1 (one)),

      5. +

    5. The column the problem was found at (counted from 0 (zero))

      6. +
    +
    3. +
+
+

Tree Structure

+

After successfully parsing a string the generated tree will have the +following structure:

+
    +

  1. In the following items the word 'root' refers to the node which was +specified as the root of the tree when invoking either text +or file. This may be the actual root of the tree.

    2. +

  2. All the following items further ignore the possibility of pre-existing +attributes in the pre-existing nodes. If attributes exists with the +same names as the attributes used by the parser the pre-existing +values are written over. Attributes with names not clashing with the +parser's attributes are not touched.

    3. +

  3. The root node has no attributes.

    4. +

  4. All other nodes have the attributes

    +
    +
    type
    +

    The value is a string from the set { Command , Text , Word }

    +
    range
    +

    The value is either empty or a 2-element list containing integer +numbers. The numbers are the offsets of the first and last character +in the input text, of the token described by the node,.

    +
    line
    +

    The value is an integer, it describes the line in the input the token +described by the node ends on. Lines are counted from 1 (one).

    +
    col
    +

    The value is an integer, it describes the column in the line in the +input the token described by the node ends on. Columns are counted +from 0 (zero).

    +
    +
    5. +

  5. The children of the root, if any, are of type Command and Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node.

    6. +

  6. The children of a Command node, if any, are of type Command, and Text, +and Word, they describe the arguments of the command.

    7. +

  7. The children of a Word node, if any, are of type Command, Text, in +semi-alternation. This means: After a Text node a Command node has to +follow, and anything can follow a Command node, a Text or other +Command node.

    8. +

  8. A Word node without children represents the empty string.

    9. +

  9. All Text nodes are leaves of the tree.

    10. +

  10. All leaves of the tree are either Text or Command nodes. +Word nodes cannot be leaves.

    11. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html Index: embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html +++ embedded/www/tcllib/files/modules/doctools2base/tcllib_msgcat.html @@ -0,0 +1,177 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat - Message catalog management for the various document parsers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat ?0.1?
    • +
+ +
+
+

Description

+

The package doctools::msgcat is a support module handling +the selection of message catalogs for the various document processing +packages in the doctools system version 2. As such it is an internal +package a regular user (developer) should not be in direct contact +with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the various +parser packages, and is shared by them. Underneath it, but not +explicit dependencies, are the packages providing the message catalogs +for the various languages.

+
+

API

+
+
::doctools::msgcat::init prefix
+

The command locates and loads the message catalogs for all the +languages returned by msgcat::mcpreferences, provided that they +could be found. It returns an integer number describing how many +packages were found and loaded.

+

The names of the packages the command will look for have the form +"doctools::msgcat::prefix::langcode", with prefix +the argument to the command, and the langcode supplied by the +result of msgcat::mcpreferences.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html +++ embedded/www/tcllib/files/modules/doctools2idx/export_docidx.html @@ -0,0 +1,295 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::docidx(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::docidx - docidx export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::docidx ?0.1?
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of docidx markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates docidx markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Configuration

+

The docidx export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean newlines
+

If this flag is set the plugin will break the generated docidx code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set. This effect is independent of the +value for aligned however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and aligned, and no indenting is +done.

+
boolean aligned
+

If this flag is set the generator ensures that the arguments for the +manpage and url commands in a keyword section are aligned +vertically for a nice table effect. To make this work this also +implies that newlines is set. This effect is independent of the +value for indented however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and indented, and no alignment is +done.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_container.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_container.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_container.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_container.html @@ -0,0 +1,439 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx(n) 2 tcllib "Documentation tools"

+

Name

+

doctools::idx - Holding keyword indices

+
+ + +

Description

+

This package provides a class to contain and programmatically +manipulate keyword indices

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Exporting keyword indices, and

    2. +

  2. Importing keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is used to encode +keyword indices as values see the section +Keyword index serialization format. +This is the only format directly known to this class. Conversions from +and to any other format are handled by export and import manager +objects. These may be attached to a container, but do not have to be, +it is merely a convenience.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx objectName
+

This command creates a new container object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName key add name
+

This method adds the keyword name to the index. If the keyword +is already known nothing is done. The result of the method is the +empty string.

+
objectName key remove name
+

This method removes the keyword name from the index. If the +keyword is already gone nothing is done. Any references for whom this +keyword was the last association are removed as well. The result of +the method is the empty string.

+
objectName key references name
+

This method returns a list containing the names of all references +associated with the keyword name. An error is thrown in the +keyword is not known to the index. The order of the references in the +list is undefined.

+
objectName keys
+

This method returns a list containing the names of all keywords known +to the index. The order of the keywords in the list is undefined.

+
objectName reference add type key name label
+

This method adds the reference name to the index and associates +it with the keyword key. +The other two arguments hold the type and label of the +reference, respectively. +The type has to match the stored information, should the reference +exist already, i.e. this information is immutable after the reference +is known. The only way to change it is delete and recreate the +reference. +The label on the other hand is automatically updated to the value of +the argument, overwriting any previously stored information. +Should the reference exists already it is simply associated with the +key. If that is true already as well nothing is done, but the +label updated to the new value. The result of the method is the +empty string.

+

The type argument has be to one of manpage or url.

+
objectName reference remove name
+

The reference name is removed from the index. All associations +with keywords are released and the relevant reference labels removed. +The result of the method is the empty string.

+
objectName reference label name
+

This method returns the label associated with the reference +name. An error is thrown if the reference is not known.

+
objectName reference keys name
+

This method returns a list containing the names of all keywords +associated with the reference name. An error is thrown in the +reference is not known to the index. The order of the keywords in the +list is undefined.

+
objectName reference type name
+

This method returns the type of the reference name. An error is +thrown in the reference is not known to the index.

+
objectName references
+

This method returns a list containing the names of all references +known to the index. The order of the references in the list is +undefined.

+
objectName title
+

Returns the currently defined title of the keyword index.

+
objectName title text
+

Sets the title of the keyword index to text, and returns it as +the result of the command.

+
objectName label
+

Returns the currently defined label of the keyword index.

+
objectName label text
+

Sets the label of the keyword index to text, and returns it as +the result of the command.

+
objectName importer
+

Returns the import manager object currently attached to the container, +if any.

+
objectName importer object
+

Attaches the object as import manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the keyword index contained in +the text, assuming the given format.

+
objectName exporter
+

Returns the export manager object currently attached to the container, +if any.

+
objectName exporter object
+

Attaches the object as export manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding keyword index stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the keyword index from which to generate the text.

+
objectName deserialize = data ?format?
+

This method replaces the contents of the index object with the index +contained in the data. If no format was specified it is +assumed to be the regular serialization of a keyword index.

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case an error will be thrown if the container has no import +manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the keyword index in the data to its +contents instead of replacing it. +The method will throw an error if merging is not possible, i.e. would +produce an invalid index. The existing content is left unchanged in +that case.

+

The result of the method is the empty string.

+
objectName serialize ?format?
+

This method returns the keyword index contained in the object. If no +format is not specified the returned result is the canonical +serialization of its contents.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. +In that case an error will be thrown if the container has no export +manager attached to it.

+
+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export.html @@ -0,0 +1,453 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export - Exporting keyword indices

+
+ +

Synopsis

+
+
    +
  • package require doctools::idx::export ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::config
    • +
  • package require doctools::idx::structure
    • +
  • package require snit
    • +
  • package require pluginmgr
    • +
+ +
+
+

Description

+

This package provides a class to manage the plugins for the export of +keyword indices to other formats, i.e. their conversion to, for +example docidx, HTML, etc.

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Importing keyword indices, and

    2. +

  2. Holding keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is the major input to +the manager objects provided by this package see the section +Keyword index serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_IDX_EXPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_IDX_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/idx/export/plugin"

    5. +

  5. the path "~/.doctools/idx/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/idx/export/plugins"

    8. +

  8. the path "~/.doctools/idx/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with six predefined export plugins, +namely

+
+
docidx
+

See docidx export plugin for details.

+
html
+

See html export plugin for details.

+
json
+

See json export plugin for details.

+
nroff
+

See nroff export plugin for details.

+
text
+

See text export plugin for details.

+
wiki
+

See wiki export plugin for details.

+
+

Readers wishing to write their own export plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Export plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a keyword index +stored in serial and converts it to the specified format, +using the export plugin for the format. An error is thrown if no +plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to docidx.

+

The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

+

The plugin has to conform to the interface specified in section +Export plugin API v2 reference.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +keyword index. It invokes that method, feeds the result into +export serial and returns the resulting string as its own +result.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
+
+
+

Export plugin API v2 reference

+

Plugins are what this package uses to manage the support for any +output format beyond the +Keyword index serialization format. Here we specify the +API the objects created by this package use to interact with their +plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::idx::export::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various export methods of export manager + objects to get a string encoding a keyword index in that + format.

    3. +

  3. The plugin can expect that the package + doctools::idx::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. A plugin has to provide one command, with the signature shown + below.

    +
    +
    export serial configuration
    +

    Whenever an export manager of doctools::idx has to generate +output for an index it will invoke this command.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +index for which to generate the output. +The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    file
    +

    This variable, if defined by the user of the index object + is expected to contain the name of the input file for which + the plugin is generating its output for.

    +
    map
    +

    This variable, if defined by the user of the index object is + expected to contain a dictionary mapping from symbolic file + names used in the references of type manpage to + actual paths (or urls). A plugin has to be able to handle + the possibility that a symbolic name is without entry in + this mapping.

    +
    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of the invokations of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export_html.html @@ -0,0 +1,357 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::html(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::html - HTML export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::html ?0.2?
    • +
  • package require doctools::text
    • +
  • package require doctools::html
    • +
  • package require doctools::html::cssdefaults
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of HTML markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates HTML markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
boolean newlines
+

If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
string meta
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output in +the <head> section of the document, just after the <title> tag.

+
string header
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output +just after the <h1> title tag in the body of the document, in the +class.header <div>'ision.

+
string footer
+

This variable is meant to hold a fragment of HTML (default: +empty). The fragment it contains will be inserted into the generated +output just before the </body> tag, in the class.footer <div>'ision.

+
dictionary kwid
+

The value of this variable (default: empty) maps keywords to the +identifiers to use as their anchor names. Each keyword FOO not +found in the dictionary uses KW-FOO as anchor, +i.e. itself prefixed with the string KW-.

+
string sepline
+

The value of this variable is the string to use for the separator +comments inserted into the output when the outpout is broken across +lines and/or indented. The default string consists of 60 dashes.

+
integer kwidth
+

This variable holds the size of the keyword column in the main table +generated by the plugin, in percent of the total width of the +table. This is an integer number in the range of 1 to 99. Choosing a +value outside of that range causes the generator to switch back to the +defauly setting, 35 percent.

+
string dot
+

This variable contains a HTML fragment inserted between the entries of +the navigation bar, and the references associated with each keyword. +The default is the HTML entity &#183; i.e. the bullet character, also +known as the "Greek middle dot", i.e. the unicode character 00B7.

+
string class.main
+

This variable contains the class name for the main <div>'ivision of +the generated document. The default is doctools.

+
string class.header
+

This variable contains the class name for the header <div>'ision of +the generated document. The default is idx-header. This +division contains the document title, the user specified header, +if any, a visible separator line, and the navigation bar for quick +access to each keyword section.

+
string class.title
+

This variable contains the class name for the <h1> tag enclosing the +document title. The default is idx-title.

+
string class.navsep
+

This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +idx-navsep.

+
string class.navbar
+

This variable contains the class name for the navigation <div>'ision +enclosing the navigation bar of the generated document. The default is +idx-kwnav.

+
string class.contents
+

This variable contains the class name for the <table> holding the +keywords and their references in the generated document. The default +is idx-contents.

+
string class.leader
+

This variable contains the class name for the anchor names the plugin +inserts into the keyword table when switching from one section to the +next (Each section holds all keywords with a particular first +character). The default is idx-leader.

+
string class.row0
+

This variable contains the class name used to label the even rows +(<tr>) of the keyword table. The default is idx-even.

+
string class.row1
+

This variable contains the class name used to label the odd rows +(<tr>) of the keyword table. The default is idx-odd.

+
string class.keyword
+

This variable contains the class name used to label the keyword +cells/column (<td>) in the keyword table of the document. The default +is idx-keyword.

+
string class.refs
+

This variable contains the class name used to label the reference +cells/column (<td>) in the keyword table of the document. The default +is idx-refs.

+
string class.footer
+

This variable contains the class name for the footer <div>'ision of +the generated document. The default is idx-footer. This +division contains a browser-visible separator line and the user +specified footer, if any.

+
+

Note that this plugin ignores the standard configuration +variable format, and its value.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export_json.html @@ -0,0 +1,310 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::json - JSON export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::json ?0.1?
    • +
  • package require textutil::adjust
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates JSON markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

JSON notation of keyword indices

+

The JSON format used for keyword indices is a direct translation of +the Keyword index serialization format, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::idx {
+	label {Keyword Index}
+	keywords {
+		changelog  {changelog.man cvs.man}
+		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
+		cvs        cvs.man
+	}
+	references {
+		apps/dtplite.man {manpage dtplite}
+		changelog.man    {manpage doctools::changelog}
+		cvs.man          {manpage doctools::cvs}
+		docidx.man       {manpage doctools::idx}
+		doctoc.man       {manpage doctools::toc}
+		doctools.man     {manpage doctools}
+		mpexpand.man     {manpage mpexpand}
+	}
+	title {}
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::idx" : {
+        "label"      : "Keyword Index",
+        "keywords"   : {
+            "changelog"  : ["changelog.man","cvs.man"],
+            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
+            "cvs"        : ["cvs.man"],
+        },
+        "references" : {
+            "apps\/dtplite.man" : ["manpage","dtplite"],
+            "changelog.man"     : ["manpage","doctools::changelog"],
+            "cvs.man"           : ["manpage","doctools::cvs"],
+            "docidx.man"        : ["manpage","doctools::idx"],
+            "doctoc.man"        : ["manpage","doctools::toc"],
+            "doctools.man"      : ["manpage","doctools"],
+            "mpexpand.man"      : ["manpage","mpexpand"]
+        },
+        "title"      : ""
+    }
+}
+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and map and +their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export_nroff.html @@ -0,0 +1,264 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::nroff(n) 0.3 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::nroff - nroff export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::nroff ?0.3?
    • +
  • package require doctools::text
    • +
  • package require doctools::nroff::man_macros
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of nroff markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates nroff markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +index came from. This variable may not be set or contain the empty +string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean inline
+

If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output.

+

If this flag is not set, the plugin will place a reference to the +definitions of the man macro set into the output, but not the macro +definitions themselves.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export_text.html @@ -0,0 +1,251 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::text(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::text - plain text export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::text ?0.2?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of plain text markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates plain text markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file, and format, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_export_wiki.html @@ -0,0 +1,264 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::export::wiki(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::idx::export::wiki - wiki export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::export::wiki ?0.2?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index export plugin for +the generation of wiki markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a keyword index, as +specified in section Keyword index serialization format, +and contained in serial, the configuration, a dictionary, +and generates wiki markup encoding the index. +The created string is then returned as the result of the command.

+
+
+

Wiki markup

+

The basic syntax of the wiki markup generated by this plugin are +described at http://wiki.tcl.tk/14.

+

The plugin goes beyond the classic markup to generate proper headers +and either a table or indented list of the keywords and their +references.

+
+

Configuration

+

The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the symbolic files names in manpage references to the actual +filenames and/or urls to be used in the output.

+

Url references and symbolic file names without a mapping are used +unchanged.

+
enum style
+

This variable recognizes two values as legal, list (default), +and table. +Depending on the value the plugin generates either a list- or +table-based wiki page for the index.

+
+

Note that this plugin ignores the standard configuration +variables user, file and format, and their values.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_import.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_import.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_import.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_import.html @@ -0,0 +1,512 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::import(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import - Importing keyword indices

+
+ + +

Description

+

This package provides a class to manage the plugins for the import of +keyword indices from other formats, i.e. their conversion from, for +example docidx, json, etc.

+

This is one of the three public pillars the management of keyword +indices resides on. The other two pillars are

+
    +

  1. Exporting keyword indices, and

    2. +

  2. Holding keyword indices

    3. +
+

For information about the Concepts of keyword indices, and +their parts, see the same-named section. +For information about the data structure which is the major output of +the manager objects provided by this package see the section +Keyword index serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_IDX_IMPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_IDX_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/idx/import/plugin"

    5. +

  5. the path "~/.doctools/idx/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/idx/import/plugins"

    8. +

  8. the path "~/.doctools/idx/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with two predefined import plugins, +namely

+
+
docidx
+

See docidx import plugin for details.

+
json
+

See json import plugin for details.

+
+

Readers wishing to write their own import plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Import plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A keyword index consists of a (possibly empty) set of keywords.

    2. +

  2. Each keyword in the set is identified by its name.

    3. +

  3. Each keyword has a (possibly empty) set of references.

    4. +

  4. A reference can be associated with more than one keyword.

    5. +

  5. A reference not associated with at least one keyword is not possible +however.

    6. +

  6. Each reference is identified by its target, specified as either an url +or symbolic filename, depending on the type of reference (url, +or manpage).

    7. +

  7. The type of a reference (url, or manpage) depends only on the +reference itself, and not the keywords it is associated with.

    8. +

  8. In addition to a type each reference has a descriptive label as +well. This label depends only on the reference itself, and not the +keywords it is associated with.

    9. +
+

A few notes

+
    +

  1. Manpage references are intended to be used for references to the +documents the index is made for. Their target is a symbolic file name +identifying the document, and export plugins may replace symbolic with +actual file names, if specified.

    2. +

  2. Url references are intended on the othre hand are inteded to be used +for links to anything else, like websites. Their target is an url.

    3. +

  3. While url and manpage references share a namespace for their +identifiers, this should be no problem, given that manpage identifiers +are symbolic filenames and as such they should never look like urls, +the identifiers for url references.

    4. +
+
+

API

+

Package commands

+
+
::doctools::idx::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::idx::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a keyword index using +the import plugin for the format. An error is thrown if no plugin +could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to docidx.

+

The specification of what a canonical serialization is can be +found in the section Keyword index serialization format.

+

The plugin has to conform to the interface specified in section +Import plugin API v2 reference.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +keyword index. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

Import plugin API v2 reference

+

Plugins are what this package uses to manage the support for any input +format beyond the Keyword index serialization format. Here +we specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::idx::import::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various import methods of import manager + objects to get a string encoding a keyword index in that + format.

    3. +

  3. The plugin can expect that the package + doctools::idx::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. The plugin can expect that a command named IncludeFile is + present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such. An example of +such a format would be docidx.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide one command, with the signature shown + below.

    +
    +
    import text configuration
    +

    Whenever an import manager of doctools::idx has to parse +input for an index it will invoke this command.

    +
    +
    string text
    +

    This argument will contain the text encoding the index per the format +the plugin is for.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of the invokations of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_import_json.html @@ -0,0 +1,287 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::import::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import::json - JSON import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::import::json ?0.1?
    • +
  • package require doctools::idx::structure
    • +
  • package require json
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index import plugin for +the parsing of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as JSON +markup encoding a keyword index, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section Keyword index serialization format.

+
+
+

JSON notation of keyword indices

+

The JSON format used for keyword indices is a direct translation of +the Keyword index serialization format, mapping Tcl +dictionaries as JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::idx {
+	label {Keyword Index}
+	keywords {
+		changelog  {changelog.man cvs.man}
+		conversion {doctools.man docidx.man doctoc.man apps/dtplite.man mpexpand.man}
+		cvs        cvs.man
+	}
+	references {
+		apps/dtplite.man {manpage dtplite}
+		changelog.man    {manpage doctools::changelog}
+		cvs.man          {manpage doctools::cvs}
+		docidx.man       {manpage doctools::idx}
+		doctoc.man       {manpage doctools::toc}
+		doctools.man     {manpage doctools}
+		mpexpand.man     {manpage mpexpand}
+	}
+	title {}
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::idx" : {
+        "label"      : "Keyword Index",
+        "keywords"   : {
+            "changelog"  : ["changelog.man","cvs.man"],
+            "conversion" : ["doctools.man","docidx.man","doctoc.man","apps\/dtplite.man","mpexpand.man"],
+            "cvs"        : ["cvs.man"],
+        },
+        "references" : {
+            "apps\/dtplite.man" : ["manpage","dtplite"],
+            "changelog.man"     : ["manpage","doctools::changelog"],
+            "cvs.man"           : ["manpage","doctools::cvs"],
+            "docidx.man"        : ["manpage","doctools::idx"],
+            "doctoc.man"        : ["manpage","doctools::toc"],
+            "doctools.man"      : ["manpage","doctools"],
+            "mpexpand.man"      : ["manpage","mpexpand"]
+        },
+        "title"      : ""
+    }
+}
+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_introduction.html @@ -0,0 +1,251 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools2idx_introduction(n) 2.0 tcllib "Documentation tools"

+

Name

+

doctools2idx_introduction - DocTools - Keyword indices

+
+ +

Description

+

docidx (short for documentation indices) stands for a +set of related, yet different, entities which are working together for +the easy creation and transformation of keyword indices for +documentation.

+

These are

+
    +

  1. A tcl based language for the semantic markup of a keyword index. +Markup is represented by Tcl commands. +Beginners should start with the +docidx language introduction. +The formal specification is split over two documents, one dealing with +the docidx language syntax, the other a +docidx language command reference.

    2. +

  2. A set of packages for the programmatic manipulation of keyword indices +in memory, and their conversion between various formats, reading and +writing. The aforementioned markup language is one of the formats +which can be both read from and written to.

    3. +

  3. The system for the conversion of indices is based on a plugin +mechanism, for this we have two APIs describing the interface between +the packages above and the import/export plugins.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to docidx should read the more informally written +docidx language introduction first. Having digested this +the formal docidx language syntax specification should +become understandable. A writer experienced with docidx may only +need the docidx language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of docidx when handling directories of documentation, +automatically generating a proper keyword index for them.

    2. +

  2. A processor of documentation written in the docidx +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose docidx to the +user. At the bottom level, common to both applications, however we +find the three packages providing the basic facilities to handle +keyword indices, i.e. import from textual formats, programmatic +manipulation in memory, and export to textual formats. These are

    +
    +
    doctools::idx
    +

    Programmatic manipulation of keyword indices in memory.

    +
    doctools::idx::import
    +

    Import of keyword indices from various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    doctools::idx::export
    +

    Export of keyword indices to various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    +

    See also section Package Overview for an overview of the +dependencies between these and other, supporting packages.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the import and export packages and their plugins. +These APIs are described in the documentation for the two relevant +packages, i.e.

    + +
    4. +
+
+

Related formats

+

The docidx format does not stand alone, it has two companion formats. +These are called doctoc and doctools, and they are +intended for the markup of tables of contents, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the DocTools - Tables Of Contents and +the DocTools - General, respectively.

+
+

Package Overview

+
+                                    ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
+                                   ~~                   |               ~~
+                doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
+                        |                               |                       |
+        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
+        |               |                         |     |    |                  |               |                       |               |
+doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
+                        |                         |     |    |                  |
+                doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
+                        docidx                    |     |    |                  docidx, json
+                        json                      |     |    |                  |           \\
+                        html                      |     |    |          doctools::idx::parse \\
+                        nroff                     |     |    |                  |             \\
+                        wiki                      |     |    |  +---------------+              json
+                        text                      |     |    |  |               |
+                                                doctools::idx::structure        |
+                                                                                |
+                                                                        +-------+---------------+
+                                                                        |                       |
+          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
+                |                                                                               |
+          doctools::text  doctools::nroff::man_macros                                           =
+                                                                                                |
+                                                                                        doctools::msgcat::idx::<*>
+                                                                                                c, en, de, fr
+                                                                                                (fr == en for now)
+        ~~      Interoperable objects, without actual package dependencies
+        --      Package dependency, higher requires lower package
+        =       Dynamic dependency through plugin system
+        <*>     Multiple packages following the given form of naming.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_c.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::idx::c(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::c - Message catalog for the docidx parser (C)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::c ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::c is a +support module providing the C language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_de.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::idx::de(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::de - Message catalog for the docidx parser (DE)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::de ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::de is a +support module providing the DE (german) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_en.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::idx::en(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::en - Message catalog for the docidx parser (EN)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::en ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::en is a +support module providing the EN (english) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_msgcat_fr.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::idx::fr(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::idx::fr - Message catalog for the docidx parser (FR)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::idx::fr ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::idx::fr is a +support module providing the FR (french) language message catalog +for the docidx parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_parse.html @@ -0,0 +1,341 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::idx::parse - Parsing text in docidx format

+
+ +

Synopsis

+
+
    +
  • package require doctools::idx::parse ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
+ +
+
+

Description

+

This package provides commands to parse text written in the +docidx markup language and convert it into the canonical +serialization of the keyword index encoded in the text. +See the section Keyword index serialization format for +specification of their format.

+

This is an internal package of doctools, for use by the higher level +packages handling docidx documents.

+
+

API

+
+
::doctools::idx::parse text text
+

The command takes the string contained in text and parses it +under the assumption that it contains a document written using the +docidx markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section Parse errors.

+

When successful the command returns the canonical serialization of the +keyword index which was encoded in the text. +See the section Keyword index serialization format for +specification of that format.

+
::doctools::idx::parse file path
+

The same as text, except that the text to parse is read from +the file specified by path.

+
::doctools::idx::parse includes
+

This method returns the current list of search paths used when looking +for include files.

+
::doctools::idx::parse include add path
+

This method adds the path to the list of paths searched when +looking for an include file. The call is ignored if the path is +already in the list of paths. The method returns the empty string as +its result.

+
::doctools::idx::parse include remove path
+

This method removes the path from the list of paths searched +when looking for an include file. The call is ignored if the path is +not contained in the list of paths. The method returns the empty +string as its result.

+
::doctools::idx::parse include clear
+

This method clears the list of search paths for include files.

+
::doctools::idx::parse vars
+

This method returns a dictionary containing the current set of +predefined variables known to the vset markup command during +processing.

+
::doctools::idx::parse var set name value
+

This method adds the variable name to the set of predefined +variables known to the vset markup command during processing, +and gives it the specified value. The method returns the empty +string as its result.

+
::doctools::idx::parse var unset name
+

This method removes the variable name from the set of predefined +variables known to the vset markup command during +processing. The method returns the empty string as its result.

+
::doctools::idx::parse var clear ?pattern?
+

This method removes all variables matching the pattern from the +set of predefined variables known to the vset markup command +during processing. The method returns the empty string as its result.

+

The pattern matching is done with string match, and the +default pattern used when none is specified, is *.

+
+
+

Parse errors

+

The format of the parse error messages thrown when encountering +violations of the docidx markup syntax is human readable and +not intended for processing by machines. As such it is not documented.

+

However, the errorCode attached to the message is +machine-readable and has the following format:

+
    +

  1. The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more.

    2. +

  2. Each error element will be a list containing six strings describing an +error in detail. The strings will be

    +
      +

    1. The path of the file the error occured in. This may be empty.

      2. +

    2. The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero.

      3. +

    3. The line the first character after the error is on. +Lines are counted from one.

      4. +

    4. The column the first character after the error is at. +Columns are counted from zero.

      5. +

    5. The message code of the error. This value can be used as argument to +msgcat::mc to obtain a localized error message, assuming that +the application had a suitable call of doctools::msgcat::init to +initialize the necessary message catalogs (See package +doctools::msgcat).

      6. +

    6. A list of details for the error, like the markup command involved. In +the case of message code docidx/include/syntax this value is +the set of errors found in the included file, using the format +described here.

      7. +
    +
    3. +
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html Index: embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html +++ embedded/www/tcllib/files/modules/doctools2idx/idx_structure.html @@ -0,0 +1,282 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::structure(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::structure - Docidx serialization utilities

+
+ + +

Description

+

This package provides commands to work with the serializations of +keyword indices as managed by the doctools system v2, and specified in +section Keyword index serialization format.

+

This is an internal package of doctools, for use by the higher level +packages handling keyword indices and their conversion into and out of +various other formats, like documents written using docidx +markup.

+
+

API

+
+
::doctools::idx::structure verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +regular serialization of a keyword index and will throw an +error if that is not the case. The result of the command is the empty +string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
::doctools::idx::structure verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a keyword index and will throw an +error if that is not the case. The result of the command is the empty +string.

+

For the specification of canonical keyword index serializations see +the section Keyword index serialization format.

+
::doctools::idx::structure canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a keyword index and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained keyword index and return it as its result. If the +input is already canonical it will be returned unchanged.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
::doctools::idx::structure print serial
+

This command assumes that the argument serial contains a valid +regular serialization of a keyword index and returns a string +containing that index in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of regular keyword index serializations see the +section Keyword index serialization format.

+
::doctools::idx::structure merge seriala serialb
+

This command accepts the regular serializations of two keyword indices +and uses them to create their union. The result of the command is the +canonical serialization of this unified keyword index.

+

Title and label of the resulting index are taken from the index +contained in serialb. The set of keys, references and their +connections is the union of the set of keys and references of the two +inputs.

+

For the specification of regular and canonical keyword index +serializations see the section +Keyword index serialization format.

+
+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html Index: embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html +++ embedded/www/tcllib/files/modules/doctools2idx/import_docidx.html @@ -0,0 +1,264 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::idx::import::docidx(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::idx::import::docidx - docidx import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::idx::import::docidx ?0.1?
    • +
  • package require doctools::idx::parse
    • +
  • package require doctools::idx::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require struct::stack
    • +
  • package require struct::tree
    • +
  • package require treeql
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools keyword index import plugin for +the parsing of docidx markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling keyword indices, especially doctools::idx::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::idx::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +docidx import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as docidx +markup encoding a keyword index, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that keyword index, in the form specified +in section Keyword index serialization format.

+
+
+

[docidx] notation of keyword indices

+

The docidx format for keyword indices, also called the +docidx markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. docidx language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. docidx language syntax and

    2. +

  2. docidx language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Keyword index serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize keyword indices as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. While a keyword index may have more than one regular +serialization only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. An index serialization is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::idx, and its +value. This value holds the contents of the index.

    3. +

  3. The contents of the index are a Tcl dictionary holding the title of +the index, a label, and the keywords and references. The relevant keys +and their values are

    +
    +
    title
    +

    The value is a string containing the title of the index.

    +
    label
    +

    The value is a string containing a label for the index.

    +
    keywords
    +

    The value is a Tcl dictionary, using the keywords known to the index +as keys. The associated values are lists containing the identifiers of +the references associated with that particular keyword.

    +

    Any reference identifier used in these lists has to exist as a key in +the references dictionary, see the next item for its +definition.

    +
    references
    +

    The value is a Tcl dictionary, using the identifiers for the +references known to the index as keys. The associated values are +2-element lists containing the type and label of the reference, in +this order.

    +

    Any key here has to be associated with at least one keyword, +i.e. occur in at least one of the reference lists which are the values +in the keywords dictionary, see previous item for its +definition.

    +
    +
    4. +

  4. The type of a reference can be one of two values,

    +
    +
    manpage
    +

    The identifier of the reference is interpreted as symbolic file name, +refering to one of the documents the index was made for.

    +
    url
    +

    The identifier of the reference is interpreted as an url, refering to +some external location, like a website, etc.

    +
    +
    5. +
+
canonical serialization
+

The canonical serialization of a keyword index has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of the keyword index.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The references listed for each keyword of the index, if any, are +listed in ascending dictionary order of their labels, as +generated by Tcl's builtin command lsort -increasing -dict.

    3. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html +++ embedded/www/tcllib/files/modules/doctools2toc/export_doctoc.html @@ -0,0 +1,318 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::doctoc(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::doctoc - doctoc export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::doctoc ?0.1?
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of doctoc markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates doctoc markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

Configuration

+

The doctoc export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean newlines
+

If this flag is set the plugin will break the generated doctoc code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of tables of contents. To make this work +this also implies that newlines is set. This effect is +independent of the value for aligned however.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
boolean aligned
+

If this flag is set the generator ensures that the arguments for the +item commands in a division are aligned vertically for a nice +table effect. To make this work this also implies that newlines +is set. This effect is independent of the value for indented +however.

+

If this flag is not set (the default), the output is formatted as per +the values of newlines and indented, and no alignment is +done.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html Index: embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html +++ embedded/www/tcllib/files/modules/doctools2toc/import_doctoc.html @@ -0,0 +1,288 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::import::doctoc(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import::doctoc - doctoc import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::import::doctoc ?0.1?
    • +
  • package require doctools::toc::parse
    • +
  • package require doctools::toc::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require struct::stack
    • +
  • package require struct::tree
    • +
  • package require treeql
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents import plugin +for the parsing of doctoc markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as doctoc +markup encoding a table of contents, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section ToC serialization format.

+
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_container.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_container.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_container.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_container.html @@ -0,0 +1,504 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc(n) 2 tcllib "Documentation tools"

+

Name

+

doctools::toc - Holding tables of contents

+
+ + +

Description

+

This package provides a class to contain and programmatically +manipulate tables of contents.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Exporting tables of contents, and

    2. +

  2. Importing tables of contents

    3. +
+

For information about the Concepts of tables of contents, and +their parts, see the same-named section. +For information about the data structure which is used to encode +tables of contents as values see the section +ToC serialization format. +This is the only format directly known to this class. Conversions from +and to any other format are handled by export and import manager +objects. These may be attached to a container, but do not have to be, +it is merely a convenience.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc objectName
+

This command creates a new container object with an associated Tcl +command whose name is objectName. This object command is +explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName + reference id label docid desc
+

This method adds a new reference element to the table of contents, +under the element specified via its handle id. This parent +element has to be a division element, or the root. An error is thrown +otherwise. +The new element will be externally identified by its label, +which has to be be unique within the parent element. An error is +thrown otherwise.

+

As a reference element it will refer to a document identified by the +symbolic docid. This reference must not be the empty string, an +error is thrown otherwise. +Beyond the label the element also has a longer descriptive string, +supplied via desc.

+

The result of the method is the handle (id) of the new element.

+
objectName + division id label ?docid?
+

This method adds a new division element to the table of contents, +under the element specified via its handle id. This parent +element has to be a division element, or the root. An error is thrown +otherwise. +The new element will be externally identified by its label, +which has to be be unique within the parent element. An error is +thrown otherwise.

+

As a division element it is can refer to a document, identified by the +symbolic docid, but may choose not to.

+

The result of the method is the handle (id) of the new element.

+
objectName remove id
+

This method removes the element identified by the handle id from +the table of contents. +If the element is a division all of its children, if any, are removed +as well. The root element/division of the table of contents cannot be +removed however, only its children.

+

The result of the method is the empty string.

+
objectName up id
+

This method returns the handle of the parent for the element +identified by its handle id, or the empty string if id +refered to the root element.

+
objectName next id
+

This method returns the handle of the right sibling for the element +identified by its handle id, or the handle of the parent if the +element has no right sibling, or the empty string if id refered +to the root element.

+
objectName prev id
+

This method returns the handle of the left sibling for the element +identified by its handle id, or the handle of the parent if the +element has no left sibling, or the empty string if id refered +to the root element.

+
objectName child id label ?...?
+

This method returns the handle of a child of the element identified by +its handle id. The child itself is identified by a series of +labels.

+
objectName element ?...?
+

This method returns the handle of the element identified by a series +of labels, starting from the root of the table of contents. The series +of labels is allowed to be empty, in which case the handle of the root +element is returned.

+
objectName children id
+

This method returns a list containing the handles of all children of +the element identified by the handle id, from first to last, in +that order.

+
objectName type id
+

This method returns the type of the element, either reference, +or division.

+
objectName full-label id
+

This method is the complement of the method element, +converting the handle id of an element into a list of labels +full identifying the element within the whole table of contents.

+
objectName elabel id ?newlabel?
+

This method queries and/or changes the label of the element identified +by the handle id. If the argument newlabel is present then +the label is changed to that value. Regardless of this, the result of +the method is the current value of the label.

+

If the label is changed the new label has to be unique within the +containing division, or an error is thrown.

+

Further, of the id refers to the root element of the table of +contents, then using this method is equivalent to using the method +label, i.e. it is accessing the global label for the whole +table.

+
objectName description id ?newdesc?
+

This method queries and/or changes the description of the element +identified by the handle id. If the argument newdesc is +present then the description is changed to that value. Regardless of +this, the result of the method is the current value of the description.

+

The element this method operates on has to be a reference element, or +an error will be thrown.

+
objectName document id ?newdocid?
+

This method queries and/or changes the document reference of the +element identified by the handle id. +If the argument newdocid is present then the description is +changed to that value. Regardless of this, the result of the method is +the current value of the document reference.

+

Setting the reference to the empty string means unsetting it, and is +allowed only for division elements. Conversely, if the result is the +empty string then the element has no document reference, and this can +happen only for division elements.

+
objectName title
+

Returns the currently defined title of the table of contents.

+
objectName title text
+

Sets the title of the table of contents to text, and returns it as +the result of the command.

+
objectName label
+

Returns the currently defined label of the table of contents.

+
objectName label text
+

Sets the label of the table of contents to text, and returns it as +the result of the command.

+
objectName importer
+

Returns the import manager object currently attached to the container, +if any.

+
objectName importer object
+

Attaches the object as import manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the table of contents contained in +the text, assuming the given format.

+
objectName exporter
+

Returns the export manager object currently attached to the container, +if any.

+
objectName exporter object
+

Attaches the object as export manager to the container, and +returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding table of contents stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the table of contents from which to generate the text.

+
objectName deserialize = data ?format?
+

This method replaces the contents of the table object with the table +contained in the data. If no format was specified it is +assumed to be the regular serialization of a table of contents.

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case an error will be thrown if the container has no import +manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the table of contents in the data to its +contents instead of replacing it. +The method will throw an error if merging is not possible, i.e. would +produce an invalid table. The existing content is left unchanged in +that case.

+

The result of the method is the empty string.

+
objectName serialize ?format?
+

This method returns the table of contents contained in the object. If no +format is not specified the returned result is the canonical +serialization of its contents.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. +In that case an error will be thrown if the container has no export +manager attached to it.

+
+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export.html @@ -0,0 +1,469 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export - Exporting tables of contents

+
+ +

Synopsis

+
+
    +
  • package require doctools::toc::export ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::config
    • +
  • package require doctools::toc::structure
    • +
  • package require snit
    • +
  • package require pluginmgr
    • +
+ +
+
+

Description

+

This package provides a class to manage the plugins for the export of +tables of contents to other formats, i.e. their conversion to, for +example doctoc, HTML, etc.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Importing tables of contents, and

    2. +

  2. Holding tables of contents

    3. +
+

For information about the Concepts of tables of contents, +and their parts, see the same-named section. +For information about the data structure which is the major input to +the manager objects provided by this package see the section +ToC serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_TOC_EXPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_TOC_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/toc/export/plugin"

    5. +

  5. the path "~/.doctools/toc/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/toc/export/plugins"

    8. +

  8. the path "~/.doctools/toc/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with six predefined export plugins, +namely

+
+
doctoc
+

See doctoc export plugin for details.

+
html
+

See html export plugin for details.

+
json
+

See json export plugin for details.

+
nroff
+

See nroff export plugin for details.

+
text
+

See text export plugin for details.

+
wiki
+

See wiki export plugin for details.

+
+

Readers wishing to write their own export plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Export plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a table of contents +stored in serial and converts it to the specified format, +using the export plugin for the format. An error is thrown if no +plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to doctoc.

+

The specification of what a canonical serialization is can be +found in the section ToC serialization format.

+

The plugin has to conform to the interface specified in section +Export plugin API v2 reference.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +table of contents. It invokes that method, feeds the result into +export serial and returns the resulting string as its own +result.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
+
+
+

Export plugin API v2 reference

+

Plugins are what this package uses to manage the support for any +output format beyond the ToC serialization format. Here we +specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::toc::export::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various export methods of export manager + objects to get a string encoding a table of contents in that + format.

    3. +

  3. The plugin can expect that the package + doctools::toc::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. A plugin has to provide one command, with the signature shown + below.

    +
    +
    export serial configuration
    +

    Whenever an export manager of doctools::toc has to generate +output for a table of contents it will invoke this command.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +table of contents for which to generate the output. +The specification of what a canonical serialization is can be +found in the section ToC serialization format.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +generation, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    file
    +

    This variable, if defined by the user of the table object + is expected to contain the name of the input file for which + the plugin is generating its output for.

    +
    map
    +

    This variable, if defined by the user of the table object is + expected to contain a dictionary mapping from symbolic + document ids used in the table entries to actual paths (or + urls). A plugin has to be able to handle the possibility + that a document id is without entry in this mapping.

    +
    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of the invokations of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export_html.html @@ -0,0 +1,351 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::html(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::html - HTML export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::html ?0.1?
    • +
  • package require doctools::text
    • +
  • package require doctools::html
    • +
  • package require doctools::html::cssdefaults
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of HTML markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates HTML markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The html export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
boolean newlines
+

If this flag is set the plugin will break the generated html code +across lines, with each markup command on a separate line.

+

If this flag is not set (the default), the whole document will be +written on a single line, with minimum spacing between all elements.

+
boolean indented
+

If this flag is set the plugin will indent the markup commands +according to the structure of indices. To make this work this also +implies that newlines is set.

+

If this flag is not set (the default), the output is formatted as per +the value of newlines, and no indenting is done.

+
string meta
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output in +the <head> section of the document, just after the <title> tag.

+
string header
+

This variable is meant to hold a fragment of HTML (default: empty). +The fragment it contains will be inserted into the generated output +just after the <h1> title tag in the body of the document, in the +class.header <div>'ision.

+
string footer
+

This variable is meant to hold a fragment of HTML (default: +empty). The fragment it contains will be inserted into the generated +output just before the </body> tag, in the class.footer <div>'ision.

+
dictionary rid
+

The value of this variable (default: empty) maps references to the +identifiers to use as their anchor names. Each reference FOO not +found in the dictionary uses REF-FOO as anchor, +i.e. itself prefixed with the string REF-.

+
string sepline
+

The value of this variable is the string to use for the separator +comments inserted into the output when the outpout is broken across +lines and/or indented. The default string consists of 60 dashes.

+
string class.main
+

This variable contains the class name for the main <div>'ivision of +the generated document. The default is doctools.

+
string class.header
+

This variable contains the class name for the header <div>'ision of +the generated document. The default is toc-header. This +division contains the document title, the user specified header, +if any, and a visible separator line.

+
string class.title
+

This variable contains the class name for the <h1> tag enclosing the +document title. The default is toc-title.

+
string class.navsep
+

This variable contains the class name for the <hr> separators in the +header and footer sections of the generated document. The default is +toc-navsep.

+
string class.contents
+

This variable contains the class name for the XXXXX holding the +keywords and their references in the generated document. The default +is toc-contents.

+
string class.ref
+

This variable contains the class name for the table elements which are +references to other documents. The default is toc-ref.

+
string class.div
+

This variable contains the class name for the table elements which are +divisions. The default is toc-div.

+
string class.footer
+

This variable contains the class name for the footer <div>'ision of +the generated document. The default is toc-footer. This +division contains a browser-visible separator line and the user +specified footer, if any.

+
+

Note that this plugin ignores the standard configuration +variable format, and its value.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export_json.html @@ -0,0 +1,354 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::json - JSON export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::json ?0.1?
    • +
  • package require textutil::adjust
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates JSON markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

JSON notation of tables of contents

+

The JSON format used for tables of contents is a direct translation of +the ToC serialization format, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::toc {
+    items {
+        {reference {
+	    desc {DocTools - Tables of Contents}
+	     id introduction.man
+	     label doctools::toc::introduction
+	}}
+	{division {
+	     id processing.man
+	     items {
+	         {reference {
+		     desc {doctoc serialization utilities}
+		     id structure.man
+		     label doctools::toc::structure
+		 }}
+		 {reference {
+		     desc {Parsing text in doctoc format}
+		     id parse.man
+		     label doctools::toc::parse
+		 }}
+	     }
+             label Processing
+        }}
+    }
+    label {Table of Contents} 
+    title TOC
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::toc" : {
+        "items" : [{
+            "reference" : {
+                "desc"  : "DocTools - Tables of Contents",
+                "id"    : "introduction.man",
+                "label" : "doctools::toc::introduction"
+            }
+        },{
+            "division" : {
+                "id"    : "processing.man",
+                "items" : [{
+                    "reference" : {
+                        "desc"  : "doctoc serialization utilities",
+                        "id"    : "structure.man",
+                        "label" : "doctools::toc::structure"
+                    }
+                },{
+                    "reference" : {
+                        "desc"  : "Parsing text in doctoc format",
+                        "id"    : "parse.man",
+                        "label" : "doctools::toc::parse"
+                    }
+                }],
+                "label" : "Processing"
+            }
+        }],
+        "label" : "Table of Contents",
+        "title" : "TOC"
+    }
+}
+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and map and +their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export_nroff.html @@ -0,0 +1,288 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::nroff(n) 0.2 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::nroff - nroff export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::nroff ?0.2?
    • +
  • package require doctools::text
    • +
  • package require doctools::nroff::man_macros
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of nroff markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates nroff markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The nroff export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string user
+

This standard configuration variable contains the name of the user +running the process which invoked the export plugin. +The plugin puts this information into the provenance comment at the +beginning of the generated document.

+
string file
+

This standard configuration variable contains the name of the file the +table of contents came from. This variable may not be set or contain +the empty string. +The plugin puts this information, if defined, i.e. set and not the +empty string, into the provenance comment at the beginning of the +generated document.

+
boolean inline
+

If this flag is set (default) the plugin will place the definitions of +the man macro set directly into the output.

+

If this flag is not set, the plugin will place a reference to the +definitions of the man macro set into the output, but not the macro +definitions themselves.

+
+

Note that this plugin ignores the standard configuration +variables format, and map, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export_text.html @@ -0,0 +1,274 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::text(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::text - plain text export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::text ?0.1?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of plain text markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates plain text markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The text export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file, and format, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html @@ -0,0 +1,281 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::export::wiki(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::export::wiki - wiki export plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::export::wiki ?0.1?
    • +
  • package require doctools::text
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents export plugin +for the generation of wiki markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::export, the export manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::export and the export manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc export plugin API version 2.

+
+
export serial configuration
+

This command takes the canonical serialization of a table of contents, +as specified in section ToC serialization format, and +contained in serial, the configuration, a dictionary, and +generates wiki markup encoding the table. +The created string is then returned as the result of the command.

+
+
+

Wiki markup

+

The basic syntax of the wiki markup generated by this plugin are +described at http://wiki.tcl.tk/14.

+

The plugin goes beyond the classic markup to generate proper headers +and indenting.

+
+

Configuration

+

The wiki export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
dictionary map
+

This standard configuration variable contains a dictionary mapping +from the (symbolic) document ids in reference entries to the actual +filenames and/or urls to be used in the output.

+

Document ids without a mapping are used unchanged.

+
+

Note that this plugin ignores the standard configuration +variables user, file and format, and their values.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_import.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_import.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_import.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_import.html @@ -0,0 +1,530 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::import(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import - Importing keyword indices

+
+ + +

Description

+

This package provides a class to manage the plugins for the import of +tables of contents from other formats, i.e. their conversion from, for +example doctoc, json, etc.

+

This is one of the three public pillars the management of tables of +contents resides on. The other two pillars are

+
    +

  1. Exporting tables of contents, and

    2. +

  2. Holding tables of contents

    3. +
+

For information about the Concepts of tables of contents, +and their parts, see the same-named section. +For information about the data structure which is the major output of +the manager objects provided by this package see the section +ToC serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,

    2. +

  2. the environment variable DOCTOOLS_TOC_PLUGINS,

    3. +

  3. the environment variable DOCTOOLS_PLUGINS,

    4. +

  4. the path "~/.doctools/toc/import/plugin"

    5. +

  5. the path "~/.doctools/toc/plugin"

    6. +

  6. the path "~/.doctools/plugin"

    7. +

  7. the path "~/.doctools/toc/import/plugins"

    8. +

  8. the path "~/.doctools/toc/plugins"

    9. +

  9. the path "~/.doctools/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\TOC\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using Windows(tm) operating system.

+

The whole system is delivered with two predefined import plugins, +namely

+
+
doctoc
+

See doctoc import plugin for details.

+
json
+

See json import plugin for details.

+
+

Readers wishing to write their own import plugin for some format, i.e. +plugin writers reading and understanding the section +containing the Import plugin API v2 reference is an +absolute necessity, as it specifies the interaction between this +package and its plugins in detail.

+
+

Concepts

+
    +

  1. A table of contents consists of a (possibly empty) list of +elements.

    2. +

  2. Each element in the list is identified by its label.

    3. +

  3. Each element is either a reference, or a division.

    4. +

  4. Each reference has an associated document, identified by a symbolic +id, and a textual description.

    5. +

  5. Each division may have an associated document, identified by a +symbolic id.

    6. +

  6. Each division consists consists of a (possibly empty) list of +elements, with each element following the rules as specified in +item 2 and above.

    7. +
+

A few notes

+
    +

  1. The above rules span up a tree of elements, with references as the +leaf nodes, and divisions as the inner nodes, and each element +representing an entry in the whole table of contents.

    2. +

  2. The identifying labels of any element E are unique within their +division (or toc), and the full label of any element E is the list of +labels for all nodes on the unique path from the root of the tree to +E, including E.

    3. +
+
+

API

+

Package commands

+
+
::doctools::toc::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::doctools::toc::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a table of contents using +the import plugin for the format. An error is thrown if no plugin +could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to doctoc.

+

The specification of what a canonical serialization is can be +found in the section ToC serialization format.

+

The plugin has to conform to the interface specified in section +Import plugin API v2 reference.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +table of contents. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName config names
+

This method returns a list containing the names of all configuration +variables currently known to the object.

+
objectName config get
+

This method returns a dictionary containing the names and values of +all configuration variables currently known to the object.

+
objectName config set name ?value?
+

This method sets the configuration variable name to the +specified value and returns the new value of the variable.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that while the user can set the predefined configuration +variables user and format doing so will have no +effect, these values will be internally overriden when invoking an +import plugin.

+
objectName config unset pattern...
+

This method unsets all configuration variables matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration variables.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

Import plugin API v2 reference

+

Plugins are what this package uses to manage the support for any input +format beyond the ToC serialization format. Here we +specify the API the objects created by this package use to interact +with their plugins.

+

A plugin for this package has to follow the rules listed below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + doctools::toc::import::FOO, + where FOO is the name of the format the plugin will + generate output for. This name is also the argument to provide + to the various import methods of import manager + objects to get a string encoding a table of contents in that + format.

    3. +

  3. The plugin can expect that the package + doctools::toc::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    4. +

  4. The plugin can expect that a command named IncludeFile is + present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such. An example of +such a format would be doctoc.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide one command, with the signature shown + below.

    +
    +
    import text configuration
    +

    Whenever an import manager of doctools::toc has to parse +input for a table of contents it will invoke this command.

    +
    +
    string text
    +

    This argument will contain the text encoding the table of contents per +the format the plugin is for.

    +
    dictionary configuration
    +

    This argument will contain the current configuration to apply to the +parsing, as a dictionary mapping from variable names to values.

    +

    The following configuration variables have a predefined meaning all +plugins have to obey, although they can ignore this information at +their discretion. Any other other configuration variables recognized +by a plugin will be described in the manpage for that plugin.

    +
    +
    user
    +

    This variable is expected to contain the name of the user + owning the process invoking the plugin.

    +
    format
    +

    This variable is expected to contain the name of the + format whose plugin is invoked.

    +
    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of the invokations of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_import_json.html @@ -0,0 +1,331 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::import::json(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::import::json - JSON import plugin

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::import::json ?0.1?
    • +
  • package require doctools::toc::structure
    • +
  • package require json
    • +
+
    +
  • import string configuration
    • +
+
+
+

Description

+

This package implements the doctools table of contents import plugin +for the parsing of JSON markup.

+

This is an internal package of doctools, for use by the higher level +management packages handling tables of contents, especially doctools::toc::import, the import manager.

+

Using it from a regular interpreter is possible, however only with +contortions, and is not recommended. +The proper way to use this functionality is through the package +doctools::toc::import and the import manager objects it +provides.

+
+

API

+

The API provided by this package satisfies the specification of the +doctoc import plugin API version 2.

+
+
import string configuration
+

This command takes the string and parses it as JSON +markup encoding a table of contents, in the context of the specified +configuration (a dictionary). The result of the command is the +canonical serialization of that table of contents, in the form +specified in section ToC serialization format.

+
+
+

JSON notation of tables of contents

+

The JSON format used for tables of contents is a direct translation of +the ToC serialization format, mapping Tcl dictionaries as +JSON objects and Tcl lists as JSON arrays. +For example, the Tcl serialization

+
+doctools::toc {
+    items {
+        {reference {
+	    desc {DocTools - Tables of Contents}
+	     id introduction.man
+	     label doctools::toc::introduction
+	}}
+	{division {
+	     id processing.man
+	     items {
+	         {reference {
+		     desc {doctoc serialization utilities}
+		     id structure.man
+		     label doctools::toc::structure
+		 }}
+		 {reference {
+		     desc {Parsing text in doctoc format}
+		     id parse.man
+		     label doctools::toc::parse
+		 }}
+	     }
+             label Processing
+        }}
+    }
+    label {Table of Contents} 
+    title TOC
+}
+
+

is equivalent to the JSON string

+
+{
+    "doctools::toc" : {
+        "items" : [{
+            "reference" : {
+                "desc"  : "DocTools - Tables of Contents",
+                "id"    : "introduction.man",
+                "label" : "doctools::toc::introduction"
+            }
+        },{
+            "division" : {
+                "id"    : "processing.man",
+                "items" : [{
+                    "reference" : {
+                        "desc"  : "doctoc serialization utilities",
+                        "id"    : "structure.man",
+                        "label" : "doctools::toc::structure"
+                    }
+                },{
+                    "reference" : {
+                        "desc"  : "Parsing text in doctoc format",
+                        "id"    : "parse.man",
+                        "label" : "doctools::toc::parse"
+                    }
+                }],
+                "label" : "Processing"
+            }
+        }],
+        "label" : "Table of Contents",
+        "title" : "TOC"
+    }
+}
+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text formatter plugin

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_introduction.html @@ -0,0 +1,251 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools2toc_introduction(n) 2.0 tcllib "Documentation tools"

+

Name

+

doctools2toc_introduction - DocTools - Tables of Contents

+
+ +

Description

+

doctoc (short for documentation tables of contents) +stands for a set of related, yet different, entities which are working +together for the easy creation and transformation of tables and +contents for documentation.

+

These are

+
    +

  1. A tcl based language for the semantic markup of a table of contents. +Markup is represented by Tcl commands. +Beginners should start with the +doctoc language introduction. +The formal specification is split over two documents, one dealing with +the doctoc language syntax, the other a +doctoc language command reference.

    2. +

  2. A set of packages for the programmatic manipulation of tables of +contents in memory, and their conversion between various formats, +reading and writing. The aforementioned markup language is one of the +formats which can be both read from and written to.

    3. +

  3. The system for the conversion of tables of contents is based on a +plugin mechanism, for this we have two APIs describing the interface +between the packages above and the import/export plugins.

    4. +
+

Which of the more detailed documents are relevant to the reader of +this introduction depends on their role in the documentation process.

+
    +

  1. A writer of documentation has to understand the markup language +itself. A beginner to doctoc should read the more informally written +doctoc language introduction first. Having digested this +the formal doctoc language syntax specification should +become understandable. A writer experienced with doctoc may only +need the doctoc language command reference from time to +time to refresh her memory.

    +

    While a document is written the dtp application can be used +to validate it, and after completion it also performs the conversion +into the chosen system of visual markup, be it *roff, HTML, plain +text, wiki, etc. The simpler dtplite application makes +internal use of doctoc when handling directories of documentation, +automatically generating a proper table of contents for them.

    2. +

  2. A processor of documentation written in the doctoc +markup language has to know which tools are available for use.

    +

    The main tool is the aforementioned dtp application provided +by Tcllib. The simpler dtplite does not expose doctoc to the +user. At the bottom level, common to both applications, however we +find the three packages providing the basic facilities to handle +tables of contents, i.e. import from textual formats, programmatic +manipulation in memory, and export to textual formats. These are

    +
    +
    doctoools::toc
    +

    Programmatic manipulation of tables of contents in memory.

    +
    doctoools::toc::import
    +

    Import of tables of contents from various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    doctoools::toc::export
    +

    Export of tables of contents to various textual formats. The set of +supported formats is extensible through plugin packages.

    +
    +

    See also section Package Overview for an overview of the +dependencies between these and other, supporting packages.

    3. +

  3. At last, but not least, plugin writers have to understand the +interaction between the import and export packages and their plugins. +These APIs are described in the documentation for the two relevant +packages, i.e.

    +
      +

    • doctoools::toc::import

      • +

    • doctoools::toc::export

      • +
    +
    4. +
+
+

Related formats

+

The doctoc format does not stand alone, it has two companion formats. +These are called docidx and doctools, and they are +intended for the markup of keyword indices, and of general +documentation, respectively. +They are described in their own sets of documents, starting at +the DocTools - Keyword Indices and +the DocTools - General, respectively.

+
+

Package Overview

+
+                                    ~~~~~~~~~~~ doctools::toc ~~~~~~~~~~~
+                                   ~~                   |               ~~
+                doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import
+                        |                               |                       |
+        +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
+        |               |                         |     |    |                  |               |                       |               |
+doctools::config        =                         |     |    |                  =       doctools::include       doctools::config doctools::paths
+                        |                         |     |    |                  |
+                doctools::toc::export::<*>        |     |    |          doctools::toc::import::<*>
+                        doctoc                    |     |    |                  doctoc, json
+                        json                      |     |    |                  |           \\
+                        html                      |     |    |          doctools::toc::parse \\
+                        nroff                     |     |    |                  |             \\
+                        wiki                      |     |    |  +---------------+              json
+                        text                      |     |    |  |               |
+                                                doctools::toc::structure        |
+                                                                                |
+                                                                        +-------+---------------+
+                                                                        |                       |
+          doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat        
+                |                                                                               |
+          doctools::text  doctools::nroff::man_macros                                           =
+                                                                                                |
+                                                                                        doctools::msgcat::toc::<*>
+                                                                                                c, en, de, fr
+                                                                                                (fr == en for now)
+        ~~      Interoperable objects, without actual package dependencies
+        --      Package dependency, higher requires lower package
+        =       Dynamic dependency through plugin system
+        <*>     Multiple packages following the given form of naming.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::c ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::c is a +support module providing the C language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::de ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::de is a +support module providing the DE (german) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::en ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::en is a +support module providing the EN (english) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require msgcat
    • +
  • package require doctools::msgcat::toc::fr ?0.1?
    • +
+
+
+

Description

+

The package doctools::msgcat::toc::fr is a +support module providing the FR (french) language message catalog +for the doctoc parser in the doctools system version 2. As such it is +an internal package a regular user (developer) should not be in direct +contact with.

+

If you are such please go the documentation of either

+
    +

  1. doctools::doc,

    2. +

  2. doctools::toc, or

    3. +

  3. doctools::idx

    4. +
+

Within the system architecture this package resides under the package +doctools::msgcat providing the general message catalog +management within the system. Note that there is no +explicit dependency between the manager and catalog packages. The +catalog is a plugin which is selected and loaded dynamically.

+
+

API

+

This package has no exported API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_parse.html @@ -0,0 +1,365 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::parse(n) 1 tcllib "Documentation tools"

+

Name

+

doctools::toc::parse - Parsing text in doctoc format

+
+ +

Synopsis

+
+
    +
  • package require doctools::toc::parse ?0.1?
    • +
  • package require Tcl 8.4
    • +
  • package require doctools::toc::structure
    • +
  • package require doctools::msgcat
    • +
  • package require doctools::tcl::parse
    • +
  • package require fileutil
    • +
  • package require logger
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::stack
    • +
+ +
+
+

Description

+

This package provides commands to parse text written in the +doctoc markup language and convert it into the canonical +serialization of the table of contents encoded in the text. +See the section ToC serialization format for specification +of their format.

+

This is an internal package of doctools, for use by the higher level +packages handling doctoc documents.

+
+

API

+
+
::doctools::toc::parse text text
+

The command takes the string contained in text and parses it +under the assumption that it contains a document written using the +doctoc markup language. An error is thrown if this assumption +is found to be false. The format of these errors is described in +section Parse errors.

+

When successful the command returns the canonical serialization of the +table of contents which was encoded in the text. +See the section ToC serialization format for specification +of that format.

+
::doctools::toc::parse file path
+

The same as text, except that the text to parse is read from +the file specified by path.

+
::doctools::toc::parse includes
+

This method returns the current list of search paths used when looking +for include files.

+
::doctools::toc::parse include add path
+

This method adds the path to the list of paths searched when +looking for an include file. The call is ignored if the path is +already in the list of paths. The method returns the empty string as +its result.

+
::doctools::toc::parse include remove path
+

This method removes the path from the list of paths searched +when looking for an include file. The call is ignored if the path is +not contained in the list of paths. The method returns the empty +string as its result.

+
::doctools::toc::parse include clear
+

This method clears the list of search paths for include files.

+
::doctools::toc::parse vars
+

This method returns a dictionary containing the current set of +predefined variables known to the vset markup command during +processing.

+
::doctools::toc::parse var set name value
+

This method adds the variable name to the set of predefined +variables known to the vset markup command during processing, +and gives it the specified value. The method returns the empty +string as its result.

+
::doctools::toc::parse var unset name
+

This method removes the variable name from the set of predefined +variables known to the vset markup command during +processing. The method returns the empty string as its result.

+
::doctools::toc::parse var clear ?pattern?
+

This method removes all variables matching the pattern from the +set of predefined variables known to the vset markup command +during processing. The method returns the empty string as its result.

+

The pattern matching is done with string match, and the +default pattern used when none is specified, is *.

+
+
+

Parse errors

+

The format of the parse error messages thrown when encountering +violations of the doctoc markup syntax is human readable and +not intended for processing by machines. As such it is not documented.

+

However, the errorCode attached to the message is +machine-readable and has the following format:

+
    +

  1. The error code will be a list, each element describing a single error +found in the input. The list has at least one element, possibly more.

    2. +

  2. Each error element will be a list containing six strings describing an +error in detail. The strings will be

    +
      +

    1. The path of the file the error occured in. This may be empty.

      2. +

    2. The range of the token the error was found at. This range is a +two-element list containing the offset of the first and last character +in the range, counted from the beginning of the input (file). Offsets +are counted from zero.

      3. +

    3. The line the first character after the error is on. +Lines are counted from one.

      4. +

    4. The column the first character after the error is at. +Columns are counted from zero.

      5. +

    5. The message code of the error. This value can be used as argument to +msgcat::mc to obtain a localized error message, assuming that +the application had a suitable call of doctools::msgcat::init to +initialize the necessary message catalogs (See package +doctools::msgcat).

      6. +

    6. A list of details for the error, like the markup command involved. In +the case of message code doctoc/include/syntax this value is +the set of errors found in the included file, using the format +described here.

      7. +
    +
    3. +
+
+

[doctoc] notation of tables of contents

+

The doctoc format for tables of contents, also called the +doctoc markup language, is too large to be covered in single +section. +The interested reader should start with the document

+
    +

  1. doctoc language introduction

    2. +
+

and then proceed from there to the formal specifications, i.e. the +documents

+
    +

  1. doctoc language syntax and

    2. +

  2. doctoc language command reference.

    3. +
+

to get a thorough understanding of the language.

+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html Index: embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html ================================================================== --- embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html +++ embedded/www/tcllib/files/modules/doctools2toc/toc_structure.html @@ -0,0 +1,318 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

doctools::toc::structure(n) 0.1 tcllib "Documentation tools"

+

Name

+

doctools::toc::structure - Doctoc serialization utilities

+
+ + +

Description

+

This package provides commands to work with the serializations of +tables of contents as managed by the doctools system v2, and specified +in section ToC serialization format.

+

This is an internal package of doctools, for use by the higher level +packages handling tables of contents and their conversion into and out +of various other formats, like documents written using doctoc +markup.

+
+

API

+
+
::doctools::toc::structure verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +regular serialization of a table of contents and will throw an +error if that is not the case. The result of the command is the empty +string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
::doctools::toc::structure verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a table of contents and will throw +an error if that is not the case. The result of the command is the +empty string.

+

For the specification of canonical serializations see the section +ToC serialization format.

+
::doctools::toc::structure canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a table of contents and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained table of contents and return it as its result. If the +input is already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
::doctools::toc::structure print serial
+

This command assumes that the argument serial contains a valid +regular serialization of a table of contents and returns a string +containing that table in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of regular serializations see the section +ToC serialization format.

+
::doctools::toc::structure merge seriala serialb
+

This command accepts the regular serializations of two tables of +contents and uses them to create their union. The result of the +command is the canonical serialization of this unified table of +contents.

+

Title and label of the resulting table are taken from the table +contained in serialb.

+

The whole table and its divisions are merged recursively in the same +manner:

+
    +

  1. All reference elements which occur in both divisions (identified by +their label) are unified with document id's and descriptions taken +from the second table.

    2. +

  2. All division elements which occur in both divisions (identified by +their label) are unified with the optional document id taken from the +second table, if any, or from the first if none is in the second. The +elements in the division are merged recursively using the same +algorithm as described in this list.

    3. +

  3. Type conflicts between elements, i.e. finding two elements with the +same label but different types result in a merge error.

    4. +

  4. All elements found in the second division but not in the first are +added to the end of the list of elements in the merge result.

    5. +
+

For the specification of regular and canonical serializations see the +section ToC serialization format.

+
+
+

ToC serialization format

+

Here we specify the format used by the doctools v2 packages to +serialize tables of contents as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a table of contents may have more than one regular serialization +only exactly one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any table of contents is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, doctools::toc, and its +value. This value holds the contents of the table of contents.

    3. +

  3. The contents of the table of contents are a Tcl dictionary holding the +title of the table of contents, a label, and its elements. The +relevant keys and their values are

    +
    +
    title
    +

    The value is a string containing the title of the table of contents.

    +
    label
    +

    The value is a string containing a label for the table of contents.

    +
    items
    +

    The value is a Tcl list holding the elements of the table, in the +order they are to be shown.

    +

    Each element is a Tcl list holding the type of the item, and its +description, in this order. An alternative description would be that +it is a Tcl dictionary holding a single key, the item type, mapped to +the item description.

    +

    The two legal item types and their descriptions are

    +
    +
    reference
    +

    This item describes a single entry in the table of contents, +referencing a single document. +To this end its value is a Tcl dictionary containing an id for the +referenced document, a label, and a longer textual description which +can be associated with the entry. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the entry.

    +
    label
    +

    The value is a string containing a label for this entry. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    desc
    +

    The value is a string containing a longer description for this entry.

    +
    +
    division
    +

    This item describes a group of entries in the table of contents, +inducing a hierarchy of entries. +To this end its value is a Tcl dictionary containing a label for the +group, an optional id to a document for the whole group, and the list +of entries in the group. +The relevant keys and their values are

    +
    +
    id
    +

    The value is a string containing the id of the document associated +with the whole group. This key is optional.

    +
    label
    +

    The value is a string containing a label for the group. This string +also identifies the entry, and no two entries (references and +divisions) in the containing list are allowed to have the same label.

    +
    items
    +

    The value is a Tcl list holding the elements of the group, in the +order they are to be shown. +This list has the same structure as the value for the keyword +items used to describe the whole table of contents, see +above. This closes the recusrive definition of the structure, with +divisions holding the same type of elements as the whole table of +contents, including other divisions.

    +
    +
    +
    +
    4. +
+
canonical serialization
+

The canonical serialization of a table of contents has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this table of contents.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html Index: embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html ================================================================== --- embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html +++ embedded/www/tcllib/files/modules/dtplite/pkg_dtplite.html @@ -0,0 +1,430 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

dtplite(n) 1.3 tcllib "Documentation toolbox"

+

Name

+

dtplite - Lightweight DocTools Markup Processor

+
+ + +

Description

+

The application described by this document, dtplite, is the +successor to the extremely simple mpexpand. Influenced in its +functionality by the dtp doctools processor it is much more +powerful than mpexpand, yet still as easy to use; definitely +easier than dtp with its myriad of subcommands and options.

+

dtplite is based upon the package doctools, like +the other two processors.

+

USE CASES

+

dtplite was written with the following three use cases in +mind.

+
    +

  1. Validation of a single document, i.e. checking that it was written in +valid doctools format. This mode can also be used to get a preliminary +version of the formatted output for a single document, for display in +a browser, nroff, etc., allowing proofreading of the formatting.

    2. +

  2. Generation of the formatted documentation for a single package, +i.e. all the manpages, plus a table of contents and an index of +keywords.

    3. +

  3. An extension of the previous mode of operation, a method for the easy +generation of one documentation tree for several packages, and +especially of a unified table of contents and keyword index.

    4. +
+

Beyond the above we also want to make use of the customization +features provided by the HTML formatter. It is not the only format the +application should be able to generate, but we anticipiate it to be +the most commonly used, and it is one of the few which do provide +customization hooks.

+

We allow the caller to specify a header string, footer string, a +stylesheet, and data for a bar of navigation links at the top of the +generated document. +While all can be set as long as the formatting engine provides an +appropriate engine parameter (See section OPTIONS) the last +two have internal processing which make them specific to HTML.

+
+

COMMAND LINE

+
+
dtplite -o output ?options? format inputfile
+

This is the form for use case [1]. The options will be +explained later, in section OPTIONS.

+
+
path output (in)
+

This argument specifies where to write the generated document. It can +be the path to a file or directory, or -. +The last value causes the application to write the generated +documented to stdout.

+

If the output does not exist then [file dirname $output] +has to exist and must be a writable directory. +The generated document will be written to a file in that directory, +and the name of that file will be derived from the inputfile, +the format, and the value given to option -ext (if +present).

+
(path|handle) format (in)
+

This argument specifies the formatting engine to use when processing +the input, and thus the format of the generated document. See section +FORMATS for the possibilities recognized by the application.

+
path inputfile (in)
+

This argument specifies the path to the file to process. It has to +exist, must be readable, and written in doctools format.

+
+
dtplite validate inputfile
+

This is a simpler form for use case [1]. The "validate" format +generates no output at all, only syntax checks are performed. As such +the specification of an output file or other options is not necessary +and left out.

+
dtplite -o output ?options? format inputdirectory
+

This is the form for use case [2]. It differs from the form for +use case [1] by having the input documents specified through a +directory instead of a file. The other arguments are identical, except +for output, which now has to be the path to an existing and +writable directory.

+

The input documents are all files in inputdirectory or any of +its subdirectories which were recognized by fileutil::fileType +as containing text in doctools format.

+
dtplite -merge -o output ?options? format inputdirectory
+

This is the form for use case [3]. The only difference to the +form for use case [2] is the additional option -merge.

+

Each such call will merge the generated documents coming from +processing the input documents under inputdirectory or any of +its subdirectories to the files under output. In this manner it +is possible to incrementally build the unified documentation for any +number of packages. Note that it is necessary to run through all the +packages twice to get fully correct cross-references (for formats +supporting them).

+
+
+

OPTIONS

+

This section describes all the options available to the user of the +application, with +the exception of the options -o and -merge. These +two were described already, in section COMMAND LINE.

+
+
-exclude string
+

This option specifies an exclude (glob) pattern. Any files identified +as manpages to process which match the exclude pattern are +ignored. The option can be provided multiple times, each usage adding +an additional pattern to the list of exclusions.

+
-ext string
+

If the name of an output file has to be derived from the name of an +input file it will use the name of the format as the extension +by default. This option here will override this however, forcing it to +use string as the file extension. This option is ignored if the +name of the output file is fully specified through option -o.

+

When used multiple times only the last definition is relevant.

+
-header file
+

This option can be used if and only if the selected format +provides an engine parameter named "header". It takes the contents of +the specified file and assign them to that parameter, for whatever use +by the engine. The HTML engine will insert the text just after the tag +<body>. +If navigation buttons are present (see option -nav below), +then the HTML generated for them is appended to the header data +originating here before the final assignment to the parameter.

+

When used multiple times only the last definition is relevant.

+
-footer file
+

Like -header, except that: Any navigation buttons are ignored, +the corresponding required engine parameter is named "footer", and the +data is inserted just before the tag </body>.

+

When used multiple times only the last definition is relevant.

+
-style file
+

This option can be used if and only if the selected format +provides an engine parameter named "meta". When specified it will +generate a piece of HTML code declaring the file as the +stylesheet for the generated document and assign that to the +parameter. The HTML engine will insert this inot the document, just +after the tag <head>.

+

When processing an input directory the stylesheet file is copied into +the output directory and the generated HTML will refer to the copy, to +make the result more self-contained. When processing an input file we +have no location to copy the stylesheet to and so just reference it as +specified.

+

When used multiple times only the last definition is relevant.

+
-toc path|text
+

This option specifies a doctoc file (or text) to use for the table of contents +instead of generating our own.

+

When used multiple times only the last definition is relevant.

+
-pre+toc label path|text
+
+
-post+toc label path|text
+

This option specifies additional doctoc files (or texts) to use in +the navigation bar.

+

Positioning and handling of multiple uses is like for options +-prenav and -postnav, see below.

+
-nav label url
+
+
-prenav label url
+

Use this option to specify a navigation button with label to +display and the url to link to. This option can be used if and +only if the selected format provides an engine parameter named +"header". The HTML generated for this is appended to whatever data we +got from option -header before it is inserted into the +generated documents.

+

When used multiple times all definitions are collected and a +navigation bar is created, with the first definition shown at the left +edge and the last definition to the right.

+

The url can be relative. In that case it is assumed to be relative +to the main files (TOC and Keyword index), and will be transformed for +all others to still link properly.

+
-postnav label url
+

Use this option to specify a navigation button with label to +display and the url to link to. This option can be used if and +only if the selected format provides an engine parameter named +"header". The HTML generated for this is appended to whatever data we +got from option -header before it is inserted into the +generated documents.

+

When used multiple times all definitions are collected and a +navigation bar is created, with the last definition shown at the right +edge and the first definition to the left.

+

The url can be relative. In that case it is assumed to be relative +to the main files (TOC and Keyword index), and will be transformed for +all others to still link properly.

+
+
+

FORMATS

+

At first the format argument will be treated as a path to a tcl +file containing the code for the requested formatting engine. The +argument will be treated as the name of one of the predefined formats +listed below if and only if the path does not exist.

+

Note a limitation: If treating the format as path to the tcl +script implementing the engine was sucessful, then this script has to +implement not only the engine API for doctools, i.e. +doctools_api, but for doctoc_api and docidx_api +as well. Otherwise the generation of a table of contents and of a +keyword index will fail.

+

List of predefined formats, i.e. as provided by the +package doctools:

+
+
nroff
+

The processor generates *roff output, the standard format for unix +manpages.

+
html
+

The processor generates HTML output, for usage in and display by web +browsers. This engine is currently the only one providing the various +engine parameters required for the additional customaization of the +output.

+
tmml
+

The processor generates TMML output, the Tcl Manpage Markup Language, +a derivative of XML.

+
latex
+

The processor generates LaTeX output.

+
wiki
+

The processor generates Wiki markup as understood by wikit.

+
list
+

The processor extracts the information provided by manpage_begin. +This format is used internally to extract the meta data from which +both table of contents and keyword index are derived from.

+
null
+

The processor does not generate any output. This is equivalent to +validate.

+
+
+

DIRECTORY STRUCTURES

+

In this section we describe the directory structures generated by the +application under output when processing all documents in an +inputdirectory. In other words, this is only relevant to the use +cases [2] and [3].

+
+
[2]
+

The following directory structure is created when processing a single +set of input documents. The file extension used is for output in +HTML, but that is not relevant to the structure and was just used to +have proper file names.

+
+    output/
+        toc.html
+        index.html
+        files/
+            path/to/FOO.html
+
+

The last line in the example shows the document +generated for a file FOO located at

+
+    inputdirectory/path/to/FOO
+
+
+
[3]
+

When merging many packages into a unified set of documents the +generated directory structure is a bit deeper:

+
+    output
+        .toc
+        .idx
+        .tocdoc
+        .idxdoc
+        .xrf
+        toc.html
+        index.html
+        FOO1/
+            ...
+        FOO2/
+            toc.html
+            files/
+                path/to/BAR.html
+
+

Each of the directories FOO1, ... contains the documents generated for +the package FOO1, ... and follows the structure shown for use case +[2]. The only exception is that there is no per-package index.

+

The files ".toc", ".idx", and ".xrf" contain the +internal status of the whole output and will be read and updated by +the next invokation. Their contents will not be documented. Remove +these files when all packages wanted for the output have been +processed, i.e. when the output is complete.

+

The files ".tocdoc", and ".idxdoc", are intermediate files +in doctoc and docidx markup, respectively, containing the main table +of contents and keyword index for the set of documents before their +conversion to the chosen output format. +They are left in place, i.e. not deleted, to serve as demonstrations +of doctoc and docidx markup.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category doctools of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/fileutil/fileutil.html Index: embedded/www/tcllib/files/modules/fileutil/fileutil.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/fileutil.html +++ embedded/www/tcllib/files/modules/fileutil/fileutil.html @@ -0,0 +1,531 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil(n) 1.15 tcllib "file utilities"

+

Name

+

fileutil - Procedures implementing some file utilities

+
+ + +

Description

+

This package provides implementations of standard unix utilities.

+
+
::fileutil::lexnormalize path
+

This command performs purely lexical normalization on the path and returns +the changed path as its result. Symbolic links in the path are not resolved.

+

Examples:

+
+    fileutil::lexnormalize /foo/./bar
+    => /foo/bar
+    fileutil::lexnormalize /foo/../bar
+    => /bar
+
+
+
::fileutil::fullnormalize path
+

This command resolves all symbolic links in the path and returns +the changed path as its result. +In contrast to the builtin file normalize this command +resolves a symbolic link in the last element of the path as well.

+
::fileutil::test path codes ?msgvar? ?label?
+

A command for the testing of several properties of a path. The +properties to test for are specified in codes, either as a list +of keywords describing the properties, or as a string where each +letter is a shorthand for a property to test. The recognized keywords, +shorthands, and associated properties are shown in the list below. The +tests are executed in the order given to the command.

+

The result of the command is a boolean value. It will be true if and +only if the path passes all the specified tests. +In the case of the path not passing one or more test the first +failing test will leave a message in the variable referenced by +msgvar, if such is specified. The message will be prefixed with +label, if it is specified. +Note that the variabled referenced by msgvar is not touched at +all if all the tests pass.

+
+
read
+

file readable

+
write
+

file writable

+
exists
+

file exists

+
exec
+

file executable

+
file
+

file isfile

+
dir
+

file isdirectory

+
+
::fileutil::cat (?options? file)...
+

A tcl implementation of the UNIX cat command. Returns the +contents of the specified file(s). The arguments are files to read, +with interspersed options configuring the process. If there are +problems reading any of the files, an error will occur, and no data +will be returned.

+

The options accepted are -encoding, -translation, +-eofchar, and --. With the exception of the last all +options take a single value as argument, as specified by the tcl +builtin command fconfigure. The -- has to be used to +terminate option processing before a file if that file's name begins +with a dash.

+

Each file can have its own set of options coming before it, and for +anything not specified directly the defaults are inherited from the +options of the previous file. The first file inherits the system +default for unspecified options.

+
::fileutil::writeFile ?options? file data
+

The command replaces the current contents of the specified file +with data, with the process configured by the options. The +command accepts the same options as ::fileutil::cat. The +specification of a non-existent file is legal and causes the command +to create the file (and all required but missing directories).

+
::fileutil::appendToFile ?options? file data
+

This command is like ::fileutil::writeFile, except that the +previous contents of file are not replaced, but appended to. The +command accepts the same options as ::fileutil::cat

+
::fileutil::insertIntoFile ?options? file at data
+

This comment is similar to ::fileutil::appendToFile, except that +the new data is not appended at the end, but inserted at a specified +location within the file. In further contrast this command has to be +given the path to an existing file. It will not create a missing file, +but throw an error instead.

+

The specified location at has to be an integer number in the +range 0 ... [file size file]. 0 will cause +insertion of the new data before the first character of the existing +content, whereas [file size file] causes insertion after +the last character of the existing content, i.e. appending.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::removeFromFile ?options? file at n
+

This command is the complement to ::fileutil::insertIntoFile, removing n characters from the file, starting at location at. +The specified location at has to be an integer number in the +range 0 ... [file size file] - n. 0 +will cause the removal of the new data to start with the first +character of the existing content, +whereas [file size file] - n causes the removal of +the tail of the existing content, i.e. the truncation of the file.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::replaceInFile ?options? file at n data
+

This command is a combination of ::fileutil::removeFromFile and +::fileutil::insertIntoFile. It first removes the part of the +contents specified by the arguments at and n, and then +inserts data at the given location, effectively replacing the +removed by content with data. +All constraints imposed on at and n by +::fileutil::removeFromFile and ::fileutil::insertIntoFile +are obeyed.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::updateInPlace ?options? file cmd
+

This command can be seen as the generic core functionality of +::fileutil::replaceInFile. +It first reads the contents of the specified file, then runs the +command prefix cmd with that data appended to it, and at last +writes the result of that invokation back as the new contents of the +file.

+

If the executed command throws an error the file is not changed.

+

The command accepts the same options as ::fileutil::cat.

+
::fileutil::fileType filename
+

An implementation of the UNIX file command, which uses +various heuristics to guess the type of a file. Returns a list +specifying as much type information as can be determined about the +file, from most general (eg, "binary" or "text") to most specific (eg, +"gif"). For example, the return value for a GIF file would be "binary +graphic gif". The command will detect the following types of files: +directory, empty, binary, text, script (with interpreter), executable +elf, executable dos, executable ne, executable pe, graphic gif, graphic +jpeg, graphic png, graphic tiff, graphic bitmap, html, xml (with doctype +if available), message pgp, binary pdf, text ps, text eps, binary +gravity_wave_data_frame, compressed bzip, compressed gzip, compressed +zip, compressed tar, audio wave, audio mpeg, and link. It further +detects doctools, doctoc, and docidx documentation files, and +tklib diagrams.

+
::fileutil::find ?basedir ?filtercmd??
+

An implementation of the unix command find. Adapted from the +Tcler's Wiki. Takes at most two arguments, the path to the directory +to start searching from and a command to use to evaluate interest in +each file. The path defaults to ".", i.e. the current +directory. The command defaults to the empty string, which means that +all files are of interest. The command takes care not to +lose itself in infinite loops upon encountering circular link +structures. The result of the command is a list containing the paths +to the interesting files.

+

The filtercmd, if specified, is interpreted as a command prefix +and one argument is added to it, the name of the file or directory +find is currently looking at. Note that this name is not fully +qualified. It has to be joined it with the result of pwd to get +an absolute filename.

+

The result of filtercmd is a boolean value that indicates if the +current file should be included in the list of interesting files.

+

Example:

+
+    # find .tcl files
+    package require fileutil
+    proc is_tcl {name} {return [string match *.tcl $name]}
+    set tcl_files [fileutil::find . is_tcl]
+
+
+
::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
+

This command is based upon the TclX command +recursive_glob, except that it doesn't allow recursion over more +than one directory at a time. It uses ::fileutil::find +internally and is thus able to and does follow symbolic links, +something the TclX command does not do. First argument is +the directory to start the search in, second argument is a list of +patterns. The command returns a list of all files reachable +through basedir whose names match at least one of the +patterns. The options before the pattern-list determine the style of +matching, either regexp or glob. glob-style matching is the default if +no options are given. Usage of the option -- stops option +processing. This allows the use of a leading '-' in the patterns.

+
::fileutil::foreachLine var filename cmd
+

The command reads the file filename and executes the script +cmd for every line in the file. During the execution of the +script the variable var is set to the contents of the current +line. The return value of this command is the result of the last +invocation of the script cmd or the empty string if the file was +empty.

+
::fileutil::grep pattern ?files?
+

Implementation of grep. Adapted from the Tcler's Wiki. The +first argument defines the pattern to search for. This is +followed by a list of files to search through. The list is +optional and stdin will be used if it is missing. The result +of the procedures is a list containing the matches. Each match is a +single element of the list and contains filename, number and contents +of the matching line, separated by a colons.

+
::fileutil::install ?-m mode? source destination
+

The install command is similar in functionality to the install +command found on many unix systems, or the shell script +distributed with many source distributions (unix/install-sh in the Tcl +sources, for example). It copies source, which can be either a +file or directory to destination, which should be a directory, +unless source is also a single file. The ?-m? option lets +the user specify a unix-style mode (either octal or symbolic - see +file attributes.

+
::fileutil::stripN path n
+

Removes the first n elements from the specified path and +returns the modified path. If n is greater than the number of +components in path an empty string is returned. The number of +components in a given path may be determined by performing +llength on the list returned by file split.

+
::fileutil::stripPwd path
+

If, and only if the path is inside of the directory returned by +[pwd] (or the current working directory itself) it is made +relative to that directory. In other words, the current working +directory is stripped from the path. The possibly modified path +is returned as the result of the command. If the current working +directory itself was specified for path the result is the string +".".

+
::fileutil::stripPath prefix path
+

If, and only of the path is inside of the directory +"prefix" (or the prefix directory itself) it is made relative to +that directory. In other words, the prefix directory is stripped from +the path. The possibly modified path is returned as the result +of the command. +If the prefix directory itself was specified for path the result +is the string ".".

+
::fileutil::jail jail path
+

This command ensures that the path is not escaping the directory +jail. It always returns an absolute path derived from path +which is within jail.

+

If path is an absolute path and already within jail it is +returned unmodified.

+

An absolute path outside of jail is stripped of its root element +and then put into the jail by prefixing it with it. The same +happens if path is relative, except that nothing is stripped of +it. Before adding the jail prefix the path is lexically +normalized to prevent the caller from using .. segments in +path to escape the jail.

+
::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
+

Implementation of touch. Alter the atime and mtime of the +specified files. If -c, do not create files if they do not +already exist. If -r, use the atime and mtime from +ref_file. If -t, use the integer clock value +time. It is illegal to specify both -r and +-t. If -a, only change the atime. If -m, +only change the mtime.

+

This command is not available for Tcl versions less than 8.3.

+
::fileutil::tempdir
+

The command returns the path of a directory where the caller can +place temporary files, such as "/tmp" on Unix systems. The +algorithm we use to find the correct directory is as follows:

+
    +

  1. The directory set by an invokation of ::fileutil::tempdir with +an argument. If this is present it is tried exclusively and none of +the following item are tried.

    2. +

  2. The directory named in the TMPDIR environment variable.

    3. +

  3. The directory named in the TEMP environment variable.

    4. +

  4. The directory named in the TMP environment variable.

    5. +

  5. A platform specific location:

    +
    +
    Windows
    +

    "C:\TEMP", "C:\TMP", "\TEMP", +and "\TMP" are tried in that order.

    +
    (classic) Macintosh
    +

    The TRASH_FOLDER environment variable is used. This is most likely +not correct.

    +
    Unix
    +

    The directories "/tmp", "/var/tmp", and "/usr/tmp" are +tried in that order.

    +
    +
    6. +
+

The algorithm utilized is mainly that used in the Python standard +library. The exception is the first item, the ability to have the +search overridden by a user-specified directory.

+
::fileutil::tempdir path
+

In this mode the command sets the path as the first and only +directory to try as a temp. directory. See the previous item for the +use of the set directory. The command returns the empty string.

+
::fileutil::tempdirReset
+

Invoking this command clears the information set by the +last call of [::fileutil::tempdir path]. +See the last item too.

+
::fileutil::tempfile ?prefix?
+

The command generates a temporary file name suitable for writing to, +and the associated file. The file name will be unique, and the file +will be writable and contained in the appropriate system specific temp +directory. The name of the file will be returned as the result of the +command.

+

The code was taken from http://wiki.tcl.tk/772, attributed to +Igor Volobouev and anon.

+
::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
+

The command generates a temporary directory suitable for writing to. +The directory name will be unique, and the directory will be writable +and contained in the appropriate system specific temp directory. The +name of the directory will be returned as the result of the command.

+

The three options can used to tweak the behaviour of the command:

+
+
-prefix str
+

The initial, fixed part of the directory name. Defaults to tmp if not specified.

+
-suffix str
+

The fixed tail of the directory. Defaults to the empty string if not specified.

+
-dir str
+

The directory to place the new directory into. Defaults to the result of fileutil::tempdir if not specified.

+
+

The initial code for this was supplied by Miguel Martinez Lopez.

+
::fileutil::relative base dst
+

This command takes two directory paths, both either absolute or relative +and computes the path of dst relative to base. This relative +path is returned as the result of the command. As implied in the previous +sentence, the command is not able to compute this relationship between the +arguments if one of the paths is absolute and the other relative.

+

Note: The processing done by this command is purely lexical. +Symbolic links are not taken into account.

+
::fileutil::relativeUrl base dst
+

This command takes two file paths, both either absolute or relative +and computes the path of dst relative to base, as seen +from inside of the base. This is the algorithm how a browser +resolves a relative link found in the currently shown file.

+

The computed relative path is returned as the result of the command. +As implied in the previous sentence, the command is not able to compute +this relationship between the arguments if one of the paths is absolute +and the other relative.

+

Note: The processing done by this command is purely lexical. +Symbolic links are not taken into account.

+
+
+

Warnings and Incompatibilities

+
+
1.14.9
+

In this version fileutil::find's broken system for handling +symlinks was replaced with one working correctly and properly +enumerating all the legal non-cyclic paths under a base directory.

+

While correct this means that certain pathological directory +hierarchies with cross-linked sym-links will now take about O(n**2) +time to enumerate whereas the original broken code managed O(n) due to +its brokenness.

+

A concrete example and extreme case is the "/sys" +hierarchy under Linux where some hundred devices exist under both +"/sys/devices" and "/sys/class" with the two sub-hierarchies +linking to the other, generating millions of legal paths to enumerate. +The structure, reduced to three devices, roughly looks like

+
+	/sys/class/tty/tty0 --> ../../dev/tty0
+	/sys/class/tty/tty1 --> ../../dev/tty1
+	/sys/class/tty/tty2 --> ../../dev/tty1
+	/sys/dev/tty0/bus
+	/sys/dev/tty0/subsystem --> ../../class/tty
+	/sys/dev/tty1/bus
+	/sys/dev/tty1/subsystem --> ../../class/tty
+	/sys/dev/tty2/bus
+	/sys/dev/tty2/subsystem --> ../../class/tty
+
+

The command fileutil::find currently has no way to escape +this. When having to handle such a pathological hierarchy It is +recommended to switch to package fileutil::traverse and the +same-named command it provides, and then use the -prefilter +option to prevent the traverser from following symbolic links, like so:

+
+    package require fileutil::traverse
+    proc NoLinks {fileName} {
+        if {[string equal [file type $fileName] link]} {
+            return 0
+        }
+        return 1
+    }
+    fileutil::traverse T /sys/devices -prefilter NoLinks
+    T foreach p {
+        puts $p
+    }
+    T destroy
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/multi.html Index: embedded/www/tcllib/files/modules/fileutil/multi.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/multi.html +++ embedded/www/tcllib/files/modules/fileutil/multi.html @@ -0,0 +1,169 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::multi(n) 0.1 tcllib "file utilities"

+

Name

+

fileutil::multi - Multi-file operation, scatter/gather, standard object

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::multi ?0.1?
    • +
  • package require fileutil::multi::op ?0.1?
    • +
  • package require wip ?1.0?
    • +
+ +
+
+

Description

+

This package provides a single command to perform actions on multiple +files selected by glob patterns. It is a thin layer over the package +fileutil::multi::op which provides objects for the +same. This package simply creates a single such object and directs all +file commands to it.

+

At the core is a domain specific language allowing the easy +specification of multi-file copy and/or move and/or deletion +operations. Alternate names would be scatter/gather processor, or +maybe even assembler. +For the detailed specification of this language, and examples, please +see the documention for the package fileutil::multi::op.

+
+

PUBLIC API

+

The main command of the package is:

+
+
::fileutil::multi ?word...?
+

This command interprets the specified words as file commands to +execute. See the section FILE API of the +documentation for the package fileutil::multi::op for +the set of acceptable commands, their syntax, and semantics.

+

The result of the command is the result generated by the last file +command it executed.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/multiop.html Index: embedded/www/tcllib/files/modules/fileutil/multiop.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/multiop.html +++ embedded/www/tcllib/files/modules/fileutil/multiop.html @@ -0,0 +1,454 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::multi::op(n) 0.5.3 tcllib "file utilities"

+

Name

+

fileutil::multi::op - Multi-file operation, scatter/gather

+
+ + +

Description

+

This package provides objects which are able to perform actions on +multiple files selected by glob patterns.

+

At the core is a domain specific language allowing the easy +specification of multi-file copy and/or move and/or deletion +operations. Alternate names would be scatter/gather processor, or +maybe even assembler.

+
+

CLASS API

+

The main command of the package is:

+
+
::fileutil::multi::op ?opName? ?word...?
+

The command creates a new multi-file operation object with an +associated global Tcl command whose name is opName. This +command can be used to invoke the various possible file operations. +It has the following general form:

+
+
opName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If the string %AUTO% is used as the opName then the +package will generate a unique name on its own.

+

If one or more words are specified they are interpreted as an +initial set of file commands to execute. I.e. the method do +of the newly constructed object is implicitly invoked using the words +as its arguments.

+
+
+

OBJECT API

+

The following methods are possible for multi-file operation objects:

+
+
$opName do ?word...?
+

This method interprets the specified words as file commands to +execute. See the section FILE API for the set of +acceptable commands, their syntax, and semantics.

+

The result of the method is the result generated by the last file +command it executed.

+
+
+

FILE API

+

Both object constructor and method do take a list of words +and interpret them as file commands to execute. The names were chosen +to allow the construction of operations as sentences in near-natural +language. Most of the commands influence just the state of the object, +i.e. are simply providing the configuration used by the command +triggering the actual action.

+
+
into directory
+

Specifies the destination directory for operations.

+
in directory
+

Alias for into.

+
to directory
+

Alias for into.

+
from directory
+

Specifies the source directory for operations.

+
not pattern
+

Specifies a glob pattern for paths to be excluded from the operation.

+
for pattern
+

Alias for not.

+
exclude pattern
+

Alias for not.

+
but
+

Has no arguments of its own, but looks ahead in the list of words and +executes all not commands immediately following it. This allows the +construction of "but not" and "but exclude" clauses for a more natural +sounding specification of excluded paths.

+
except
+

A semi-alias for but. Has no arguments of its own, but looks +ahead in the list of words and executes all for commands +immediately following it. This allows the construction of "except for" +clauses for a more natural sounding specification of excluded paths.

+
as name
+

Specifies a new name for the first file handled by the current +operation. I.e. for the renaming of a single file during the +operation.

+
recursive
+

Signals that file expansion should happen in the whole directory +hierarchy and not just the directory itself.

+
recursively
+

An alias for recursive.

+
copy
+

Signals that the operation is the copying of files from source to +destination directory per the specified inclusion and exclusion +patterns.

+
move
+

Signals that the operation is the moving of files from source to +destination directory per the specified inclusion and exclusion +patterns.

+
remove
+

Signals that the operation is the removal of files in the destination +directory per the specified inclusion and exclusion patterns.

+
expand
+

Signals that there is no operation but the calculation of the set of +files from the include and exclude patterns. This operation is not +available if the-set is used.

+
invoke cmdprefix
+

Signals that the user-specified command prefix cmdprefix is the +operation to perform. The command prefix is executed at the global +level and given the source directory, destination directory, and set +of files (as dictionary mapping from source to destination files), in +this order.

+
reset
+

Forces the object into the ground state where all parts of the +configuration have default values.

+
(
+

Saves a copy of the current object state on a stack.

+
)
+

Takes the state at the top of the state stack and restores it, +i.e. makes it the new current object state.

+
cd directory
+

Changes the destination directory to the sub-directory directory +of the current destination.

+
up
+

Changes the destination directory to the parent directory of the +current destination.

+
for-windows
+

Checks that Windows is the current platform. Aborts processing if not.

+
for-win
+

An alias for for-windows.

+
for-unix
+

Checks that Unix is the current platform. Aborts processing if not.

+
the pattern
+

This command specifies the files to operate on per a glob pattern, and +is also the active element, i.e. the command which actually performs +the specified operation. All the other commands only modified the +object state to set the operation up, but di nothing else.

+

To allow for a more natural sounding syntax this command also looks +ahead in the list of words looks and executes several commands +immediately following it before performing its own actions. +These commands are as, but, exclude, except, +from, and into (and aliases). That way these commands act +like qualifiers, and still take effect as if they had been written +before this command.

+

After the operation has been performed the object state the exclude +patterns and the alias name, if specified, are reset to their default +values (i.e. empty), but nothing else.

+
the-set varname
+

Like the, however the set of files to use is not specified +implicitly per a glob pattern, but contained and loaded from the +specified variable. The operation expand is not available +if this command is used.

+
-> varname
+

Saves the set of files from the last expansion into the specified +variable.

+
strict
+

Make file expansion and definition of destination directory (in +and aliases) strict, i.e. report errors for missing directories, and +empty expansion.

+
!strict
+

Complement of strict. A missing destination directory or empty +expansion are not reported as errors.

+
files
+

Limit the search to files. Default is to accept every type of path.

+
links
+

Limit the search to symbolic links. Default is to accept every type of path.

+
directories
+

Limit the search to directories. Default is to accept every type of path.

+
dirs
+

An alias for directories.

+
all
+

Accept all types of paths (default).

+
state?
+

Returns the current state of the object as dictionary. The dictionary keys and their meanings are:

+
+
as
+

Last setting made by as.

+
excluded
+

List of currently known exclusion patterns.

+
from
+

Current source directory, set by from.

+
into
+

Current destination directory, set by into (and aliases).

+
operation
+

Current operation to perform, set by copy, move, remove, expand, or invoke.

+
recursive
+

Current recursion status. Set/unset by recursive and !recursive.

+
strict
+

Current strictness. Set/unset by strict and !strict.

+
type
+

Current path type limiter. Set by either files, directories, links, or all.

+
+
as?
+

Returns the current alias name.

+
excluded?
+

Returns the current set of exclusion patterns.

+
from?
+

Returns the current source directory.

+
into?
+

Returns the current destination directory.

+
operation?
+

Returns the current operation to perform.

+
recursive?
+

Returns the current recursion status.

+
strict?
+

Returns the current strictness.

+
type?
+

Returns the current path type limiter.

+
+
+

EXAMPLES

+

The following examples assume that the variable F contains a +reference to a multi-file operation object.

+
+    $F do copy                       \\
+	the  *.dll                    \\
+	from c:/TDK/PrivateOpenSSL/bin \\
+	to   [installdir_of tls]
+
+
+    $F do move      \\
+	the  *       \\
+	from /sources \\
+	into /scratch  \\
+	but not *.html
+    # Alternatively use 'except for *.html'.
+
+
+    $F do           \\
+	move         \\
+	the  index    \\
+	from /sources  \\
+	into /scratch   \\
+	as   pkgIndex.tcl
+
+
+    $F do         \\
+	remove     \\
+	the *.txt  \\
+	in /scratch
+
+

Note that the fact that most commands just modify the object state +allows us to use more off forms as specifications instead of just +nearly-natural language sentences. +For example the second example in this section can re-arranged into:

+
+    $F do            \\
+	from /sources \\
+	into /scratch  \\
+	but not *.html \\
+	move           \\
+	the  *
+
+

and the result is not only still a valid specification, but even stays +relatively readable.

+

Further note that the information collected by the commands but, +except, and as is automatically reset after the associated +the was executed. However no other state is reset in that +manner, allowing the user to avoid repetitions of unchanging +information. For example the second and third examples of this section +can be merged and rewritten into the equivalent:

+
+$F do                   \\
+    move                 \\
+    the  *                \\
+    from /sources          \\
+    into /scratch           \\
+    but not *.html not index \\
+    the  index               \\
+    as   pkgIndex.tcl
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fileutil/traverse.html Index: embedded/www/tcllib/files/modules/fileutil/traverse.html ================================================================== --- embedded/www/tcllib/files/modules/fileutil/traverse.html +++ embedded/www/tcllib/files/modules/fileutil/traverse.html @@ -0,0 +1,279 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil_traverse(n) 0.6 tcllib "file utilities"

+

Name

+

fileutil_traverse - Iterative directory traversal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require fileutil::traverse ?0.6?
    • +
  • package require fileutil
    • +
  • package require control
    • +
+ +
+
+

Description

+

This package provides objects for the programmable traversal of +directory hierarchies. +The main command exported by the package is:

+
+
::fileutil::traverse ?objectName? path ?option value...?
+

The command creates a new traversal object with an associated global +Tcl command whose name is objectName. This command may be used +to invoke various operations on the traverser. +If the string %AUTO% is used as the objectName then a +unique name will be generated by the package itself.

+

Regarding the recognized options see section OPTIONS. Note +that all these options can be set only during the creation of the +traversal object. Changing them later is not possible and causes +errors to be thrown if attempted.

+

The object command has the following general form:

+
+
$traverser command ?arg arg ...?
+

Command and its arguments determine the exact behavior of +the object.

+
+
+

The following commands are possible for traversal objects:

+
+
$traverser files
+

This method is the most highlevel one provided by traversal +objects. When invoked it returns a list containing the names of all +files and directories matching the current configuration of the +traverser.

+
$traverser foreach filevar script
+

The highlevel files method (see above) is based on this +mid-level method. When invoked it finds all files and directories +matching per the current configuration and executes the script +for each path. The current path under consideration is stored in the +variable named by filevar. Both variable and script live / are +executed in the context of the caller of the method. In the method +files the script simply saves the found paths into the list +to return.

+
$traverser next filevar
+

This is the lowest possible interface to the traverser, the core all +higher methods are built on. When invoked it returns a boolean value +indicating whether it found a path matching the current configuration +(True), or not (False). If a path was found it is +stored into the variable named by filevar, in the context of the +caller.

+

The foreach method simply calls this method in a loop +until it returned False. This method is exposed so that we are +also able to incrementally traverse a directory hierarchy in an +event-based manner.

+

Note that the traverser does follow symbolic links, except when +doing so would cause it to enter a link-cycle. In other words, the +command takes care to not lose itself in infinite loops upon +encountering circular link structures. Note that even links which are +not followed will still appear in the result.

+
+
+

OPTIONS

+
+
-prefilter command_prefix
+

This callback is executed for directories. Its result determines if +the traverser recurses into the directory or not. The default is to +always recurse into all directories. The callback is invoked with a +single argument, the absolute path of the directory, and has to +return a boolean value, True when the directory passes the +filter, and False if not.

+
-filter command_prefix
+

This callback is executed for all paths. Its result determines if the +current path is a valid result, and returned by next. The +default is to accept all paths as valid. The callback is invoked with +a single argument, the absolute path to check, and has to +return a boolean value, True when the path passes the filter, +and False if not.

+
-errorcmd command_prefix
+

This callback is executed for all paths the traverser has trouble +with. Like being unable to change into them, get their status, +etc. The default is to ignore any such problems. The callback is +invoked with a two arguments, the absolute path for which the +error occured, and the error message. Errors thrown by the filter +callbacks are handled through this callback too. Errors thrown by the +error callback itself are not caught and ignored, but allowed to pass +to the caller, i.e. however invoked the next. Any other +results from the callback are ignored.

+
+
+

Warnings and Incompatibilities

+
+
0.4.4
+

In this version the traverser's broken system for handling symlinks +was replaced with one working correctly and properly enumerating all +the legal non-cyclic paths under a base directory.

+

While correct this means that certain pathological directory +hierarchies with cross-linked sym-links will now take about O(n**2) +time to enumerate whereas the original broken code managed O(n) due to +its brokenness.

+

A concrete example and extreme case is the "/sys" +hierarchy under Linux where some hundred devices exist under both +"/sys/devices" and "/sys/class" with the two sub-hierarchies +linking to the other, generating millions of legal paths to enumerate. +The structure, reduced to three devices, roughly looks like

+
+	/sys/class/tty/tty0 --> ../../dev/tty0
+	/sys/class/tty/tty1 --> ../../dev/tty1
+	/sys/class/tty/tty2 --> ../../dev/tty1
+	/sys/dev/tty0/bus
+	/sys/dev/tty0/subsystem --> ../../class/tty
+	/sys/dev/tty1/bus
+	/sys/dev/tty1/subsystem --> ../../class/tty
+	/sys/dev/tty2/bus
+	/sys/dev/tty2/subsystem --> ../../class/tty
+
+

When having to handle such a pathological hierarchy it is +recommended to use the -prefilter option to prevent the +traverser from following symbolic links, like so:

+
+    package require fileutil::traverse
+    proc NoLinks {fileName} {
+        if {[string equal [file type $fileName] link]} {
+            return 0
+        }
+        return 1
+    }
+    fileutil::traverse T /sys/devices -prefilter NoLinks
+    T foreach p {
+        puts $p
+    }
+    T destroy
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/ftp/ftp.html Index: embedded/www/tcllib/files/modules/ftp/ftp.html ================================================================== --- embedded/www/tcllib/files/modules/ftp/ftp.html +++ embedded/www/tcllib/files/modules/ftp/ftp.html @@ -0,0 +1,440 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ftp(n) 2.4.13 tcllib "ftp client"

+

Name

+

ftp - Client-side tcl implementation of the ftp protocol

+
+ + +

Description

+

The ftp package provides the client side of the ftp protocol as +specified in RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). +The package implements both active (default) and passive ftp sessions.

+

A new ftp session is started with the ::ftp::Open command. To +shutdown an existing ftp session use ::ftp::Close. All other +commands are restricted to usage in an an open ftp session. They will +generate errors if they are used out of context. The ftp package +includes file and directory manipulating commands for remote sites. To +perform the same operations on the local site use commands built into +the core, like cd or file.

+

The output of the package is controlled by two state variables, +::ftp::VERBOSE and ::ftp::DEBUG. Setting +::ftp::VERBOSE to "1" forces the package to show all responses +from a remote server. The default value is "0". Setting +::ftp::DEBUG to "1" enables debugging and forces the package to +show all return codes, states, state changes and "real" ftp +commands. The default value is "0".

+

The command ::ftp::DisplayMsg is used to show the different +messages from the ftp session. The setting of ::ftp::VERBOSE +determines if this command is called or not. The current +implementation of the command uses the log package of tcllib +to write the messages to their final destination. This means that the +behaviour of ::ftp::DisplayMsg can be customized without +changing its implementation. For more radical changes overwriting its +implementation by the application is of course still possible. Note +that the default implementation honors the option -output to +::ftp::Open for a session specific log command.

+

Caution: The default implementation logs error messages like +all other messages. If this behaviour is changed to throwing an error +instead all commands in the API will change their behaviour too. In +such a case they will not return a failure code as described below but +pass the thrown error to their caller.

+
+

API

+
+
::ftp::Open server user passwd ?options?
+

This command is used to start a FTP session by establishing a control +connection to the FTP server. The defaults are used for any option not +specified by the caller.

+

The command takes a host name server, a user name user and +a password password as its parameters and returns a session +handle that is an integer number greater than or equal to "0", if the +connection is successfully established. Otherwise it returns "-1". +The server parameter must be the name or internet address (in +dotted decimal notation) of the ftp server to connect to. The +user and passwd parameters must contain a valid user name +and password to complete the login process.

+

The options overwrite some default values or set special abilities:

+
+
-blocksize size
+

The blocksize is used during data transfer. At most size bytes +are transfered at once. The default value for this option is 4096. +The package will evaluate the -progress callback for the +session after the transfer of each block.

+
-timeout seconds
+

If seconds is non-zero, then ::ftp::Open sets up a timeout +which will occur after the specified number of seconds. The default +value is 600.

+
-port number
+

The port number specifies an alternative remote port on the ftp +server on which the ftp service resides. Most ftp services listen for +connection requests on the default port 21. Sometimes, usually for +security reasons, port numbers other than 21 are used for ftp +connections.

+
-mode mode
+

The transfer mode option determines if a file transfer occurs in +active or passive mode. In passive mode the client +will ask the ftp server to listen on a data port and wait for the +connection rather than to initiate the process by itself when a data +transfer request comes in. Passive mode is normally a requirement when +accessing sites via a firewall. The default mode is active.

+
-progress callback
+

This callback is evaluated whenever a block of data was +transfered. See the option -blocksize for how to specify the +size of the transfered blocks.

+

When evaluating the callback one argument is appended to the +callback script, the current accumulated number of bytes transferred +so far.

+
-command callback
+

Specifying this option places the connection into asynchronous +mode. The callback is evaluated after the completion of any +operation. When an operation is running no further operations must be +started until a callback has been received for the currently executing +operation.

+

When evaluating the callback several arguments are appended to +the callback script, namely the keyword of the operation that has +completed and any additional arguments specific to the operation. If +an error occurred during the execution of the operation the callback is +given the keyword error.

+
-output callback
+

This option has no default. If it is set the default implementation of +::ftp::DisplayMsg will use its value as command prefix to log +all internal messages. The callback will have three arguments appended +to it before evaluation, the id of the session, the message itself, +and the connection state, in this order.

+
+
::ftp::Close handle
+

This command terminates the specified ftp session. If no file transfer +is in progress, the server will close the control connection +immediately. If a file transfer is in progress however, the control +connection will remain open until the transfers completes. When that +happens the server will write the result response for the transfer to +it and close the connection afterward.

+
::ftp::Cd handle directory
+

This command changes the current working directory on the ftp server +to a specified target directory. The command returns 1 if the +current working directory was successfully changed to the specified +directory or 0 if it fails. The target directory can be

+
    +

  • a subdirectory of the current directory,

    • +

  • Two dots, .. (as an indicator for the parent directory of +the current directory)

    • +

  • or a fully qualified path to a new working directory.

    • +
+
::ftp::Pwd handle
+

This command returns the complete path of the current working +directory on the ftp server, or an empty string in case of an error.

+
::ftp::Type handle ?ascii|binary|tenex?
+

This command sets the ftp file transfer type to either ascii, +binary, or tenex. The command always returns the +currently set type. If called without type no change is made.

+

Currently only ascii and binary types are +supported. There is some early (alpha) support for Tenex mode. The +type ascii is normally used to convert text files into a +format suitable for text editors on the platform of the destination +machine. This mainly affects end-of-line markers. The type +binary on the other hand allows the undisturbed transfer of +non-text files, such as compressed files, images and executables.

+
::ftp::List handle ?pattern?
+

This command returns a human-readable list of files. Wildcard +expressions such as "*.tcl" are allowed. If pattern +refers to a specific directory, then the contents of that directory +are returned. If the pattern is not a fully-qualified path +name, the command lists entries relative to the current remote +directory. If no pattern is specified, the contents of the +current remote directory is returned.

+

The listing includes any system-dependent information that the server +chooses to include. For example most UNIX systems produce output from +the command ls -l. The command returns the retrieved +information as a tcl list with one item per entry. Empty lines and +UNIX's "total" lines are ignored and not included in the result as +reported by this command.

+

If the command fails an empty list is returned.

+
::ftp::NList handle ?directory?
+

This command has the same behavior as the ::ftp::List command, +except that it only retrieves an abbreviated listing. This means only +file names are returned in a sorted list.

+
::ftp::FileSize handle file
+

This command returns the size of the specified file on the ftp +server. If the command fails an empty string is returned.

+

ATTENTION! It will not work properly when in ascii mode and +is not supported by all ftp server implementations.

+
::ftp::ModTime handle file
+

This command retrieves the time of the last modification of the +file on the ftp server as a system dependent integer value in +seconds or an empty string if an error occurred. Use the built-in +command clock to convert the retrieves value into other formats.

+
::ftp::Delete handle file
+

This command deletes the specified file on the ftp server. The +command returns 1 if the specified file was successfully deleted or 0 +if it failed.

+
::ftp::Rename handle from to
+

This command renames the file from in the current directory of +the ftp server to the specified new file name to. This new file +name must not be the same as any existing subdirectory or file name. +The command returns 1 if the specified file was successfully renamed +or 0 if it failed.

+
::ftp::Put handle (local | -data data | -channel chan) ?remote?
+

This command transfers a local file local to a remote file +remote on the ftp server. If the file parameters passed to the +command do not fully qualified path names the command will use the +current directory on local and remote host. If the remote file name is +unspecified, the server will use the name of the local file as the +name of the remote file. The command returns 1 to indicate a successful +transfer and 0 in the case of a failure.

+

If -data data is specified instead of a local file, the +system will not transfer a file, but the data passed into it. In +this case the name of the remote file has to be specified.

+

If -channel chan is specified instead of a local file, +the system will not transfer a file, but read the contents of the +channel chan and write this to the remote file. In this case the +name of the remote file has to be specified. After the transfer +chan will be closed.

+
::ftp::Append handle (local | -data data | -channel chan) ?remote?
+

This command behaves like ::ftp::Puts, but appends the +transfered information to the remote file. If the file did not exist +on the server it will be created.

+
::ftp::Get handle remote ?(local | -variable varname | -channel chan)?
+

This command retrieves a remote file remote on the ftp server +and stores its contents into the local file local. If the file +parameters passed to the command are not fully qualified path names +the command will use the current directory on local and remote +host. If the local file name is unspecified, the server will use the +name of the remote file as the name of the local file. The command +returns 1 to indicate a successful transfer and 0 in the case of a +failure. The command will throw an error if the directory the file +local is to be placed in does not exist.

+

If -variable varname is specified, the system will +store the retrieved data into the variable varname instead of a +file.

+

If -channel chan is specified, the system will write +the retrieved data into the channel chan instead of a file. The +system will not close chan after the transfer, this is +the responsibility of the caller to ::ftp::Get.

+
::ftp::Reget handle remote ?local? ?from? ?to?
+

This command behaves like ::ftp::Get, except that if local file +local exists and is smaller than remote file remote, the +local file is presumed to be a partially transferred copy of the +remote file and the transfer is continued from the apparent point of +failure. The command will throw an error if the directory the file +local is to be placed in does not exist. This command is useful +when transferring very large files over networks that tend to drop +connections.

+

Specifying the additional byte offsets from and to will +cause the command to change its behaviour and to download exactly the +specified slice of the remote file. This mode is possible only if a +local destination is explicitly provided. Omission of to leads +to downloading till the end of the file.

+
::ftp::Newer handle remote ?local?
+

This command behaves like ::ftp::Get, except that it retrieves +the remote file only if the modification time of the remote file is +more recent than the file on the local system. If the file does not +exist on the local system, the remote file is considered newer. The +command will throw an error if the directory the file local is +to be placed in does not exist.

+
::ftp::MkDir handle directory
+

This command creates the specified directory on the ftp +server. If the specified path is relative the new directory will be +created as a subdirectory of the current working directory. Else the +created directory will have the specified path name. The command +returns 1 to indicate a successful creation of the directory and 0 in +the case of a failure.

+
::ftp::RmDir handle directory
+

This command removes the specified directory on the ftp server. The +remote directory has to be empty or the command will fail. The command +returns 1 to indicate a successful removal of the directory and 0 in +the case of a failure.

+
::ftp::Quote handle arg1 arg2 ...
+

This command is used to send an arbitrary ftp command to the +server. It cannot be used to obtain a directory listing or for +transferring files. It is included to allow an application to execute +commands on the ftp server which are not provided by this package. +The arguments are sent verbatim, i.e. as is, with no changes.

+

In contrast to the other commands in this package this command will +not parse the response it got from the ftp server but return it +verbatim to the caller.

+
::ftp::DisplayMsg handle msg ?state?
+

This command is used by the package itself to show the different +messages from the ftp sessions. The package itself declares this +command very simple, writing the messages to stdout (if +::ftp::VERBOSE was set, see below) and throwing tcl errors for +error messages. It is the responsibility of the application to +overwrite it as needed. A state variable for different states assigned +to different colors is recommended by the author. The package +log is useful for this.

+
::ftp::VERBOSE
+

A state variable controlling the output of the package. Setting +::ftp::VERBOSE to "1" forces the package to show all responses +from a remote server. The default value is "0".

+
::ftp::DEBUG
+

A state variable controlling the output of ftp. Setting +::ftp::DEBUG to "1" enables debugging and forces the package to +show all return codes, states, state changes and "real" ftp +commands. The default value is "0".

+
+
+

BUGS

+

The correct execution of many commands depends upon the proper +behavior by the remote server, network and router configuration.

+

An update command placed in the procedure ::ftp::DisplayMsg may +run into persistent errors or infinite loops. The solution to this +problem is to use update idletasks instead of update.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ftp/ftp_geturl.html Index: embedded/www/tcllib/files/modules/ftp/ftp_geturl.html ================================================================== --- embedded/www/tcllib/files/modules/ftp/ftp_geturl.html +++ embedded/www/tcllib/files/modules/ftp/ftp_geturl.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ftp::geturl(n) 0.2.2 tcllib "ftp client"

+

Name

+

ftp::geturl - Uri handler for ftp urls

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require ftp::geturl ?0.2.2?
    • +
+ +
+
+

Description

+

This package provides a command which wraps around the client side of +the ftp protocol provided by package ftp to allow the +retrieval of urls using the ftp schema.

+
+

API

+
+
::ftp::geturl url
+

This command can be used by the generic command ::uri::geturl +(See package uri) to retrieve the contents of ftp +urls. Internally it uses the commands of the package ftp to +fulfill the request.

+

The contents of a ftp url are defined as follows:

+
+
file
+

The contents of the specified file itself.

+
directory
+

A listing of the contents of the directory in key value notation where +the file name is the key and its attributes the associated value.

+
link
+

The attributes of the link, including the path it refers to.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ftpd/ftpd.html Index: embedded/www/tcllib/files/modules/ftpd/ftpd.html ================================================================== --- embedded/www/tcllib/files/modules/ftpd/ftpd.html +++ embedded/www/tcllib/files/modules/ftpd/ftpd.html @@ -0,0 +1,338 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ftpd(n) 1.3 tcllib "Tcl FTP Server Package"

+

Name

+

ftpd - Tcl FTP server implementation

+
+ + +

Description

+

The ftpd package provides a simple Tcl-only server library +for the FTP protocol as specified in +RFC 959 (http://www.rfc-editor.org/rfc/rfc959.txt). +It works by listening on the standard FTP socket. Most server errors +are returned as error messages with the appropriate code attached to +them. Since the server code for the ftp daemon is executed in the +event loop, it is possible that a +bgerror will be thrown on the server if there are problems with +the code in the module.

+
+

COMMANDS

+
+
::ftpd::server ?myaddr?
+

Open a listening socket to listen to and accept ftp connections. +myaddr is an optional argument. myaddr is the domain-style name +or numerical IP address of the client-side network interface to use +for the connection.

+
::ftpd::config ?option value? ?option value ...?
+

The value is always the name of the command to call as the +callback. The option specifies which callback should be configured. +See section CALLBACKS for descriptions of the arguments and +return values for each of the callbacks.

+
+
-authIpCmd proc
+

Callback to authenticate new connections based on the ip-address of +the peer.

+
-authUsrCmd proc
+

Callback to authenticate new connections based on the user logging in +(and the users password).

+
-authFileCmd proc
+

Callback to accept or deny a users access to read and write to a +specific path or file.

+
-logCmd proc
+

Callback for log information generated by the FTP engine.

+
-fsCmd proc
+

Callback to connect the engine to the filesystem it operates on.

+
-closeCmd proc
+

Callback to be called when a connection is closed. This allows the +embedding application to perform its own cleanup operations.

+
-xferDoneCmd proc
+

Callback for transfer completion notification. In other words, it is +called whenever a transfer of data to or from the client has +completed.

+
+
+
+

CALLBACKS

+
+
authIpCmd callback
+

The authIpCmd receives the ip-address of the peer attempting to +connect to the ftp server as its argument. It returns a 1 to allow +users from the specified IP to attempt to login and a 0 to reject the +login attempt from the specified IP.

+
authUsrCmd callback
+

The authUsrCmd receives the username and password as its two +arguments. It returns a 1 to accept the attempted login to the ftpd +and a 0 to reject the attempted login.

+
authFileCmd callback
+

The authFileCmd receives the user (that is currently logged in), the +path or filename that is about to be read or written, and +read or write as its three arguments. It returns a +1 to allow the path or filename to be read or written, and a 0 to +reject the attempted read or write with a permissions error code.

+
logCmd callback
+

The logCmd receives a severity and a message as its two arguments. +The severities used within the ftpd package are note, +debug, and error. The logCmd doesn't return +anything.

+
fsCmd callback
+

The fsCmd receives a subcommand, a filename or path, and optional +additional arguments (depending on the subcommand).

+

The subcommands supported by the fsCmd are:

+
+
fsCmd append path
+

The append subcommand receives the filename to append to as its +argument. It returns a writable tcl channel as its return value.

+
fsCmd delete path channel
+

The delete subcommand receives the filename to delete, and a channel +to write to as its two arguments. The file specified is deleted and +the appropriate ftp message is written to the channel that is passed +as the second argument. The delete subcommand returns nothing.

+
fsCmd dlist path style channel
+

The dlist subcommand receives the path that it should list the files +that are in, the style in which the files should be listed which is +either nlst or list, and a channel to write to as +its three arguments. The files in the specified path are printed to +the specified channel one per line. If the style is nlst +only the name of the file is printed to the channel. If the style is +list then the file permissions, number of links to the file, +the name of the user that owns the file, the name of the group that +owns the file, the size (in bytes) of the file, the modify time of the +file, and the filename are printed out to the channel in a formatted +space separated format. The dlist subcommand returns +nothing.

+
fsCmd exists path
+

The exists subcommand receives the name of a file to check the +existence of as its only argument. The exists subcommand returns a 1 +if the path specified exists and the path is not a directory.

+
fsCmd mkdir path channel
+

The mkdir subcommand receives the path of a directory to create and a +channel to write to as its two arguments. The mkdir subcommand +creates the specified directory if necessary and possible. The mkdir +subcommand then prints the appropriate success or failure message to +the channel. The mkdir subcommand returns nothing.

+
fsCmd mtime path channel
+

The mtime subcommand receives the path of a file to check the modify +time on and a channel as its two arguments. If the file exists the +mtime is printed to the channel in the proper FTP format, otherwise an +appropriate error message and code are printed to the channel. The +mtime subcommand returns nothing.

+
fsCmd permissions path
+

The permissions subcommand receives the path of a file to retrieve the +permissions of. The permissions subcommand returns the octal file +permissions of the specified file. The file is expected to exist.

+
fsCmd rename path newpath channel
+

The rename subcommand receives the path of the current file, the new +file path, and a channel to write to as its three arguments. The +rename subcommand renames the current file to the new file path if the +path to the new file exists, and then prints out the appropriate +message to the channel. If the new file path doesn't exist the +appropriate error message is printed to the channel. The rename +subcommand returns nothing.

+
fsCmd retr path
+

The retr subcommand receives the path of a file to read as its only +argument. The retr subcommand returns a readable channel that the +specified file can be read from.

+
fsCmd rmdir path channel
+

The rmdir subcommand receives the path of a directory to remove and a +channel to write to as its two arguments. The rmdir subcommand +removes the specified directory (if possible) and prints the +appropriate message to the channel (which may be an error if the +specified directory does not exist or is not empty). The rmdir +subcommand returns nothing.

+
fsCmd size path channel
+

The size subcommand receives the path of a file to get the size (in +bytes) of and a channel to write to as its two arguments. The size +subcommand prints the appropriate code and the size of the file if the +specified path is a file, otherwise an appropriate error code and +message are printed to the channel. The size subcommand returns +nothing.

+
fsCmd store path
+

The store subcommand receives the path of a file to write as its only +argument. The store subcommand returns a writable channel.

+
+
closeCmd
+

The closeCmd receives no arguments when it is invoked, and any +return value it may generate is discarded.

+
xferDoneCmd sock sock2 file bytes filename err
+

The xferDoneCmd receives six arguments when invoked. These are, +in this order, the channel handle of the control socket for the +connection, the channel handle of the data socket used for the +transfer (already closed), the handle of the channel containing the +transfered file, the number of bytes transfered, the path of the file +which was transfered, and a (possibly empty) error message. +Any return value it may generate is discarded.

+
+
+

VARIABLES

+
+
::ftpd::cwd
+

The current working directory for a session when someone first +connects to the FTPD or when the REIN ftp command is received.

+
::ftpd::contact
+

The e-mail address of the person that is the contact for the ftp +server. This address is printed out as part of the response to the +FTP HELP command.

+
::ftpd::port
+

The port that the ftp server should listen on. +If port is specified as zero, the operating system will allocate an +unused port for use as a server socket; afterwards, the variable will +contain the port number that was allocated.

+
::ftpd::welcome
+

The message that is printed out when the user first connects to the +ftp server.

+
::ftpd::CurrentSocket
+

Accessible to all callbacks and all filesystem commands (which are a +special form of callback) and contains the handle of the socket +channel which was active when the callback was invoked.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ftpd of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/cfront.html Index: embedded/www/tcllib/files/modules/fumagic/cfront.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/cfront.html +++ embedded/www/tcllib/files/modules/fumagic/cfront.html @@ -0,0 +1,182 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::magic::cfront(n) 1.2.0 tcllib "file utilities"

+

Name

+

fileutil::magic::cfront - Generator core for compiler of magic(5) files

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require fileutil::magic::cfront ?1.2.0?
    • +
  • package require fileutil::magic::cgen ?1.2.0?
    • +
  • package require fileutil::magic::rt ?1.2.0?
    • +
  • package require struct::list
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides the frontend of a compiler of magic(5) files +into recognizers based on the fileutil::magic::rt recognizer +runtime package. For the generator backed used by this compiler see +the package fileutil::magic::cgen.

+
+

COMMANDS

+
+
::fileutil::magic::cfront::compile path...
+

This command takes the paths of one or more files and directories and +compiles all the files, and the files in all the directories into a +single recognizer for all the file types specified in these files.

+

All the files have to be in the format specified by magic(5).

+

The result of the command is a Tcl script containing the generated +recognizer.

+
::fileutil::magic::cfront::procdef procname path...
+

This command behaves like ::fileutil::magic::cfront::compile +with regard to the specified path arguments, then wraps the resulting +recognizer script into a procedure named procname, puts code +setting up the namespace of procname in front, and returns the +resulting script.

+
::fileutil::magic::cfront::install path...
+

This command uses ::fileutil::magic::cfront::procdef to compile +each of the paths into a recognizer procedure and installs the result +in the current interpreter.

+

The name of each new procedure is derived from the name of the +file/directory used in its creation, with file/directory "FOO" +causing the creation of procedure ::fileutil::magic::/FOO::run.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/cgen.html Index: embedded/www/tcllib/files/modules/fumagic/cgen.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/cgen.html +++ embedded/www/tcllib/files/modules/fumagic/cgen.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::magic::cgen(n) 1.2.0 tcllib "file utilities"

+

Name

+

fileutil::magic::cgen - Generator core for compiler of magic(5) files

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require fileutil::magic::cgen ?1.2.0?
    • +
  • package require fileutil::magic::rt ?1.2.0?
    • +
  • package require struct::tree
    • +
  • package require struct::list
    • +
+ +
+
+

Description

+

This package provides the generator backend for a compiler of magic(5) +files into recognizers based on the fileutil::magic::rt +recognizer runtime package. For the compiler frontend using this +generator see the package fileutil::magic::cfront.

+
+

COMMANDS

+
+
::fileutil::magic::cgen::2tree script
+

This command converts the recognizer specified by the script +into a tree and returns the object command of that tree as its +result. It uses the package struct::tree for the tree.

+

The script is in the format specified by magic(5).

+
::fileutil::magic::cgen::treedump tree
+

This command takes a tree as generated by +::fileutil::magic::cgen::2tree and returns a string encoding the +tree for human consumption, to aid in debugging.

+
::fileutil::magic::cgen::treegen tree node
+

This command takes a tree as generated by +::fileutil::magic::cgen::2tree and returns a Tcl script, the +recognizer for the file types represented by the sub-tree rooted at +the node. +The generated script makes extensive use of the commands provided by +the recognizer runtime package fileutil::magic::rt to +perform its duties.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/filetypes.html Index: embedded/www/tcllib/files/modules/fumagic/filetypes.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/filetypes.html +++ embedded/www/tcllib/files/modules/fumagic/filetypes.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::magic::filetype(n) 1.2.0 tcllib "file utilities"

+

Name

+

fileutil::magic::filetype - Procedures implementing file-type recognition

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require fileutil::magic::filetype ?1.2.0?
    • +
+ +
+
+

Description

+

This package provides a command for the recognition of file types in +pure Tcl.

+

The core part of the recognizer was generated from a "magic(5)" file +containing the checks to perform to recognize files, and associated +file-types.

+

Beware! This recognizer is large, about 752 Kilobyte of +generated Tcl code.

+
+
::fileutil::magic::filetype filename
+

This command is similar to the command fileutil::fileType.

+

Returns a list containing a list of descriptions, a list of mimetype +components, and a list file extensions. Returns an empty string if the file +content is not recognized.

+
+
+

REFERENCES

+
    +

  1. File(1) sources +This site contains the current sources for the file command, including +the magic definitions used by it. The latter were used by us to +generate this recognizer.

    2. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/fumagic/rtcore.html Index: embedded/www/tcllib/files/modules/fumagic/rtcore.html ================================================================== --- embedded/www/tcllib/files/modules/fumagic/rtcore.html +++ embedded/www/tcllib/files/modules/fumagic/rtcore.html @@ -0,0 +1,327 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

fileutil::magic::rt(n) 1.2.0 tcllib "file utilities"

+

Name

+

fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl

+
+ + +

Description

+

This package provides the runtime core for file type recognition +engines written in pure Tcl and is thus used by all other packages in +this module, i.e. the two frontend packages +fileutil::magic::mimetypes and +fileutil::magic::filetypes, and the two engine compiler +packages fileutil::magic::cgen and +fileutil::magic::cfront.

+
+

COMMANDS

+
+
::fileutil::magic::rt::>
+

Shorthand for incr level.

+
::fileutil::magic::rt::<
+

Shorthand for incr level -1.

+
::fileutil::magic::rt::open filename
+

This command initializes the runtime and prepares the file +filename for use by the system. +This command has to be invoked first, before any other command of this +package.

+

The command returns the channel handle of the opened file as its +result.

+
::fileutil::magic::rt::close
+

This command closes the last file opened via +::fileutil::magic::rt::open and shuts the runtime down. +This command has to be invoked last, after the file has been dealt +with completely. +Afterward another invokation of ::fileutil::magic::rt::open is +required to process another file.

+

This command returns the empty string as its result.

+
::fileutil::magic::rt::file_start name
+

This command marks the start of a magic file when debugging. It +returns the empty string as its result.

+
::fileutil::magic::rt::result ?msg?
+

This command returns the current result and stops processing.

+

If msg is specified its text is added to the result before it is +returned. See ::fileutil::magic::rt::emit for the allowed +special character sequences.

+
::fileutil::magic::rt::resultv ?msg?
+

This command returns the current result. +In contrast to ::fileutil::magic::rt::result processing +continues.

+

If msg is specified its text is added to the result before it is +returned. See ::fileutil::magic::rt::emit for the allowed +special character sequences.

+
::fileutil::magic::rt::emit msg
+

This command adds the text msg to the result buffer. The +message may contain the following special character sequences. They +will be replaced with buffered values before the message is added to +the result. The command returns the empty string as its result.

+
+
\b
+

This sequence is removed

+
%s
+

Replaced with the last buffered string value.

+
%ld
+

Replaced with the last buffered numeric value.

+
%d
+

See above.

+
+
::fileutil::magic::rt::Nv type offset ?qual?
+

This command fetches the numeric value with type from the +absolute location offset and returns it as its result. The +fetched value is further stored in the numeric buffer.

+

If qual is specified it is considered to be a mask and applied +to the fetched value before it is stored and returned. It has to have +the form of a partial Tcl bit-wise expression, i.e.

+
+	& number
+
+

For example:

+
+	Nv lelong 0 &0x8080ffff
+
+

For the possible types see section NUMERIC TYPES.

+
::fileutil::magic::rt::N type offset comp val ?qual?
+

This command behaves mostly like ::fileutil::magic::rt::Nv, +except that it compares the fetched and masked value against val +as specified with comp and returns the result of that +comparison.

+

The argument comp has to contain one of Tcl's comparison +operators, and the comparison made will be

+
+	<val> <comp> <fetched-and-masked-value>
+
+

The special comparison operator x signals that no comparison +should be done, or, in other words, that the fetched value will always +match val.

+
::fileutil::magic::rt::Nvx type offset ?qual?
+

This command behaves like ::fileutil::magic::rt::Nv, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the current level, for later use by +::fileutil::magic::rt::R.

+
::fileutil::magic::rt::Nx type offset comp val ?qual?
+

This command behaves like ::fileutil::magic::rt::N, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the current, for later use by +::fileutil::magic::rt::R.

+
::fileutil::magic::rt::S offset comp val ?qual?
+

This command behaves like ::fileutil::magic::rt::N, except that +it fetches and compares strings, not numeric data. The fetched value +is also stored in the internal string buffer instead of the numeric +buffer.

+
::fileutil::magic::rt::Sx offset comp val ?qual?
+

This command behaves like ::fileutil::magic::rt::S, except that +it additionally remembers the location in the file after the fetch in +the calling context, for the current level, for later use by +::fileutil::magic::rt::R.

+
::fileutil::magic::rt::L newlevel
+

This command sets the current level in the calling context to +newlevel. The command returns the empty string as its result.

+
::fileutil::magic::rt::I base type delta
+

This command handles base locations specified indirectly through the +contents of the inspected file. It returns the sum of delta and +the value of numeric type fetched from the absolute location +base.

+

For the possible types see section NUMERIC TYPES.

+
::fileutil::magic::rt::R offset
+

This command handles base locations specified relative to the end of +the last field one level above.

+

In other words, the command computes an absolute location in the file +based on the relative offset and returns it as its result. The +base the offset is added to is the last location remembered for the +level in the calling context.

+
::fileutil::magic::rt::U fileindex name
+

Use a named test script at the current level.

+
+
+

NUMERIC TYPES

+
+
byte
+

8-bit integer

+
short
+

16-bit integer, stored in native endianess

+
beshort
+

see above, stored in big endian

+
leshort
+

see above, stored in small/little endian

+
long
+

32-bit integer, stored in native endianess

+
belong
+

see above, stored in big endian

+
lelong
+

see above, stored in small/little endian

+
+

All of the types above exit in an unsigned form as well. The type +names are the same, with the character "u" added as prefix.

+
+
date
+

32-bit integer timestamp, stored in native endianess

+
bedate
+

see above, stored in big endian

+
ledate
+

see above, stored in small/little endian

+
ldate
+

32-bit integer timestamp, stored in native endianess

+
beldate
+

see above, stored in big endian

+
leldate
+

see above, stored in small/little endian

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category fileutil :: magic of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

file(1), fileutil, magic(5)

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/generator/generator.html Index: embedded/www/tcllib/files/modules/generator/generator.html ================================================================== --- embedded/www/tcllib/files/modules/generator/generator.html +++ embedded/www/tcllib/files/modules/generator/generator.html @@ -0,0 +1,506 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

generator(n) 0.1 tcllib "Tcl Generator Commands"

+

Name

+

generator - Procedures for creating and using generators.

+
+ + +

Description

+

The generator package provides commands to define and iterate over +generator expressions. A generator is a command that returns a sequence +of values. However, unlike an ordinary command that returns a list, a +generator yields each value and then suspends, allowing subsequent +values to be fetched on-demand. As such, generators can be used to efficiently +iterate over a set of values, without having to generate all answers in-memory. +Generators can be used to iterate over elements of a data structure, or rows +in the result set of a database query, or to decouple producer/consumer software +designs such as parsers and tokenizers, or to implement sophisticated custom +control strategies such as backtracking search. Generators reduce the need to +implement custom control structures, as many such structures can be recast as +generators, leading to both a simpler implementation and a more standardised +interface. The generator mechanism is built on top of the Tcl 8.6 coroutine +mechanism.

+

The package exports a single ensemble command, generator. All +functionality is provided as subcommands of this command. The core subcommands +of the package are define, yield, and foreach. The +define command works like Tcl's proc command, but creates a +generator procedure; that is, a procedure that returns a generator when called. +The generator itself is a command that can be called multiple times: each time +it returns the next value in the generated series. When the +series has been exhausted, the generator command returns an empty list and then +destroys itself. Rather than manually call a generator, however, the package +also provides a flexible foreach command that loops through the values of +one or more generators. This loop construct mimicks the functionality of the +built-in Tcl foreach command, including handling multiple return values +and looping over multiple generators at once. Writing a generator is also a +simple task, much like writing a normal procedure: simply use the define +command to define the generator, and then call yield instead of return. +For example, we can define a generator for looping through the integers +in a particular range:

+
+    generator define range {n m} {
+        for {set i $n} {$i <= $m} {incr i} { generator yield $i }
+    }
+    generator foreach x [range 1 10] {
+        puts "x = $x"
+    }
+
+

The above example will print the numbers from 1 to 10 in sequence, as you would +expect. The difference from a normal loop over a list is that the numbers are +only generated as they are needed. If we insert a break into the loop then any +remaining numbers in the sequence would never be generated. To illustrate, we +can define a generator that produces the sequence of natural numbers: an +infinite series. A normal procedure would never return trying to produce this +series as a list. By using a generator we only have to generate those values +which are actually used:

+
+    generator define nats {} {
+        while 1 { generator yield [incr nat] }
+    }
+    generator foreach n [nats] {
+        if {$n > 100} { break }
+    }
+
+
+

COMMANDS

+
+
generator define name params body
+

Creates a new generator procedure. The arguments to the command are identical to +those for proc: a name, a list of parameters, and a body. The +parameter list format is identical to a procedure. In particular, default values +and the ?args? syntax can be used as usual. Each time the resulting +generator procedure is called it creates a new generator command (coroutine) +that will yield a list of values on each call. Each result from a generator is +guaranteed to be a non-empty list of values. When a generator is exhausted it +returns an empty list and then destroys itself to free up resources. It is an +error to attempt to call an exhausted generator as the command no longer exists.

+
generator yield arg ?args..?
+

Used in the definition of a generator, this command returns the next set of +values to the consumer. Once the yield command has been called the +generator will suspend to allow the consumer to process that value. When the +next value is requested, the generator will resume as if the yield command had +just returned, and can continue processing to yield the next result. The +yield command must be called with at least one argument, but can be called with +multiple arguments, in which case this is equivalent to calling yield +once for each argument.

+
generator foreach varList generator varList generator ?...? body
+

Loops through one or more generators, assigning the next values to variables and +then executing the loop body. Works much like the built-in foreach +command, but working with generators rather than lists. Multiple generators can +be iterated over in parallel, and multiple results can be retrieved from a +single generator at once. Like the built-in foreach, the loop will +continue until all of the generators have been exhausted: variables for +generators that are exhausted early will be set to the empty string.

+

The foreach command will automatically clean-up all of the generators +at the end of the loop, regardless of whether the loop terminated early or not. +This behaviour is provided as a convenience to avoid having to explicitly +clean up a generator in the usual cases. Generators can however be destroyed +before the end of the loop, in which case the loop will continue as normal until +all the other generators have been destroyed or exhausted.

+

The foreach command does not take a snapshot of the generator. Any +changes in the state of the generator made inside the loop or by other code will +affect the state of the loop. In particular, if the code in the loop invokes the +generator to manually retrieve the next element, this element will then be +excluded from the loop, and the next iteration will continue from the element +after that one. Care should be taken to avoid concurrent updates to generators +unless this behaviour is required (e.g., in argument processing).

+
generator next generator ?varName..?
+

Manually retrieves the next values from a generator. One value is retrieved for +each variable supplied and assigned to the corresponding variable. If the +generator becomes exhausted at any time then any remaining variables are set to +the empty string.

+
generator exists generator
+

Returns 1 if the generator (still) exists, or 0 otherwise.

+
generator names
+

Returns a list of all currently existing generator commands.

+
generator destroy ?generator..?
+

Destroys one or more generators, freeing any associated resources.

+
generator finally cmd ?arg..?
+

Used in the definition of a generator procedure, this command arranges for a +resource to be cleaned up whenever the generator is destroyed, either explicitly +or implicitly when the generator is exhausted. This command can be used like a +finally block in the try command, except that it is tied to the +life-cycle of the generator rather than to a particular scope. For example, if +we create a generator to iterate over the lines in a text file, we can use +finally to ensure that the file is closed whenever the generator is +destroyed:

+
+    generator define lines file {
+        set in [open $file]
+        # Ensure file is always closed
+        generator finally close $in
+        while {[gets $in line] >= 0} {
+            generator yield $line
+        }
+    }
+    generator foreach line [lines /etc/passwd] {
+        puts "[incr count]: $line"
+        if {$count > 10} { break }
+    }
+    # File will be closed even on early exit
+
+

If you create a generator that consumes another generator (such as the standard +map and filter generators defined later), then you should use +a finally command to ensure that this generator is destroyed when its +parent is. For example, the map generator is defined as follows:

+
+    generator define map {f xs} {
+        generator finally generator destroy $xs
+        generator foreach x $xs { generator yield [{*}$f $x] }
+    }
+
+
+
generator from format value
+

Creates a generator from a data structure. Currently, supported formats are +list, dict, or string. The list format yields each +element in turn. For dictionaries, each key and value are yielded separately. +Finally, strings are yielded a character at a time.

+
generator to format generator
+

Converts a generator into a data structure. This is the reverse operation of the +from command, and supports the same data structures. The two operations +obey the following identity laws (where = is interpreted +appropriately):

+
+    [generator to $fmt [generator from $fmt $value]] = $value
+    [generator from $fmt [generator to $fmt $gen]]   = $gen
+
+
+
+
+

PRELUDE

+

The following commands are provided as a standard library of generator +combinators and functions that perform convenience operations on generators. The +functions in this section are loosely modelled on the equivalent functions from +the Haskell Prelude. Warning: most of the functions in this prelude +destroy any generator arguments they are passed as a side-effect. If you want to +have persistent generators, see the streams library.

+
+
generator map function generator
+

Apply a function to every element of a generator, returning a new generator of +the results. This is the classic map function from functional programming, +applied to generators. For example, we can generate all the square numbers using +the following code (where nats is defined as earlier):

+
+    proc square x { expr {$x * $x} }
+    generator foreach n [generator map square [nats]] {
+        puts "n = $n"
+        if {$n > 1000} { break }
+    }
+
+
+
generator filter predicate generator
+

Another classic functional programming gem. This command returns a generator +that yields only those items from the argument generator that satisfy the +predicate (boolean function). For example, if we had a generator employees +that returned a stream of dictionaries representing people, we could filter all +those whose salaries are above 100,000 dollars (or whichever currency you prefer) +using a simple filter:

+
+    proc salary> {amount person} { expr {[dict get $person salary] > $amount} }
+    set fat-cats [generator filter {salary> 100000} $employees]
+
+
+
generator reduce function zero generator
+

This is the classic left-fold operation. This command takes a function, an +initial value, and a generator of values. For each element in the generator it +applies the function to the current accumulator value (the zero argument +initially) and that element, and then uses the result as the new accumulator +value. This process is repeated through the entire generator (eagerly) and the +final accumulator value is then returned. If we consider the function to be a +binary operator, and the zero argument to be the left identity element of that +operation, then we can consider the reduce command as folding +the operator between each successive pair of values in the generator in a +left-associative fashion. For example, the sum of a sequence of numbers can be +calculated by folding a + operator between them, with 0 as the identity:

+
+    # sum xs          = reduce + 0 xs
+    # sum [range 1 5] = reduce + 0 [range 1 5]
+    #                 = reduce + [+ 0 1] [range 2 5]
+    #                 = reduce + [+ 1 2] [range 3 5]
+    #                 = ...
+    #                 = reduce + [+ 10 5] <empty>
+    #                 = ((((0+1)+2)+3)+4)+5
+    #                 = 15
+    proc + {a b} { expr {$a + $b} }
+    proc sum gen { generator reduce + 0 $gen }
+    puts [sum [range 1 10]]
+
+

The reduce operation is an extremely useful one, and a great variety of +different operations can be defined using it. For example, we can define a +factorial function as the product of a range using generators. This definition +is both very clear and also quite efficient (in both memory and running time):

+
+    proc * {x y} { expr {$x * $y} }
+    proc prod gen { generator reduce * 0 $gen }
+    proc fac n { prod [range 1 $n] }
+
+

However, while the reduce operation is efficient for finite generators, +care should be taken not to apply it to an infinite generator, as this will +result in an infinite loop:

+
+    sum [nats]; # Never returns
+
+
+
generator foldl function zero generator
+

This is an alias for the reduce command.

+
generator foldr function zero generator
+

This is the right-associative version of reduce. This operation is +generally inefficient, as the entire generator needs to be evaluated into memory +(as a list) before the reduction can commence. In an eagerly evaluated language +like Tcl, this operation has limited use, and should be avoided if possible.

+
generator all predicate generator
+

Returns true if all elements of the generator satisfy the given predicate.

+
generator and generator
+

Returns true if all elements of the generator are true (i.e., takes the logical +conjunction of the elements).

+
generator any generator
+

Returns true if any of the elements of the generator are true (i.e., logical +disjunction).

+
generator concat generator ?generator..?
+

Returns a generator which is the concatenation of each of the argument +generators.

+
generator concatMap function generator
+

Given a function which maps a value to a series of values, and a generator of +values of that type, returns a generator of all of the results in one flat +series. Equivalent to concat applied to the result of map.

+
generator drop n generator
+

Removes the given number of elements from the front of the generator and returns +the resulting generator with those elements removed.

+
generator dropWhile predicate generator
+

Removes all elements from the front of the generator that satisfy the predicate.

+
generator contains element generator
+

Returns true if the generator contains the given element. Note that this will +destroy the generator!

+
generator foldl1 function generator
+

A version of foldl that takes the zero argument from the first +element of the generator. Therefore this function is only valid on non-empty +generators.

+
generator foldli function zero generator
+

A version of foldl that supplies the integer index of each element as +the first argument to the function. The first element in the generator at this +point is given index 0.

+
generator foldri function zero generator
+

Right-associative version of foldli.

+
generator head generator
+

Returns the first element of the generator.

+
generator tail generator
+

Removes the first element of the generator, returning the rest.

+
generator init generator
+

Returns a new generator consisting of all elements except the last of the +argument generator.

+
generator takeList n generator
+

Returns the next n elements of the generator as a list. If not enough +elements are left in the generator, then just the remaining elements are +returned.

+
generator take n generator
+

Returns the next n elements of the generator as a new generator. The old +generator is destroyed.

+
generator iterate function init
+

Returns an infinite generator formed by repeatedly applying the function to the +initial argument. For example, the Fibonacci numbers can be defined as follows:

+
+    proc fst pair { lindex $pair 0 }
+    proc snd pair { lindex $pair 1 }
+    proc nextFib ab { list [snd $ab] [expr {[fst $ab] + [snd $ab]}] }
+    proc fibs {} { generator map fst [generator iterate nextFib {0 1}] }
+
+
+
generator last generator
+

Returns the last element of the generator (if it exists).

+
generator length generator
+

Returns the length of the generator, destroying it in the process.

+
generator or predicate generator
+

Returns 1 if any of the elements of the generator satisfy the predicate.

+
generator product generator
+

Returns the product of the numbers in a generator.

+
generator repeat n value..
+

Returns a generator that consists of n copies of the given elements. The +special value Inf can be used to generate an infinite sequence.

+
generator sum generator
+

Returns the sum of the values in the generator.

+
generator takeWhile predicate generator
+

Returns a generator of the first elements in the argument generator that satisfy +the predicate.

+
generator splitWhen predicate generator
+

Splits the generator into lists of elements using the predicate to identify +delimiters. The resulting lists are returned as a generator. Elements matching +the delimiter predicate are discarded. For example, to split up a generator +using the string "|" as a delimiter:

+
+    set xs [generator from list {a | b | c}]
+    generator split {string equal "|"} $xs ;# returns a then b then c
+
+
+
generator scanl function zero generator
+

Similar to foldl, but returns a generator of all of the intermediate +values for the accumulator argument. The final element of this generator is +equivalent to foldl called on the same arguments.

+
+
+

BUGS, IDEAS, FEEDBACK

+

Please report any errors in this document, or in the package it describes, to +Neil Madden.

+
+ +
ADDED embedded/www/tcllib/files/modules/gpx/gpx.html Index: embedded/www/tcllib/files/modules/gpx/gpx.html ================================================================== --- embedded/www/tcllib/files/modules/gpx/gpx.html +++ embedded/www/tcllib/files/modules/gpx/gpx.html @@ -0,0 +1,265 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)"

+

Name

+

gpx - Extracts waypoints, tracks and routes from GPX files

+
+ + +

Description

+

This module parses and extracts waypoints, tracks, routes and +metadata from a GPX (GPS eXchange) file. Both GPX version 1.0 +and 1.1 are supported.

+
+

COMMANDS

+
+
::gpx::Create gpxFilename ?rawXML?
+

The ::gpx::Create is the first command called to process GPX +data. It takes the GPX data from either the rawXML +parameter if present or from the contents of gpxFilename, +and parses it using tdom. It returns a token value that is used +by all the other commands.

+
::gpx::Cleanup token
+

This procedure cleans up resources associated with token. +It is strongly recommended that you call this +function after you are done with a given GPX file. +Not doing so will result in memory not being freed, and +if your app calls ::gpx::Create enough times, the +memory leak could cause a performance hit...or worse.

+
::gpx::GetGPXMetadata token
+

This procedure returns a dictionary of the metadata +associated with the GPX data identified by token. +The format of the metadata dictionary is described +below, but keys version and creator +will always be present.

+
::gpx::GetWaypointCount token
+

This procedure returns the number of waypoints defined in the GPX +data identified by token.

+
::gpx::GetAllWaypoints token
+

This procedure returns the a list of waypoints defined in the GPX +data identified by token. The format of each waypoint item +is described below.

+
::gpx::GetTrackCount token
+

This procedure returns the number of tracks defined in the GPX +data identified by token.

+
::gpx::GetTrackMetadata token whichTrack
+

This procedure returns a dictionary of the metadata +associated track number whichTrack (1 based) in +the GPX data identified by token. +The format of the metadata dictionary is described below.

+
::gpx::GetTrackPoints token whichTrack
+

The procedure returns a list of track points comprising track +number whichTrack (1 based) in the GPX data identified by +token. The format of the metadata dictionary is described below.

+
::gpx::GetRouteCount token
+

This procedure returns the number of routes defined in the GPX +data identified by token.

+
::gpx::GetRouteMetadata token whichRoute
+

This procedure returns a dictionary of the metadata +associated route number whichRoute (1 based) in +the GPX data identified by token. +The format of the metadata dictionary is described below.

+
::gpx::GetRoutePoints token whichRoute
+

The procedure returns a list of route points comprising route +number whichRoute (1 based) in the GPX data identified by +token. The format of the metadata dictionary is described below.

+
+
+

DATA STRUCTURES

+
+
metadata dictionary
+

The metadata associated with either the GPX document, a +track, a route, a waypoint, a track point or route +point is returned in a dictionary. The keys of that +dictionary will be whatever optional GPX elements are +present. The value for each key depends on the GPX schema +for that element. For example, the value for a version +key will be a string, while for a link key will be +a sub-dictionary with keys href and optionally +text and type.

+
point item
+

Each item in a track or route list of points consists of +a list of three elements: latitude, longitude and +metadata dictionary. Latitude and longitude +are decimal numbers. The metadata dictionary format is +described above. For points in a track, typically there will +always be ele (elevation) and time metadata keys.

+
+
+

EXAMPLE

+
+% set token [::gpx::Create myGpxFile.gpx]
+% set version [dict get [::gpx::GetGPXMetadata $token] version]
+% set trackCnt [::gpx::GetTrackCount $token]
+% set firstPoint [lindex [::gpx::GetTrackPoints $token 1] 0]
+% lassign $firstPoint lat lon ptMetadata
+% puts "first point in the first track is at $lat, $lon"
+% if {[dict exists $ptMetadata ele]} {
+     puts "at elevation [dict get $ptMetadata ele] meters"
+  }
+% ::gpx::Cleanup $token
+
+
+

REFERENCES

+
    +

  1. GPX: the GPS Exchange Format + (http://www.topografix.com/gpx.asp)

    2. +

  2. GPX 1.1 Schema Documentation (http://www.topografix.com/GPX/1/1/)

    3. +

  3. GPX 1.0 Developer's Manual (http://www.topografix.com/gpx_manual.asp)

    4. +
+
+

AUTHOR

+

Keith Vetter

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category gpx of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_aycock/aycock.html Index: embedded/www/tcllib/files/modules/grammar_aycock/aycock.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_aycock/aycock.html +++ embedded/www/tcllib/files/modules/grammar_aycock/aycock.html @@ -0,0 +1,240 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl"

+

Name

+

grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl

+
+ + +

Description

+

The grammar::aycock package +implements a parser generator for the class of parsers described +in John Aycock and R. Nigel Horspool. Practical Earley Parsing. +The Computer Journal, 45(6):620-630, 2002. +http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.12.4254

+
+

PROCEDURES

+

The grammar::aycock package exports the single procedure:

+
+
::aycock::parser grammar ?-verbose?
+

Generates a parser for the given grammar, and returns its +name. If the optional -verbose flag is given, dumps verbose +information relating to the generated parser to the standard output. +The returned parser is an object that accepts commands as shown in +OBJECT COMMAND below.

+
+
+

OBJECT COMMAND

+
+
parserName parse symList valList ?clientData?
+

Invokes a parser returned from ::aycock::parser. symList is +a list of grammar symbols representing the terminals in an input +string, and valList is a list of their semantic values. The +result is the semantic value of the entire string when parsed.

+
parserName destroy
+

Destroys a parser constructed by ::aycock::parser.

+
parserName terminals
+

Returns a list of terminal symbols that may be presented in the +symList argument to the parse object command.

+
parserName nonterminals
+

Returns a list of nonterminal symbols that were defined in the +parser's grammar.

+
parserName save
+

Returns a Tcl script that will reconstruct the parser without +needing all the mechanism of the parser generator at run time. +The reconstructed parser depends on a set of commands in the +package grammar::aycock::runtime, +which is also automatically loaded +when the grammar::aycock package is loaded.

+
+
+

DESCRIPTION

+

The grammar::aycock::parser command accepts a grammar expressed as +a Tcl list. The list must be structured as the concatenation of a set +of rules. Each rule comprises a variable number of +elements in the list:

+
    +

  • The name of the nonterminal symbol that the rule reduces.

    • +

  • The literal string, ::=

    • +

  • Zero or more names of terminal or nonterminal symbols that +comprise the right-hand-side of the rule.

    • +

  • Finally, a Tcl script to execute when the rule is reduced. +Within the given script, a variable called _ contains a list of +the semantic values of the symbols on the right-hand side. The value +returned by the script is expected to be the semantic value of the +left-hand side. If the clientData parameter was passed to the +parse method, it is available in a variable called +clientData. It is permissible for the script to be the empty +string. In this case, the semantic value of the rule will be the same +as the semantic value of the first symbol on the right-hand side. If +the right-hand side is also empty, the semantic value will be the +empty string.

    • +
+

Parsing is done with an Earley parser, which is not terribly efficient +in speed or memory consumption, but which deals effectively with +ambiguous grammars. For this reason, the grammar::aycock package is +perhaps best adapted to natural-language processing or the parsing of +extraordinarily complex languages in which ambiguity can be tolerated.

+
+

EXAMPLE

+

The following code demonstrates a trivial desk calculator, admitting +only +, * and parentheses as its operators. It also +shows the format in which the lexical analyzer is expected to present +terminal symbols to the parser.

+
+set p [aycock::parser {
+    start ::= E {}
+    E ::= E + T {expr {[lindex $_ 0] + [lindex $_ 2]}}
+    E ::= T {}
+    T ::= T * F {expr {[lindex $_ 0] * [lindex $_ 2]}}
+    T ::= F {}
+    F ::= NUMBER {}
+    F ::= ( E ) {lindex $_ 1}
+}]
+puts [$p parse {(  NUMBER +  NUMBER )  *  ( NUMBER +  NUMBER ) }  {{} 2      {} 3      {} {} {} 7     {} 1      {}}]
+$p destroy
+
+

The example, when run, prints 40.

+
+

KEYWORDS

+

Aycock, Earley, Horspool, parser, compiler

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html Index: embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html +++ embedded/www/tcllib/files/modules/grammar_fa/dacceptor.html @@ -0,0 +1,202 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::dacceptor - Create and use deterministic acceptors

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit
    • +
  • package require struct::set
    • +
  • package require grammar::fa::dacceptor ?0.1.1?
    • +
+ +
+
+

Description

+

This package provides a class for acceptors constructed from +deterministic finite automatons (DFA). Acceptors are objects +which can be given a string of symbols and tell if the DFA they are +constructed from would accept that string. +For the actual creation of the DFAs the acceptors are based on we have +the packages grammar::fa and grammar::fa::op.

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa::dacceptor daName fa ?-any any?
+

Creates a new deterministic acceptor with an associated global Tcl command +whose name is daName. This command may be used to invoke various +operations on the acceptor. It has the following general form:

+
+
daName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section ACCEPTOR METHODS for more explanations.

+

The acceptor will be based on the deterministic finite automaton +stored in the object fa. It will keep a copy of the relevant +data of the FA in its own storage, in a form easy to use for its +purposes. This also means that changes made to the fa after the +construction of the acceptor will not influence the acceptor.

+

If any has been specified, then the acceptor will convert all +symbols in the input which are unknown to the base FA to that symbol +before proceeding with the processing.

+
+
+
+

ACCEPTOR METHODS

+

All acceptors provide the following methods for their manipulation:

+
+
daName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
daName accept? symbols
+

Takes the list of symbols and checks if the FA the acceptor is +based on would accept it. The result is a boolean value. True +is returned if the symbols are accepted, and False +otherwise. Note that bogus symbols in the input are either translated +to the any symbol (if specified), or cause the acceptance test +to simply fail. No errors will be thrown. The method will process only +just that prefix of the input which is enough to fully determine +(non-)acceptance.

+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/dexec.html Index: embedded/www/tcllib/files/modules/grammar_fa/dexec.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/dexec.html +++ embedded/www/tcllib/files/modules/grammar_fa/dexec.html @@ -0,0 +1,259 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::dexec - Execute deterministic finite automatons

+
+ + +

Description

+

This package provides a class for executors constructed from +deterministic finite automatons (DFA). Executors are objects +which are given a string of symbols in a piecemal fashion, perform +state transitions and report back when they enter a final state, or +find an error in the input. +For the actual creation of the DFAs the executors are based on we have +the packages grammar::fa and grammar::fa::op.

+

The objects follow a push model. Symbols are pushed into the executor, +and when something important happens, i.e. error occurs, a state transition, +or a final state is entered this will be reported via the callback +specified via the option -command. Note that conversion of +this into a pull model where the environment retrieves messages from +the object and the object uses a callback to ask for more symbols is +a trivial thing.

+

Side note: +The acceptor objects provided by grammar::fa::dacceptor +could have been implemented on top of the executors provided here, but +were not, to get a bit more performance (we avoid a number of method +calls and the time required for their dispatch).

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?
+

Creates a new deterministic executor with an associated global Tcl +command whose name is daName. This command may be used to invoke +various operations on the executor. It has the following general form:

+
+
daName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section EXECUTOR METHODS for more +explanations.

+

The executor will be based on the deterministic finite automaton +stored in the object fa. It will keep a copy of the relevant +data of the FA in its own storage, in a form easy to use for its +purposes. This also means that changes made to the fa after the +construction of the executor will not influence the executor.

+

If any has been specified, then the executor will convert all +symbols in the input which are unknown to the base FA to that symbol +before proceeding with the processing.

+
+
+
+

EXECUTOR METHODS

+

All executors provide the following methods for their manipulation:

+
+
daName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
daName put symbol
+

Takes the current state of the executor and the symbol and +performs the appropriate state transition. Reports any errors +encountered via the command callback, as well as entering a final +state of the underlying FA.

+

When an error is reported all further invokations of put will +do nothing, until the error condition has been cleared via an +invokation of method reset.

+
daName reset
+

Unconditionally sets the executor into the start state of the +underlying FA. This also clears any error condition put may +have encountered.

+
daName state
+

Returns the current state of the underlying FA. This allow for +introspection without the need to pass data from the callback command.

+
+
+

EXECUTOR CALLBACK

+

The callback command cmdprefix given to an executor via the +option -command will be executed by the object at the global +level, using the syntax described below. Note that cmdprefix is +not simply the name of a command, but a full command prefix. In other +words it may contain additional fixed argument words beyond the +command word.

+
+
cmdprefix error code message
+

The executor has encountered an error, and message contains a +human-readable text explaining the nature of the problem. +The code on the other hand is a fixed machine-readable text. +The following error codes can be generated by executor objects.

+
+
BADSYM
+

An unknown symbol was found in the input. This can happen if and only +if no -any symbol was specified.

+
BADTRANS
+

The underlying FA has no transition for the current combination of +input symbol and state. In other words, the executor was not able to +compute a new state for this combination.

+
+
cmdprefix final stateid
+

The executor has entered the final state stateid.

+
cmdprefix reset
+

The executor was reset.

+
cmdprefix state stateid
+

The FA changed state due to a transition. stateid is the new state.

+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/fa.html Index: embedded/www/tcllib/files/modules/grammar_fa/fa.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/fa.html +++ embedded/www/tcllib/files/modules/grammar_fa/fa.html @@ -0,0 +1,622 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa - Create and manipulate finite automatons

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit 1.3
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require grammar::fa::op ?0.2?
    • +
  • package require grammar::fa ?0.4?
    • +
+ +
+
+

Description

+

This package provides a container class for +finite automatons (Short: FA). +It allows the incremental definition of the automaton, its +manipulation and querying of the definition. +While the package provides complex operations on the automaton +(via package grammar::fa::op), it does not have the +ability to execute a definition for a stream of symbols. +Use the packages +grammar::fa::dacceptor and +grammar::fa::dexec for that. +Another package related to this is grammar::fa::compiler. It +turns a FA into an executor class which has the definition of the FA +hardwired into it. The output of this package is configurable to suit +a large number of different implementation languages and paradigms.

+

For more information about what a finite automaton is see section +FINITE AUTOMATONS.

+
+

API

+

The package exports the API described here.

+
+
::grammar::fa faName ?=|:=|<--|as|deserialize src|fromRegex re ?over??
+

Creates a new finite automaton with an associated global Tcl command +whose name is faName. This command may be used to invoke various +operations on the automaton. It has the following general form:

+
+
faName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section FA METHODS for more explanations. The +new automaton will be empty if no src is specified. Otherwise +it will contain a copy of the definition contained in the src. +The src has to be a FA object reference for all operators except +deserialize and fromRegex. The deserialize +operator requires src to be the serialization of a FA instead, +and fromRegex takes a regular expression in the form a of a +syntax tree. See ::grammar::fa::op::fromRegex for more detail on +that.

+
+
+
+

FA METHODS

+

All automatons provide the following methods for their manipulation:

+
+
faName destroy
+

Destroys the automaton, including its storage space and associated +command.

+
faName clear
+

Clears out the definition of the automaton contained in faName, +but does not destroy the object.

+
faName = srcFA
+

Assigns the contents of the automaton contained +in srcFA to faName, overwriting any +existing definition. +This is the assignment operator for automatons. It copies the +automaton contained in the FA object srcFA over the automaton +definition in faName. The old contents of faName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    faName deserialize [srcFA serialize]
+
+
+
faName --> dstFA
+

This is the reverse assignment operator for automatons. It copies the +automation contained in the object faName over the automaton +definition in the object dstFA. +The old contents of dstFA are deleted by this operation.

+

This operation is in effect equivalent to

+
+    dstFA deserialize [faName serialize]
+
+
+
faName serialize
+

This method serializes the automaton stored in faName. In other +words it returns a tcl value completely describing that +automaton. +This allows, for example, the transfer of automatons over arbitrary +channels, persistence, etc. +This method is also the basis for both the copy constructor and the +assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the grammar::fa interface. This is what +will enable us to copy automatons between different implementations of +the same interface.

+

The result is a list of three elements with the following structure:

+
    +

  1. The constant string grammar::fa.

    2. +

  2. A list containing the names of all known input symbols. The order of +elements in this list is not relevant.

    3. +

  3. The last item in the list is a dictionary, however the order of the +keys is important as well. The keys are the states of the serialized +FA, and their order is the order in which to create the states when +deserializing. This is relevant to preserve the order relationship +between states.

    +

    The value of each dictionary entry is a list of three elements +describing the state in more detail.

    +
      +

    1. A boolean flag. If its value is true then the state is a +start state, otherwise it is not.

      2. +

    2. A boolean flag. If its value is true then the state is a +final state, otherwise it is not.

      3. +

    3. The last element is a dictionary describing the transitions for the +state. The keys are symbols (or the empty string), and the values are +sets of successor states.

      4. +
    +
    4. +
+

Assuming the following FA (which describes the life of a truck driver +in a very simple way :)

+
+    Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive
+    (...) is the start state.
+
+

a possible serialization is

+
+    grammar::fa \\
+    {yellow red green red/yellow} \\
+    {Drive     {0 0 {yellow     Brake}} \\
+     Brake     {0 0 {red        Stop}} \\
+     Stop      {1 0 {red/yellow Attention}} \\
+     Attention {0 0 {green      Drive}}}
+
+

A possible one, because I did not care about creation order here

+
faName deserialize serialization
+

This is the complement to serialize. It replaces the +automaton definition in faName with the automaton described by +the serialization value. The old contents of faName are +deleted by this operation.

+
faName states
+

Returns the set of all states known to faName.

+
faName state add s1 ?s2 ...?
+

Adds the states s1, s2, et cetera to the FA definition in +faName. The operation will fail any of the new states is already +declared.

+
faName state delete s1 ?s2 ...?
+

Deletes the state s1, s2, et cetera, and all associated +information from the FA definition in faName. The latter means +that the information about in- or outbound transitions is deleted as +well. If the deleted state was a start or final state then this +information is invalidated as well. The operation will fail if the +state s is not known to the FA.

+
faName state exists s
+

A predicate. It tests whether the state s is known to the FA in +faName. +The result is a boolean value. It will be set to true if the +state s is known, and false otherwise.

+
faName state rename s snew
+

Renames the state s to snew. Fails if s is not a +known state. Also fails if snew is already known as a state.

+
faName startstates
+

Returns the set of states which are marked as start states, +also known as initial states. +See FINITE AUTOMATONS for explanations what this means.

+
faName start add s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as start (aka initial).

+
faName start remove s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as not start (aka not accepting).

+
faName start? s
+

A predicate. It tests if the state s in the FA faName is +start or not. +The result is a boolean value. It will be set to true if the +state s is start, and false otherwise.

+
faName start?set stateset
+

A predicate. It tests if the set of states stateset contains at +least one start state. They operation will fail if the set contains an +element which is not a known state. +The result is a boolean value. It will be set to true if a +start state is present in stateset, and false otherwise.

+
faName finalstates
+

Returns the set of states which are marked as final states, +also known as accepting states. +See FINITE AUTOMATONS for explanations what this means.

+
faName final add s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as final (aka accepting).

+
faName final remove s1 ?s2 ...?
+

Mark the states s1, s2, et cetera in the FA faName +as not final (aka not accepting).

+
faName final? s
+

A predicate. It tests if the state s in the FA faName is +final or not. +The result is a boolean value. It will be set to true if the +state s is final, and false otherwise.

+
faName final?set stateset
+

A predicate. It tests if the set of states stateset contains at +least one final state. They operation will fail if the set contains an +element which is not a known state. +The result is a boolean value. It will be set to true if a +final state is present in stateset, and false otherwise.

+
faName symbols
+

Returns the set of all symbols known to the FA faName.

+
faName symbols@ s ?d?
+

Returns the set of all symbols for which the state s has transitions. +If the empty symbol is present then s has epsilon transitions. If two +states are specified the result is the set of symbols which have transitions +from s to t. This set may be empty if there are no transitions +between the two specified states.

+
faName symbols@set stateset
+

Returns the set of all symbols for which at least one state in the set +of states stateset has transitions. +In other words, the union of [faName symbols@ s] +for all states s in stateset. +If the empty symbol is present then at least one state contained in +stateset has epsilon transitions.

+
faName symbol add sym1 ?sym2 ...?
+

Adds the symbols sym1, sym2, et cetera to the FA +definition in faName. The operation will fail any of the symbols +is already declared. The empty string is not allowed as a value for the symbols.

+
faName symbol delete sym1 ?sym2 ...?
+

Deletes the symbols sym1, sym2 et cetera, and all +associated information from the FA definition in faName. The +latter means that all transitions using the symbols are deleted as +well. The operation will fail if any of the symbols is not known to +the FA.

+
faName symbol rename sym newsym
+

Renames the symbol sym to newsym. Fails if sym is +not a known symbol. Also fails if newsym is already known as a +symbol.

+
faName symbol exists sym
+

A predicate. It tests whether the symbol sym is known to the FA +in faName. +The result is a boolean value. It will be set to true if the +symbol sym is known, and false otherwise.

+
faName next s sym ?--> next?
+

Define or query transition information.

+

If next is specified, then the method will add a transition from +the state s to the successor state next labeled with +the symbol sym to the FA contained in faName. The +operation will fail if s, or next are not known states, or +if sym is not a known symbol. An exception to the latter is that +sym is allowed to be the empty string. In that case the new +transition is an epsilon transition which will not consume +input when traversed. The operation will also fail if the combination +of (s, sym, and next) is already present in the FA.

+

If next was not specified, then the method will return +the set of states which can be reached from s through +a single transition labeled with symbol sym.

+
faName !next s sym ?--> next?
+

Remove one or more transitions from the Fa in faName.

+

If next was specified then the single transition from the state +s to the state next labeled with the symbol sym is +removed from the FA. Otherwise all transitions originating in +state s and labeled with the symbol sym will be removed.

+

The operation will fail if s and/or next are not known as +states. It will also fail if a non-empty sym is not known as +symbol. The empty string is acceptable, and allows the removal of +epsilon transitions.

+
faName nextset stateset sym
+

Returns the set of states which can be reached by a single transition +originating in a state in the set stateset and labeled with the +symbol sym.

+

In other words, this is the union of +[faName next s symbol] +for all states s in stateset.

+
faName is deterministic
+

A predicate. It tests whether the FA in faName is a +deterministic FA or not. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName is complete
+

A predicate. It tests whether the FA in faName is a complete FA +or not. A FA is complete if it has at least one transition per state +and symbol. This also means that a FA without symbols, or states is +also complete. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+

Note: When a FA has epsilon-transitions transitions over a symbol for +a state S can be indirect, i.e. not attached directly to S, but to a +state in the epsilon-closure of S. The symbols for such indirect +transitions count when computing completeness.

+
faName is useful
+

A predicate. It tests whether the FA in faName is an useful FA +or not. A FA is useful if all states are reachable +and useful. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName is epsilon-free
+

A predicate. It tests whether the FA in faName is an +epsilon-free FA or not. A FA is epsilon-free if it has no epsilon +transitions. This definition means that all deterministic FAs are +epsilon-free as well, and epsilon-freeness is a necessary +pre-condition for deterministic'ness. +The result is a boolean value. It will be set to true if the +FA is deterministic, and false otherwise.

+
faName reachable_states
+

Returns the set of states which are reachable from a start state by +one or more transitions.

+
faName unreachable_states
+

Returns the set of states which are not reachable from any start state +by any number of transitions. This is

+
+	 [faName states] - [faName reachable_states]
+
+
+
faName reachable s
+

A predicate. It tests whether the state s in the FA faName +can be reached from a start state by one or more transitions. +The result is a boolean value. It will be set to true if the +state can be reached, and false otherwise.

+
faName useful_states
+

Returns the set of states which are able to reach a final state by +one or more transitions.

+
faName unuseful_states
+

Returns the set of states which are not able to reach a final state by +any number of transitions. This is

+
+	 [faName states] - [faName useful_states]
+
+
+
faName useful s
+

A predicate. It tests whether the state s in the FA faName +is able to reach a final state by one or more transitions. +The result is a boolean value. It will be set to true if the +state is useful, and false otherwise.

+
faName epsilon_closure s
+

Returns the set of states which are reachable from the state s +in the FA faName by one or more epsilon transitions, i.e +transitions over the empty symbol, transitions which do not consume +input. This is called the epsilon closure of s.

+
faName reverse
+
+
faName complete
+
+
faName remove_eps
+
+
faName trim ?what?
+
+
faName determinize ?mapvar?
+
+
faName minimize ?mapvar?
+
+
faName complement
+
+
faName kleene
+
+
faName optional
+
+
faName union fa ?mapvar?
+
+
faName intersect fa ?mapvar?
+
+
faName difference fa ?mapvar?
+
+
faName concatenate fa ?mapvar?
+
+
faName fromRegex regex ?over?
+

These methods provide more complex operations on the FA. Please see +the same-named commands in the package grammar::fa::op for +descriptions of what they do.

+
+
+ +

FINITE AUTOMATONS

+

For the mathematically inclined, a FA is a 5-tuple (S,Sy,St,Fi,T) where

+
    +

  • S is a set of states,

    • +

  • Sy a set of input symbols,

    • +

  • St is a subset of S, the set of start states, also known as +initial states.

    • +

  • Fi is a subset of S, the set of final states, also known as +accepting.

    • +

  • T is a function from S x (Sy + epsilon) to {S}, the transition function. +Here epsilon denotes the empty input symbol and is distinct +from all symbols in Sy; and {S} is the set of subsets of S. In other +words, T maps a combination of State and Input (which can be empty) to +a set of successor states.

    • +
+

In computer theory a FA is most often shown as a graph where the nodes +represent the states, and the edges between the nodes encode the +transition function: For all n in S' = T (s, sy) we have one edge +between the nodes representing s and n resp., labeled with sy. The +start and accepting states are encoded through distinct visual +markers, i.e. they are attributes of the nodes.

+

FA's are used to process streams of symbols over Sy.

+

A specific FA is said to accept a finite stream sy_1 sy_2 +... sy_n if there is a path in the graph of the FA beginning at a +state in St and ending at a state in Fi whose edges have the labels +sy_1, sy_2, etc. to sy_n. +The set of all strings accepted by the FA is the language of +the FA. One important equivalence is that the set of languages which +can be accepted by an FA is the set of regular languages.

+

Another important concept is that of deterministic FAs. A FA is said +to be deterministic if for each string of input symbols there +is exactly one path in the graph of the FA beginning at the start +state and whose edges are labeled with the symbols in the string. +While it might seem that non-deterministic FAs to have more power of +recognition, this is not so. For each non-deterministic FA we can +construct a deterministic FA which accepts the same language (--> +Thompson's subset construction).

+

While one of the premier applications of FAs is in parsing, +especially in the lexer stage (where symbols == characters), +this is not the only possibility by far.

+

Quite a lot of processes can be modeled as a FA, albeit with a +possibly large set of states. For these the notion of accepting states +is often less or not relevant at all. What is needed instead is the +ability to act to state changes in the FA, i.e. to generate some +output in response to the input. +This transforms a FA into a finite transducer, which has an +additional set OSy of output symbols and also an additional +output function O which maps from "S x (Sy + epsilon)" to +"(Osy + epsilon)", i.e a combination of state and input, possibly +empty to an output symbol, or nothing.

+

For the graph representation this means that edges are additional +labeled with the output symbol to write when this edge is traversed +while matching input. Note that for an application "writing an output +symbol" can also be "executing some code".

+

Transducers are not handled by this package. They will get their own +package in the future.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_fa/faop.html Index: embedded/www/tcllib/files/modules/grammar_fa/faop.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_fa/faop.html +++ embedded/www/tcllib/files/modules/grammar_fa/faop.html @@ -0,0 +1,458 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage"

+

Name

+

grammar::fa::op - Operations on finite automatons

+
+ + +

Description

+

This package provides a number of complex operations on finite +automatons (Short: FA), +as provided by the package grammar::fa. +The package does not provide the ability to create and/or manipulate +such FAs, nor the ability to execute a FA for a stream of symbols. +Use the packages grammar::fa +and grammar::fa::interpreter for that. +Another package related to this is grammar::fa::compiler +which turns a FA into an executor class which has the definition of +the FA hardwired into it.

+

For more information about what a finite automaton is see section +FINITE AUTOMATONS in package grammar::fa.

+
+

API

+

The package exports the API described here. All commands modify their +first argument. I.e. whatever FA they compute is stored back into +it. Some of the operations will construct an automaton whose states +are all new, but related to the states in the source +automaton(s). These operations take variable names as optional +arguments where they will store mappings which describe the +relationship(s). +The operations can be loosely partitioned into structural and language +operations. The latter are defined in terms of the language the +automaton(s) accept, whereas the former are defined in terms of the +structural properties of the involved automaton(s). Some operations +are both. +Structure operations

+
+
::grammar::fa::op::constructor cmd
+

This command has to be called by the user of the package before any other +operations is performed, to establish a command which can be used to +construct a FA container object. If this is not done several operations +will fail as they are unable to construct internal and transient containers +to hold state and/or partial results.

+

Any container class using this package for complex operations should set +its own class command as the constructor. See package grammar::fa +for an example.

+
::grammar::fa::op::reverse fa
+

Reverses the fa. This is done by reversing the direction of all +transitions and swapping the sets of start and final +states. The language of fa changes unpredictably.

+
::grammar::fa::op::complete fa ?sink?
+

Completes the fa complete, but nothing is done if the +fa is already complete. This implies that only the first +in a series of multiple consecutive complete operations on fa +will perform anything. The remainder will be null operations.

+

The language of fa is unchanged by this operation.

+

This is done by adding a single new state, the sink, and +transitions from all other states to that sink for all symbols they +have no transitions for. The sink itself is made complete by adding +loop transitions for all symbols.

+

Note: When a FA has epsilon-transitions transitions over a symbol for +a state S can be indirect, i.e. not attached directly to S, but to a +state in the epsilon-closure of S. The symbols for such indirect +transitions count when computing completeness of a state. In other +words, these indirectly reached symbols are not missing.

+

The argument sink provides the name for the new state and most +not be present in the fa if specified. If the name is not +specified the command will name the state "sinkn", where n +is set so that there are no collisions with existing states.

+

Note that the sink state is not useful by definition. In +other words, while the FA becomes complete, it is also +not useful in the strict sense as it has a state from which +no final state can be reached.

+
::grammar::fa::op::remove_eps fa
+

Removes all epsilon-transitions from the fa in such a manner the +the language of fa is unchanged. However nothing is done if the +fa is already epsilon-free. +This implies that only the first in a series of multiple consecutive +complete operations on fa will perform anything. The remainder +will be null operations.

+

Note: This operation may cause states to become unreachable or +not useful. These states are not removed by this operation. +Use ::grammar::fa::op::trim for that instead.

+
::grammar::fa::op::trim fa ?what?
+

Removes unwanted baggage from fa. +The legal values for what are listed below. The command defaults +to !reachable|!useful if no specific argument was given.

+
+
!reachable
+

Removes all states which are not reachable from a start state.

+
!useful
+

Removes all states which are unable to reach a final state.

+
!reachable&!useful
+
+
!(reachable|useful)
+

Removes all states which are not reachable from a start state and are +unable to reach a final state.

+
!reachable|!useful
+
+
!(reachable&useful)
+

Removes all states which are not reachable from a start state or are +unable to reach a final state.

+
+
::grammar::fa::op::determinize fa ?mapvar?
+

Makes the fa deterministic without changing the language +accepted by the fa. However nothing is done if the fa is +already deterministic. This implies that only the first in a +series of multiple consecutive complete operations on fa will +perform anything. The remainder will be null operations.

+

The command will store a dictionary describing the relationship +between the new states of the resulting dfa and the states of the +input nfa in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting dfa, values +are sets of states from the input nfa.

+

Note: An empty dictionary signals that the command was able to +make the fa deterministic without performing a full subset +construction, just by removing states and shuffling transitions around +(As part of making the FA epsilon-free).

+

Note: The algorithm fails to make the FA deterministic in the +technical sense if the FA has no start state(s), because determinism +requires the FA to have exactly one start states. +In that situation we make a best effort; and the missing start state +will be the only condition preventing the generated result from being +deterministic. +It should also be noted that in this case the possibilities for +trimming states from the FA are also severely reduced as we cannot +declare states unreachable.

+
::grammar::fa::op::minimize fa ?mapvar?
+

Creates a FA which accepts the same language as fa, but has a +minimal number of states. Uses Brzozowski's method to accomplish this.

+

The command will store a dictionary describing the relationship +between the new states of the resulting minimal fa and the states of +the input fa in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting minimal fa, +values are sets of states from the input fa.

+

Note: An empty dictionary signals that the command was able to +minimize the fa without having to compute new states. This +should happen if and only if the input FA was already minimal.

+

Note: If the algorithm has no start or final states to work +with then the result might be technically minimal, but have a very +unexpected structure. +It should also be noted that in this case the possibilities for +trimming states from the FA are also severely reduced as we cannot +declare states unreachable.

+
+

Language operations +All operations in this section require that all input FAs have at +least one start and at least one final state. Otherwise the language of +the FAs will not be defined, making the operation senseless (as it +operates on the languages of the FAs in a defined manner).

+
+
::grammar::fa::op::complement fa
+

Complements fa. This is possible if and only if fa is +complete and deterministic. The resulting FA accepts the +complementary language of fa. In other words, all inputs not +accepted by the input are accepted by the result, and vice versa.

+

The result will have all states and transitions of the input, and +different final states.

+
::grammar::fa::op::kleene fa
+

Applies Kleene's closure to fa. +The resulting FA accepts all strings S for which we can find a +natural number n (0 inclusive) and strings A1 ... An +in the language of fa such that S is the concatenation of +A1 ... An. +In other words, the language of the result is the infinite union over +finite length concatenations over the language of fa.

+

The result will have all states and transitions of the input, and new +start and final states.

+
::grammar::fa::op::optional fa
+

Makes the fa optional. In other words it computes the FA which +accepts the language of fa and the empty the word (epsilon) as +well.

+

The result will have all states and transitions of the input, and new +start and final states.

+
::grammar::fa::op::union fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the union of the languages of the two FAs.

+

The result will have all states and transitions of the two input FAs, +and new start and final states. All states of fb which exist in +fa as well will be renamed, and the mapvar will contain a +mapping from the old states of fb to the new ones, if present.

+

It should be noted that the result will be non-deterministic, even if +the inputs are deterministic.

+
::grammar::fa::op::intersect fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the intersection of the languages of the two FAs. In other +words, the result will accept a word if and only if the word is +accepted by both fa and fb. The result will be useful, but +not necessarily deterministic or minimal.

+

The command will store a dictionary describing the relationship +between the new states of the resulting fa and the pairs of states of +the input FAs in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting fa, values +are pairs of states from the input FAs. Pairs are represented by +lists. The first element in each pair will be a state in fa, the +second element will be drawn from fb.

+
::grammar::fa::op::difference fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the difference of the languages of the two FAs. In other +words, the result will accept a word if and only if the word is +accepted by fa, but not by fb. This can also be expressed +as the intersection of fa with the complement of fb. The +result will be useful, but not necessarily deterministic or minimal.

+

The command will store a dictionary describing the relationship +between the new states of the resulting fa and the pairs of states of +the input FAs in mapvar, if it has been specified. Keys of the +dictionary are the handles for the states of the resulting fa, values +are pairs of states from the input FAs. Pairs are represented by +lists. The first element in each pair will be a state in fa, the +second element will be drawn from fb.

+
::grammar::fa::op::concatenate fa fb ?mapvar?
+

Combines the FAs fa and fb such that the resulting FA +accepts the cross-product of the languages of the two FAs. I.e. a word +W will be accepted by the result if there are two words A and B +accepted by fa, and fb resp. and W is the concatenation of +A and B.

+

The result FA will be non-deterministic.

+
::grammar::fa::op::fromRegex fa regex ?over?
+

Generates a non-deterministic FA which accepts the same language as +the regular expression regex. If the over is specified it +is treated as the set of symbols the regular expression and the +automaton are defined over. The command will compute the set from the +"S" constructors in regex when over was not +specified. This set is important if and only if the complement +operator "!" is used in regex as the complementary language of +an FA is quite different for different sets of symbols.

+

The regular expression is represented by a nested list, which forms +a syntax tree. The following structures are legal:

+
+
{S x}
+

Atomic regular expression. Everything else is constructed from +these. Accepts the Symbol "x".

+
{. A1 A2 ...}
+

Concatenation operator. Accepts the concatenation of the regular +expressions A1, A2, etc.

+

Note that this operator accepts zero or more arguments. With zero +arguments the represented language is epsilon, the empty word.

+
{| A1 A2 ...}
+

Choice operator, also called "Alternative". Accepts all input accepted +by at least one of the regular expressions A1, A2, etc. In +other words, the union of A1, A2.

+

Note that this operator accepts zero or more arguments. With zero +arguments the represented language is the empty language, +the language without words.

+
{& A1 A2 ...}
+

Intersection operator, logical and. Accepts all input accepted which +is accepted by all of the regular expressions A1, A2, +etc. In other words, the intersection of A1, A2.

+
{? A}
+

Optionality operator. Accepts the empty word and anything from the +regular expression A.

+
{* A}
+

Kleene closure. Accepts the empty word and any finite concatenation of +words accepted by the regular expression A.

+
{+ A}
+

Positive Kleene closure. Accepts any finite concatenation of words +accepted by the regular expression A, but not the empty word.

+
{! A}
+

Complement operator. Accepts any word not accepted by the regular +expression A. Note that the complement depends on the set of +symbol the result should run over. See the discussion of the argument +over before.

+
+
::grammar::fa::op::toRegexp fa
+

This command generates and returns a regular expression which accepts +the same language as the finite automaton fa. The regular +expression is in the format as described above, for +::grammar::fa::op::fromRegex.

+
::grammar::fa::op::toRegexp2 fa
+

This command has the same functionality as ::grammar::fa::op::toRegexp, +but uses a different algorithm to simplify the generated regular expressions.

+
::grammar::fa::op::toTclRegexp regexp symdict
+

This command generates and returns a regular expression in Tcl syntax for the +regular expression regexp, if that is possible. regexp is in the +same format as expected by ::grammar::fa::op::fromRegex.

+

The command will fail and throw an error if regexp contains +complementation and intersection operations.

+

The argument symdict is a dictionary mapping symbol names to +pairs of syntactic type and Tcl-regexp. If a symbol +occurring in the regexp is not listed in this dictionary then +single-character symbols are considered to designate themselves +whereas multiple-character symbols are considered to be a character +class name.

+
::grammar::fa::op::simplifyRegexp regexp
+

This command simplifies a regular expression by applying the following +algorithm first to the main expression and then recursively to all +sub-expressions:

+
    +

  1. Convert the expression into a finite automaton.

    2. +

  2. Minimize the automaton.

    3. +

  3. Convert the automaton back to a regular expression.

    4. +

  4. Choose the shorter of original expression and expression from +the previous step.

    5. +
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_fa of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/gasm.html Index: embedded/www/tcllib/files/modules/grammar_me/gasm.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/gasm.html +++ embedded/www/tcllib/files/modules/grammar_me/gasm.html @@ -0,0 +1,439 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu::gasm - ME assembler

+
+ + +

Description

+

This package provides a simple in-memory assembler. Its origin is that +of a support package for use by packages converting PEG and other +grammars into a corresponding matcher based on the ME virtual machine, +like page::compiler::peg::mecpu. Despite that it is actually +mostly agnostic regarding the instructions, users can choose any +instruction set they like.

+

The program under construction is held in a graph structure (See +package struct::graph) during assembly and subsequent +manipulation, with instructions represented by nodes, and the flow of +execution between instructions explicitly encoded in the arcs between +them.

+

In this model jumps are not encoded explicitly, they are implicit in +the arcs. The generation of explicit jumps is left to any code +converting the graph structure into a more conventional +representation. The same goes for branches. They are implicitly +encoded by all instructions which have two outgoing arcs, whereas all +other instructions have only one outgoing arc. Their conditonality is +handled by tagging their outgoing arcs with information about the +conditions under which they are taken.

+

While the graph the assembler operates on is supplied from the +outside, i.e. external, it does manage some internal state, namely:

+
    +

  1. The handle of the graph node most assembler operations will +work on, the anchor.

    2. +

  2. A mapping from arbitrary strings to instructions. I.e. it is +possible to label an instruction during assembly, and later +recall that instruction by its label.

    3. +

  3. The condition code to use when creating arcs between +instructions, which is one of always, ok, and +fail.

    4. +

  4. The current operation mode, one of halt, +okfail, and !okfail.

    5. +

  5. The name of a node in a tree. This, and the operation mode +above are the parts most heavily influenced by the needs of a grammar +compiler, as they assume some basic program structures (selected +through the operation mode), and intertwine the graph with a tree, +like the AST for the grammar to be compiled.

    6. +
+
+

DEFINITIONS

+

As the graph the assembler is operating on, and the tree it is +intertwined with, are supplied to the assembler from the outside it is +necessary to specify the API expected from them, and to describe the +structures expected and/or generated by the assembler in either.

+
    +

  1. Any graph object command used by the assembler has to provide +the API as specified in the documentation for the package +struct::graph.

    2. +

  2. Any tree object command used by the assembler has to provide +the API as specified in the documentation for the package +struct::tree.

    3. +

  3. Any instruction (node) generated by the assembler in a graph +will have at least two, and at most three attributes:

    +
    +
    instruction
    +

    The value of this attribute is the name of +the instruction. The only names currently defined by the assembler are +the three pseudo-instructions

    +
    +
    NOP
    +

    This instruction does nothing. Useful for fixed +framework nodes, unchanging jump destinations, and the like. No +arguments.

    +
    C
    +

    A .NOP to allow the insertion of arbitrary comments +into the instruction stream, i.e. a comment node. One argument, the +text of the comment.

    +
    BRA
    +

    A .NOP serving as explicitly coded conditional +branch. No arguments.

    +
    +

    However we reserve the space of all instructions whose names begin +with a "." (dot) for future use by the assembler.

    +
    arguments
    +

    The value of this attribute is a list of +strings, the arguments of the instruction. The contents are dependent +on the actual instruction and the assembler doesn't know or care about +them. This means for example that it has no builtin knowledge about +what instruction need which arguments and thus doesn't perform any +type of checking.

    +
    expr
    +

    This attribute is optional. When it is present its +value is the name of a node in the tree intertwined with the graph.

    +
    +
    4. +

  4. Any arc between two instructions will have one attribute:

    +
    +
    condition
    +

    The value of this attribute determines under which +condition execution will take this arc. It is one of always, +ok, and fail. The first condition is used for all arcs +which are the single outgoing arc of an instruction. The other two are +used for the two outgoing arcs of an instruction which implicitly +encode a branch.

    +
    +
    5. +

  5. A tree node given to the assembler for cross-referencing will +be written to and given the following attributes, some fixed, some +dependent on the operation mode. All values will be references to +nodes in the instruction graph. Some of the instruction will expect +some or specific sets of these attributes.

    +
    +
    gas::entry
    +

    Always written.

    +
    gas::exit
    +

    Written for all modes but okfail.

    +
    gas::exit::ok
    +

    Written for mode okfail.

    +
    gas::exit::fail
    +

    Written for mode okfail.

    +
    +
    6. +
+
+

API

+
+
::grammar::me::cpu::gasm::begin g n ?mode? ?note?
+

This command starts the assembly of an instruction sequence, and +(re)initializes the state of the assembler. After completion of the +instruction sequence use ::grammar::me::cpu::gasm::done to +finalize the assembler.

+

It will operate on the graph g in the specified mode +(Default is okfail). As part of the initialization it will +always create a standard .NOP instruction and label it "entry". The +creation of the remaining standard instructions is +mode-dependent:

+
+
halt
+

An "icf_halt" instruction labeled "exit/return".

+
!okfail
+

An "icf_ntreturn" instruction labeled "exit/return".

+
okfail
+

Two .NOP instructions labeled "exit/ok" and +"exit/fail" respectively.

+
+

The note, if specified (default is not), is given to the "entry" .NOP instruction.

+

The node reference n is simply stored for use by +::grammar::me::cpu::gasm::done. It has to refer to a node in the +tree t argument of that command.

+

After the initialization is done the "entry" instruction will be the +anchor, and the condition code will be set to always.

+

The command returns the empy string as its result.

+
::grammar::me::cpu::gasm::done --> t
+

This command finalizes the creation of an instruction sequence and +then clears the state of the assembler. +NOTE that this does not delete any of the created +instructions. They can be made available to future begin/done cycles. +Further assembly will be possible only after reinitialization of the +system via ::grammar::me::cpu::gasm::begin.

+

Before the state is cleared selected references to selected +instructions will be written to attributes of the node n in the +tree t. +Which instructions are saved is mode-dependent. Both mode +and the destination node n were specified during invokation of +::grammar::me::cpu::gasm::begin.

+

Independent of the mode a reference to the instruction labeled "entry" +will be saved to the attribute gas::entry of n. The +reference to the node n will further be saved into the attribute +"expr" of the "entry" instruction. Beyond that

+
+
halt
+

A reference to the instruction labeled +"exit/return" will be saved to the attribute gas::exit of +n.

+
okfail
+

See halt.

+
!okfail
+

Reference to the two instructions labeled +"exit/ok" and "exit/fail" will be saved to the attributes +gas::exit::ok and gas::exit::fail of n +respectively.

+
+

The command returns the empy string as its result.

+
::grammar::me::cpu::gasm::state
+

This command returns the current state of the assembler. Its format is +not documented and considered to be internal to the package.

+
::grammar::me::cpu::gasm::state! s
+

This command takes a serialized assembler state s as returned by +::grammar::me::cpu::gasm::state and makes it the current state +of the assembler.

+

Note that this may overwrite label definitions, however all +non-conflicting label definitions in the state before are not touched +and merged with s.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::lift t dst = src
+

This command operates on the tree t. It copies the contents of +the attributes gas::entry, gas::exit::ok and +gas::exit::fail from the node src to the node dst. +It returns the empty string as its result.

+
::grammar::me::cpu::gasm::Inline t node label
+

This command links an instruction sequence created by an earlier +begin/done pair into the current instruction sequence.

+

To this end it

+
    +

  1. reads the instruction references from the attributes +gas::entry, gas::exit::ok, and gas::exit::fail +from the node n of the tree t and makes them available to +assembler und the labels label/entry, label/exit::ok, and +label/exit::fail respectively.

    2. +

  2. Creates an arc from the anchor to the node labeled +label/entry, and tags it with the current condition code.

    3. +

  3. Makes the node labeled label/exit/ok the new anchor.

    4. +
+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Cmd cmd ?arg...?
+

This is the basic command to add instructions to the graph. +It creates a new instruction of type cmd with the given +arguments arg... +If the anchor was defined it will also create an arc from the +anchor to the new instruction using the current condition code. +After the call the new instruction will be the anchor and the +current condition code will be set to always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Bra
+

This is a convenience command to create a .BRA pseudo-instruction. It +uses ::grammar::me::cpu::gasm::Cmd to actually create the +instruction and inherits its behaviour.

+
::grammar::me::cpu::gasm::Nop text
+

This is a convenience command to create a .NOP pseudo-instruction. It +uses ::grammar::me::cpu::gasm::Cmd to actually create the +instruction and inherits its behaviour. +The text will be saved as the first and only argument of the new +instruction.

+
::grammar::me::cpu::gasm::Note text
+

This is a convenience command to create a .C pseudo-instruction, +i.e. a comment. It uses ::grammar::me::cpu::gasm::Cmd to +actually create the instruction and inherits its behaviour. +The text will be saved as the first and only argument of the new +instruction.

+
::grammar::me::cpu::gasm::Jmp label
+

This command creates an arc from the anchor to the instruction +labeled with label, and tags with the the current condition +code.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Exit
+

This command creates an arc from the anchor to one of the exit +instructions, based on the operation mode (see +::grammar::me::cpu::gasm::begin), and tags it with current +condition code.

+

For mode okfail it links to the instruction labeled either +"exit/ok" or "exit/fail", depending on the current condition code, and +tagging it with the current condition code +For the other two modes it links to the instruction labeled +"exit/return", tagging it condition code always, independent +the current condition code.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::Who label
+

This command returns a reference to the instruction labeled with +label.

+
::grammar::me::cpu::gasm::/Label name
+

This command labels the anchor with name. +Note that an instruction can have more than one label.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Clear
+

This command clears the anchor, leaving it undefined, and +further resets the current condition code to always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Ok
+

This command sets the current condition code to ok.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/Fail
+

This command sets the current condition code to fail.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/At name
+

This command sets the anchor to the instruction labeled with +name, and further resets the current condition code to +always.

+

The command returns the empty string as its result.

+
::grammar::me::cpu::gasm::/CloseLoop
+

This command marks the anchor as the last instruction in a loop +body, by creating the attribute LOOP.

+

The command returns the empty string as its result.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_ast.html Index: embedded/www/tcllib/files/modules/grammar_me/me_ast.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_ast.html +++ embedded/www/tcllib/files/modules/grammar_me/me_ast.html @@ -0,0 +1,212 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_ast - Various representations of ASTs

+
+ +

Description

+

This document specifies various representations for the +abstract syntax trees (short AST) generated by +instances of ME virtual machines, independent of variant. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

ASTs and all the representations we specify distinguish between two +types of nodes, namely:

+
+
Terminal
+

Terminal nodes refer to the terminal symbols found in the token +stream. They are always leaf nodes. I.e. terminal nodes never have +children.

+
Nonterminal
+

Nonterminal nodes represent a nonterminal symbol of the grammar used +during parsing. They can occur as leaf and inner nodes of the +tree.

+
+

Both types of nodes carry basic range information telling a user which +parts of the input are covered by the node by providing the location +of the first and last tokens found within the range. Locations are +provided as non-negative integer offsets from the beginning of the +token stream, with the first token found in the stream located at +offset 0 (zero).

+

The root of an AS tree can be either a terminal or nonterminal node.

+
+

AST VALUES

+

This representation of ASTs is a Tcl list. The main list represents +the root node of the tree, with the representations of the children +nested within.

+

Each node is represented by a single Tcl list containing three or more +elements. The first element is either the empty string or the name of +a nonterminal symbol (which is never the empty string). The second and +third elements are then the locations of the first and last tokens. +Any additional elements after the third are then the representations +of the children, with the leftmost child first, i.e. as the fourth +element of the list representing the node.

+
+

AST OBJECTS

+

In this representation an AST is represented by a Tcl object command +whose API is compatible to the tree objects provided by the package +struct::tree. I.e it has to support at least all of the +methods described by that package, and may support more.

+

Because of this the remainder of the specifications is written using +the terms of struct::tree.

+

Each node of the AST directly maps to a node in the tree object. All +data beyond the child nodes, i.e. node type and input locations, are +stored in attributes of the node in the tree object. They are:

+
+
type
+

The type of the AST node. The recognized values are terminal +and nonterminal.

+
range
+

The locations of the first and last token of the terminal data in the +input covered by the node. This is a list containing two locations.

+
detail
+

This attribute is present only for nonterminal nodes. It contains the +name of the nonterminal symbol stored in the node.

+
+
+

EXTENDED AST OBJECTS

+

Extended AST objects are like AST objects, with additional +information.

+
+
detail
+

This attribute is now present at all nodes. Its contents are unchanged +for nonterminal nodes. For terminal nodes it contains a list +describing all tokens from the input which are covered by the node.

+

Each element of the list contains the token name, the associated +lexeme attribute, line number, and column index, in this order.

+
range_lc
+

This new attribute is defined for all nodes, and contains the +locations from attribute range translated into line number and +column index. Lines are counted from 1, columns are counted from 0.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_cpu.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpu.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_cpu.html +++ embedded/www/tcllib/files/modules/grammar_me/me_cpu.html @@ -0,0 +1,351 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu - Virtual machine implementation II for parsing token streams

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation provides an object-based API and the machines are +not truly tied to Tcl. A C implementation of the same API is quite +possible.

+

Internally the package actually uses the value-based machine +manipulation commands as provided by the package +grammar::me::cpu::core to perform its duties.

+
+

API

+

CLASS API

+

The package directly provides only a single command for the +construction of ME virtual machines.

+
+
::grammar::me::cpu meName matchcode
+

The command creates a new ME machine object with an associated global +Tcl command whose name is meName. This command may be used to +invoke various operations on the machine. +It has the following general form:

+
+
meName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The argument matchcode contains the match instructions the +machine has to execute while parsing the input stream. Please read +section MATCH CODE REPRESENTATION of the +documentation for the package grammar::me::cpu::core for +the specification of the structure of this value.

+

The tokmap argument taken by the implementation provided by the +package grammar::me::tcl is here hidden inside of the match +instructions and therefore not needed.

+
+
+

OBJECT API

+

All ME virtual machine objects created by the class command specified +in section CLASS API support the methods listed below.

+

The machines provided by this package provide methods for operation in +both push- and pull-styles. Push-style means that tokens are pushed +into the machine state when they arrive, triggering further execution +until they are consumed. In other words, this allows the machine to be +suspended and resumed at will and an arbitrary number of times, the +quasi-parallel operation of several machines, and the operation as +part of the event loop.

+
+
meName lc location
+

This method converts the location of a token given as offset in the +input stream into the associated line number and column index. The +result of the command is a 2-element list containing the two values, +in the order mentioned in the previous sentence. +This allows higher levels to convert the location information found in +the error status and the generated AST into more human readable data.

+

Note that the command is not able to convert locations which +have not been reached by the machine yet. In other words, if the +machine has read 7 tokens the command is able to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+
meName tok ?from ?to??
+

This method returns a Tcl list containing the part of the input stream +between the locations from and to (both inclusive). If +to is not specified it will default to the value of from. +If from is not specified either the whole input stream is returned.

+

Each element of the returned list is a list of four elements, the +token, its associated lexeme, line number, and column index, in this +order. +This command places the same restrictions on its location arguments as +the method lc.

+
meName pc state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter.

+
meName iseof state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag.

+
meName at state
+

This method takes the state value of a ME virtual machine and returns +the current location in the input stream.

+
meName cc state
+

This method takes the state value of a ME virtual machine and returns +the current token.

+
meName sv
+

This command returns the current semantic value SV stored in +the machine. This is an abstract syntax tree as specified in the +document grammar::me_ast, section AST VALUES.

+
meName ok
+

This method returns the current match status OK.

+
meName error
+

This method returns the current error status ER.

+
meName lstk state
+

This method takes the state value of a ME virtual machine and returns +the location stack.

+
meName astk state
+

This method takes the state value of a ME virtual machine and returns +the AST stack.

+
meName mstk state
+

This method takes the state value of a ME virtual machine and returns +the AST marker stack.

+
meName estk state
+

This method takes the state value of a ME virtual machine and returns +the error stack.

+
meName rstk state
+

This method takes the state value of a ME virtual machine and returns +the subroutine return stack.

+
meName nc state
+

This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary.

+
meName ast
+

This method returns the current top entry of the AST stack AS. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
meName halted
+

This method returns a boolean value telling the caller whether the +engine has halted execution or not. Halt means that no further +matching is possible, and the information retrieved via the other +method is final. Attempts to run the engine will be ignored, +until a reset is made.

+
meName code
+

This method returns the code information used to construct the +object. In other words, the match program executed by the machine.

+
meName eof
+

This method adds an end of file marker to the end of the input stream. +This signals the machine that the current contents of the input queue +are the final parts of the input and nothing will come after. Attempts +to put more characters into the queue will fail.

+
meName put tok lex line col
+

This method adds the token tok to the end of the input stream, +with associated lexeme data lex and line/column +information.

+
meName putstring string lvar cvar
+

This method adds each individual character in the string as a +token to the end of the input stream, from first to last. The lexemes +will be empty and the line/col information is computed based on the +characters encountered and the data in the variables lvar and +cvar.

+
meName run ?n?
+

This methods causes the engine to execute match instructions until +either

+
    +

  • n instructions have been executed, or

    • +

  • a halt instruction was executed, or

    • +

  • the input queue is empty and the code is asking for more tokens to +process.

    • +
+

If no limit n was set only the last two conditions are checked +for.

+
meName pull nextcmd
+

This method implements pull-style operation of the machine. It causes +it to execute match instructions until either a halt instruction is +reached, or the command prefix +nextcmd ceases to deliver more tokens.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the machine whenever the a new character +from the stream is required. The instruction for handling this is +ict_advance. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The end of the input stream for this method does not imply that method +eof is called for the machine as a whole. By avoiding this +and still asking for an explicit call of the method it is possible to +mix push- and pull-style operation during the lifetime of the machine.

+
meName reset
+

This method resets the machine to its initial state, discarding any +state it may have.

+
meName destroy
+

This method deletes the object and releases all resurces it claimed.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html Index: embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html +++ embedded/www/tcllib/files/modules/grammar_me/me_cpucore.html @@ -0,0 +1,416 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::cpu::core - ME virtual machine state manipulation

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation represents each ME virtual machine as a Tcl value +and provides commands to manipulate and query such values to show the +effects of executing instructions, adding tokens, retrieving state, +etc.

+

The values fully follow the paradigm of Tcl that every value is a +string and while also allowing C implementations for a proper +Tcl_ObjType to keep all the important data in native data structures. +Because of the latter it is recommended to access the state values +only through the commands of this package to ensure that +internal representation is not shimmered away.

+

The actual structure used by all state values is described in section +CPU STATE.

+
+

API

+

The package directly provides only a single command, and all the +functionality is made available through its methods.

+
+
::grammar::me::cpu::core disasm asm
+

This method returns a list containing a disassembly of the match +instructions in asm. The format of asm is specified in the +section MATCH PROGRAM REPRESENTATION.

+

Each element of the result contains instruction label, instruction +name, and the instruction arguments, in this order. The label can be +the empty string. Jump destinations are shown as labels, strings and +tokens unencoded. Token names are prefixed with their numeric id, if, +and only if a tokmap is defined. The two components are separated by a +colon.

+
::grammar::me::cpu::core asm asm
+

This method returns code in the format as specified in section +MATCH PROGRAM REPRESENTATION generated from ME assembly +code asm, which is in the format as returned by the method +disasm.

+
::grammar::me::cpu::core new asm
+

This method creates state value for a ME virtual machine in its +initial state and returns it as its result.

+

The argument matchcode contains a Tcl representation of the +match instructions the machine has to execute while parsing the input +stream. Its format is specified in the section +MATCH PROGRAM REPRESENTATION.

+

The tokmap argument taken by the implementation provided by the +package grammar::me::tcl is here hidden inside of the match +instructions and therefore not needed.

+
::grammar::me::cpu::core lc state location
+

This method takes the state value of a ME virtual machine and uses it +to convert a location in the input stream (as offset) into a line +number and column index. The result of the method is a 2-element list +containing the two pieces in the order mentioned in the previous +sentence.

+

Note that the method cannot convert locations which the machine +has not yet read from the input stream. In other words, if the machine +has read 7 characters so far it is possible to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+

This utility allows higher levels to convert the location offsets +found in the error status and the AST into more human readable data.

+
::grammar::me::cpu::core tok state ?from ?to??
+

This method takes the state value of a ME virtual machine and returns +a Tcl list containing the part of the input stream between the +locations from and to (both inclusive). If to is not +specified it will default to the value of from. If from is +not specified either the whole input stream is returned.

+

This method places the same restrictions on its location arguments as +the method lc.

+
::grammar::me::cpu::core pc state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored program counter.

+
::grammar::me::cpu::core iseof state
+

This method takes the state value of a ME virtual machine and returns +the current value of the stored eof flag.

+
::grammar::me::cpu::core at state
+

This method takes the state value of a ME virtual machine and returns +the current location in the input stream.

+
::grammar::me::cpu::core cc state
+

This method takes the state value of a ME virtual machine and returns +the current token.

+
::grammar::me::cpu::core sv state
+

This method takes the state value of a ME virtual machine and returns +the current semantic value stored in it. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
::grammar::me::cpu::core ok state
+

This method takes the state value of a ME virtual machine and returns +the match status stored in it.

+
::grammar::me::cpu::core error state
+

This method takes the state value of a ME virtual machine and returns +the current error status stored in it.

+
::grammar::me::cpu::core lstk state
+

This method takes the state value of a ME virtual machine and returns +the location stack.

+
::grammar::me::cpu::core astk state
+

This method takes the state value of a ME virtual machine and returns +the AST stack.

+
::grammar::me::cpu::core mstk state
+

This method takes the state value of a ME virtual machine and returns +the AST marker stack.

+
::grammar::me::cpu::core estk state
+

This method takes the state value of a ME virtual machine and returns +the error stack.

+
::grammar::me::cpu::core rstk state
+

This method takes the state value of a ME virtual machine and returns +the subroutine return stack.

+
::grammar::me::cpu::core nc state
+

This method takes the state value of a ME virtual machine and returns +the nonterminal match cache as a dictionary.

+
::grammar::me::cpu::core ast state
+

This method takes the state value of a ME virtual machine and returns +the abstract syntax tree currently at the top of the AST stack stored +in it. +This is an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES.

+
::grammar::me::cpu::core halted state
+

This method takes the state value of a ME virtual machine and returns +the current halt status stored in it, i.e. if the machine has stopped +or not.

+
::grammar::me::cpu::core code state
+

This method takes the state value of a ME virtual machine and returns +the code stored in it, i.e. the instructions executed by the machine.

+
::grammar::me::cpu::core eof statevar
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar and modifies it so that the eof +flag inside is set. This signals to the machine that whatever token +are in the input queue are the last to be processed. There will be no +more.

+
::grammar::me::cpu::core put statevar tok lex line col
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar and modifies it so that the token +tok is added to the end of the input queue, with associated +lexeme data lex and line/column information.

+

The operation will fail with an error if the eof flag of the machine +has been set through the method eof.

+
::grammar::me::cpu::core run statevar ?n?
+

This method takes the state value of a ME virtual machine as stored in +the variable named by statevar, executes a number of +instructions and stores the state resulting from their modifications +back into the variable.

+

The execution loop will run until either

+
    +

  • n instructions have been executed, or

    • +

  • a halt instruction was executed, or

    • +

  • the input queue is empty and the code is asking for more tokens to +process.

    • +
+

If no limit n was set only the last two conditions are checked +for.

+
+

MATCH PROGRAM REPRESENTATION

+

A match program is represented by nested Tcl list. The first element, +asm, is a list of integer numbers, the instructions to execute, +and their arguments. The second element, pool, is a list of +strings, referenced by the instructions, for error messages, token +names, etc. The third element, tokmap, provides ordering +information for the tokens, mapping their names to their numerical +rank. This element can be empty, forcing lexicographic comparison when +matching ranges.

+

All ME instructions are encoded as integer numbers, with the mapping +given below. A number of the instructions, those which handle error +messages, have been given an additional argument to supply that +message explicitly instead of having it constructed from token names, +etc. This allows the machine state to store only the message ids +instead of the full strings.

+

Jump destination arguments are absolute indices into the asm +element, refering to the instruction to jump to. Any string arguments +are absolute indices into the pool element. Tokens, characters, +messages, and token (actually character) classes to match are coded as +references into the pool as well.

+
    +

  1. "ict_advance message"

    2. +

  2. "ict_match_token tok message"

    3. +

  3. "ict_match_tokrange tokbegin tokend message"

    4. +

  4. "ict_match_tokclass code message"

    5. +

  5. "inc_restore branchlabel nt"

    6. +

  6. "inc_save nt"

    7. +

  7. "icf_ntcall branchlabel"

    8. +

  8. "icf_ntreturn"

    9. +

  9. "iok_ok"

    10. +

  10. "iok_fail"

    11. +

  11. "iok_negate"

    12. +

  12. "icf_jalways branchlabel"

    13. +

  13. "icf_jok branchlabel"

    14. +

  14. "icf_jfail branchlabel"

    15. +

  15. "icf_halt"

    16. +

  16. "icl_push"

    17. +

  17. "icl_rewind"

    18. +

  18. "icl_pop"

    19. +

  19. "ier_push"

    20. +

  20. "ier_clear"

    21. +

  21. "ier_nonterminal message"

    22. +

  22. "ier_merge"

    23. +

  23. "isv_clear"

    24. +

  24. "isv_terminal"

    25. +

  25. "isv_nonterminal_leaf nt"

    26. +

  26. "isv_nonterminal_range nt"

    27. +

  27. "isv_nonterminal_reduce nt"

    28. +

  28. "ias_push"

    29. +

  29. "ias_mark"

    30. +

  30. "ias_mrewind"

    31. +

  31. "ias_mpop"

    32. +
+
+
+

CPU STATE

+

A state value is a list containing the following elements, in the order listed below:

+
    +

  1. code: Match instructions, see MATCH PROGRAM REPRESENTATION.

    2. +

  2. pc: Program counter, int.

    3. +

  3. halt: Halt flag, boolean.

    4. +

  4. eof: Eof flag, boolean

    5. +

  5. tc: Terminal cache, and input queue. Structure see below.

    6. +

  6. cl: Current location, int.

    7. +

  7. ct: Current token, string.

    8. +

  8. ok: Match status, boolean.

    9. +

  9. sv: Semantic value, list.

    10. +

  10. er: Error status, list.

    11. +

  11. ls: Location stack, list.

    12. +

  12. as: AST stack, list.

    13. +

  13. ms: AST marker stack, list.

    14. +

  14. es: Error stack, list.

    15. +

  15. rs: Return stack, list.

    16. +

  16. nc: Nonterminal cache, dictionary.

    17. +
+

tc, the input queue of tokens waiting for processing and the +terminal cache containing the tokens already processing are one +unified data structure simply holding all tokens and their +information, with the current location separating that which has been +processed from that which is waiting. +Each element of the queue/cache is a list containing the token, its +lexeme information, line number, and column index, in this order.

+

All stacks have their top element aat the end, i.e. pushing an item is +equivalent to appending to the list representing the stack, and +popping it removes the last element.

+

er, the error status is either empty or a list of two elements, +a location in the input, and a list of messages, encoded as references +into the pool element of the code.

+

nc, the nonterminal cache is keyed by nonterminal name and +location, each value a four-element list containing current location, +match status, semantic value, and error status, in this order.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_intro.html Index: embedded/www/tcllib/files/modules/grammar_me/me_intro.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_intro.html +++ embedded/www/tcllib/files/modules/grammar_me/me_intro.html @@ -0,0 +1,173 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_intro - Introduction to virtual machines for parsing token streams

+
+ +

Description

+

This document is an introduction to and overview of the basic +facilities for the parsing and/or matching of token +streams. One possibility often used for the token domain are +characters.

+

The packages themselves all provide variants of one +virtual machine, called a match engine (short +ME), which has all the facilities needed for the matching and +parsing of a stream, and which are either controlled directly, or are +customized with a match program. The virtual machine is basically a +pushdown automaton, with additional elements for backtracking and/or +handling of semantic data and construction of abstract syntax trees +(AST).

+

Because of the high degree of similarity in the actual implementations +of the aforementioned virtual machine and the data structures they +receive and generate these common parts are specified in a separate +document which will be referenced by the documentation for packages +actually implementing it.

+

The relevant documents are:

+
+
grammar::me_vm
+

Virtual machine specification.

+
grammar::me_ast
+

Specification of various representations used for abstract syntax +trees.

+
grammar::me::util
+

Utility commands.

+
grammar::me::tcl
+

Singleton ME virtual machine implementation tied to Tcl for control +flow and stacks. Hardwired for pull operation. Uninteruptible during +processing.

+
grammar::me::cpu
+

Object-based ME virtual machine implementation with explicit control +flow, and stacks, using bytecodes. Suspend/Resumable. Push/pull +operation.

+
grammar::me::cpu::core
+

Core functionality for state manipulation and stepping used in the +bytecode based implementation of ME virtual machines.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_tcl.html Index: embedded/www/tcllib/files/modules/grammar_me/me_tcl.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_tcl.html +++ embedded/www/tcllib/files/modules/grammar_me/me_tcl.html @@ -0,0 +1,396 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::tcl - Virtual machine implementation I for parsing token streams

+
+ + +

Description

+

This package provides an implementation of the ME virtual machine. +Please go and read the document grammar::me_intro first if +you do not know what a ME virtual machine is.

+

This implementation is tied very strongly to Tcl. All the stacks in +the machine state are handled through the Tcl stack, all control flow +is handled by Tcl commands, and the remaining machine instructions are +directly mapped to Tcl commands. Especially the matching of +nonterminal symbols is handled by Tcl procedures as well, essentially +extending the machine implementation with custom instructions.

+

Further on the implementation handles only a single machine which is +uninteruptible during execution and hardwired for pull operation. I.e. +it explicitly requests each new token through a callback, pulling them +into its state.

+

A related package is grammar::peg::interp which provides a +generic interpreter / parser for parsing expression grammars (PEGs), +implemented on top of this implementation of the ME virtual machine.

+
+

API

+

The commands documented in this section do not implement any of the +instructions of the ME virtual machine. They provide the facilities +for the initialization of the machine and the retrieval of important +information.

+
+
::grammar::me::tcl cmd ...
+

This is an ensemble command providing access to the commands listed in +this section. See the methods themselves for detailed specifications.

+
::grammar::me::tcl init nextcmd ?tokmap?
+

This command (re)initializes the machine. It returns the empty +string. This command has to be invoked before any other command of +this package.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the machine whenever the a new character +from the stream is required. The instruction for handling this is +ict_advance. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The optional dictionary tokmap maps from tokens to integer +numbers. If present the numbers impose an order on the tokens, which +is subsequently used by ict_match_tokrange to determine if a +token is in the specified range or not. If no token map is specified +the lexicographic order of th token names will be used instead. This +choice is especially asensible when using characters as tokens.

+
::grammar::me::tcl lc location
+

This command converts the location of a token given as offset in the +input stream into the associated line number and column index. The +result of the command is a 2-element list containing the two values, +in the order mentioned in the previous sentence. +This allows higher levels to convert the location information found in +the error status and the generated AST into more human readable data.

+

Note that the command is not able to convert locations which +have not been reached by the machine yet. In other words, if the +machine has read 7 tokens the command is able to convert the offsets +0 to 6, but nothing beyond that. This also shows that +it is not possible to convert offsets which refer to locations before +the beginning of the stream.

+

After a call of init the state used for the conversion is +cleared, making further conversions impossible until the machine has +read tokens again.

+
::grammar::me::tcl tok from ?to?
+

This command returns a Tcl list containing the part of the input +stream between the locations from and to (both +inclusive). If to is not specified it will default to the value +of from.

+

Each element of the returned list is a list of four elements, the +token, its associated lexeme, line number, and column index, in this +order. +In other words, each element has the same structure as the result of +the nextcmd callback given to ::grammar::me::tcl::init

+

This command places the same restrictions on its location arguments as +::grammar::me::tcl::lc.

+
::grammar::me::tcl tokens
+

This command returns the number of tokens currently known to the ME +virtual machine.

+
::grammar::me::tcl sv
+

This command returns the current semantic value SV stored in +the machine. This is an abstract syntax tree as specified in the +document grammar::me_ast, section AST VALUES.

+
::grammar::me::tcl ast
+

This method returns the abstract syntax tree currently at the top of +the AST stack of the ME virtual machine. This is an abstract syntax +tree as specified in the document grammar::me_ast, section +AST VALUES.

+
::grammar::me::tcl astall
+

This method returns the whole stack of abstract syntax trees currently +known to the ME virtual machine. Each element of the returned list is +an abstract syntax tree as specified in the document +grammar::me_ast, section AST VALUES. +The top of the stack resides at the end of the list.

+
::grammar::me::tcl ctok
+

This method returns the current token considered by the ME virtual +machine.

+
::grammar::me::tcl nc
+

This method returns the contents of the nonterminal cache as a +dictionary mapping from "symbol,location" to match +information.

+
::grammar::me::tcl next
+

This method returns the next token callback as specified during +initialization of the ME virtual machine.

+
::grammar::me::tcl ord
+

This method returns a dictionary containing the tokmap specified +during initialization of the ME virtual machine. +::grammar::me::tcl::ok +This variable contains the current match status OK. It is +provided as variable instead of a command because that makes access to +this information faster, and the speed of access is considered very +important here as this information is used constantly to determine the +control flow.

+
+
+

MACHINE STATE

+

Please go and read the document grammar::me_vm first for a +specification of the basic ME virtual machine and its state.

+

This implementation manages the state described in that document, +except for the stacks minus the AST stack. In other words, location +stack, error stack, return stack, and ast marker stack are implicitly +managed through standard Tcl scoping, i.e. Tcl variables in +procedures, outside of this implementation.

+
+

MACHINE INSTRUCTIONS

+

Please go and read the document grammar::me_vm first for a +specification of the basic ME virtual machine and its instruction set.

+

This implementation maps all instructions to Tcl commands in the +namespace "::grammar::me::tcl", except for the stack related commands, +nonterminal symbols and control flow. +Here we simply list the commands and explain the differences to the +specified instructions, if there are any. For their semantics see the +aforementioned specification. The machine commands are not +reachable through the ensemble command ::grammar::me::tcl.

+
+
::grammar::me::tcl::ict_advance message
+

No changes.

+
::grammar::me::tcl::ict_match_token tok message
+

No changes.

+
::grammar::me::tcl::ict_match_tokrange tokbegin tokend message
+

If, and only if a token map was specified during initialization then +the arguments are the numeric representations of the smallest and +largest tokens in the range. Otherwise they are the relevant tokens +themselves and lexicographic comparison is used.

+
::grammar::me::tcl::ict_match_tokclass code message
+

No changes.

+
::grammar::me::tcl::inc_restore nt
+

Instead of taking a branchlabel the command returns a boolean value. +The result will be true if and only if cached information was +found. The caller has to perform the appropriate branching.

+
::grammar::me::tcl::inc_save nt startlocation
+

The command takes the start location as additional argument, as it is +managed on the Tcl stack, and not in the machine state.

+
icf_ntcall branchlabel
+
+
icf_ntreturn
+

These two instructions are not mapped to commands. They are control +flow instructions and handled in Tcl.

+
::grammar::me::tcl::iok_ok
+

No changes.

+
::grammar::me::tcl::iok_fail
+

No changes.

+
::grammar::me::tcl::iok_negate
+

No changes.

+
icf_jalways branchlabel
+
+
icf_jok branchlabel
+
+
icf_jfail branchlabel
+
+
icf_halt
+

These four instructions are not mapped to commands. They are control +flow instructions and handled in Tcl.

+
::grammar::me::tcl::icl_get
+

This command returns the current location CL in the input. +It replaces icl_push.

+
::grammar::me::tcl::icl_rewind oldlocation
+

The command takes the location as argument as it comes from the +Tcl stack, not the machine state.

+
icl_pop
+

Not mapped, the stacks are not managed by the package.

+
::grammar::me::tcl::ier_get
+

This command returns the current error state ER. +It replaces ier_push.

+
::grammar::me::tcl::ier_clear
+

No changes.

+
::grammar::me::tcl::ier_nonterminal message location
+

The command takes the location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::ier_merge olderror
+

The command takes the second error state to merge as argument as it +comes from the Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_clear
+

No changes.

+
::grammar::me::tcl::isv_terminal
+

No changes.

+
::grammar::me::tcl::isv_nonterminal_leaf nt startlocation
+

The command takes the start location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_nonterminal_range nt startlocation
+

The command takes the start location as argument as it comes from the +Tcl stack, not the machine state.

+
::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?
+

The command takes start location and marker as argument as it comes +from the Tcl stack, not the machine state.

+
::grammar::me::tcl::ias_push
+

No changes.

+
::grammar::me::tcl::ias_mark
+

This command returns a marker for the current state of the AST stack +AS. The marker stack is not managed by the machine.

+
::grammar::me::tcl::ias_pop2mark marker
+

The command takes the marker as argument as it comes from the +Tcl stack, not the machine state. It replaces ias_mpop.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_util.html Index: embedded/www/tcllib/files/modules/grammar_me/me_util.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_util.html +++ embedded/www/tcllib/files/modules/grammar_me/me_util.html @@ -0,0 +1,193 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me::util(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me::util - AST utilities

+
+ + +

Description

+

This package provides a number of utility command for the conversion +between the various representations of abstract syntax trees as +specified in the document grammar::me_ast.

+
+
::grammar::me::util::ast2tree ast tree ?root?
+

This command converts an ast from value to object +representation. All nodes in the ast will be converted into +nodes of this tree, with the root of the AST a child of the node +root. If this node is not explicitly specified the root of the +tree is used. Existing content of tree is not touched, i.e. neither +removed nor changed, with the exception of the specified root node, +which will gain a new child.

+
::grammar::me::util::ast2etree ast mcmd tree ?root?
+

This command is like ::grammar::me::util::ast2tree, except that +the result is in the extended object representation of the input AST. +The source of the extended information is the command prefix +mcmd. +It has to understand two methods, lc, and tok, with +the semantics specified below.

+
+
mcmd lc location
+

Takes the location of a token given as offset in the input stream and +return a 2-element list containing the associated line number and +column index, in this order.

+
mcmd tok from ?to?
+

Takes one or two locations from and to as offset in the +input stream and returns a Tcl list containing the specified part of +the input stream. Both location are inclusive. If to is not +specified it will default to the value of from.

+

Each element of the returned list is a list containing the token, its +associated lexeme, the line number, and column index, in this order.

+
+

Both the ensemble command ::grammar::me::tcl provided by the +package grammar::me::tcl and the objects command created by +the package ::grammar::me::cpu fit the above specification.

+
::grammar::me::util::tree2ast tree ?root?
+

This command converts an ast in (extended) object representation +into a value and returns it. +If a root node is specified the AST is generated from that node +downward. Otherwise the root of the tree object is used as the +starting point.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_me/me_vm.html Index: embedded/www/tcllib/files/modules/grammar_me/me_vm.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_me/me_vm.html +++ embedded/www/tcllib/files/modules/grammar_me/me_vm.html @@ -0,0 +1,543 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::me_vm - Virtual machine for parsing token streams

+
+ +

Description

+

Please go and read the document grammar::me_intro first for +an overview of the various documents and their relations.

+

This document specifies a virtual machine for the controlled matching +and parsing of token streams, creating an +abstract syntax tree (short AST) reflecting the +structure of the input. Special machine features are the caching and +reuse of partial results, caching of the encountered input, and the +ability to backtrack in both input and AST creation.

+

These features make the specified virtual machine especially useful to +packrat parsers based on parsing expression grammars. It is however +not restricted to this type of parser. Normal LL and LR parsers can be +implemented with it as well.

+

The following sections will discuss first the abstract state kept by +ME virtual machines, and then their instruction set.

+
+

MACHINE STATE

+

A ME virtual machine manages the following state:

+
+
Current token CT
+

The token from the input under consideration by the machine.

+

This information is used and modified by the instructions defined in +the section +TERMINAL MATCHING.

+
Current location CL
+

The location of the current token in the input stream, as +offset relative to the beginning of the stream. The first token is +considered to be at offset 0.

+

This information is implicitly used and modified by the instructions +defined in the sections +TERMINAL MATCHING and +NONTERMINAL MATCHING, +and can be directly queried and modified by the instructions defined +in section +INPUT LOCATION HANDLING.

+
Location stack LS
+

In addition to the above a stack of locations, for backtracking. +Locations can put on the stack, removed from it, and removed with +setting the current location.

+

This information is implicitly used and modified by the instructions +defined in the sections +TERMINAL MATCHING and +NONTERMINAL MATCHING, +and can be directly queried and modified by the instructions defined +in section +INPUT LOCATION HANDLING.

+
Match status OK
+

A boolean value, the result of the last attempt at matching input. +It is set to true if that attempt was successful, and +false otherwise.

+

This information is influenced by the instructions defined in the +sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +UNCONDITIONAL MATCHING. +It is queried by the instructions defined in the section +CONTROL FLOW.

+
Semantic value SV
+

The semantic value associated with (generated by) the last attempt at +matching input. Contains either the empty string or a node for the +abstract syntax tree constructed from the input.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
AST stack AS
+

A stack of partial abstract syntax trees constructed by the machine +during matching.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
AST Marker stack MS
+

In addition to the above a stack of stacks, for backtracking. This is +actually a stack of markers into the AST stack, thus implicitly +snapshooting the state of the AST stack at some point in time. Markers +can be put on the stack, dropped from it, and used to roll back the +AST stack to an earlier state.

+

This information is influenced by the instructions defined in the +sections +SEMANTIC VALUES, and +AST STACK HANDLING.

+
Error status ER
+

Error information associated with the last attempt at matching +input. Contains either the empty string or a list of 2 elements, a +location in the input and a list of error messages associated with +it, in this order.

+

Note that error information can be set even if the last attempt +at matching input was successful. For example the *-operator (matching +a sub-expression zero or more times) in a parsing expression grammar +is always successful, even if it encounters a problem further in the +input and has to backtrack. Such problems must not be forgotten when +continuing to match.

+

This information is queried and influenced by the instructions defined +in the sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +ERROR HANDLING.

+
Error stack ES
+

In addition to the above a stack of error information, to allow the +merging of current and older error information when performing +backtracking in choices after an unsucessful match.

+

This information is queried and influenced by the instructions defined +in the sections +TERMINAL MATCHING, +NONTERMINAL MATCHING, and +ERROR HANDLING.

+
Return stack RS
+

A stack of program counter values, i.e. locations in the code +controlling the virtual machine, for the management of subroutine +calls, i.e. the matching of nonterminal symbols.

+

This information is queried and influenced by the instructions defined +in the section +NONTERMINAL MATCHING.

+
Nonterminal cache NC
+

A cache of machine states (A 4-tuple containing a location in the +input, match status OK, semantic value SV, and error +status ER) keyed by name of nonterminal symbol and location in +the input stream.

+

The key location is where machine started the attempt to match the +named nonterminal symbol, and the location in the value is where +machine ended up after the attempt completed, independent of the +success of the attempt.

+

This status is queried and influenced by the instructions defined in +the section +NONTERMINAL MATCHING.

+
+
+

MACHINE INSTRUCTIONS

+

With the machine state specified it is now possible to explain the +instruction set of ME virtual machines. They are grouped roughly by +the machine state they influence and/or query.

+

TERMINAL MATCHING

+

First the instructions to match tokens from the input stream, and +by extension all terminal symbols.

+

These instructions are the only ones which may retrieve a new token +from the input stream. This is a may and not a will +because the instructions will a retrieve new token if, and only if the +current location CL is at the head of the stream. +If the machine has backtracked (see icl_rewind) the instructions +will retrieve the token to compare against from the internal cache.

+
+
ict_advance message
+

This instruction tries to advance to the next token in the input +stream, i.e. the one after the current location CL. The +instruction will fail if, and only if the end of the input stream is +reached, i.e. if there is no next token.

+

The sucess/failure of the instruction is remembered in the match +status OK. In the case of failure the error status ER is +set to the current location and the message message. +In the case of success the error status ER is cleared, the new +token is made the current token CT, and the new location is +made the current location CL.

+

The argument message is a reference to the string to put into +the error status ER, if such is needed.

+
ict_match_token tok message
+

This instruction tests the current token CT for equality +with the argument tok and records the result in the match +status OK. The instruction fails if the current token is +not equal to tok.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the +current location CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+
ict_match_tokrange tokbegin tokend message
+

This instruction tests the current token CT for being in +the range of tokens from tokbegin to tokend +(inclusive) and records the result in the match status OK. The +instruction fails if the current token is not inside the range.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the current location +CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+
ict_match_tokclass code message
+

This instruction tests the current token CT for being a member +of the token class code and records the result in the match +status OK. The instruction fails if the current token is not a +member of the specified class.

+

In case of failure the error status ER is set to the current +location CL and the message message, and the +current location CL is moved one token backwards. +Otherwise, i.e. upon success, the error status ER is cleared +and the current location CL is not touched.

+

Currently the following classes are legal:

+
+
alnum
+

A token is accepted if it is a unicode alphabetical character, or a digit.

+
alpha
+

A token is accepted if it is a unicode alphabetical character.

+
digit
+

A token is accepted if it is a unicode digit character.

+
xdigit
+

A token is accepted if it is a hexadecimal digit character.

+
punct
+

A token is accepted if it is a unicode punctuation character.

+
space
+

A token is accepted if it is a unicode space character.

+
+
+
+

NONTERMINAL MATCHING

+

The instructions in this section handle the matching of nonterminal +symbols. They query the nonterminal cache NC for saved +information, and put such information into the cache.

+

The usage of the cache is a performance aid for backtracking parsers, +allowing them to avoid an expensive rematch of complex nonterminal +symbols if they have been encountered before.

+
+
inc_restore branchlabel nt
+

This instruction checks if the nonterminal cache NC contains +information about the nonterminal symbol nt, at the current +location CL. If that is the case the instruction will update +the machine state (current location CL, match status OK, +semantic value SV, and error status ER) with the found +information and continue execution at the instruction refered to by +the branchlabel. The new current location CL will be the +last token matched by the nonterminal symbol, i.e. belonging to it.

+

If no information was found the instruction will continue execution at +the next instruction.

+

Together with icf_ntcall it is possible to generate code for +memoized and non-memoized matching of nonterminal symbols, either as +subroutine calls, or inlined in the caller.

+
inc_save nt
+

This instruction saves the current state of the machine (current +location CL, match status OK, semantic value SV, +and error status ER), to the nonterminal cache NC. It +will also pop an entry from the location stack LS and save it +as the start location of the match.

+

It is expected to be called at the end of matching a nonterminal +symbol, with nt the name of the nonterminal symbol the code was +working on. This allows the instruction inc_restore to check for +and retrieve the data, should we have to match this nonterminal symbol +at the same location again, during backtracking.

+
icf_ntcall branchlabel
+

This instruction invokes the code for matching the nonterminal symbol +nt as a subroutine. To this end it stores the current program +counter PC on the return stack RS, the current location +CL on the location stack LS, and then continues +execution at the address branchlabel.

+

The next matching icf_ntreturn will cause the execution to +continue at the instruction coming after the call.

+
icf_ntreturn
+

This instruction will pop an entry from the return stack RS, +assign it to the program counter PC, and then continue +execution at the new address.

+
+
+

UNCONDITIONAL MATCHING

+

The instructions in this section are the remaining match +operators. They change the match status OK directly and +unconditionally.

+
+
iok_ok
+

This instruction sets the match status OK to true, +indicating a successful match.

+
iok_fail
+

This instruction sets the match status OK to false, +indicating a failed match.

+
iok_negate
+

This instruction negates the match status OK, turning a failure +into a success and vice versa.

+
+
+

CONTROL FLOW

+

The instructions in this section implement both conditional and +unconditional control flow. The conditional jumps query the match +status OK.

+
+
icf_jalways branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel and then continues execution from +there. This is an unconditional jump.

+
icf_jok branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel. This happens if, and only if the match +status OK indicates a success. Otherwise it simply continues +execution at the next instruction. This is a conditional jump.

+
icf_jfail branchlabel
+

This instruction sets the program counter PC to the address +specified by branchlabel. This happens if, and only if the match +status OK indicates a failure. Otherwise it simply continues +execution at the next instruction. This is a conditional jump.

+
icf_halt
+

This instruction halts the machine and blocks any further execution.

+
+
+

INPUT LOCATION HANDLING

+

The instructions in this section are for backtracking, they manipulate +the current location CL of the machine state. +They allow a user of the machine to query and save locations in the +input, and to rewind the current location CL to saved +locations, making them one of the components enabling the +implementation of backtracking parsers.

+
+
icl_push
+

This instruction pushes a copy of the current location CL on +the location stack LS.

+
icl_rewind
+

This instruction pops an entry from the location stack LS and +then moves the current location CL back to this point in the +input.

+
icl_pop
+

This instruction pops an entry from the location stack LS and +discards it.

+
+
+

ERROR HANDLING

+

The instructions in this section provide read and write access to the +error status ER of the machine.

+
+
ier_push
+

This instruction pushes a copy of the current error status ER +on the error stack ES.

+
ier_clear
+

This instruction clears the error status ER.

+
ier_nonterminal message
+

This instruction checks if the error status ER contains an +error whose location is just past the location found in the top entry +of the location stack LS. +Nothing happens if no such error is found. +Otherwise the found error is replaced by an error at the location +found on the stack, having the message message.

+
ier_merge
+

This instruction pops an entry from the error stack ES, merges +it with the current error status ER and stores the result of +the merge as the new error status ER.

+

The merge is performed as described below:

+

If one of the two error states is empty the other is chosen. If +neither error state is empty, and refering to different locations, +then the error state with the location further in the input is +chosen. If both error states refer to the same location their messages +are merged (with removing duplicates).

+
+
+

SEMANTIC VALUES

+

The instructions in this section manipulate the semantic value +SV.

+
+
isv_clear
+

This instruction clears the semantic value SV.

+
isv_terminal
+

This instruction creates a terminal AST node for the current token +CT, makes it the semantic value SV, and also pushes the +node on the AST stack AS.

+
isv_nonterminal_leaf nt
+

This instruction creates a nonterminal AST node without any children +for the nonterminal nt, and makes it the semantic value +SV.

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
isv_nonterminal_range nt
+

This instruction creates a nonterminal AST node for the nonterminal +nt, with a single terminal node as its child, and makes this AST +the semantic value SV. The terminal node refers to the input +string from the location found on top of the location stack LS +to the current location CL (both inclusive).

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
isv_nonterminal_reduce nt
+

This instruction creates a nonterminal AST node for the nonterminal +nt and makes it the semantic value SV.

+

All entries on the AST stack AS above the marker found in the +top entry of the AST Marker stack MS become children of the new +node, with the entry at the stack top becoming the rightmost child. If +the AST Marker stack MS is empty the whole stack is used. The +AST marker stack MS is left unchanged.

+

This instruction should be executed if, and only if the match status +OK indicates a success. +In the case of a failure isv_clear should be called.

+
+
+

AST STACK HANDLING

+

The instructions in this section manipulate the AST stack AS, +and the AST Marker stack MS.

+
+
ias_push
+

This instruction pushes the semantic value SV on the AST stack +AS.

+
ias_mark
+

This instruction pushes a marker for the current state of the AST +stack AS on the AST Marker stack MS.

+
ias_mrewind
+

This instruction pops an entry from the AST Marker stack MS and +then proceeds to pop entries from the AST stack AS until the +state represented by the popped marker has been reached again. +Nothing is done if the AST stack AS is already smaller than +indicated by the popped marker.

+
ias_mpop
+

This instruction pops an entry from the AST Marker stack MS and +discards it.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_me of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_peg/peg.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_peg/peg.html +++ embedded/www/tcllib/files/modules/grammar_peg/peg.html @@ -0,0 +1,586 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::peg(n) 0.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::peg - Create and manipulate parsing expression grammars

+
+ + +

Description

+

This package provides a container class for +parsing expression grammars (Short: PEG). +It allows the incremental definition of the grammar, its manipulation +and querying of the definition. +The package neither provides complex operations on the grammar, nor has +it the ability to execute a grammar definition for a stream of symbols. +Two packages related to this one are grammar::mengine and +grammar::peg::interpreter. The first of them defines a +general virtual machine for the matching of a character stream, and +the second implements an interpreter for parsing expression grammars +on top of that virtual machine.

+

TERMS & CONCEPTS

+

PEGs are similar to context-free grammars, but not equivalent; in some +cases PEGs are strictly more powerful than context-free grammars (there +exist PEGs for some non-context-free languages). +The formal mathematical definition of parsing expressions and parsing +expression grammars can be found in section +PARSING EXPRESSION GRAMMARS.

+

In short, we have terminal symbols, which are the most basic +building blocks for sentences, and nonterminal symbols +with associated parsing expressions, defining the grammatical +structure of the sentences. The two sets of symbols are distinctive, +and do not overlap. When speaking about symbols the word "symbol" is +often left out. The union of the sets of terminal and nonterminal +symbols is called the set of symbols.

+

Here the set of terminal symbols is not explicitly managed, +but implicitly defined as the set of all characters. Note that this +means that we inherit from Tcl the ability to handle all of Unicode.

+

A pair of nonterminal and parsing expression is also +called a grammatical rule, or rule for short. In the +context of a rule the nonterminal is often called the left-hand-side +(LHS), and the parsing expression the right-hand-side (RHS).

+

The start expression of a grammar is a parsing expression +from which all the sentences contained in the language specified by +the grammar are derived. +To make the understanding of this term easier let us assume for a +moment that the RHS of each rule, and the start expression, is either +a sequence of symbols, or a series of alternate parsing expressions. +In the latter case the rule can be seen as a set of rules, each +providing one alternative for the nonterminal. +A parsing expression A' is now a derivation of a parsing expression A +if we pick one of the nonterminals N in the expression, and one of the +alternative rules R for N, and then replace the nonterminal in A with +the RHS of the chosen rule. Here we can see why the terminal symbols +are called such. They cannot be expanded any further, thus terminate +the process of deriving new expressions. +An example

+
+    Rules
+      (1)  A <- a B c
+      (2a) B <- d B
+      (2b) B <- e
+    Some derivations, using starting expression A.
+      A -/1/-> a B c -/2a/-> a d B c -/2b/-> a d e c
+
+

A derived expression containing only terminal symbols is a +sentence. The set of all sentences which can be derived from +the start expression is the language of the grammar.

+

Some definitions for nonterminals and expressions:

+
    +

  1. A nonterminal A is called reachable if it is possible to derive +a parsing expression from the start expression which contains A.

    2. +

  2. A nonterminal A is called useful if it is possible to derive a +sentence from it.

    3. +

  3. A nonterminal A is called recursive if it is possible to derive +a parsing expression from it which contains A, again.

    4. +

  4. The FIRST set of a nonterminal A contains all the symbols which +can occur of as the leftmost symbol in a parsing expression derived from +A. If the FIRST set contains A itself then that nonterminal is called +left-recursive.

    5. +

  5. The LAST set of a nonterminal A contains all the symbols which +can occur of as the rightmost symbol in a parsing expression derived from +A. If the LAST set contains A itself then that nonterminal is called +right-recursive.

    6. +

  6. The FOLLOW set of a nonterminal A contains all the symbols which +can occur after A in a parsing expression derived from the start +expression.

    7. +

  7. A nonterminal (or parsing expression) is called nullable if the +empty sentence can be derived from it.

    8. +
+

And based on the above definitions for grammars:

+
    +

  1. A grammar G is recursive if and only if it contains a nonterminal +A which is recursive. The terms left- and right-recursive, +and useful are analogously defined.

    2. +

  2. A grammar is minimal if it contains only reachable and +useful nonterminals.

    3. +

  3. A grammar is wellformed if it is not left-recursive. Such +grammars are also complete, which means that they always succeed +or fail on all input sentences. For an incomplete grammar on the +other hand input sentences exist for which an attempt to match them +against the grammar will not terminate.

    4. +

  4. As we wish to allow ourselves to build a grammar incrementally in a +container object we will encounter stages where the RHS of one or more +rules reference symbols which are not yet known to the container. Such +a grammar we call invalid. +We cannot use the term incomplete as this term is already +taken, see the last item.

    5. +
+
+

CONTAINER CLASS API

+

The package exports the API described here.

+
+
::grammar::peg pegName ?=|:=|<--|as|deserialize src?
+

The command creates a new container object for a parsing expression +grammar and returns the fully qualified name of the object command as +its result. The API the returned command is following is described in +the section CONTAINER OBJECT API. It may be used to invoke +various operations on the container and the grammar within.

+

The new container, i.e. grammar will be empty if no src is +specified. Otherwise it will contain a copy of the grammar contained +in the src. +The src has to be a container object reference for all operators +except deserialize. +The deserialize operator requires src to be the +serialization of a parsing expression grammar instead.

+

An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is valid, but not +useful.

+
+
+

CONTAINER OBJECT API

+

All grammar container objects provide the following methods for the +manipulation of their contents:

+
+
pegName destroy
+

Destroys the grammar, including its storage space and associated +command.

+
pegName clear
+

Clears out the definition of the grammar contained in pegName, +but does not destroy the object.

+
pegName = srcPEG
+

Assigns the contents of the grammar contained in srcPEG to +pegName, overwriting any existing definition. +This is the assignment operator for grammars. It copies the grammar +contained in the grammar object srcPEG over the grammar +definition in pegName. The old contents of pegName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    pegName deserialize [srcPEG serialize]
+
+
+
pegName --> dstPEG
+

This is the reverse assignment operator for grammars. It copies the +automation contained in the object pegName over the grammar +definition in the object dstPEG. +The old contents of dstPEG are deleted by this operation.

+

This operation is in effect equivalent to

+
+    dstPEG deserialize [pegName serialize]
+
+
+
pegName serialize
+

This method serializes the grammar stored in pegName. In other +words it returns a tcl value completely describing that +grammar. +This allows, for example, the transfer of grammars over arbitrary +channels, persistence, etc. +This method is also the basis for both the copy constructor and the +assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the grammar::peg interface. This is what +will enable us to copy grammars between different implementations of +the same interface.

+

The result is a list of four elements with the following structure:

+
    +

  1. The constant string grammar::peg.

    2. +

  2. A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values are the parsing expressions describing +their sentennial structure.

    3. +

  3. A dictionary. Its keys are the names of all known nonterminal symbols, +and their associated values hints to a matcher regarding the semantic +values produced by the symbol.

    4. +

  4. The last item is a parsing expression, the start expression +of the grammar.

    5. +
+

Assuming the following PEG for simple mathematical expressions

+
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'
+    Sign       <- '+' / '-'
+    Number     <- Sign? Digit+
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)
+    MulOp      <- '*' / '/'
+    Factor     <- Term (AddOp Term)*
+    AddOp      <- '+'/'-'
+    Term       <- Number
+
+

a possible serialization is

+
+    grammar::peg \\
+    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
+     Factor     {x Term {* {x AddOp Term}}} \\
+     Term       Number \\
+     MulOp      {/ * /} \\
+     AddOp      {/ + -} \\
+     Number     {x {? Sign} {+ Digit}} \\
+     Sign       {/ + -} \\
+     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
+    } \\
+    {Expression value     Factor     value \\
+     Term       value     MulOp      value \\
+     AddOp      value     Number     value \\
+     Sign       value     Digit      value \\
+    }
+    Expression
+
+

A possible one, because the order of the nonterminals in the +dictionary is not relevant.

+
pegName deserialize serialization
+

This is the complement to serialize. It replaces the grammar +definition in pegName with the grammar described by the +serialization value. The old contents of pegName are +deleted by this operation.

+
pegName is valid
+

A predicate. It tests whether the PEG in pegName is valid. +See section TERMS & CONCEPTS for the definition of this +grammar property. +The result is a boolean value. It will be set to true if +the PEG has the tested property, and false otherwise.

+
pegName start ?pe?
+

This method defines the start expression of the grammar. It +replaces the previously defined start expression with the parsing +expression pe. +The method fails and throws an error if pe does not contain a +valid parsing expression as specified in the section +PARSING EXPRESSIONS. In that case the existing start +expression is not changed. +The method returns the empty string as its result.

+

If the method is called without an argument it will return the currently +defined start expression.

+
pegName nonterminals
+

Returns the set of all nonterminal symbols known to the grammar.

+
pegName nonterminal add nt pe
+

This method adds the nonterminal nt and its associated parsing +expression pe to the set of nonterminal symbols and rules of the +PEG contained in the object pegName. +The method fails and throws an error if either the string nt is +already known as a symbol of the grammar, or if pe does not +contain a valid parsing expression as specified in the section +PARSING EXPRESSIONS. In that case the current set of +nonterminal symbols and rules is not changed. +The method returns the empty string as its result.

+
pegName nonterminal delete nt1 ?nt2 ...?
+

This method removes the named symbols nt1, nt2 from the +set of nonterminal symbols of the PEG contained in the object +pegName. +The method fails and throws an error if any of the strings is not +known as a nonterminal symbol. In that case the current set of +nonterminal symbols is not changed. +The method returns the empty string as its result.

+

The stored grammar becomes invalid if the deleted nonterminals are +referenced by the RHS of still-known rules.

+
pegName nonterminal exists nt
+

A predicate. It tests whether the nonterminal symbol nt is known +to the PEG in pegName. +The result is a boolean value. It will be set to true if the +symbol nt is known, and false otherwise.

+
pegName nonterminal rename nt ntnew
+

This method renames the nonterminal symbol nt to ntnew. +The method fails and throws an error if either nt is not known +as a nonterminal, or if ntnew is a known symbol. +The method returns the empty string as its result.

+
pegName nonterminal mode nt ?mode?
+

This mode returns or sets the semantic mode associated with the +nonterminal symbol nt. If no mode is specified the +current mode of the nonterminal is returned. Otherwise the current +mode is set to mode. +The method fails and throws an error if nt is not known as a +nonterminal. +The grammar interpreter implemented by the package +grammar::peg::interpreter recognizes the +following modes:

+
+
value
+

The semantic value of the nonterminal is the abstract syntax tree +created from the AST's of the RHS and a node for the nonterminal +itself.

+
match
+

The semantic value of the nonterminal is an the abstract syntax tree +consisting of single a node for the string matched by the RHS. The ASTs +generated by the RHS are discarded.

+
leaf
+

The semantic value of the nonterminal is an the abstract syntax tree +consisting of single a node for the nonterminal itself. The ASTs +generated by the RHS are discarded.

+
discard
+

The nonterminal has no semantic value. The ASTs generated by the RHS +are discarded (as well).

+
+
pegName nonterminal rule nt
+

This method returns the parsing expression associated with the +nonterminal nt. +The method fails and throws an error if nt is not known as a +nonterminal.

+
pegName unknown nonterminals
+

This method returns a list containing the names of all nonterminal +symbols which are referenced on the RHS of a grammatical rule, but +have no rule definining their structure. In other words, a list of +the nonterminal symbols which make the grammar invalid. The grammar +is valid if this list is empty.

+
+
+

PARSING EXPRESSIONS

+

Various methods of PEG container objects expect a parsing expression +as their argument, or will return such. This section specifies the +format such parsing expressions are in.

+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string alnum is an atomic parsing expression. It matches +any alphanumeric character.

    3. +

  3. The string alpha is an atomic parsing expression. It matches +any alphabetical character.

    4. +

  4. The string dot is an atomic parsing expression. It matches +any character.

    5. +

  5. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    6. +

  6. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    7. +

  7. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    8. +

  8. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    9. +

  9. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    10. +

  10. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    11. +

  11. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    12. +

  12. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    13. +

  13. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    14. +
+

Examples of parsing expressions where already shown, in the +description of the method serialize.

+
+
+

PARSING EXPRESSION GRAMMARS

+

For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where

+
    +

  • VN is a set of nonterminal symbols,

    • +

  • VT is a set of terminal symbols,

    • +

  • R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and e a parsing expression.

    • +

  • eS is a parsing expression, the start expression.

    • +
+

Further constraints are

+
    +

  • The intersection of VN and VT is empty.

    • +

  • For all A in VT exists exactly one pair (A,e) in R. In other words, R +is a function from nonterminal symbols to parsing expressions.

    • +
+

Parsing expression are inductively defined via

+
    +

  • The empty string (epsilon) is a parsing expression.

    • +

  • A terminal symbol a is a parsing expression.

    • +

  • A nonterminal symbol A is a parsing expression.

    • +

  • e1e2 is a parsing expression for parsing expressions +e1 and 2. This is called sequence.

    • +

  • e1/e2 is a parsing expression for parsing expressions +e1 and 2. This is called ordered choice.

    • +

  • e* is a parsing expression for parsing expression +e. This is called zero-or-more repetitions, also known +as kleene closure.

    • +

  • e+ is a parsing expression for parsing expression +e. This is called one-or-more repetitions, also known +as positive kleene closure.

    • +

  • !e is a parsing expression for parsing expression +e1. This is called a not lookahead predicate.

    • +

  • &e is a parsing expression for parsing expression +e1. This is called an and lookahead predicate.

    • +
+

PEGs are used to define a grammatical structure for streams of symbols +over VT. They are a modern phrasing of older formalisms invented by +Alexander Birham. These formalisms were called TS (TMG recognition +scheme), and gTS (generalized TS). Later they were renamed to TPDL +(Top-Down Parsing Languages) and gTPDL (generalized TPDL).

+

They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars.

+
+

REFERENCES

+
    +

  1. The Packrat Parsing and Parsing Expression Grammars Page, +by Bryan Ford, Massachusetts Institute of Technology. This is the main +entry page to PEGs, and their realization through Packrat Parsers.

    2. +

  2. Parsing Techniques - A Practical Guide , an online book +offering a clear, accessible, and thorough discussion of many +different parsing techniques with their interrelations and +applicabilities, including error recovery techniques.

    3. +

  3. Compilers and Compiler Generators, an online book using +CoCo/R, a generator for recursive descent parsers.

    4. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_peg of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html Index: embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html ================================================================== --- embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html +++ embedded/www/tcllib/files/modules/grammar_peg/peg_interp.html @@ -0,0 +1,206 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage"

+

Name

+

grammar::peg::interp - Interpreter for parsing expression grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require grammar::mengine ?0.1?
    • +
  • package require grammar::peg::interp ?0.1.1?
    • +
+ +
+
+

Description

+

This package provides commands for the controlled matching of a +character stream via a parsing expression grammar and the creation +of an abstract syntax tree for the stream and partials.

+

It is built on top of the virtual machine provided by the package +grammar::me::tcl and directly interprets the parsing +expression grammar given to it. +In other words, the grammar is not pre-compiled but used as is.

+

The grammar to be interpreted is taken from a container object +following the interface specified by the package +grammar::peg::container. Only the relevant parts +are copied into the state of this package.

+

It should be noted that the package provides exactly one instance +of the interpreter, and interpreting a second grammar requires +the user to either abort or complete a running interpretation, or +to put them into different Tcl interpreters.

+

Also of note is that the implementation assumes a pull-type +handling of the input. In other words, the interpreter pulls +characters from the input stream as it needs them. For usage +in a push environment, i.e. where the environment pushes new +characters as they come we have to put the engine into its +own thread.

+
+

THE INTERPRETER API

+

The package exports the following API

+
+
::grammar::peg::interp::setup peg
+

This command (re)initializes the interpreter. It returns the +empty string. This command has to be invoked first, before any +matching run.

+

Its argument peg is the handle of an object containing the +parsing expression grammar to interpret. This grammar has to be +valid, or an error will be thrown.

+
::grammar::peg::interp::parse nextcmd errorvar astvar
+

This command interprets the loaded grammar and tries to match it +against the stream of characters represented by the command prefix +nextcmd.

+

The command prefix nextcmd represents the input stream of +characters and is invoked by the interpreter whenever the a new +character from the stream is required. +The callback has to return either the empty list, or a list of 4 +elements containing the token, its lexeme attribute, and its location +as line number and column index, in this order. +The empty list is the signal that the end of the input stream has been +reached. The lexeme attribute is stored in the terminal cache, but +otherwise not used by the machine.

+

The result of the command is a boolean value indicating whether the +matching process was successful (true), or not +(false). In the case of a match failure error information will +be stored into the variable referenced by errorvar. The variable +referenced by astvar will always contain the generated abstract +syntax tree, however in the case of an error it will be only partial +and possibly malformed.

+

The abstract syntax tree is represented by a nested list, as +described in section AST VALUES of +document grammar::me_ast.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category grammar_peg of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Grammars and finite automata

+
+ +
ADDED embedded/www/tcllib/files/modules/hook/hook.html Index: embedded/www/tcllib/files/modules/hook/hook.html ================================================================== --- embedded/www/tcllib/files/modules/hook/hook.html +++ embedded/www/tcllib/files/modules/hook/hook.html @@ -0,0 +1,409 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

hook(n) 0.1 tcllib "Hooks"

+

Name

+

hook - Hooks

+
+ + +

Description

+

This package provides the hook ensemble command, which +implements the Subject/Observer pattern. It allows subjects, +which may be modules, objects, widgets, and so +forth, to synchronously call hooks which may be bound to an +arbitrary number of subscribers, called observers. A subject +may call any number of distinct hooks, and any number of observers can +bind callbacks to a particular hook called by a particular +subject. Hook bindings can be queried and deleted.

+

This man page is intended to be a reference only.

+
+

Concepts

+

Introduction

+

Tcl modules usually send notifications to other modules in two ways: +via Tk events, and via callback options like the text widget's +-yscrollcommand option. Tk events are available only in Tk, +and callback options require tight coupling between the modules +sending and receiving the notification.

+

Loose coupling between sender and receiver is often desirable, +however. In Model/View/Controller terms, a View can send a command +(stemming from user input) to the Controller, which updates the +Model. The Model can then call a hook to which all relevant +Views subscribe. The Model is decoupled from the Views, and indeed +need not know whether any Views actually exist. +At present, Tcl/Tk has no standard mechanism for implementing loose +coupling of this kind. This package defines a new command, hook, +which implements just such a mechanism.

+
+

Bindings

+

The hook command manages a collection of hook bindings. A hook +binding has four elements:

+
    +

  1. A subject: the name of the entity that will be calling the +hook.

    2. +

  2. The hook itself. A hook usually reflects some occurrence in the +life of the subject that other entities might care to know +about. A hook has a name, and may also have arguments. Hook +names are arbitrary strings. Each subject must document the +names and arguments of the hooks it can call.

    3. +

  3. The name of the observer that wishes to receive the hook +from the subject.

    4. +

  4. A command prefix to which the hook arguments will be appended +when the binding is executed.

    5. +
+
+

Subjects and observers

+

For convenience, this document collectively refers to subjects and +observers as objects, while placing no requirements on how +these objects are actually implemented. An object can be a +TclOO or Snit or XOTcl object, a Tcl +command, a namespace, a module, a pseudo-object managed by some other +object (as tags are managed by the Tk text widget) or simply a +well-known name.

+

Subject and observer names are arbitrary strings; however, as +hook might be used at the package level, it's necessary to have +conventions that avoid name collisions between packages written by +different people.

+

Therefore, any subject or observer name used in core or package level +code should look like a Tcl command name, and should be defined in a +namespace owned by the package. Consider, for example, an ensemble +command ::foo that creates a set of pseudo-objects and uses +hook to send notifications. The pseudo-objects have names +that are not commands and exist in their own namespace, rather like +file handles do. To avoid name collisions with subjects defined by +other packages, users of hook, these ::foo handles +should have names like ::foo::1, ::foo::2, and so on.

+

Because object names are arbitrary strings, application code can use +whatever additional conventions are dictated by the needs of the +application.

+
+
+

Reference

+

Hook provides the following commands:

+
+
hook bind ?subject? ?hook? ?observer? ?cmdPrefix?
+

This subcommand is used to create, update, delete, and query hook +bindings.

+

Called with no arguments it returns a list of the subjects with +hooks to which observers are currently bound.

+

Called with one argument, a subject, it returns a list of +the subject's hooks to which observers are currently bound.

+

Called with two arguments, a subject and a hook, it +returns a list of the observers which are currently bound to this +subject and hook.

+

Called with three arguments, a subject, a hook, and +an observer, it returns the binding proper, the command prefix +to be called when the hook is called, or the empty string if there is +no such binding.

+

Called with four arguments, it creates, updates, or deletes a +binding. If cmdPrefix is the empty string, it deletes any +existing binding for the subject, hook, and +observer; nothing is returned. Otherwise, cmdPrefix must +be a command prefix taking as many additional arguments as are +documented for the subject and hook. The binding is added +or updated, and the observer is returned.

+

If the observer is the empty string, "", it will create a +new binding using an automatically generated observer name of the form +::hook::ob<number>. The automatically generated name +will be returned, and can be used to query, update, and delete the +binding as usual. If automated observer names are always used, the +observer name effectively becomes a unique binding ID.

+

It is possible to call hook bind to create or delete a +binding to a subject and hook while in an observer binding +for that same subject and hook. The following rules +determine what happens when

+
+    hook bind $s $h $o $binding
+
+

is called during the execution of

+
+    hook call $s $h
+
+
    +

  1. No binding is ever called after it is deleted.

    2. +

  2. When a binding is called, the most recently given command prefix is +always used.

    3. +

  3. The set of observers whose bindings are to be called is determined +when this method begins to execute, and does not change thereafter, +except that deleted bindings are not called.

    4. +
+

In particular:

+
    +

  1. If $os binding to $s and $h is deleted, and +$os binding has not yet been called during this execution of

    +
    +    hook call $s $h
+
    +

    it will not be called. (Note that it might already have been called; +and in all likelihood, it is probably deleting itself.)

    2. +

  2. If $o changes the command prefix that's bound to $s and +$h, and if $os binding has not yet been called during +this execution of

    +
    +    hook call $s $h
+
    +

    the new binding will be called when the time comes. (But again, it is +probably $os binding that is is making the change.)

    3. +

  3. If a new observer is bound to $s and $h, its binding will +not be called until the next invocation of

    +
    +    hook call $s $h
+
    +
    4. +
+
hook call subject hook ?args...?
+

This command is called when the named subject wishes to call the +named hook. All relevant bindings are called with the specified +arguments in the global namespace. Note that the bindings are called +synchronously, before the command returns; this allows the args +to include references to entities that will be cleaned up as soon as +the hook has been called.

+

The order in which the bindings are called is not guaranteed. If +sequence among observers must be preserved, define one observer and +have its bindings call the other callbacks directly in the proper +sequence.

+

Because the hook mechanism is intended to support loose +coupling, it is presumed that the subject has no knowledge of +the observers, nor any expectation regarding return values. This has a +number of implications:

+
    +

  1. hook call returns the empty string.

    2. +

  2. Normal return values from observer bindings are ignored.

    3. +

  3. Errors and other exceptional returns propagate normally by +default. This will rarely be what is wanted, because the subjects +usually have no knowledge of the observers and will therefore have no +particular competence at handling their errors. That makes it an +application issue, and so applications will usually want to define an +-errorcommand.

    4. +
+

If the -errorcommand configuration option has a non-empty +value, its value will be invoked for all errors and other exceptional +returns in observer bindings. See hook configure, below, for +more information on configuration options.

+
hook forget object
+

This command deletes any existing bindings in which the named +object appears as either the subject or the +observer. +Bindings deleted by this method will never be called again. In +particular,

+
    +

  1. If an observer is forgotten during a call to hook call, any +uncalled binding it might have had to the relevant subject and hook +will not be called subsequently.

    2. +

  2. If a subject $s is forgotten during a call to

    +
    hook call $s $h
    +

    then hook call will return as soon as the current binding +returns. No further bindings will be called.

    3. +
+
hook cget option
+

This command returns the value of one of the hook command's +configuration options.

+
hook configure option value ...
+

This command sets the value of one or more of the hook command's +configuration options:

+
+
-errorcommand cmdPrefix
+

If the value of this option is the empty string, "", then errors +and other exception returns in binding scripts are propagated +normally. Otherwise, it must be a command prefix taking three +additional arguments:

+
    +

  1. a 4-element list {subject hook arglist observer},

    2. +

  2. the result string, and

    3. +

  3. the return options dictionary.

    4. +
+

Given this information, the -errorcommand can choose to log +the error, call interp bgerror, delete the errant binding +(thus preventing the error from arising a second time) and so forth.

+
-tracecommand cmdPrefix
+

The option's value should be a command prefix taking four +arguments:

+
    +

  1. a subject,

    2. +

  2. a hook,

    3. +

  3. a list of the hook's argument values, and

    4. +

  4. a list of objects the hook was called for.

    5. +
+

The command will be called for each hook that is called. This allows +the application to trace hook execution for debugging purposes.

+
+
+
+

Example

+

The ::model module calls the <Update> hook in response to +commands that change the model's data:

+
+     hook call ::model <Update>
+
+

The .view megawidget displays the model state, and needs to +know about model updates. Consequently, it subscribes to the ::model's +<Update> hook.

+
+     hook bind ::model <Update> .view [list .view ModelUpdate]
+
+

When the ::model calls the hook, the .views +ModelUpdate subcommand will be called.

+

Later the .view megawidget is destroyed. In its destructor, +it tells the hook that it no longer exists:

+
+     hook forget .view
+
+

All bindings involving .view are deleted.

+
+

Credits

+

Hook has been designed and implemented by William H. Duquette.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category hook of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/html/html.html Index: embedded/www/tcllib/files/modules/html/html.html ================================================================== --- embedded/www/tcllib/files/modules/html/html.html +++ embedded/www/tcllib/files/modules/html/html.html @@ -0,0 +1,506 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

html(n) 1.4.4 tcllib "HTML Generation"

+

Name

+

html - Procedures to generate HTML structures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require html ?1.4.4?
    • +
+ +
+
+

Description

+

The package html provides commands that generate HTML. +These commands typically return an HTML string as their result. In +particular, they do not output their result to stdout.

+

The command ::html::init should be called early to initialize +the module. You can also use this procedure to define default values +for HTML tag parameters.

+
+
::html::author author
+

Side effect only. Call this before ::html::head to +define an author for the page. The author is noted in a comment in +the HEAD section.

+
::html::bodyTag args
+

Generate a body tag. The tag parameters are taken from args or +from the body.* attributes define with ::html::init.

+
::html::cell param value ?tag?
+

Generate a td (or th) tag, a value, and a closing +td (or th) tag. The +tag parameters come from param or TD.* attributes defined with +::html::init. This uses ::html::font to insert a standard +font tag into the table cell. The tag argument defaults to "td".

+
::html::checkbox name value
+

Generate a checkbox form element with the specified name and value. +This uses ::html::checkValue.

+
::html::checkSet key sep list
+

Generate a set of checkbox form elements and associated labels. The +list should contain an alternating list of labels and values. +This uses ::html::checkbox. All the checkbox buttons share the +same key for their name. The sep is text used to separate +the elements.

+
::html::checkValue name ?value?
+

Generate the "name=name value=value" for a checkbox form +element. If the CGI variable name has the value value, +then SELECTED is added to the return value. value defaults to +"1".

+
::html::closeTag
+

Pop a tag off the stack created by ::html::openTag and generate +the corresponding close tag (e.g., </body>).

+
::html::default key ?param?
+

This procedure is used by ::html::tagParam to generate the name, +value list of parameters for a tag. The ::html::default +procedure is used to generate default values for those items not +already in param. If the value identified by key matches +a value in param then this procedure returns the empty string. +Otherwise, it returns a "parameter=value" string for a form element +identified by key. The key has the form "tag.parameter" +(e.g., body.bgcolor). Use ::html::init to register default +values. param defaults to the empty string.

+
::html::description description
+

Side effect only. Call this before ::html::head to +define a description meta tag for the page. This tag is generated +later in the call to ::html::head.

+
::html::end
+

Pop all open tags from the stack and generate the corresponding close +HTML tags, (e.g., </body></html>).

+
::html::eval arg ?args?
+

This procedure is similar to the built-in Tcl eval command. The +only difference is that it returns "" so it can be called from an HTML +template file without appending unwanted results.

+
::html::extractParam param key ?varName?
+

This is a parsing procedure that extracts the value of key from +param, which is a HTML-style "name=quotedvalue" list. +varName is used as the name of a Tcl variable that is changed to +have the value found in the parameters. The function returns 1 if the +parameter was found in param, otherwise it returns 0. If the +varName is not specified, then key is used as the variable +name.

+
::html::font args
+

Generate a standard font tag. The parameters to the tag are taken +from args and the HTML defaults defined with ::html::init.

+
::html::for start test next body
+

This procedure is similar to the built-in Tcl for control +structure. Rather than evaluating the body, it returns the subst'ed +body. Each iteration of the loop causes another string to be +concatenated to the result value.

+
::html::foreach varlist1 list1 ?varlist2 list2 ...? body
+

This procedure is similar to the built-in Tcl foreach control +structure. Rather than evaluating the body, it returns the subst'ed +body. Each iteration of the loop causes another string to be +concatenated to the result value.

+
::html::formValue name ?defvalue?
+

Return a name and value pair, where the value is initialized from +existing CGI data, if any. The result has this form:

+
+  name="fred" value="freds value"
+
+
+
::html::getFormInfo args
+

Generate hidden fields to capture form values. If args is +empty, then hidden fields are generated for all CGI values. Otherwise +args is a list of string match patterns for form element names.

+
::html::getTitle
+

Return the title string, with out the surrounding title tag, +set with a previous call to ::html::title.

+
::html::h level string ?param?
+

Generate a heading (e.g., hlevel) tag. The string is nested in the +heading, and param is used for the tag parameters.

+
::html::h1 string ?param?
+

Generate an h1 tag. See ::html::h.

+
::html::h2 string ?param?
+

Generate an h2 tag. See ::html::h.

+
::html::h3 string ?param?
+

Generate an h3 tag. See ::html::h.

+
::html::h4 string ?param?
+

Generate an h4 tag. See ::html::h.

+
::html::h5 string ?param?
+

Generate an h5 tag. See ::html::h.

+
::html::h6 string ?param?
+

Generate an h6 tag. See ::html::h.

+
::html::hdrRow args
+

Generate a table row, including tr and th tags. +Each value in args is place into its own table cell. +This uses ::html::cell.

+
::html::head title
+

Generate the head section that includes the page title. +If previous calls have been made to +::html::author, +::html::keywords, +::html::description, +or +::html::meta +then additional tags are inserted into the head section. +This leaves an open html tag pushed on the stack with +::html::openTag.

+
::html::headTag string
+

Save a tag for inclusion in the head section generated by +::html::head. The string is everything in the tag except +the enclosing angle brackets, < >.

+
::html::html_entities string
+

This command replaces all special characters in the string with +their HTML entities and returns the modified text.

+
::html::if expr1 body1 ?elseif expr2 body2 ...? ?else bodyN?
+

This procedure is similar to the built-in Tcl if control +structure. Rather than evaluating the body of the branch that is +taken, it returns the subst'ed body. Note that the syntax is +slightly more restrictive than that of the built-in Tcl if +control structure.

+
::html::init ?list?
+

::html::init accepts a Tcl-style name-value list that defines +values for items with a name of the form "tag.parameter". For +example, a default with key "body.bgcolor" defines the background +color for the body tag.

+
::html::keywords args
+

Side effect only. Call this before ::html::head to +define a keyword meta tag for the page. The meta tag +is included in the result of ::html::head.

+
::html::mailto email ?subject?
+

Generate a hypertext link to a mailto: URL.

+
::html::meta args
+

Side effect only. Call this before ::html::head to +define a meta tag for the page. The args is a Tcl-style name, +value list that is used for the name= and value= parameters for the +meta tag. The meta tag is included in the result of +::html::head.

+
::html::css href
+

Side effect only. Call this before ::html::head to +define a link tag for a linked CSS document. The href +value is a HTTP URL to a CSS document. The link tag is included +in the result of ::html::head.

+

Multiple calls of this command are allowed, enabling the use of +multiple CSS document references. In other words, the arguments +of multiple calls are accumulated, and do not overwrite each other.

+
::html::css-clear
+

Side effect only. Call this before ::html::head to +clear all links to CSS documents.

+

Multiple calls of this command are allowed, doing nothing after the +first of a sequence with no intervening ::html::css.

+
::html::js href
+

Side effect only. Call this before ::html::head to +define a script tag for a linked JavaScript document. The +href is a HTTP URL to a JavaScript document. The script +tag is included in the result of ::html::head.

+

Multiple calls of this command are allowed, enabling the use of +multiple JavaScript document references. In other words, the arguments +of multiple calls are accumulated, and do not overwrite each other.

+
::html::js-clear
+

Side effect only. Call this before ::html::head to +clear all links to JavaScript documents.

+

Multiple calls of this command are allowed, doing nothing after the +first of a sequence with no intervening ::html::js.

+
::html::minorList list ?ordered?
+

Generate an ordered or unordered list of links. The list is a +Tcl-style name, value list of labels and urls for the links. +ordered is a boolean used to choose between an ordered or +unordered list. It defaults to false.

+
::html::minorMenu list ?sep?
+

Generate a series of hypertext links. The list is a Tcl-style +name, value list of labels and urls for the links. The sep is +the text to put between each link. It defaults to " | ".

+
::html::nl2br string
+

This command replaces all line-endings in the string with a +br tag and returns the modified text.

+
::html::openTag tag ?param?
+

Push tag onto a stack and generate the opening tag for +tag. Use ::html::closeTag to pop the tag from the +stack. The second argument provides any tag arguments, as a +list whose elements are formatted to be in the form +"key=value".

+
::html::paramRow list ?rparam? ?cparam?
+

Generate a table row, including tr and td tags. Each value in +list is placed into its own table cell. This uses +::html::cell. The value of rparam is used as parameter for +the tr tag. The value of cparam is passed to ::html::cell +as parameter for the td tags.

+
::html::passwordInput ?name?
+

Generate an input tag of type password. The name defaults to +"password".

+
::html::passwordInputRow label ?name?
+

Format a table row containing a label and an input tag of type +password. The name defaults to "password".

+
::html::quoteFormValue value
+

Quote special characters in value by replacing them with HTML +entities for quotes, ampersand, and angle brackets.

+
::html::radioSet key sep list
+

Generate a set of input tags of type radio and an associated text +label. All the radio buttons share the same key for their name. +The sep is text used to separate the elements. The list +is a Tcl-style label, value list.

+
::html::radioValue name value
+

Generate the "name=name value=value" for a radio form +element. If the CGI variable name has the value value, +then SELECTED is added to the return value.

+
::html::refresh seconds url
+

Set up a refresh meta tag. Call this before ::html::head and the +HEAD section will contain a meta tag that causes the document to +refresh in seconds seconds. The url is optional. If +specified, it specifies a new page to load after the refresh interval.

+
::html::row args
+

Generate a table row, including tr and td tags. Each value in +args is place into its own table cell. This uses +::html::cell. Ignores any default information set up via +::html::init.

+
::html::select name param choices ?current?
+

Generate a select form element and nested option tags. The name +and param are used to generate the select tag. The choices +list is a Tcl-style name, value list.

+
::html::selectPlain name param choices ?current?
+

Like ::html::select except that choices is a Tcl list of +values used for the option tags. The label and the value for each +option are the same.

+
::html::set var val
+

This procedure is similar to the built-in Tcl set command. The +main difference is that it returns "" so it can be called from an HTML +template file without appending unwanted results. The other +difference is that it must take two arguments.

+
::html::submit label ?name?
+

Generate an input tag of type submit. name defaults to "submit".

+
::html::tableFromArray arrname ?param? ?pat?
+

Generate a two-column table and nested rows to display a Tcl array. The +table gets a heading that matches the array name, and each generated row +contains a name, value pair. The array names are sorted (lsort without +special options). The argument param is for the table tag and has +to contain a pre-formatted string. The pat is a string match +pattern used to select the array elements to show in the table. It defaults to +*, i.e. the whole array is shown.

+
::html::tableFromList querylist ?param?
+

Generate a two-column table and nested rows to display querylist, +which is a Tcl dictionary. Each generated row contains a name, value pair. The +information is shown in the same order as specified in the dictionary. The +argument param is for the table tag and has to contain a +pre-formatted string.

+
::html::textarea name ?param? ?current?
+

Generate a textarea tag wrapped around its current values.

+
::html::textInput name value args
+

Generate an input form tag with type text. This uses +::html::formValue. The args is any additional tag attributes +you want to put into the input tag.

+
::html::textInputRow label name value args
+

Generate an input form tag with type text formatted into a table row +with an associated label. The args is any additional tag attributes +you want to put into the input tag.

+
::html::varEmpty name
+

This returns 1 if the named variable either does not exist or has the +empty string for its value.

+
::html::while test body
+

This procedure is similar to the built-in Tcl while control +structure. Rather than evaluating the body, it returns the subst'ed +body. Each iteration of the loop causes another string to be +concatenated to the result value.

+
::html::doctype id
+

This procedure can be used to build the standard DOCTYPE +declaration string. It will return the standard declaration +string for the id, or throw an error if the id is not known. +The following id's are defined:

+
    +

  1. HTML32

    2. +

  2. HTML40

    3. +

  3. HTML40T

    4. +

  4. HTML40F

    5. +

  5. HTML401

    6. +

  6. HTML401T

    7. +

  7. HTML401F

    8. +

  8. XHTML10S

    9. +

  9. XHTML10T

    10. +

  10. XHTML10F

    11. +

  11. XHTML11

    12. +

  12. XHTMLB

    13. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category html of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/htmlparse/htmlparse.html Index: embedded/www/tcllib/files/modules/htmlparse/htmlparse.html ================================================================== --- embedded/www/tcllib/files/modules/htmlparse/htmlparse.html +++ embedded/www/tcllib/files/modules/htmlparse/htmlparse.html @@ -0,0 +1,314 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

htmlparse(n) 1.2.2 tcllib "HTML Parser"

+

Name

+

htmlparse - Procedures to parse HTML strings

+
+ + +

Description

+

The htmlparse package provides commands that allow libraries +and applications to parse HTML in a string into a representation of +their choice.

+

The following commands are available:

+
+
::htmlparse::parse ?-cmd cmd? ?-vroot tag? ?-split n? ?-incvar var? ?-queue q? html
+

This command is the basic parser for HTML. It takes an HTML string, +parses it and invokes a command prefix for every tag encountered. It +is not necessary for the HTML to be valid for this parser to +function. It is the responsibility of the command invoked for every +tag to check this. Another responsibility of the invoked command is +the handling of tag attributes and character entities (escaped +characters). The parser provides the un-interpreted tag attributes to +the invoked command to aid in the former, and the package at large +provides a helper command, ::htmlparse::mapEscapes, to aid in +the handling of the latter. The parser does ignore leading +DOCTYPE declarations and all valid HTML comments it encounters.

+

All information beyond the HTML string itself is specified via +options, these are explained below.

+

To help understand the options, some more background information about +the parser.

+

It is capable of detecting incomplete tags in the HTML string given to +it. Under normal circumstances this will cause the parser to throw an +error, but if the option -incvar is used to specify a global (or +namespace) variable, the parser will store the incomplete part of the +input into this variable instead. This will aid greatly in the +handling of incrementally arriving HTML, as the parser will handle +whatever it can and defer the handling of the incomplete part until +more data has arrived.

+

Another feature of the parser are its two possible modes of +operation. The normal mode is activated if the option -queue is +not present on the command line invoking the parser. If it is present, +the parser will go into the incremental mode instead.

+

The main difference is that a parser in normal mode will immediately +invoke the command prefix for each tag it encounters. In incremental +mode however the parser will generate a number of scripts which invoke +the command prefix for groups of tags in the HTML string and then +store these scripts in the specified queue. It is then the +responsibility of the caller of the parser to ensure the execution of +the scripts in the queue.

+

Note: The queue object given to the parser has to provide the +same interface as the queue defined in tcllib -> struct. This means, +for example, that all queues created via that tcllib module can be +immediately used here. Still, the queue doesn't have to come from +tcllib -> struct as long as the same interface is provided.

+

In both modes the parser will return an empty string to the caller.

+

The -split option may be given to a parser in incremental mode to +specify the size of the groups it creates. In other words, -split 5 +means that each of the generated scripts will invoke the command +prefix for 5 consecutive tags in the HTML string. A parser in normal +mode will ignore this option and its value.

+

The option -vroot specifies a virtual root tag. A parser in +normal mode will invoke the command prefix for it immediately before +and after it processes the tags in the HTML, thus simulating that the +HTML string is enclosed in a <vroot> </vroot> combination. In +incremental mode however the parser is unable to provide the closing +virtual root as it never knows when the input is complete. In this +case the first script generated by each invocation of the parser will +contain an invocation of the command prefix for the virtual root as +its first command. +The following options are available:

+
+
-cmd cmd
+

The command prefix to invoke for every tag in the HTML +string. Defaults to ::htmlparse::debugCallback.

+
-vroot tag
+

The virtual root tag to add around the HTML in normal mode. In +incremental mode it is the first tag in each chunk processed by the +parser, but there will be no closing tags. Defaults to +hmstart.

+
-split n
+

The size of the groups produced by an incremental mode parser. Ignored +when in normal mode. Defaults to 10. Values <= 0 are not allowed.

+
-incvar var
+

The name of the variable where to store any incomplete HTML into. This +makes most sense for the incremental mode. The parser will throw an +error if it sees incomplete HTML and has no place to store it to. This +makes sense for the normal mode. Only incomplete tags are detected, +not missing tags. Optional, defaults to 'no variable'.

+
+
+
Interface to the command prefix
+

In normal mode the parser will invoke the command prefix with four +arguments appended. See ::htmlparse::debugCallback for a +description.

+

In incremental mode, however, the generated scripts will invoke the +command prefix with five arguments appended. The last four of these +are the same which were mentioned above. The first is a placeholder +string (@win@) for a clientdata value to be supplied later +during the actual execution of the generated scripts. This could be a +tk window path, for example. This allows the user of this package to +preprocess HTML strings without committing them to a specific window, +object, whatever during parsing. This connection can be made +later. This also means that it is possible to cache preprocessed +HTML. Of course, nothing prevents the user of the parser from +replacing the placeholder with an empty string.

+
+
::htmlparse::debugCallback ?clientdata? tag slash param textBehindTheTag
+

This command is the standard callback used by the parser in +::htmlparse::parse if none was specified by the user. It simply +dumps its arguments to stdout. This callback can be used for both +normal and incremental mode of the calling parser. In other words, it +accepts four or five arguments. The last four arguments are described +below. The optional fifth argument contains the clientdata value +passed to the callback by a parser in incremental mode. All callbacks +have to follow the signature of this command in the last four +arguments, and callbacks used in incremental parsing have to follow +this signature in the last five arguments.

+

The first argument, clientdata, is optional and present only if +this command is invoked by a parser in incremental mode. It contains +whatever the user of this package wishes.

+

The second argument, tag, contains the name of the tag which is +currently processed by the parser.

+

The third argument, slash, is either empty or contains a slash +character. It allows the callback to distinguish between opening +(slash is empty) and closing tags (slash contains a slash character).

+

The fourth argument, param, contains the un-interpreted list of +parameters to the tag.

+

The fifth and last argument, textBehindTheTag, contains the text +found by the parser behind the tag named in tag.

+
::htmlparse::mapEscapes html
+

This command takes a HTML string, substitutes all escape sequences +with their actual characters and then returns the resulting string. +HTML strings which do not contain escape sequences are returned +unchanged.

+
::htmlparse::2tree html tree
+

This command is a wrapper around ::htmlparse::parse which takes +an HTML string (in html) and converts it into a tree containing +the logical structure of the parsed document. The name of the tree is +given to the command as its second argument (tree). The command +does not generate the tree by itself but expects that the caller +provided it with an existing and empty tree. It also expects that the +specified tree object follows the same interface as the tree object in +tcllib -> struct. It doesn't have to be from tcllib -> struct, but it +must provide the same interface.

+

The internal callback does some basic checking of HTML validity and +tries to recover from the most basic errors. The command returns the +contents of its second argument. Side effects are the creation and +manipulation of a tree object.

+

Each node in the generated tree represent one tag in the input. The +name of the tag is stored in the attribute type of the +node. Any html attributes coming with the tag are stored unmodified in +the attribute data of the tag. In other words, the command does +not parse html attributes into their names and values.

+

If a tag contains text its node will have children of type +PCDATA containing this text. The text will be stored in the +attribute data of these children.

+
::htmlparse::removeVisualFluff tree
+

This command walks a tree as generated by ::htmlparse::2tree and +removes all the nodes which represent visual tags and not structural +ones. The purpose of the command is to make the tree easier to +navigate without getting bogged down in visual information not +relevant to the search. Its only argument is the name of the tree to +cut down.

+
::htmlparse::removeFormDefs tree
+

Like ::htmlparse::removeVisualFluff this command is here to cut +down on the size of the tree as generated by +::htmlparse::2tree. It removes all nodes representing forms and +form elements. Its only argument is the name of the tree to cut down.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category htmlparse of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/http/autoproxy.html Index: embedded/www/tcllib/files/modules/http/autoproxy.html ================================================================== --- embedded/www/tcllib/files/modules/http/autoproxy.html +++ embedded/www/tcllib/files/modules/http/autoproxy.html @@ -0,0 +1,319 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

autoproxy(n) 1.5.3 tcllib "HTTP protocol helper modules"

+

Name

+

autoproxy - Automatic HTTP proxy usage and authentication

+
+ + +

Description

+

This package attempts to automate the use of HTTP proxy servers in Tcl +HTTP client code. It tries to initialize the web access settings from +system standard locations and can be configured to negotiate +authentication with the proxy if required.

+

On Unix the standard for identifying the local HTTP proxy server +seems to be to use the environment variable http_proxy or ftp_proxy and +no_proxy to list those domains to be excluded from proxying. +On Windows we can retrieve the Internet Settings values from the registry +to obtain pretty much the same information. +With this information we can setup a suitable filter procedure for the +Tcl http package and arrange for automatic use of the proxy.

+

There seem to be a number of ways that the http_proxy environment +variable may be set up. Either a plain host:port or more commonly a +URL and sometimes the URL may contain authentication parameters or +these may be requested from the user or provided via http_proxy_user +and http_proxy_pass. This package attempts to deal with all these +schemes. It will do it's best to get the required parameters from the +environment or registry and if it fails can be reconfigured.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

COMMANDS

+
+
::autoproxy::init
+

Initialize the autoproxy package from system resources. Under unix +this means we look for environment variables. Under windows we look +for the same environment variables but also look at the registry +settings used by Internet Explorer.

+
::autoproxy::cget -option
+

Retrieve individual package configuration options. See OPTIONS.

+
::autoproxy::configure ?-option value?
+

Configure the autoproxy package. Calling configure with no +options will return a list of all option names and values. +See OPTIONS.

+
::autoproxy::tls_connect args
+

Connect to a secure socket through a proxy. HTTP proxy servers permit +the use of the CONNECT HTTP command to open a link through the proxy +to the target machine. This function hides the details. For use with +the http package see tls_socket.

+

The args list may contain any of the tls package options but +must end with the host and port as the last two items.

+
::autoproxy::tunnel_connect args
+

Connect to a target host throught a proxy. This uses the same CONNECT +HTTP command as the tls_connect but does not promote the link +security once the connection is established.

+

The args list may contain any of the tls package options but +must end with the host and port as the last two items.

+

Note that many proxy servers will permit CONNECT calls to a limited +set of ports - typically only port 443 (the secure HTTP port).

+
::autoproxy::tls_socket args
+

This function is to be used to register a proxy-aware secure socket +handler for the https protocol. It may only be used with the Tcl http +package and should be registered using the http::register command (see +the examples below). The job of actually creating the tunnelled +connection is done by the tls_connect command and this may be used +when not registering with the http package.

+
+
+

OPTIONS

+
+
-host hostname
+
+
-proxy_host hostname
+

Set the proxy hostname. This is normally set up by init but may +be configured here as well.

+
-port number
+
+
-proxy_port number
+

Set the proxy port number. This is normally set up by init. +e.g. configure -port 3128

+
-no_proxy list
+

You may manipulate the no_proxy list that was setup by +init. The value of this option is a tcl list of +strings that are matched against the http request host using the tcl +string match command. Therefore glob patterns are permitted. +For instance, configure -no_proxy *.localdomain

+
-authProc procedure
+

This option may be used to set an application defined procedure to be +called when configure -basic is called with either no or +insufficient authentication details. This can be used to present a +dialog to the user to request the additional information.

+
-basic
+

Following options are for configuring the Basic authentication +scheme parameters. See Basic Authentication.

+
+
+

Basic Authentication

+

Basic is the simplest and most commonly use HTTP proxy authentication +scheme. It is described in (1 section 11) and also in (2). It offers +no privacy whatsoever and its use should be discouraged in favour of +more secure alternatives like Digest. To perform Basic authentication +the client base64 encodes the username and plaintext password +separated by a colon. This encoded text is prefixed with the word +"Basic" and a space.

+

The following options exists for this scheme:

+
+
-username name
+

The username required to authenticate with the configured proxy.

+
-password password
+

The password required for the username specified.

+
-realm realm
+

This option is not used.

+
+
+

EXAMPLES

+
+package require autoproxy
+autoproxy::init
+autoproxy::configure -basic -username ME -password SEKRET
+set tok [http::geturl http://wiki.tcl.tk/]
+http::data $tok
+
+
+package require http
+package require tls
+package require autoproxy
+autoproxy::init
+http::register https 443 autoproxy::tls_socket
+set tok [http::geturl https://www.example.com/]
+
+
+

REFERENCES

+
    +

  1. Berners-Lee, T., Fielding R. and Frystyk, H. + "Hypertext Transfer Protocol -- HTTP/1.0", + RFC 1945, May 1996, + (http://www.rfc-editor.org/rfc/rfc1945.txt)

    2. +

  2. Franks, J. et al. + "HTTP Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999 + (http://www.rfc-editor.org/rfc/rfc2617.txt)

    3. +
+
+

BUGS

+

At this time only Basic authentication (1) (2) is supported. It is +planned to add support for Digest (2) and NTLM in the future.

+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category http :: autoproxy of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

http(n)

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ident/ident.html Index: embedded/www/tcllib/files/modules/ident/ident.html ================================================================== --- embedded/www/tcllib/files/modules/ident/ident.html +++ embedded/www/tcllib/files/modules/ident/ident.html @@ -0,0 +1,173 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ident(n) 0.42 tcllib "Identification protocol client"

+

Name

+

ident - Ident protocol client

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require ident ?0.42?
    • +
+ +
+
+

Description

+

The ident package provides a client implementation of the ident +protocol as defined in +RFC 1413 (http://www.rfc-editor.org/rfc/rfc1413.txt).

+
+
::ident::query socket ?callback?
+

This command queries the ident daemon on the remote side of the given +socket, and returns the result of the query as a dictionary. +Interpreting the dictionary as list the first key will always be +resp-type, and can have one of the values USERID, +ERROR, and FATAL. These response types have +the following meanings:

+
+
USERID
+

This indicates a successful response. Two more keys and associated +values are returned, opsys, and user-id.

+
ERROR
+

This means the ident server has returned an error. A second key named +error is present whose value contains the error-type +field from the server response.

+
FATAL
+

Fatal errors happen when no ident server is listening on the remote +side, or when the ident server gives a response that does not conform +to the RFC. A detailed error message is returned under the +error key.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ident of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/imap4/imap4.html Index: embedded/www/tcllib/files/modules/imap4/imap4.html ================================================================== --- embedded/www/tcllib/files/modules/imap4/imap4.html +++ embedded/www/tcllib/files/modules/imap4/imap4.html @@ -0,0 +1,481 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

imap4(n) 0.5.3 tcllib "imap client"

+

Name

+

imap4 - imap client-side tcl implementation of imap protocol

+
+ + +

Description

+

The imap4 library package provides the client side of the +Internet Message Access Protocol (IMAP) using standard +sockets or secure connection via TLS/SSL. +The package is fully implemented in Tcl.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::imap4::open hostname ?port?
+

Open a new IMAP connection and initalize the handler, +the imap communication channel (handler) is returned.

+

hostname - mail server

+

port - connection port, defaults to 143

+

The namespace variable ::imap4::use_ssl +can be used to establish to a secure connection +via TSL/SSL if set to true. In this case default connection port +defaults to 993.

+

Note: +For connecting via SSL the Tcl module tls must be already +loaded otherwise an error is raised.

+
+    package require tls              ; # must be loaded for TLS/SSL
+    set ::imap4::use_ssl 1           ; # request a secure connection
+    set chan [::imap4::open $server] ; # default port is now 993
+
+
::imap4::starttls chan
+

Use this when tasked with connecting to an unsecure port which must be +changed to a secure port prior to user login. This feature is known +as STARTTLS.

+
::imap4::login chan user pass
+

Login using the IMAP LOGIN command, 0 is returned on successful login.

+

chan - imap channel

+

user - username

+

pass - password

+
::imap4::folders chan ?-inline? ?mboxref? ?mboxname?
+

Get list of matching folders, 0 is returned on success.

+

Wildcards '*' as '%' are allowed for mboxref and mboxname, +command ::imap4::folderinfo can be used to retrieve folder information.

+

chan - imap channel

+

mboxref - mailbox reference, defaults to ""

+

mboxname - mailbox name, defaults to "*"

+

If -inline is specified a compact folderlist is +returned instead of the result code. All flags are converted to +lowercase and leading special characters are removed.

+
{{Arc08 noselect} {Arc08/Private {noinferiors unmarked}} {INBOX noinferiors}}
+
+
::imap4::select chan ?mailbox?
+

Select a mailbox, 0 is returned on success.

+

chan - imap channel

+

mailbox - Path of the mailbox, defaults to INBOX

+

Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

+
::imap4::examine chan ?mailbox?
+

"Examines" a mailbox, read-only equivalent of ::imap4::select.

+

chan - imap channel

+

mailbox - mailbox name or path to mailbox, +defaults to INBOX

+

Prior to examine/select an open mailbox must be closed - see: ::imap4::close.

+
::imap4::fetch chan range ?-inline? ?attr ...?
+

Fetch attributes from messages.

+

The attributes are fetched and stored in the internal state +which can be retrieved with command ::imap4::msginfo, 0 is returned +on success. +If -inline is specified, alle records are returned as list +in order as defined in the attr argument.

+

chan - imap channel

+

range - message index in format FROM:TO

+

attr - imap attributes to fetch

+

Note: +If FROM is omitted, the 1st message is assumed, +if TO is ommitted the last message is assumed. +All message index ranges are 1-based.

+
::imap4::noop chan
+

Send NOOP command to server. May get information as untagged data.

+

chan - imap channel

+
::imap4::check chan
+

Send CHECK command to server. Flush to disk.

+

chan - imap channel

+
::imap4::folderinfo chan ?info?
+

Get information on the recently selected folderlist. +If the info argument is omitted or a null string, the full list +of information available for the mailbox is returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

info - folderlist options to retrieve

+

Currently supported options: +delim - hierarchy delimiter only, +match - ref and mbox search patterns (see ::imap4::folders), +names - list of folder names only, +flags - list of folder names with flags in format +{ {name {flags}} ... } (see also compact format in function +::imap4::folders).

+
+{{Arc08 {{\NoSelect}}} {Arc08/Private {{\NoInferiors} {\UnMarked}}} {INBOX {\NoInferiors}}}
+
+
+
::imap4::msginfo chan msgid ?info? ?defval?
+

Get information (from previously collected using fetch) from a given +msgid. If the 'info' argument is omitted or a null string, +the list of available information options for the given message is +returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

msgid - message number

+

info - imap keyword to retrieve

+

defval - default value, returned if info is empty

+

Note: +All message index ranges are 1-based.

+
::imap4::mboxinfo chan ?info?
+

Get information on the currently selected mailbox. +If the info argument is omitted or a null string, the list +of available information options for the mailbox is returned.

+

If the required information name is suffixed with a ? character, +the command returns true if the information is available, or +false if it is not.

+

chan - imap channel

+

opt - mailbox option to retrieve

+

Currently supported options: +EXISTS (noof msgs), +RECENT (noof 'recent' flagged msgs), +FLAGS

+

In conjunction with OK: +PERMFLAGS, UIDNEXT, UIDVAL, UNSEEN

+

Div. states: +CURRENT, FOUND, PERM.

+
+    ::imap4::select $chan INBOX
+    puts "[::imap4::mboxinfo $chan exists] mails in INBOX"
+
+
::imap4::isableto chan ?capability?
+

Test for capability. +It returns 1 if requested capability is supported, 0 otherwise. +If capability is omitted all capability imap +codes are retured as list.

+

chan - imap channel

+

info - imap keyword to retrieve

+

Note: +Use the capability command to ask the server if not +already done by the user.

+
::imap4::create chan mailbox
+

Create a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::delete chan mailbox
+

Delete a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::rename chan oldname newname
+

Rename a new mailbox.

+

chan - imap channel

+

mailbox - old mailbox name

+

mailbox - new mailbox name

+
::imap4::subscribe chan mailbox
+

Subscribe a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::unsubscribe chan mailbox
+

Unsubscribe a new mailbox.

+

chan - imap channel

+

mailbox - mailbox name

+
::imap4::search chan expr ?...?
+

Search for mails matching search criterions, 0 is returned on success.

+

chan - imap channel

+

expr - imap search expression

+

Notes: +Currently the following search expressions are handled:

+

Mail header flags: +all mail header entries (ending with a colon ":"), like "From:", "Bcc:", ...

+

Imap message search flags: +ANSWERED, DELETED, DRAFT, FLAGGED, RECENT, +SEEN, NEW, OLD, UNANSWERED, UNDELETED, +UNDRAFT, UNFLAGGED, UNSEEN, ALL

+

Imap header search flags: +BODY, CC, FROM, SUBJECT, TEXT, KEYWORD, BCC

+

Imap conditional search flags: +SMALLER, LARGER, ON, SENTBEFORE, SENTON, SENTSINCE, SINCE, +BEFORE (not implemented), +UID (not implemented)

+

Logical search conditions: +OR, NOT

+
::imap4::search $chan larger 4000 seen
+puts "Found messages: [::imap4::mboxinfo $chan found]"
+Found messages: 1 3 6 7 8 9 13 14 15 19 20
+
+
::imap4::close chan
+

Close the mailbox. Permanently removes \Deleted messages and +return to the AUTH state.

+

chan - imap channel

+
::imap4::cleanup chan
+

Destroy an IMAP connection and free the used space. +Close the mailbox. Permanently removes \Deleted messages +and return to the AUTH state.

+

chan - imap channel

+
::imap4::debugmode chan ?errormsg?
+

Switch client into command line debug mode.

+

This is a developers mode only that pass the control to the +programmer. Every line entered is sent verbatim to the +server (after the addition of the request identifier). +The ::imap4::debug variable is automatically set to '1' on enter.

+

It's possible to execute Tcl commands starting the line +with a slash.

+

chan - imap channel

+

errormsg - optional error message to display

+
::imap4::store chan range data flaglist
+

Alters data associated with a message in the selected +mailbox.

+

chan - imap channel

+

range - message index in format FROM:TO

+

flaglist - Flags the data operates on.

+

data - The currently defined data items that can be +stored are shown below. Note that all of these data types may +also be suffixed with ".SILENT" to suppress the untagged FETCH +response.

+
+
FLAGS
+

Replace the flags for the message (other than \Recent) with the +flaglist.

+
+FLAGS
+

Add the flags in flaglist to the existing flags for the message.

+
-FLAGS
+

Remove the flags in flaglist to the existing flags for the +message.

+
+

For example:

+
+	::imap4::store $chan $start_msgid:$end_msgid +FLAGS "Deleted"
+
+
+
::imap4::expunge chan
+

Permanently removes all messages that have the \Deleted flag +set from the currently selected mailbox, without the need to close the +connection.

+

chan - imap channel

+
::imap4::copy chan msgid mailbox
+

Copies the specified message (identified by its message number) +to the named mailbox, i.e. imap folder.

+

chan - imap channel

+

msgid - message number

+

mailbox - mailbox name

+
::imap4::logout chan
+

Informs the server that the client is done with the connection +and closes the network connection. Permanently removes \Deleted +messages.

+

A new connection will need to be established to login once +more.

+

chan - imap channel

+
+
+

EXAMPLES

+
+    set user myusername
+    set pass xtremescrt
+    set server imap.test.tld
+    set FOLDER INBOX
+    # Connect to server
+    set imap [::imap4::open $server]
+    ::imap4::login $imap $user $pass
+    ::imap4::select $imap $FOLDER
+    # Output all the information about that mailbox
+    foreach info [::imap4::mboxinfo $imap] {
+        puts "$info -> [::imap4::mboxinfo $imap $info]"
+    }
+    # fetch 3 records inline
+    set fields {from: to: subject: size}
+    foreach rec [::imap4::fetch $imap :3 -inline {*}$fields] {
+        puts -nonewline "#[incr idx])"
+        for {set j 0} {$j<[llength $fields]} {incr j} {
+            puts "\t[lindex $fields $j] [lindex $rec $j]"
+        }
+    }
+    # Show all the information available about the message ID 1
+    puts "Available info about message 1: [::imap4::msginfo $imap 1]"
+    # Use the capability stuff
+    puts "Capabilities: [::imap4::isableto $imap]"
+    puts "Is able to imap4rev1? [::imap4::isableto $imap imap4rev1]"
+    # Cleanup
+    ::imap4::cleanup $imap
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

REFERENCES

+

Mark R. Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", +RFC 3501, March 2003, http://www.rfc-editor.org/rfc/rfc3501.txt

+

OpenSSL, http://www.openssl.org/

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category imap4 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation. +Only a small part of rfc3501 implemented.

+
+ + +
ADDED embedded/www/tcllib/files/modules/inifile/ini.html Index: embedded/www/tcllib/files/modules/inifile/ini.html ================================================================== --- embedded/www/tcllib/files/modules/inifile/ini.html +++ embedded/www/tcllib/files/modules/inifile/ini.html @@ -0,0 +1,204 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

inifile(n) 0.3 tcllib "Parsing of Windows INI files"

+

Name

+

inifile - Parsing of Windows INI files

+
+ + +

Description

+

This package provides an interface for easy manipulation of Windows INI files.

+
+
::ini::open file ?-encoding encoding? ?access?
+

Opens an INI file and returns a handle that is used by other commands. +access is the same as the first form (non POSIX) of the open +command, with the exception that mode a is not supported. The +default mode is r+.

+

The default encoding is the system encoding.

+
::ini::close ini
+

Close the specified handle. If any changes were made and not written by +commit they are lost.

+
::ini::commit ini
+

Writes the file and all changes to disk. The sections are written in +arbitrary order. The keys in a section are written in alphabetical +order. If the ini was opened in read only mode an error will be thrown.

+
::ini::revert ini
+

Rolls all changes made to the inifile object back to the last +committed state.

+
::ini::filename ini
+

Returns the name of the file the ini object is associated with.

+
::ini::sections ini
+

Returns a list of all the names of the existing sections in the file handle +specified.

+
::ini::keys ini section
+

Returns a list of all they key names in the section and file specified.

+
::ini::get ini section
+

Returns a list of key value pairs that exist in the section and file specified.

+
::ini::exists ini section ?key?
+

Returns a boolean value indicating the existance of the specified section as a +whole or the specified key within that section.

+
::ini::value ini section key ?default?
+

Returns the value of the named key and section. If specified, +the default value will be returned if the key does not exist. If the key does +not exist and no default is specified an error will be thrown.

+
::ini::set ini section key value
+

Sets the value of the key in the specified section. If the section does not +exist then a new one is created.

+
::ini::delete ini section ?key?
+

Removes the key or the entire section and all its keys. A section is not +automatically deleted when it has no remaining keys.

+
::ini::comment ini section ?key? ?text?
+

Reads and modifies comments for sections and keys. To write a section comment use an +empty string for the key. To remove all comments use an empty string for text. +text may consist of a list of lines or one single line. Any embedded newlines in +text are properly handled. Comments may be written to nonexistant +sections or keys and will not return an error. Reading a comment from a nonexistant +section or key will return an empty string.

+
::ini::commentchar ?char?
+

Reads and sets the comment character. Lines that begin with this character are treated as +comments. When comments are written out each line is preceded by this character. The default +is ;.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category inifile of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/interp/deleg_method.html Index: embedded/www/tcllib/files/modules/interp/deleg_method.html ================================================================== --- embedded/www/tcllib/files/modules/interp/deleg_method.html +++ embedded/www/tcllib/files/modules/interp/deleg_method.html @@ -0,0 +1,168 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

deleg_method(n) 0.2 tcllib "Interpreter utilities"

+

Name

+

deleg_method - Creation of comm delegates (snit methods)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require snit ?1.1?
    • +
  • package require interp::delegate::method ?0.2?
    • +
+ +
+
+

Description

+

This package provides a single command for use within snit +type definition (i.e. actually a snit::macro) for the convenient +creation of methods which delegate the actual work to a remote +location via a "channel" created by the package comm.

+
+

API

+
+
::interp::delegate::method ?-async? name arguments comm id
+

This commands creates a method which is named by name. All +invokations of this method will delegate the actual work to the remote +location identified by the comm channel comm and the endpoint +id.

+

The name of the remote method invoked by the delegator is identical to +the name of the method itself.

+

Normally the generated method marshalls the arguments, and +returns the result from the remote method as its own result. If +however the option -async was specified then the generated +method will not wait for a result and return immediately.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/interp/deleg_proc.html Index: embedded/www/tcllib/files/modules/interp/deleg_proc.html ================================================================== --- embedded/www/tcllib/files/modules/interp/deleg_proc.html +++ embedded/www/tcllib/files/modules/interp/deleg_proc.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

deleg_proc(n) 0.2 tcllib "Interpreter utilities"

+

Name

+

deleg_proc - Creation of comm delegates (procedures)

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require interp::delegate::proc ?0.2?
    • +
+ +
+
+

Description

+

This package provides a single command for the convenient creation of +procedures which delegate the actual work to a remote location via a +"channel" created by the package comm.

+
+

API

+
+
::interp::delegate::proc ?-async? name arguments comm id
+

This commands creates a procedure which is named by name and +returns its fully-qualified name. All invokations of this procedure +will delegate the actual work to the remote location identified by the +comm channel comm and the endpoint id.

+

The name of the remote procedure invoked by the delegator is +[namespace tail name]. I.e., namespace information is +stripped from the call.

+

Normally the generated procedure marshalls the arguments, and +returns the result from the remote procedure as its own result. If +however the option -async was specified then the generated +procedure will not wait for a result and return immediately.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/interp/tcllib_interp.html Index: embedded/www/tcllib/files/modules/interp/tcllib_interp.html ================================================================== --- embedded/www/tcllib/files/modules/interp/tcllib_interp.html +++ embedded/www/tcllib/files/modules/interp/tcllib_interp.html @@ -0,0 +1,182 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

interp(n) 0.1.2 tcllib "Interpreter utilities"

+

Name

+

interp - Interp creation and aliasing

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require interp ?0.1.2?
    • +
+ +
+
+

Description

+

This package provides a number of commands for the convenient creation +of Tcl interpreters for highly restricted execution.

+
+

API

+
+
::interp::createEmpty ?path?
+

This commands creates an empty Tcl interpreter and returns it +name. Empty means that the new interpreter has neither namespaces, nor +any commands. It is useful only for the creation of aliases.

+

If a path is specified then it is taken as the name of the new +interpreter.

+
::interp::snitLink path methodlist
+

This command assumes that it was called from within a method of a snit +object, and that the command mymethod is available.

+

It extends the interpreter specified by path with aliases for +all methods found in the methodlist, with the alias directing +execution to the same-named method of the snit object invoking this +command. +Each element of methodlist is actually interpreted as a command +prefix, with the first word of each prefix the name of the method to +link to.

+

The result of the command is the empty string.

+
::interp::snitDictLink path methoddict
+

This command behaves like ::interp::snitLink, except that it +takes a dictionary mapping from commands to methods as its input, and +not a list of methods. +Like for ::interp::snitLink the method references are actually +command prefixes. +This command allows the creation of more complex command-method +mappings than ::interp::snitLink.

+

The result of the command is the empty string.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category interp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/irc/irc.html Index: embedded/www/tcllib/files/modules/irc/irc.html ================================================================== --- embedded/www/tcllib/files/modules/irc/irc.html +++ embedded/www/tcllib/files/modules/irc/irc.html @@ -0,0 +1,318 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

irc(n) 0.6.1 tcllib "Low Level Tcl IRC Interface"

+

Name

+

irc - Create IRC connection and interface.

+
+ + +

Description

+

This package provides low-level commands to deal with the IRC protocol +(Internet Relay Chat) for immediate and interactive multi-cast +communication.

+
+
::irc::config ?key? ?value?
+

Sets configuration ?key? to ?value?. The configuration keys +currently defined are the boolean flags logger and debug. +logger makes irc use the logger package for printing +error. debug requires logger and prints extra debug output. +If no ?key? or ?value? is given the current values are returned.

+
::irc::connection
+

The command creates a new object to deal with an IRC connection. +Creating this IRC object does not automatically create the network +connection. It returns a new irc namespace command which can be used +to interact with the new IRC connection. NOTE: the old form of the +connection command, which took a hostname and port as arguments, is +deprecated. Use connect instead to specify this information.

+
::irc::connections
+

Returns a list of all the current connections that were created with +connection

+
+
+

Per-connection Commands

+

In the following list of available connection methods net +represents a connection command as returned by +::irc::connection.

+
+
net registerevent event script
+

Registers a callback handler for the specific event. Events available +are those described in RFC 1459 +http://www.rfc-editor.org/rfc/rfc1459.txt. +In addition, there are several other events defined. +defaultcmd adds a command that is called if no other callback +is present. EOF is called if the connection signals an End of +File condition. The events defaultcmd, defaultnumeric, +defaultevent, and EOF are required. +script is executed in the connection namespace, which can take +advantage of several commands (see Callback Commands +below) to aid in the parsing of data.

+
net getevent event script
+

Returns the current handler for the event if one exists. Otherwise an +empty string is returned.

+
net eventexists event script
+

Returns a boolean value indicating the existence of the event handler.

+
net connect hostname ?port?
+

This causes the socket to be established. ::irc::connection +created the namespace and the commands to be used, but did not +actually open the socket. This is done here. NOTE: the older form of +'connect' did not require the user to specify a hostname and port, +which were specified with 'connection'. That form is deprecated.

+
net config ?key? ?value?
+

The same as ::irc::config but sets and gets options for the net +connection only.

+
net log level message
+

If logger is turned on by config this will write a log message +at level.

+
net logname
+

Returns the name of the logger instance if logger is turned on.

+
net connected
+

Returns a boolean value indicating if this connection is connected to a server.

+
net sockname
+

Returns a 3 element list consisting of the ip address, the hostname, and the port +of the local end of the connection, if currently connected.

+
net peername
+

Returns a 3 element list consisting of the ip address, the hostname, and the port +of the remote end of the connection, if currently connected.

+
net socket
+

Return the Tcl channel for the socket used by the connection.

+
net user username localhostname localdomainname userinfo
+

Sends USER command to server. username is the username you want +to appear. localhostname is the host portion of your hostname, localdomainname +is your domain name, and userinfo is a short description of who you are. The 2nd and 3rd +arguments are normally ignored by the IRC server.

+
net nick nick
+

NICK command. nick is the nickname you wish to use for the +particular connection.

+
net ping target
+

Send a CTCP PING to target.

+
net serverping
+

PING the server.

+
net join channel ?key?
+

channel is the IRC channel to join. IRC channels typically +begin with a hashmark ("#") or ampersand ("&").

+
net part channel ?message?
+

Makes the client leave channel. Some networks may support the optional +argument message

+
net quit ?message?
+

Instructs the IRC server to close the current connection. The package +will use a generic default if no message was specified.

+
net privmsg target message
+

Sends message to target, which can be either a channel, or +another user, in which case their nick is used.

+
net notice target message
+

Sends a notice with message message to target, +which can be either a channel, or another user, in which case their nick is used.

+
net ctcp target message
+

Sends a CTCP of type message to target

+
net kick channel target ?message?
+

Kicks the user target from the channel channel with a message. +The latter can be left out.

+
net mode target args
+

Sets the mode args on the target target. target may be a channel, +a channel user, or yourself.

+
net topic channel message
+

Sets the topic on channel to message specifying an empty string +will remove the topic.

+
net invite channel target
+

Invites target to join the channel channel

+
net send text
+

Sends text to the IRC server.

+
net destroy
+

Deletes the connection and its associated namespace and information.

+
+
+

Callback Commands

+

These commands can be used within callbacks

+
+
who ?address?
+

Returns the nick of the user who performed a command. The optional +keyword address causes the command to return the user in the +format "username@address".

+
action
+

Returns the action performed, such as KICK, PRIVMSG, MODE, etc... +Normally not useful, as callbacks are bound to a particular event.

+
target
+

Returns the target of a particular command, such as the channel or +user to whom a PRIVMSG is sent.

+
additional
+

Returns a list of any additional arguments after the target.

+
header
+

Returns the entire event header (everything up to the :) as a proper list.

+
msg
+

Returns the message portion of the command (the part after the :).

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category irc of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

rfc 1459

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/irc/picoirc.html Index: embedded/www/tcllib/files/modules/irc/picoirc.html ================================================================== --- embedded/www/tcllib/files/modules/irc/picoirc.html +++ embedded/www/tcllib/files/modules/irc/picoirc.html @@ -0,0 +1,243 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

picoirc(n) 0.5.2 tcllib "Simple embeddable IRC interface"

+

Name

+

picoirc - Small and simple embeddable IRC client.

+
+ + +

Description

+

This package provides a general purpose minimal IRC client suitable for +embedding in other applications. All communication with the parent +application is done via an application provided callback procedure. +Each connection has its own state so you can hook up multiple servers +in a single application instance.

+

To initiate an IRC connection you must call picoirc::connect +with a callback procedure, a nick-name to use on IRC and the IRC URL +that describes the connection. This will return a variable name that +is the irc connection context. See CALLBACK for details.

+

This package is a fairly simple IRC client. If you need something with +more capability investigate the irc package.

+
+

COMMANDS

+
+
::picoirc::connect callback nick url
+

Create a new irc connection to the server specified by url and +login using the nick as the username. The callback must be +as specified in CALLBACK. Returns a package-specific variable +that is used when calling other commands in this package.

+
::picoirc::post context channel message
+

This should be called to process user input and send it to the +server. A number of commands are recognised when prefixed with a +forward-slash (/). Such commands are converted to IRC command +sequences and then sent.

+
::picoirc::splituri uri
+

Splits an IRC scheme uniform resource indicator into its component +parts. Returns a list of server, port and channel. The default port is +6667 and there is no default channel.

+
::picoirc::send context line
+

This command is where all raw output to the server is handled. The +default action is to write the line to the irc socket. However, +before this happens the callback is called with "debug write". This +permits the application author to inspect the raw IRC data and if +desired to return a break error code to halt further processing. In +this way the application can override the default send via the +callback procedure.

+
+
+

CALLBACK

+

The callback must look like:

+
+proc Callback {context state args} {
+}
+
+

where context is the irc context variable name (in case you need to pass +it back to a picoirc procedure). state is one of a number of states as +described below.

+
+
init
+

called just before the socket is created

+
connect
+

called once we have connected, before we join any channels

+
close
+

called when the socket gets closed, before the context is deleted. If +an error occurs before we get connected the only argument will be the +socket error message.

+
userlist channel nicklist
+

called to notify the application of an updated userlist. This is +generated when the output of the NAMES irc command is seen. The +package collects the entire output which can span a number of output +lines from the server and calls this callback when they have all been +received.

+
chat target nick message type
+

called when a message arrives. target is the identity that the +message was targetted for. This can be the logged in nick or a channel +name. nick is the name of the sender of the message. +message is the message text. type is set to "ACTION" if the +message was sent as a CTCP ACTION

+
system channel message
+

called when a system message is received

+
topic channel topic
+

called when the channel topic string is seen. topic is the text +of the channel topic.

+
traffic action channel nick ?newnick?
+

called when users join, leave or change names. +action is either entered, left or nickchange and nick +is the user doing the action. newnick is +the new name if action is nickchange.

+

NOTE: channel is often empty for these messages as nick +activities are global for the irc server. You will have +to manage the nick for all connected channels yourself.

+
version
+

This is called to request a version string to use to +override the internal version. If implemented, you should +return as colon delimited string as

+

Appname:Appversion:LibraryVersion

+

For example, the default is

+

PicoIRC:[package provide picoirc]:Tcl [info patchlevel]

+
debug type raw
+

called when data is either being read or written to the network +socket. type is set to read when reading data and +write if the data is to be written. raw is the +unprocessed IRC protocol data.

+

In both cases the application can return a break error code to +interrupt further processing of the raw data. If this is a +read operation then the package will not handle this line. If +the operation is write then the package will not send the +data. This callback is intended for debugging protocol issues but +could be used to redirect all input and output if desired.

+
+
+

See Also

+

rfc 1459

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/javascript/javascript.html Index: embedded/www/tcllib/files/modules/javascript/javascript.html ================================================================== --- embedded/www/tcllib/files/modules/javascript/javascript.html +++ embedded/www/tcllib/files/modules/javascript/javascript.html @@ -0,0 +1,209 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

javascript(n) 1.0.2 tcllib "HTML and Java Script Generation"

+

Name

+

javascript - Procedures to generate HTML and Java Script structures.

+
+ + +

Description

+

The ::javascript package provides commands that generate +HTML and Java Script code. These commands typically return an HTML +string as their result. In particular, they do not output their +result to stdout.

+
+
::javascript::makeSelectorWidget id leftLabel leftValueList rightLabel rightValueList rightNameList ?length? ?minWidth?
+

Construct HTML code to create a dual-multi-selection megawidget. This +megawidget consists of two side-by-side multi-selection boxes +separated by a left arrow and a right arrow button. The right arrow +button moves all items selected in the left box to the right box. The +left arrow button moves all items selected in the right box to the +left box. The id argument is the suffix of all HTML objects in +this megawidget. The leftLabel argument is the text that +appears above the left selection box. The leftValueList +argument is the values of items in the left selection box. The +leftNameList argument is the names to appear in the left +selection box. The rightLabel argument is the text that appears +above the right selection box. The rightValueList argument is +the values of items in the right selection box. The +rightNameList argument is the names to appear in the right +selection box. The length argument (optional) determines the +number of elts to show before adding a vertical scrollbar; it defaults +to 8. The minWidth argument (optional) is the number of spaces +to determine the minimum box width; it defaults to 32.

+
::javascript::makeSubmitButton name value
+

Create an HTML submit button that resets a hidden field for each +registered multi-selection box. The name argument is the name +of the HTML button object to create. The value argument is the +label of the HTML button object to create.

+
::javascript::makeProtectedSubmitButton name value msg
+

Create an HTML submit button that prompts the user with a +continue/cancel shutdown warning before the form is submitted. The +name argument is the name of the HTML button object to create. +The value argument is the label of the HTML button object to +create. The msg argument is the message to display when the +button is pressed.

+
::javascript::makeMasterButton master value slavePattern boolean
+

Create an HTML button that sets its slave checkboxs to the boolean +value. The master argument is the name of the child's parent +html checkbox object. The value argument is the value of the +master. The slaves argument is the name of child html checkbox +object to create. The boolean argument is the java script +boolean value that will be given to all the slaves; it must be "true" +or "false".

+
::javascript::makeParentCheckbox parentName childName
+

Create an HTML checkbox and tie its value to that of its child +checkbox. If the parent is unchecked, the child is automatically +unchecked. The parentName argument is the name of parent html +checkbox object to create. The childName argument is the name of +the parent's child html checkbox object.

+
::javascript::makeChildCheckbox parentName childName
+

Create an HTML checkbox and tie its value to that of its parent +checkbox. If the child is checked, the parent is automatically +checked. The parentName argument is the name of the child's +parent html checkbox object. The childName argument is the name +of child html checkbox object to create.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category javascript of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/jpeg/jpeg.html Index: embedded/www/tcllib/files/modules/jpeg/jpeg.html ================================================================== --- embedded/www/tcllib/files/modules/jpeg/jpeg.html +++ embedded/www/tcllib/files/modules/jpeg/jpeg.html @@ -0,0 +1,288 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

jpeg(n) 0.5 tcllib "JPEG image manipulation"

+

Name

+

jpeg - JPEG querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query and modify JPEG images. JPEG +stands for Joint Photography Experts Group and is a standard +for the lossy compression of photographical images. It is specified at +LINK_HERE.

+
+

COMMANDS

+
+
::jpeg::isJPEG file
+

Returns a boolean value indicating if file is a +JPEG image.

+
::jpeg::imageInfo file
+

Returns a dictionary with keys version, units, +xdensity, ydensity, xthumb, and +ythumb. The values are the associated properties of the JPEG +image in file. +Throws an error if file is not a JPEG image.

+
::jpeg::dimensions file
+

Returns the dimensions of the JPEG file as a list of the +horizontal and vertical pixel count. +Throws an error if file is not a JPEG image.

+
::jpeg::getThumbnail file
+

This procedure will return the binary thumbnail image data, if a JPEG +thumbnail is included in file, and the empty string +otherwise. Note that it is possible to include thumbnails in formats +other than JPEG although that is not common. The command finds +thumbnails that are encoded in either the JFXX or EXIF segments of the +JPEG information. If both are present the EXIF thumbnail will take precedence. +Throws an error if file is not a JPEG image.

+
+    set fh [open thumbnail.jpg w+]
+    fconfigure $fh -translation binary -encoding binary
+    puts -nonewline $fh [::jpeg::getThumbnail photo.jpg]
+    close $fh
+
+
+
::jpeg::getExif file ?section?
+

section must be one of main or thumbnail. +The default is main. +Returns a dictionary containing the EXIF information for the specified section. +For example:

+
+    set exif {
+	Make     Canon
+	Model    {Canon DIGITAL IXUS}
+	DateTime {2001:06:09 15:17:32}
+    }
+
+

Throws an error if file is not a JPEG image.

+
::jpeg::getExifFromChannel channel ?section?
+

This command is as per ::jpeg::getExif except that it uses a +previously opened channel. channel should be a seekable channel +and section is as described in the documentation of +::jpeg::getExif.

+

Note: The jpeg parser expects that the start of the +channel is the start of the image data. If working with an image +embedded in a container file format it may be necessary to read the +jpeg data into a temporary container: either a temporary file or a +memory channel.

+

Attention: It is the resonsibility of the caller to close +the channel after its use.

+
::jpeg::formatExif keys
+

Takes a list of key-value pairs as returned by getExif and formats +many of the values into a more human readable form. As few as one key-value +may be passed in, the entire exif is not required.

+
+    foreach {key val} [::jpeg::formatExif [::jpeg::getExif photo.jpg]] {
+        puts "$key: $val"
+    }
+
+
+    array set exif [::jpeg::getExif photo.jpg]
+    puts "max f-stop: [::jpeg::formatExif [list MaxAperture $exif(MaxAperture)]]
+
+
+
::jpeg::exifKeys
+

Returns a list of the EXIF keys which are currently understood. +There may be keys present in getExif data that are not understood. +Those keys will appear in a 4 digit hexadecimal format.

+
::jpeg::removeExif file
+

Removes the Exif data segment from the specified file and replaces +it with a standard JFIF segment. +Throws an error if file is not a JPEG image.

+
::jpeg::stripJPEG file
+

Removes all metadata from the JPEG file leaving only +the image. This includes comments, EXIF segments, JFXX +segments, and application specific segments. +Throws an error if file is not a JPEG image.

+
::jpeg::getComments file
+

Returns a list containing all the JPEG comments found in +the file. +Throws an error if file is not a valid JPEG image.

+
::jpeg::addComment file text...
+

Adds one or more plain text comments to the JPEG image +in file. +Throws an error if file is not a valid JPEG image.

+
::jpeg::removeComments file
+

Removes all comments from the file specified. +Throws an error if file is not a valid JPEG image.

+
::jpeg::replaceComment file text
+

Replaces the first comment in the file with the new text. +This is merely a shortcut for ::jpeg::removeComments +and ::jpeg::addComment +Throws an error if file is not a valid JPEG image.

+
::jpeg::debug file
+

Prints everything we know about the given file in a nice format.

+
::jpeg::markers channel
+

This is an internal helper command, we document it for use by advanced +users of the package. The argument channel is an open file +handle positioned at the start of the first marker (usually 2 +bytes). The command returns a list with one element for each JFIF +marker found in the file. Each element consists of a list of the +marker name, its offset in the file, and its length. The offset points +to the beginning of the sections data, not the marker itself. The +length is the length of the data from the offset listed to the start +of the next marker.

+
+
+

LIMITATIONS

+

can only work with files +cant write exif data +gps exif data not parsed +makernote data not yet implemented

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category jpeg of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/json/json.html Index: embedded/www/tcllib/files/modules/json/json.html ================================================================== --- embedded/www/tcllib/files/modules/json/json.html +++ embedded/www/tcllib/files/modules/json/json.html @@ -0,0 +1,221 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

json(n) 1.3.3 tcllib "JSON"

+

Name

+

json - JSON parser

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require json ?1.3.3?
    • +
+ +
+
+

Description

+

The json package provides a simple Tcl-only library for parsing the +JSON http://www.json.org/ data exchange format as specified in RFC 4627 +http://www.ietf.org/rfc/rfc4627.txt. +There is some ambiguity in parsing JSON because JSON has type information that +is not maintained by the Tcl conversion. The json package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
::json::json2dict txt
+

Parse JSON formatted text txt into a Tcl dict and return +the value.

+

If txt contains more than one JSON entity only the +first one is returned.

+
::json::many-json2dict txt ?max?
+

Parse JSON formatted text txt containing multiple JSON entities +into a list of dictionaries and return that list.

+

If max is specified exactly that many entities are extracted +from txt. By default the command will attempt to extract all, without +limits. A value of "max == 0" does not make sense and will cause the +command to throw an error.

+
+
+

EXAMPLES

+

An example of a JSON array converted to Tcl. A JSON array is returned as a +single item with multiple elements.

+
[
+    {
+       "precision": "zip",
+       "Latitude":  37.7668,
+       "Longitude": -122.3959,
+       "Address":   "",
+       "City":      "SAN FRANCISCO",
+       "State":     "CA",
+       "Zip":       "94107",
+       "Country":   "US"
+    },
+    {
+       "precision": "zip",
+       "Latitude":  37.371991,
+       "Longitude": -122.026020,
+       "Address":   "",
+       "City":      "SUNNYVALE",
+       "State":     "CA",
+       "Zip":       "94085",
+       "Country":   "US"
+    }
+]
+=>
+{Country US Latitude 37.7668 precision zip State CA City {SAN FRANCISCO} Address {} Zip 94107 Longitude -122.3959} {Country US Latitude 37.371991 precision zip State CA City SUNNYVALE Address {} Zip 94085 Longitude -122.026020}
+
+

An example of a JSON object converted to Tcl. A JSON object is returned as a +multi-element list (a dict).

+
{
+    "Image": {
+        "Width":  800,
+        "Height": 600,
+        "Title":  "View from 15th Floor",
+        "Thumbnail": {
+            "Url":    "http://www.example.com/image/481989943",
+            "Height": 125,
+            "Width":  "100"
+        },
+        "IDs": [116, 943, 234, 38793]
+    }
+}
+=>
+Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www.example.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category json of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

CGI programming

+
+ +
ADDED embedded/www/tcllib/files/modules/json/json_write.html Index: embedded/www/tcllib/files/modules/json/json_write.html ================================================================== --- embedded/www/tcllib/files/modules/json/json_write.html +++ embedded/www/tcllib/files/modules/json/json_write.html @@ -0,0 +1,193 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

json::write(n) 1.0.3 tcllib "JSON"

+

Name

+

json::write - JSON generation

+
+ + +

Description

+

The json::write package provides a simple Tcl-only library +for generation of text in the JSON http://www.json.org/ data +exchange format as specified in +RFC 4627 http://www.ietf.org/rfc/rfc4627.txt.

+
+

COMMANDS

+
+
::json::write indented
+

This method returns the current state of the indentation setting.

+
::json::write indented flag
+

This and the method aligned configure the layout of the JSON +generated by the package.

+

If this flag is set (default) the package will break the +generated JSON code across lines and indent it according to its inner +structure, with each key of an object on a separate line.

+

If this flag is not set, the whole JSON object will be written on a +single line, with minimum spacing between all elements.

+
::json::write aligned
+

This method returns the current state of the alignment setting.

+
::json::write aligned flag
+

This and the method indented configure the layout of the JSON +generated by the package.

+

If this flag is set (default) the package ensures that the +values for the keys in an object are vertically aligned with each +other, for a nice table effect. To make this work this also implies +that indented is set as well.

+

If this flag is not set, the output is formatted as per the value of +indented, without trying to align the values for object keys.

+
::json::write string s
+

This method takes the string s and returns it properly quoted +for JSON as its result.

+
::json::write array arg...
+

This method takes a series of JSON formatted arguments and returns +them as a properly formatted JSON array as its result.

+
::json::write object key value...
+

This method takes a series of key/value arguments, the values already +formatted for JSON, and returns them as a properly formatted JSON +object as its result, with the keys formatted as JSON strings.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category json of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

CGI programming

+
+ +
ADDED embedded/www/tcllib/files/modules/lambda/lambda.html Index: embedded/www/tcllib/files/modules/lambda/lambda.html ================================================================== --- embedded/www/tcllib/files/modules/lambda/lambda.html +++ embedded/www/tcllib/files/modules/lambda/lambda.html @@ -0,0 +1,203 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

lambda(n) 1 tcllib "Utility commands for anonymous procedures"

+

Name

+

lambda - Utility commands for anonymous procedures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require lambda ?1?
    • +
+ +
+
+

Description

+

This package provides two convenience commands to make the writing of +anonymous procedures, i.e. lambdas more proc-like. Instead of, +for example, to write

+
+     set f {::apply {{x} {
+        ....
+     }}}
+
+

with its deep nesting of braces, or

+
+     set f [list ::apply {{x y} {
+        ....
+     }} $value_for_x]
+
+

with a list command to insert some of the arguments of a partial +application, just write

+
+     set f [lambda {x} {
+        ....
+     }]
+
+

and

+
+     set f [lambda {x y} {
+        ....
+     } $value_for_x]
+
+
+

COMMANDS

+
+
::lambda arguments body ?arg...?
+

The command constructs an anonymous procedure from the list of +arguments, body script and (optional) predefined argument values and +returns a command prefix representing this anonymous procedure.

+

When invoked the body is run in a new procedure scope +just underneath the global scope, with the arguments set to the values +supplied at both construction and invokation time.

+
::lambda@ namespace arguments body ?arg...?
+

The command constructs an anonymous procedure from the namespace name, +list of arguments, body script and (optional) predefined argument +values and returns a command prefix representing this anonymous +procedure.

+

When invoked the body is run in a new procedure scope in +the namespace, with the arguments set to the values supplied at +both construction and invokation time.

+
+
+

AUTHORS

+

Andreas Kupries

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category lambda of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

apply(n), proc(n)

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/ldap/ldap.html Index: embedded/www/tcllib/files/modules/ldap/ldap.html ================================================================== --- embedded/www/tcllib/files/modules/ldap/ldap.html +++ embedded/www/tcllib/files/modules/ldap/ldap.html @@ -0,0 +1,524 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ldap(n) 1.6.9 tcllib "LDAP client"

+

Name

+

ldap - LDAP client

+
+ + +

Description

+

The ldap package provides a Tcl-only client library +for the LDAPv3 protocol as specified in +RFC 4511 (http://www.rfc-editor.org/rfc/rfc4511.txt). +It works by opening the standard (or secure) LDAP socket on the +server, and then providing a Tcl API to access the LDAP protocol +commands. All server errors are returned as Tcl errors (thrown) which +must be caught with the Tcl catch command.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

COMMANDS

+
+
::ldap::connect host ?port?
+

Opens a LDAPv3 connection to the specified host, at the given +port, and returns a token for the connection. This token is the +handle argument for all other commands. If no port is +specified it will default to 389.

+

The command blocks until the connection has been established, or +establishment definitely failed.

+
::ldap::secure_connect host ?port?
+

Like ::ldap::connect, except that the created connection is +secured by SSL. The port defaults to 636. This command +depends on the availability of the package TLS, which is a +SSL binding for Tcl. If TLS is not available, then this +command will fail.

+

The command blocks until the connection has been established, or +establishment definitely failed.

+
::ldap::disconnect handle
+

Closes the ldap connection refered to by the token +handle. Returns the empty string as its result.

+
::ldap::starttls handle ?cafile? ?certfile? ?keyfile?
+

Start TLS negotiation on the connection denoted by handle. +This is currently experimental and subject to change, more control over the TLS details +will probably be exposed later, to allow users to fine tune the negotiation according +to their security needs.

+
::ldap::bind handle ?name? ?password?
+

This command authenticates the ldap connection refered to by the token +in handle, with a user name and associated password. It blocks +until a response from the ldap server arrives. Its result is the empty +string. +Both name and passwd default to the empty string if they +are not specified. +By leaving out name and passwd you can make an anonymous bind to +the ldap server. +You can issue ::ldap::bind again to bind with different credentials.

+
::ldap::bindSASL handle ?name? ?password?
+

This command uses SASL authentication mechanisms to do a multistage bind. +Its otherwise identical to the standard ::ldap::bind. +This feature is currently experimental and subject to change. See the documentation +for the SASL and the "SASL.txt" in the tcllib CVS repository for +details how to setup and use SASL with openldap.

+
::ldap::unbind handle
+

This command asks the ldap server to release the last bind done for +the connection refered to by the token in handle. +The handle is invalid after the unbind, as the server closes the connection. +So this is effectivly just a more polite disconnect operation.

+
::ldap::search handle baseObject filterString attributes options
+

This command performs a LDAP search below the baseObject tree +using a complex LDAP search expression filterString and returns +the specified attributes of all matching objects (DNs). If the +list of attributes was empty all attributes are returned. The +command blocks until it has received all results. +The valid options are identical to the options listed for ::ldap::searchInit.

+

An example of a search expression is

+
+    set filterString "|(cn=Linus*)(sn=Torvalds*)"
+
+

The return value of the command is a list of nested dictionaries. The +first level keys are object identifiers (DNs), second levels keys are +attribute names. In other words, it is in the form

+
+    {dn1 {attr1 {val11 val12 ...} attr2 {val21...} ...}} {dn2 {a1 {v11 ...} ...}} ...
+
+
+
::ldap::searchInit handle baseObject filterString attributes options
+

This command initiates a LDAP search below the baseObject tree +using a complex LDAP search expression filterString. +The search gets the specified attributes of all matching objects (DNs). +The command itself just starts the search, to retrieve the actual results, use +::ldap::searchNext. +A search can be terminated at any time by +::ldap::searchEnd. This informs the server that no further results should be sent by sending and ABANDON message +and cleans up the internal state of the search. +Only one ::ldap::search can be active at a given time, this +includes the introspection commands ::ldap::info saslmechanisms, ldap::info control and +ldap::info extensions, which invoke a search internally. +Error responses from the server due to wrong arguments or similar things are returned +with the first ::ldap::searchNext call and should be checked and dealed with there. +If the list of requested attributes is empty all attributes will be returned. +The parameter options specifies the options to be used in the search, +and has the following format:

+
+    {-option1 value1 -option2 value2 ... }
+
+

Following options are available:

+
+
-scope base one sub
+

Control the scope of the search to be one of base, one, or sub, to specify a base +object, one-level or subtree search. The default is sub.

+
-derefaliases never search find always
+

Control how aliases dereferencing is done. Should be one of never, always, search, or find to +specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or +dereferenced only when locating the base object for the search. +The default is to never dereference aliases.

+
-sizelimit num
+

Determines the maximum number of entries to return in a search. If specified as +0 no limit is enforced. The server may enforce a configuration dependent sizelimit, +which may be lower than the one given by this option. The default is 0, no limit.

+
-timelimit seconds
+

Asks the server to use a timelimit of seconds for the search. Zero means no +limit. The default is 0, no limit.

+
-attrsonly boolean
+

If set to 1 only the attribute names but not the values will be present in the search result. +The default is to retrieve attribute names and values.

+
-referencevar varname
+

If set the search result reference LDAPURIs, if any, are returned in the given variable. +The caller can than decide to follow those references and query other LDAP servers for +further results.

+
+
::ldap::searchNext handle
+

This command returns the next entry from a LDAP search initiated +by ::ldap::searchInit. It returns only after a new result is received +or when no further results are available, but takes care to keep +the event loop alive. +The returned entry is a list with +two elements: the first is the DN of the entry, the second is the +list of attributes and values, under the format:

+
+    dn {attr1 {val11 val12 ...} attr2 {val21...} ...}
+
+

The ::ldap::searchNext command returns an empty list at the +end of the search.

+
::ldap::searchEnd handle
+

This command terminates a LDAP search initiated +by ::ldap::searchInit. It also cleans up +the internal state so a new search can be initiated. +If the client has not yet received all results, the client +sends an ABANDON message to inform the server that no +further results for the previous search should to be sent.

+
::ldap::modify handle dn attrValToReplace ?attrToDelete? ?attrValToAdd?
+

This command modifies the object dn on the ldap server we are +connected to via handle. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are dictionaries mapping attribute names to values. The +optional arguments default to the empty dictionary, which means that +no attributes will be deleted nor added.

+
+
dictionary attrValToReplace (in)
+

No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +replace all attributes known to the object.

+
dictionary attrToDelete (in)
+

No attributes will be deleted if this argument is empty. The +dictionary values are restrictions on the deletion. An attribute +listed here will be deleted if and only if its current value at the +server matches the value specified in the dictionary, or if the value +in the dictionary is the empty string.

+
dictionary attrValToAdd (in)
+

No attributes will be added if this argument is empty. The dictionary +values are the values for the new attributes.

+
+

The command blocks until all modifications have completed. Its result +is the empty string.

+
::ldap::modifyMulti handle dn attrValToReplace ?attrValToDelete? ?attrValToAdd?
+

This command modifies the object dn on the ldap server we are +connected to via handle. It replaces attributes with new values, +deletes attributes, and adds new attributes with new values. +All arguments are lists with the format:

+
+    attr1 {val11 val12 ...} attr2 {val21...} ...
+
+

where each value list may be empty for deleting all attributes. +The optional arguments default to empty lists of attributes to +delete and to add.

+
+
list attrValToReplace (in)
+

No attributes will be changed if this argument is empty. The +dictionary contains the new attributes and their values. They +replace all attributes known to the object.

+
list attrValToDelete (in)
+

No attributes will be deleted if this argument is empty. If no +value is specified, the whole set of values for an attribute +will be deleted.

+
list attrValToAdd (in)
+

No attributes will be added if this argument is empty.

+
+

The command blocks until all modifications have completed. Its result +is the empty string.

+
::ldap::add handle dn attrValueTuples
+

This command creates a new object using the specified dn. The +attributes of the new object are set to the values in the list +attrValueTuples. +Multiple valuated attributes may be specified using multiple tuples. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::addMulti handle dn attrValueTuples
+

This command is the preferred one to create +a new object using the specified dn. The +attributes of the new object are set to the values in the dictionary +attrValueTuples (which is keyed by the attribute names). +Each tuple is a list containing multiple values. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::delete handle dn
+

This command removes the object specified by dn, and all its +attributes from the server. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::modifyDN handle dn newrdn ?deleteOld? ?newSuperior?
+

] +This command moves or copies the object specified by dn +to a new location in the tree of object. This location is +specified by newrdn, a relative designation, +or by newrdn and newSuperior, a absolute designation. +The optional argument deleteOld defaults to true, +i.e. a move operation. If deleteOld is not set, then the +operation will create a copy of dn in the new location. +The optional argument newSuperior defaults an empty string, +meaning that the object must not be relocated in another branch of +the tree. If this argument is given, the argument deleteOld +must be specified also. +The command blocks until the operation has completed. Its result +is the empty string.

+
::ldap::info ip handle
+

This command returns the IP address of the remote LDAP server the handle is connected to.

+
::ldap::info bound handle
+

This command returns 1 if a handle has successfully completed a ::ldap::bind. +If no bind was done or it failed, a 0 is returned.

+
::ldap::info bounduser handle
+

This command returns the username used in the bind operation if a handle has successfully completed a ::ldap::bind. +If no bound was done or it failed, an empty string is returned.

+
::ldap::info connections
+

This command returns all currently existing ldap connection handles.

+
::ldap::info tls handle
+

This command returns 1 if the ldap connection handle used TLS/SSL for +connection via ldap::secure_connect or completed ldap::starttls, 0 otherwise.

+
::ldap::info saslmechanisms handle
+

Return the supported SASL mechanisms advertised by the server. Only valid in a +bound state (anonymous or other).

+
::ldap::info control handle
+

Return the supported controls advertised by the server as a list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change.

+
::ldap::info extensions extensions
+

Returns the supported LDAP extensions as list of OIDs. Only valid in a bound state. +This is currently experimental and subject to change.

+
::ldap::info whoami handle
+

Returns authzId for the current connection. This implements the RFC 4532 +protocol extension.

+
+
+

EXAMPLES

+

A small example, extracted from the test application coming with this +code.

+
+    package require ldap
+    # Connect, bind, add a new object, modify it in various ways
+    set handle [ldap::connect localhost 9009]
+    set dn "cn=Manager, o=University of Michigan, c=US"
+    set pw secret
+    ldap::bind $handle $dn $pw
+    set dn "cn=Test User,ou=People,o=University of Michigan,c=US"
+    ldap::add $handle $dn {
+	objectClass     OpenLDAPperson
+	cn              {Test User}
+	mail            test.user@google.com
+	uid             testuid
+	sn              User
+	telephoneNumber +31415926535
+	telephoneNumber +27182818285
+    }
+    set dn "cn=Another User,ou=People,o=University of Michigan,c=US"
+    ldap::addMulti $handle $dn {
+	objectClass     {OpenLDAPperson}
+	cn              {{Anotther User}}
+	mail            {test.user@google.com}
+	uid             {testuid}
+	sn              {User}
+	telephoneNumber {+31415926535 +27182818285}
+    }
+    # Replace all attributes
+    ldap::modify $handle $dn [list drink icetea uid JOLO]
+    # Add some more
+    ldap::modify $handle $dn {} {} [list drink water  drink orangeJuice pager "+1 313 555 7671"]
+    # Delete
+    ldap::modify $handle $dn {} [list drink water  pager ""]
+    # Move
+    ldap::modifyDN $handle $dn "cn=Tester"
+    # Kill the test object, and shut the connection down.
+    set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
+    ldap::delete $handle $dn
+    ldap::unbind     $handle
+    ldap::disconnect $handle
+
+

And a another example, a simple query, and processing the +results.

+
+    package require ldap
+    set handle [ldap::connect ldap.acme.com 389]
+    ldap::bind $handle
+    set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
+    foreach result $results {
+	foreach {object attributes} $result break
+	# The processing here is similar to what 'parray' does.
+	# I.e. finding the longest attribute name and then
+	# generating properly aligned output listing all attributes
+	# and their values.
+	set width 0
+	set sortedAttribs {}
+	foreach {type values} $attributes {
+	    if {[string length $type] > $width} {
+		set width [string length $type]
+	    }
+	    lappend sortedAttribs [list $type $values]
+	}
+	puts "object='$object'"
+	foreach sortedAttrib  $sortedAttribs {
+	    foreach {type values} $sortedAttrib break
+	    foreach value $values {
+		regsub -all "\[\x01-\x1f\]" $value ? value
+		puts [format "  %-${width}s %s" $type $value]
+	    }
+	}
+	puts ""
+    }
+    ldap::unbind $handle
+    ldap::disconnect $handle
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ldap of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/ldap/ldapx.html Index: embedded/www/tcllib/files/modules/ldap/ldapx.html ================================================================== --- embedded/www/tcllib/files/modules/ldap/ldapx.html +++ embedded/www/tcllib/files/modules/ldap/ldapx.html @@ -0,0 +1,745 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ldapx(n) 0.2.5 tcllib "LDAP extended object interface"

+

Name

+

ldapx - LDAP extended object interface

+
+ + +

Description

+

The ldapx package provides an extended Tcl interface to +LDAP directores and LDIF files. The ldapx package is built +upon the ldap package in order to get low level LDAP access.

+

LDAP access is compatible with RFC 2251 +(http://www.rfc-editor.org/rfc/rfc2251.txt). +LDIF access is compatible with RFC 2849 +(http://www.rfc-editor.org/rfc/rfc2849.txt).

+
+

OVERVIEW

+

The ldapx package provides objects to interact with LDAP +directories and LDIF files with an easy to use programming interface. +It implements three snit::type classes.

+

The first class, entry, is used to store individual entries. +Two different formats are available: the first one is the +standard format, which represents an entry as read from the +directory. The second format is the change format, which +stores differences between two standard entries.

+

With these entries, an application which wants to modify an entry +in a directory needs to read a (standard) entry from the directory, +create a fresh copy into a new (standard) entry, modify the new +copy, and then compute the differences between the two entries into +a new (change) entry, which may be commited to the directory.

+

Such kinds of modifications are so heavily used that standard entries +may contain their own copy of the original data. With such a copy, +the application described above reads a (standard) entry from the +directory, backs-up the original data, modifies the entry, and +computes the differences between the entry and its backup. These +differences are then commited to the directory.

+

Methods are provided to compute differences between two entries, +to apply differences to an entry in order to get a new entry, and +to get or set attributes in standard entries.

+

The second class is the ldap class. It provides a method +to connect and bind to the directory with a uniform access +to LDAP and LDAPS through an URL (ldap:// or ldaps://). The +traverse control structure executes a body for each entry +found in the directory. The commit method applies some +changes (represented as entry objects) to the directory. +Since some attributes are represented as UTF-8 strings, the option +-utf8 controls which attributes must be converted and +which attributes must not be converted.

+

The last class is the ldif class. It provides a method to +associate a standard Tcl channel to an LDIF object. Then, +methods read and write read or write entries from +or to this channel. This class can make use of standard or change +entries, according to the type of the LDIF file which may contain +either standard entries or change entries (but not both at the same +time). The option -utf8 works exactly as with the +ldap class.

+
+

ENTRY CLASS

+

Entry Instance Data

+

An instance of the entry class keeps the following data:

+
+ +
dn
+

This is the DN of the entry, which includes (in LDAP + terminology) the RDN (relative DN) and the Superior parts.

+
format
+

The format may be uninitialized (entry not yet used), + standard or change. Most methods check the + format of the entry, which can be reset with the + reset method.

+
attrvals
+

In a standard entry, this is where the attributes + and associated values are stored. Many methods provide + access to these informations. Attribute names are always + converted into lower case.

+
backup
+

In a standard entry, the backup may contain a copy + of the dn and all attributes and values. Methods + backup and restore manipulate these data, + and method diff may use this backup.

+
change
+

In a change entry, these data represent the + modifications. Such modifications are handled by specialized + methods such as apply or commit. + Detailed format should not be used directly by programs.

+

Internally, modifications are represented as a list of + elements, each element has one of the following formats + (which match the corresponding LDAP operations):

+
    + +

  1. {add {attr1 {val1...valn} attr2 {...} ...}}

    +

    Addition of a new entry.

    2. +

  2. {mod {modop {attr1 ?val1...valn?} attr2 ...} {modop ...} ...}

    +

    Modification of one or more attributes and/or values, + where <modop> can be modadd, moddel + or modrepl (see the LDAP modify operation).

    3. +

  3. {del}

    +

    Deletion of an old entry.

    4. +

  4. {modrdn newrdn deleteoldrdn ?newsuperior?}

    +

    Renaming of an entry.

    5. +
+
+
+

Entry Options

+

No option is defined by this class.

+
+

Methods for all kinds of entries

+
+ +
e reset
+

This method resets the entry to an uninitialized state.

+
e dn ?newdn?
+

This method returns the current DN of the entry. If the + optional newdn is specified, it replaces the current + DN of the entry.

+
e rdn
+

This method returns the RDN part of the DN of the entry.

+
e superior
+

This method returns the superior part of the DN of the entry.

+
e print
+

This method returns the entry as a string ready to be printed.

+
+
+

Methods for standard entries only

+

In all methods, attribute names are converted in lower case.

+
+ +
se isempty
+

This method returns 1 if the entry is empty (i.e. without + any attribute).

+
se get attr
+

This method returns all values of the attribute attr, + or the empty list if the attribute is not fond.

+
se get1 attr
+

This method returns the first value of the attribute.

+
se set attr values
+

This method sets the values (list values) of the + attribute attr. If the list is empty, this method + deletes all

+
se set1 attr value
+

This method sets the values of the attribute attr to + be an unique value value. Previous values, if any, + are replaced by the new value.

+
se add attr values
+

This method adds all elements the list values to the + values of the attribute attr.

+
se add1 attr value
+

This method adds a single value given by the parameter + value to the attribute attr.

+
se del attr ?values?
+

If the optional list values is specified, this method + deletes all specified values from the attribute attr. + If the argument values is not specified, this method + deletes all values.

+
se del1 attr value
+

This method deletes a unique value from the attribute + attr.

+
se getattr
+

This method returns all attributes names.

+
se getall
+

This method returns all attributes and values from the + entry, packed in a list of pairs <attribute, list of values>.

+
se setall avpairs
+

This method sets at once all attributes and values. The + format of the avpairs argument is the same as the one + returned by method getall.

+
se backup ?other?
+

This method stores in an other standard entry object + a copy of the current DN and attributes/values. If the + optional other argument is not specified, copy is + done in the current entry (in a specific place, see section + OVERVIEW).

+
se swap
+

This method swaps the current and backup contexts of the + entry.

+
se restore ?other?
+

If the optional argument other is given, which must + then be a standard entry, this method restores the + current entry into the other entry. If the argument + other argument is not specified, this methods restores + the current entry from its internal backup (see section + OVERVIEW).

+
se apply centry
+

This method applies changes defined in the centry + argument, which must be a change entry.

+
+
+

Methods for change entries only

+
+ +
ce change ?new?
+

If the optional argument new is specified, this method + modifies the change list (see subsection Entry Instance Data for + the exact format). In both cases, current change list is + returned. + Warning: values returned by this method should only be used + by specialized methods such as apply or + commit.

+
ce diff new ?old?
+

This method computes the differences between the new + and old entries under the form of a change list, and + stores this list into the current change entry. If + the optional argument old is not specified, difference + is computed from the entry and its internal backup (see + section OVERVIEW). Return value is the computed + change list.

+
+
+

Entry Example

+
+    package require ldapx
+    #
+    # Create an entry and fill it as a standard entry with
+    # attributes and values
+    #
+    ::ldapx::entry create e
+    e dn "uid=joe,ou=people,o=mycomp"
+    e set1 "uid"             "joe"
+    e set  "objectClass"     {person anotherObjectClass}
+    e set1 "givenName"       "Joe"
+    e set1 "sn"              "User"
+    e set  "telephoneNumber" {+31415926535 +2182818}
+    e set1 "anotherAttr"     "This is a beautiful day, isn't it?"
+    puts stdout "e\n[e print]"
+    #
+    # Create a second entry as a backup of the first, and
+    # make some changes on it.
+    # Entry is named automatically by snit.
+    #
+    set b [::ldapx::entry create %AUTO%]
+    e backup $b
+    puts stdout "$b\n[$b print]"
+    $b del  "anotherAttr"
+    $b del1 "objectClass" "anotherObjectClass"
+    #
+    # Create a change entry, a compute differences between first
+    # and second entry.
+    #
+    ::ldapx::entry create c
+    c diff e $b
+    puts stdout "$c\n[$c print]"
+    #
+    # Apply changes to first entry. It should be the same as the
+    # second entry, now.
+    #
+    e apply c
+    ::ldapx::entry create nc
+    nc diff e $b
+    puts stdout "nc\n[nc print]"
+    #
+    # Clean-up
+    #
+    e destroy
+    $b destroy
+    c destroy
+    nc destroy
+
+
+
+

LDAP CLASS

+

Ldap Instance Data

+

An instance of the ldap class keeps the following data:

+
+ +
channel
+

This is the channel used by the ldap package for + communication with the LDAP server.

+
lastError
+

This variable contains the error message which appeared in + the last method of the ldap class (this string is + modified in nearly all methods). The error method + may be used to fetch this message.

+
+
+

Ldap Options

+

A first set of options of the ldap class is used during +search operations (methods traverse, search and +read, see below).

+
+ +
-scope base|one|sub
+

Specify the scope of the LDAP search to be one of + base, one or sub to specify + a base object, one-level or subtree search.

+

The default is sub.

+
-derefaliases never|seach|find|always
+

Specify how aliases dereferencing is handled: + never is used to specify that aliases are never derefenced, + always that aliases are always derefenced, + search that aliases are dereferenced when searching, + or find that aliases are dereferenced only when + locating the base object for the search.

+

The default is never.

+
-sizelimit integer
+

Specify the maximum number of entries to be retreived + during a search. A value of 0 means no limit.

+

Default is 0.

+
-timelimit integer
+

Specify the time limit for a search to complete. + A value of 0 means no limit.

+

Default is 0.

+
-attrsonly 0|1
+

Specify if only attribute names are to be retrieved (value + 1). Normally (value 0), attribute values + are also retrieved.

+

Default is 0.

+
+

The last option is used when getting entries or committing changes +in the directory:

+
+ +
-utf8 pattern-yes pattern-no
+

Specify which attribute values are encoded in UTF-8. This + information is specific to the LDAP schema in use by the + application, since some attributes such as jpegPhoto, for + example, are not encoded in UTF-8. This option takes the + form of a list with two regular expressions suitable for + the regexp command (anchored by ^ and $). + The first specifies which attribute names are to be UTF-8 + encoded, and the second selects, among those, the attribute + names which will not be UTF-8 encoded. It is thus possible + to say: convert all attributes, except jpegPhoto.

+

Default is {{.*} {}}, meaning: all attributes are converted, + without exception.

+
+
+

Ldap Methods

+
+ +
la error ?newmsg?
+

This method returns the error message that occurred in the + last call to a ldap class method. If the optional + argument newmsg is supplied, it becomes the last + error message.

+
la connect url ?binddn? ?bindpw?
+

This method connects to the LDAP server using given URL + (which can be of the form ldap://host:port or + ldaps://host:port). If an optional binddn + argument is given together with the bindpw argument, + the connect binds to the LDAP server using the + specified DN and password.

+
la disconnect
+

This method disconnects (and unbinds, if necessary) from + the LDAP server.

+
la traverse base filter attrs entry body
+

This method is a new control structure. It searches the + LDAP directory from the specified base DN (given by the + base argument) and selects entries based on the + argument filter. For each entry found, this method + fetches attributes specified by the attrs argument + (or all attributes if it is an empty list), stores them in + the entry instance of class entry and executes + the script defined by the argument body. Options are + used to refine the search.

+

Caution: when this method is used, the script body + cannot perform another LDAP search (methods traverse, + search or read).

+
la search base filter attrs
+

This method searches the directory using the same way as + method traverse. All found entries are stored in + newly created instances of class entry, which are + returned in a list. The newly created instances should be + destroyed when they are no longer used.

+
la read base filter entry ... entry
+

This method reads one or more entries, using the same search + criteria as methods traverse and search. + All attributes are stored in the entries. This method + provides a quick way to read some entries. It returns the + number of entries found in the directory (which may be more + than the number of read entries). If called without any + entry argument, this method just returns the number + of entries found, without returning any data.

+
la commit entry ... entry
+

This method commits the changes stored in the entry + arguments. Each entry may be either a change + entry, or a standard entry with a backup.

+

Note: in the future, this method should use the LDAP + transaction extension provided by OpenLDAP 2.3 and later.

+
+
+

Ldap Example

+
+    package require ldapx
+    #
+    # Connects to the LDAP directory
+    #
+    ::ldapx::ldap create l
+    set url "ldap://server.mycomp.com"
+    if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then {
+	puts stderr "error: [l error]"
+	exit 1
+    }
+    #
+    # Search all entries matching some criterion
+    #
+    l configure -scope one
+    ::ldapx::entry create e
+    set n 0
+    l traverse "ou=people,o=mycomp" "(sn=Joe*)" {sn givenName} e {
+	puts "dn: [e dn]"
+	puts "  sn:        [e get1 sn]"
+	puts "  givenName: [e get1 givenName]"
+	incr n
+    }
+    puts "$n entries found"
+    e destroy
+    #
+    # Add a telephone number to some entries
+    # Note this modification cannot be done in the "traverse" operation.
+    #
+    set lent [l search "ou=people,o=mycomp" "(sn=Joe*)" {}]
+    ::ldapx::entry create c
+    foreach e $lent {
+	$e backup
+	$e add1 "telephoneNumber" "+31415926535"
+	c diff $e
+	if {! [l commit c]} then {
+	    puts stderr "error: [l error]"
+	    exit 1
+	}
+	$e destroy
+    }
+    l disconnect
+    l destroy
+
+
+
+

LDIF CLASS

+

Ldif Instance Data

+

An instance of the ldif class keeps the following data:

+
+ +
channel
+

This is the Tcl channel used to retrieve or store LDIF file + contents. The association between an instance and a channel + is made by the method channel. There is no need + to disrupt this association when the LDIF file operation + has ended.

+
format
+

LDIF files may contain standard entries or + change entries, but not both. This variable contains + the detected format of the file (when reading) or the format + of entries written to the file (when writing).

+
lastError
+

This variable contains the error message which appeared in + the last method of the ldif class (this string is + modified in nearly all methods). The error method + may be used to fetch this message.

+
version
+

This is the version of the LDIF file. Only version 1 is + supported: the method read can only read from + version 1 files, and method write only creates + version 1 files.

+
+
+

Ldif Options

+

This class defines two options:

+
+ +
-ignore list-of-attributes
+

This option is used to ignore certain attribute names on + reading. For example, to read OpenLDAP replica files (replog), + one must ignore replica and time attributes + since they do not conform to the RFC 2849 standard for LDIF + files.

+

Default is empty list: no attribute is ignored.

+
-utf8 pattern-yes pattern-no
+

Specify which attribute values are encoded in UTF-8. This + information is specific to the LDAP schema in use by the + application, since some attributes such as jpegPhoto, for + example, are not encoded in UTF-8. This option takes the + form of a list with two regular expressions suitable for + the regexp command (anchored by ^ and $). + The first specifies which attribute names are to be UTF-8 + encoded, and the second selects, among those, the attribute + names which will not be UTF-8 encoded. It is thus possible + to say: convert all attributes, except jpegPhoto.

+

Default is {{.*} {}}, meaning: all attributes are converted, + without exception.

+
+
+

Ldif Methods

+
+ +
li channel chan
+

This method associates the Tcl channel named chan + with the LDIF instance. It resets the type of LDIF object + to uninitialized.

+
li error ?newmsg?
+

This method returns the error message that occurred in the + last call to a ldif class method. If the optional + argument newmsg is supplied, it becomes the last + error message.

+
li read entry
+

This method reads the next entry from the LDIF file and + stores it in the entry object of class entry. + The entry may be a standard or change entry.

+
li write entry
+

This method writes the entry given in the argument + entry to the LDIF file.

+
+
+

Ldif Example

+
+    package require ldapx
+    # This examples reads a LDIF file containing entries,
+    # compare them to a LDAP directory, and writes on standard
+    # output an LDIF file containing changes to apply to the
+    # LDAP directory to match exactly the LDIF file.
+    ::ldapx::ldif create liin
+    liin channel stdin
+    ::ldapx::ldif create liout
+    liout channel stdout
+    ::ldapx::ldap create la
+    if {! [la connect "ldap://server.mycomp.com"]} then {
+	puts stderr "error: [la error]"
+	exit 1
+    }
+    la configure -scope one
+    # Reads LDIF file
+    ::ldapx::entry create e1
+    ::ldapx::entry create e2
+    ::ldapx::entry create c
+    while {[liin read e1] != 0} {
+	set base [e1 superior]
+	set id [e1 rdn]
+	if {[la read $base "($id)" e2] == 0} then {
+	    e2 reset
+	}
+	c diff e1 e2
+	if {[llength [c change]] != 0} then {
+	    liout write c
+	}
+    }
+    la disconnect
+    la destroy
+    e1 destroy
+    e2 destroy
+    c destroy
+    liout destroy
+    liin destroy
+
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ldap of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/log/log.html Index: embedded/www/tcllib/files/modules/log/log.html ================================================================== --- embedded/www/tcllib/files/modules/log/log.html +++ embedded/www/tcllib/files/modules/log/log.html @@ -0,0 +1,343 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

log(n) 1.3 tcllib "Logging facility"

+

Name

+

log - Procedures to log messages of libraries and applications.

+
+ + +

Description

+

The log package provides commands that allow libraries and +applications to selectively log information about their internal +operation and state.

+

To use the package just execute

+
+    package require log
+    log::log notice "Some message"
+
+

As can be seen above, each message given to the log facility is +associated with a level determining the importance of the +message. The user can then select which levels to log, what commands +to use for the logging of each level and the channel to write the +message to. In the following example the logging of all message with +level debug is deactivated.

+
+    package require log
+    log::lvSuppress debug
+    log::log debug "Unseen message" ; # No output
+
+

By default all messages associated with an error-level +(emergency, alert, critical, and +error) are written to stderr. Messages with any +other level are written to stdout. In the following example +the log module is reconfigured to write debug messages to +stderr too.

+
+    package require log
+    log::lvChannel debug stderr
+    log::log debug "Written to stderr"
+
+

Each message level is also associated with a command to use when +logging a message with that level. The behaviour above for example +relies on the fact that all message levels use by default the standard +command ::log::Puts to log any message. In the following example +all messages of level notice are given to the non-standard +command toText for logging. This disables the channel setting +for such messages, assuming that toText does not use it by +itself.

+
+    package require log
+    log::lvCmd notice toText
+    log::log notice "Handled by \"toText\""
+
+

Another database maintained by this facility is a map from message +levels to colors. The information in this database has no +influence on the behaviour of the module. It is merely provided as a +convenience and in anticipation of the usage of this facility in +tk-based application which may want to colorize message +logs.

+
+

API

+

The following commands are available:

+
+
::log::levels
+

Returns the names of all known levels, in alphabetical order.

+
::log::lv2longform level
+

Converts any unique abbreviation of a level name to the full level +name.

+
::log::lv2color level
+

Converts any level name including unique abbreviations to the +corresponding color.

+
::log::lv2priority level
+

Converts any level name including unique abbreviations to the +corresponding priority.

+
::log::lv2cmd level
+

Converts any level name including unique abbreviations to the command +prefix used to write messages with that level.

+
::log::lv2channel level
+

Converts any level name including unique abbreviations to the channel +used by ::log::Puts to write messages with that level.

+
::log::lvCompare level1 level2
+

Compares two levels (including unique abbreviations) with respect to +their priority. This command can be used by the -command option of +lsort. The result is one of -1, 0 or 1 or an error. A result of -1 +signals that level1 is of less priority than level2. 0 signals that +both levels have the same priority. 1 signals that level1 has higher +priority than level2.

+
::log::lvSuppress level {suppress 1}
+

] +(Un)suppresses the output of messages having the specified +level. Unique abbreviations for the level are allowed here too.

+
::log::lvSuppressLE level {suppress 1}
+

] +(Un)suppresses the output of messages having the specified level or +one of lesser priority. Unique abbreviations for the level are allowed +here too.

+
::log::lvIsSuppressed level
+

Asks the package whether the specified level is currently +suppressed. Unique abbreviations of level names are allowed.

+
::log::lvCmd level cmd
+

Defines for the specified level with which command to write the +messages having this level. Unique abbreviations of level names are +allowed. The command is actually a command prefix and this facility +will append 2 arguments before calling it, the level of the message +and the message itself, in this order.

+
::log::lvCmdForall cmd
+

Defines for all known levels with which command to write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order.

+
::log::lvChannel level chan
+

Defines for the specified level into which channel ::log::Puts +(the standard command) shall write the messages having this +level. Unique abbreviations of level names are allowed. The command is +actually a command prefix and this facility will append 2 arguments +before calling it, the level of the message and the message itself, in +this order.

+
::log::lvChannelForall chan
+

Defines for all known levels with which which channel +::log::Puts (the standard command) shall write the messages +having this level. The command is actually a command prefix and this +facility will append 2 arguments before calling it, the level of the +message and the message itself, in this order.

+
::log::lvColor level color
+

Defines for the specified level the color to return for it in a call +to ::log::lv2color. Unique abbreviations of level names are +allowed.

+
::log::lvColorForall color
+

Defines for all known levels the color to return for it in a call to +::log::lv2color. Unique abbreviations of level names are +allowed.

+
::log::log level text
+

Log a message according to the specifications for commands, channels +and suppression. In other words: The command will do nothing if the +specified level is suppressed. If it is not suppressed the actual +logging is delegated to the specified command. If there is no command +specified for the level the message won't be logged. The standard +command ::log::Puts will write the message to the channel +specified for the given level. If no channel is specified for the +level the message won't be logged. Unique abbreviations of level names +are allowed. Errors in the actual logging command are not +caught, but propagated to the caller, as they may indicate +misconfigurations of the log facility or errors in the callers code +itself.

+
::log::logarray level arrayvar ?pattern?
+

Like ::log::log, but logs the contents of the specified array +variable arrayvar, possibly restricted to entries matching the +pattern. The pattern defaults to * (i.e. all entries) if +none was specified.

+
::log::loghex level text data
+

Like ::log::log, but assumes that data contains binary +data. It converts this into a mixed hex/ascii representation before +writing them to the log.

+
::log::logMsg text
+

Convenience wrapper around ::log::log. +Equivalent to ::log::log info text.

+
::log::logError text
+

Convenience wrapper around ::log::log. +Equivalent to ::log::log error text.

+
::log::Puts level text
+

The standard log command, it writes messages and their levels to +user-specified channels. Assumes that the suppression checks were done +by the caller. Expects full level names, abbreviations are +not allowed.

+
+
+

LEVELS

+

The package currently defines the following log levels, the level of +highest importance listed first.

+
    +

  • emergency

    • +

  • alert

    • +

  • critical

    • +

  • error

    • +

  • warning

    • +

  • notice

    • +

  • info

    • +

  • debug

    • +
+

Note that by default all messages with levels warning down to +debug are suppressed. This is done intentionally, because (we believe +that) in most situations debugging output is not wanted. Most people wish to +have such output only when actually debugging an application.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category log of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/log/logger.html Index: embedded/www/tcllib/files/modules/log/logger.html ================================================================== --- embedded/www/tcllib/files/modules/log/logger.html +++ embedded/www/tcllib/files/modules/log/logger.html @@ -0,0 +1,469 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

logger(n) 0.9.4 tcllib "Object Oriented logging facility"

+

Name

+

logger - System to control logging of events.

+
+ + +

Description

+

The logger package provides a flexible system for logging messages +from different services, at priority levels, with different commands.

+

To begin using the logger package, we do the following:

+
+    package require logger
+    set log [logger::init myservice]
+    ${log}::notice "Initialized myservice logging"
+    ... code ...
+    ${log}::notice "Ending myservice logging"
+    ${log}::delete
+
+

In the above code, after the package is loaded, the following things +happen:

+
+
logger::init service
+

Initializes the service service for logging. The service names +are actually Tcl namespace names, so they are separated with '::'. +The service name may not be the empty string or only ':'s. +When a logger service is initialized, it "inherits" properties from its +parents. For instance, if there were a service foo, and +we did a logger::init foo::bar (to create a bar +service underneath foo), bar would copy the current +configuration of the foo service, although it would of +course, also be possible to then separately configure bar. +If a logger service is initialized and the parent does not yet exist, the +parent is also created. +The new logger service is initialized with the default loglevel set +with logger::setlevel.

+
logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service
+

Import the logger service commands into the current namespace. Without the -all option +only the commands corresponding to the log levels are imported. If -all is given, +all the ${log}::cmd style commands are imported. If the import would overwrite a command +an error is returned and no command is imported. Use the -force option to force the import +and overwrite existing commands without complaining. +If the -prefix option is given, the commands are imported with the given prefix +prepended to their names. +If the -namespace option is given, the commands are imported into the given namespace. If the +namespace does not exist, it is created. If a namespace without a leading :: is given, it is interpreted as +a child namespace to the current namespace.

+
logger::initNamespace ns ?level?
+

Convenience command for setting up a namespace for logging. Creates a +logger service named after the namespace ns (a :: prefix is +stripped), imports all the log commands into the namespace, and sets +the default logging level, either as specified by level, or +inherited from a service in the parent namespace, or a hardwired +default, warn.

+
logger::services
+

Returns a list of all the available services.

+
logger::enable level
+

Globally enables logging at and "above" the given level. Levels are +debug, info, notice, warn, error, +critical, alert, emergency.

+
logger::disable level
+

Globally disables logging at and "below" the given level. Levels are +those listed above.

+
logger::setlevel level
+

Globally enable logging at and "above" the given level. Levels are those +listed above. This command changes the default loglevel for new loggers +created with logger::init.

+
logger::levels
+

Returns a list of the available log levels (also listed above under enable).

+
logger::servicecmd service
+

Returns the ${log} token created by logger::init for this service.

+
${log}::debug message
+
+
${log}::info message
+
+
${log}::notice message
+
+
${log}::warn message
+
+
${log}::error message
+
+
${log}::critical message
+
+
${log}::alert message
+
+
${log}::emergency message
+

These are the commands called to actually log a message about an +event. ${log} is the variable obtained from logger::init.

+
${log}::setlevel level
+

Enable logging, in the service referenced by ${log}, and its +children, at and above the level specified, and disable logging below +it.

+
${log}::enable level
+

Enable logging, in the service referenced by ${log}, and its +children, at and above the level specified. Note that this does not disable logging below this level, so you should probably use +setlevel instead.

+
${log}::disable level
+

Disable logging, in the service referenced by ${log}, and its +children, at and below the level specified. Note that this does not enable logging above this level, +so you should probably use setlevel instead. +Disabling the loglevel emergency switches logging off for the service and its children.

+
${log}::lvlchangeproc command
+
+
${log}::lvlchangeproc
+

Set the script to call when the log instance in question changes its log level. +If called without a command it returns the currently registered command. The command gets two arguments +appended, the old and the new loglevel. The callback is invoked after all changes have been done. +If child loggers are affected, their callbacks are called before their parents callback.

+
+ 	proc lvlcallback {old new} {
+ 	    puts "Loglevel changed from $old to $new"
+ 	}
+ 	${log}::lvlchangeproc lvlcallback
+
+
+
${log}::logproc level
+
+
${log}::logproc level command
+
+
${log}::logproc level argname body
+

This command comes in three forms - the third, older one is deprecated +and may be removed from future versions of the logger package. +The current set version takes one argument, a command to be executed when the +level is called. The callback command takes on argument, the text to +be logged. If called only with a valid level logproc returns the name of the command +currently registered as callback command. +logproc specifies which command will perform the actual logging +for a given level. The logger package ships with default commands for +all log levels, but with logproc it is possible to replace them +with custom code. This would let you send your logs over the network, +to a database, or anything else. For example:

+
+    proc logtoserver {txt} {
+        variable socket
+        puts $socket "Notice: $txt"
+    }
+    ${log}::logproc notice logtoserver
+
+

Trace logs are slightly different: instead of a plain text argument, +the argument provided to the logproc is a dictionary consisting of the +enter or leave keyword along with another dictionary of +details about the trace. These include:

+
    +

  • proc - Name of the procedure being traced.

    • +

  • level - The stack level for the procedure invocation +(from info level).

    • +

  • script - The name of the file in which the procedure is +defined, or an empty string if defined in interactive mode.

    • +

  • caller - The name of the procedure calling the procedure +being traced, or an empty string if the procedure was called from the +global scope (stack level 0).

    • +

  • procargs - A dictionary consisting of the names of arguments +to the procedure paired with values given for those arguments (enter +traces only).

    • +

  • status - The Tcl return code (e.g. ok, +continue, etc.) (leave traces only).

    • +

  • result - The value returned by the procedure (leave +traces only).

    • +
+
${log}::services
+

Returns a list of the registered logging services which are children of this service.

+
${log}::servicename
+

Returns the name of this service.

+
${log}::currentloglevel
+

Returns the currently enabled log level for this service. If no logging is enabled returns none.

+
${log}::delproc command
+
+
${log}::delproc
+

Set the script to call when the log instance in question is deleted. +If called without a command it returns the currently registered command. +For example:

+
+    ${log}::delproc [list closesock $logsock]
+
+
+
${log}::delete
+

This command deletes a particular logging service, and its children. +You must call this to clean up the resources used by a service.

+
${log}::trace command
+

This command controls logging of enter/leave traces for specified procedures. +It is used to enable and disable tracing, query tracing status, and +specify procedures are to be traced. Trace handlers are unregistered when +tracing is disabled. As a result, there is not performance impact to a +library when tracing is disabled, just as with other log level commands.

+
+  proc tracecmd { dict } {
+      puts $dict
+  }
+  set log [::logger::init example]
+  ${log}::logproc trace tracecmd
+  proc foo { args } {
+      puts "In foo"
+      bar 1
+      return "foo_result"
+  }
+  proc bar { x } {
+      puts "In bar"
+      return "bar_result"
+  }
+  ${log}::trace add foo bar
+  ${log}::trace on
+  foo
+# Output:
+enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
+In foo
+enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
+In bar
+leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
+leave {proc ::foo level 1 script {} caller {} status ok result foo_result}
+
+
+
${log}::trace on
+

Turns on trace logging for procedures registered through the trace +add command. This is similar to the enable command for other +logging levels, but allows trace logging to take place at any level. +The trace logging mechanism takes advantage of the execution trace feature +of Tcl 8.4 and later. The trace on command will return an +error if called from earlier versions of Tcl.

+
${log}::trace off
+

Turns off trace logging for procedures registered for trace logging +through the trace add command. This is similar to the +disable command for other logging levels, but allows trace logging +to take place at any level. +Procedures are not unregistered, so logging for them can be turned back +on with the trace on command. There is no overhead imposed +by trace registration when trace logging is disabled.

+
${log}::trace status ?procName? ?...?
+

This command returns a list of the procedures currently registered for +trace logging, or a flag indicating whether or not a trace is registered +for one or more specified procedures.

+
${log}::trace add procName ?...?
+
+
${log}::trace add ?-ns? nsName ?...?
+

This command registers one or more procedures for logging of entry/exit +traces. Procedures can be specified via a list of procedure names or +namespace names (in which case all procedure within the namespace +are targeted by the operation). By default, each name is first +interpreted as a procedure name or glob-style search pattern, and if +not found its interpreted as a namespace name. The -ns option can +be used to force interpretation of all provided arguments as namespace names. +Procedures must be defined prior to registering them for tracing +through the trace add command. Any procedure or namespace +names/patterns that don't match any existing procedures will be +silently ignored.

+
${log}::trace remove procName ?...?
+
+
${log}::trace remove ?-ns? nsName ?...?
+

This command unregisters one or more procedures so that they will no +longer have trace logging performed, with the same matching rules as +that of the trace add command.

+
+
+

IMPLEMENTATION

+

The logger package is implemented in such a way as to optimize (for +Tcl 8.4 and newer) log procedures which are disabled. They are +aliased to a proc which has no body, which is compiled to a no op in +bytecode. This should make the peformance hit minimal. If you really +want to pull out all the stops, you can replace the ${log} token in +your code with the actual namespace and command (${log}::warn becomes +::logger::tree::myservice::warn), so that no variable lookup is done. +This puts the performance of disabled logger commands very close to no +logging at all.

+

The "object orientation" is done through a hierarchy of namespaces. +Using an actual object oriented system would probably be a better way +of doing things, or at least provide for a cleaner implementation.

+

The service "object orientation" is done with namespaces.

+
+

Logprocs and Callstack

+

The logger package takes extra care to keep the logproc out of the call stack. +This enables logprocs to execute code in the callers scope by using uplevel or +linking to local variables by using upvar. This may fire traces with all usual +side effects.

+
+     # Print caller and current vars in the calling proc
+     proc log_local_var {txt} {
+          set caller [info level -1]
+          set vars [uplevel 1 info vars]
+          foreach var [lsort $vars] {
+             if {[uplevel 1 [list array exists $var]] == 1} {
+             	lappend val $var <Array>
+             } else {
+             	lappend val $var [uplevel 1 [list set $var]]
+             }
+          }
+          puts "$txt"
+          puts "Caller: $caller"
+          puts "Variables in callers scope:"
+          foreach {var value} $val {
+          	puts "$var = $value"
+          }
+     }
+     # install as logproc
+     ${log}::logproc debug log_local_var
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/log/loggerAppender.html Index: embedded/www/tcllib/files/modules/log/loggerAppender.html ================================================================== --- embedded/www/tcllib/files/modules/log/loggerAppender.html +++ embedded/www/tcllib/files/modules/log/loggerAppender.html @@ -0,0 +1,171 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

logger::appender(n) 1.2 tcllib "Object Oriented logging facility"

+

Name

+

logger::appender - Collection of predefined appenders for logger

+
+ + +

Description

+

This package provides a predefined set of logger templates.

+
+
::logger::appender::console -level level -service service ?options...?
+
+
-level level
+

Name of the level to fill in as "priority" in the log procedure.

+
-service service
+

Name of the service to fill in as "category" in the log procedure.

+
-appenderArgs appenderArgs
+

Any additional arguments for the log procedure in list form

+
-conversionPattern conversionPattern
+

The log pattern to use (see logger::utils::createLogProc for the +allowed substitutions).

+
-procName procName
+

Explicitly set the name of the created procedure.

+
-procNameVar procNameVar
+

Name of the variable to set in the calling context. This variable will +contain the name of the procedure.

+
+
::logger::appender::colorConsole -level level -service service ?options...?
+

See ::logger::appender::colorConsole for a description of the +applicable options.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/log/loggerUtils.html Index: embedded/www/tcllib/files/modules/log/loggerUtils.html ================================================================== --- embedded/www/tcllib/files/modules/log/loggerUtils.html +++ embedded/www/tcllib/files/modules/log/loggerUtils.html @@ -0,0 +1,240 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

logger::utils(n) 1.3 tcllib "Object Oriented logging facility"

+

Name

+

logger::utils - Utilities for logger

+
+ + +

Description

+

This package adds template based appenders.

+
+
::logger::utils::createFormatCmd formatString
+

This command translates formatString into an expandable command +string. +The following strings are the known substitutions (from log4perl) +allowed to occur in the formatString:

+
+
%c
+

Category of the logging event

+
%C
+

Fully qualified name of logging event

+
%d
+

Current date in yyyy/MM/dd hh:mm:ss

+
%H
+

Hostname

+
%m
+

Message to be logged

+
%M
+

Method where logging event was issued

+
%p
+

Priority of logging event

+
%P
+

Pid of current process

+
+
::logger::utils::createLogProc -procName procName ?options...?
+

This command ...

+
+
-procName procName
+

The name of the procedure to create.

+
-conversionPattern pattern
+

See ::logger::utils::createFormatCmd for the substitutions +allowed in the pattern.

+
-category category
+

The category (service).

+
-priority priority
+

The priority (level).

+
-outputChannel channel
+

channel to output on (default stdout)

+
+
::logger::utils::applyAppender -appender appenderType ?options...?
+

This command will create an appender for the specified logger +services. If no service is specified then the appender will be added +as the default appender for the specified levels. If no levels are +specified, then all levels are assumed.

+
+
-service loggerservices
+
+
-serviceCmd loggerserviceCmds
+

Name of the logger instance to modify. -serviceCmd takes as +input the return of logger::init.

+
-appender appenderType
+

Type of the appender to use. +One of console, colorConsole.

+
-appenderArgs appenderArgs
+

Additional arguments to apply to the appender. +The argument of the option is a list of options +and their arguments.

+

For example

+
+logger::utils::applyAppender -serviceCmd $log -appender console -appenderArgs {-conversionPattern {\[%M\] \[%p\] - %m}}
+
+

The usual Tcl quoting rules apply.

+
-levels levelList
+

The list of levels to apply this appender to. If not specified all +levels are assumed.

+
+

Example of usage:

+
+   % set log [logger::init testLog]
+   ::logger::tree::testLog
+   % logger::utils::applyAppender -appender console -serviceCmd $log
+   % ${log}::error "this is an error"
+   [2005/08/22 10:14:13] [testLog] [global] [error] this is an error
+
+
+
::logger::utils::autoApplyAppender command command-string log op args...
+

This command is designed to be added via trace leave to calls +of logger::init. It will look at preconfigured state (via +::logger::utils::applyAppender) to autocreate appenders for +newly created logger instances. +It will return its argument log.

+

Example of usage:

+
+  logger::utils::applyAppender -appender console
+  set log [logger::init applyAppender-3]
+  ${log}::error "this is an error"
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category logger of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html Index: embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html ================================================================== --- embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html +++ embedded/www/tcllib/files/modules/map/map_geocode_nominatim.html @@ -0,0 +1,220 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

map::geocode::nominatim(n) 0.1 tcllib "Mapping utilities"

+

Name

+

map::geocode::nominatim - Resolving geographical names with a Nominatim service

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require http
    • +
  • package require json
    • +
  • package require uri
    • +
  • package require snit
    • +
  • package require map::geocode::nominatim ?0.1?
    • +
+ +
+
+

Description

+

This package provides a class for accessing geocoding services which implement +the Nominatim interface (see References)

+
+

API

+
+
::map::geocode::nominatim requestor ?-baseurl url? ?-callback callback? ?-error error callback?
+

Creates a geocoding request object requestor, which will send its requests to +the Nominatim server.

+

The result of the command is name.

+
+

Options

+
+
-baseurl url
+

The base URL of the Nominatim service. Default value is OpenStreetMap's service at +http://nominatim.openstreetmap.org/search A possible free alternative is at +http://open.mapquestapi.com//nominatim/v1/search

+
-callback cmdprefix
+

A command prefix to be invoked when search result become available. +The default setting, active when nothing was specified on object creation, is to print +the result (see below) to stdout. The result of the command prefix is +ignored. Errors thrown by the command prefix are caught and cause the invokation of +the error callback (see option -error below), with the error message as argument.

+

The signature of the command prefix is:

+
+
$cmdprefix result
+

The result is a list of dictionaries, containing one item per hit. +Each dictionary will have the following entries:

+
+
place_id
+

The place ID (FIXME: what's this?)

+
licence
+

The data licence string

+
osm_type
+

The OSM type of the location

+
osm_id
+

FIXME

+
boundingbox
+

The coordinates of the bounding box (min and max latitude, min and max longitude)

+
lat
+

The location's latitude

+
lon
+

The location's longitude

+
display_name
+

the location's human readable name

+
class
+

FIXME

+
type
+

FIXME

+
icon
+

FIXME

+
+
+
-error cmdprefix
+

A command prefix to be invoked when encountering errors. Typically these are HTTP errors. +The default setting, active when nothing was specified on object creation, is to print +the errorstring (see below) to stderr. The result of the command prefix is +ignored. Errors thrown by the command prefix are passed to higher levels.

+

The signature of the command prefix is:

+
+
$cmdprefix errorstring
+
+
+
+
+

Methods

+
+
requestor search query
+

This method returns a list of dictionaries, one item per hit for the specified query.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy.html Index: embedded/www/tcllib/files/modules/map/map_slippy.html ================================================================== --- embedded/www/tcllib/files/modules/map/map_slippy.html +++ embedded/www/tcllib/files/modules/map/map_slippy.html @@ -0,0 +1,278 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

map::slippy(n) 0.5 tcllib "Mapping utilities"

+

Name

+

map::slippy - Common code for slippy based map packages

+
+ + +

Description

+

This package provides a number of methods doing things needed by all +types of slippy-based map packages.

+
+

API

+
+
::map::slippy length level
+

This method returns the width/height of a slippy-based map at the +specified zoom level, in pixels. This is, in essence, the result +of

+
+	expr { [tiles $level] * [tile size] }
+
+
+
::map::slippy tiles level
+

This method returns the width/height of a slippy-based map at the +specified zoom level, in tiles.

+
::map::slippy tile size
+

This method returns the width/height of a tile in a slippy-based map, +in pixels.

+
::map::slippy tile valid tile levels ?msgvar?
+

This method checks whether tile described a valid tile in a +slippy-based map containing that many zoom levels. The result is +a boolean value, true if the tile is valid, and false +otherwise. For the latter a message is left in the variable named by +msgvar, should it be specified.

+

A tile identifier as stored in tile is a list containing zoom +level, tile row, and tile column, in this order. The command +essentially checks this, i.e. the syntax, that the zoom level is +between 0 and "levels-1", and that the row/col information is +within the boundaries for the zoom level, i.e. 0 ... +"[tiles $zoom]-1".

+
::map::slippy geo 2tile geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses pure integer numbers for the tile +coordinates, for all geographic coordinates mapping to that tile.

+
::map::slippy geo 2tile.float geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +tile identifier (list containing zoom level, row, and column) at that +level. The tile identifier uses floating point numbers for the tile +coordinates, representing not only the tile the geographic coordinates +map to, but also the fractional location inside of that tile.

+
::map::slippy geo 2point geo
+

Converts a geographical location at a zoom level (geo, a list +containing zoom level, latitude, and longitude, in this order) to a +pixel position (list containing zoom level, y, and x) at that level.

+
::map::slippy tile 2geo tile
+

Converts a tile identifier at a zoom level (tile, list +containing zoom level, row, and column) to a geographical location +(list containing zoom level, latitude, and longitude, in this order) +at that level.

+
::map::slippy tile 2point tile
+

Converts a tile identifier at a zoom level (tile, a list +containing zoom level, row, and column, in this order) to a pixel +position (list containing zoom level, y, and x) at that level.

+
::map::slippy point 2geo point
+

Converts a pixel position at a zoom level (point, list +containing zoom level, y, and x) to a geographical location (list +containing zoom level, latitude, and longitude, in this order) at that +level.

+
::map::slippy point 2tile point
+

Converts a pixel position at a zoom level (point, a list +containing zoom level, y, and x, in this order) to a tile identifier +(list containing zoom level, row, and column) at that level.

+
::map::slippy fit geobox canvdim geobox zmin zmax
+

Calculates the zoom level (whithin the bounds zmin and +zmax) such that geobox (a 4-element list containing the +latitudes and longitudes lat0, lat1, lon0 and lon1 of a geo box, +in this order) fits into a viewport given by canvdim, a +2-element list containing the width and height of the viewport, in +this order.

+
+
+

Coordinate systems

+

The commands of this package operate on three distinct coordinate +systems, which are explained below.

+

Geographic

+

Geographical coordinates are represented by Latitude and +Longitude, each of which is measured in degrees, as they are +essentially angles.

+

Zero longitude is the Greenwich meridian, with +positive values going east, and negative values going +west, for a total range of +/- 180 degrees. Note that +180 and +-180 longitude are the same meridian, opposite to greenwich.

+

zero latitude the Equator, with positive values +going north and negative values going south. While the +true range is +/- 90 degrees the projection used by the package +requires us to cap the range at +/- 85.05112877983284 degrees. This +means that north and south pole are not representable and not part of +any map.

+
+

Tiles

+

While Geographical coordinates of the previous section are +independent of zoom level the tile coordinates are not.

+

Generally the integer part of tile coordinates represent the +row and column number of the tile in question, wheras the fractional +parts signal how far inside the tile the location in question is, with +pure integer coordinates (no fractional part) representing the upper +left corner of the tile.

+

The zero point of the map is at the upper left corner, +regardless of zoom level, with larger coordinates going right (east) +and down (south), and smaller coordinates going left (west) and up +(north). Again regardless of zxoom level.

+

Negative tile coordinates are not allowed.

+

At zoom level 0 the whole map is represented by a single, +putting the geographic zero at 1/2, 1/2 of tile coordinates, and the +range of tile coordinates as [0...1].

+

To go from a zoom level N to the next deeper level N+1 each +tile of level N is split into its four quadrants, which then are the +tiles of level N+1.

+

This means that at zoom level N the map is sliced (horizontally +and vertically) into 2^N stripes, for a total of 4^N tiles, with tile +coordinates ranging from 0 to 2^N+1.

+
+

Pixels/Points

+

pixel coordinates, also called point coordinates are +in essence tile coordinates scaled by the size of +the image representing a tile. This tile size currently has a fixed +value, 256.

+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy_cache.html Index: embedded/www/tcllib/files/modules/map/map_slippy_cache.html ================================================================== --- embedded/www/tcllib/files/modules/map/map_slippy_cache.html +++ embedded/www/tcllib/files/modules/map/map_slippy_cache.html @@ -0,0 +1,195 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

map::slippy::cache(n) 0.2 tcllib "Mapping utilities"

+

Name

+

map::slippy::cache - Management of a tile cache in the local filesystem

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require Tk 8.4
    • +
  • package require img::png
    • +
  • package require map::slippy
    • +
  • package require map::slippy::cache ?0.2?
    • +
+ +
+
+

Description

+

This package provides a class for managing a cache of tiles for +slippy-based maps in the local filesystem.

+
+

API

+
+
::map::slippy::cache cacheName cachedir provider
+

Creates the cache cacheName and configures it with both the path +to the directory contaiing the locally cached tiles (cachedir), +and the command prefix from which it will pull tiles asked for and not +yet known to the cache itself (provider).

+

The result of the command is cacheName.

+
+

Methods

+
+
cacheName valid tile ?msgvar?
+

This method checks the validity of a the given tile identifier. +This is a convenience wrapper to ::map::slippy tile valid and +has the same interface.

+
cacheName exists tile
+

This methods tests whether the cache contains the specified tile +or not. The result is a boolean value, true if the tile is +known, and false otherwise. The tile is identified by a list +containing three elements, zoom level, row, and column number, in this +order.

+
cacheName get tile donecmd
+

This is the main method of the cache, retrieving the image for the +specified tile from the cache. The tile identifier is a list +containing three elements, the zoom level, row, and column number of +the tile, in this order.

+

The command refix donecmd will be invoked when the cache +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e.

+
    +

  1. The string set, the tile, and the image.

    2. +

  2. The string unset, and the tile.

    3. +
+

These two possibilities are used to either signal the image for the +tile, or that the tile has no image defined for it.

+

When the cache has no information about the tile it will invoke the +provider command prefix specified during its construction, +adding three arguments: The string get, the tile, and a +callback into the cache. The latter will be invoked by the provider to +either transfer the image to the cache, or signal that the tile has no +image.

+

When multiple requests for the same tile are made only one request +will be issued to the provider.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html Index: embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html ================================================================== --- embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html +++ embedded/www/tcllib/files/modules/map/map_slippy_fetcher.html @@ -0,0 +1,184 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

map::slippy::fetcher(n) 0.4 tcllib "Mapping utilities"

+

Name

+

map::slippy::fetcher - Accessing a server providing tiles for slippy-based maps

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require Tk 8.4
    • +
  • package require img::png
    • +
  • package require map::slippy
    • +
  • package require map::slippy::fetcher ?0.4?
    • +
+ +
+
+

Description

+

This package provides a class for accessing http servers providing +tiles for slippy-based maps.

+
+

API

+
+
::map::slippy::fetcher fetcherName levels url
+

Creates the fetcher fetcherName and configures it with the +number of zoom levels supported by the tile server, and the +url it is listening on for tile requests.

+

The result of the command is fetcherName.

+
+

Methods

+
+
fetcherName levels
+

This method returns the number of zoom levels supported by the fetcher +object, and the tile server it is accessing.

+
fetcherName tileheight
+

This method returns the height of tiles served, in pixels.

+
fetcherName tilewidth
+

This method returns the width of tiles served, in pixels.

+
fetcherName get tile donecmd
+

This is the main method of the fetcher, retrieving the image for the +specified tile. The tile identifier is a list containing three +elements, the zoom level, row, and column number of the tile, in this +order.

+

The command refix donecmd will be invoked when the fetcher +either knows the image for the tile or that no image will forthcoming. +It will be invoked with either 2 or 3 arguments, i.e.

+
    +

  1. The string set, the tile, and the image.

    2. +

  2. The string unset, and the tile.

    3. +
+

These two possibilities are used to either signal the image for the +tile, or that the tile has no image defined for it.

+
+
+
+ + +
ADDED embedded/www/tcllib/files/modules/mapproj/mapproj.html Index: embedded/www/tcllib/files/modules/mapproj/mapproj.html ================================================================== --- embedded/www/tcllib/files/modules/mapproj/mapproj.html +++ embedded/www/tcllib/files/modules/mapproj/mapproj.html @@ -0,0 +1,447 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

mapproj(n) 0.1 tcllib "Tcl Library"

+

Name

+

mapproj - Map projection routines

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.4?
    • +
  • package require math::interpolate ?1.0?
    • +
  • package require math::special ?0.2.1?
    • +
  • package require mapproj ?1.0?
    • +
+ +
+
+

Description

+

The mapproj package provides a set of procedures for +converting between world co-ordinates (latitude and longitude) and map +co-ordinates on a number of different map projections.

+
+

Commands

+

The following commands convert between world co-ordinates and +map co-ordinates:

+
+
::mapproj::toPlateCarree lambda_0 phi_0 lambda phi
+

Converts to the plate carrée (cylindrical equidistant) +projection.

+
::mapproj::fromPlateCarree lambda_0 phi_0 x y
+

Converts from the plate carrée (cylindrical equidistant) +projection.

+
::mapproj::toCylindricalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the cylindrical equal-area projection.

+
::mapproj::fromCylindricalEqualArea lambda_0 phi_0 x y
+

Converts from the cylindrical equal-area projection.

+
::mapproj::toMercator lambda_0 phi_0 lambda phi
+

Converts to the Mercator (cylindrical conformal) projection.

+
::mapproj::fromMercator lambda_0 phi_0 x y
+

Converts from the Mercator (cylindrical conformal) projection.

+
::mapproj::toMillerCylindrical lambda_0 lambda phi
+

Converts to the Miller Cylindrical projection.

+
::mapproj::fromMillerCylindrical lambda_0 x y
+

Converts from the Miller Cylindrical projection.

+
::mapproj::toSinusoidal lambda_0 phi_0 lambda phi
+

Converts to the sinusoidal (Sanson-Flamsteed) projection. +projection.

+
::mapproj::fromSinusoidal lambda_0 phi_0 x y
+

Converts from the sinusoidal (Sanson-Flamsteed) projection. +projection.

+
::mapproj::toMollweide lambda_0 lambda phi
+

Converts to the Mollweide projection.

+
::mapproj::fromMollweide lambda_0 x y
+

Converts from the Mollweide projection.

+
::mapproj::toEckertIV lambda_0 lambda phi
+

Converts to the Eckert IV projection.

+
::mapproj::fromEckertIV lambda_0 x y
+

Converts from the Eckert IV projection.

+
::mapproj::toEckertVI lambda_0 lambda phi
+

Converts to the Eckert VI projection.

+
::mapproj::fromEckertVI lambda_0 x y
+

Converts from the Eckert VI projection.

+
::mapproj::toRobinson lambda_0 lambda phi
+

Converts to the Robinson projection.

+
::mapproj::fromRobinson lambda_0 x y
+

Converts from the Robinson projection.

+
::mapproj::toCassini lambda_0 phi_0 lambda phi
+

Converts to the Cassini (transverse cylindrical equidistant) +projection.

+
::mapproj::fromCassini lambda_0 phi_0 x y
+

Converts from the Cassini (transverse cylindrical equidistant) +projection.

+
::mapproj::toPeirceQuincuncial lambda_0 lambda phi
+

Converts to the Peirce Quincuncial Projection.

+
::mapproj::fromPeirceQuincuncial lambda_0 x y
+

Converts from the Peirce Quincuncial Projection.

+
::mapproj::toOrthographic lambda_0 phi_0 lambda phi
+

Converts to the orthographic projection.

+
::mapproj::fromOrthographic lambda_0 phi_0 x y
+

Converts from the orthographic projection.

+
::mapproj::toStereographic lambda_0 phi_0 lambda phi
+

Converts to the stereographic (azimuthal conformal) projection.

+
::mapproj::fromStereographic lambda_0 phi_0 x y
+

Converts from the stereographic (azimuthal conformal) projection.

+
::mapproj::toGnomonic lambda_0 phi_0 lambda phi
+

Converts to the gnomonic projection.

+
::mapproj::fromGnomonic lambda_0 phi_0 x y
+

Converts from the gnomonic projection.

+
::mapproj::toAzimuthalEquidistant lambda_0 phi_0 lambda phi
+

Converts to the azimuthal equidistant projection.

+
::mapproj::fromAzimuthalEquidistant lambda_0 phi_0 x y
+

Converts from the azimuthal equidistant projection.

+
::mapproj::toLambertAzimuthalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the Lambert azimuthal equal-area projection.

+
::mapproj::fromLambertAzimuthalEqualArea lambda_0 phi_0 x y
+

Converts from the Lambert azimuthal equal-area projection.

+
::mapproj::toHammer lambda_0 lambda phi
+

Converts to the Hammer projection.

+
::mapproj::fromHammer lambda_0 x y
+

Converts from the Hammer projection.

+
::mapproj::toConicEquidistant lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the conic equidistant projection.

+
::mapproj::fromConicEquidistant lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the conic equidistant projection.

+
::mapproj::toAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the Albers equal-area conic projection.

+
::mapproj::fromAlbersEqualAreaConic lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the Albers equal-area conic projection.

+
::mapproj::toLambertConformalConic lambda_0 phi_0 phi_1 phi_2 lambda phi
+

Converts to the Lambert conformal conic projection.

+
::mapproj::fromLambertConformalConic lambda_0 phi_0 phi_1 phi_2 x y
+

Converts from the Lambert conformal conic projection.

+
+

Among the cylindrical equal-area projections, there are a number of +choices of standard parallels that have names:

+
+
::mapproj::toLambertCylindricalEqualArea lambda_0 phi_0 lambda phi
+

Converts to the Lambert cylindrical equal area projection. (standard parallel +is the Equator.)

+
::mapproj::fromLambertCylindricalEqualArea lambda_0 phi_0 x y
+

Converts from the Lambert cylindrical equal area projection. (standard parallel +is the Equator.)

+
::mapproj::toBehrmann lambda_0 phi_0 lambda phi
+

Converts to the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South)

+
::mapproj::fromBehrmann lambda_0 phi_0 x y
+

Converts from the Behrmann cylindrical equal area projection. (standard parallels +are 30 degrees North and South.)

+
::mapproj::toTrystanEdwards lambda_0 phi_0 lambda phi
+

Converts to the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South)

+
::mapproj::fromTrystanEdwards lambda_0 phi_0 x y
+

Converts from the Trystan Edwards cylindrical equal area projection. (standard parallels +are 37.4 degrees North and South.)

+
::mapproj::toHoboDyer lambda_0 phi_0 lambda phi
+

Converts to the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South)

+
::mapproj::fromHoboDyer lambda_0 phi_0 x y
+

Converts from the Hobo-Dyer cylindrical equal area projection. (standard parallels +are 37.5 degrees North and South.)

+
::mapproj::toGallPeters lambda_0 phi_0 lambda phi
+

Converts to the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South)

+
::mapproj::fromGallPeters lambda_0 phi_0 x y
+

Converts from the Gall-Peters cylindrical equal area projection. (standard parallels +are 45 degrees North and South.)

+
::mapproj::toBalthasart lambda_0 phi_0 lambda phi
+

Converts to the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South)

+
::mapproj::fromBalthasart lambda_0 phi_0 x y
+

Converts from the Balthasart cylindrical equal area projection. (standard parallels +are 50 degrees North and South.)

+
+
+

Arguments

+

The following arguments are accepted by the projection commands:

+
+
lambda
+

Longitude of the point to be projected, in degrees.

+
phi
+

Latitude of the point to be projected, in degrees.

+
lambda_0
+

Longitude of the center of the sheet, in degrees. For many projections, +this figure is also the reference meridian of the projection.

+
phi_0
+

Latitude of the center of the sheet, in degrees. For the azimuthal +projections, this figure is also the latitude of the center of the projection.

+
phi_1
+

Latitude of the first reference parallel, for projections that use reference +parallels.

+
phi_2
+

Latitude of the second reference parallel, for projections that use reference +parallels.

+
x
+

X co-ordinate of a point on the map, in units of Earth radii.

+
y
+

Y co-ordinate of a point on the map, in units of Earth radii.

+
+
+

Results

+

For all of the procedures whose names begin with 'to', the return value +is a list comprising an x co-ordinate and a y co-ordinate. +The co-ordinates are relative to the center of the map sheet to be drawn, +measured in Earth radii at the reference location on the map. +For all of the functions whose names begin with 'from', the return value +is a list comprising the longitude and latitude, in degrees.

+
+

Choosing a projection

+

This package offers a great many projections, because no single projection +is appropriate to all maps. This section attempts to provide guidance +on how to choose a projection.

+

First, consider the type of data that you intend to display on the map. +If the data are directional (e.g., winds, ocean currents, or +magnetic fields) then you need to use a projection that preserves +angles; these are known as conformal projections. Conformal +projections include the Mercator, the Albers azimuthal equal-area, +the stereographic, and the Peirce Quincuncial projection. If the +data are thematic, describing properties of land or water, such +as temperature, population density, land use, or demographics; then +you need a projection that will show these data with the areas on the map +proportional to the areas in real life. These so-called equal area +projections include the various cylindrical equal area projections, +the sinusoidal projection, the Lambert azimuthal equal-area projection, +the Albers equal-area conic projection, and several of the world-map +projections (Miller Cylindrical, Mollweide, Eckert IV, Eckert VI, Robinson, +and Hammer). If the significant factor in your data is distance from a +central point or line (such as air routes), then you will do best with +an equidistant projection such as plate carrée, +Cassini, azimuthal equidistant, or conic equidistant. If direction from +a central point is a critical factor in your data (for instance, +air routes, radio antenna pointing), then you will almost surely want to +use one of the azimuthal projections. Appropriate choices are azimuthal +equidistant, azimuthal equal-area, stereographic, and perhaps orthographic.

+

Next, consider how much of the Earth your map will cover, and the general +shape of the area of interest. For maps of the entire Earth, +the cylindrical equal area, Eckert IV and VI, Mollweide, Robinson, and Hammer +projections are good overall choices. The Mercator projection is traditional, +but the extreme distortions of area at high latitudes make it +a poor choice unless a conformal projection is required. The Peirce +projection is a better choice of conformal projection, having less distortion +of landforms. The Miller Cylindrical is a compromise designed to give +shapes similar to the traditional Mercator, but with less polar stretching. +The Peirce Quincuncial projection shows all the continents with acceptable +distortion if a reference meridian close to +20 degrees is chosen. +The Robinson projection yields attractive maps for things like political +divisions, but should be avoided in presenting scientific data, since other +projections have moe useful geometric properties.

+

If the map will cover a hemisphere, then choose stereographic, +azimuthal-equidistant, Hammer, or Mollweide projections; these all project +the hemisphere into a circle.

+

If the map will cover a large area (at least a few hundred km on a side), +but less than +a hemisphere, then you have several choices. Azimuthal projections +are usually good (choose stereographic, azimuthal equidistant, or +Lambert azimuthal equal-area according to whether shapes, distances from +a central point, or areas are important). Azimuthal projections (and possibly +the Cassini projection) are the only +really good choices for mapping the polar regions.

+

If the large area is in one of the temperate zones and is round or has +a primarily east-west extent, then the conic projections are good choices. +Choose the Lambert conformal conic, the conic equidistant, or the Albers +equal-area conic according to whether shape, distance, or area are the +most important parameters. For any of these, the reference parallels +should be chosen at approximately 1/6 and 5/6 of the range of latitudes +to be displayed. For instance, maps of the 48 coterminous United States +are attractive with reference parallels of 28.5 and 45.5 degrees.

+

If the large area is equatorial and is round or has a primarily east-west +extent, then the Mercator projection is a good choice for a conformal +projection; Lambert cylindrical equal-area and sinusoidal projections are +good equal-area projections; and the plate carrée is a +good equidistant projection.

+

Large areas having a primarily North-South aspect, particularly those +spanning the Equator, need some other choices. The Cassini projection +is a good choice for an equidistant projection (for instance, a Cassini +projection with a central meridian of 80 degrees West produces an +attractive map of the Americas). The cylindrical equal-area, Albers +equal-area conic, sinusoidal, Mollweide and Hammer +projections are possible choices for equal-area projections. +A good conformal projection in this situation is the Transverse +Mercator, which alas, is not yet implemented.

+

Small areas begin to get into a realm where the ellipticity of the +Earth affects the map scale. This package does not attempt to +handle accurate mapping for large-scale topographic maps. If +slight scale errors are acceptable in your application, then any +of the projections appropriate to large areas should work for +small ones as well.

+

There are a few projections that are included for their special +properties. The orthographic projection produces views of the +Earth as seen from space. The gnomonic projection produces a +map on which all great circles (the shortest distance between +two points on the Earth's surface) are rendered as straight lines. +While this projection is useful for navigational planning, it +has extreme distortions of shape and area, and can display +only a limited area of the Earth (substantially less than a hemisphere).

+
+ + +
ADDED embedded/www/tcllib/files/modules/markdown/markdown.html Index: embedded/www/tcllib/files/modules/markdown/markdown.html ================================================================== --- embedded/www/tcllib/files/modules/markdown/markdown.html +++ embedded/www/tcllib/files/modules/markdown/markdown.html @@ -0,0 +1,146 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

markdown(n) 1.0 tcllib "Markdown to HTML Converter"

+

Name

+

markdown - Converts Markdown text to HTML

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require textutil ?0.8?
    • +
+ +
+
+

Description

+

The package Markdown provides a command to convert +Markdown annotated text into HMTL.

+
+
::Markdown::convert markdown
+

This command takes in a block of Markdown text, and returns a block +of HTML.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/math/bigfloat.html Index: embedded/www/tcllib/files/modules/math/bigfloat.html ================================================================== --- embedded/www/tcllib/files/modules/math/bigfloat.html +++ embedded/www/tcllib/files/modules/math/bigfloat.html @@ -0,0 +1,569 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::bigfloat(n) 2.0.1 tcllib "Tcl Math Library"

+

Name

+

math::bigfloat - Arbitrary precision floating-point numbers

+
+ + +

Description

+

The bigfloat package provides arbitrary precision floating-point math +capabilities to the Tcl language. It is designed to work with Tcl 8.5, +but for Tcl 8.4 is provided an earlier version of this package. +See WHAT ABOUT TCL 8.4 ? for more explanations. +By convention, we will talk about the numbers treated in this library as :

+
    +

  • BigFloat for floating-point numbers of arbitrary length.

    • +

  • integers for arbitrary length signed integers, just as basic integers since Tcl 8.5.

    • +
+

Each BigFloat is an interval, namely [m-d, m+d], +where m is the mantissa and d the uncertainty, representing the +limitation of that number's precision. +This is why we call such mathematics interval computations. +Just take an example in physics : when you measure a temperature, not all +digits you read are significant. Sometimes you just cannot trust all digits - not to mention if doubles (f.p. numbers) can handle all these digits. +BigFloat can handle this problem - trusting the digits you get - plus the ability to store numbers with an arbitrary precision. +BigFloats are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to :

+
    +

  • perform math operations on BigFloats and (optionnaly) with integers.

    • +

  • convert BigFloats from their internal representations to strings, and vice versa.

    • +
+
+

INTRODUCTION

+
+
fromstr number ?trailingZeros?
+

Converts number into a BigFloat. Its precision +is at least the number of digits provided by number. +If the number contains only digits and eventually a minus sign, it is considered as +an integer. Subsequently, no conversion is done at all.

+

trailingZeros - the number of zeros to append at the end of the floating-point number +to get more precision. It cannot be applied to an integer.

+
+# x and y are BigFloats : the first string contained a dot, and the second an e sign
+set x [fromstr -1.000000]
+set y [fromstr 2000e30]
+# let's see how we get integers
+set t 20000000000000
+# the old way (package 1.2) is still supported for backwards compatibility :
+set m [fromstr 10000000000]
+# but we do not need fromstr for integers anymore
+set n -39
+# t, m and n are integers
+
+

The number's last digit is considered by the procedure to be true at +/-1, +For example, 1.00 is the interval [0.99, 1.01], +and 0.43 the interval [0.42, 0.44]. +The Pi constant may be approximated by the number "3.1415". +This string could be considered as the interval [3.1414 , 3.1416] by fromstr. +So, when you mean 1.0 as a double, you may have to write 1.000000 to get enough precision. +To learn more about this subject, see PRECISION.

+

For example :

+
+set x [fromstr 1.0000000000]
+# the next line does the same, but smarter
+set y [fromstr 1. 10]
+
+
+
tostr ?-nosci? number
+

Returns a string form of a BigFloat, in which all digits are exacts. +All exact digits means a rounding may occur, for example to zero, +if the uncertainty interval does not clearly show the true digits. +number may be an integer, causing the command to return exactly the input argument. +With the -nosci option, the number returned is never shown in scientific +notation, i.e. not like '3.4523e+5' but like '345230.'.

+
+puts [tostr [fromstr 0.99999]] ;# 1.0000
+puts [tostr [fromstr 1.00001]] ;# 1.0000
+puts [tostr [fromstr 0.002]] ;# 0.e-2
+
+

See PRECISION for that matter. +See also iszero for how to detect zeros, which is useful when performing a division.

+
fromdouble double ?decimals?
+

Converts a double (a simple floating-point value) to a BigFloat, with +exactly decimals digits. Without the decimals argument, +it behaves like fromstr. +Here, the only important feature you might care of is the ability +to create BigFloats with a fixed number of decimals.

+
+tostr [fromstr 1.111 4]
+# returns : 1.111000 (3 zeros)
+tostr [fromdouble 1.111 4]
+# returns : 1.111
+
+
+
todouble number
+

Returns a double, that may be used in expr, +from a BigFloat.

+
isInt number
+

Returns 1 if number is an integer, 0 otherwise.

+
isFloat number
+

Returns 1 if number is a BigFloat, 0 otherwise.

+
int2float integer ?decimals?
+

Converts an integer to a BigFloat with decimals trailing zeros. +The default, and minimal, number of decimals is 1. +When converting back to string, one decimal is lost:

+
+set n 10
+set x [int2float $n]; # like fromstr 10.0
+puts [tostr $x]; # prints "10."
+set x [int2float $n 3]; # like fromstr 10.000
+puts [tostr $x]; # prints "10.00"
+
+
+
+
+

ARITHMETICS

+
+
add x y
+
+
sub x y
+
+
mul x y
+

Return the sum, difference and product of x by y. +x - may be either a BigFloat or an integer +y - may be either a BigFloat or an integer +When both are integers, these commands behave like expr.

+
div x y
+
+
mod x y
+

Return the quotient and the rest of x divided by y. +Each argument (x and y) can be either a BigFloat or an integer, +but you cannot divide an integer by a BigFloat +Divide by zero throws an error.

+
abs x
+

Returns the absolute value of x

+
opp x
+

Returns the opposite of x

+
pow x n
+

Returns x taken to the nth power. +It only works if n is an integer. +x might be a BigFloat or an integer.

+
+
+

COMPARISONS

+
+
iszero x
+

Returns 1 if x is :

+
    +

  • a BigFloat close enough to zero to raise "divide by zero".

    • +

  • the integer 0.

    • +
+

See here how numbers that are close to zero are converted to strings:

+
+tostr [fromstr 0.001] ; # -> 0.e-2
+tostr [fromstr 0.000000] ; # -> 0.e-5
+tostr [fromstr -0.000001] ; # -> 0.e-5
+tostr [fromstr 0.0] ; # -> 0.
+tostr [fromstr 0.002] ; # -> 0.e-2
+set a [fromstr 0.002] ; # uncertainty interval : 0.001, 0.003
+tostr  $a ; # 0.e-2
+iszero $a ; # false
+set a [fromstr 0.001] ; # uncertainty interval : 0.000, 0.002
+tostr  $a ; # 0.e-2
+iszero $a ; # true
+
+
+
equal x y
+

Returns 1 if x and y are equal, 0 elsewhere.

+
compare x y
+

Returns 0 if both BigFloat arguments are equal, +1 if x is greater than y, +and -1 if x is lower than y. +You would not be able to compare an integer to a BigFloat : +the operands should be both BigFloats, or both integers.

+
+
+

ANALYSIS

+
+
sqrt x
+
+
log x
+
+
exp x
+
+
cos x
+
+
sin x
+
+
tan x
+
+
cotan x
+
+
acos x
+
+
asin x
+
+
atan x
+
+
cosh x
+
+
sinh x
+
+
tanh x
+

The above functions return, respectively, the following : +square root, logarithm, exponential, cosine, sine, +tangent, cotangent, arc cosine, arc sine, arc tangent, hyperbolic +cosine, hyperbolic sine, hyperbolic tangent, of a BigFloat named x.

+
pi n
+

Returns a BigFloat representing the Pi constant with n digits after the dot. +n is a positive integer.

+
rad2deg radians
+
+
deg2rad degrees
+

radians - angle expressed in radians (BigFloat)

+

degrees - angle expressed in degrees (BigFloat)

+

Convert an angle from radians to degrees, and vice versa.

+
+
+

ROUNDING

+
+
round x
+
+
ceil x
+
+
floor x
+

The above functions return the x BigFloat, +rounded like with the same mathematical function in expr, +and returns it as an integer.

+
+
+

PRECISION

+

How do conversions work with precision ?

+
    +

  • When a BigFloat is converted from string, the internal representation +holds its uncertainty as 1 at the level of the last digit.

    • +

  • During computations, the uncertainty of each result +is internally computed the closest to the reality, thus saving the memory used.

    • +

  • When converting back to string, the digits that are printed +are not subject to uncertainty. However, some rounding is done, as not doing so +causes severe problems.

    • +
+

Uncertainties are kept in the internal representation of the number ; +it is recommended to use tostr only for outputting data (on the screen or in a file), +and NEVER call fromstr with the result of tostr. +It is better to always keep operands in their internal representation. +Due to the internals of this library, the uncertainty interval may be slightly +wider than expected, but this should not cause false digits.

+

Now you may ask this question : What precision am I going to get +after calling add, sub, mul or div? +First you set a number from the string representation and, +by the way, its uncertainty is set:

+
+set a [fromstr 1.230]
+# $a belongs to [1.229, 1.231]
+set a [fromstr 1.000]
+# $a belongs to [0.999, 1.001]
+# $a has a relative uncertainty of 0.1% : 0.001(the uncertainty)/1.000(the medium value)
+
+

The uncertainty of the sum, or the difference, of two numbers, is the sum +of their respective uncertainties.

+
+set a [fromstr 1.230]
+set b [fromstr 2.340]
+set sum [add $a $b]]
+# the result is : [3.568, 3.572] (the last digit is known with an uncertainty of 2)
+tostr $sum ; # 3.57
+
+

But when, for example, we add or substract an integer to a BigFloat, +the relative uncertainty of the result is unchanged. So it is desirable +not to convert integers to BigFloats:

+
+set a [fromstr 0.999999999]
+# now something dangerous
+set b [fromstr 2.000]
+# the result has only 3 digits
+tostr [add $a $b]
+# how to keep precision at its maximum
+puts [tostr [add $a 2]]
+
+

For multiplication and division, the relative uncertainties of the product +or the quotient, is the sum of the relative uncertainties of the operands. +Take care of division by zero : check each divider with iszero.

+
+set num [fromstr 4.00]
+set denom [fromstr 0.01]
+puts [iszero $denom];# true
+set quotient [div $num $denom];# error : divide by zero
+# opposites of our operands
+puts [compare $num [opp $num]]; # 1
+puts [compare $denom [opp $denom]]; # 0 !!!
+# No suprise ! 0 and its opposite are the same...
+
+

Effects of the precision of a number considered equal to zero +to the cos function:

+
+puts [tostr [cos [fromstr 0. 10]]]; # -> 1.000000000
+puts [tostr [cos [fromstr 0. 5]]]; # -> 1.0000
+puts [tostr [cos [fromstr 0e-10]]]; # -> 1.000000000
+puts [tostr [cos [fromstr 1e-10]]]; # -> 1.000000000
+
+

BigFloats with different internal representations may be converted +to the same string.

+

For most analysis functions (cosine, square root, logarithm, etc.), determining the precision +of the result is difficult. +It seems however that in many cases, the loss of precision in the result +is of one or two digits. +There are some exceptions : for example,

+
+tostr [exp [fromstr 100.0 10]]
+# returns : 2.688117142e+43 which has only 10 digits of precision, although the entry
+# has 14 digits of precision.
+
+
+

WHAT ABOUT TCL 8.4 ?

+

If your setup do not provide Tcl 8.5 but supports 8.4, the package can still be loaded, +switching back to math::bigfloat 1.2. Indeed, an important function introduced in Tcl 8.5 +is required - the ability to handle bignums, that we can do with expr. +Before 8.5, this ability was provided by several packages, +including the pure-Tcl math::bignum package provided by tcllib. +In this case, all you need to know, is that arguments to the commands explained here, +are expected to be in their internal representation. +So even with integers, you will need to call fromstr +and tostr in order to convert them between string and internal representations.

+
+#
+# with Tcl 8.5
+# ============
+set a [pi 20]
+# round returns an integer and 'everything is a string' applies to integers
+# whatever big they are
+puts [round [mul $a 10000000000]]
+#
+# the same with Tcl 8.4
+# =====================
+set a [pi 20]
+# bignums (arbitrary length integers) need a conversion hook
+set b [fromstr 10000000000]
+# round returns a bignum:
+# before printing it, we need to convert it with 'tostr'
+puts [tostr [round [mul $a $b]]]
+
+
+

NAMESPACES AND OTHER PACKAGES

+

We have not yet discussed about namespaces +because we assumed that you had imported public commands into the global namespace, +like this:

+
+namespace import ::math::bigfloat::*
+
+

If you matter much about avoiding names conflicts, +I considere it should be resolved by the following :

+
+package require math::bigfloat
+# beware: namespace ensembles are not available in Tcl 8.4
+namespace eval ::math::bigfloat {namespace ensemble create -command ::bigfloat}
+# from now, the bigfloat command takes as subcommands all original math::bigfloat::* commands
+set a [bigfloat sub [bigfloat fromstr 2.000] [bigfloat fromstr 0.530]]
+puts [bigfloat tostr $a]
+
+
+

EXAMPLES

+

Guess what happens when you are doing some astronomy. Here is an example :

+
+# convert acurrate angles with a millisecond-rated accuracy
+proc degree-angle {degrees minutes seconds milliseconds} {
+    set result 0
+    set div 1
+    foreach factor {1 1000 60 60} var [list $milliseconds $seconds $minutes $degrees] {
+        # we convert each entry var into milliseconds
+        set div [expr {$div*$factor}]
+        incr result [expr {$var*$div}]
+    }
+    return [div [int2float $result] $div]
+}
+# load the package
+package require math::bigfloat
+namespace import ::math::bigfloat::*
+# work with angles : a standard formula for navigation (taking bearings)
+set angle1 [deg2rad [degree-angle 20 30 40   0]]
+set angle2 [deg2rad [degree-angle 21  0 50 500]]
+set opposite3 [deg2rad [degree-angle 51  0 50 500]]
+set sinProduct [mul [sin $angle1] [sin $angle2]]
+set cosProduct [mul [cos $angle1] [cos $angle2]]
+set angle3 [asin [add [mul $sinProduct [cos $opposite3]] $cosProduct]]
+puts "angle3 : [tostr [rad2deg $angle3]]"
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: bignum :: float of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/bignum.html Index: embedded/www/tcllib/files/modules/math/bignum.html ================================================================== --- embedded/www/tcllib/files/modules/math/bignum.html +++ embedded/www/tcllib/files/modules/math/bignum.html @@ -0,0 +1,343 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::bignum(n) 3.1 tcllib "Tcl Math Library"

+

Name

+

math::bignum - Arbitrary precision integer numbers

+
+ + +

Description

+

The bignum package provides arbitrary precision integer math +(also known as "big numbers") capabilities to the Tcl language. +Big numbers are internally represented at Tcl lists: this +package provides a set of procedures operating against +the internal representation in order to:

+
    +

  • perform math operations

    • +

  • convert bignums from the internal representation to a string in +the desired radix and vice versa.

    • +
+

But the two constants "0" and "1" are automatically converted to +the internal representation, in order to easily compare a number to zero, +or increment a big number.

+

The bignum interface is opaque, so +operations on bignums that are not returned by procedures +in this package (but created by hand) may lead to unspecified behaviours. +It's safe to treat bignums as pure values, so there is no need +to free a bignum, or to duplicate it via a special operation.

+
+

EXAMPLES

+

This section shows some simple example. This library being just +a way to perform math operations, examples may be the simplest way +to learn how to work with it. Consult the API section of +this man page for information about individual procedures.

+
+    package require math::bignum
+    # Multiplication of two bignums
+    set a [::math::bignum::fromstr 88888881111111]
+    set b [::math::bignum::fromstr 22222220000000]
+    set c [::math::bignum::mul $a $b]
+    puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000
+    set c [::math::bignum::sqrt $c]
+    puts [::math::bignum::tostr $c] ; # => will output 44444440277777
+    # From/To string conversion in different radix
+    set a [::math::bignum::fromstr 1100010101010111001001111010111 2]
+    puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7
+    # Factorial example
+    proc fact n {
+        # fromstr is not needed for 0 and 1
+        set z 1
+        for {set i 2} {$i <= $n} {incr i} {
+            set z [::math::bignum::mul $z [::math::bignum::fromstr $i]]
+        }
+        return $z
+    }
+    puts [::math::bignum::tostr [fact 100]]
+
+
+

API

+
+
::math::bignum::fromstr string ?radix?
+

Convert string into a bignum. If radix is omitted or zero, +the string is interpreted in hex if prefixed with +0x, in octal if prefixed with ox, +in binary if it's pefixed with bx, as a number in +radix 10 otherwise. If instead the radix argument +is specified in the range 2-36, the string is interpreted +in the given radix. Please note that this conversion is +not needed for two constants : 0 and 1. (see the example)

+
::math::bignum::tostr bignum ?radix?
+

Convert bignum into a string representing the number +in the specified radix. If radix is omitted, the +default is 10.

+
::math::bignum::sign bignum
+

Return the sign of the bignum. +The procedure returns 0 if the number is positive, 1 if it's negative.

+
::math::bignum::abs bignum
+

Return the absolute value of the bignum.

+
::math::bignum::cmp a b
+

Compare the two bignums a and b, returning 0 if a == b, +1 if a > b, and -1 if a < b.

+
::math::bignum::iszero bignum
+

Return true if bignum value is zero, otherwise false is returned.

+
::math::bignum::lt a b
+

Return true if a < b, otherwise false is returned.

+
::math::bignum::le a b
+

Return true if a <= b, otherwise false is returned.

+
::math::bignum::gt a b
+

Return true if a > b, otherwise false is returned.

+
::math::bignum::ge a b
+

Return true if a >= b, otherwise false is returned.

+
::math::bignum::eq a b
+

Return true if a == b, otherwise false is returned.

+
::math::bignum::ne a b
+

Return true if a != b, otherwise false is returned.

+
::math::bignum::isodd bignum
+

Return true if bignum is odd.

+
::math::bignum::iseven bignum
+

Return true if bignum is even.

+
::math::bignum::add a b
+

Return the sum of the two bignums a and b.

+
::math::bignum::sub a b
+

Return the difference of the two bignums a and b.

+
::math::bignum::mul a b
+

Return the product of the two bignums a and b. +The implementation uses Karatsuba multiplication if both +the numbers are bigger than a given threshold, otherwise +the direct algorith is used.

+
::math::bignum::divqr a b
+

Return a two-elements list containing as first element +the quotient of the division between the two bignums +a and b, and the remainder of the division as second element.

+
::math::bignum::div a b
+

Return the quotient of the division between the two +bignums a and b.

+
::math::bignum::rem a b
+

Return the remainder of the division between the two +bignums a and b.

+
::math::bignum::mod n m
+

Return n modulo m. This operation is +called modular reduction.

+
::math::bignum::pow base exp
+

Return base raised to the exponent exp.

+
::math::bignum::powm base exp m
+

Return base raised to the exponent exp, +modulo m. This function is often used in the field +of cryptography.

+
::math::bignum::sqrt bignum
+

Return the integer part of the square root of bignum

+
::math::bignum::rand bits
+

Return a random number of at most bits bits. +The returned number is internally generated using Tcl's expr rand() +function and is not suitable where an unguessable and cryptographically +secure random number is needed.

+
::math::bignum::lshift bignum bits
+

Return the result of left shifting bignum's binary +representation of bits positions on the left. +This is equivalent to multiplying by 2^bits but much faster.

+
::math::bignum::rshift bignum bits
+

Return the result of right shifting bignum's binary +representation of bits positions on the right. +This is equivalent to dividing by 2^bits but much faster.

+
::math::bignum::bitand a b
+

Return the result of doing a bitwise AND operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::bitor a b
+

Return the result of doing a bitwise OR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::bitxor a b
+

Return the result of doing a bitwise XOR operation on a +and b. The operation is restricted to positive numbers, +including zero. When negative numbers are provided as +arguments the result is undefined.

+
::math::bignum::setbit bignumVar bit
+

Set the bit at bit position to 1 in the bignum stored +in the variable bignumVar. Bit 0 is the least significant.

+
::math::bignum::clearbit bignumVar bit
+

Set the bit at bit position to 0 in the bignum stored +in the variable bignumVar. Bit 0 is the least significant.

+
::math::bignum::testbit bignum bit
+

Return true if the bit at the bit position of bignum +is on, otherwise false is returned. If bit is out of +range, it is considered as set to zero.

+
::math::bignum::bits bignum
+

Return the number of bits needed to represent bignum in radix 2.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: bignum of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/calculus.html Index: embedded/www/tcllib/files/modules/math/calculus.html ================================================================== --- embedded/www/tcllib/files/modules/math/calculus.html +++ embedded/www/tcllib/files/modules/math/calculus.html @@ -0,0 +1,498 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::calculus(n) 0.8.1 tcllib "Tcl Math Library"

+

Name

+

math::calculus - Integration and ordinary differential equations

+
+ + +

Description

+

This package implements several simple mathematical algorithms:

+
    +

  • The integration of a function over an interval

    • +

  • The numerical integration of a system of ordinary differential +equations.

    • +

  • Estimating the root(s) of an equation of one variable.

    • +
+

The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, well-known +algorithms have been used in a straightforward manner.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::math::calculus::integral begin end nosteps func
+

Determine the integral of the given function using the Simpson +rule. The interval for the integration is [begin, end]. +The remaining arguments are:

+
+
nosteps
+

Number of steps in which the interval is divided.

+
func
+

Function to be integrated. It should take one single argument.

+
+
::math::calculus::integralExpr begin end nosteps expression
+

Similar to the previous proc, this one determines the integral of +the given expression using the Simpson rule. +The interval for the integration is [begin, end]. +The remaining arguments are:

+
+
nosteps
+

Number of steps in which the interval is divided.

+
expression
+

Expression to be integrated. It should +use the variable "x" as the only variable (the "integrate")

+
+
::math::calculus::integral2D xinterval yinterval func
+
+
::math::calculus::integral2D_accurate xinterval yinterval func
+

The commands integral2D and integral2D_accurate calculate the +integral of a function of two variables over the rectangle given by the +first two arguments, each a list of three items, the start and +stop interval for the variable and the number of steps.

+

The command integral2D evaluates the function at the centre of +each rectangle, whereas the command integral2D_accurate uses a +four-point quadrature formula. This results in an exact integration of +polynomials of third degree or less.

+

The function must take two arguments and return the function +value.

+
::math::calculus::integral3D xinterval yinterval zinterval func
+
+
::math::calculus::integral3D_accurate xinterval yinterval zinterval func
+

The commands integral3D and integral3D_accurate are the +three-dimensional equivalent of integral2D and integral3D_accurate. +The function func takes three arguments and is integrated over the block in +3D space given by three intervals.

+
::math::calculus::qk15 xstart xend func nosteps
+

Determine the integral of the given function using the Gauss-Kronrod 15 points quadrature rule. +The returned value is the estimate of the integral over the interval [xstart, xend]. +The remaining arguments are:

+
+
func
+

Function to be integrated. It should take one single argument.

+
?nosteps?
+

Number of steps in which the interval is divided. Defaults to 1.

+
+
::math::calculus::qk15_detailed xstart xend func nosteps
+

Determine the integral of the given function using the Gauss-Kronrod 15 points quadrature rule. +The interval for the integration is [xstart, xend]. +The procedure returns a list of four values:

+
    +

  • The estimate of the integral over the specified interval (I).

    • +

  • An estimate of the absolute error in I.

    • +

  • The estimate of the integral of the absolute value of the function over the interval.

    • +

  • The estimate of the integral of the absolute value of the function minus its mean over the interval.

    • +
+

The remaining arguments are:

+
+
func
+

Function to be integrated. It should take one single argument.

+
?nosteps?
+

Number of steps in which the interval is divided. Defaults to 1.

+
+
::math::calculus::eulerStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Euler's.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::heunStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Heun's.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::rungeKuttaStep t tstep xvec func
+

Set a single step in the numerical integration of a system of +differential equations. The method used is Runge-Kutta 4th +order.

+
+
t
+

Value of the independent variable (typically time) +at the beginning of the step.

+
tstep
+

Step size for the independent variable.

+
xvec
+

List (vector) of dependent values

+
func
+

Function of t and the dependent values, returning +a list of the derivatives of the dependent values. (The lengths of +xvec and the return value of "func" must match).

+
+
::math::calculus::boundaryValueSecondOrder coeff_func force_func leftbnd rightbnd nostep
+

Solve a second order linear differential equation with boundary +values at two sides. The equation has to be of the form (the +"conservative" form):

+
+         d      dy     d
+         -- A(x)--  +  -- B(x)y + C(x)y  =  D(x)
+         dx     dx     dx
+
+

Ordinarily, such an equation would be written as:

+
+             d2y        dy
+         a(x)---  + b(x)-- + c(x) y  =  D(x)
+             dx2        dx
+
+

The first form is easier to discretise (by integrating over a +finite volume) than the second form. The relation between the two +forms is fairly straightforward:

+
+         A(x)  =  a(x)
+         B(x)  =  b(x) - a'(x)
+         C(x)  =  c(x) - B'(x)  =  c(x) - b'(x) + a''(x)
+
+

Because of the differentiation, however, it is much easier to ask +the user to provide the functions A, B and C directly.

+
+
coeff_func
+

Procedure returning the three coefficients +(A, B, C) of the equation, taking as its one argument the x-coordinate.

+
force_func
+

Procedure returning the right-hand side +(D) as a function of the x-coordinate.

+
leftbnd
+

A list of two values: the x-coordinate of the +left boundary and the value at that boundary.

+
rightbnd
+

A list of two values: the x-coordinate of the +right boundary and the value at that boundary.

+
nostep
+

Number of steps by which to discretise the +interval. +The procedure returns a list of x-coordinates and the approximated +values of the solution.

+
+
::math::calculus::solveTriDiagonal acoeff bcoeff ccoeff dvalue
+

Solve a system of linear equations Ax = b with A a tridiagonal +matrix. Returns the solution as a list.

+
+
acoeff
+

List of values on the lower diagonal

+
bcoeff
+

List of values on the main diagonal

+
ccoeff
+

List of values on the upper diagonal

+
dvalue
+

List of values on the righthand-side

+
+
::math::calculus::newtonRaphson func deriv initval
+

Determine the root of an equation given by

+
+    func(x) = 0
+
+

using the method of Newton-Raphson. The procedure takes the following +arguments:

+
+
func
+

Procedure that returns the value the function at x

+
deriv
+

Procedure that returns the derivative of the function at x

+
initval
+

Initial value for x

+
+
::math::calculus::newtonRaphsonParameters maxiter tolerance
+

Set the numerical parameters for the Newton-Raphson method:

+
+
maxiter
+

Maximum number of iteration steps (defaults to 20)

+
tolerance
+

Relative precision (defaults to 0.001)

+
+
::math::calculus::regula_falsi f xb xe eps
+

Return an estimate of the zero or one of the zeros of the function +contained in the interval [xb,xe]. The error in this estimate is of the +order of eps*abs(xe-xb), the actual error may be slightly larger.

+

The method used is the so-called regula falsi or +false position method. It is a straightforward implementation. +The method is robust, but requires that the interval brackets a zero or +at least an uneven number of zeros, so that the value of the function at +the start has a different sign than the value at the end.

+

In contrast to Newton-Raphson there is no need for the computation of +the function's derivative.

+
+
command f
+

Name of the command that evaluates the function for +which the zero is to be returned

+
float xb
+

Start of the interval in which the zero is supposed +to lie

+
float xe
+

End of the interval

+
float eps
+

Relative allowed error (defaults to 1.0e-4)

+
+
+

Notes:

+

Several of the above procedures take the names of procedures as +arguments. To avoid problems with the visibility of these +procedures, the fully-qualified name of these procedures is determined +inside the calculus routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance:

+
+    namespace eval ::mySpace {
+       namespace export calcfunc
+       proc calcfunc { x } { return $x }
+    }
+    #
+    # Use a fully-qualified name
+    #
+    namespace eval ::myCalc {
+       proc detIntegral { begin end } {
+          return [integral $begin $end 100 ::mySpace::calcfunc]
+       }
+    }
+    #
+    # Import the name
+    #
+    namespace eval ::myCalc {
+       namespace import ::mySpace::calcfunc
+       proc detIntegral { begin end } {
+          return [integral $begin $end 100 calcfunc]
+       }
+    }
+
+

Enhancements for the second-order boundary value problem:

+
    +

  • Other types of boundary conditions (zero gradient, zero flux)

    • +

  • Other schematisation of the first-order term (now central +differences are used, but upstream differences might be useful too).

    • +
+
+

EXAMPLES

+

Let us take a few simple examples:

+

Integrate x over the interval [0,100] (20 steps):

+
+proc linear_func { x } { return $x }
+puts "Integral: [::math::calculus::integral 0 100 20 linear_func]"
+
+

For simple functions, the alternative could be:

+
+puts "Integral: [::math::calculus::integralExpr 0 100 20 {$x}]"
+
+

Do not forget the braces!

+

The differential equation for a dampened oscillator:

+
+x'' + rx' + wx = 0
+
+

can be split into a system of first-order equations:

+
+x' = y
+y' = -ry - wx
+
+

Then this system can be solved with code like this:

+
+proc dampened_oscillator { t xvec } {
+   set x  [lindex $xvec 0]
+   set x1 [lindex $xvec 1]
+   return [list $x1 [expr {-$x1-$x}]]
+}
+set xvec   { 1.0 0.0 }
+set t      0.0
+set tstep  0.1
+for { set i 0 } { $i < 20 } { incr i } {
+   set result [::math::calculus::eulerStep $t $tstep $xvec dampened_oscillator]
+   puts "Result ($t): $result"
+   set t      [expr {$t+$tstep}]
+   set xvec   $result
+}
+
+

Suppose we have the boundary value problem:

+
+    Dy'' + ky = 0
+    x = 0: y = 1
+    x = L: y = 0
+
+

This boundary value problem could originate from the diffusion of a +decaying substance.

+

It can be solved with the following fragment:

+
+   proc coeffs { x } { return [list $::Diff 0.0 $::decay] }
+   proc force  { x } { return 0.0 }
+   set Diff   1.0e-2
+   set decay  0.0001
+   set length 100.0
+   set y [::math::calculus::boundaryValueSecondOrder \
+      coeffs force {0.0 1.0} [list $length 0.0] 100]
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

romberg

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/combinatorics.html Index: embedded/www/tcllib/files/modules/math/combinatorics.html ================================================================== --- embedded/www/tcllib/files/modules/math/combinatorics.html +++ embedded/www/tcllib/files/modules/math/combinatorics.html @@ -0,0 +1,197 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::combinatorics(n) 1.2.3 tcllib "Tcl Math Library"

+

Name

+

math::combinatorics - Combinatorial functions in the Tcl Math Library

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require math ?1.2.3?
    • +
+ +
+
+

Description

+

The math package contains implementations of several +functions useful in combinatorial problems.

+
+

COMMANDS

+
+
::math::ln_Gamma z
+

Returns the natural logarithm of the Gamma function for the argument +z.

+

The Gamma function is defined as the improper integral from zero to +positive infinity of

+
+  t**(x-1)*exp(-t) dt
+
+

The approximation used in the Tcl Math Library is from Lanczos, +ISIAM J. Numerical Analysis, series B, volume 1, p. 86. +For "x > 1", the absolute error of the result is claimed to be +smaller than 5.5*10**-10 -- that is, the resulting value of Gamma when

+
+  exp( ln_Gamma( x) )
+
+

is computed is expected to be precise to better than nine significant +figures.

+
::math::factorial x
+

Returns the factorial of the argument x.

+

For integer x, 0 <= x <= 12, an exact integer result is +returned.

+

For integer x, 13 <= x <= 21, an exact floating-point +result is returned on machines with IEEE floating point.

+

For integer x, 22 <= x <= 170, the result is exact to 1 +ULP.

+

For real x, x >= 0, the result is approximated by +computing Gamma(x+1) using the ::math::ln_Gamma +function, and the result is expected to be precise to better than nine +significant figures.

+

It is an error to present x <= -1 or x > 170, or a value +of x that is not numeric.

+
::math::choose n k
+

Returns the binomial coefficient C(n, k)

+
+   C(n,k) = n! / k! (n-k)!
+
+

If both parameters are integers and the result fits in 32 bits, the +result is rounded to an integer.

+

Integer results are exact up to at least n = 34. Floating point +results are precise to better than nine significant figures.

+
::math::Beta z w
+

Returns the Beta function of the parameters z and w.

+
+   Beta(z,w) = Beta(w,z) = Gamma(z) * Gamma(w) / Gamma(z+w)
+
+

Results are returned as a floating point number precise to better than +nine significant digits provided that w and z are both at +least 1.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/constants.html Index: embedded/www/tcllib/files/modules/math/constants.html ================================================================== --- embedded/www/tcllib/files/modules/math/constants.html +++ embedded/www/tcllib/files/modules/math/constants.html @@ -0,0 +1,244 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::constants(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::constants - Mathematical and numerical constants

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.3?
    • +
  • package require math::constants ?1.0.2?
    • +
+ +
+
+

Description

+

This package defines some common mathematical and numerical constants. +By using the package you get consistent values for numbers like pi and +ln(10).

+

It defines two commands:

+
    +

  • One for importing the constants

    • +

  • One for reporting which constants are defined and what values they +actually have.

    • +
+

The motivation for this package is that quite often, with +(mathematical) computations, you need a good approximation to, say, +the ratio of degrees to radians. You can, of course, define this +like:

+
+    variable radtodeg [expr {180.0/(4.0*atan(1.0))}]
+
+

and use the variable radtodeg whenever you need the conversion.

+

This has two drawbacks:

+
    +

  • You need to remember the proper formula or value and that is +error-prone.

    • +

  • Especially with the use of mathematical functions like atan +you assume that they have been accurately implemented. This is seldom or +never the case and for each platform you can get subtle differences.

    • +
+

Here is the way you can do it with the math::constants package:

+
+    package require math::constants
+    ::math::constants::constants radtodeg degtorad
+
+

which creates two variables, radtodeg and (its reciprocal) degtorad +in the calling namespace.

+

Constants that have been defined (their values are mostly taken +from mathematical tables with more precision than usually can be +handled) include:

+
    +

  • basic constants like pi, e, gamma (Euler's constant)

    • +

  • derived values like ln(10) and sqrt(2)

    • +

  • purely numerical values such as 1/3 that are included for convenience +and for the fact that certain seemingly trivial computations like:

    +
    +    set value [expr {3.0*$onethird}]
+
    +

    give exactly the value you expect (if IEEE arithmetic is +available).

    • +
+

The full set of named constants is listed in section Constants.

+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::constants::constants args
+

Import the constants whose names are given as arguments

+
::math::constants::print-constants args
+

Print the constants whose names are given as arguments on the screen +(name, value and description) or, if no arguments are given, print all +defined constants. This is mainly a convenience procedure.

+
+
+

Constants

+
+
pi
+

Ratio of circle circumference to diameter

+
e
+

Base for natural logarithm

+
ln10
+

Natural logarithm of 10

+
phi
+

Golden ratio

+
gamma
+

Euler's constant

+
sqrt2
+

Square root of 2

+
thirdrt2
+

One-third power of 2

+
sqrt3
+

Square root of 3

+
radtodeg
+

Conversion from radians to degrees

+
degtorad
+

Conversion from degrees to radians

+
onethird
+

One third (0.3333....)

+
twothirds
+

Two thirds (0.6666....)

+
onesixth
+

One sixth (0.1666....)

+
huge
+

(Approximately) largest number

+
tiny
+

(Approximately) smallest number not equal zero

+
eps
+

Smallest number such that 1+eps != 1

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: constants of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/decimal.html Index: embedded/www/tcllib/files/modules/math/decimal.html ================================================================== --- embedded/www/tcllib/files/modules/math/decimal.html +++ embedded/www/tcllib/files/modules/math/decimal.html @@ -0,0 +1,320 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::decimal(n) 1.0.3 tcllib "Tcl Decimal Arithmetic Library"

+

Name

+

math::decimal - General decimal arithmetic

+
+ + +

Description

+

The decimal package provides decimal arithmetic support for both limited +precision floating point and arbitrary precision floating point. +Additionally, integer arithmetic is supported.

+

More information and the specifications on which this package depends can be +found on the general decimal arithmetic page at http://speleotrove.com/decimal +This package provides for:

+
    +

  • A new data type decimal which is represented as a list containing sign, +mantissa and exponent.

    • +

  • Arithmetic operations on those decimal numbers such as addition, subtraction, +multiplication, etc...

    • +
+

Numbers are converted to decimal format using the operation ::math::decimal::fromstr.

+

Numbers are converted back to string format using the operation +::math::decimal::tostr.

+
+

EXAMPLES

+

This section shows some simple examples. Since the purpose of this library +is to perform decimal math operations, examples may be the simplest way +to learn how to work with it and to see the difference between using this +package and sticking with expr. Consult the API section of +this man page for information about individual procedures.

+
+    package require decimal
+    # Various operations on two numbers.
+    # We first convert them to decimal format.
+    set a [::math::decimal::fromstr 8.2]
+    set b [::math::decimal::fromstr .2]
+    # Then we perform our operations. Here we multiply
+    set c [::math::decimal::* $a $b]
+    # Finally we convert back to string format for presentation to the user.
+    puts [::math::decimal::tostr $c] ; # => will output 8.4
+    # Other examples
+    #
+    # Subtraction
+    set c [::math::decimal::- $a $b]
+    puts [::math::decimal::tostr $c] ; # => will output 8.0
+    # Why bother using this instead of simply expr?
+    puts 8.399999999999999 ; # => will output 8.399999999999999
+    puts 7.999999999999999 ; # => will output 7.999999999999999
+    # See http://speleotrove.com/decimal to learn more about why this happens.
+
+
+

API

+
+
::math::decimal::fromstr string
+

Convert string into a decimal.

+
::math::decimal::tostr decimal
+

Convert decimal into a string representing the number in base 10.

+
::math::decimal::setVariable variable setting
+

Sets the variable to setting. Valid variables are:

+
    +

  • rounding - Method of rounding to use during rescale. Valid + methods are round_half_even, round_half_up, round_half_down, + round_down, round_up, round_floor, round_ceiling.

    • +

  • precision - Maximum number of digits allowed in mantissa.

    • +

  • extended - Set to 1 for extended mode. 0 for simplified mode.

    • +

  • maxExponent - Maximum value for the exponent. Defaults to 999.

    • +

  • minExponent - Minimum value for the exponent. Default to -998.

    • +
+
::math::decimal::add a b
+
+
::math::decimal::+ a b
+

Return the sum of the two decimals a and b.

+
::math::decimal::subtract a b
+
+
::math::decimal::- a b
+

Return the differnece of the two decimals a and b.

+
::math::decimal::multiply a b
+
+
::math::decimal::* a b
+

Return the product of the two decimals a and b.

+
::math::decimal::divide a b
+
+
::math::decimal::/ a b
+

Return the quotient of the division between the two +decimals a and b.

+
::math::decimal::divideint a b
+

Return a the integer portion of the quotient of the division between +decimals a and b

+
::math::decimal::remainder a b
+

Return the remainder of the division between the two +decimals a and b.

+
::math::decimal::abs decimal
+

Return the absolute value of the decimal.

+
::math::decimal::compare a b
+

Compare the two decimals a and b, returning 0 if a == b, +1 if a > b, and -1 if a < b.

+
::math::decimal::max a b
+

Compare the two decimals a and b, and return a if a >= b, and b if a < b.

+
::math::decimal::maxmag a b
+

Compare the two decimals a and b while ignoring their signs, and return a if abs(a) >= abs(b), and b if abs(a) < abs(b).

+
::math::decimal::min a b
+

Compare the two decimals a and b, and return a if a <= b, and b if a > b.

+
::math::decimal::minmag a b
+

Compare the two decimals a and b while ignoring their signs, and return a if abs(a) <= abs(b), and b if abs(a) > abs(b).

+
::math::decimal::plus a
+

Return the result from ::math::decimal::+ 0 $a.

+
::math::decimal::minus a
+

Return the result from ::math::decimal::- 0 $a.

+
::math::decimal::copynegate a
+

Returns a with the sign flipped.

+
::math::decimal::copysign a b
+

Returns a with the sign set to the sign of the b.

+
::math::decimal::is-signed decimal
+

Return the sign of the decimal. +The procedure returns 0 if the number is positive, 1 if it's negative.

+
::math::decimal::is-zero decimal
+

Return true if decimal value is zero, otherwise false is returned.

+
::math::decimal::is-NaN decimal
+

Return true if decimal value is NaN (not a number), otherwise false is returned.

+
::math::decimal::is-infinite decimal
+

Return true if decimal value is Infinite, otherwise false is returned.

+
::math::decimal::is-finite decimal
+

Return true if decimal value is finite, otherwise false is returned.

+
::math::decimal::fma a b c
+

Return the result from first multiplying a by b and then adding c. Rescaling only occurs after completion of all operations. In this way the result may vary from that returned by performing the operations individually.

+
::math::decimal::round_half_even decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round so the final digit is even.

+
::math::decimal::round_half_up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round up.

+
::math::decimal::round_half_down decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round to the nearest. If equidistant, round down.

+
::math::decimal::round_down decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward 0. (Truncate)

+
::math::decimal::round_up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round away from 0

+
::math::decimal::round_floor decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward -Infinity.

+
::math::decimal::round_ceiling decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round toward Infinity

+
::math::decimal::round_05up decimal digits
+

Rounds decimal to digits number of decimal points with the following rules: Round zero or five away from 0. The same as round-up, except that rounding up only occurs if the digit to be rounded up is 0 or 5, and after overflow +the result is the same as for round-down.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category decimal of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/exact.html Index: embedded/www/tcllib/files/modules/math/exact.html ================================================================== --- embedded/www/tcllib/files/modules/math/exact.html +++ embedded/www/tcllib/files/modules/math/exact.html @@ -0,0 +1,296 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::exact(n) 1.0 tcllib "Tcl Math Library"

+

Name

+

math::exact - Exact Real Arithmetic

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require grammar::aycock 1.0
    • +
  • package require math::exact 1.0
    • +
+ +
+
+

Description

+

The exactexpr command in the math::exact package +allows for exact computations over the computable real numbers. +These are not arbitrary-precision calculations; rather they are +exact, with numbers represented by algorithms that produce successive +approximations. At the end of a calculation, the caller can +request a given precision for the end result, and intermediate results are +computed to whatever precision is necessary to satisfy the request.

+
+

Procedures

+

The following procedure is the primary entry into the math::exact +package.

+
+
::math::exact::exactexpr expr
+

Accepts a mathematical expression in Tcl syntax, and returns an object +that represents the program to calculate successive approximations to +the expression's value. The result will be referred to as an +exact real number.

+
number ref
+

Increases the reference count of a given exact real number.

+
number unref
+

Decreases the reference count of a given exact real number, and destroys +the number if the reference count is zero.

+
number asPrint precision
+

Formats the given number for printing, with the specified precision. +(See below for how precision is interpreted). Numbers that are known to +be rational are formatted as fractions.

+
number asFloat precision
+

Formats the given number for printing, with the specified precision. +(See below for how precision is interpreted). All numbers are formatted +in floating-point E format.

+
+
+

Parameters

+
+
expr
+

Expression to evaluate. The syntax for expressions is the same as it is in Tcl, +but the set of operations is smaller. See Expressions below +for details.

+
number
+

The object returned by an earlier invocation of math::exact::exactexpr

+
precision
+

The requested 'precision' of the result. The precision is (approximately) +the absolute value of the binary exponent plus the number of bits of the +binary significand. For instance, to return results to IEEE-754 double +precision, 56 bits plus the exponent are required. Numbers between 1/2 and 2 +will require a precision of 57; numbers between 1/4 and 1/2 or between 2 and 4 +will require 58; numbers between 1/8 and 1/4 or between 4 and 8 will require +59; and so on.

+
+
+

Expressions

+

The math::exact::exactexpr command accepts expressions in a subset +of Tcl's syntax. The following components may be used in an expression.

+
    +

  • Decimal integers.

    • +

  • Variable references with the dollar sign ($). +The value of the variable must be the result of another call to +math::exact::exactexpr. The reference count of the value +will be increased by one for each position at which it appears +in the expression.

    • +

  • The exponentiation operator (**).

    • +

  • Unary plus (+) and minus (-) operators.

    • +

  • Multiplication (*) and division (/) operators.

    • +

  • Parentheses used for grouping.

    • +

  • Functions. See Functions below for the functions that are +available.

    • +
+
+

Functions

+

The following functions are available for use within exact real expressions.

+
+
acos(x)
+

The inverse cosine of x. The result is expressed in radians. +The absolute value of x must be less than 1.

+
acosh(x)
+

The inverse hyperbolic cosine of x. +x must be greater than 1.

+
asin(x)
+

The inverse sine of x. The result is expressed in radians. +The absolute value of x must be less than 1.

+
asinh(x)
+

The inverse hyperbolic sine of x.

+
atan(x)
+

The inverse tangent of x. The result is expressed in radians.

+
atanh(x)
+

The inverse hyperbolic tangent of x. +The absolute value of x must be less than 1.

+
cos(x)
+

The cosine of x. x is expressed in radians.

+
cosh(x)
+

The hyperbolic cosine of x.

+
e()
+

The base of the natural logarithms = 2.71828...

+
exp(x)
+

The exponential function of x.

+
log(x)
+

The natural logarithm of x. x must be positive.

+
pi()
+

The value of pi = 3.15159...

+
sin(x)
+

The sine of x. x is expressed in radians.

+
sinh(x)
+

The hyperbolic sine of x.

+
sqrt(x)
+

The square root of x. x must be positive.

+
tan(x)
+

The tangent of x. x is expressed in radians.

+
tanh(x)
+

The hyperbolic tangent of x.

+
+
+

Summary

+

The math::exact::exactexpr command provides a system that +performs exact arithmetic over computable real numbers, representing +the numbers as algorithms for successive approximation. +An example, which implements the high-school quadratic formula, +is shown below.

+
+namespace import math::exact::exactexpr
+proc exactquad {a b c} {
+    set d [[exactexpr {sqrt($b*$b - 4*$a*$c)}] ref]
+    set r0 [[exactexpr {(-$b - $d) / (2 * $a)}] ref]
+    set r1 [[exactexpr {(-$b + $d) / (2 * $a)}] ref]
+    $d unref
+    return [list $r0 $r1]
+}
+set a [[exactexpr 1] ref]
+set b [[exactexpr 200] ref]
+set c [[exactexpr {(-3/2) * 10**-12}] ref]
+lassign [exactquad $a $b $c] r0 r1
+$a unref; $b unref; $c unref
+puts [list [$r0 asFloat 70] [$r1 asFloat 110]]
+$r0 unref; $r1 unref
+
+

The program prints the result:

+
+-2.000000000000000075e2 7.499999999999999719e-15
+
+

Note that if IEEE-754 floating point had been used, a catastrophic +roundoff error would yield a smaller root that is a factor of two +too high:

+
+-200.0 1.4210854715202004e-14
+
+

The invocations of exactexpr should be fairly self-explanatory. +The other commands of note are ref and unref. It is necessary +for the caller to keep track of references to exact expressions - to call +ref every time an exact expression is stored in a variable and +unref every time the variable goes out of scope or is overwritten. +The asFloat method emits decimal digits as long as the requested +precision supports them. It terminates when the requested precision +yields an uncertainty of more than one unit in the least significant digit.

+
+

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/fourier.html Index: embedded/www/tcllib/files/modules/math/fourier.html ================================================================== --- embedded/www/tcllib/files/modules/math/fourier.html +++ embedded/www/tcllib/files/modules/math/fourier.html @@ -0,0 +1,242 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::fourier(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::fourier - Discrete and fast fourier transforms

+
+ + +

Description

+

The math::fourier package implements two versions of discrete +Fourier transforms, the ordinary transform and the fast Fourier +transform. It also provides a few simple filter procedures as an +illustrations of how such filters can be implemented.

+

The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. We also refer to the original Wiki page on the subject +which describes some of the considerations behind the current +implementation.

+
+

GENERAL INFORMATION

+

The two top-level procedures defined are

+
    +

  • dft data-list

    • +

  • inverse_dft data-list

    • +
+

Both take a list of complex numbers and apply a Discrete Fourier +Transform (DFT) or its inverse respectively to these lists of numbers. +A "complex number" in this case is either (i) a pair (two element list) of +numbers, interpreted as the real and imaginary parts of the complex number, +or (ii) a single number, interpreted as the real part of a complex number +whose imaginary part is zero. The return value is always in the +first format. (The DFT generally produces complex results even if the +input is purely real.) Applying first one and then the other of these +procedures to a list of complex numbers will (modulo rounding errors +due to floating point arithmetic) return the original list of numbers.

+

If the input length N is a power of two then these procedures will +utilize the O(N log N) Fast Fourier Transform algorithm. If input +length is not a power of two then the DFT will instead be computed +using a the naive quadratic algorithm.

+

Some examples:

+
+    % dft {1 2 3 4}
+    {10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}
+    % inverse_dft {{10 0.0} {-2.0 2.0} {-2 0.0} {-2.0 -2.0}}
+    {1.0 0.0} {2.0 0.0} {3.0 0.0} {4.0 0.0}
+    % dft {1 2 3 4 5}
+    {15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}
+    % inverse_dft {{15.0 0.0} {-2.5 3.44095480118} {-2.5 0.812299240582} {-2.5 -0.812299240582} {-2.5 -3.44095480118}}
+    {1.0 0.0} {2.0 8.881784197e-17} {3.0 4.4408920985e-17} {4.0 4.4408920985e-17} {5.0 -8.881784197e-17}
+
+

In the last case, the imaginary parts <1e-16 would have been zero in exact +arithmetic, but aren't here due to rounding errors.

+

Internally, the procedures use a flat list format where every even +index element of a list is a real part and every odd index element +is an imaginary part. This is reflected in the variable names by Re_ +and Im_ prefixes.

+

The package includes two simple filters. They have an analogue +equivalent in a simple electronic circuit, a resistor and a capacitance +in series. Using these filters requires the +math::complexnumbers package.

+
+

PROCEDURES

+

The public Fourier transform procedures are:

+
+
::math::fourier::dft in_data
+

Determine the Fourier transform of the given list of complex +numbers. The result is a list of complex numbers representing the +(complex) amplitudes of the Fourier components.

+
+
list in_data
+

List of data

+
+
::math::fourier::inverse_dft in_data
+

Determine the inverse Fourier transform of the given list of +complex numbers (interpreted as amplitudes). The result is a list of +complex numbers representing the original (complex) data

+
+
list in_data
+

List of data (amplitudes)

+
+
::math::fourier::lowpass cutoff in_data
+

Filter the (complex) amplitudes so that high-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance.

+
+
float cutoff
+

Cut-off frequency

+
list in_data
+

List of data (amplitudes)

+
+
::math::fourier::highpass cutoff in_data
+

Filter the (complex) amplitudes so that low-frequency components +are suppressed. The implemented filter is a first-order low-pass filter, +the discrete equivalent of a simple electronic circuit with a resistor +and a capacitance.

+
+
float cutoff
+

Cut-off frequency

+
list in_data
+

List of data (amplitudes)

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: fourier of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/fuzzy.html Index: embedded/www/tcllib/files/modules/math/fuzzy.html ================================================================== --- embedded/www/tcllib/files/modules/math/fuzzy.html +++ embedded/www/tcllib/files/modules/math/fuzzy.html @@ -0,0 +1,243 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::fuzzy(n) 0.2 tcllib "Tcl Math Library"

+

Name

+

math::fuzzy - Fuzzy comparison of floating-point numbers

+
+ + +

Description

+

The package Fuzzy is meant to solve common problems with floating-point +numbers in a systematic way:

+
    +

  • Comparing two numbers that are "supposed" to be identical, like +1.0 and 2.1/(1.2+0.9) is not guaranteed to give the +intuitive result.

    • +

  • Rounding a number that is halfway two integer numbers can cause +strange errors, like int(100.0*2.8) != 28 but 27

    • +
+

The Fuzzy package is meant to help sorting out this type of problems +by defining "fuzzy" comparison procedures for floating-point numbers. +It does so by allowing for a small margin that is determined +automatically - the margin is three times the "epsilon" value, that is +three times the smallest number eps such that 1.0 and 1.0+$eps +canbe distinguished. In Tcl, which uses double precision floating-point +numbers, this is typically 1.1e-16.

+
+

PROCEDURES

+

Effectively the package provides the following procedures:

+
+
::math::fuzzy::teq value1 value2
+

Compares two floating-point numbers and returns 1 if their values +fall within a small range. Otherwise it returns 0.

+
::math::fuzzy::tne value1 value2
+

Returns the negation, that is, if the difference is larger than +the margin, it returns 1.

+
::math::fuzzy::tge value1 value2
+

Compares two floating-point numbers and returns 1 if their values +either fall within a small range or if the first number is larger +than the second. Otherwise it returns 0.

+
::math::fuzzy::tle value1 value2
+

Returns 1 if the two numbers are equal according to +[teq] or if the first is smaller than the second.

+
::math::fuzzy::tlt value1 value2
+

Returns the opposite of [tge].

+
::math::fuzzy::tgt value1 value2
+

Returns the opposite of [tle].

+
::math::fuzzy::tfloor value
+

Returns the integer number that is lower or equal +to the given floating-point number, within a well-defined +tolerance.

+
::math::fuzzy::tceil value
+

Returns the integer number that is greater or equal to the given +floating-point number, within a well-defined tolerance.

+
::math::fuzzy::tround value
+

Rounds the floating-point number off.

+
::math::fuzzy::troundn value ndigits
+

Rounds the floating-point number off to the +specified number of decimals (Pro memorie).

+
+

Usage:

+
+if { [teq $x $y] } { puts "x == y" }
+if { [tne $x $y] } { puts "x != y" }
+if { [tge $x $y] } { puts "x >= y" }
+if { [tgt $x $y] } { puts "x > y" }
+if { [tlt $x $y] } { puts "x < y" }
+if { [tle $x $y] } { puts "x <= y" }
+set fx      [tfloor $x]
+set fc      [tceil  $x]
+set rounded [tround $x]
+set roundn  [troundn $x $nodigits]
+
+
+

TEST CASES

+

The problems that can occur with floating-point numbers are illustrated +by the test cases in the file "fuzzy.test":

+
    +

  • Several test case use the ordinary comparisons, and they +fail invariably to produce understandable results

    • +

  • One test case uses [expr] without braces ({ and }). It too +fails.

    • +
+

The conclusion from this is that any expression should be surrounded by +braces, because otherwise very awkward things can happen if you need +accuracy. Furthermore, accuracy and understandable results are +enhanced by using these "tolerant" or fuzzy comparisons.

+

Note that besides the Tcl-only package, there is also a C-based version.

+
+

REFERENCES

+

Original implementation in Fortran by dr. H.D. Knoble (Penn State +University).

+

P. E. Hagerty, "More on Fuzzy Floor and Ceiling," +APL QUOTE QUAD 8(4):20-24, June 1978. Note that TFLOOR=FL5 took five +years of refereed evolution (publication).

+

L. M. Breed, "Definitions for Fuzzy Floor and Ceiling", +APL QUOTE QUAD 8(3):16-23, March 1978.

+

D. Knuth, Art of Computer Programming, +Vol. 1, Problem 1.2.4-5.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: fuzzy of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/interpolate.html Index: embedded/www/tcllib/files/modules/math/interpolate.html ================================================================== --- embedded/www/tcllib/files/modules/math/interpolate.html +++ embedded/www/tcllib/files/modules/math/interpolate.html @@ -0,0 +1,362 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::interpolate(n) 1.1 tcllib "Tcl Math Library"

+

Name

+

math::interpolate - Interpolation routines

+
+ + +

Description

+

This package implements several interpolation algorithms:

+
    +

  • Interpolation into a table (one or two independent variables), this is useful +for example, if the data are static, like with tables of statistical functions.

    • +

  • Linear interpolation into a given set of data (organised as (x,y) pairs).

    • +

  • Lagrange interpolation. This is mainly of theoretical interest, because there is +no guarantee about error bounds. One possible use: if you need a line or +a parabola through given points (it will calculate the values, but not return +the coefficients).

    +

    A variation is Neville's method which has better behaviour and error +bounds.

    • +

  • Spatial interpolation using a straightforward distance-weight method. This procedure +allows any number of spatial dimensions and any number of dependent variables.

    • +

  • Interpolation in one dimension using cubic splines.

    • +
+

This document describes the procedures and explains their usage.

+
+

INCOMPATIBILITY WITH VERSION 1.0.3

+

The interpretation of the tables in the ::math::interpolate::interpolate-1d-table command +has been changed to be compatible with the interpretation for 2D interpolation in +the ::math::interpolate::interpolate-table command. As a consequence this version is +incompatible with the previous versions of the command (1.0.x).

+
+

PROCEDURES

+

The interpolation package defines the following public procedures:

+
+
::math::interpolate::defineTable name colnames values
+

Define a table with one or two independent variables (the distinction is implicit in +the data). The procedure returns the name of the table - this name is used whenever you +want to interpolate the values. Note: this procedure is a convenient wrapper for the +struct::matrix procedure. Therefore you can access the data at any location in your program.

+
+
string name (in)
+

Name of the table to be created

+
list colnames (in)
+

List of column names

+
list values (in)
+

List of values (the number of elements should be a +multiple of the number of columns. See EXAMPLES for more information on the +interpretation of the data.

+

The values must be sorted with respect to the independent variable(s).

+
+
::math::interpolate::interp-1d-table name xval
+

Interpolate into the one-dimensional table "name" and return a list of values, one for +each dependent column.

+
+
string name (in)
+

Name of an existing table

+
float xval (in)
+

Value of the independent row variable

+
+
::math::interpolate::interp-table name xval yval
+

Interpolate into the two-dimensional table "name" and return the interpolated value.

+
+
string name (in)
+

Name of an existing table

+
float xval (in)
+

Value of the independent row variable

+
float yval (in)
+

Value of the independent column variable

+
+
::math::interpolate::interp-linear xyvalues xval
+

Interpolate linearly into the list of x,y pairs and return the interpolated value.

+
+
list xyvalues (in)
+

List of pairs of (x,y) values, sorted to increasing x. +They are used as the breakpoints of a piecewise linear function.

+
float xval (in)
+

Value of the independent variable for which the value of y +must be computed.

+
+
::math::interpolate::interp-lagrange xyvalues xval
+

Use the list of x,y pairs to construct the unique polynomial of lowest degree +that passes through all points and return the interpolated value.

+
+
list xyvalues (in)
+

List of pairs of (x,y) values

+
float xval (in)
+

Value of the independent variable for which the value of y +must be computed.

+
+
::math::interpolate::prepare-cubic-splines xcoord ycoord
+

Returns a list of coefficients for the second routine +interp-cubic-splines to actually interpolate.

+
+
list xcoord
+

List of x-coordinates for the value of the +function to be interpolated is known. The coordinates must be strictly +ascending. At least three points are required.

+
list ycoord
+

List of y-coordinates (the values of the +function at the given x-coordinates).

+
+
::math::interpolate::interp-cubic-splines coeffs x
+

Returns the interpolated value at coordinate x. The coefficients are +computed by the procedure prepare-cubic-splines.

+
+
list coeffs
+

List of coefficients as returned by +prepare-cubic-splines

+
float x
+

x-coordinate at which to estimate the function. Must +be between the first and last x-coordinate for which values were given.

+
+
::math::interpolate::interp-spatial xyvalues coord
+

Use a straightforward interpolation method with weights as function of the +inverse distance to interpolate in 2D and N-dimensional space

+

The list xyvalues is a list of lists:

+
+    {   {x1 y1 z1 {v11 v12 v13 v14}}
+	{x2 y2 z2 {v21 v22 v23 v24}}
+	...
+    }
+
+

The last element of each inner list is either a single number or a list in itself. +In the latter case the return value is a list with the same number of elements.

+

The method is influenced by the search radius and the power of the inverse distance

+
+
list xyvalues (in)
+

List of lists, each sublist being a list of coordinates and +of dependent values.

+
list coord (in)
+

List of coordinates for which the values must be calculated

+
+
::math::interpolate::interp-spatial-params max_search power
+

Set the parameters for spatial interpolation

+
+
float max_search (in)
+

Search radius (data points further than this are ignored)

+
integer power (in)
+

Power for the distance (either 1 or 2; defaults to 2)

+
+
::math::interpolate::neville xlist ylist x
+

Interpolates between the tabulated values of a function +whose abscissae are xlist +and whose ordinates are ylist to produce an estimate for the value +of the function at x. The result is a two-element list; the first +element is the function's estimated value, and the second is an estimate +of the absolute error of the result. Neville's algorithm for polynomial +interpolation is used. Note that a large table of values will use an +interpolating polynomial of high degree, which is likely to result in +numerical instabilities; one is better off using only a few tabulated +values near the desired abscissa.

+
+
+

EXAMPLES

+

Example of using one-dimensional tables:

+

Suppose you have several tabulated functions of one variable:

+
+    x     y1     y2
+  0.0    0.0    0.0
+  1.0    1.0    1.0
+  2.0    4.0    8.0
+  3.0    9.0   27.0
+  4.0   16.0   64.0
+
+

Then to estimate the values at 0.5, 1.5, 2.5 and 3.5, you can use:

+
+   set table [::math::interpolate::defineTable table1  {x y1 y2} {   -      1      2
+                   0.0    0.0    0.0
+                   1.0    1.0    1.0
+                   2.0    4.0    8.0
+                   3.0    9.0   27.0
+                   4.0   16.0   64.0}]
+   foreach x {0.5 1.5 2.5 3.5} {
+       puts "$x: [::math::interpolate::interp-1d-table $table $x]"
+   }
+
+

For one-dimensional tables the first row is not used. For two-dimensional +tables, the first row represents the values for the second independent variable.

+

Example of using the cubic splines:

+

Suppose the following values are given:

+
+    x       y
+  0.1     1.0
+  0.3     2.1
+  0.4     2.2
+  0.8     4.11
+  1.0     4.12
+
+

Then to estimate the values at 0.1, 0.2, 0.3, ... 1.0, you can use:

+
+   set coeffs [::math::interpolate::prepare-cubic-splines  {0.1 0.3 0.4 0.8  1.0}  {1.0 2.1 2.2 4.11 4.12}]
+   foreach x {0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0} {
+      puts "$x: [::math::interpolate::interp-cubic-splines $coeffs $x]"
+   }
+
+

to get the following output:

+
+0.1: 1.0
+0.2: 1.68044117647
+0.3: 2.1
+0.4: 2.2
+0.5: 3.11221507353
+0.6: 4.25242647059
+0.7: 5.41804227941
+0.8: 4.11
+0.9: 3.95675857843
+1.0: 4.12
+
+

As you can see, the values at the abscissae are reproduced perfectly.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: interpolate of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/linalg.html Index: embedded/www/tcllib/files/modules/math/linalg.html ================================================================== --- embedded/www/tcllib/files/modules/math/linalg.html +++ embedded/www/tcllib/files/modules/math/linalg.html @@ -0,0 +1,987 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::linearalgebra(n) 1.1.5 tcllib "Tcl Math Library"

+

Name

+

math::linearalgebra - Linear Algebra

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.4?
    • +
  • package require math::linearalgebra ?1.1.5?
    • +
+ +
+
+

Description

+

This package offers both low-level procedures and high-level algorithms +to deal with linear algebra problems:

+
    +

  • robust solution of linear equations or least squares problems

    • +

  • determining eigenvectors and eigenvalues of symmetric matrices

    • +

  • various decompositions of general matrices or matrices of a specific +form

    • +

  • (limited) support for matrices in band storage, a common type of sparse +matrices

    • +
+

It arose as a re-implementation of Hume's LA package and the desire to +offer low-level procedures as found in the well-known BLAS library. +Matrices are implemented as lists of lists rather linear lists with +reserved elements, as in the original LA package, as it was found that +such an implementation is actually faster.

+

It is advisable, however, to use the procedures that are offered, such +as setrow and getrow, rather than rely on this +representation explicitly: that way it is to switch to a possibly even +faster compiled implementation that supports the same API.

+

Note: When using this package in combination with Tk, there may +be a naming conflict, as both this package and Tk define a command +scale. See the NAMING CONFLICT section below.

+
+

PROCEDURES

+

The package defines the following public procedures (several exist as +specialised procedures, see below):

+

Constructing matrices and vectors

+
+
::math::linearalgebra::mkVector ndim value
+

Create a vector with ndim elements, each with the value value.

+
+
integer ndim
+

Dimension of the vector (number of components)

+
double value
+

Uniform value to be used (default: 0.0)

+
+
::math::linearalgebra::mkUnitVector ndim ndir
+

Create a unit vector in ndim-dimensional space, along the +ndir-th direction.

+
+
integer ndim
+

Dimension of the vector (number of components)

+
integer ndir
+

Direction (0, ..., ndim-1)

+
+
::math::linearalgebra::mkMatrix nrows ncols value
+

Create a matrix with nrows rows and ncols columns. All +elements have the value value.

+
+
integer nrows
+

Number of rows

+
integer ncols
+

Number of columns

+
double value
+

Uniform value to be used (default: 0.0)

+
+
::math::linearalgebra::getrow matrix row ?imin? ?imax?
+

Returns a single row of a matrix as a list

+
+
list matrix
+

Matrix in question

+
integer row
+

Index of the row to return

+
integer imin
+

Minimum index of the column (default: 0)

+
integer imax
+

Maximum index of the column (default: ncols-1)

+
+
::math::linearalgebra::setrow matrix row newvalues ?imin? ?imax?
+

Set a single row of a matrix to new values (this list must have the same +number of elements as the number of columns in the matrix)

+
+
list matrix
+

name of the matrix in question

+
integer row
+

Index of the row to update

+
list newvalues
+

List of new values for the row

+
integer imin
+

Minimum index of the column (default: 0)

+
integer imax
+

Maximum index of the column (default: ncols-1)

+
+
::math::linearalgebra::getcol matrix col ?imin? ?imax?
+

Returns a single column of a matrix as a list

+
+
list matrix
+

Matrix in question

+
integer col
+

Index of the column to return

+
integer imin
+

Minimum index of the row (default: 0)

+
integer imax
+

Maximum index of the row (default: nrows-1)

+
+
::math::linearalgebra::setcol matrix col newvalues ?imin? ?imax?
+

Set a single column of a matrix to new values (this list must have +the same number of elements as the number of rows in the matrix)

+
+
list matrix
+

name of the matrix in question

+
integer col
+

Index of the column to update

+
list newvalues
+

List of new values for the column

+
integer imin
+

Minimum index of the row (default: 0)

+
integer imax
+

Maximum index of the row (default: nrows-1)

+
+
::math::linearalgebra::getelem matrix row col
+

Returns a single element of a matrix/vector

+
+
list matrix
+

Matrix or vector in question

+
integer row
+

Row of the element

+
integer col
+

Column of the element (not present for vectors)

+
+
::math::linearalgebra::setelem matrix row ?col? newvalue
+

Set a single element of a matrix (or vector) to a new value

+
+
list matrix
+

name of the matrix in question

+
integer row
+

Row of the element

+
integer col
+

Column of the element (not present for vectors)

+
+
::math::linearalgebra::swaprows matrix irow1 irow2 ?imin? ?imax?
+

Swap two rows in a matrix completely or only a selected part

+
+
list matrix
+

name of the matrix in question

+
integer irow1
+

Index of first row

+
integer irow2
+

Index of second row

+
integer imin
+

Minimum column index (default: 0)

+
integer imin
+

Maximum column index (default: ncols-1)

+
+
::math::linearalgebra::swapcols matrix icol1 icol2 ?imin? ?imax?
+

Swap two columns in a matrix completely or only a selected part

+
+
list matrix
+

name of the matrix in question

+
integer irow1
+

Index of first column

+
integer irow2
+

Index of second column

+
integer imin
+

Minimum row index (default: 0)

+
integer imin
+

Maximum row index (default: nrows-1)

+
+
+

Querying matrices and vectors

+
+
::math::linearalgebra::show obj ?format? ?rowsep? ?colsep?
+

Return a string representing the vector or matrix, for easy printing. +(There is currently no way to print fixed sets of columns)

+
+
list obj
+

Matrix or vector in question

+
string format
+

Format for printing the numbers (default: %6.4f)

+
string rowsep
+

String to use for separating rows (default: newline)

+
string colsep
+

String to use for separating columns (default: space)

+
+
::math::linearalgebra::dim obj
+

Returns the number of dimensions for the object (either 0 for a scalar, +1 for a vector and 2 for a matrix)

+
+
any obj
+

Scalar, vector, or matrix

+
+
::math::linearalgebra::shape obj
+

Returns the number of elements in each dimension for the object (either +an empty list for a scalar, a single number for a vector and a list of +the number of rows and columns for a matrix)

+
+
any obj
+

Scalar, vector, or matrix

+
+
::math::linearalgebra::conforming type obj1 obj2
+

Checks if two objects (vector or matrix) have conforming shapes, that is +if they can be applied in an operation like addition or matrix +multiplication.

+
+
string type
+

Type of check:

+
    +

  • "shape" - the two objects have the same shape (for all element-wise +operations)

    • +

  • "rows" - the two objects have the same number of rows (for use as A and +b in a system of linear equations Ax = b

    • +

  • "matmul" - the first object has the same number of columns as the number +of rows of the second object. Useful for matrix-matrix or matrix-vector +multiplication.

    • +
+
list obj1
+

First vector or matrix (left operand)

+
list obj2
+

Second vector or matrix (right operand)

+
+
::math::linearalgebra::symmetric matrix ?eps?
+

Checks if the given (square) matrix is symmetric. The argument eps +is the tolerance.

+
+
list matrix
+

Matrix to be inspected

+
float eps
+

Tolerance for determining approximate equality +(defaults to 1.0e-8)

+
+
+

Basic operations

+
+
::math::linearalgebra::norm vector type
+

Returns the norm of the given vector. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm.

+
+
list vector
+

Vector, list of coefficients

+
string type
+

Type of norm (default: 2, the Euclidean norm)

+
+
::math::linearalgebra::norm_one vector
+

Returns the L1 norm of the given vector, the sum of absolute values

+
+
list vector
+

Vector, list of coefficients

+
+
::math::linearalgebra::norm_two vector
+

Returns the L2 norm of the given vector, the ordinary Euclidean norm

+
+
list vector
+

Vector, list of coefficients

+
+
::math::linearalgebra::norm_max vector ?index?
+

Returns the Linf norm of the given vector, the maximum absolute +coefficient

+
+
list vector
+

Vector, list of coefficients

+
integer index
+

(optional) if non zero, returns a list made of the maximum +value and the index where that maximum was found. +if zero, returns the maximum value.

+
+
::math::linearalgebra::normMatrix matrix type
+

Returns the norm of the given matrix. The type argument can be: 1, +2, inf or max, respectively the sum of absolute values, the ordinary +Euclidean norm or the max norm.

+
+
list matrix
+

Matrix, list of row vectors

+
string type
+

Type of norm (default: 2, the Euclidean norm)

+
+
::math::linearalgebra::dotproduct vect1 vect2
+

Determine the inproduct or dot product of two vectors. These must have +the same shape (number of dimensions)

+
+
list vect1
+

First vector, list of coefficients

+
list vect2
+

Second vector, list of coefficients

+
+
::math::linearalgebra::unitLengthVector vector
+

Return a vector in the same direction with length 1.

+
+
list vector
+

Vector to be normalized

+
+
::math::linearalgebra::normalizeStat mv
+

Normalize the matrix or vector in a statistical sense: the mean of the +elements of the columns of the result is zero and the standard deviation +is 1.

+
+
list mv
+

Vector or matrix to be normalized in the above sense

+
+
::math::linearalgebra::axpy scale mv1 mv2
+

Return a vector or matrix that results from a "daxpy" operation, that +is: compute a*x+y (a a scalar and x and y both vectors or matrices of +the same shape) and return the result.

+

Specialised variants are: axpy_vect and axpy_mat (slightly faster, +but no check on the arguments)

+
+
double scale
+

The scale factor for the first vector/matrix (a)

+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::add mv1 mv2
+

Return a vector or matrix that is the sum of the two arguments (x+y)

+

Specialised variants are: add_vect and add_mat (slightly faster, +but no check on the arguments)

+
+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::sub mv1 mv2
+

Return a vector or matrix that is the difference of the two arguments +(x-y)

+

Specialised variants are: sub_vect and sub_mat (slightly faster, +but no check on the arguments)

+
+
list mv1
+

First vector or matrix (x)

+
list mv2
+

Second vector or matrix (y)

+
+
::math::linearalgebra::scale scale mv
+

Scale a vector or matrix and return the result, that is: compute a*x.

+

Specialised variants are: scale_vect and scale_mat (slightly faster, +but no check on the arguments)

+
+
double scale
+

The scale factor for the vector/matrix (a)

+
list mv
+

Vector or matrix (x)

+
+
::math::linearalgebra::rotate c s vect1 vect2
+

Apply a planar rotation to two vectors and return the result as a list +of two vectors: c*x-s*y and s*x+c*y. In algorithms you can often easily +determine the cosine and sine of the angle, so it is more efficient to +pass that information directly.

+
+
double c
+

The cosine of the angle

+
double s
+

The sine of the angle

+
list vect1
+

First vector (x)

+
list vect2
+

Seocnd vector (x)

+
+
::math::linearalgebra::transpose matrix
+

Transpose a matrix

+
+
list matrix
+

Matrix to be transposed

+
+
::math::linearalgebra::matmul mv1 mv2
+

Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector.

+
+
list mv1
+

First vector/matrix (x)

+
list mv2
+

Second vector/matrix (y)

+
+
::math::linearalgebra::angle vect1 vect2
+

Compute the angle between two vectors (in radians)

+
+
list vect1
+

First vector

+
list vect2
+

Second vector

+
+
::math::linearalgebra::crossproduct vect1 vect2
+

Compute the cross product of two (three-dimensional) vectors

+
+
list vect1
+

First vector

+
list vect2
+

Second vector

+
+
::math::linearalgebra::matmul mv1 mv2
+

Multiply a vector/matrix with another vector/matrix. The result is +a matrix, if both x and y are matrices or both are vectors, in +which case the "outer product" is computed. If one is a vector and the +other is a matrix, then the result is a vector.

+
+
list mv1
+

First vector/matrix (x)

+
list mv2
+

Second vector/matrix (y)

+
+
+

Common matrices and test matrices

+
+
::math::linearalgebra::mkIdentity size
+

Create an identity matrix of dimension size.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkDiagonal diag
+

Create a diagonal matrix whose diagonal elements are the elements of the +vector diag.

+
+
list diag
+

Vector whose elements are used for the diagonal

+
+
::math::linearalgebra::mkRandom size
+

Create a square matrix whose elements are uniformly distributed random +numbers between 0 and 1 of dimension size.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkTriangular size ?uplo? ?value?
+

Create a triangular matrix with non-zero elements in the upper or lower +part, depending on argument uplo.

+
+
integer size
+

Dimension of the matrix

+
string uplo
+

Fill the upper (U) or lower part (L)

+
double value
+

Value to fill the matrix with

+
+
::math::linearalgebra::mkHilbert size
+

Create a Hilbert matrix of dimension size. +Hilbert matrices are very ill-conditioned with respect to +eigenvalue/eigenvector problems. Therefore they +are good candidates for testing the accuracy +of algorithms and implementations.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkDingdong size
+

Create a "dingdong" matrix of dimension size. +Dingdong matrices are imprecisely represented, +but have the property of being very stable in +such algorithms as Gauss elimination.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkOnes size
+

Create a square matrix of dimension size whose entries are all 1.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkMoler size
+

Create a Moler matrix of size size. (Moler matrices have +a very simple Choleski decomposition. It has one small eigenvalue +and it can easily upset elimination methods for systems of linear +equations.)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkFrank size
+

Create a Frank matrix of size size. (Frank matrices are +fairly well-behaved matrices)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkBorder size
+

Create a bordered matrix of size size. (Bordered matrices have +a very low rank and can upset certain specialised algorithms.)

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkWilkinsonW+ size
+

Create a Wilkinson W+ of size size. This kind of matrix +has pairs of eigenvalues that are very close together. Usually +the order (size) is odd.

+
+
integer size
+

Dimension of the matrix

+
+
::math::linearalgebra::mkWilkinsonW- size
+

Create a Wilkinson W- of size size. This kind of matrix +has pairs of eigenvalues with opposite signs, when the order (size) +is odd.

+
+
integer size
+

Dimension of the matrix

+
+
+

Common algorithms

+
+
::math::linearalgebra::solveGauss matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination. +Returns the solution (x) as a vector or matrix of the same shape as +bvect.

+
+
list matrix
+

Square matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solvePGauss matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination with +partial pivoting. Returns the solution (x) as a vector or matrix of the +same shape as bvect.

+
+
list matrix
+

Square matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solveTriangular matrix bvect ?uplo?
+

Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular.

+
+
list matrix
+

Lower or upper-triangular matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
string uplo
+

Indicates whether the matrix is lower-triangular +(L) or upper-triangular (U). Defaults to "U".

+
+
::math::linearalgebra::solveGaussBand matrix bvect
+

Solve a system of linear equations (Ax=b) using Gauss elimination, +where the matrix is stored as a band matrix (cf. STORAGE). +Returns the solution (x) as a vector or matrix of the same shape as +bvect.

+
+
list matrix
+

Square matrix (matrix A; in band form)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::solveTriangularBand matrix bvect
+

Solve a system of linear equations (Ax=b) by backward substitution. The +matrix is supposed to be upper-triangular and stored in band form.

+
+
list matrix
+

Upper-triangular matrix (matrix A)

+
list bvect
+

Vector or matrix whose columns are the individual +b-vectors

+
+
::math::linearalgebra::determineSVD A eps
+

Determines the Singular Value Decomposition of a matrix: A = U S Vtrans. +Returns a list with the matrix U, the vector of singular values S and +the matrix V.

+
+
list A
+

Matrix to be decomposed

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::eigenvectorsSVD A eps
+

Determines the eigenvectors and eigenvalues of a real +symmetric matrix, using SVD. Returns a list with the matrix of +normalized eigenvectors and their eigenvalues.

+
+
list A
+

Matrix whose eigenvalues must be determined

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::leastSquaresSVD A y qmin eps
+

Determines the solution to a least-sqaures problem Ax ~ y via singular +value decomposition. The result is the vector x.

+

Note that if you add a column of 1s to the matrix, then this column will +represent a constant like in: y = a*x1 + b*x2 + c. To force the +intercept to be zero, simply leave it out.

+
+
list A
+

Matrix of independent variables

+
list y
+

List of observed values

+
float qmin
+

Minimum singular value to be considered (defaults to 0.0)

+
float eps
+

Tolerance (defaults to 2.3e-16)

+
+
::math::linearalgebra::choleski matrix
+

Determine the Choleski decomposition of a symmetric positive +semidefinite matrix (this condition is not checked!). The result +is the lower-triangular matrix L such that L Lt = matrix.

+
+
list matrix
+

Matrix to be decomposed

+
+
::math::linearalgebra::orthonormalizeColumns matrix
+

Use the modified Gram-Schmidt method to orthogonalize and normalize +the columns of the given matrix and return the result.

+
+
list matrix
+

Matrix whose columns must be orthonormalized

+
+
::math::linearalgebra::orthonormalizeRows matrix
+

Use the modified Gram-Schmidt method to orthogonalize and normalize +the rows of the given matrix and return the result.

+
+
list matrix
+

Matrix whose rows must be orthonormalized

+
+
::math::linearalgebra::dger matrix alpha x y ?scope?
+

Perform the rank 1 operation A + alpha*x*y' inline (that is: the matrix A is adjusted). +For convenience the new matrix is also returned as the result.

+
+
list matrix
+

Matrix whose rows must be adjusted

+
double alpha
+

Scale factor

+
list x
+

A column vector

+
list y
+

A column vector

+
list scope
+

If not provided, the operation is performed on all rows/columns of A +if provided, it is expected to be the list {imin imax jmin jmax} +where:

+
    +

  • imin Minimum row index

    • +

  • imax Maximum row index

    • +

  • jmin Minimum column index

    • +

  • jmax Maximum column index

    • +
+
+
::math::linearalgebra::dgetrf matrix
+

Computes an LU factorization of a general matrix, using partial, +pivoting with row interchanges. Returns the permutation vector.

+

The factorization has the form

+
+   P * A = L * U
+
+

where P is a permutation matrix, L is lower triangular with unit +diagonal elements, and U is upper triangular. +Returns the permutation vector, as a list of length n-1. +The last entry of the permutation is not stored, since it is +implicitely known, with value n (the last row is not swapped +with any other row). +At index #i of the permutation is stored the index of the row #j +which is swapped with row #i at step #i. That means that each +index of the permutation gives the permutation at each step, not the +cumulated permutation matrix, which is the product of permutations.

+
+
list matrix
+

On entry, the matrix to be factored. +On exit, the factors L and U from the factorization +P*A = L*U; the unit diagonal elements of L are not stored.

+
+
::math::linearalgebra::det matrix
+

Returns the determinant of the given matrix, based on PA=LU +decomposition, i.e. Gauss partial pivotal.

+
+
list matrix
+

Square matrix (matrix A)

+
list ipiv
+

The pivots (optionnal). +If the pivots are not provided, a PA=LU decomposition +is performed. +If the pivots are provided, we assume that it +contains the pivots and that the matrix A contains the +L and U factors, as provided by dgterf. +b-vectors

+
+
::math::linearalgebra::largesteigen matrix tolerance maxiter
+

Returns a list made of the largest eigenvalue (in magnitude) +and associated eigenvector. +Uses iterative Power Method as provided as algorithm #7.3.3 of Golub & Van Loan. +This algorithm is used here for a dense matrix (but is usually +used for sparse matrices).

+
+
list matrix
+

Square matrix (matrix A)

+
double tolerance
+

The relative tolerance of the eigenvalue (default:1.e-8).

+
integer maxiter
+

The maximum number of iterations (default:10).

+
+
+

Compability with the LA package +Two procedures are provided for compatibility with Hume's LA package:

+
+
::math::linearalgebra::to_LA mv
+

Transforms a vector or matrix into the format used by the original LA +package.

+
+
list mv
+

Matrix or vector

+
+
::math::linearalgebra::from_LA mv
+

Transforms a vector or matrix from the format used by the original LA +package into the format used by the present implementation.

+
+
list mv
+

Matrix or vector as used by the LA package

+
+
+
+

STORAGE

+

While most procedures assume that the matrices are given in full form, +the procedures solveGaussBand and solveTriangularBand +assume that the matrices are stored as band matrices. This +common type of "sparse" matrices is related to ordinary matrices as +follows:

+
    +

  • "A" is a full-size matrix with N rows and M columns.

    • +

  • "B" is a band matrix, with m upper and lower diagonals and n rows.

    • +

  • "B" can be stored in an ordinary matrix of (2m+1) columns (one for +each off-diagonal and the main diagonal) and n rows.

    • +

  • Element i,j (i = -m,...,m; j =1,...,n) of "B" corresponds to element +k,j of "A" where k = M+i-1 and M is at least (!) n, the number of rows +in "B".

    • +

  • To set element (i,j) of matrix "B" use:

    +
    +    setelem B $j [expr {$N+$i-1}] $value
+
    +
    • +
+

(There is no convenience procedure for this yet)

+
+

REMARKS ON THE IMPLEMENTATION

+

There is a difference between the original LA package by Hume and the +current implementation. Whereas the LA package uses a linear list, the +current package uses lists of lists to represent matrices. It turns out +that with this representation, the algorithms are faster and easier to +implement.

+

The LA package was used as a model and in fact the implementation of, +for instance, the SVD algorithm was taken from that package. The set of +procedures was expanded using ideas from the well-known BLAS library and +some algorithms were updated from the second edition of J.C. Nash's +book, Compact Numerical Methods for Computers, (Adam Hilger, 1990) that +inspired the LA package.

+

Two procedures are provided to make the transition between the two +implementations easier: to_LA and from_LA. They are +described above.

+
+

TODO

+

Odds and ends: the following algorithms have not been implemented yet:

+
    +

  • determineQR

    • +

  • certainlyPositive, diagonallyDominant

    • +
+
+

NAMING CONFLICT

+

If you load this package in a Tk-enabled shell like wish, then the +command

+
namespace import ::math::linearalgebra
+

results in an error +message about "scale". This is due to the fact that Tk defines all +its commands in the global namespace. The solution is to import +the linear algebra commands in a namespace that is not the global one:

+
+package require math::linearalgebra
+namespace eval compute {
+    namespace import ::math::linearalgebra::*
+    ... use the linear algebra version of scale ...
+}
+
+

To use Tk's scale command in that same namespace you can rename it:

+
+namespace eval compute {
+    rename ::scale scaleTk
+    scaleTk .scale ...
+}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: linearalgebra of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/machineparameters.html Index: embedded/www/tcllib/files/modules/math/machineparameters.html ================================================================== --- embedded/www/tcllib/files/modules/math/machineparameters.html +++ embedded/www/tcllib/files/modules/math/machineparameters.html @@ -0,0 +1,287 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tclrep/machineparameters(n) 1.0 tcllib "tclrep"

+

Name

+

tclrep/machineparameters - Compute double precision machine parameters.

+
+ + +

Description

+

The math::machineparameters package +is the Tcl equivalent of the DLAMCH LAPACK function. +In floating point systems, a floating point number is represented +by

+
+x = +/- d1 d2 ... dt basis^e
+
+

where digits satisfy

+
+0 <= di <= basis - 1, i = 1, t
+
+

with the convention :

+
    +

  • t is the size of the mantissa

    • +

  • basis is the basis (the "radix")

    • +
+

The compute method computes all machine parameters. + Then, the get method can be used to get each + parameter. + The print method prints a report on standard output.

+
+

EXAMPLE

+

In the following example, one compute the parameters of a desktop +under Linux with the following Tcl 8.4.19 properties :

+
+% parray tcl_platform
+tcl_platform(byteOrder) = littleEndian
+tcl_platform(machine)   = i686
+tcl_platform(os)        = Linux
+tcl_platform(osVersion) = 2.6.24-19-generic
+tcl_platform(platform)  = unix
+tcl_platform(tip,268)   = 1
+tcl_platform(tip,280)   = 1
+tcl_platform(user)      = <username>
+tcl_platform(wordSize)  = 4
+
+

The following example creates a machineparameters object, + computes the properties and displays it.

+
+     set pp [machineparameters create %AUTO%]
+     $pp compute
+     $pp print
+     $pp destroy
+
+

This prints out :

+
+     Machine parameters
+     Epsilon : 1.11022302463e-16
+     Beta : 2
+     Rounding : proper
+     Mantissa : 53
+     Maximum exponent : 1024
+     Minimum exponent : -1021
+     Overflow threshold : 8.98846567431e+307
+     Underflow threshold : 2.22507385851e-308
+
+

That compares well with the results produced by Lapack 3.1.1 :

+
+     Epsilon                      =   1.11022302462515654E-016
+     Safe minimum                 =   2.22507385850720138E-308
+     Base                         =    2.0000000000000000
+     Precision                    =   2.22044604925031308E-016
+     Number of digits in mantissa =    53.000000000000000
+     Rounding mode                =   1.00000000000000000
+     Minimum exponent             =   -1021.0000000000000
+     Underflow threshold          =   2.22507385850720138E-308
+     Largest exponent             =    1024.0000000000000
+     Overflow threshold           =   1.79769313486231571E+308
+     Reciprocal of safe minimum   =   4.49423283715578977E+307
+
+

The following example creates a machineparameters object, + computes the properties and gets the epsilon for + the machine.

+
+     set pp [machineparameters create %AUTO%]
+     $pp compute
+     set eps [$pp get -epsilon]
+     $pp destroy
+
+
+

REFERENCES

+
    +

  • "Algorithms to Reveal Properties of Floating-Point Arithmetic", Michael A. Malcolm, Stanford University, Communications of the ACM, Volume 15 , Issue 11 (November 1972), Pages: 949 - 951

    • +

  • "More on Algorithms that Reveal Properties of Floating, Point Arithmetic Units", W. Morven Gentleman, University of Waterloo, Scott B. Marovich, Purdue University, Communications of the ACM, Volume 17 , Issue 5 (May 1974), Pages: 276 - 277

    • +
+
+

CLASS API

+
+
machineparameters create objectname ?options...?
+

The command creates a new machineparameters object and returns the fully +qualified name of the object command as its result.

+
+
-verbose verbose
+

Set this option to 1 to enable verbose logging. +This option is mainly for debug purposes. +The default value of verbose is 0.

+
+
+
+

OBJECT API

+
+
objectname configure ?options...?
+

The command configure the options of the object objectname. The options +are the same as the static method create.

+
objectname cget opt
+

Returns the value of the option which name is opt. The options +are the same as the method create and configure.

+
objectname destroy
+

Destroys the object objectname.

+
objectname compute
+

Computes the machine parameters.

+
objectname get key
+

Returns the value corresponding with given key. +The following is the list of available keys.

+
    +

  • -epsilon : smallest value so that 1+epsilon>1 is false

    • +

  • -rounding : The rounding mode used on the machine. +The rounding occurs when more than t digits would be required to +represent the number. +Two modes can be determined with the current system : +"chop" means than only t digits are kept, no matter the value of the number +"proper" means that another rounding mode is used, be it "round to nearest", +"round up", "round down".

    • +

  • -basis : the basis of the floating-point representation. +The basis is usually 2, i.e. binary representation (for example IEEE 754 machines), +but some machines (like HP calculators for example) uses 10, or 16, etc...

    • +

  • -mantissa : the number of bits in the mantissa

    • +

  • -exponentmax : the largest positive exponent before overflow occurs

    • +

  • -exponentmin : the largest negative exponent before (gradual) underflow occurs

    • +

  • -vmax : largest positive value before overflow occurs

    • +

  • -vmin : largest negative value before (gradual) underflow occurs

    • +
+
objectname tostring
+

Return a report for machine parameters.

+
objectname print
+

Print machine parameters on standard output.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +
ADDED embedded/www/tcllib/files/modules/math/math.html Index: embedded/www/tcllib/files/modules/math/math.html ================================================================== --- embedded/www/tcllib/files/modules/math/math.html +++ embedded/www/tcllib/files/modules/math/math.html @@ -0,0 +1,218 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math(n) 1.2.5 tcllib "Tcl Math Library"

+

Name

+

math - Tcl Math Library

+
+ + +

Description

+

The math package provides utility math functions.

+

Besides a set of basic commands, available via the package math, +there are more specialised packages:

+ +
+

BASIC COMMANDS

+
+
::math::cov value value ?value ...?
+

Return the coefficient of variation expressed as percent of two or +more numeric values.

+
::math::integrate list of xy value pairs
+

Return the area under a "curve" defined by a set of x,y pairs and the +error bound as a list.

+
::math::fibonacci n
+

Return the n'th Fibonacci number.

+
::math::max value ?value ...?
+

Return the maximum of one or more numeric values.

+
::math::mean value ?value ...?
+

Return the mean, or "average" of one or more numeric values.

+
::math::min value ?value ...?
+

Return the minimum of one or more numeric values.

+
::math::product value ?value ...?
+

Return the product of one or more numeric values.

+
::math::random ?value1? ?value2?
+

Return a random number. If no arguments are given, the number is a +floating point value between 0 and 1. If one argument is given, the +number is an integer value between 0 and value1. If two +arguments are given, the number is an integer value between +value1 and value2.

+
::math::sigma value value ?value ...?
+

Return the population standard deviation of two or more numeric +values.

+
::math::stats value value ?value ...?
+

Return the mean, standard deviation, and coefficient of variation (as +percent) as a list.

+
::math::sum value ?value ...?
+

Return the sum of one or more numeric values.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/math_geometry.html Index: embedded/www/tcllib/files/modules/math/math_geometry.html ================================================================== --- embedded/www/tcllib/files/modules/math/math_geometry.html +++ embedded/www/tcllib/files/modules/math/math_geometry.html @@ -0,0 +1,549 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::geometry(n) 1.2.2 tcllib "Tcl Math Library"

+

Name

+

math::geometry - Geometrical computations

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.5?
    • +
  • package require math::geometry ?1.2.2?
    • +
+ +
+
+

Description

+

The math::geometry package is a collection of functions for +computations and manipulations on two-dimensional geometrical objects, +such as points, lines and polygons.

+

The geometrical objects are implemented as plain lists of coordinates. +For instance a line is defined by a list of four numbers, the x- and +y-coordinate of a first point and the x- and y-coordinates of a second +point on the line.

+

The various types of object are recognised by the number of coordinate +pairs and the context in which they are used: a list of four elements +can be regarded as an infinite line, a finite line segment but also +as a polyline of one segment and a point set of two points.

+

Currently the following types of objects are distinguished:

+
    +

  • point - a list of two coordinates representing the x- and +y-coordinates respectively.

    • +

  • line - a list of four coordinates, interpreted as the x- and +y-coordinates of two distinct points on the line.

    • +

  • line segment - a list of four coordinates, interpreted as the +x- and y-coordinates of the first and the last points on the line +segment.

    • +

  • polyline - a list of an even number of coordinates, +interpreted as the x- and y-coordinates of an ordered set of points.

    • +

  • polygon - like a polyline, but the implicit assumption is that +the polyline is closed (if the first and last points do not coincide, +the missing segment is automatically added).

    • +

  • point set - again a list of an even number of coordinates, but +the points are regarded without any ordering.

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::geometry::+ point1 point2
+

Compute the sum of the two vectors given as points and return it. +The result is a vector as well.

+
::math::geometry::- point1 point2
+

Compute the difference (point1 - point2) of the two vectors +given as points and return it. The result is a vector as well.

+
::math::geometry::p x y
+

Construct a point from its coordinates and return it as the +result of the command.

+
::math::geometry::distance point1 point2
+

Compute the distance between the two points and return it as the +result of the command. This is in essence the same as

+
+    math::geometry::length [math::geomtry::- point1 point2]
+
+
+
::math::geometry::length point
+

Compute the length of the vector and return it as the +result of the command.

+
::math::geometry::s* factor point
+

Scale the vector by the factor and return it as the +result of the command. This is a vector as well.

+
::math::geometry::direction angle
+

Given the angle in degrees this command computes and returns +the unit vector pointing into this direction. The vector for +angle == 0 points to the right (up), and for angle == 90 up (north).

+
::math::geometry::h length
+

Returns a horizontal vector on the X-axis of the specified length. +Positive lengths point to the right (east).

+
::math::geometry::v length
+

Returns a vertical vector on the Y-axis of the specified length. +Positive lengths point down (south).

+
::math::geometry::between point1 point2 s
+

Compute the point which is at relative distance s between the two +points and return it as the result of the command. A relative distance of +0 returns point1, the distance 1 returns point2. +Distances < 0 or > 1 extrapolate along the line between the two point.

+
::math::geometry::octant point
+

Compute the octant of the circle the point is in and return it as the result +of the command. The possible results are

+
    +

  1. east

    2. +

  2. northeast

    3. +

  3. north

    4. +

  4. northwest

    5. +

  5. west

    6. +

  6. southwest

    7. +

  7. south

    8. +

  8. southeast

    9. +
+

Each octant is the arc of the circle +/- 22.5 degrees from the cardinal direction +the octant is named for.

+
::math::geometry::rect nw se
+

Construct a rectangle from its northwest and southeast corners and return +it as the result of the command.

+
::math::geometry::nwse rect
+

Extract the northwest and southeast corners of the rectangle and return +them as the result of the command (a 2-element list containing the +points, in the named order).

+
::math::geometry::angle line
+

Calculate the angle from the positive x-axis to a given line +(in two dimensions only).

+
+
list line
+

Coordinates of the line

+
+
::math::geometry::calculateDistanceToLine P line
+

Calculate the distance of point P to the (infinite) line and return the +result

+
+
list P
+

List of two numbers, the coordinates of the point

+
list line
+

List of four numbers, the coordinates of two points +on the line

+
+
::math::geometry::calculateDistanceToLineSegment P linesegment
+

Calculate the distance of point P to the (finite) line segment and +return the result.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list linesegment
+

List of four numbers, the coordinates of the +first and last points of the line segment

+
+
::math::geometry::calculateDistanceToPolyline P polyline
+

Calculate the distance of point P to the polyline and +return the result. Note that a polyline needs not to be closed.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list polyline
+

List of numbers, the coordinates of the +vertices of the polyline

+
+
::math::geometry::calculateDistanceToPolygon P polygon
+

Calculate the distance of point P to the polygon and +return the result. If the list of coordinates is not closed (first and last +points differ), it is automatically closed.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list polygon
+

List of numbers, the coordinates of the +vertices of the polygon

+
+
::math::geometry::findClosestPointOnLine P line
+

Return the point on a line which is closest to a given point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list line
+

List of four numbers, the coordinates of two points +on the line

+
+
::math::geometry::findClosestPointOnLineSegment P linesegment
+

Return the point on a line segment which is closest to a given +point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list linesegment
+

List of four numbers, the first and last +points on the line segment

+
+
::math::geometry::findClosestPointOnPolyline P polyline
+

Return the point on a polyline which is closest to a given +point.

+
+
list P
+

List of two numbers, the coordinates of the point

+
list polyline
+

List of numbers, the vertices of the polyline

+
+
::math::geometry::lengthOfPolyline polyline
+

Return the length of the polyline (note: it not regarded as a +polygon)

+
+
list polyline
+

List of numbers, the vertices of the polyline

+
+
::math::geometry::movePointInDirection P direction dist
+

Move a point over a given distance in a given direction and return the +new coordinates (in two dimensions only).

+
+
list P
+

Coordinates of the point to be moved

+
double direction
+

Direction (in degrees; 0 is to the right, 90 +upwards)

+
list dist
+

Distance over which to move the point

+
+
::math::geometry::lineSegmentsIntersect linesegment1 linesegment2
+

Check if two line segments intersect or coincide. Returns 1 if that is +the case, 0 otherwise (in two dimensions only). If an endpoint of one segment lies on +the other segment (or is very close to the segment), they are considered to intersect

+
+
list linesegment1
+

First line segment

+
list linesegment2
+

Second line segment

+
+
::math::geometry::findLineSegmentIntersection linesegment1 linesegment2
+

Find the intersection point of two line segments. Return the coordinates +or the keywords "coincident" or "none" if the line segments coincide or +have no points in common (in two dimensions only).

+
+
list linesegment1
+

First line segment

+
list linesegment2
+

Second line segment

+
+
::math::geometry::findLineIntersection line1 line2
+

Find the intersection point of two (infinite) lines. Return the coordinates +or the keywords "coincident" or "none" if the lines coincide or +have no points in common (in two dimensions only).

+
+
list line1
+

First line

+
list line2
+

Second line

+
+

See section References for details on the algorithm and math behind it.

+
::math::geometry::polylinesIntersect polyline1 polyline2
+

Check if two polylines intersect or not (in two dimensions only).

+
+
list polyline1
+

First polyline

+
list polyline2
+

Second polyline

+
+
::math::geometry::polylinesBoundingIntersect polyline1 polyline2 granularity
+

Check whether two polylines intersect, but reduce +the correctness of the result to the given granularity. +Use this for faster, but weaker, intersection checking.

+

How it works:

+

Each polyline is split into a number of smaller polylines, +consisting of granularity points each. If a pair of those smaller +lines' bounding boxes intersect, then this procedure returns 1, +otherwise it returns 0.

+
+
list polyline1
+

First polyline

+
list polyline2
+

Second polyline

+
int granularity
+

Number of points in each part (<=1 means check +every edge)

+
+
::math::geometry::intervalsOverlap y1 y2 y3 y4 strict
+

Check if two intervals overlap.

+
+
double y1,y2
+

Begin and end of first interval

+
double y3,y4
+

Begin and end of second interval

+
logical strict
+

Check for strict or non-strict overlap

+
+
::math::geometry::rectanglesOverlap P1 P2 Q1 Q2 strict
+

Check if two rectangles overlap.

+
+
list P1
+

upper-left corner of the first rectangle

+
list P2
+

lower-right corner of the first rectangle

+
list Q1
+

upper-left corner of the second rectangle

+
list Q2
+

lower-right corner of the second rectangle

+
list strict
+

choosing strict or non-strict interpretation

+
+
::math::geometry::bbox polyline
+

Calculate the bounding box of a polyline. Returns a list of four +coordinates: the upper-left and the lower-right corner of the box.

+
+
list polyline
+

The polyline to be examined

+
+
::math::geometry::pointInsidePolygon P polyline
+

Determine if a point is completely inside a polygon. If the point +touches the polygon, then the point is not completely inside the +polygon.

+
+
list P
+

Coordinates of the point

+
list polyline
+

The polyline to be examined

+
+
::math::geometry::pointInsidePolygonAlt P polyline
+

Determine if a point is completely inside a polygon. If the point +touches the polygon, then the point is not completely inside the +polygon. Note: this alternative procedure uses the so-called +winding number to determine this. It handles self-intersecting polygons +in a "natural" way.

+
+
list P
+

Coordinates of the point

+
list polyline
+

The polyline to be examined

+
+
::math::geometry::rectangleInsidePolygon P1 P2 polyline
+

Determine if a rectangle is completely inside a polygon. If polygon +touches the rectangle, then the rectangle is not complete inside the +polygon.

+
+
list P1
+

Upper-left corner of the rectangle

+
list P2
+

Lower-right corner of the rectangle

+
list polygon
+

The polygon in question

+
+
::math::geometry::areaPolygon polygon
+

Calculate the area of a polygon.

+
+
list polygon
+

The polygon in question

+
+
::math::geometry::translate vector polyline
+

Translate a polyline over a given vector

+
+
list vector
+

Translation vector

+
list polyline
+

The polyline to be rotated

+
+
::math::geometry::rotate angle polyline
+

Rotate a polyline over a given angle (degrees) around the origin

+
+
list angle
+

Angle over which to rotate the polyline (degrees)

+
list polyline
+

The polyline to be translated

+
+
::math::geometry::reflect angle polyline
+

Reflect a polyline in a line through the origin at a given angle (degrees) to the x-axis

+
+
list angle
+

Angle of the line of reflection (degrees)

+
list polyline
+

The polyline to be reflected

+
+
::math::geometry::degToRad angle
+

Convert from degrees to radians

+
+
list angle
+

Angle in degrees

+
+
::math::geometry::radToDeg angle
+

Convert from radians to degrees

+
+
list angle
+

Angle in radians

+
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: geometry of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/numtheory.html Index: embedded/www/tcllib/files/modules/math/numtheory.html ================================================================== --- embedded/www/tcllib/files/modules/math/numtheory.html +++ embedded/www/tcllib/files/modules/math/numtheory.html @@ -0,0 +1,178 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::numtheory(n) 1.0 tcllib "Tcl Math Library"

+

Name

+

math::numtheory - Number Theory

+
+ +

Synopsis

+
+
    +
  • package require Tcl ?8.5?
    • +
  • package require math::numtheory ?1.0?
    • +
+ +
+
+

Description

+

This package is for collecting various number-theoretic operations, +though at the moment it only provides that of testing whether an +integer is a prime.

+
+
math::numtheory::isprime N ?option value ...?
+

The isprime command tests whether the integer N is a + prime, returning a boolean true value for prime N and a + boolean false value for non-prime N. The formal definition of + 'prime' used is the conventional, that the number being tested is + greater than 1 and only has trivial divisors.

+

To be precise, the return value is one of 0 (if N is + definitely not a prime), 1 (if N is definitely a + prime), and on (if N is probably prime); the latter + two are both boolean true values. The case that an integer may be + classified as "probably prime" arises because the Miller-Rabin + algorithm used in the test implementation is basically probabilistic, + and may if we are unlucky fail to detect that a number is in fact + composite. Options may be used to select the risk of such + "false positives" in the test. 1 is returned for "small" + N (which currently means N < 118670087467), where it is + known that no false positives are possible.

+

The only option currently defined is:

+
+ +
-randommr repetitions
+

which controls how many times the Miller-Rabin test should be + repeated with randomly chosen bases. Each repetition reduces the + probability of a false positive by a factor at least 4. The + default for repetitions is 4.

+
+

Unknown options are silently ignored.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: numtheory of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/optimize.html Index: embedded/www/tcllib/files/modules/math/optimize.html ================================================================== --- embedded/www/tcllib/files/modules/math/optimize.html +++ embedded/www/tcllib/files/modules/math/optimize.html @@ -0,0 +1,386 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::optimize(n) 1.0 tcllib "Tcl Math Library"

+

Name

+

math::optimize - Optimisation routines

+
+ + +

Description

+

This package implements several optimisation algorithms:

+
    +

  • Minimize or maximize a function over a given interval

    • +

  • Solve a linear program (maximize a linear function subject to linear +constraints)

    • +

  • Minimize a function of several variables given an initial guess for the +location of the minimum.

    • +
+

The package is fully implemented in Tcl. No particular attention has +been paid to the accuracy of the calculations. Instead, the +algorithms have been used in a straightforward manner.

+

This document describes the procedures and explains their usage.

+
+

PROCEDURES

+

This package defines the following public procedures:

+
+
::math::optimize::minimum begin end func maxerr
+

Minimize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the minimum. No guarantee is made that the global +minimum is found.

+

The procedure returns the "x" value for which the function is minimal.

+

This procedure has been deprecated - use min_bound_1d instead

+

begin - Start of the interval

+

end - End of the interval

+

func - Name of the function to be minimized (a procedure taking +one argument).

+

maxerr - Maximum relative error (defaults to 1.0e-4)

+
::math::optimize::maximum begin end func maxerr
+

Maximize the given (continuous) function by examining the values in the +given interval. The procedure determines the values at both ends and in the +centre of the interval and then constructs a new interval of 1/2 length +that includes the maximum. No guarantee is made that the global +maximum is found.

+

The procedure returns the "x" value for which the function is maximal.

+

This procedure has been deprecated - use max_bound_1d instead

+

begin - Start of the interval

+

end - End of the interval

+

func - Name of the function to be maximized (a procedure taking +one argument).

+

maxerr - Maximum relative error (defaults to 1.0e-4)

+
::math::optimize::min_bound_1d func begin end ?-relerror reltol? ?-abserror abstol? ?-maxiter maxiter? ?-trace traceflag?
+

Miminizes a function of one variable in the given interval. The procedure +uses Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a global minimum is found. The function to evaluate, func, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument.

+

x1 and x2 are the two bounds of +the interval in which the minimum is to be found. They need not be in +increasing order.

+

reltol, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. abstol, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of abstol to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale.

+

maxiter may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than maxiter times, it returns an error to the caller.

+

traceFlag is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace).

+
::math::optimize::min_unbound_1d func begin end ?-relerror reltol? ?-abserror abstol? ?-maxiter maxiter? ?-trace traceflag?
+

Miminizes a function of one variable over the entire real number line. +The procedure uses parabolic extrapolation combined with golden-section +dilatation to search for a region where a minimum exists, followed by +Brent's method of parabolic interpolation, protected by golden-section +subdivisions if the interpolation is not converging. No guarantee is made +that a global minimum is found. The function to evaluate, func, +must be a single Tcl command; it will be evaluated with an abscissa appended +as the last argument.

+

x1 and x2 are two initial guesses at where the minimum +may lie. x1 is the starting point for the minimization, and +the difference between x2 and x1 is used as a hint at the +characteristic length scale of the problem.

+

reltol, if specified, is the desired upper bound +on the relative error of the result; default is 1.0e-7. The given value +should never be smaller than the square root of the machine's floating point +precision, or else convergence is not guaranteed. abstol, if specified, +is the desired upper bound on the absolute error of the result; default +is 1.0e-10. Caution must be used with small values of abstol to +avoid overflow/underflow conditions; if the minimum is expected to lie +about a small but non-zero abscissa, you consider either shifting the +function or changing its length scale.

+

maxiter may be used to constrain the number of function evaluations +to be performed; default is 100. If the command evaluates the function +more than maxiter times, it returns an error to the caller.

+

traceFlag is a Boolean value. If true, it causes the command to +print a message on the standard output giving the abscissa and ordinate +at each function evaluation, together with an indication of what type +of interpolation was chosen. Default is 0 (no trace).

+
::math::optimize::solveLinearProgram objective constraints
+

Solve a linear program in standard form using a straightforward +implementation of the Simplex algorithm. (In the explanation below: The +linear program has N constraints and M variables).

+

The procedure returns a list of M values, the values for which the +objective function is maximal or a single keyword if the linear program +is not feasible or unbounded (either "unfeasible" or "unbounded")

+

objective - The M coefficients of the objective function

+

constraints - Matrix of coefficients plus maximum values that +implement the linear constraints. It is expected to be a list of N lists +of M+1 numbers each, M coefficients and the maximum value.

+
::math::optimize::linearProgramMaximum objective result
+

Convenience function to return the maximum for the solution found by the +solveLinearProgram procedure.

+

objective - The M coefficients of the objective function

+

result - The result as returned by solveLinearProgram

+
::math::optimize::nelderMead objective xVector ?-scale xScaleVector? ?-ftol epsilon? ?-maxiter count? ??-trace? flag?
+

Minimizes, in unconstrained fashion, a function of several variable over all +of space. The function to evaluate, objective, must be a single Tcl +command. To it will be appended as many elements as appear in the initial guess at +the location of the minimum, passed in as a Tcl list, xVector.

+

xScaleVector is an initial guess at the problem scale; the first +function evaluations will be made by varying the co-ordinates in xVector +by the amounts in xScaleVector. If xScaleVector is not supplied, +the co-ordinates will be varied by a factor of 1.0001 (if the co-ordinate +is non-zero) or by a constant 0.0001 (if the co-ordinate is zero).

+

epsilon is the desired relative error in the value of the function +evaluated at the minimum. The default is 1.0e-7, which usually gives three +significant digits of accuracy in the values of the x's.

+

pp +count is a limit on the number of trips through the main loop of +the optimizer. The number of function evaluations may be several times +this number. If the optimizer fails to find a minimum to within ftol +in maxiter iterations, it returns its current best guess and an +error status. Default is to allow 500 iterations.

+

flag is a flag that, if true, causes a line to be written to the +standard output for each evaluation of the objective function, giving +the arguments presented to the function and the value returned. Default is +false.

+

The nelderMead procedure returns a list of alternating keywords and +values suitable for use with array set. The meaning of the keywords is:

+

x is the approximate location of the minimum.

+

y is the value of the function at x.

+

yvec is a vector of the best N+1 function values achieved, where +N is the dimension of x

+

vertices is a list of vectors giving the function arguments +corresponding to the values in yvec.

+

nIter is the number of iterations required to achieve convergence or +fail.

+

status is 'ok' if the operation succeeded, or 'too-many-iterations' +if the maximum iteration count was exceeded.

+

nelderMead minimizes the given function using the downhill +simplex method of Nelder and Mead. This method is quite slow - much +faster methods for minimization are known - but has the advantage of being +extremely robust in the face of problems where the minimum lies in +a valley of complex topology.

+

nelderMead can occasionally find itself "stuck" at a point where +it can make no further progress; it is recommended that the caller +run it at least a second time, passing as the initial guess the +result found by the previous call. The second run is usually very +fast.

+

nelderMead can be used in some cases for constrained optimization. +To do this, add a large value to the objective function if the parameters +are outside the feasible region. To work effectively in this mode, +nelderMead requires that the initial guess be feasible and +usually requires that the feasible region be convex.

+
+
+

NOTES

+

Several of the above procedures take the names of procedures as +arguments. To avoid problems with the visibility of these +procedures, the fully-qualified name of these procedures is determined +inside the optimize routines. For the user this has only one +consequence: the named procedure must be visible in the calling +procedure. For instance:

+
+    namespace eval ::mySpace {
+       namespace export calcfunc
+       proc calcfunc { x } { return $x }
+    }
+    #
+    # Use a fully-qualified name
+    #
+    namespace eval ::myCalc {
+       puts [min_bound_1d ::myCalc::calcfunc $begin $end]
+    }
+    #
+    # Import the name
+    #
+    namespace eval ::myCalc {
+       namespace import ::mySpace::calcfunc
+       puts [min_bound_1d calcfunc $begin $end]
+    }
+
+

The simple procedures minimum and maximum have been +deprecated: the alternatives are much more flexible, robust and +require less function evaluations.

+
+

EXAMPLES

+

Let us take a few simple examples:

+

Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10):

+
+proc efunc { x } { expr {$x*$x*$x * exp(-3.0*$x)} }
+puts "Maximum at: [::math::optimize::max_bound_1d efunc 0.0 10.0]"
+
+

The maximum allowed error determines the number of steps taken (with +each step in the iteration the interval is reduced with a factor 1/2). +Hence, a maximum error of 0.0001 is achieved in approximately 14 steps.

+

An example of a linear program is:

+

Optimise the expression 3x+2y, where:

+
+   x >= 0 and y >= 0 (implicit constraints, part of the
+                     definition of linear programs)
+   x + y   <= 1      (constraints specific to the problem)
+   2x + 5y <= 10
+
+

This problem can be solved as follows:

+
+   set solution [::math::optimize::solveLinearProgram  { 3.0   2.0 }  { { 1.0   1.0   1.0 }
+        { 2.0   5.0  10.0 } } ]
+
+

Note, that a constraint like:

+
+   x + y >= 1
+
+

can be turned into standard form using:

+
+   -x  -y <= -1
+
+

The theory of linear programming is the subject of many a text book and +the Simplex algorithm that is implemented here is the best-known +method to solve this type of problems, but it is not the only one.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: optimize of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/polynomials.html Index: embedded/www/tcllib/files/modules/math/polynomials.html ================================================================== --- embedded/www/tcllib/files/modules/math/polynomials.html +++ embedded/www/tcllib/files/modules/math/polynomials.html @@ -0,0 +1,294 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::polynomials(n) 1.0.1 tcllib "Tcl Math Library"

+

Name

+

math::polynomials - Polynomial functions

+
+ + +

Description

+

This package deals with polynomial functions of one variable:

+
    +

  • the basic arithmetic operations are extended to polynomials

    • +

  • computing the derivatives and primitives of these functions

    • +

  • evaluation through a general procedure or via specific procedures)

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::polynomials::polynomial coeffs
+

Return an (encoded) list that defines the polynomial. A polynomial

+
+   f(x) = a + b.x + c.x**2 + d.x**3
+
+

can be defined via:

+
+   set f [::math::polynomials::polynomial [list $a $b $c $d]
+
+
+
list coeffs
+

Coefficients of the polynomial (in ascending +order)

+
+
::math::polynomials::polynCmd coeffs
+

Create a new procedure that evaluates the polynomial. The name of the +polynomial is automatically generated. Useful if you need to evualuate +the polynomial many times, as the procedure consists of a single +[expr] command.

+
+
list coeffs
+

Coefficients of the polynomial (in ascending +order) or the polynomial definition returned by the polynomial +command.

+
+
::math::polynomials::evalPolyn polynomial x
+

Evaluate the polynomial at x.

+
+
list polynomial
+

The polynomial's definition (as returned by +the polynomial command). +order)

+
float x
+

The coordinate at which to evaluate the polynomial

+
+
::math::polynomials::addPolyn polyn1 polyn2
+

Return a new polynomial which is the sum of the two others.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::subPolyn polyn1 polyn2
+

Return a new polynomial which is the difference of the two others.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::multPolyn polyn1 polyn2
+

Return a new polynomial which is the product of the two others. If one +of the arguments is a scalar value, the other polynomial is simply +scaled.

+
+
list polyn1
+

The first polynomial operand or a scalar

+
list polyn2
+

The second polynomial operand or a scalar

+
+
::math::polynomials::divPolyn polyn1 polyn2
+

Divide the first polynomial by the second polynomial and return the +result. The remainder is dropped

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::remainderPolyn polyn1 polyn2
+

Divide the first polynomial by the second polynomial and return the +remainder.

+
+
list polyn1
+

The first polynomial operand

+
list polyn2
+

The second polynomial operand

+
+
::math::polynomials::derivPolyn polyn
+

Differentiate the polynomial and return the result.

+
+
list polyn
+

The polynomial to be differentiated

+
+
::math::polynomials::primitivePolyn polyn
+

Integrate the polynomial and return the result. The integration +constant is set to zero.

+
+
list polyn
+

The polynomial to be integrated

+
+
::math::polynomials::degreePolyn polyn
+

Return the degree of the polynomial.

+
+
list polyn
+

The polynomial to be examined

+
+
::math::polynomials::coeffPolyn polyn index
+

Return the coefficient of the term of the index'th degree of the +polynomial.

+
+
list polyn
+

The polynomial to be examined

+
int index
+

The degree of the term

+
+
::math::polynomials::allCoeffsPolyn polyn
+

Return the coefficients of the polynomial (in ascending order).

+
+
list polyn
+

The polynomial in question

+
+
+
+

REMARKS ON THE IMPLEMENTATION

+

The implementation for evaluating the polynomials at some point uses +Horn's rule, which guarantees numerical stability and a minimum of +arithmetic operations. +To recognise that a polynomial definition is indeed a correct +definition, it consists of a list of two elements: the keyword +"POLYNOMIAL" and the list of coefficients in descending order. The +latter makes it easier to implement Horner's rule.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: polynomials of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/qcomplex.html Index: embedded/www/tcllib/files/modules/math/qcomplex.html ================================================================== --- embedded/www/tcllib/files/modules/math/qcomplex.html +++ embedded/www/tcllib/files/modules/math/qcomplex.html @@ -0,0 +1,331 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::complexnumbers(n) 1.0.2 tcllib "Tcl Math Library"

+

Name

+

math::complexnumbers - Straightforward complex number package

+
+ + +

Description

+

The mathematical module complexnumbers provides a straightforward +implementation of complex numbers in pure Tcl. The philosophy is that +the user knows he or she is dealing with complex numbers in an abstract +way and wants as high a performance as can be had within the limitations +of an interpreted language.

+

Therefore the procedures defined in this package assume that the +arguments are valid (representations of) "complex numbers", that is, +lists of two numbers defining the real and imaginary part of a +complex number (though this is a mere detail: rely on the +complex command to construct a valid number.)

+

Most procedures implement the basic arithmetic operations or elementary +functions whereas several others convert to and from different +representations:

+
+    set z [complex 0 1]
+    puts "z = [tostring $z]"
+    puts "z**2 = [* $z $z]
+
+

would result in:

+
+    z = i
+    z**2 = -1
+
+
+

AVAILABLE PROCEDURES

+

The package implements all or most basic operations and elementary +functions.

+

The arithmetic operations are:

+
+
::math::complexnumbers::+ z1 z2
+

Add the two arguments and return the resulting complex number

+
+
complex z1 (in)
+

First argument in the summation

+
complex z2 (in)
+

Second argument in the summation

+
+
::math::complexnumbers::- z1 z2
+

Subtract the second argument from the first and return the +resulting complex number. If there is only one argument, the +opposite of z1 is returned (i.e. -z1)

+
+
complex z1 (in)
+

First argument in the subtraction

+
complex z2 (in)
+

Second argument in the subtraction (optional)

+
+
::math::complexnumbers::* z1 z2
+

Multiply the two arguments and return the resulting complex number

+
+
complex z1 (in)
+

First argument in the multiplication

+
complex z2 (in)
+

Second argument in the multiplication

+
+
::math::complexnumbers::/ z1 z2
+

Divide the first argument by the second and return the resulting complex +number

+
+
complex z1 (in)
+

First argument (numerator) in the division

+
complex z2 (in)
+

Second argument (denominator) in the division

+
+
::math::complexnumbers::conj z1
+

Return the conjugate of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
+

Conversion/inquiry procedures:

+
+
::math::complexnumbers::real z1
+

Return the real part of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::imag z1
+

Return the imaginary part of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::mod z1
+

Return the modulus of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::arg z1
+

Return the argument ("angle" in radians) of the given complex number

+
+
complex z1 (in)
+

Complex number in question

+
+
::math::complexnumbers::complex real imag
+

Construct the complex number "real + imag*i" and return it

+
+
float real (in)
+

The real part of the new complex number

+
float imag (in)
+

The imaginary part of the new complex number

+
+
::math::complexnumbers::tostring z1
+

Convert the complex number to the form "real + imag*i" and return the +string

+
+
float complex (in)
+

The complex number to be converted

+
+
+

Elementary functions:

+
+
::math::complexnumbers::exp z1
+

Calculate the exponential for the given complex argument and return the +result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::sin z1
+

Calculate the sine function for the given complex argument and return +the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::cos z1
+

Calculate the cosine function for the given complex argument and return +the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::tan z1
+

Calculate the tangent function for the given complex argument and +return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::log z1
+

Calculate the (principle value of the) logarithm for the given complex +argument and return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::sqrt z1
+

Calculate the (principle value of the) square root for the given complex +argument and return the result

+
+
complex z1 (in)
+

The complex argument for the function

+
+
::math::complexnumbers::pow z1 z2
+

Calculate "z1 to the power of z2" and return the result

+
+
complex z1 (in)
+

The complex number to be raised to a power

+
complex z2 (in)
+

The complex power to be used

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: complexnumbers of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/rational_funcs.html Index: embedded/www/tcllib/files/modules/math/rational_funcs.html ================================================================== --- embedded/www/tcllib/files/modules/math/rational_funcs.html +++ embedded/www/tcllib/files/modules/math/rational_funcs.html @@ -0,0 +1,272 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::rationalfunctions(n) 1.0.1 tcllib "Math"

+

Name

+

math::rationalfunctions - Polynomial functions

+
+ + +

Description

+

This package deals with rational functions of one variable:

+
    +

  • the basic arithmetic operations are extended to rational functions

    • +

  • computing the derivatives of these functions

    • +

  • evaluation through a general procedure or via specific procedures)

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::rationalfunctions::rationalFunction num den
+

Return an (encoded) list that defines the rational function. A +rational function

+
+             1 + x^3
+   f(x) = ------------
+          1 + 2x + x^2
+
+

can be defined via:

+
+   set f [::math::rationalfunctions::rationalFunction [list 1 0 0 1]  [list 1 2 1]]
+
+
+
list num
+

Coefficients of the numerator of the rational +function (in ascending order)

+
list den
+

Coefficients of the denominator of the rational +function (in ascending order)

+
+
::math::rationalfunctions::ratioCmd num den
+

Create a new procedure that evaluates the rational function. The name of the +function is automatically generated. Useful if you need to evaluate +the function many times, as the procedure consists of a single +[expr] command.

+
+
list num
+

Coefficients of the numerator of the rational +function (in ascending order)

+
list den
+

Coefficients of the denominator of the rational +function (in ascending order)

+
+
::math::rationalfunctions::evalRatio rational x
+

Evaluate the rational function at x.

+
+
list rational
+

The rational function's definition (as returned +by the rationalFunction command). +order)

+
float x
+

The coordinate at which to evaluate the function

+
+
::math::rationalfunctions::addRatio ratio1 ratio2
+

Return a new rational function which is the sum of the two others.

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::subRatio ratio1 ratio2
+

Return a new rational function which is the difference of the two +others.

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::multRatio ratio1 ratio2
+

Return a new rational function which is the product of the two others. +If one of the arguments is a scalar value, the other rational function is +simply scaled.

+
+
list ratio1
+

The first rational function operand or a scalar

+
list ratio2
+

The second rational function operand or a scalar

+
+
::math::rationalfunctions::divRatio ratio1 ratio2
+

Divide the first rational function by the second rational function and +return the result. The remainder is dropped

+
+
list ratio1
+

The first rational function operand

+
list ratio2
+

The second rational function operand

+
+
::math::rationalfunctions::derivPolyn ratio
+

Differentiate the rational function and return the result.

+
+
list ratio
+

The rational function to be differentiated

+
+
::math::rationalfunctions::coeffsNumerator ratio
+

Return the coefficients of the numerator of the rational function.

+
+
list ratio
+

The rational function to be examined

+
+
::math::rationalfunctions::coeffsDenominator ratio
+

Return the coefficients of the denominator of the rational +function.

+
+
list ratio
+

The rational function to be examined

+
+
+
+

REMARKS ON THE IMPLEMENTATION

+

The implementation of the rational functions relies on the +math::polynomials package. For further remarks see the documentation on +that package.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: rationalfunctions of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/roman.html Index: embedded/www/tcllib/files/modules/math/roman.html ================================================================== --- embedded/www/tcllib/files/modules/math/roman.html +++ embedded/www/tcllib/files/modules/math/roman.html @@ -0,0 +1,178 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::roman() 1.0 tcllib "Tcl Math Library"

+

Name

+

math::roman - Tools for creating and manipulating roman numerals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require math::roman ?1.0?
    • +
+ +
+
+

Description

+

::math::roman is a pure-Tcl library for converting between integers + and roman numerals. It also provides utility functions for sorting and performing + arithmetic on roman numerals.

+

This code was originally harvested from the Tcler's wiki at + http://wiki.tcl.tk/1823 and as such is free for any use for + any purpose. Many thanks to the ingeneous folk who devised + these clever routines and generously contributed them to the + Tcl community.

+

While written and tested under Tcl 8.3, I expect this library + will work under all 8.x versions of Tcl.

+
+

COMMANDS

+
+ +
::math::roman::toroman i
+

Convert an integer to roman numerals. The result is always in + upper case. The value zero is converted to an empty string.

+
::math::roman::tointeger r
+

Convert a roman numeral into an integer.

+
::math::roman::sort list
+

Sort a list of roman numerals from smallest to largest.

+
::math::roman::expr args
+

Evaluate an expression where the operands are all roman numerals.

+
+

Of these commands both toroman and tointeger are exported +for easier use. The other two are not, as they could interfer or be +confused with existing Tcl commands.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: roman of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/romberg.html Index: embedded/www/tcllib/files/modules/math/romberg.html ================================================================== --- embedded/www/tcllib/files/modules/math/romberg.html +++ embedded/www/tcllib/files/modules/math/romberg.html @@ -0,0 +1,394 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::calculus::romberg(n) 0.6 tcllib "Tcl Math Library"

+

Name

+

math::calculus::romberg - Romberg integration

+
+ + +

Description

+

The romberg procedures in the math::calculus package +perform numerical integration of a function of one variable. They +are intended to be of "production quality" in that they are robust, +precise, and reasonably efficient in terms of the number of function +evaluations.

+
+

PROCEDURES

+

The following procedures are available for Romberg integration:

+
+
::math::calculus::romberg f a b ?-option value...?
+

Integrates an analytic function over a given interval.

+
::math::calculus::romberg_infinity f a b ?-option value...?
+

Integrates an analytic function over a half-infinite interval.

+
::math::calculus::romberg_sqrtSingLower f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +lower limit.

+
::math::calculus::romberg_sqrtSingUpper f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of an inverse square root singularity at the +upper limit.

+
::math::calculus::romberg_powerLawLower gamma f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +lower limit.

+
::math::calculus::romberg_powerLawUpper gamma f a b ?-option value...?
+

Integrates a function that is expected to be analytic over an interval +except for the presence of a power law singularity at the +upper limit.

+
::math::calculus::romberg_expLower f a b ?-option value...?
+

Integrates an exponentially growing function; the lower limit of the +region of integration may be arbitrarily large and negative.

+
::math::calculus::romberg_expUpper f a b ?-option value...?
+

Integrates an exponentially decaying function; the upper limit of the +region of integration may be arbitrarily large.

+
+
+

PARAMETERS

+
+
f
+

Function to integrate. Must be expressed as a single Tcl command, +to which will be appended a single argument, specifically, the +abscissa at which the function is to be evaluated. The first word +of the command will be processed with namespace which in the +caller's scope prior to any evaluation. Given this processing, the +command may local to the calling namespace rather than needing to be +global.

+
a
+

Lower limit of the region of integration.

+
b
+

Upper limit of the region of integration. For the +romberg_sqrtSingLower, romberg_sqrtSingUpper, +romberg_powerLawLower, romberg_powerLawUpper, +romberg_expLower, and romberg_expUpper procedures, +the lower limit must be strictly less than the upper. For +the other procedures, the limits may appear in either order.

+
gamma
+

Power to use for a power law singularity; see section +IMPROPER INTEGRALS for details.

+
+
+

OPTIONS

+
+
-abserror epsilon
+

Requests that the integration machinery proceed at most until +the estimated absolute error of the integral is less than +epsilon. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section IMPROPER INTEGRALS for details. Default +is 1.0e-08.

+
-relerror epsilon
+

Requests that the integration machinery proceed at most until +the estimated relative error of the integral is less than +epsilon. The error may be seriously over- or underestimated +if the function (or any of its derivatives) contains singularities; +see section IMPROPER INTEGRALS for details. Default is +1.0e-06.

+
-maxiter m
+

Requests that integration terminate after at most n triplings of +the number of evaluations performed. In other words, given n +for -maxiter, the integration machinery will make at most +3**n evaluations of the function. Default is 14, corresponding +to a limit approximately 4.8 million evaluations. (Well-behaved +functions will seldom require more than a few hundred evaluations.)

+
-degree d
+

Requests that an extrapolating polynomial of degree d be used +in Romberg integration; see section DESCRIPTION for +details. Default is 4. Can be at most m-1.

+
+
+

DESCRIPTION

+

The romberg procedure performs Romberg integration using +the modified midpoint rule. Romberg integration is an iterative +process. At the first step, the function is evaluated at the +midpoint of the region of integration, and the value is multiplied by +the width of the interval for the coarsest possible estimate. +At the second step, the interval is divided into three parts, +and the function is evaluated at the midpoint of each part; the +sum of the values is multiplied by three. At the third step, +nine parts are used, at the fourth twenty-seven, and so on, +tripling the number of subdivisions at each step.

+

Once the interval has been divided at least d times, +a polynomial is fitted to the integrals estimated in the last +d+1 divisions. The integrals are considered to be a +function of the square of the width of the subintervals +(any good numerical analysis text will discuss this process +under "Romberg integration"). The polynomial is extrapolated +to a step size of zero, computing a value for the integral and +an estimate of the error.

+

This process will be well-behaved only if the function is analytic +over the region of integration; there may be removable singularities +at either end of the region provided that the limit of the function +(and of all its derivatives) exists as the ends are approached. +Thus, romberg may be used to integrate a function like +f(x)=sin(x)/x over an interval beginning or ending at zero.

+

Note that romberg will either fail to converge or else return +incorrect error estimates if the function, or any of its derivatives, +has a singularity anywhere in the region of integration (except for +the case mentioned above). Care must be used, therefore, in +integrating a function like 1/(1-x**2) to avoid the places +where the derivative is singular.

+
+

IMPROPER INTEGRALS

+

Romberg integration is also useful for integrating functions over +half-infinite intervals or functions that have singularities. +The trick is to make a change of variable to eliminate the +singularity, and to put the singularity at one end or the other +of the region of integration. The math::calculus package +supplies a number of romberg procedures to deal with the +commoner cases.

+
+
romberg_infinity
+

Integrates a function over a half-infinite interval; either +a or b may be infinite. a and b must be +of the same sign; if you need to integrate across the axis, +say, from a negative value to positive infinity, +use romberg to integrate from the negative +value to a small positive value, and then romberg_infinity +to integrate from the positive value to positive infinity. The +romberg_infinity procedure works by making the change of +variable u=1/x, so that the integral from a to b of f(x) is +evaluated as the integral from 1/a to 1/b of f(1/u)/u**2.

+
romberg_powerLawLower and romberg_powerLawUpper
+

Integrate a function that has an integrable power law singularity +at either the lower or upper bound of the region of integration +(or has a derivative with a power law singularity there). +These procedures take a first parameter, gamma, which gives +the power law. The function or its first derivative are presumed to diverge as +(x-a)**(-gamma) or (b-x)**(-gamma). gamma +must be greater than zero and less than 1.

+

These procedures are useful not only in integrating functions +that go to infinity at one end of the region of integration, but +also functions whose derivatives do not exist at the end of +the region. For instance, integrating f(x)=pow(x,0.25) with the +origin as one end of the region will result in the romberg +procedure greatly underestimating the error in the integral. +The problem can be fixed by observing that the first derivative +of f(x), f'(x)=x**(-3/4)/4, goes to infinity at the origin. Integrating +using romberg_powerLawLower with gamma set to 0.75 +gives much more orderly convergence.

+

These procedures operate by making the change of variable +u=(x-a)**(1-gamma) (romberg_powerLawLower) or +u=(b-x)**(1-gamma) (romberg_powerLawUpper).

+

To summarize the meaning of gamma:

+
    +

  • If f(x) ~ x**(-a) (0 < a < 1), use gamma = a

    • +

  • If f'(x) ~ x**(-b) (0 < b < 1), use gamma = b

    • +
+
romberg_sqrtSingLower and romberg_sqrtSingUpper
+

These procedures behave identically to romberg_powerLawLower and +romberg_powerLawUpper for the common case of gamma=0.5; +that is, they integrate a function with an inverse square root +singularity at one end of the interval. They have a simpler +implementation involving square roots rather than arbitrary powers.

+
romberg_expLower and romberg_expUpper
+

These procedures are for integrating a function that grows or +decreases exponentially over a half-infinite interval. +romberg_expLower handles exponentially growing functions, and +allows the lower limit of integration to be an arbitrarily large +negative number. romberg_expUpper handles exponentially +decaying functions and allows the upper limit of integration to +be an arbitrary large positive number. The functions make the +change of variable u=exp(-x) and u=exp(x) respectively.

+
+
+

OTHER CHANGES OF VARIABLE

+

If you need an improper integral other than the ones listed here, +a change of variable can be written in very few lines of Tcl. +Because the Tcl coding that does it is somewhat arcane, +we offer a worked example here.

+

Let's say that the function that we want to integrate is +f(x)=exp(x)/sqrt(1-x*x) (not a very natural +function, but a good example), and we want to integrate +it over the interval (-1,1). The denominator falls to zero +at both ends of the interval. We wish to make a change of variable +from x to u +so that dx/sqrt(1-x**2) maps to du. Choosing x=sin(u), we can +find that dx=cos(u)*du, and sqrt(1-x**2)=cos(u). The integral +from a to b of f(x) is the integral from asin(a) to asin(b) +of f(sin(u))*cos(u).

+

We can make a function g that accepts an arbitrary function +f and the parameter u, and computes this new integrand.

+
+proc g { f u } {
+    set x [expr { sin($u) }]
+    set cmd $f; lappend cmd $x; set y [eval $cmd]
+    return [expr { $y / cos($u) }]
+}
+
+

Now integrating f from a to b is the same +as integrating g from asin(a) to asin(b). +It's a little tricky to get f consistently evaluated in +the caller's scope; the following procedure does it.

+
+proc romberg_sine { f a b args } {
+    set f [lreplace $f 0 0 [uplevel 1 [list namespace which [lindex $f 0]]]]
+    set f [list g $f]
+    return [eval [linsert $args 0 romberg $f [expr { asin($a) }] [expr { asin($b) }]]]
+}
+
+

This romberg_sine procedure will do any function with +sqrt(1-x*x) in the denominator. Our sample function is +f(x)=exp(x)/sqrt(1-x*x):

+
+proc f { x } {
+    expr { exp($x) / sqrt( 1. - $x*$x ) }
+}
+
+

Integrating it is a matter of applying romberg_sine +as we would any of the other romberg procedures:

+
+foreach { value error } [romberg_sine f -1.0 1.0] break
+puts [format "integral is %.6g +/- %.6g" $value $error]
+integral is 3.97746 +/- 2.3557e-010
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/special.html Index: embedded/www/tcllib/files/modules/math/special.html ================================================================== --- embedded/www/tcllib/files/modules/math/special.html +++ embedded/www/tcllib/files/modules/math/special.html @@ -0,0 +1,507 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::special(n) 0.3 tcllib "Tcl Math Library"

+

Name

+

math::special - Special mathematical functions

+
+ + +

Description

+

This package implements several so-called special functions, like +the Gamma function, the Bessel functions and such.

+

Each function is implemented by a procedure that bears its name (well, +in close approximation):

+
    +

  • J0 for the zeroth-order Bessel function of the first kind

    • +

  • J1 for the first-order Bessel function of the first kind

    • +

  • Jn for the nth-order Bessel function of the first kind

    • +

  • J1/2 for the half-order Bessel function of the first kind

    • +

  • J-1/2 for the minus-half-order Bessel function of the first kind

    • +

  • I_n for the modified Bessel function of the first kind of order n

    • +

  • Gamma for the Gamma function, erf and erfc for the error function and +the complementary error function

    • +

  • fresnel_C and fresnel_S for the Fresnel integrals

    • +

  • elliptic_K and elliptic_E (complete elliptic integrals)

    • +

  • exponent_Ei and other functions related to the so-called exponential +integrals

    • +

  • legendre, hermite: some of the classical orthogonal polynomials.

    • +
+
+

OVERVIEW

+

In the following table several characteristics of the functions in this +package are summarized: the domain for the argument, the values for the +parameters and error bounds.

+
+Family       | Function    | Domain x    | Parameter   | Error bound
+-------------+-------------+-------------+-------------+--------------
+Bessel       | J0, J1,     | all of R    | n = integer |   < 1.0e-8
+             | Jn          |             |             |  (|x|<20, n<20)
+Bessel       | J1/2, J-1/2,|  x > 0      | n = integer |   exact
+Bessel       | I_n         | all of R    | n = integer |   < 1.0e-6
+             |             |             |             |
+Elliptic     | cn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+functions    | dn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+             | sn          | 0 <= x <= 1 |     --      |   < 1.0e-10
+Elliptic     | K           | 0 <= x < 1  |     --      |   < 1.0e-6
+integrals    | E           | 0 <= x < 1  |     --      |   < 1.0e-6
+             |             |             |             |
+Error        | erf         |             |     --      |
+functions    | erfc        |             |             |
+             |             |             |             |
+Inverse      | invnorm     | 0 < x < 1   |     --      |   < 1.2e-9
+normal       |             |             |             |
+distribution |             |             |             |
+             |             |             |             |
+Exponential  | Ei          |  x != 0     |     --      |   < 1.0e-10 (relative)
+integrals    | En          |  x >  0     |     --      |   as Ei
+             | li          |  x > 0      |     --      |   as Ei
+             | Chi         |  x > 0      |     --      |   < 1.0e-8
+             | Shi         |  x > 0      |     --      |   < 1.0e-8
+             | Ci          |  x > 0      |     --      |   < 2.0e-4
+             | Si          |  x > 0      |     --      |   < 2.0e-4
+             |             |             |             |
+Fresnel      | C           |  all of R   |     --      |   < 2.0e-3
+integrals    | S           |  all of R   |     --      |   < 2.0e-3
+             |             |             |             |
+general      | Beta        | (see Gamma) |     --      |   < 1.0e-9
+             | Gamma       |  x != 0,-1, |     --      |   < 1.0e-9
+             |             |  -2, ...    |             |
+             | sinc        |  all of R   |     --      |   exact
+             |             |             |             |
+orthogonal   | Legendre    |  all of R   | n = 0,1,... |   exact
+polynomials  | Chebyshev   |  all of R   | n = 0,1,... |   exact
+             | Laguerre    |  all of R   | n = 0,1,... |   exact
+             |             |             | alpha el. R |
+             | Hermite     |  all of R   | n = 0,1,... |   exact
+
+

Note: Some of the error bounds are estimated, as no +"formal" bounds were available with the implemented approximation +method, others hold for the auxiliary functions used for estimating +the primary functions.

+

The following well-known functions are currently missing from the package:

+
    +

  • Bessel functions of the second kind (Y_n, K_n)

    • +

  • Bessel functions of arbitrary order (and hence the Airy functions)

    • +

  • Chebyshev polynomials of the second kind (U_n)

    • +

  • The digamma function (psi)

    • +

  • The incomplete gamma and beta functions

    • +
+
+

PROCEDURES

+

The package defines the following public procedures:

+
+
::math::special::Beta x y
+

Compute the Beta function for arguments "x" and "y"

+
+
float x
+

First argument for the Beta function

+
float y
+

Second argument for the Beta function

+
+
::math::special::Gamma x
+

Compute the Gamma function for argument "x"

+
+
float x
+

Argument for the Gamma function

+
+
::math::special::erf x
+

Compute the error function for argument "x"

+
+
float x
+

Argument for the error function

+
+
::math::special::erfc x
+

Compute the complementary error function for argument "x"

+
+
float x
+

Argument for the complementary error function

+
+
::math::special::invnorm p
+

Compute the inverse of the normal distribution function for argument "p"

+
+
float p
+

Argument for the inverse normal distribution function +(p must be greater than 0 and lower than 1)

+
+
::math::special::J0 x
+

Compute the zeroth-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::J1 x
+

Compute the first-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::Jn n x
+

Compute the nth-order Bessel function of the first kind for the +argument "x"

+
+
integer n
+

Order of the Bessel function

+
float x
+

Argument for the Bessel function

+
+
::math::special::J1/2 x
+

Compute the half-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::J-1/2 x
+

Compute the minus-half-order Bessel function of the first kind for the +argument "x"

+
+
float x
+

Argument for the Bessel function

+
+
::math::special::I_n x
+

Compute the modified Bessel function of the first kind of order n for +the argument "x"

+
+
int x
+

Positive integer order of the function

+
float x
+

Argument for the function

+
+
::math::special::cn u k
+

Compute the elliptic function cn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::dn u k
+

Compute the elliptic function dn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::sn u k
+

Compute the elliptic function sn for the argument "u" and +parameter "k".

+
+
float u
+

Argument for the function

+
float k
+

Parameter

+
+
::math::special::elliptic_K k
+

Compute the complete elliptic integral of the first kind +for the argument "k"

+
+
float k
+

Argument for the function

+
+
::math::special::elliptic_E k
+

Compute the complete elliptic integral of the second kind +for the argument "k"

+
+
float k
+

Argument for the function

+
+
::math::special::exponential_Ei x
+

Compute the exponential integral of the second kind +for the argument "x"

+
+
float x
+

Argument for the function (x != 0)

+
+
::math::special::exponential_En n x
+

Compute the exponential integral of the first kind +for the argument "x" and order n

+
+
int n
+

Order of the integral (n >= 0)

+
float x
+

Argument for the function (x >= 0)

+
+
::math::special::exponential_li x
+

Compute the logarithmic integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Ci x
+

Compute the cosine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Si x
+

Compute the sine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Chi x
+

Compute the hyperbolic cosine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::exponential_Shi x
+

Compute the hyperbolic sine integral for the argument "x"

+
+
float x
+

Argument for the function (x > 0)

+
+
::math::special::fresnel_C x
+

Compute the Fresnel cosine integral for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::fresnel_S x
+

Compute the Fresnel sine integral for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::sinc x
+

Compute the sinc function for real argument x

+
+
float x
+

Argument for the function

+
+
::math::special::legendre n
+

Return the Legendre polynomial of degree n +(see THE ORTHOGONAL POLYNOMIALS)

+
+
int n
+

Degree of the polynomial

+
+
::math::special::chebyshev n
+

Return the Chebyshev polynomial of degree n (of the first kind)

+
+
int n
+

Degree of the polynomial

+
+
::math::special::laguerre alpha n
+

Return the Laguerre polynomial of degree n with parameter alpha

+
+
float alpha
+

Parameter of the Laguerre polynomial

+
int n
+

Degree of the polynomial

+
+
::math::special::hermite n
+

Return the Hermite polynomial of degree n

+
+
int n
+

Degree of the polynomial

+
+
+
+

THE ORTHOGONAL POLYNOMIALS

+

For dealing with the classical families of orthogonal polynomials, the +package relies on the math::polynomials package. To evaluate the +polynomial at some coordinate, use the evalPolyn command:

+
+   set leg2 [::math::special::legendre 2]
+   puts "Value at x=$x: [::math::polynomials::evalPolyn $leg2 $x]"
+
+

The return value from the legendre and other commands is actually +the definition of the corresponding polynomial as used in that package.

+
+

REMARKS ON THE IMPLEMENTATION

+

It should be noted, that the actual implementation of J0 and J1 depends +on straightforward Gaussian quadrature formulas. The (absolute) accuracy +of the results is of the order 1.0e-4 or better. The main reason to +implement them like that was that it was fast to do (the formulas are +simple) and the computations are fast too.

+

The implementation of J1/2 does not suffer from this: this function can +be expressed exactly in terms of elementary functions.

+

The functions J0 and J1 are the ones you will encounter most frequently +in practice.

+

The computation of I_n is based on Miller's algorithm for computing the +minimal function from recurrence relations.

+

The computation of the Gamma and Beta functions relies on the +combinatorics package, whereas that of the error functions relies on the +statistics package.

+

The computation of the complete elliptic integrals uses the AGM +algorithm.

+

Much information about these functions can be found in:

+

Abramowitz and Stegun: Handbook of Mathematical Functions +(Dover, ISBN 486-61272-4)

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: special of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/math/statistics.html Index: embedded/www/tcllib/files/modules/math/statistics.html ================================================================== --- embedded/www/tcllib/files/modules/math/statistics.html +++ embedded/www/tcllib/files/modules/math/statistics.html @@ -0,0 +1,1592 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::statistics(n) 1 tcllib "Tcl Math Library"

+

Name

+

math::statistics - Basic statistical functions and procedures

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require math::statistics 1
    • +
+ +
+
+

Description

+

The math::statistics package contains functions and procedures for +basic statistical data analysis, such as:

+
    +

  • Descriptive statistical parameters (mean, minimum, maximum, standard +deviation)

    • +

  • Estimates of the distribution in the form of histograms and quantiles

    • +

  • Basic testing of hypotheses

    • +

  • Probability and cumulative density functions

    • +
+

It is meant to help in developing data analysis applications or doing +ad hoc data analysis, it is not in itself a full application, nor is it +intended to rival with full (non-)commercial statistical packages.

+

The purpose of this document is to describe the implemented procedures +and provide some examples of their usage. As there is ample literature +on the algorithms involved, we refer to relevant text books for more +explanations. +The package contains a fairly large number of public procedures. They +can be distinguished in three sets: general procedures, procedures +that deal with specific statistical distributions, list procedures to +select or transform data and simple plotting procedures (these require +Tk). +Note: The data that need to be analyzed are always contained in a +simple list. Missing values are represented as empty list elements. +Note: With version 1.0.1 a mistake in the procs pdf-lognormal, +cdf-lognormal and random-lognormal has been corrected. In +previous versions the argument for the standard deviation was actually +used as if it was the variance.

+
+

GENERAL PROCEDURES

+

The general statistical procedures are:

+
+
::math::statistics::mean data
+

Determine the mean value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::min data
+

Determine the minimum value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::max data
+

Determine the maximum value of the given list of data.

+
+
list data
+

- List of data

+
+
::math::statistics::number data
+

Determine the number of non-missing data in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::stdev data
+

Determine the sample standard deviation of the data in the +given list

+
+
list data
+

- List of data

+
+
::math::statistics::var data
+

Determine the sample variance of the data in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::pstdev data
+

Determine the population standard deviation of the data +in the given list

+
+
list data
+

- List of data

+
+
::math::statistics::pvar data
+

Determine the population variance of the data in the +given list

+
+
list data
+

- List of data

+
+
::math::statistics::median data
+

Determine the median of the data in the given list +(Note that this requires sorting the data, which may be a +costly operation)

+
+
list data
+

- List of data

+
+
::math::statistics::basic-stats data
+

Determine a list of all the descriptive parameters: mean, minimum, +maximum, number of data, sample standard deviation, sample variance, +population standard deviation and population variance.

+

(This routine is called whenever either or all of the basic statistical +parameters are required. Hence all calculations are done and the +relevant values are returned.)

+
+
list data
+

- List of data

+
+
::math::statistics::histogram limits values ?weights?
+

Determine histogram information for the given list of data. Returns a +list consisting of the number of values that fall into each interval. +(The first interval consists of all values lower than the first limit, +the last interval consists of all values greater than the last limit. +There is one more interval than there are limits.)

+

Optionally, you can use weights to influence the histogram.

+
+
list limits
+

- List of upper limits (in ascending order) for the +intervals of the histogram.

+
list values
+

- List of data

+
list weights
+

- List of weights, one weight per value

+
+
::math::statistics::histogram-alt limits values ?weights?
+

Alternative implementation of the histogram procedure: the open end of the intervals +is at the lower bound instead of the upper bound.

+
+
list limits
+

- List of upper limits (in ascending order) for the +intervals of the histogram.

+
list values
+

- List of data

+
list weights
+

- List of weights, one weight per value

+
+
::math::statistics::corr data1 data2
+

Determine the correlation coefficient between two sets of data.

+
+
list data1
+

- First list of data

+
list data2
+

- Second list of data

+
+
::math::statistics::interval-mean-stdev data confidence
+

Return the interval containing the mean value and one +containing the standard deviation with a certain +level of confidence (assuming a normal distribution)

+
+
list data
+

- List of raw data values (small sample)

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance)

+
+
::math::statistics::t-test-mean data est_mean est_stdev alpha
+

Test whether the mean value of a sample is in accordance with the +estimated normal distribution with a certain probability. +Returns 1 if the test succeeds or 0 if the mean is unlikely to fit +the given distribution.

+
+
list data
+

- List of raw data values (small sample)

+
float est_mean
+

- Estimated mean of the distribution

+
float est_stdev
+

- Estimated stdev of the distribution

+
float alpha
+

- Probability level (0.95 or 0.99 for instance)

+
+
::math::statistics::test-normal data significance
+

Test whether the given data follow a normal distribution +with a certain level of significance. +Returns 1 if the data are normally distributed within the level of +significance, returns 0 if not. The underlying test is the Lilliefors +test. Smaller values of the significance mean a stricter testing.

+
+
list data
+

- List of raw data values

+
float significance
+

- Significance level (one of 0.01, 0.05, 0.10, 0.15 or 0.20). For compatibility +reasons the values "1-significance", 0.80, 0.85, 0.90, 0.95 or 0.99 are also accepted.

+
+

Compatibility issue: the original implementation and documentation used the term "confidence" and used a value +1-significance (see ticket 2812473fff). This has been corrected as of version 0.9.3.

+
::math::statistics::lillieforsFit data
+

Returns the goodness of fit to a normal distribution according to +Lilliefors. The higher the number, the more likely the data are indeed +normally distributed. The test requires at least five data +points.

+
+
list data
+

- List of raw data values

+
+
::math::statistics::test-Duckworth list1 list2 significance
+

Determine if two data sets have the same median according to the Tukey-Duckworth test. +The procedure returns 0 if the medians are unequal, 1 if they are equal, -1 if the test can not +be conducted (the smallest value must be in a different set than the greatest value). +# +# Arguments: +# list1 Values in the first data set +# list2 Values in the second data set +# significance Significance level (either 0.05, 0.01 or 0.001) +# +# Returns: +Test whether the given data follow a normal distribution +with a certain level of significance. +Returns 1 if the data are normally distributed within the level of +significance, returns 0 if not. The underlying test is the Lilliefors +test. Smaller values of the significance mean a stricter testing.

+
+
list list1
+

- First list of data

+
list list2
+

- Second list of data

+
float significance
+

- Significance level (either 0.05, 0.01 or 0.001)

+
+
::math::statistics::test-anova-F alpha args
+

Determine if two or more groups with normally distributed data have the same variances. +The procedure returns 0 if the variances are likely unequal, 1 if they are. This is +a one-way ANOVA test. The groups may also be stored in a nested list:

+
+    test-anova-F 0.05 $A $B $C
+    #
+    # Or equivalently:
+    #
+    test-anova-F 0.05 [list $A $B $C]
+
+
+
float alpha
+

- Significance level

+
list args
+

- Two or more groups of data to be checked

+
+
::math::statistics::quantiles data confidence
+

Return the quantiles for a given set of data

+
+
list data
+

- List of raw data values

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance) or a list of confidence levels.

+
+
::math::statistics::quantiles limits counts confidence
+

Return the quantiles based on histogram information (alternative to the +call with two arguments)

+
+
list limits
+

- List of upper limits from histogram

+
list counts
+

- List of counts for for each interval in histogram

+
float confidence
+

- Confidence level (0.95 or 0.99 for instance) or a list of confidence levels.

+
+
::math::statistics::autocorr data
+

Return the autocorrelation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data)

+

The correlation is determined in such a way that the first value is +always 1 and all others are equal to or smaller than 1. The number of +values involved will diminish as the "time" (the index in the list of +returned values) increases

+
+
list data
+

- Raw data for which the autocorrelation must be determined

+
+
::math::statistics::crosscorr data1 data2
+

Return the cross-correlation function as a list of values (assuming +equidistance between samples, about 1/2 of the number of raw data)

+

The correlation is determined in such a way that the values can never +exceed 1 in magnitude. The number of values involved will diminish +as the "time" (the index in the list of returned values) increases.

+
+
list data1
+

- First list of data

+
list data2
+

- Second list of data

+
+
::math::statistics::mean-histogram-limits mean stdev number
+

Determine reasonable limits based on mean and standard deviation +for a histogram +Convenience function - the result is suitable for the histogram function.

+
+
float mean
+

- Mean of the data

+
float stdev
+

- Standard deviation

+
int number
+

- Number of limits to generate (defaults to 8)

+
+
::math::statistics::minmax-histogram-limits min max number
+

Determine reasonable limits based on a minimum and maximum for a histogram

+

Convenience function - the result is suitable for the histogram function.

+
+
float min
+

- Expected minimum

+
float max
+

- Expected maximum

+
int number
+

- Number of limits to generate (defaults to 8)

+
+
::math::statistics::linear-model xdata ydata intercept
+

Determine the coefficients for a linear regression between +two series of data (the model: Y = A + B*X). Returns a list of +parameters describing the fit

+
+
list xdata
+

- List of independent data

+
list ydata
+

- List of dependent data to be fitted

+
boolean intercept
+

- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0)

+

The result consists of the following list:

+
    +

  • (Estimate of) Intercept A

    • +

  • (Estimate of) Slope B

    • +

  • Standard deviation of Y relative to fit

    • +

  • Correlation coefficient R2

    • +

  • Number of degrees of freedom df

    • +

  • Standard error of the intercept A

    • +

  • Significance level of A

    • +

  • Standard error of the slope B

    • +

  • Significance level of B

    • +
+
+
::math::statistics::linear-residuals xdata ydata intercept
+

Determine the difference between actual data and predicted from +the linear model.

+

Returns a list of the differences between the actual data and the +predicted values.

+
+
list xdata
+

- List of independent data

+
list ydata
+

- List of dependent data to be fitted

+
boolean intercept
+

- (Optional) compute the intercept (1, default) or fit +to a line through the origin (0)

+
+
::math::statistics::test-2x2 n11 n21 n12 n22
+

Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter).

+

Returns the "chi-square" value, which can be used to the determine the +significance.

+
+
int n11
+

- Number of outcomes with the first value from the first sample.

+
int n21
+

- Number of outcomes with the first value from the second sample.

+
int n12
+

- Number of outcomes with the second value from the first sample.

+
int n22
+

- Number of outcomes with the second value from the second sample.

+
+
::math::statistics::print-2x2 n11 n21 n12 n22
+

Determine if two set of samples, each from a binomial distribution, +differ significantly or not (implying a different parameter).

+

Returns a short report, useful in an interactive session.

+
+
int n11
+

- Number of outcomes with the first value from the first sample.

+
int n21
+

- Number of outcomes with the first value from the second sample.

+
int n12
+

- Number of outcomes with the second value from the first sample.

+
int n22
+

- Number of outcomes with the second value from the second sample.

+
+
::math::statistics::control-xbar data ?nsamples?
+

Determine the control limits for an xbar chart. The number of data +in each subsample defaults to 4. At least 20 subsamples are required.

+

Returns the mean, the lower limit, the upper limit and the number of +data per subsample.

+
+
list data
+

- List of observed data

+
int nsamples
+

- Number of data per subsample

+
+
::math::statistics::control-Rchart data ?nsamples?
+

Determine the control limits for an R chart. The number of data +in each subsample (nsamples) defaults to 4. At least 20 subsamples are required.

+

Returns the mean range, the lower limit, the upper limit and the number +of data per subsample.

+
+
list data
+

- List of observed data

+
int nsamples
+

- Number of data per subsample

+
+
::math::statistics::test-xbar control data
+

Determine if the data exceed the control limits for the xbar chart.

+

Returns a list of subsamples (their indices) that indeed violate the +limits.

+
+
list control
+

- Control limits as returned by the "control-xbar" procedure

+
list data
+

- List of observed data

+
+
::math::statistics::test-Rchart control data
+

Determine if the data exceed the control limits for the R chart.

+

Returns a list of subsamples (their indices) that indeed violate the +limits.

+
+
list control
+

- Control limits as returned by the "control-Rchart" procedure

+
list data
+

- List of observed data

+
+
::math::statistics::test-Kruskal-Wallis confidence args
+

Check if the population medians of two or more groups are equal with a +given confidence level, using the Kruskal-Wallis test.

+
+
float confidence
+

- Confidence level to be used (0-1)

+
list args
+

- Two or more lists of data

+
+
::math::statistics::analyse-Kruskal-Wallis args
+

Compute the statistical parameters for the Kruskal-Wallis test. +Returns the Kruskal-Wallis statistic and the probability that that +value would occur assuming the medians of the populations are +equal.

+
+
list args
+

- Two or more lists of data

+
+
::math::statistics::group-rank args
+

Rank the groups of data with respect to the complete set. +Returns a list consisting of the group ID, the value and the rank +(possibly a rational number, in case of ties) for each data item.

+
+
list args
+

- Two or more lists of data

+
+
::math::statistics::test-Wilcoxon sample_a sample_b
+

Compute the Wilcoxon test statistic to determine if two samples have the +same median or not. (The statistic can be regarded as standard normal, if the +sample sizes are both larger than 10. Returns the value of this statistic.

+
+
list sample_a
+

- List of data comprising the first sample

+
list sample_b
+

- List of data comprising the second sample

+
+
::math::statistics::spearman-rank sample_a sample_b
+

Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient. The two samples should have the same number of data.

+
+
list sample_a
+

- First list of data

+
list sample_b
+

- Second list of data

+
+
::math::statistics::spearman-rank-extended sample_a sample_b
+

Return the Spearman rank correlation as an alternative to the ordinary (Pearson's) correlation +coefficient as well as additional data. The two samples should have the same number of data. +The procedure returns the correlation coefficient, the number of data pairs used and the +z-score, an approximately standard normal statistic, indicating the significance of the correlation.

+
+
list sample_a
+

- First list of data

+
list sample_b
+

- Second list of data

+
+
::math::statistics::kernel-density data opt -option value ...
+

] +Return the density function based on kernel density estimation. The procedure is controlled by +a small set of options, each of which is given a reasonable default.

+

The return value consists of three lists: the centres of the bins, the associated probability +density and a list of computational parameters (begin and end of the interval, mean and standard +deviation and the used bandwidth). The computational parameters can be used for further analysis.

+
+
list data
+

- The data to be examined

+
list args
+

- Option-value pairs:

+
+
-weights weights
+

Per data point the weight (default: 1 for all data)

+
-bandwidth value
+

Bandwidth to be used for the estimation (default: determined from standard deviation)

+
-number value
+

Number of bins to be returned (default: 100)

+
-interval {begin end}
+

Begin and end of the interval for +which the density is returned (default: mean +/- 3*standard deviation)

+
-kernel function
+

Kernel to be used (One of: gaussian, cosine, +epanechnikov, uniform, triangular, biweight, logistic; default: gaussian)

+
+
+
+
+

MULTIVARIATE LINEAR REGRESSION

+

Besides the linear regression with a single independent variable, the +statistics package provides two procedures for doing ordinary +least squares (OLS) and weighted least squares (WLS) linear regression +with several variables. They were written by Eric Kemp-Benedict.

+

In addition to these two, it provides a procedure (tstat) +for calculating the value of the t-statistic for the specified number of +degrees of freedom that is required to demonstrate a given level of +significance.

+

Note: These procedures depend on the math::linearalgebra package.

+

Description of the procedures

+
+
::math::statistics::tstat dof ?alpha?
+

Returns the value of the t-distribution t* satisfying

+
+    P(t*)  =  1 - alpha/2
+    P(-t*) =  alpha/2
+
+

for the number of degrees of freedom dof.

+

Given a sample of normally-distributed data x, with an +estimate xbar for the mean and sbar for the standard deviation, +the alpha confidence interval for the estimate of the mean can +be calculated as

+
+      ( xbar - t* sbar , xbar + t* sbar)
+
+

The return values from this procedure can be compared to +an estimated t-statistic to determine whether the estimated +value of a parameter is significantly different from zero at +the given confidence level.

+
+
int dof
+

Number of degrees of freedom

+
float alpha
+

Confidence level of the t-distribution. Defaults to 0.05.

+
+
::math::statistics::mv-wls wt1 weights_and_values
+

Carries out a weighted least squares linear regression for +the data points provided, with weights assigned to each point.

+

The linear model is of the form

+
+    y = b0 + b1 * x1 + b2 * x2 ... + bN * xN + error
+
+

and each point satisfies

+
+    yi = b0 + b1 * xi1 + b2 * xi2 + ... + bN * xiN + Residual_i
+
+

The procedure returns a list with the following elements:

+
    +

  • The r-squared statistic

    • +

  • The adjusted r-squared statistic

    • +

  • A list containing the estimated coefficients b1, ... bN, b0 +(The constant b0 comes last in the list.)

    • +

  • A list containing the standard errors of the coefficients

    • +

  • A list containing the 95% confidence bounds of the coefficients, +with each set of bounds returned as a list with two values

    • +
+

Arguments:

+
+
list weights_and_values
+

A list consisting of: the weight for the first observation, the data +for the first observation (as a sublist), the weight for the second +observation (as a sublist) and so on. The sublists of data are organised +as lists of the value of the dependent variable y and the independent +variables x1, x2 to xN.

+
+
::math::statistics::mv-ols values
+

Carries out an ordinary least squares linear regression for +the data points provided.

+

This procedure simply calls ::mvlinreg::wls with the weights +set to 1.0, and returns the same information.

+
+

Example of the use:

+
+# Store the value of the unicode value for the "+/-" character
+set pm "\u00B1"
+# Provide some data
+set data {{  -.67  14.18  60.03 -7.5  }
+          { 36.97  15.52  34.24 14.61 }
+          {-29.57  21.85  83.36 -7.   }
+          {-16.9   11.79  51.67 -6.56 }
+          { 14.09  16.24  36.97 -12.84}
+          { 31.52  20.93  45.99 -25.4 }
+          { 24.05  20.69  50.27  17.27}
+          { 22.23  16.91  45.07  -4.3 }
+          { 40.79  20.49  38.92  -.73 }
+          {-10.35  17.24  58.77  18.78}}
+# Call the ols routine
+set results [::math::statistics::mv-ols $data]
+# Pretty-print the results
+puts "R-squared: [lindex $results 0]"
+puts "Adj R-squared: [lindex $results 1]"
+puts "Coefficients $pm s.e. -- \[95% confidence interval\]:"
+foreach val [lindex $results 2] se [lindex $results 3] bounds [lindex $results 4] {
+    set lb [lindex $bounds 0]
+    set ub [lindex $bounds 1]
+    puts "   $val $pm $se -- \[$lb to $ub\]"
+}
+
+
+

STATISTICAL DISTRIBUTIONS

+

In the literature a large number of probability distributions can be +found. The statistics package supports:

+
    +

  • The normal or Gaussian distribution as well as the log-normal distribution

    • +

  • The uniform distribution - equal probability for all data within a given +interval

    • +

  • The exponential distribution - useful as a model for certain +extreme-value distributions.

    • +

  • The gamma distribution - based on the incomplete Gamma integral

    • +

  • The beta distribution

    • +

  • The chi-square distribution

    • +

  • The student's T distribution

    • +

  • The Poisson distribution

    • +

  • The Pareto distribution

    • +

  • The Gumbel distribution

    • +

  • The Weibull distribution

    • +

  • The Cauchy distribution

    • +

  • The F distribution (only the cumulative density function)

    • +

  • PM - binomial.

    • +
+

In principle for each distribution one has procedures for:

+
    +

  • The probability density (pdf-*)

    • +

  • The cumulative density (cdf-*)

    • +

  • Quantiles for the given distribution (quantiles-*)

    • +

  • Histograms for the given distribution (histogram-*)

    • +

  • List of random values with the given distribution (random-*)

    • +
+

The following procedures have been implemented:

+
+
::math::statistics::pdf-normal mean stdev value
+

Return the probability of a given value for a normal distribution with +given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-lognormal mean stdev value
+

Return the probability of a given value for a log-normal distribution with +given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-exponential mean value
+

Return the probability of a given value for an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-uniform xmin xmax value
+

Return the probability of a given value for a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmin
+

- Maximum value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-gamma alpha beta value
+

Return the probability of a given value for a Gamma +distribution with given shape and rate parameters

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-poisson mu k
+

Return the probability of a given number of occurrences in the same +interval (k) for a Poisson distribution with given mean (mu)

+
+
float mu
+

- Mean number of occurrences

+
int k
+

- Number of occurences

+
+
::math::statistics::pdf-chisquare df value
+

Return the probability of a given value for a chi square +distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-student-t df value
+

Return the probability of a given value for a Student's t +distribution with given degrees of freedom

+
+
float df
+

- Degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-gamma a b value
+

Return the probability of a given value for a Gamma +distribution with given shape and rate parameters

+
+
float a
+

- Shape parameter

+
float b
+

- Rate parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-beta a b value
+

Return the probability of a given value for a Beta +distribution with given shape parameters

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-weibull scale shape value
+

Return the probability of a given value for a Weibull +distribution with given scale and shape parameters

+
+
float location
+

- Scale parameter

+
float scale
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-gumbel location scale value
+

Return the probability of a given value for a Gumbel +distribution with given location and shape parameters

+
+
float location
+

- Location parameter

+
float scale
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-pareto scale shape value
+

Return the probability of a given value for a Pareto +distribution with given scale and shape parameters

+
+
float scale
+

- Scale parameter

+
float shape
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::pdf-cauchy location scale value
+

Return the probability of a given value for a Cauchy +distribution with given location and shape parameters. Note that the Cauchy distribution +has no finite higher-order moments.

+
+
float location
+

- Location parameter

+
float scale
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-normal mean stdev value
+

Return the cumulative probability of a given value for a normal +distribution with given mean and standard deviation, that is the +probability for values up to the given one.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-lognormal mean stdev value
+

Return the cumulative probability of a given value for a log-normal +distribution with given mean and standard deviation, that is the +probability for values up to the given one.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-exponential mean value
+

Return the cumulative probability of a given value for an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-uniform xmin xmax value
+

Return the cumulative probability of a given value for a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmin
+

- Maximum value of the distribution

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-students-t degrees value
+

Return the cumulative probability of a given value for a Student's t +distribution with given number of degrees.

+
+
int degrees
+

- Number of degrees of freedom

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-gamma alpha beta value
+

Return the cumulative probability of a given value for a Gamma +distribution with given shape and rate parameters.

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
float value
+

- Value for which the cumulative probability is required

+
+
::math::statistics::cdf-poisson mu k
+

Return the cumulative probability of a given number of occurrences in +the same interval (k) for a Poisson distribution with given mean (mu).

+
+
float mu
+

- Mean number of occurrences

+
int k
+

- Number of occurences

+
+
::math::statistics::cdf-beta a b value
+

Return the cumulative probability of a given value for a Beta +distribution with given shape parameters

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-weibull scale shape value
+

Return the cumulative probability of a given value for a Weibull +distribution with given scale and shape parameters.

+
+
float scale
+

- Scale parameter

+
float shape
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-gumbel location scale value
+

Return the cumulative probability of a given value for a Gumbel +distribution with given location and scale parameters.

+
+
float location
+

- Location parameter

+
float scale
+

- Scale parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-pareto scale shape value
+

Return the cumulative probability of a given value for a Pareto +distribution with given scale and shape parameters

+
+
float scale
+

- Scale parameter

+
float shape
+

- Shape parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-cauchy location scale value
+

Return the cumulative probability of a given value for a Cauchy +distribution with given location and scale parameters.

+
+
float location
+

- Location parameter

+
float scale
+

- Scale parameter

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::cdf-F nf1 nf2 value
+

Return the cumulative probability of a given value for an F +distribution with nf1 and nf2 degrees of freedom.

+
+
float nf1
+

- Degrees of freedom for the numerator

+
float nf2
+

- Degrees of freedom for the denominator

+
float value
+

- Value for which the probability is required

+
+
::math::statistics::empirical-distribution values
+

Return a list of values and their empirical probability. The values are sorted in increasing order. +(The implementation follows the description at the corresponding Wikipedia page)

+
+
list values
+

- List of data to be examined

+
+
::math::statistics::random-normal mean stdev number
+

Return a list of "number" random values satisfying a normal +distribution with given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-lognormal mean stdev number
+

Return a list of "number" random values satisfying a log-normal +distribution with given mean and standard deviation.

+
+
float mean
+

- Mean value of the distribution

+
float stdev
+

- Standard deviation of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-exponential mean number
+

Return a list of "number" random values satisfying an exponential +distribution with given mean.

+
+
float mean
+

- Mean value of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-uniform xmin xmax number
+

Return a list of "number" random values satisfying a uniform +distribution with given extremes.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmax
+

- Maximum value of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-gamma alpha beta number
+

Return a list of "number" random values satisfying +a Gamma distribution with given shape and rate parameters.

+
+
float alpha
+

- Shape parameter

+
float beta
+

- Rate parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-poisson mu number
+

Return a list of "number" random values satisfying +a Poisson distribution with given mean.

+
+
float mu
+

- Mean of the distribution

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-chisquare df number
+

Return a list of "number" random values satisfying +a chi square distribution with given degrees of freedom.

+
+
float df
+

- Degrees of freedom

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-student-t df number
+

Return a list of "number" random values satisfying +a Student's t distribution with given degrees of freedom.

+
+
float df
+

- Degrees of freedom

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-beta a b number
+

Return a list of "number" random values satisfying +a Beta distribution with given shape parameters.

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-weibull scale shape number
+

Return a list of "number" random values satisfying +a Weibull distribution with given scale and shape parameters.

+
+
float scale
+

- Scale parameter

+
float shape
+

- Shape parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-gumbel location scale number
+

Return a list of "number" random values satisfying +a Gumbel distribution with given location and scale parameters.

+
+
float location
+

- Location parameter

+
float scale
+

- Scale parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-pareto scale shape number
+

Return a list of "number" random values satisfying +a Pareto distribution with given scale and shape parameters.

+
+
float scale
+

- Scale parameter

+
float shape
+

- Shape parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::random-cauchy location scale number
+

Return a list of "number" random values satisfying +a Cauchy distribution with given location and scale parameters.

+
+
float location
+

- Location parameter

+
float scale
+

- Scale parameter

+
int number
+

- Number of values to be returned

+
+
::math::statistics::histogram-uniform xmin xmax limits number
+

Return the expected histogram for a uniform distribution.

+
+
float xmin
+

- Minimum value of the distribution

+
float xmax
+

- Maximum value of the distribution

+
list limits
+

- Upper limits for the buckets in the histogram

+
int number
+

- Total number of "observations" in the histogram

+
+
::math::statistics::incompleteGamma x p ?tol?
+

Evaluate the incomplete Gamma integral

+
+                    1       / x               p-1
+      P(p,x) =  --------   |   dt exp(-t) * t
+                Gamma(p)  / 0
+
+
+
float x
+

- Value of x (limit of the integral)

+
float p
+

- Value of p in the integrand

+
float tol
+

- Required tolerance (default: 1.0e-9)

+
+
::math::statistics::incompleteBeta a b x ?tol?
+

Evaluate the incomplete Beta integral

+
+
float a
+

- First shape parameter

+
float b
+

- Second shape parameter

+
float x
+

- Value of x (limit of the integral)

+
float tol
+

- Required tolerance (default: 1.0e-9)

+
+
::math::statistics::estimate-pareto values
+

Estimate the parameters for the Pareto distribution that comes closest to the given values. +Returns the estimated scale and shape parameters, as well as the standard error for the shape parameter.

+
+
list values
+

- List of values, assumed to be distributed according to a Pareto distribution

+
+
+

TO DO: more function descriptions to be added

+
+

DATA MANIPULATION

+

The data manipulation procedures act on lists or lists of lists:

+
+
::math::statistics::filter varname data expression
+

Return a list consisting of the data for which the logical +expression is true (this command works analogously to the command foreach).

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of data

+
string expression
+

- Logical expression using the variable name

+
+
::math::statistics::map varname data expression
+

Return a list consisting of the data that are transformed via the +expression.

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of data

+
string expression
+

- Expression to be used to transform (map) the data

+
+
::math::statistics::samplescount varname list expression
+

Return a list consisting of the counts of all data in the +sublists of the "list" argument for which the expression is true.

+
+
string varname
+

- Name of the variable used in the expression

+
list data
+

- List of sublists, each containing the data

+
string expression
+

- Logical expression to test the data (defaults to +"true").

+
+
::math::statistics::subdivide
+

Routine PM - not implemented yet

+
+
+

PLOT PROCEDURES

+

The following simple plotting procedures are available:

+
+
::math::statistics::plot-scale canvas xmin xmax ymin ymax
+

Set the scale for a plot in the given canvas. All plot routines expect +this function to be called first. There is no automatic scaling +provided.

+
+
widget canvas
+

- Canvas widget to use

+
float xmin
+

- Minimum x value

+
float xmax
+

- Maximum x value

+
float ymin
+

- Minimum y value

+
float ymax
+

- Maximum y value

+
+
::math::statistics::plot-xydata canvas xdata ydata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The tag can be used to manipulate the +appearance.

+
+
widget canvas
+

- Canvas widget to use

+
float xdata
+

- Series of independent data

+
float ydata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-xyline canvas xdata ydata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a line through the data points. The tag can be used to +manipulate the appearance.

+
+
widget canvas
+

- Canvas widget to use

+
list xdata
+

- Series of independent data

+
list ydata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-tdata canvas tdata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a collection of dots. The horizontal coordinate is equal to the +index. The tag can be used to manipulate the appearance. +This type of presentation is suitable for autocorrelation functions for +instance or for inspecting the time-dependent behaviour.

+
+
widget canvas
+

- Canvas widget to use

+
list tdata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-tline canvas tdata tag
+

Create a simple XY plot in the given canvas - the data are +shown as a line. See plot-tdata for an explanation.

+
+
widget canvas
+

- Canvas widget to use

+
list tdata
+

- Series of dependent data

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
::math::statistics::plot-histogram canvas counts limits tag
+

Create a simple histogram in the given canvas

+
+
widget canvas
+

- Canvas widget to use

+
list counts
+

- Series of bucket counts

+
list limits
+

- Series of upper limits for the buckets

+
string tag
+

- Tag to give to the plotted data (defaults to xyplot)

+
+
+
+

THINGS TO DO

+

The following procedures are yet to be implemented:

+
    +

  • F-test-stdev

    • +

  • interval-mean-stdev

    • +

  • histogram-normal

    • +

  • histogram-exponential

    • +

  • test-histogram

    • +

  • test-corr

    • +

  • quantiles-*

    • +

  • fourier-coeffs

    • +

  • fourier-residuals

    • +

  • onepar-function-fit

    • +

  • onepar-function-residuals

    • +

  • plot-linear-model

    • +

  • subdivide

    • +
+
+

EXAMPLES

+

The code below is a small example of how you can examine a set of +data:

+
+# Simple example:
+# - Generate data (as a cheap way of getting some)
+# - Perform statistical analysis to describe the data
+#
+package require math::statistics
+#
+# Two auxiliary procs
+#
+proc pause {time} {
+   set wait 0
+   after [expr {$time*1000}] {set ::wait 1}
+   vwait wait
+}
+proc print-histogram {counts limits} {
+   foreach count $counts limit $limits {
+      if { $limit != {} } {
+         puts [format "<%12.4g\t%d" $limit $count]
+         set prev_limit $limit
+      } else {
+         puts [format ">%12.4g\t%d" $prev_limit $count]
+      }
+   }
+}
+#
+# Our source of arbitrary data
+#
+proc generateData { data1 data2 } {
+   upvar 1 $data1 _data1
+   upvar 1 $data2 _data2
+   set d1 0.0
+   set d2 0.0
+   for { set i 0 } { $i < 100 } { incr i } {
+      set d1 [expr {10.0-2.0*cos(2.0*3.1415926*$i/24.0)+3.5*rand()}]
+      set d2 [expr {0.7*$d2+0.3*$d1+0.7*rand()}]
+      lappend _data1 $d1
+      lappend _data2 $d2
+   }
+   return {}
+}
+#
+# The analysis session
+#
+package require Tk
+console show
+canvas .plot1
+canvas .plot2
+pack   .plot1 .plot2 -fill both -side top
+generateData data1 data2
+puts "Basic statistics:"
+set b1 [::math::statistics::basic-stats $data1]
+set b2 [::math::statistics::basic-stats $data2]
+foreach label {mean min max number stdev var} v1 $b1 v2 $b2 {
+   puts "$label\t$v1\t$v2"
+}
+puts "Plot the data as function of \"time\" and against each other"
+::math::statistics::plot-scale .plot1  0 100  0 20
+::math::statistics::plot-scale .plot2  0 20   0 20
+::math::statistics::plot-tline .plot1 $data1
+::math::statistics::plot-tline .plot1 $data2
+::math::statistics::plot-xydata .plot2 $data1 $data2
+puts "Correlation coefficient:"
+puts [::math::statistics::corr $data1 $data2]
+pause 2
+puts "Plot histograms"
+.plot2 delete all
+::math::statistics::plot-scale .plot2  0 20 0 100
+set limits         [::math::statistics::minmax-histogram-limits 7 16]
+set histogram_data [::math::statistics::histogram $limits $data1]
+::math::statistics::plot-histogram .plot2 $histogram_data $limits
+puts "First series:"
+print-histogram $histogram_data $limits
+pause 2
+set limits         [::math::statistics::minmax-histogram-limits 0 15 10]
+set histogram_data [::math::statistics::histogram $limits $data2]
+::math::statistics::plot-histogram .plot2 $histogram_data $limits d2
+.plot2 itemconfigure d2 -fill red
+puts "Second series:"
+print-histogram $histogram_data $limits
+puts "Autocorrelation function:"
+set  autoc [::math::statistics::autocorr $data1]
+puts [::math::statistics::map $autoc {[format "%.2f" $x]}]
+puts "Cross-correlation function:"
+set  crossc [::math::statistics::crosscorr $data1 $data2]
+puts [::math::statistics::map $crossc {[format "%.2f" $x]}]
+::math::statistics::plot-scale .plot1  0 100 -1  4
+::math::statistics::plot-tline .plot1  $autoc "autoc"
+::math::statistics::plot-tline .plot1  $crossc "crossc"
+.plot1 itemconfigure autoc  -fill green
+.plot1 itemconfigure crossc -fill yellow
+puts "Quantiles: 0.1, 0.2, 0.5, 0.8, 0.9"
+puts "First:  [::math::statistics::quantiles $data1 {0.1 0.2 0.5 0.8 0.9}]"
+puts "Second: [::math::statistics::quantiles $data2 {0.1 0.2 0.5 0.8 0.9}]"
+
+

If you run this example, then the following should be clear:

+
    +

  • There is a strong correlation between two time series, as displayed by +the raw data and especially by the correlation functions.

    • +

  • Both time series show a significant periodic component

    • +

  • The histograms are not very useful in identifying the nature of the time +series - they do not show the periodic nature.

    • +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: statistics of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Mathematics

+
+
ADDED embedded/www/tcllib/files/modules/math/symdiff.html Index: embedded/www/tcllib/files/modules/math/symdiff.html ================================================================== --- embedded/www/tcllib/files/modules/math/symdiff.html +++ embedded/www/tcllib/files/modules/math/symdiff.html @@ -0,0 +1,206 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

math::calculus::symdiff(n) 1.0.1 tcllib "Symbolic differentiation for Tcl"

+

Name

+

math::calculus::symdiff - Symbolic differentiation for Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require grammar::aycock 1.0
    • +
  • package require math::calculus::symdiff 1.0.1
    • +
+ +
+
+

Description

+

The math::calculus::symdiff package provides a symbolic differentiation +facility for Tcl math expressions. It is useful for providing derivatives +to packages that either require the Jacobian of a set of functions or else +are more efficient or stable when the Jacobian is provided.

+
+

Procedures

+

The math::calculus::symdiff package exports the two procedures:

+
+
math::calculus::symdiff::symdiff expression variable
+

Differentiates the given expression with respect to the specified +variable. (See Expressions below for a discussion of the +subset of Tcl math expressions that are acceptable to +math::calculus::symdiff.) +The result is a Tcl expression that evaluates the derivative. Returns an +error if expression is not a well-formed expression or is not +differentiable.

+
math::calculus::jacobian variableDict
+

Computes the Jacobian of a system of equations. +The system is given by the dictionary variableDict, whose keys +are the names of variables in the system, and whose values are Tcl expressions +giving the values of those variables. (See Expressions below +for a discussion of the subset of Tcl math expressions that are acceptable +to math::calculus::symdiff. The result is a list of lists: +the i'th element of the j'th sublist is the partial derivative of +the i'th variable with respect to the j'th variable. Returns an error if +any of the expressions cannot be differentiated, or if variableDict +is not a well-formed dictionary.

+
+
+

Expressions

+

The math::calculus::symdiff package accepts only a small subset of the expressions +that are acceptable to Tcl commands such as expr or if. +Specifically, the only constructs accepted are:

+
    +

  • Floating-point constants such as 5 or 3.14159e+00.

    • +

  • References to Tcl variable using $-substitution. The variable names +must consist of alphanumerics and underscores: the ${...} notation +is not accepted.

    • +

  • Parentheses.

    • +

  • The +, -, *, /. and ** +operators.

    • +

  • Calls to the functions acos, asin, atan, +atan2, cos, cosh, exp, hypot, log, +log10, pow, sin, sinh. sqrt, tan, +and tanh.

    • +
+

Command substitution, backslash substitution, and argument expansion are +not accepted.

+
+

Examples

+
+math::calculus::symdiff::symdiff {($a*$x+$b)*($c*$x+$d)} x
+==> (($c * (($a * $x) + $b)) + ($a * (($c * $x) + $d)))
+math::calculus::symdiff::jacobian {x {$a * $x + $b * $y}
+                         y {$c * $x + $d * $y}}
+==> {{$a} {$b}} {{$c} {$d}}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category math :: calculus of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/md4/md4.html Index: embedded/www/tcllib/files/modules/md4/md4.html ================================================================== --- embedded/www/tcllib/files/modules/md4/md4.html +++ embedded/www/tcllib/files/modules/md4/md4.html @@ -0,0 +1,259 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

md4(n) 1.0.6 tcllib "MD4 Message-Digest Algorithm"

+

Name

+

md4 - MD4 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the MD4 message-digest +algorithm as described in RFC 1320 (1) and (2). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD4 algorithm is faster but potentially weaker than +the related MD5 algorithm (3).

+

If you have critcl and have built the tcllibc package +then the implementation of the hashing function will be performed by compiled +code. Alternatively if cryptkit is available this will be +used. If no accelerator package can be found then the pure-tcl +implementation is used. The programming interface remains the same in +all cases.

+
+

COMMANDS

+
+
::md4::md4 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the MD4 digest of the data given in string. This is returned +as a binary string by default. Giving the -hex option will +return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the md4 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::md4::hmac ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the MD4 +digest algorithm. HMACs are described in RFC 2104 (4) and provide an MD4 +digest that includes a key. All options other than -key are as +for the ::md4::md4 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the MD4 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD4 hash operates on a token (equivalent to the +bucket). You call MD4Init to obtain a token and then call +MD4Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +MD4Final. An equivalent set of functions gives you a keyed digest (HMAC).

+
+
::md4::MD4Init
+

Begins a new MD4 hash. Returns a token ID that must be used for the +remaining functions.

+
::md4::MD4Update token data
+

Add data to the hash identified by token. Calling +MD4Update $token "abcd" is equivalent to calling +MD4Update $token "ab" followed by +MD4Update $token "cb". See EXAMPLES.

+
::md4::MD4Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD4 +digest value.

+
::md4::HMACInit key
+

This is equivalent to the ::md4::MD4Init command except that +it requires the key that will be included in the HMAC.

+
::md4::HMACUpdate token data
+
+
::md4::HMACFinal token
+

These commands are identical to the MD4 equivalent commands.

+
+
+

EXAMPLES

+
+% md4::md4 -hex "Tcl does MD4"
+858da9b31f57648a032230447bd15f25
+
+
+% md4::hmac -hex -key Sekret "Tcl does MD4"
+c324088e5752872689caedf2a0464758
+
+
+% set tok [md4::MD4Init]
+::md4::1
+% md4::MD4Update $tok "Tcl "
+% md4::MD4Update $tok "does "
+% md4::MD4Update $tok "MD4"
+% md4::Hex [md4::MD4Final $tok]
+858da9b31f57648a032230447bd15f25
+
+
+

REFERENCES

+
    +

  1. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    2. +

  2. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    3. +

  3. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    4. +

  4. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    5. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md4 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/md5/md5.html Index: embedded/www/tcllib/files/modules/md5/md5.html ================================================================== --- embedded/www/tcllib/files/modules/md5/md5.html +++ embedded/www/tcllib/files/modules/md5/md5.html @@ -0,0 +1,264 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

md5(n) 2.0.7 tcllib "MD5 Message-Digest Algorithm"

+

Name

+

md5 - MD5 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the MD5 message-digest +algorithm as described in RFC 1321 (1). This algorithm takes +an arbitrary quantity of data and generates a 128-bit message digest +from the input. The MD5 algorithm is related to the MD4 algorithm (2) +but has been strengthened against certain types of potential +attack. MD5 should be used in preference to MD4 for new applications.

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Alternatively if you have either +cryptkit or Trf then either of these can be used to +accelerate the digest computation. If no suitable compiled package is +available then the pure-Tcl implementation wil be used. The +programming interface remains the same in all cases.

+

Note the previous version of this package always returned a +hex encoded string. This has been changed to simplify the programming +interface and to make this version more compatible with other +implementations. To obtain the previous usage, either explicitly +specify package version 1 or use the -hex option to the +md5 command.

+
+

COMMANDS

+
+
::md5::md5 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the MD5 digest of the data given in string. This is returned +as a binary string by default. Giving the -hex option will +return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the md5 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::md5::hmac ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the MD5 +digest algorithm. HMACs are described in RFC 2104 (3) and provide an MD5 +digest that includes a key. All options other than -key are as +for the ::md5::md5 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the MD5 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the MD5 hash operates on a token (equivalent to the +bucket). You call MD5Init to obtain a token and then call +MD5Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +MD5Final. An equivalent set of functions gives you a keyed digest +(HMAC).

+
+
::md5::MD5Init
+

Begins a new MD5 hash. Returns a token ID that must be used for the +remaining functions.

+
::md5::MD5Update token data
+

Add data to the hash identified by token. Calling +MD5Update $token "abcd" is equivalent to calling +MD5Update $token "ab" followed by +MD5Update $token "cb". See EXAMPLES.

+
::md5::MD5Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit MD5 +digest value.

+
::md5::HMACInit key
+

This is equivalent to the ::md5::MD5Init command except that +it requires the key that will be included in the HMAC.

+
::md5::HMACUpdate token data
+
+
::md5::HMACFinal token
+

These commands are identical to the MD5 equivalent commands.

+
+
+

EXAMPLES

+
+% md5::md5 -hex "Tcl does MD5"
+8AAC1EE01E20BB347104FABB90310433
+
+
+% md5::hmac -hex -key Sekret "Tcl does MD5"
+35BBA244FD56D3EDF5F3C47474DACB5D
+
+
+% set tok [md5::MD5Init]
+::md5::1
+% md5::MD5Update $tok "Tcl "
+% md5::MD5Update $tok "does "
+% md5::MD5Update $tok "MD5"
+% md5::Hex [md5::MD5Final $tok]
+8AAC1EE01E20BB347104FABB90310433
+
+
+

REFERENCES

+
    +

  1. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md5 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/md5crypt/md5crypt.html Index: embedded/www/tcllib/files/modules/md5crypt/md5crypt.html ================================================================== --- embedded/www/tcllib/files/modules/md5crypt/md5crypt.html +++ embedded/www/tcllib/files/modules/md5crypt/md5crypt.html @@ -0,0 +1,202 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

md5crypt(n) 1.1.0 tcllib "MD5-based password encryption"

+

Name

+

md5crypt - MD5-based password encryption

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require md5 2.0
    • +
  • package require md5crypt ?1.1.0?
    • +
+ +
+
+

Description

+

This package provides an implementation of the MD5-crypt password +encryption algorithm as pioneered by FreeBSD and currently in use as a +replacement for the unix crypt(3) function in many modern +systems. An implementation of the closely related Apache MD5-crypt is +also available. +The output of these commands are compatible with the BSD and OpenSSL +implementation of md5crypt and the Apache 2 htpasswd program.

+
+

COMMANDS

+
+
::md5crypt::md5crypt password salt
+

Generate a BSD compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT).

+
::md5crypt::aprcrypt password salt
+

Generate an Apache compatible md5-encoded password hash from the plaintext +password and a random salt (see SALT).

+
::md5crypt::salt ?length?
+

Generate a random salt string suitable for use with the md5crypt and +aprcrypt commands.

+
+
+

SALT

+

The salt passed to either of the encryption schemes implemented here +is checked to see if it begins with the encryption scheme magic string +(either "$1$" for MD5-crypt or "$apr1$" for Apache crypt). If so, this +is removed. The remaining characters up to the next $ and up to a +maximum of 8 characters are then used as the salt. The salt text +should probably be restricted the set of ASCII alphanumeric characters +plus "./" (dot and forward-slash) - this is to preserve maximum +compatability with the unix password file format.

+

If a password is being generated rather than checked from a password +file then the salt command may be used to generate a random salt.

+
+

EXAMPLES

+
+% md5crypt::md5crypt password 01234567
+$1$01234567$b5lh2mHyD2PdJjFfALlEz1
+
+
+% md5crypt::aprcrypt password 01234567
+$apr1$01234567$IXBaQywhAhc0d75ZbaSDp/
+
+
+% md5crypt::md5crypt password [md5crypt::salt]
+$1$dFmvyRmO$T.V3OmzqeEf3hqJp2WFcb.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category md5crypt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/mime/mime.html Index: embedded/www/tcllib/files/modules/mime/mime.html ================================================================== --- embedded/www/tcllib/files/modules/mime/mime.html +++ embedded/www/tcllib/files/modules/mime/mime.html @@ -0,0 +1,364 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

mime(n) 1.6 tcllib "Mime"

+

Name

+

mime - Manipulation of MIME body parts

+
+ + +

Description

+

The mime library package provides the commands to create and +manipulate MIME body parts.

+
+
::mime::initialize ?-canonical type/subtype ?-param {key value}...? ?-encoding value? ?-header {key value}...?? (-file name | -string value | -parts {token1 ... tokenN})
+

This command creates a MIME part and returns a token representing it.

+
    +

  • If the -canonical option is present, then the body is in +canonical (raw) form and is found by consulting either the +-file, -string, or -parts option.

    +

    In addition, both the -param and -header options may +occur zero or more times to specify Content-Type parameters +(e.g., charset) and header keyword/values (e.g., +Content-Disposition), respectively.

    +

    Also, -encoding, if present, specifies the +Content-Transfer-Encoding when copying the body.

    • +

  • If the -canonical option is not present, then the MIME part +contained in either the -file or the -string option +is parsed, dynamically generating subordinates as appropriate.

    • +
+
::mime::finalize token ?-subordinates all | dynamic | none?
+

This command destroys the MIME part represented by token. It +returns an empty string.

+

If the -subordinates option is present, it specifies which +subordinates should also be destroyed. The default value is +dynamic, destroying all subordinates which were created by +::mime::initialize together with the containing body part.

+
::mime::getproperty token ?property | -names?
+

This command returns a string or a list of strings containing the +properties of a MIME part. If the command is invoked with the name of +a specific property, then the corresponding value is returned; +instead, if -names is specified, a list of all properties is +returned; otherwise, a serialized array of properties and values is +returned.

+

The possible properties are:

+
+
content
+

The type/subtype describing the content

+
encoding
+

The "Content-Transfer-Encoding"

+
params
+

A list of "Content-Type" parameters

+
parts
+

A list of tokens for the part's subordinates. This property is +present only if the MIME part has subordinates.

+
size
+

The approximate size of the content (unencoded)

+
+
::mime::getheader token ?key | -names?
+

This command returns the header of a MIME part, as a list of strings.

+

A header consists of zero or more key/value pairs. Each value is a +list containing one or more strings.

+

If this command is invoked with the name of a specific key, then +a list containing the corresponding value(s) is returned; instead, if +-names is specified, a list of all keys is returned; otherwise, a +serialized array of keys and values is returned. Note that when a key +is specified (e.g., "Subject"), the list returned usually contains +exactly one string; however, some keys (e.g., "Received") often occur +more than once in the header, accordingly the list returned usually +contains more than one string.

+
::mime::setheader token key value ?-mode write | append | delete?
+

This command writes, appends to, or deletes the value associated +with a key in the header. It returns a list of strings +containing the previous value associated with the key.

+

The value for -mode is one of:

+
+
write
+

The key/value is either created or overwritten (the default).

+
append
+

A new value is appended for the key (creating it as necessary).

+
delete
+

All values associated with the key are removed (the value +parameter is ignored).

+
+
::mime::getbody token ?-decode? ?-command callback ?-blocksize octets??
+

This command returns a string containing the body of the leaf MIME +part represented by token in canonical form.

+

If the -command option is present, then it is repeatedly +invoked with a fragment of the body as this:

+
+  uplevel #0 $callback [list "data" $fragment]
+
+

(The -blocksize option, if present, specifies the maximum +size of each fragment passed to the callback.)

+

When the end of the body is reached, the callback is invoked as:

+
+    uplevel #0 $callback "end"
+
+

Alternatively, if an error occurs, the callback is invoked as:

+
+    uplevel #0 $callback [list "error" reason]
+
+

Regardless, the return value of the final invocation of the callback +is propagated upwards by ::mime::getbody.

+

If the -command option is absent, then the return value of +::mime::getbody is a string containing the MIME part's entire +body.

+

If the option -decode is absent the return value computed +above is returned as is. This means that it will be in the charset +specified for the token and not the usual utf-8. +If the option -decode is present however the command will use +the charset information associated with the token to convert the +string from its encoding into utf-8 before returning it.

+
::mime::copymessage token channel
+

This command copies the MIME represented by token part to the +specified channel. The command operates synchronously, and uses +fileevent to allow asynchronous operations to proceed +independently. It returns an empty string.

+
::mime::buildmessage token
+

This command returns the MIME part represented by token as a +string. It is similar to ::mime::copymessage, only it returns +the data as a return string instead of writing to a channel.

+
::mime::parseaddress string
+

This command takes a string containing one or more 822-style address +specifications and returns a list of serialized arrays, one element +for each address specified in the argument. If the string contains +more than one address they will be separated by commas.

+

Each serialized array contains the properties below. Note that one or +more of these properties may be empty.

+
+
address
+

local@domain

+
comment
+

822-style comment

+
domain
+

the domain part (rhs)

+
error
+

non-empty on a parse error

+
group
+

this address begins a group

+
friendly
+

user-friendly rendering

+
local
+

the local part (lhs)

+
memberP
+

this address belongs to a group

+
phrase
+

the phrase part

+
proper
+

822-style address specification

+
route
+

822-style route specification (obsolete)

+
+
::mime::parsedatetime (string | -now) property
+

This command takes a string containing an 822-style date-time +specification and returns the specified property as a serialized +array.

+

The list of properties and their ranges are:

+
+
hour
+

0 .. 23

+
lmonth
+

January, February, ..., December

+
lweekday
+

Sunday, Monday, ... Saturday

+
mday
+

1 .. 31

+
min
+

0 .. 59

+
mon
+

1 .. 12

+
month
+

Jan, Feb, ..., Dec

+
proper
+

822-style date-time specification

+
rclock
+

elapsed seconds between then and now

+
sec
+

0 .. 59

+
wday
+

0 .. 6 (Sun .. Mon)

+
weekday
+

Sun, Mon, ..., Sat

+
yday
+

1 .. 366

+
year
+

1900 ...

+
zone
+

-720 .. 720 (minutes east of GMT)

+
+
::mime::mapencoding encoding_name
+

This commansd maps tcl encodings onto the proper names for their MIME +charset type. This is only done for encodings whose charset types +were known. The remaining encodings return "" for now.

+
::mime::reversemapencoding charset_type
+

This command maps MIME charset types onto tcl encoding names. Those +that are unknown return "".

+
+
+

KNOWN BUGS

+
+
Tcllib Bug #447037
+

This problem affects only people which are using Tcl and Mime on a +64-bit system. The currently recommended fix for this problem is to +upgrade to Tcl version 8.4. This version has extended 64 bit support +and the bug does not appear anymore.

+

The problem could have been generally solved by requiring the use of +Tcl 8.4 for this package. We decided against this solution as it would +force a large number of unaffected users to upgrade their Tcl +interpreter for no reason.

+

See Ticket 447037 for additional information.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category mime of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/mime/smtp.html Index: embedded/www/tcllib/files/modules/mime/smtp.html ================================================================== --- embedded/www/tcllib/files/modules/mime/smtp.html +++ embedded/www/tcllib/files/modules/mime/smtp.html @@ -0,0 +1,292 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

smtp(n) 1.4.5 tcllib "smtp client"

+

Name

+

smtp - Client-side tcl implementation of the smtp protocol

+
+ +

Synopsis

+
+
    +
  • package require Tcl
    • +
  • package require mime ?1.5.4?
    • +
  • package require smtp ?1.4.5?
    • +
+ +
+
+

Description

+

The smtp library package provides the client side of the +Simple Mail Transfer Protocol (SMTP) (1) (2).

+
+
::smtp::sendmessage token option...
+

This command sends the MIME part (see package mime) +represented by token to an SMTP server. options is a list +of options and their associated values. The recognized options are:

+
+
-servers
+

A list of SMTP servers. The default is localhost.

+
-ports
+

A list of SMTP ports. The default is 25.

+
-client
+

The name to use as our hostname when connecting to the server. By +default this is either localhost if one of the servers is localhost, +or is set to the string returned by info hostname.

+
-queue
+

Indicates that the SMTP server should be asked to queue the message +for later processing. A boolean value.

+
-atleastone
+

Indicates that the SMTP server must find at least one recipient +acceptable for the message to be sent. A boolean value.

+
-originator
+

A string containing an 822-style address specification. If present the +header isn't examined for an originator address.

+
-recipients
+

A string containing one or more 822-style address specifications. If +present the header isn't examined for recipient addresses). If the +string contains more than one address they will be separated by +commas.

+
-header
+

A list containing two elements, an smtp header and its associated +value (the -header option may occur zero or more times).

+
-usetls
+

This package supports the RFC 3207 TLS extension (3) by default provided the +tls package is available. You can turn this off with this boolean option.

+
-tlspolicy
+

This option lets you specify a command to be called if an error occurs +during TLS setup. The command is called with the SMTP code and diagnostic +message appended. The command should return 'secure' or 'insecure' where +insecure will cause the package to continue on the unencrypted channel. +Returning 'secure' will cause the socket to be closed and the next server +in the -servers list to be tried.

+
-username
+
+
-password
+

If your SMTP server requires authentication (RFC 2554 (4)) before +accepting mail you can use -username and -password +to provide your authentication details to the server. Currently this +package supports DIGEST-MD5, CRAM-MD5, LOGIN and PLAIN authentication +methods. The most secure method will be tried first and each method +tried in turn until we are either authorized or we run out of +methods. Note that if the server permits a TLS connection, then the +authorization will occur after we begin using the secure channel.

+

Please also read the section on Authentication, it details +the necessary prequisites, i.e. packages needed to support these +options and authentication.

+
+

If the -originator option is not present, the originator +address is taken from From (or Resent-From); +similarly, if the -recipients option is not present, +recipient addresses are taken from To, cc, and +Bcc (or Resent-To, and so on). Note that the header +key/values supplied by the -header option (not those present +in the MIME part) are consulted. Regardless, header key/values are +added to the outgoing message as necessary to ensure that a valid +822-style message is sent.

+

The command returns a list indicating which recipients were +unacceptable to the SMTP server. Each element of the list is another +list, containing the address, an SMTP error code, and a textual +diagnostic. Depending on the -atleastone option and the +intended recipients, a non-empty list may still indicate that the +message was accepted by the server.

+
+
+

Authentication

+

Beware. SMTP authentication uses SASL. I.e. if the user +has to authenticate a connection, i.e. use the options -user +and -password (see above) it is necessary to have the +sasl package available so that smtp can load it.

+

This is a soft dependency because not everybody requires authentication, +and sasl depends on a lot of the cryptographic (secure) hashes, +i.e. all of md5, otp, md4, sha1, +and ripemd160.

+
+

EXAMPLE

+
+proc send_simple_message {recipient email_server subject body} {
+    package require smtp
+    package require mime
+    set token [mime::initialize -canonical text/plain \\
+	-string $body]
+    mime::setheader $token Subject $subject
+    smtp::sendmessage $token \\
+	-recipients $recipient -servers $email_server
+    mime::finalize $token
+}
+send_simple_message someone@somewhere.com localhost \\
+    "This is the subject." "This is the message."
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

REFERENCES

+
    +

  1. Jonathan B. Postel, "SIMPLE MAIL TRANSFER PROTOCOL", RFC 821, August 1982. + (http://www.rfc-editor.org/rfc/rfc821.txt)

    2. +

  2. J. Klensin, "Simple Mail Transfer Protocol", RFC 2821, April 2001. + (http://www.rfc-editor.org/rfc/rfc2821.txt)

    3. +

  3. P. Hoffman, "SMTP Service Extension for Secure SMTP over Transport + Layer Security", RFC 3207, February 2002. + (http://www.rfc-editor.org/rfc/rfc3207.txt)

    4. +

  4. J. Myers, "SMTP Service Extension for Authentication", + RFC 2554, March 1999. + (http://www.rfc-editor.org/rfc/rfc2554.txt)

    5. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category smtp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/multiplexer/multiplexer.html Index: embedded/www/tcllib/files/modules/multiplexer/multiplexer.html ================================================================== --- embedded/www/tcllib/files/modules/multiplexer/multiplexer.html +++ embedded/www/tcllib/files/modules/multiplexer/multiplexer.html @@ -0,0 +1,228 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

multiplexer(n) 0.2 tcllib "One-to-many communication with sockets."

+

Name

+

multiplexer - One-to-many communication with sockets.

+
+ + +

Description

+

The multiplexer package provides a generic system for one-to-many +communication utilizing sockets. For example, think of a chat system +where one user sends a message which is then broadcast to all the +other connected users.

+

It is possible to have different multiplexers running concurrently.

+
+
::multiplexer::create
+

The create command creates a new multiplexer 'instance'. For +example:

+
set mp [::multiplexer::create]
+

This instance can then be manipulated like so:

+
${mp}::Init 35100
+
+
${multiplexer_instance}::Init port
+

This starts the multiplexer listening on the specified port.

+
${multiplexer_instance}::Config key value
+

Use Config to configure the multiplexer instance. Configuration +options currently include:

+
+
sendtoorigin
+

A boolean flag. If true, the sender will receive a copy of the +sent message. Defaults to false.

+
debuglevel
+

Sets the debug level to use for the multiplexer instance, according to +those specified by the logger package (debug, info, notice, +warn, error, critical).

+
+
${multiplexer_instance}::AddFilter cmdprefix
+

Command to add a filter for data that passes through the multiplexer +instance. +The registered cmdprefix is called when data arrives at a +multiplexer instance. If there is more than one filter command +registered at the instance they will be called in the order of +registristation, and each filter will get the result of the preceding +filter as its argument. The first filter gets the incoming data as its +argument. The result returned by the last filter is the data which +will be broadcast to all clients of the multiplexer instance. +The command prefix is called as

+
+
cmdprefix data chan clientaddress clientport
+

Takes the incoming data, modifies it, and returns that as its +result. The last three arguments contain information about the client +which sent the data to filter: The channel connecting us to the +client, its ip-address, and its ip-port.

+
+
${multiplexer_instance}::AddAccessFilter cmdprefix
+

Command to add an access filter. +The registered cmdprefix is called when a new client socket +tries to connect to the multixer instance. If there is more than one +access filter command registered at the instance they will be called +in the order of registristation. If any of the called commands returns +-1 the access to the multiplexer instance is denied and the +client channel is closed immediately. Any other result grants the +client access to the multiplexer instance. +The command prefix is called as

+
+
cmdprefix chan clientaddress clientport
+

The arguments contain information about the client which tries to +connected to the instance: The channel connecting us to the client, +its ip-address, and its ip-port.

+
+
${multiplexer_instance}::AddExitFilter cmdprefix
+

Adds filter to be run when client socket generates an EOF condition. +The registered cmdprefix is called when a client socket of the +multixer signals EOF. If there is more than one exit filter command +registered at the instance they will be called in the order of +registristation. Errors thrown by an exit filter are ignored, but +logged. Any result returned by an exit filter is ignored. +The command prefix is called as

+
+
cmdprefix chan clientaddress clientport
+

The arguments contain information about the client which signaled the +EOF: The channel connecting us to the client, its ip-address, and its +ip-port.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category multiplexer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/namespacex/namespacex.html Index: embedded/www/tcllib/files/modules/namespacex/namespacex.html ================================================================== --- embedded/www/tcllib/files/modules/namespacex/namespacex.html +++ embedded/www/tcllib/files/modules/namespacex/namespacex.html @@ -0,0 +1,185 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

namespacex(n) 0.1 tcllib "Namespace utility commands"

+

Name

+

namespacex - Namespace utility commands

+
+ + +

Description

+

This package provides a number of utility commands for working with +namespaces.

+
+

API

+
+
::namespacex hook add ?namespace? cmdprefix
+
+
::namespacex hook proc ?namespace? arguments body
+
+
::namespacex hook on ?namespace? guardcmdprefix actioncmdprefix
+
+
::namespacex hook next arg...
+
+
::namespacex info allchildren namespace
+

This command returns a list containing the names of all child +namespaces in the specified namespace and its children. The +names are all fully qualified.

+
::namespacex info allvars namespace
+

This command returns a list containing the names of all variables in +the specified namespace and its children. The names are all +relative to namespace, and not fully qualified.

+
::namespacex info vars namespace ?pattern?
+

This command returns a list containing the names of all variables in +the specified namespace.

+
::namespacex state get namespace
+

This command returns a dictionary holding the names and values of all +variables in the specified namespace and its child namespaces.

+

Note that the names are all relative to namespace, +and not fully qualified.

+
::namespacex state set namespace dict
+

This command takes a dictionary holding the names and values for a set +of variables and replaces the current state of the specified +namespace and its child namespaces with this state. +The result of the command is the empty string.

+
::namespacex state drop namespace
+

This command unsets all variables in the specified namespace and +its child namespaces. +The result of the command is the empty string.

+
+
+ + +
ADDED embedded/www/tcllib/files/modules/ncgi/ncgi.html Index: embedded/www/tcllib/files/modules/ncgi/ncgi.html ================================================================== --- embedded/www/tcllib/files/modules/ncgi/ncgi.html +++ embedded/www/tcllib/files/modules/ncgi/ncgi.html @@ -0,0 +1,371 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ncgi(n) 1.4.3 tcllib "CGI Support"

+

Name

+

ncgi - Procedures to manipulate CGI values.

+
+ + +

Description

+

The ncgi package provides commands that manipulate CGI +values. These are values that come from Web forms and are processed +either by CGI scripts or web pages with embedded Tcl code. Use the +ncgi package to query these values, set and get cookies, and +encode and decode www-url-encoded values.

+

In the simplest case, a CGI script first calls ::ncgi::parse and +then calls ::ncgi::value to get different form values. If a CGI +value is repeated, you should use ::ncgi::valueList to get back +the complete list of values.

+

An alternative to ::ncgi::parse is ::ncgi::input, which +has semantics similar to Don Libes' cgi_input procedure. +::ncgi::input restricts repeated CGI values to have names that +end with "List". In this case, ::ncgi::value will return the +complete list of values, and ::ncgi::input will raise errors if +it find repeated form elements without the right name.

+

The ::ncgi::reset procedure can be used in test suites and Web +servers to initialize the source of the CGI values. Otherwise the +values are read in from the CGI environment.

+

The complete set of procedures is described below.

+
+
::ncgi::cookie cookie
+

Return a list of values for cookie, if any. It is possible that +more than one cookie with the same name can be present, so this +procedure returns a list.

+
::ncgi::decode str
+

Decode strings in www-url-encoding, which represents special +characters with a %xx sequence, where xx is the character code in hex.

+
::ncgi::empty name
+

Returns 1 if the CGI variable name is not present or has the +empty string as its value.

+
::ncgi::exists name
+

The return value is a boolean. It returns 0 if the CGI +variable name is not present, and 1 otherwise.

+
::ncgi::encode string
+

Encode string into www-url-encoded format.

+
::ncgi::header ?type? args
+

Output the CGI header to standard output. This emits a Content-Type: +header and additional headers based on args, which is a list of +header names and header values. The type defaults to +"text/html".

+
::ncgi::import cginame ?tclname?
+

This creates a variable in the current scope with the value of the CGI +variable cginame. The name of the variable is tclname, or +cginame if tclname is empty (default).

+
::ncgi::importAll args
+

This imports several CGI variables as Tcl variables. If args is +empty, then every CGI value is imported. Otherwise each CGI variable +listed in args is imported.

+
::ncgi::importFile cmd cginame ?filename?
+

This provides information about an uploaded file from a form input +field of type file with name cginame. cmd can be +one of -server -client, -type or +-data.

+
+
-client cginame
+

returns the filename as sent by the client.

+
-type cginame
+

returns the mime type of the uploaded file.

+
-data cginame
+

returns the contents of the file.

+
-server cginame filename
+

writes the file contents to a local temporary file (or filename +if supplied) and returns the name of the file. The caller is +responsible for deleting this file after use.

+
+
::ncgi::input ?fakeinput? ?fakecookie?
+

This reads and decodes the CGI values from the environment. It +restricts repeated form values to have a trailing "List" in their +name. The CGI values are obtained later with the ::ncgi::value +procedure.

+
::ncgi::multipart type query
+

This procedure parses a multipart/form-data query. This is used +by ::ncgi::nvlist and not normally called directly. It returns +an alternating list of names and structured values. Each structure +value is in turn a list of two elements. The first element is +meta-data from the multipart/form-data structure. The second element +is the form value. If you use ::ncgi::value you just get the +form value. If you use ::ncgi::valueList you get the structured +value with meta data and the value.

+

The type is the whole Content-Type, including the parameters +like boundary. This returns a list of names and values that +describe the multipart data. The values are a nested list structure +that has some descriptive information first, and the actual form value +second. The descriptive information is list of header names and +values that describe the content.

+
::ncgi::nvlist
+

This returns all the query data as a name, value list. In the case of +multipart/form-data, the values are structured as described in +::ncgi::multipart.

+
::ncgi::names
+

This returns all names found in the query data, as a list. +::ncgi::multipart.

+
::ncgi::parse
+

This reads and decodes the CGI values from the environment. The CGI +values are obtained later with the ::ncgi::value procedure. IF +a CGI value is repeated, then you should use ::ncgi::valueList +to get the complete list of values.

+
::ncgi::parseMimeValue value
+

This decodes the Content-Type and other MIME headers that have the +form of "primary value; param=val; p2=v2" It returns a list, where the +first element is the primary value, and the second element is a list +of parameter names and values.

+
::ncgi::query
+

This returns the raw query data.

+
::ncgi::redirect url
+

Generate a response that causes a 302 redirect by the Web server. The +url is the new URL that is the target of the redirect. The URL +will be qualified with the current server and current directory, if +necessary, to convert it into a full URL.

+
::ncgi::reset query type
+

Set the query data and Content-Type for the current CGI session. This +is used by the test suite and by Web servers to initialize the ncgi +module so it does not try to read standard input or use environment +variables to get its data. If neither query or type are +specified, then the ncgi module will look in the standard +CGI environment for its data.

+
::ncgi::setCookie args
+

Set a cookie value that will be returned as part of the reply. This +must be done before ::ncgi::header or ::ncgi::redirect is +called in order for the cookie to be returned properly. The +args are a set of flags and values:

+
+
-name name
+
+
-value value
+
+
-expires date
+
+
-path path restriction
+
+
-domain domain restriction
+
+
+
::ncgi::setDefaultValue key defvalue
+

Set a CGI value if it does not already exists. This affects future +calls to ::ncgi::value (but not future calls to +::ncgi::nvlist). If the CGI value already is present, then this +procedure has no side effects.

+
::ncgi::setDefaultValueList key defvaluelist
+

Like ::ncgi::setDefaultValue except that the value already has +list structure to represent multiple checkboxes or a multi-selection.

+
::ncgi::setValue key value
+

Set a CGI value, overriding whatever was present in the CGI +environment already. This affects future calls to ::ncgi::value +(but not future calls to ::ncgi::nvlist).

+
::ncgi::setValueList key valuelist
+

Like ::ncgi::setValue except that the value already has list +structure to represent multiple checkboxes or a multi-selection.

+
::ncgi::type
+

Returns the Content-Type of the current CGI values.

+
::ncgi::urlStub ?url?
+

Returns the current URL, but without the protocol, server, and port. +If url is specified, then it defines the URL for the current +session. That value will be returned by future calls to +::ncgi::urlStub

+
::ncgi::value key ?default?
+

Return the CGI value identified by key. If the CGI value is not +present, then the default value is returned instead. This value +defaults to the empty string.

+

If the form value key is repeated, then there are two cases: if +::ncgi::parse was called, then ::ncgi::value only returns +the first value associated with key. If ::ncgi::input was +called, then ::ncgi::value returns a Tcl list value and +key must end in "List" (e.g., "skuList"). In the case of +multipart/form-data, this procedure just returns the value of the form +element. If you want the meta-data associated with each form value, +then use ::ncgi::valueList.

+
::ncgi::valueList key ?default?
+

Like ::ncgi::value, but this always returns a list of values +(even if there is only one value). In the case of +multipart/form-data, this procedure returns a list of two elements. +The first element is meta-data in the form of a parameter, value list. +The second element is the form value.

+
+
+

EXAMPLES

+

Uploading a file

+
+HTML:
+<html>
+<form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
+Path: <input type="file" name="filedata"><br>
+Name: <input type="text" name="filedesc"><br>
+<input type="submit">
+</form>
+</html>
+TCL: upload.cgi
+#!/usr/local/bin/tclsh
+::ncgi::parse
+set filedata [::ncgi::value filedata]
+set filedesc [::ncgi::value filedesc]
+puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"
+set filename /www/images/$filedesc
+set fh [open $filename w]
+puts -nonewline $fh $filedata
+close $fh
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ncgi of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

CGI programming

+
+
ADDED embedded/www/tcllib/files/modules/nettool/nettool.html Index: embedded/www/tcllib/files/modules/nettool/nettool.html ================================================================== --- embedded/www/tcllib/files/modules/nettool/nettool.html +++ embedded/www/tcllib/files/modules/nettool/nettool.html @@ -0,0 +1,250 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nettool(n) 0.5.1 tcllib "nettool"

+

Name

+

nettool - Tools for networked applications

+
+ + +

Description

+

The nettool package consists of a Pure-tcl set of tools +to perform common network functions that would normally require +different packages or calls to exec, in a standard Tcl interface. +At present nettool has reference implementations for the following operating +systems: Windows, MacOSX, and Linux (debian).

+
+

Commands

+
+
::cat filename
+

Dump the contents of a file as a result.

+
::nettool::allocate_port startingport
+

Attempt to allocate startingport, or, if busy, advance the port +number sequentially until a free port is found, and claim that port. +This command uses a built-in database of known ports to avoid returning a +port which is in common use. (For example: http (80))

+
::nettool::arp_table
+

Dump the contents of this computer's Address Resolution Protocol (ARP) table. +The result will be a Tcl formatted list: macid ipaddrlist ...

+
::nettool::broadcast_list
+

Returns a list of broadcast addresses (suitable for UDP multicast) +that this computer is associated with.

+
::nettool::claim_port port ?protocol?
+

Mark port as busy, optionally as either tcp (default) or udp.

+
::nettool::cpuinfo args
+

If no arguments are given, return a key/value list describing the +CPU of the present machine. Included in the matrix is info on the number +of cores/processors that are available for parallel tasking, installed physical +RAM, and processor family.

+

The exact contents are platform specific.

+

For Linux, information is drawn from /proc/cpuinfo and /proc/meminfo.

+

For MacOSX, information is drawn from sysctl

+

For Windows, information is draw from TWAPI.

+

If arguments are given, the result with be a key/value list limited to the +fields requested.

+

Canonical fields for all platforms:

+
+
cpus
+

Count of CPUs/cores/execution units

+
speed
+

Clock speed of processor(s) in Mhz

+
memory
+

Installed RAM (in MB)

+
vendor
+

Manufacturer

+
+
::nettool::find_port startingport
+

Return startingport if it is available, or the next free port after +startingport. Note: Unlike ::nettool::allocate_port, this +command does not claim the port.

+

This command uses a built-in database of known ports to avoid returning a +port which is in common use. (For example: http (80))

+
::nettool::hwid_list
+

Return a list of hardware specific identifiers from this computer. The source +and content will vary by platform.

+

For MacOSX, the motherboard serial number and macids for all network devices is returned.

+

For Windows, the volume serial number of C and macids for all network devices is returned.

+

For Linux, macids for all network devices is returned.

+
::nettool::ip_list
+

Return a list of IP addresses associated with this computer.

+
::nettool::mac_list
+

Return a list of MACIDs for the network cards attached to this machine. The MACID of the +primary network card is returned first.

+
::nettool::network_list
+

Return a list of networks associated with this computer. Networks are formated with +ip::nativeToPrefix.

+
::nettool::port_busy port
+

Return true if port is claimed, false otherwise.

+
::nettool::release_port port ?protocol?
+

Mark port as not busy, optionally as either tcp (default) or udp.

+
::nettool::status
+

Return a key/value list describing the status of the computer. The output +is designed to be comparable to the output of top for all platforms.

+

Common fields include:

+
+
load
+

Processes per processing unit

+
memory_total
+

Total physical RAM (MB)

+
memory_free
+

Total physical RAM unused (MB)

+
+
::nettool::user_data_root appname
+

Return a fully qualified path to a folder where appname should store it's data. +The path is not created, only computed, by this command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category odie of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

System

+
+ +
ADDED embedded/www/tcllib/files/modules/nmea/nmea.html Index: embedded/www/tcllib/files/modules/nmea/nmea.html ================================================================== --- embedded/www/tcllib/files/modules/nmea/nmea.html +++ embedded/www/tcllib/files/modules/nmea/nmea.html @@ -0,0 +1,228 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nmea(n) 1.0.0 tcllib "NMEA protocol implementation"

+

Name

+

nmea - Process NMEA data

+
+ + +

Description

+

This package provides a standard interface for writing software which recieves +NMEA standard input data. It allows for reading data from COM ports, files, +or programmatic input. It also supports the checksumming and logging of incoming data. +After parsing, input is dispatched to user defined handler commands for processing. +To define a handler, see the event command. There are no GPS specific functions +in this package. NMEA data consists of a sentence type, followed by a list of data.

+
+

COMMANDS

+
+
::nmea::input sentence
+

Processes and dispatches the supplied sentence. If sentence contains no commas it is treated as a Tcl list, otherwise it must be standard comma delimited NMEA data, with an optional checksum and leading $.

+
+nmea::input {$GPGSA,A,3,04,05,,09,12,,,24,,,,,2.5,1.3,2.1*39}
+nmea::input [list GPGSA A 3 04 05  09 12 "" "" 24 "" "" ""  2.5 1.3 2.1]
+
+
+
::nmea::open_port port ?speed?
+

Open the specified COM port and read NMEA sentences when available. Port speed is set to +4800bps by default or to speed.

+
::nmea::close_port
+

Close the com port connection if one is open.

+
::nmea::configure_port settings
+

Changes the current port settings. settings has the same format as fconfigure -mode.

+
::nmea::open_file file ?rate?
+

Open file file and read NMEA sentences, one per line, at the rate specified by ?rate? in milliseconds. +The file format may omit the leading $ and/or the checksum. If rate is <= 0 (the default) then lines +will only be processed when a call to do_line is made.

+
::nmea::close_file
+

Close the open file if one exists.

+
::nmea::do_line
+

If there is a currently open file, this command will read and process a single line from it. +Returns the number of lines read.

+
::nmea::rate
+

Sets the rate at which lines are processed from the open file, in milliseconds. The rate remains +consistant across files, there does not need to be a file currently open to use this command. +Set to 0 to disable automatic line processing.

+
::nmea::log ?file?
+

Starts or stops input logging. If a file name is specified then all NMEA data recieved on +the open port will be logged to the ?file? in append mode. If file is an empty string then +any logging will be stopped. If no file is specified then returns a boolean value indicating +if logging is currently enabled. Data written to the port by write, + data read from files, or input made using input, is not logged.

+
::nmea::checksum data
+

Returns the checksum of the supplied data.

+
::nmea::write sentence data
+

If there is a currently open port, this command will write the specified sentence and data to the port +in proper NMEA checksummed format.

+
::nmea::event setence ?command?
+

Registers a handler proc for a given NMEA sentence. There may be at most one handler per +sentence, any existing handler is replaced. +If no command is specified, returns the name of the current handler for the given setence +or an empty string if none exists. In addition to the incoming sentences there are 2 builtin types, +EOF and DEFAULT. The handler for the DEFAULT setence is invoked if there is not a specific handler +for that sentence. The EOF handler is invoked when End Of File is reached on the open file or port.

+

The handler procedures, with the exception of the builtin types,must take exactly one argument, +which is a list of the data values. +The DEFAULT handler should have two arguments, the sentence type and the data values. +The EOF handler has no arguments.

+
+nmea::event gpgsa parse_sat_detail
+nmea::event default handle_unknown
+proc parse_sat_detail {data} {
+    puts [lindex $data 1]
+}
+proc handle_unknown {name data} {
+    puts "unknown data type $name"
+}
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nmea of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_auto.html Index: embedded/www/tcllib/files/modules/nns/nns_auto.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_auto.html +++ embedded/www/tcllib/files/modules/nns/nns_auto.html @@ -0,0 +1,218 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nameserv::auto(n) 0.3 tcllib "Name service facility"

+

Name

+

nameserv::auto - Name service facility, Client Extension

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require nameserv::auto ?0.3?
    • +
  • package require nameserv
    • +
+
+
+

Description

+

Please read the document Name service facility, introduction +first.

+

This package provides the exact same API as is provided by +package nameserv, i.e. the regular name service client. It +differs from the former by taking measures to ensure that longer-lived +data, i.e. bound names, continuous and unfullfilled async searches, +survive the loss of the connection to the name server as much as is +possible.

+

This means that the bound names and continuous and unfullfilled async +searches are remembered client-side and automatically re-entered into +the server when the connection comes back after its loss. For bound +names there is one important limitation to such restoration: It is +possible that a name of this client was bound by a different client +while the connection was gone. Such names are fully lost, and the best +the package can and will do is to inform the user of this.

+
+

API

+

The user-visible API is mainly identical to the API of nameserv +and is therefore not described here. Please read the documentation of +nameserv.

+

The differences are explained below, in the sections OPTIONS and +EVENTS.

+
+

OPTIONS

+

This package supports all the options of package nameserv, +plus one more. The additional option allows the user to specify the +time interval between attempts to restore a lost connection.

+
+
-delay milliseconds
+

The value of this option is an integer value > 0 which specifies the +interval to wait between attempts to restore a lost connection, in +milliseconds. The default value is 1000, i.e. one second.

+
+
+

EVENTS

+

This package generates all of the events of package nameserv, +plus two more. Both events are generated for the tag nameserv.

+
+
lost-name
+

This event is generated when a bound name is truly lost, i.e. could +not be restored after the temporary loss of the connection to the name +server. It indicates that a different client took ownership of the +name while this client was out of contact.

+

The detail information of the event will be a Tcl dictionary +containing two keys, name, and data. Their values hold +all the information about the lost name.

+
re-connection
+

This event is generated when the connection to the server is +restored. The remembered data has been restored when the event is +posted.

+

The event has no detail information.

+
+
+

DESIGN

+

The package is implemented on top of the regular nameservice client, +i.e. package nameserv. It detects the loss of the +connection by listening for lost-connection events, on the tag +nameserv.

+

It reacts to such events by starting a periodic timer and trying to +reconnect to the server whenver this timer triggers. On success the +timer is canceled, a re-connection event generated, and the +package proceeds to re-enter the remembered bound names and continuous +searches.

+

Another loss of the connection, be it during or after re-entering the +remembered information simply restarts the timer and subsequent +reconnection attempts.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_client.html Index: embedded/www/tcllib/files/modules/nns/nns_client.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_client.html +++ embedded/www/tcllib/files/modules/nns/nns_client.html @@ -0,0 +1,393 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nameserv(n) 0.4.2 tcllib "Name service facility"

+

Name

+

nameserv - Name service facility, Client

+
+ + +

Description

+

Please read Name service facility, introduction first.

+

This package provides a client for the name service facility +implemented by the package nameserv::server.

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+
+

API

+

The package exports eight commands, as specified below:

+
+
::nameserv::bind name data
+

The caller of this command registers the given name as its name +in the configured name service, and additionally associates a piece of +data with it. The service does nothing with this information +beyond storing it and delivering it as part of search results. The +meaning is entirely up to the applications using the name service.

+

A generally useful choice would for example be an identifier for a +communication endpoint managed by the package comm. Anybody +retrieving the name becomes immediately able to talk to this endpoint, +i.e. the registering application.

+

Of further importance is that a caller can register itself under more +than one name, and each name can have its own piece of data.

+

Note that the name service, and thwerefore this command, will throw an +error if the chosen name is already registered.

+
::nameserv::release
+

Invoking this command releases all names (and their data) registered +by all previous calls to ::nameserv::bind of this client. Note +that the name service will run this command implicitly when it loses +the connection to this client.

+
::nameserv::search ?-async|-continuous? ?pattern?
+

This command searches the name service for all registered names +matching the specified glob-pattern. If not specified the +pattern defaults to *, matching everything. The result of the +command is a dictionary mapping the matching names to the data +associated with them at bind-time.

+

If either option -async or -continuous were +specified the result of this command changes and becomes the Tcl +command of an object holding the actual result. +These two options are supported if and only if the service the client +is connected to supports the protocol feature +Search/Continuous.

+

For -async the result object is asynchronously filled with +the entries matching the pattern at the time of the search and then +not modified any more. +The option -continuous extends this behaviour by additionally +continuously monitoring the service for the addition and removal of +entries which match the pattern, and updating the object's contents +appropriately.

+

Note that the caller is responsible for configuring the object +with a callback for proper notification when the current result (or +further changes) arrive.

+

For more information about this object see section +ASYNCHRONOUS AND CONTINUOUS SEARCHES.

+
::nameserv::protocol
+

This command returns the highest version of the name service protocol +supported by the package.

+
::nameserv::server_protocol
+

This command returns the highest version of the name service protocol +supported by the name service the client is currently connected to.

+
::nameserv::server_features
+

This command returns a list containing the names of the features of +the name service protocol which are supported by the name service the +client is currently connected to.

+
::nameserv::cget -option
+

This command returns the currently configured value for the specified +-option. The list of supported options and their meaning can +be found in section OPTIONS.

+
::nameserv::configure
+

In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section OPTIONS.

+
::nameserv::configure -option
+

In this form the command is an alias for +"::nameserv::cget -option]". +The list of supported options and their meaning can be found in +section OPTIONS.

+
::nameserv::configure -option value...
+

In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section OPTIONS.

+

This form can be used only as long as the client has not contacted the +name service yet. After contact has been made reconfiguration is not +possible anymore. This means that this form of the command is for the +initalization of the client before it use. +The command forcing a contact with the name service are

+
+
bind
+
+
release
+
+
search
+
+
server_protocol
+
+
server_features
+
+
+
+
+

CONNECTION HANDLING

+

The client automatically connects to the service when one of the +commands below is run for the first time, or whenever one of the +commands is run after the connection was lost, when it was lost.

+
+
bind
+
+
release
+
+
search
+
+
server_protocol
+
+
server_features
+
+
+

Since version 0.2 of the client it will generate an event when the +connection is lost, allowing higher layers to perform additional +actions. This is done via the support package uevent. This +and all other name service related packages hereby reserve the +uevent-tag nameserv. All their events will be posted to that +tag.

+
+

EVENTS

+

This package generates only one event, lost-connection. The +detail information provided to that event is a Tcl dictionary. The +only key contained in the dictionnary is reason, and its value +will be a string describing why the connection was lost. +This string is supplied by the underlying communication package, +i.e. comm.

+
+

OPTIONS

+

The options supported by the client are for the specification of which +name service to contact, i.e. of the location of the name service. +They are:

+
+
-host name|ipaddress
+

This option specifies the host name service to contact is running on, +either by name, or by ipaddress. The initial default is +localhost, i.e. it is expected to contact a name service +running on the same host as the application using this package.

+
-port number
+

This option specifies the port the name service to contact is +listening on. It has to be a positive integer number (> 0) not greater +than 65536 (unsigned short). The initial default is the number +returned by the command ::nameserv::common::port, as provided by +the package ::nameserv::common.

+
+
+

ASYNCHRONOUS AND CONTINUOUS SEARCHES

+

Asynchronous and continuous searches are invoked by using either +option -async or -continuous as argument to the +command ::nameserv::search.

+

Note that these two options are supported if and only if the +service the client is connected to supports the protocol feature +Search/Continuous. The service provided by the package +::nameserv::server does this since version 0.3.

+

For such searches the result of the search command is the Tcl command +of an object holding the actual result. The API provided by these +objects is:

+
+
Options:
+
+
-command command_prefix
+

This option has to be set if a user of the result object wishes to get +asynchronous notifications when the search result or changes to it +arrive.

+

Note that while it is possible to poll for the arrival of the +initial search result via the method filled, and for +subsequent changes by comparing the output of method getall +against a saved copy, this is not the recommended behaviour. Setting +the -command callback and processing the notifications as +they arrive is much more efficient.

+

The command_prefix is called with two arguments, the type of +change, and the data of the change. The type is either add or +remove, indicating new data, or deleted data, respectively. +The data of the change is always a dictionary listing the +added/removed names and their associated data.

+

The first change reported for a search is always the set of matching +entries at the time of the search.

+
+
Methods:
+
+
$result destroy
+

Destroys the object and cancels any continuous monitoring of the +service the object may have had active.

+
$result filled
+

The result is a boolean value indicating whether the search result has +already arrived (True), or not (False).

+
$result get name
+

Returns the data associated with the given name at +bind-time.

+
$result names
+

Returns a list containing all names known to the object at the time of +the invokation.

+
$result size
+

Returns an integer value specifying the size of the result at the time +of the invokation.

+
$result getall ?pattern?
+

Returns a dictionary containing the search result at the time of the +invokation, mapping the matching names to the data associated with +them at bind-time.

+
+
+
+

HISTORY

+
+
0.3.1
+

Fixed SF Bug 1954771.

+
0.3
+

Extended the client with the ability to perform asynchronous and +continuous searches.

+
0.2
+

Extended the client with the ability to generate events when it loses +its connection to the name service. Based on package uevent.

+
0.1
+

Initial implementation of the client.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_common.html Index: embedded/www/tcllib/files/modules/nns/nns_common.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_common.html +++ embedded/www/tcllib/files/modules/nns/nns_common.html @@ -0,0 +1,169 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nameserv::common(n) 0.1 tcllib "Name service facility"

+

Name

+

nameserv::common - Name service facility, shared definitions

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8
    • +
  • package require nameserv::common ?0.1?
    • +
+ +
+
+

Description

+

Please read Name service facility, introduction first.

+

This package is internal and of no interest to users. It provides the +commands of the name service facility which are shared by the client +and server implemented by the packages nameserv::server and +nameserv (the client).

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+
+

API

+

The package exports a single command, as specified below:

+
+
::nameserv::common::port
+

The result returned by the command is the id of the default TCP/IP +port a nameservice server will listen on, and a name service client +will try to connect to.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

nameserv::client(n), nameserv::server(n)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_intro.html Index: embedded/www/tcllib/files/modules/nns/nns_intro.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_intro.html +++ embedded/www/tcllib/files/modules/nns/nns_intro.html @@ -0,0 +1,207 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nns_intro(n) 1.0 tcllib "Name service facility"

+

Name

+

nns_intro - Name service facility, introduction

+
+ +

Description

+

nns (short for nano nameservice) is a facility built +for the package comm, adding a simple name service to it. +It is also built on top of comm, using it for the exchange +of messages between the client and server parts.

+

This name service facility has nothing to do with the Internet's +Domain Name System, otherwise known as DNS. If the +reader is looking for a package dealing with that please see either of +the packages dns and resolv, both found in Tcllib +too.

+

Tcllib provides 2 applications and 4 packages which are working +together and provide access to the facility at different levels.

+
+

Applications

+

The application nnsd provides a simple name server which can +be run by anybody anywhere on their system, as they see fit. +It is also an example on the use of the server-side package +nameserv::server.

+

Complementing this server is the nns client application. +A possible, but no very sensible use would be to enter name/port +bindings into a server from a shell script. Not sensible, as shell +scripts normally do not provide a comm-based service.

+

The only case for this to make some sense would be in a shell script +wrapped around a Tcl script FOO which is using comm, to register the +listening port used by FOO. +However even there it would much more sensible to extend FOO to use +the nameservice directly. And in regard on how to that nns +can be used as both example and template. +Beyond that it may also be useful to perform nameservice queries from +shell scripts.

+

The third application, nnslog is a stripped down form of the +nns client application. It is reduced to perform a continuous +search for all changes and logs all received events to stdout.

+

Both clients use the nameserv::auto package to automatically +hande the loss and restoration of the connection to the server.

+
+

Packages

+

The two main packages implementing the service are nameserv +and nameserv::server, i.e. client and server. The latter has +not much of an API, just enough to start, stop, and configure it. See +the application nnsd on how to use it.

+

The basic client, in package nameserv, provides the main API +to manipulate and query the service. An example of its use is the +application nns.

+

The second client package, nameserv::auto is API compatible +to the basic client, but provides the additional functionality that it +will automatically restore data like bound names when the connection +to the name service was lost and then reestablished. I.e. it +automatically detects the loss of the server and re-enters the data +when the server comes back.

+

The package nameserv::common is of no interest to users. It +is an internal package containing code and definitions common to the +packages nameserv and nameserv::server.

+

All packages use the uevent package for the reporting of +special circumstances via events, and reserve the uevent-tag +nameserv for their exclusive use. All their events will be +posted to that tag.

+
+

Internals

+

The document Name service facility, client/server protocol +specifies the protocol used by the packages nameserv and +nameserv::server to talk to each other. It is of no interest +to users of either the packages or applications.

+

Developers wishing to modify and/or extend or to just understand the +internals of the nameservice facility however are strongly advised to +read it.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_protocol.html Index: embedded/www/tcllib/files/modules/nns/nns_protocol.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_protocol.html +++ embedded/www/tcllib/files/modules/nns/nns_protocol.html @@ -0,0 +1,261 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nameserv::protocol(n) 0.1 tcllib "Name service facility"

+

Name

+

nameserv::protocol - Name service facility, client/server protocol

+
+ + +

Description

+

The packages nameserv::server, nameserv, and +nameserv::common provide a simple unprotected name service +facility for use in small trusted environments.

+

Please read Name service facility, introduction first.

+

This document contains the specification of the network protocol which +is used by client and server to talk to each other, enabling +implementations of the same protocol in other languages.

+
+

Nano Name Service Protocol Version 1

+

This protocol defines the basic set of messages to be supported by a +name service, also called the Core feature.

+

Basic Layer

+

The basic communication between client and server is done using the +remote-execution protocol specified by the Tcl package comm. +The relevant document specifying its on-the-wire protocol can be found +in comm_wire.

+

All the scripts exchanged via this protocol are single commands in +list form and thus can be interpreted as plain messages instead of as +Tcl commands. The commands/messages specified in the next section are +the only commands understood by the server-side. Command and variable +substitutions are not allowed within the messages, i.e. arguments have +to be literal values.

+

The protocol is synchronous. I.e. for each message sent a response is +expected, and has to be generated. All messages are sent by the client. +The server does not sent messages, only responses to messages.

+
+

Message Layer

+
+
Bind name data
+

The client sends this message when it registers itself at the service +with a name and some associated data. The server has to +send an error response if the name is already in use. Otherwise +the response has to be an empty string.

+

The server has to accept multiple names for the same client.

+
Release
+

The client sends this message to unregister all names it is known +under at the service. The response has to be an empty string, always.

+
Search pattern
+

The client sends this message to search the service for names matching +the glob-pattern. The response has to be a dictionary containing +the matching names as keys, and mapping them to the data associated +with it at Bind-time.

+
ProtocolVersion
+

The client sends this message to query the service for the highest +version of the name service protocol it supports. The response has to +be a positive integer number.

+

Servers supporting only Nano Name Service Protocol Version 1 +have to return 1.

+
ProtocolFeatures
+

The client sends this message to query the service for the features of +the name service protocol it supports. The response has to be a +list containing feature names.

+

Servers supporting only Nano Name Service Protocol Version 1 +have to return {Core}.

+
+
+
+

Nano Name Service Protocol Extension: Continuous Search

+

This protocol defines an extended set of messages to be supported by a +name service, also called the Search/Continuous feature. This +feature defines additional messages between client and server, and is +otherwise identical to version 1 of the protocol. See the last section +for the details of our foundation.

+

A service supporting this feature has to put the feature name +Search/Continuous into the list of features returned by the +message ProtocolFeatures.

+

For this extension the protocol is asynchronous. No direct response is +expected for any of the messages in the extension. Furthermore the +server will start sending messages on its own, instead of only +responses to messages, and the client has to be able to handle these +notifications.

+
+
Search/Continuous/Start tag pattern
+

The client sends this message to start searching the service for names +matching the glob-pattern. +In contrast to the regular Search request this one asks the +server to continuously monitor the database for the addition and +removal of matching entries and to notify the client of all such +changes. The particular search is identified by the tag.

+

No direct response is expected, rather the clients expect to be +notified of changes via explicit Search/Continuous/Result +messages generated by the service.

+

It is further expected that the tag information is passed +unchanged to the Search/Continuous/Result messages. This +tagging of the results enables clients to start multiple searches and +distinguish between the different results.

+
Search/Continuous/Stop tag
+

The client sends this message to stop the continuous search identified +by the tag.

+
Search/Continuous/Change tag add|remove response
+

This message is sent by the service to clients with active continuous +searches to transfer found changes. The first such message for a new +continuous search has to contains the current set of matching entries.

+

To ensure this a service has to generate an add-message with +an empty response if there were no matching entries at the time.

+

The response has to be a dictionary containing the matching +names as keys, and mapping them to the data associated with it at +Bind-time. +The argument coming before the response tells the client whether the +names in the response were added or removed from the service.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nns/nns_server.html Index: embedded/www/tcllib/files/modules/nns/nns_server.html ================================================================== --- embedded/www/tcllib/files/modules/nns/nns_server.html +++ embedded/www/tcllib/files/modules/nns/nns_server.html @@ -0,0 +1,244 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nameserv::server(n) 0.3.2 tcllib "Name service facility"

+

Name

+

nameserv::server - Name service facility, Server

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require nameserv::server ?0.3.2?
    • +
  • package require comm
    • +
  • package require interp
    • +
  • package require logger
    • +
+ +
+
+

Description

+

Please read Name service facility, introduction first.

+

This package provides an implementation of the serviver side of the +name service facility queried by the client provided by the package +nameserv. All information required by the server will be +held in memory. There is no persistent state.

+

This service is built in top of and for the package comm. +It has nothing to do with the Internet's Domain Name System. If the +reader is looking for a package dealing with that please see Tcllib's +packages dns and resolv.

+

This server supports the Core protocol feature, and since +version 0.3 the Search/Continuous feature as well.

+
+

API

+

The package exports five commands, as specified below:

+
+
::nameserv::server::start
+

This command starts the server and causes it to listen on the +configured port. From now on clients are able to connect and make +requests. The result of the command is the empty string.

+

Note that any incoming requests will only be handled if the +application the server is part of does enter an event loop after this +command has been run.

+
::nameserv::server::stop
+

Invoking this command stops the server and releases all information it +had. Existing connections are shut down, and no new connections will +be accepted any longer. The result of the command is the empty string.

+
::nameserv::server::active?
+

This command returns a boolean value indicating the state of the +server. The result will be true if the server is active, +i.e. has been started, and false otherwise.

+
::nameserv::server::cget -option
+

This command returns the currently configured value for the specified +-option. The list of supported options and their meaning can +be found in section OPTIONS.

+
::nameserv::server::configure
+

In this form the command returns a dictionary of all supported +options, and their current values. The list of supported options and +their meaning can be found in section OPTIONS.

+
::nameserv::server::configure -option
+

In this form the command is an alias for +"::nameserv::server::cget -option]". +The list of supported options and their meaning can be found in +section OPTIONS.

+
::nameserv::server::configure -option value...
+

In this form the command is used to configure one or more of the +supported options. At least one option has to be specified, and each +option is followed by its new value. +The list of supported options and their meaning can be found in +section OPTIONS.

+

This form can be used only if the server is not active, i.e. has not +been started yet, or has been stopped. While the server is active it +cannot be reconfigured.

+
+
+

OPTIONS

+

The options supported by the server are for the specification of the +TCP port to listen on, and whether to accept non-local connections or +not. +They are:

+
+
-localonly bool
+

This option specifies whether to accept only local connections +(-localonly 1) or remote connections as well (-localonly 0). The +default is to accept only local connections.

+
-port number
+

This option specifies the port the name service will listen on after +it has been started. It has to be a positive integer number (> 0) not +greater than 65536 (unsigned short). The initial default is the number +returned by the command ::nameserv::server::common::port, as +provided by the package ::nameserv::server::common.

+
+
+

HISTORY

+
+
0.3
+

Extended the server with the ability to perform asynchronous and +continuous searches.

+
0.2
+

Changed name of -local switch to -localonly.

+
0.1
+

Initial implementation of the server.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

nameserv::client(n), nameserv::common(n)

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/nntp/nntp.html Index: embedded/www/tcllib/files/modules/nntp/nntp.html ================================================================== --- embedded/www/tcllib/files/modules/nntp/nntp.html +++ embedded/www/tcllib/files/modules/nntp/nntp.html @@ -0,0 +1,398 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

nntp(n) 1.5.1 tcllib "Tcl NNTP Client Library"

+

Name

+

nntp - Tcl client for the NNTP protocol

+
+ + +

Description

+

The package nntp provides a simple Tcl-only client library +for the NNTP protocol. It works by opening the standard NNTP socket +on the server, and then providing a Tcl API to access the NNTP +protocol commands. All server errors are returned as Tcl errors +(thrown) which must be caught with the Tcl catch command.

+
+

COMMANDS

+
+
::nntp::nntp ?host? ?port? ?nntpName?
+

The command opens a socket connection to the specified NNTP server and +creates a new nntp object with an associated global Tcl command whose +name is nntpName. This command may be used to access the various +NNTP protocol commands for the new connection. The default port +number is "119" and the default host is "news". These defaults +can be overridden with the environment variables NNTPPORT and +NNTPHOST respectively.

+

Some of the commands supported by this package are not part of the +nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt) and will +not be available (or implemented) on all nntp servers.

+

The access command nntpName has the following general form:

+
+
nntpName method ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+
nntpName article ?msgid?
+

Query the server for article msgid from the current group. The article +is returned as a valid tcl list which contains the headers, followed by +a blank line, and then followed by the body of the article. Each element +in the list is one line of the article.

+
nntpName authinfo ?user? ?pass?
+

Send authentication information (username and password) to the server.

+
nntpName body ?msgid?
+

Query the server for the body of the article msgid from the current +group. The body of the article is returned as a valid tcl list. Each element +in the list is one line of the body of the article.

+
nntpName configure
+
+
nntpName configure option
+
+
nntpName configure option value ...
+
+
nntpName cget option
+

Query and configure options of the nntp connection object. Currently +only one option is supported, -binary. When set articles are +retrieved as binary data instead of text. The only methods affected by +this are article and body.

+

One application of this option would be the download of articles +containing yEnc encoded images. Although encoded the data is still +mostly binary and retrieving it as text will corrupt the information.

+

See package yencode for both encoder and decoder of such data.

+
nntpName date
+

Query the server for the servers current date. The date is returned in the +format YYYYMMDDHHMMSS.

+
nntpName group ?group?
+

Optionally set the current group, and retrieve information about the +currently selected group. Returns the estimated number of articles in +the group followed by the number of the first article in the group, followed +by the last article in the group, followed by the name of the group.

+
nntpName head ?msgid?
+

Query the server for the headers of the article msgid from the current +group. The headers of the article are returned as a valid tcl list. Each element +in the list is one line of the headers of the article.

+
nntpName help
+

Retrieves a list of the commands that are supported by the news server that +is currently attached to.

+
nntpName last
+

Sets the current article pointer to point to the previous message (if there is +one) and returns the msgid of that message.

+
nntpName list
+

Returns a tcl list of valid newsgroups and associated information. Each +newsgroup is returned as an element in the tcl list with the following format:

+
+      group last first p
+
+

where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n').

+

The <first> and <last> fields will always be numeric. They may have +leading zeros. If the <last> field evaluates to less than the +<first> field, there are no articles currently on file in the +newsgroup.

+
nntpName listgroup ?group?
+

Query the server for a list of all the messages (message numbers) in the +group specified by the argument group or by the current group if +the group argument was not passed.

+
nntpName mode_reader
+

Query the server for its nntp 'MODE READER' response string.

+
nntpName newgroups since
+

Query the server for a list of all the new newsgroups created since the time +specified by the argument since. The argument since can be any +time string that is understood by clock scan. The tcl list of newsgroups +is returned in a similar form to the list of groups returned by the +nntpName list command. Each element of the list has the form:

+
+      group last first p
+
+

where <group> is the name of the newsgroup, <last> is the number of +the last known article currently in that newsgroup, <first> is the +number of the first article currently in the newsgroup, and <p> is +either 'y' or 'n' indicating whether posting to this newsgroup is +allowed ('y') or prohibited ('n').

+
nntpName newnews
+

Query the server for a list of new articles posted to the current group in the +last day.

+
nntpName newnews since
+

Query the server for a list of new articles posted to the current group since +the time specified by the argument since. The argument since can +be any time string that is understood by clock scan.

+
nntpName newnews group ?since?
+

Query the server for a list of new articles posted to the group specified by +the argument group since the time specified by the argument since +(or in the past day if no since argument is passed. The argument +since can be any time string that is understood by clock scan.

+
nntpName next
+

Sets the current article pointer to point to the next message (if there is +one) and returns the msgid of that message.

+
nntpName post article
+

Posts an article of the form specified in +RFC 1036 (http://www.rfc-editor.org/rfc/rfc1036.txt, successor +to RFC 850) to the current news group.

+
nntpName slave
+

Identifies a connection as being made from a slave nntp server. This might +be used to indicate that the connection is serving multiple people and should +be given priority. Actual use is entirely implementation dependent and may +vary from server to server.

+
nntpName stat ?msgid?
+

The stat command is similar to the article command except that no +text is returned. When selecting by message number within a group, +the stat command serves to set the current article pointer without +sending text. The returned acknowledgment response will contain the +message-id, which may be of some value. Using the stat command to +select by message-id is valid but of questionable value, since a +selection by message-id does NOT alter the "current article pointer"

+
nntpName quit
+

Gracefully close the connection after sending a NNTP QUIT command down +the socket.

+
nntpName xgtitle ?group_pattern?
+

Returns a tcl list where each element is of the form:

+
+newsgroup description
+
+

If a group_pattern is specified then only newsgroups that match +the pattern will have their name and description returned.

+
nntpName xhdr field ?range?
+

Returns the specified header field value for the current message or for a +list of messages from the current group. field is the title of a +field in the header such as from, subject, date, etc. If range is +not specified or is "" then the current message is queried. The command +returns a list of elements where each element has the form of:

+
+    msgid value
+
+

Where msgid is the number of the message and value is the value set for the +queried field. The range argument can be in any of the following forms:

+
+
""
+

The current message is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
nntpName xover ?range?
+

Returns header information for the current message or for a range of messages +from the current group. The information is returned in a tcl list +where each element is of the form:

+
+    msgid subject from date idstring bodysize headersize xref
+
+

If range is not specified or is "" then the current message is queried. +The range argument can be in any of the following forms:

+
+
""
+

The current message is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
nntpName xpat field range ?pattern_list?
+

Returns the specified header field value for a specified message or for a +list of messages from the current group where the messages match the +pattern(s) given in the pattern_list. field is the title of a +field in the header such as from, subject, date, etc. The information is +returned in a tcl list where each element is of the form:

+
+    msgid value
+
+

Where msgid is the number of the message and value is the value set for the +queried field. The range argument can be in any of the following forms:

+
+
msgid
+

The message specified by msgid is queried.

+
msgid1-msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
msgid1 msgid2
+

All messages between msgid1 and msgid2 +(including msgid1 and msgid2) are queried.

+
+
+
+

EXAMPLE

+

A bigger example for posting a single article.

+
+    package require nntp
+    set n [nntp::nntp NNTP_SERVER]
+    $n post "From: USER@DOMAIN.EXT (USER_FULL)
+    Path: COMPUTERNAME!USERNAME
+    Newsgroups: alt.test
+    Subject: Tcl test post -ignore
+    Message-ID: <[pid][clock seconds]
+    @COMPUTERNAME>
+    Date: [clock format [clock seconds] -format "%a, %d %
+    b %y %H:%M:%S GMT" -gmt true]
+    Test message body"
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nntp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/ntp/ntp_time.html Index: embedded/www/tcllib/files/modules/ntp/ntp_time.html ================================================================== --- embedded/www/tcllib/files/modules/ntp/ntp_time.html +++ embedded/www/tcllib/files/modules/ntp/ntp_time.html @@ -0,0 +1,250 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ntp_time(n) 1.2.1 tcllib "Network Time Facilities"

+

Name

+

ntp_time - Tcl Time Service Client

+
+ + +

Description

+

This package implements a client for the RFC 868 TIME protocol +(http://www.rfc-editor.org/rfc/rfc868.txt) and also a minimal +client for the RFC 2030 Simple Network Time Protocol +(http://www.rfc-editor.org/rfc/rfc2030.txt). +RFC 868 returns the time in seconds since 1 January 1900 +to either tcp or udp clients. RFC 2030 also gives this time but also +provides a fractional part which is not used in this client.

+
+

COMMANDS

+
+
::time::gettime ?options? timeserver ?port?
+

Get the time from timeserver. You may specify any of the options +listed for the configure command here. This command returns a +token which must then be used with the remaining commands in this +package. Once you have finished, you should use cleanup to +release all resources. The default port is 37.

+
::time::getsntp ?options? timeserver ?port?
+

Get the time from an SNTP server. This accepts exactly the same +arguments as ::time::gettime except that the default port is +123. The result is a token as per ::time::gettime and +should be handled in the same way.

+

Note that it is unlikely that any SNTP server will reply using tcp so +you will require the tcludp or the ceptcl +package. If a suitable package can be loaded then the udp protocol +will be used by default.

+
::time::configure ?options?
+

Called with no arguments this command returns all the current +configuration options and values. Otherwise it should be called with +pairs of option name and value.

+
+
-protocol number
+

Set the default network protocol. This defaults to udp if the tcludp + package is available. Otherwise it will use tcp.

+
-port number
+

Set the default port to use. RFC 868 uses port 37, RFC 2030 uses +port 123.

+
-timeout number
+

Set the default timeout value in milliseconds. The default is 10 seconds.

+
-command number
+

Set a command procedure to be run when a reply is received. The + procedure is called with the time token appended to the argument list.

+
-loglevel number
+

Set the logging level. The default is 'warning'.

+
+
::time::cget name
+

Get the current value for the named configuration option.

+
::time::unixtime token
+

Format the returned time for the unix epoch. RFC 868 time defines + time 0 as 1 Jan 1900, while unix time defines time 0 as 1 Jan + 1970. This command converts the reply to unix time.

+
::time::status token
+

Returns the status flag. For a successfully completed query this will be + ok. May be error or timeout or eof. + See also ::time::error

+
::time::error token
+

Returns the error message provided for requests whose status is error. + If there is no error message then an empty string is returned.

+
::time::reset token ?reason?
+

Reset or cancel the query optionally specfying the reason to record + for the error command.

+
::time::wait token
+

Wait for a query to complete and return the status upon completion.

+
::time::cleanup token
+

Remove all state variables associated with the request.

+
+
+% set tok [::time::gettime ntp2a.mcc.ac.uk]
+% set t [::time::unixtime $tok]
+% ::time::cleanup $tok
+
+
+% set tok [::time::getsntp pool.ntp.org]
+% set t [::time::unixtime $tok]
+% ::time::cleanup $tok
+
+
+proc on_time {token} {
+   if {[time::status $token] eq "ok"} {
+      puts [clock format [time::unixtime $token]]
+   } else {
+      puts [time::error $token]
+   }
+   time::cleanup $token
+}
+time::getsntp -command on_time pool.ntp.org
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ntp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

ntp

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/oauth/oauth.html Index: embedded/www/tcllib/files/modules/oauth/oauth.html ================================================================== --- embedded/www/tcllib/files/modules/oauth/oauth.html +++ embedded/www/tcllib/files/modules/oauth/oauth.html @@ -0,0 +1,306 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

oauth(n) 1.0 tcllib "oauth"

+

Name

+

oauth - oauth API base signature

+
+ + +

Description

+

The oauth package provides a simple Tcl-only library +for communication with oauth APIs. +This current version of the package supports the Oauth 1.0 Protocol, +as specified in RFC 5849.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Commands

+
+
::oauth::config
+

When this command is invoked without arguments it returns a dictionary +containing the current values of all options.

+
::oauth::config ?options...?
+

When invoked with arguments, options followed by their values, it is used +to set and query various parameters of application and client, like proxy +host and user agent for the HTTP requests. The detailed list of options +is below:

+
+
-accesstoken string
+

This is the user's token.

+
-accesstokensecret string
+

This is the user's secret token.

+
-consumerkey string
+

This is the public token of your app.

+
-consumersecret string
+

This is the private token of your app.

+
-debug bool
+

The default value is off. If you change this option to on, +the basic signature just created will be printed to stdout, among other +debug output.

+
-oauthversion version
+

This is the version of the OAuth protocol to use. +At the moment only 1.0 is supported, the default.

+
-proxyhost hostname
+

You can set up a proxy host for send contact the oauth's api server.

+
-proxyport port-number
+

Port number of your proxy.

+
-signmethod method
+

The signature method to use. OAuth 1.0 only supports HMAC-SHA1, the default.

+
-timeout milliseconds
+

Timeout in milliseconds for your query. +The default value is 6000, i.e. 6 seconds.

+
-urlencoding encoding
+

The encoding used for creating the x-url-encoded URLs with +::http::formatQuery. The default is utf-8, as specified +by RFC 2718.

+
+
::oauth::header baseURL ?postQuery?
+

This command is the base signature creator. With proper settings for various tokens +and secrets (See ::oauth::config) the result is the base authentication string +to send to the server.

+

You do not need to call this procedure to create the query because +::oauth::query (see below) will do for it for you. +Doing so is useful for debugging purposes, though.

+
+
url baseURL
+

This argument is the URI path to the OAuth API server. +If you plan send a GET query, you should provide a full path.

+
+HTTP GET 
+::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente} 
+
+
+
url-encoded-string postQuery
+

When you have to send a header in POST format, you have to put the query string into this argument.

+
+::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true}
+
+
+
+
::oauth::query baseURL ?postQuery?
+

This procedure will use the settings made with ::oauth::config to create the +basic authentication and then send the command to the server API. +It takes the same arguments as ::oauth::header.

+

The returned result will be a list containing 2 elements. The first +element will be a dictionary containing the HTTP header data response. +This allows you, for example, to check the X-Rate-Limit from OAuth. +The second element will be the raw data returned from API server. +This string is usually a json object which can be further decoded with the +functions of package json, or any other json-parser for Tcl.

+

Here is an example of how it would work in Twitter. Do not forget to +replace the placeholder tokens and keys of the example with your own tokens +and keys when trying it out.

+
% package require oauth
+% package require json
+% oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret}
+% set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente]
+% set jsondata [lindex $response 1]
+% set data [json::json2dict $jsondata]
+$ set data [lindex $data 0]
+% dict for {key val} $data {puts "$key => $val"}
+id => 158812437
+id_str => 158812437
+name => Un Librepensador
+screen_name => AbiertaMente
+location => Explico mis tuits ahí →
+description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q
+url => http://t.co/SGs3k9odBn
+entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}}
+protected => false
+followers_count => 72705
+friends_count => 53099
+listed_count => 258
+created_at => Wed Jun 23 18:29:58 +0000 2010
+favourites_count => 297
+utc_offset => 7200
+time_zone => Madrid
+geo_enabled => false
+verified => false
+statuses_count => 8996
+lang => es
+status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name Ἑλένη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und
+contributors_enabled => false
+is_translator => true
+is_translation_enabled => false
+profile_background_color => 709397
+profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
+profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
+profile_background_tile => true
+profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
+profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
+profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874
+profile_link_color => FF3300
+profile_sidebar_border_color => FFFFFF
+profile_sidebar_fill_color => A0C5C7
+profile_text_color => 333333
+profile_use_background_image => true
+default_profile => false
+default_profile_image => false
+following => true
+follow_request_sent => false
+notifications => false
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category oauth of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/ooutil/ooutil.html Index: embedded/www/tcllib/files/modules/ooutil/ooutil.html ================================================================== --- embedded/www/tcllib/files/modules/ooutil/ooutil.html +++ embedded/www/tcllib/files/modules/ooutil/ooutil.html @@ -0,0 +1,273 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

oo::util(n) 1.2.2 tcllib "Utility commands for TclOO"

+

Name

+

oo::util - Utility commands for TclOO

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require oo::util ?1.2.2?
    • +
+ +
+
+

Description

+

This package provides a convenience command for the easy specification +of instance methods as callback commands, like timers, file events, Tk +bindings, etc.

+
+

COMMANDS

+
+
mymethod method ?arg...?
+

This command is available within instance methods. It takes a method +name and, possibly, arguments for the method and returns a command +prefix which, when executed, will invoke the named method of the +object we are in, with the provided arguments, and any others supplied +at the time of actual invokation.

+

Note: The command is equivalent to and named after the command +provided by the OO package snit for the same purpose.

+
classmethod name arguments body
+

This command is available within class definitions. It takes a method +name and, possibly, arguments for the method and creates a method on the +class, available to a user of the class and of derived classes.

+

Note: The command is equivalent to the command typemethod +provided by the OO package snit for the same purpose.

+

Example

+
+oo::class create ActiveRecord {
+    classmethod find args { puts "[self] called with arguments: $args" }
+}
+oo::class create Table {
+    superclass ActiveRecord
+}
+puts [Table find foo bar]
+# ======
+# which will write
+# ======
+# ::Table called with arguments: foo bar
+
+
+
classvariable ?arg...?
+

This command is available within instance methods. It takes a series +of variable names and makes them available in the method's scope. The +originating scope for the variables is the class (instance) the object +instance belongs to. In other words, the referenced variables are shared +between all instances of their class.

+

Note: The command is roughly equivalent to the command +typevariable provided by the OO package snit for the +same purpose. The difference is that it cannot be used in the class +definition itself.

+

Example:

+
+% oo::class create Foo {
+    method bar {z} {
+        classvariable x y
+        return [incr x $z],[incr y]
+    }
+}
+::Foo
+% Foo create a
+::a
+% Foo create b
+::b
+% a bar 2
+2,1
+% a bar 3
+5,2
+% b bar 7
+12,3
+% b bar -1
+11,4
+% a bar 0
+11,5
+
+
+
link method...
+
+
link {alias method}...
+

This command is available within instance methods. It takes a list of +method names and/or pairs of alias- and method-name and makes the +named methods available to all instance methods without requiring the +my command.

+

The alias name under which the method becomes available defaults +to the method name, except where explicitly specified through an +alias/method pair.

+

Examples:

+
+    link foo
+    # The method foo is now directly accessible as foo instead of my foo.
+    link {bar foo}
+    # The method foo is now directly accessible as bar.
+    link a b c
+    # The methods a, b, and c all become directly acessible under their
+    # own names.
+
+

The main use of this command is expected to be in instance constructors, +for convenience, or to set up some methods for use in a mini DSL.

+
ooutil::singleton ?arg...?
+

This command is a meta-class, i.e. a variant of the builtin +oo::class which ensures that it creates only a single +instance of the classes defined with it.

+

Syntax and results are like for oo::class.

+

Example:

+
+% oo::class create example {
+   self mixin singleton
+   method foo {} {self}
+}
+::example
+% [example new] foo
+::oo::Obj22
+% [example new] foo
+::oo::Obj22
+
+
+
+
+

AUTHORS

+

Donal Fellows, Andreas Kupries

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category oo::util of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/otp/otp.html Index: embedded/www/tcllib/files/modules/otp/otp.html ================================================================== --- embedded/www/tcllib/files/modules/otp/otp.html +++ embedded/www/tcllib/files/modules/otp/otp.html @@ -0,0 +1,205 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

otp(n) 1.0.0 tcllib "RFC 2289 A One-Time Password System"

+

Name

+

otp - One-Time Passwords

+
+ + +

Description

+

This package is an implementation in Tcl of the One-Time Password +system as described in RFC 2289 (1). This system uses message-digest +algorithms to sequentially hash a passphrase to create single-use +passwords. The resulting data is then provided to the user as either +hexadecimal digits or encoded using a dictionary of 2048 words. This +system is used by OpenBSD for secure login and can be used as a SASL +mechanism for authenticating users.

+

In this implementation we provide support for four algorithms that are +included in the tcllib distribution: MD5 (2), MD4 (3), RIPE-MD160 (4) +and SHA-1 (5).

+
+ +

EXAMPLES

+
+% otp::otp-md5 -count 99 -seed host67821 "My Secret Pass Phrase"
+(binary gibberish)
+% otp::otp-md5 -words -count 99 -seed host67821 "My Secret Pass Phrase"
+SOON ARAB BURG LIMB FILE WAD
+% otp::otp-md5 -hex -count 99 -seed host67821 "My Secret Pass Phrase"
+e249b58257c80087
+
+
+

REFERENCES

+
    +

  1. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998. + http://www.rfc-editor.org/rfc/rfc2289.txt

    2. +

  2. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    3. +

  3. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    4. +

  4. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    5. +

  5. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    6. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category otp of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_intro.html Index: embedded/www/tcllib/files/modules/page/page_intro.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_intro.html +++ embedded/www/tcllib/files/modules/page/page_intro.html @@ -0,0 +1,148 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_intro(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_intro - page introduction

+
+ +

Description

+

page (short for parser generator) stands for a set of +related packages which help in the construction of parser generators, +and other utilities doing text processing.

+

They are mainly geared towards supporting the Tcllib application +page, with the package page::pluginmgr in a central +role as the plugin management for the application. The other packages +are performing low-level text processing and utility tasks geared +towards parser generation and mainly accessed by page through +plugins.

+

The packages implementing the plugins are not documented as regular +packages, as they cannot be loaded into a general interpreter, like +tclsh, without extensive preparation of the interpreter. Preparation +which is done for them by the plugin manager.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_pluginmgr.html Index: embedded/www/tcllib/files/modules/page/page_pluginmgr.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_pluginmgr.html +++ embedded/www/tcllib/files/modules/page/page_pluginmgr.html @@ -0,0 +1,706 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_pluginmgr(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_pluginmgr - page plugin manager

+
+ +

Synopsis

+
+
    +
  • package require page::pluginmgr ?0.2?
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides the plugin manager central to the page +application. It manages the various reader, writer, configuration, and +transformation plugins which actually process the text (read, +transform, and write).

+

All plugins are loaded into slave interpreters specially prepared for +them. While implemented using packages they need this special +environment and are not usable in a plain interpreter, like +tclsh. Because of that they are only described in general terms in +section PREDEFINED PLUGINS, and not documented as regular +packages. It is expected that they follow the APIs specified in the +sections

+
    +

  1. CONFIG PLUGIN API

    2. +

  2. READER PLUGIN API

    3. +

  3. WRITER PLUGIN API

    4. +

  4. TRANSFORM PLUGIN API

    5. +
+

as per their type.

+
+

API

+
+
::page::pluginmgr::reportvia cmd
+

This command defines the callback command used by +::page::pluginmgr::report (see below) to report input errors and +warnings. The default is to write such reports to the standard error +channel.

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

This command is used to report input errors and warnings. By default +such reports are written to the standard error. This can be changed by +setting a user-specific callback command with +::page::pluginmgr::reportvia (see above).

+

The arguments level and text specify both the importance +of the message, and the message itself. For the former see the package +logger for the allowed values.

+

The optional argument from and to can be used by the +caller to indicate the location (or range) in the input where the +reported problem occured. Each is a list containing two elements, the +line and the column in the input, in this order.

+
::page::pluginmgr::log cmd
+

This command defines a log callback command to be used by loaded +plugins for the reporting of internal errors, warnings, and general +information. Specifying the empty string as callback disables logging.

+

Note: The cmd has to be created by the logger package, +or follow the same API as such.

+

The command returns the empty string as its result.

+
::page::pluginmgr::configuration name
+

This command loads the named configuration plugin, retrieves the +options encoded in it, and then immediately unloads it again.

+

If the name is the path to a file, then this files will be tried +to be loaded as a plugin first, and, if that fails, opened and its +contents read as a list of options and their arguments, separated by +spaces, tabs and newlines, possibly quotes with single and double +quotes.

+

See section CONFIG PLUGIN API for the API expected of +configuration plugins.

+

The result of the command is the list of options retrieved.

+
::page::pluginmgr::reader name
+

This command loads the named reader plugin and initializes it. The +result of the command 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 section READER PLUGIN API for the API expected of +reader plugins.

+
::page::pluginmgr::rconfigure dict
+

This commands configures the loaded reader plugin. The options and +their values are provided as a Tcl dictionary. The result of the +command is the empty string.

+
::page::pluginmgr::rtimeable
+

This commands checks if the loaded reader plugin is able to collect +timing statistics. The result of the command is a boolean flag. The +result is true if the plugin can be timed, and false +otherwise.

+
::page::pluginmgr::rtime
+

This command activates the collection of timing statistics in the +loaded reader plugin.

+
::page::pluginmgr::rgettime
+

This command retrieves the collected timing statistics of the loaded +reader plugin after it was executed.

+
::page::pluginmgr::rhelp
+

This command retrieves the help string of the loaded reader +plugin. This is expected to be in doctools format.

+
::page::pluginmgr::rlabel
+

This command retrieves the human-readable name of the loaded reader +plugin.

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

This command invokes the loaded reader plugin to process the input, +and returns the results of the plugin as its own result. The input is +accessible through the callback commands read, and eof. The +optional done can be used to intrecept when the plugin has +completed its processing. All arguments are command prefixes.

+

The plugin will invoke the various callbacks in the following +situations:

+
+
read num
+

is invoked whenever input to process is needed, with the number of +characters/bytes it asks for. The result is expected to be the input +the plugin is in need of.

+
eof
+

is invoked by the plugin to check if the input has reached the of the +stream. The result is expected to be a boolean flag, true when +the input has hit EOF, and false otherwise.

+
done
+

is invoked when the plugin has completed the processing of the input.

+
+
::page::pluginmgr::writer name
+

This command loads the named writer plugin and initializes it. The +result of the command 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 section WRITER PLUGIN API for the API expected of +writer plugins.

+
::page::pluginmgr::wconfigure dict
+

This commands configures the loaded writer plugin. The options and +their values are provided as a Tcl dictionary. The result of the +command is the empty string.

+
::page::pluginmgr::wtimeable
+

This commands checks if the loaded writer plugin is able to measure +execution times. The result of the command is a boolean flag. The +result is true if the plugin can be timed, and false +otherwise.

+
::page::pluginmgr::wtime
+

This command activates the collection of timing statistics in the +loaded writer plugin.

+
::page::pluginmgr::wgettime
+

This command retrieves the collected timing statistics of the loaded +writer plugin after it was executed.

+
::page::pluginmgr::whelp
+

This command retrieves the help string of the loaded writer +plugin. This is expected to be in doctools format.

+
::page::pluginmgr::wlabel
+

This command retrieves the human-readable name of the loaded writer +plugin.

+
::page::pluginmgr::write chan data
+

The loaded writer plugin is invoked to generate the output. It is +given the data to generate the outpout from, and the Tcl handle +chan of the channel to write the generated output to. The +command returns th empty string as its result.

+
::page::pluginmgr::transform name
+

This command loads the named transformation plugin and initializes +it. The result of the command is a 2-element list containing the +plugin id and a list of options the plugin understands, in this order.

+

Multiple transformations plugins can be loaded and are identified by +handles.

+

See section TRANSFORM PLUGIN API for the API expected of +transformation plugins.

+
::page::pluginmgr::tconfigure id dict
+

This commands configures the identified transformation plugin. The +options and their values are provided as a Tcl dictionary. The result +of the command is the empty string.

+
::page::pluginmgr::ttimeable id
+

This commands checks if the identified transformation plugin is able +to collect timing statistics. The result of the command is a boolean +flag. The result is true if the plugin can be timed, and +false otherwise.

+
::page::pluginmgr::ttime id
+

This command activates the collection of timing statistics in the +identified transformation plugin.

+
::page::pluginmgr::tgettime id
+

This command retrieves the collected timing statistics of the +identified transformation plugin after it was executed.

+
::page::pluginmgr::thelp id
+

This command retrieves the help string of the identified +transformation plugin. This is expected to be in doctools +format.

+
::page::pluginmgr::tlabel id
+

This command retrieves the human-readable name of the identified +transformation plugin.

+
::page::pluginmgr::transform_do id data
+

The identified transformation plugin is invoked 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.

+
+
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 is 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

+

Reader plugins are expected to provide the following commands, +described below.

+
+
page_rfeature name
+

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 section FEATURES for the possible features the plugin +manager will ask for.

+
page_rtime
+

This command is invoked to activate the collection of timing +statistics.

+
page_rgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_rlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_rhelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_roptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_rconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_rrun
+

This command is invoked to process the input stream per the current +plugin configuration. The result of the command is the result of the +processing.

+
+

Reader plugins expect the environment to provide the following special +commands.

+
+
page_read num
+

This command is invoked to read num characters/bytes from the +input. Its result has to be read characters/bytes.

+
page_read_done
+

This command is invoked to signal that the plugin has completed the +processing of the input.

+
page_eof
+

This command is 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.

+
+

It is expected that a reader plugin FOO is implemented +by the package page::reader::FOO.

+

Reader plugins are loaded by the command +::page::pluginmgr::reader. At most one reader plugin can be kept +in memory.

+
+

WRITER PLUGIN API

+

Writer plugins are expected to provide the following commands, +described below.

+
+
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.

+

See section FEATURES for the possible features the plugin +manager will ask for.

+
page_wtime
+

This command is invoked to activate the collection of timing +statistics.

+
page_wgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_wlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_whelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_woptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_wconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_wrun chan data
+

This command is invoked to process the specified data and write +it to the output stream chan. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string.

+
+

Writer plugins expect the environment to provide the following 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.

+
+

It is expected that a writer plugin FOO is implemented +by the package page::writer::FOO.

+

Writer plugins are loaded by the command +::page::pluginmgr::writer. At most one writer plugin can be kept +in memory.

+
+

TRANSFORM PLUGIN API

+

page::transform::* +Transformation plugins are expected to provide the following 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 section FEATURES for the possible features the plugin +manager will ask for.

+
page_ttime
+

This command is invoked to activate the collection of timing +statistics.

+
page_tgettime
+

This command is invoked to retrieve the collected timing statistics.

+
page_tlabel
+

This command is invoked to retrieve a human-readable label for the +plugin.

+
page_thelp
+

This command is invoked to retrieve a help text for plugin. The text +is expected to be in doctools format.

+
page_toptions
+

This command is invoked to retrieve the options understood by the +plugin.

+
page_tconfigure option value
+

This command is invoked to reconfigure the plugin, specifically the +given option is set to the new value.

+
page_trun chan data
+

This command is invoked to process the specified data and write +it to the output stream chan. The latter is a Tcl channel handle +opened for writing. The result of the command is the empty string.

+
+

Transformation plugins expect the environment to provide the following +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.

+
+

It is expected that a transformation plugin FOO is implemented +by the package page::transform::FOO.

+

Transformation plugins are loaded by the command +::page::pluginmgr::transform. More than one transformation +plugin can be kept in memory.

+
+

PREDEFINED PLUGINS

+

The following predefined plugins are known, i.e. provided by the page +module.

+
+
Configuration
+
+
peg
+

Returns a set of options to configure the page application +for the processing of a PEG grammar and the generation of ME code. See +the packages grammar_peg, grammar_me and relations +for more details.

+
+
Reader
+
+
hb
+

Expects a so-called half-baked PEG container as input and +returns the equivalent abstract syntax tree. See the writer plugin +hb for the plugin generating this type of input.

+
lemon
+

Expects a grammar specification as understood by Richar Hipp's LEMON +parser generator and returns an abstract syntax tree for it.

+
peg
+

Expects a grammar specification in the form of a parsing expression +grammar (PEG) and returns an abstract syntax tree for it.

+
ser
+

Expect the serialized form of a parsing expression grammar as +generated by the package grammar::peg as input, converts it +into an equivalent abstract syntax tree and returns that.

+
treeser
+

Expects the serialized form of a tree as generated by the package +struct::tree as input and returns it, after validation.

+
+
Writer
+
+
hb
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out in the form of a so-called +half-baked PEG container.

+
identity
+

Takes any input and writes it as is.

+
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 parses input in +that grammar.

+
null
+

Takes any input and writes nothing. The logical equivalent of +/dev/null.

+
peg
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out in the form of a canonical PEG which can be +read by the reader plugin peg.

+
ser
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out as a serialized PEG container which can be +read by the reader plugin ser.

+
tpc
+

Expects an abstract syntax tree for a parsing expression grammar as +input and writes it out as Tcl code initializing a PEG container as +provided by the package grammar::peg.

+
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, performs a reachability analysis, and returns the modified and +annotated tree.

+
realizable
+

Takes an abstract syntax tree for a parsing expression grammer as +input, performs an analysis of realizability, and returns the modified +and annotated tree.

+
+
+
+

FEATURES

+

The plugin manager currently checks the plugins for only one feature, +timeable. A plugin supporting this feature is assumed to be +able to collect timing statistics on request.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_flow.html Index: embedded/www/tcllib/files/modules/page/page_util_flow.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_util_flow.html +++ embedded/www/tcllib/files/modules/page/page_util_flow.html @@ -0,0 +1,200 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_util_flow(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_flow - page dataflow/treewalker utility

+
+ +

Synopsis

+
+
    +
  • package require page::util::flow ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command for easy dataflow based +manipulation of arbitrary data structures, especially abstract syntax +trees.

+
+

API

+
+
::page::util::flow start flowvar nodevar script
+

This command contains the core logic to drive the walking of an +arbitrary data structure which can partitioned into separate +parts. Examples of such structures are trees and graphs.

+

The command makes no assumptions at all about the API of the structure +to be walked, except that that its parts, here called nodes, +are identified by strings. These strings are taken as is, from the +arguments, and the body, and handed back to the body, without +modification.

+

Access to the actual data structure, and all decisions regarding which +nodes to visit in what order are delegated to the body of the loop, +i.e. the script.

+

The body is invoked first for the nodes in the start-set specified via +start), and from then on for the nodes the body has requested to +be visited. The command stops when the set of nodes to visit becomes +empty. Note that a node can be visited more than once. The body has +complete control about this.

+

The body is invoked in the context of the caller. The variable named +by nodevar will be set to the current node, and the variable +named by flowvar will be set to the command of the flow object +through which the body can request the nodes to visit next. The API +provided by this object is described in the next section, +FLOW API.

+

Note that the command makes no promises regarding the order in which +nodes are visited, excpt that the nodes requested to be visited by the +current iteration will be visited afterward, in some order.

+
+
+

FLOW API

+

This section describes the API provided by the flow object made +accessible to the body script of ::page::util::flow.

+
+
flow visit node
+

Invoking this method requests that the node n is visited after +the current iteration.

+
flow visitl nodelist
+

Invoking this method requests that all the nodes found in the list +nodelist are visited after the current iteration.

+
flow visita node...
+

This is the variadic arguments form of the method visitl, see +above.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html Index: embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html +++ embedded/www/tcllib/files/modules/page/page_util_norm_lemon.html @@ -0,0 +1,162 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_util_norm_lemon(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_norm_lemon - page AST normalization, LEMON

+
+ +

Synopsis

+
+
    +
  • package require page::util::norm_lemon ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command which takes an AST for a +lemon grammar and normalizes it in various ways. The result +is called a Normalized Lemon Grammar Tree.

+

Note that this package can only be used from within a plugin +managed by the package page::pluginmgr.

+
+

API

+
+
::page::util::norm::lemon tree
+

This command assumes the tree object contains for a lemon +grammar. It normalizes this tree in place. The result is called a +Normalized Lemon Grammar Tree.

+

The exact operations performed are left undocumented for the moment.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_norm_peg.html Index: embedded/www/tcllib/files/modules/page/page_util_norm_peg.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_util_norm_peg.html +++ embedded/www/tcllib/files/modules/page/page_util_norm_peg.html @@ -0,0 +1,200 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_util_norm_peg(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_norm_peg - page AST normalization, PEG

+
+ +

Synopsis

+
+
    +
  • package require page::util::norm_peg ?0.1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

This package provides a single utility command which takes an AST for a +parsing expression grammar and normalizes it in various ways. The result +is called a Normalized PE Grammar Tree.

+

Note that this package can only be used from within a plugin +managed by the package page::pluginmgr.

+
+

API

+
+
::page::util::norm::peg tree
+

This command assumes the tree object contains for a +parsing expression grammar. It normalizes this tree in place. +The result is called a Normalized PE Grammar Tree.

+

The following operations are performd

+
    +

  1. The data for all terminals is stored in their grandparental +nodes. The terminal nodes and their parents are removed. Type +information is dropped.

    2. +

  2. All nodes which have exactly one child are irrelevant and are +removed, with the exception of the root node. The immediate +child of the root is irrelevant as well, and removed as well.

    3. +

  3. The name of the grammar is moved from the tree node it is stored +in to an attribute of the root node, and the tree node removed.

    +

    The node keeping the start expression separate is removed as +irrelevant and the root node of the start expression tagged with +a marker attribute, and its handle saved in an attribute of the +root node for quick access.

    4. +

  4. Nonterminal hint information is moved from nodes into attributes, +and the now irrelevant nodes are deleted.

    +

    Note: This transformation is dependent on the removal of all +nodes with exactly one child, as it removes the all 'Attribute' +nodes already. Otherwise this transformation would have to put +the information into the grandparental node.

    +

    The default mode given to the nonterminals is value.

    +

    Like with the global metadata definition specific information +is moved out out of nodes into attributes, the now irrelevant +nodes are deleted, and the root nodes of all definitions are +tagged with marker attributes. This provides us with a mapping +from nonterminal names to their defining nodes as well, which +is saved in an attribute of the root node for quick reference.

    +

    At last the range in the input covered by a definition is +computed. The left extent comes from the terminal for the +nonterminal symbol it defines. The right extent comes from +the rightmost child under the definition. While this not an +expression tree yet the location data is sound already.

    5. +

  5. The remaining nodes under all definitions are transformed +into proper expression trees. First character ranges, followed +by unary operations, characters, and nonterminals. At last the +tree is flattened by the removal of superfluous inner nodes.

    +

    The order matters, to shed as much nodes as possible early, and +to avoid unnecessary work later.

    6. +
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_peg.html Index: embedded/www/tcllib/files/modules/page/page_util_peg.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_util_peg.html +++ embedded/www/tcllib/files/modules/page/page_util_peg.html @@ -0,0 +1,213 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_util_peg(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_peg - page PEG transformation utilities

+
+ + +

Description

+

This package provides a few common operations to PEG transformations. +They assume a Normalized PE Grammar Tree as input, see the +package page::util::norm::peg, possibly augmented with +attributes coming from transformations not in conflict with the base +definition.

+
+

API

+
+
::page::util::peg::symbolNodeOf tree node
+

Given an arbitrary expression node in the AST tree it +determines the node (itself or an ancestor) containing the name of the +nonterminal symbol the node belongs to, and returns its id. The result +is either the root of the tree (for the start expression), or a +definition node.

+
::page::util::peg::symbolOf tree node
+

As ::page::util::peg::symbolNodeOf, but returns the symbol name +instead of the node.

+
::page::util::peg::updateUndefinedDueRemoval tree
+

The removal of nodes in the AST tree can cause symbols to lose +one or more users.

+
+	A used by B and C,
+	B is reachable,
+	C is not,
+	so A now loses the node in the expression for C calling it,
+	or rather, not calling it anymore.
+
+

This command updates the cross-references and which nonterminals are +now undefined.

+
::page::util::peg::flatten treequery tree
+

This commands flattens nested sequence and choice operators in the AST +tree, re-using the treeql object treequery to +run the query determining which nodes to cut.

+
::page::util::peg::getWarnings tree
+

This command looks at the attributes of the AST tree for +problems with the grammar and issues warnings. They do not prevent us +from writing the grammar, but still represent problems with it the +user should be made aware of.

+

The result of the command is a dictionary mapping nonterminal names to +their associated warnings.

+
::page::util::peg::printWarnings msg
+

The argument of the command is a dictionary mapping nonterminal names +to their associated warnings, as generated by, for example, the +command ::page::util::peg::getWarnings.

+

The warnings contained therein are formatted and then printed via the +log command page_info. This means that this command can be used +only from within a plugin managed by the package +page::pluginmgr.

+
::page::util::peg::peOf tree eroot
+

This command converts the parsing expression starting at the node +eroot in the AST tree into a nested list. The exact syntax +of this list specified by the package grammar::peg.

+
::page::util::peg::printTclExpr pe
+

This command converts the parsing expression contained in the nested +list pe into a Tcl string which can be placed into a Tcl script. +See the package grammar::peg for the exact syntax of +pe.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/page/page_util_quote.html Index: embedded/www/tcllib/files/modules/page/page_util_quote.html ================================================================== --- embedded/www/tcllib/files/modules/page/page_util_quote.html +++ embedded/www/tcllib/files/modules/page/page_util_quote.html @@ -0,0 +1,182 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

page_util_quote(n) 1.0 tcllib "Parser generator tools"

+

Name

+

page_util_quote - page character quoting utilities

+
+ + +

Description

+

This package provides a few utility commands to convert characters +into various forms.

+
+

API

+
+
::page::util::quote::unquote char
+

A character, as stored in an abstract syntax tree by a PEG processor +(See the packages grammar::peg::interpreter, +grammar::me, and their relations), i.e. in some quoted form, +is converted into the equivalent Tcl character. The character is returned +as the result of the command.

+
::page::util::quote::quote'tcl char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser, will +regenerate the character in question and is 7bit ASCII. The string is +returned as the result of this command.

+
::page::util::quote::quote'tclstr char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser and will +generate a human readable representation of the character in question. +The string is returned as the result of this command.

+

The string does not use any unprintable characters. It may use +backslash-quoting. High UTF characters are quoted to avoid problems +with the still prevalent ascii terminals. It is assumed that the +string will be used in a double-quoted environment.

+
::page::util::quote::quote'tclcom char
+

This command takes a Tcl character (internal representation) and +converts it into a string which is accepted by the Tcl parser when +used within a Tcl comment. The string is returned as the result of +this command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category page of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Page Parser Generator

+
+ +
ADDED embedded/www/tcllib/files/modules/pki/pki.html Index: embedded/www/tcllib/files/modules/pki/pki.html ================================================================== --- embedded/www/tcllib/files/modules/pki/pki.html +++ embedded/www/tcllib/files/modules/pki/pki.html @@ -0,0 +1,318 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pki(n) 0.10 tcllib "public key encryption"

+

Name

+

pki - Implementation of the public key cipher

+
+ + + +

COMMANDS

+
+
::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? input key
+

Encrypt a message using PKI (probably RSA). +Requires the caller to specify either -priv to encrypt with +the private key or -pub to encrypt with the public key. The +default option is to pad and return in hex. One of -pub or +-priv must be specified. +The -hex option causes the data to be returned in encoded as +a hexidecimal string, while the -binary option causes the data +to be returned as a binary string. If they are specified multiple +times, the last one specified is used. +The -pad option causes the data to be padded per PKCS#1 prior +to being encrypted. The -nopad inhibits this behaviour. If +they are specified multiple times, the last one specified is used. +The input to encrypt is specified as input. +The key parameter, holding the key to use, is a return value +from either +::pki::pkcs::parse_key, +::pki::x509::parse_cert, or +::pki::rsa::generate.

+

Mapping to OpenSSL's openssl application:

+
    +

  1. "openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"

    2. +

  2. "openssl rsautl -sign" == "::pki::encrypt -binary -priv"

    3. +
+
::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--? input key
+

Decrypt a message using PKI (probably RSA). See ::pki::encrypt for option handling.

+

Mapping to OpenSSL's openssl application:

+
    +

  1. "openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"

    2. +

  2. "openssl rsautl -verify" == "::pki::decrypt -binary -pub"

    3. +
+
::pki::sign input key ?algo?
+

Digitally sign message input using the private key. If algo +is ommited "sha1" is assumed. Possible values for algo include +"md5", "sha1", "sha256", and "raw". Specifyin "raw" for algo will +inhibit the building of an ASN.1 structure to encode which hashing +algorithm was chosen. +The input should be the plain text, hashing will be performed on it. +The key should include the private key.

+
::pki::verify signedmessage plaintext key ?algo?
+

Verify a digital signature using a public key. Returns true or false.

+
::pki::key key ?password? ?encodePem?
+

Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications. For RSA keys this means PKCS#1.

+
::pki::pkcs::parse_key key ?password?
+

Convert a PKCS#1 private key into a usable key, i.e. one which +can be used as argument for +::pki::encrypt, +::pki::decrypt, +::pki::sign, and +::pki::verify.

+
::pki::x509::parse_cert cert
+

Convert an X.509 certificate to a usable (public) key, i.e. one which +can be used as argument for +::pki:encrypt, +::pki::decrypt, and +::pki::verify. +The cert argument can be either PEM or DER encoded.

+
::pki::rsa::generate bitlength ?exponent?
+

Generate a new RSA key pair, the parts of which can be used as +argument for +::pki::encrypt, +::pki::decrypt, +::pki::sign, and +::pki::verify. +The bitlength argument is the length of the public key modulus. +The exponent argument should generally not be specified unless +you really know what you are doing.

+
::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
+

Verify that a trust can be found between the certificate specified in the +cert argument and one of the certificates specified in the list +of certificates in the trustedcerts argument. (Eventually the +chain can be through untrusted certificates listed in the intermediatecerts +argument, but this is currently unimplemented). +The certificates specified in the cert and trustedcerts option +should be parsed (from ::pki::x509::parse_cert).

+
::pki::x509::validate_cert cert ?-sign_message dn_of_signer? ?-encrypt_message dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl dn?
+

Validate that a certificate is valid to be used in some capacity. If +multiple options are specified they must all be met for this procedure +to return "true". +Currently, only the -sign_cert option is functional. +Arguments for the -sign_cert option are dn_to_be_signed +and ca_depth. The dn_to_be_signed is the distinguished from +the subject of a certificate to verify that the certificate specified in +the cert argument can sign. The ca_depth argument is used to +indicate at which depth the verification should be done at. Some +certificates are limited to how far down the chain they can be used to +verify a given certificate.

+
::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
+

Generate a certificate signing request from a key pair specified in +the keylist argument. +The namelist argument is a list of "name" followed by "value" +pairs to encoding as the requested distinguished name in the CSR. +The encodePem option specifies whether or not the result should +be PEM encoded or DER encoded. A "true" value results in the result +being PEM encoded, while any other value 9results in the the result +being DER encoded. DER encoding is the default. +The algo argument specifies the hashing algorithm we should use +to sign this certificate signing request with. The default is "sha1". +Other possible values include "md5" and "sha256".

+
::pki::pkcs::parse_csr csr
+

Parse a Certificate Signing Request. The csr argument can be +either PEM or DER encoded.

+
::pki::x509::create_cert signreqlist cakeylist serial_number notBefore notAfter isCA extensions ?encodePem? ?algo?
+

Sign a signing request (usually from ::pki::pkcs::create_csr or +::pki::pkcs::parse_csr) with a Certificate Authority (CA) certificate. +The signreqlist argument should be the parsed signing request. +The cakeylist argument should be the parsed CA certificate. +The serial_number argument should be a serial number unique to +this certificate from this certificate authority. +The notBefore and notAfter arguments should contain the +time before and after which (respectively) the certificate should +be considered invalid. The time should be encoded as something +clock format will accept (i.e., the results of clock seconds +and clock add). +The isCA argument is a boolean argumen describing whether or not +the signed certificate should be a a CA certificate. If specified as +true the "id-ce-basicConstraints" extension is added with the arguments +of "critical" being true, "allowCA" being true, and caDepth being +-1 (infinite). +The extensions argument is a list of extensions and their parameters +that should be encoded into the created certificate. Currently only one +extension is understood ("id-ce-basicConstraints"). It accepts three +arguments critical allowCA caDepth. The critical +argument to this extension (and any extension) whether or not the +validator should reject the certificate as invalid if it does not +understand the extension (if set to "true") or should ignore the extension +(if set to "false"). The allowCA argument is used to specify +as a boolean value whether or not we can be used a certificate +authority (CA). The caDepth argument indicates how many children +CAs can be children of this CA in a depth-wise fashion. A value of "0" +for the caDepth argument means that this CA cannot sign a CA +certificate and have the result be valid. A value of "-1" indicates +infinite depth.

+
+
+

EXAMPLES

+
+
+
+
+
+

REFERENCES

+
    +
  1. +
+
+

AUTHORS

+

Roy Keene

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rsa of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html Index: embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html ================================================================== --- embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html +++ embedded/www/tcllib/files/modules/pluginmgr/pluginmgr.html @@ -0,0 +1,414 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pluginmgr(n) 0.3 tcllib "Plugin management"

+

Name

+

pluginmgr - Manage a plugin

+
+ + +

Description

+

This package provides commands and objects for the generic management +of plugins which can be loaded into an application.

+

To avoid the implementation of yet another system to locate Tcl code +the system provides by this package is built on top of the regular +package management system. Each plugin is considered as a package and +a simple invokation of package require is enough to locate and +load it, if it exists. The only time we will need additional paths is +when a plugin manager is part of a wrapped application and has to be +able to search for plugins existing outside of that application. For +this situation the package provides a command to create a general set +of such paths based on names for the plugin manager and/or application +in question.

+

The main contribution of this package is a generic framework which +allows the easy declaration of

+
    +

  1. How to translate a plugin name to the name of the package implementing +it, and vice versa.

    2. +

  2. The list of commands a plugin has to provide as API, and also of more +complex checks as code.

    3. +

  3. The list of commands expected by the plugin from the environment.

    4. +
+

This then allows the easy generation of plugin managers customized to +particular types of plugins for an application.

+

It should be noted that all plugin code is considered untrusted and +will always be executed within a safe interpreter. The interpreter is +enabled enough to allow plugins the loading of all additional packages +they may need.

+
+

PUBLIC API

+

PACKAGE COMMANDS

+
+
::pluginmgr objectName ?option value...?
+

This command creates a new plugin manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections OBJECT COMMAND +and OBJECT METHODS. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+

The options and their values coming after the name of the object are +used to set the initial configuration of the mamager object, +specifying the applicable plugins and their API.

+
::pluginmgr::paths objectName name...
+

This utility command adds a set of paths to the specified object, +based on the given names. +It will search for:

+
    +

  1. The environment variable name_PLUGINS. Its contents will +be interpreted as a list of package paths. The entries have to be +separated by either : (unix) or ; (windows).

    +

    The name will be converted to upper-case letters.

    2. +

  2. The registry entry "HKEY_LOCAL_MACHINE\SOFTWARE\name\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by ;. This item is considered +only when on Windows (tm).

    +

    The casing of letters is not changed.

    3. +

  3. The registry entry "HKEY_CURRENT_USER\SOFTWARE\name\PLUGINS". +Its contents will be interpreted as a list of package paths. The +entries have to be separated by ;. This item is considered +only when on Windows (tm).

    +

    The casing of letters is not changed.

    4. +

  4. The directory "~/.name/plugin".

    5. +

  5. The directory "~/.name/plugins".

    +

    The casing of letters is not changed.

    6. +
+

and add all the paths found that way to the list of package paths +maintained by the object.

+

If name is namespaced each item in the list will be repeated per +prefix of name, with conversion of :-sequences into the proper +separator (underscore for environment variables, backslash for +registry entries, and / for directories).

+

Examples:

+
+    ::pluginmgr::paths ::obj docidx
+    => env  DOCIDX_PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\docidx\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\docidx\PLUGINS
+       path ~/.docidx/plugins
+    ::pluginmgr::paths ::obj doctools::idx
+    => env  DOCTOOLS_PLUGINS
+       env  DOCTOOLS_IDX_PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\PLUGINS
+       reg  HKEY_LOCAL_MACHINE\SOFTWARE\doctools\idx\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\doctools\PLUGINS
+       reg  HKEY_CURRENT_USER\SOFTWARE\doctools\idx\PLUGINS
+       path ~/.doctools/plugin
+       path ~/.doctools/idx/plugin
+
+
+
+
+

OBJECT COMMAND

+

All commands created by the command ::pluginmgr (See section +PACKAGE COMMANDS) have the following general form and may +be used to invoke various operations on their plugin manager object.

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the exact +behavior of the command. See section OBJECT METHODS for +the detailed specifications.

+
+
+

OBJECT METHODS

+
+
objectName clone
+

This method creates a new plugin management object and returns the +associated object command. The generated object is a clone of the +object the method was invoked on. I.e. the new object will have the +same configuration as the current object. With regard to state, if the +current object has a plugin loaded then this plugin and all associated +state is moved to the generated clone and the current object is reset +into the base state (no plugin loaded). In this manner a configured +plugin manager is also a factory for loaded plugins.

+
objectName configure
+

The method returns a list of all known options and their current +values when called without any arguments.

+
objectName configure option
+

The method behaves like the method cget when called with a +single argument and returns the value of the option specified by said +argument.

+
objectName configure -option value...
+

The method reconfigures the specified options of the object, +setting them to the associated values, when called with an even +number of arguments, at least two.

+

The legal options are described in the section +OBJECT CONFIGURATION.

+
objectName cget -option
+

This method expects a legal configuration option as argument and will +return the current value of that option for the object the method was +invoked for.

+

The legal configuration options are described in section +OBJECT CONFIGURATION.

+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName do arg...
+

This method interprets its list of arguments as the words of a command +and invokes this command in the execution context of the plugin. +The result of the invoked command is made the result of the method. +The call will fail with an error if no valid plugin has been loaded +into the manager object.

+
objectName interpreter
+

This method returns the handle of the safe interpreter the current +plugin is loaded into. An empty string as return value signals that +the manager currently has no valid plugin loaded.

+
objectName plugin
+

This method returns the name of the plugin currently loaded. An empty +string as return value signals that the manager currently has no valid +plugin loaded.

+
objectName load string
+

This method loads, validates, and initializes a named plugin into the +manager object.

+

The algorithm to locate and load the plugin employed is:

+
    +

  1. If the string contains the path to an existing file then this +file is taken as the implementation of the plugin.

    2. +

  2. Otherwise the plugin name is translated into a package name via the value +of the option -pattern and then loaded through the +regular package management.

    3. +

  3. The load fails.

    4. +
+

The algorithm to validate and initialize the loaded code is:

+
    +

  1. If the option -api is non-empty introspection commands are +used to ascertain that the plugin provides the listed commands.

    2. +

  2. If the option -check is non-empty the specified command +prefix is called.

    3. +

  3. If either of the above fails the candidate plugin is unloaded again

    4. +

  4. Otherwise all the commands specified via the option +-cmds are installed in the plugin.

    5. +
+

A previously loaded plugin is discarded, but only if the new plugin +was found and sucessfully validated and initialized. Note that there +will be no intereference between old and new plugin as both will be +put into separate safe interpreters.

+
objectName unload
+

This method unloads the currently loaded plugin. It returns the empty +string. The call will be silently ignored if no plugin is loaded at +all.

+
objectName list
+

This method uses the contents of the option -pattern to find +all packages which can be plugins under the purview of this manager +object. It translates their names into plugin names and returns a list +containing them.

+
objectName path path
+

This methods adds the specified path to the list of additional +package paths to look at when searching for a plugin. It returns the +empty string. Duplicate paths are ignored, i.e. each path is added +only once. Paths are made absolute, but are not normalized.

+
objectName paths
+

This method returns a list containing all additional paths which have +been added to the plugin manager object since its creation.

+
+
+

OBJECT CONFIGURATION

+

All plugin manager objects understand the following configuration options:

+
+
-pattern string
+

The value of this option is a glob pattern which has to contain +exactly one '*'-operator. All packages whose names match this pattern +are the plugins recognized by the manager object. And vice versa, the +replacement of the '*'-operator with a plugin name will yield the name +of the package implementing that plugin.

+

This option has no default, except if option -name was set. +It has to be set before attempting to load a plugin, either directly, +or through option -name.

+
-api list
+

The value of this option is a list of command names, and any plugin +loaded has to provide these commands. Names which are not fully +qualified are considered to be rooted in the global namespace. +If empty no expectations are made on the plugin. The default value is +the empty list.

+
-check cmdprefix
+

The value of this option is interpreted as a command prefix. +Its purpose is to perform complex checks on a loaded plugin package to +validate it, which go beyond a simple list of provided commands.

+

It is called with the manager object command as the only argument and +has to return a boolean value. A value of true will be +interpreted to mean that the candidate plugin passed the test. +The call will happen if and only if the candidate plugin already +passed the basic API check specified through the option -api.

+

The default value is the empty list, which causes the manager object +to suppress the call and to assume the candidate plugin passes.

+
-cmds dict
+

The value of this option is a dictionary. It specifies the commands +which will be made available to the plugin (as keys), and the trusted +commands in the environment which implement them (as values). +The trusted commands will be executed in the interpreter specified by +the option -cmdip. +The default value is the empty dictionary.

+
-cmdip ipspec
+

The value of this option is the path of the interpreter where the +trusted commands given to the plugin will be executed in. +The default is the empty string, referring to the current interpreter.

+
-setup cmdprefix
+

The value of this option is interpreted as a command prefix.

+

It is called whenever a new safe interpreter for a plugin has been +created, but before a plugin is loaded. It is provided with the +manager object command and the interpreter handle as its only +arguments. Any return value will be ignored.

+

Its purpose is give a user of the plugin management the ability to +define commands, packages, etc. a chosen plugin may need while being +loaded.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pluginmgr of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/png/png.html Index: embedded/www/tcllib/files/modules/png/png.html ================================================================== --- embedded/www/tcllib/files/modules/png/png.html +++ embedded/www/tcllib/files/modules/png/png.html @@ -0,0 +1,248 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

png(n) 0.1.2 tcllib "Image manipulation"

+

Name

+

png - PNG querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query and modify PNG images. PNG +stands for Portable Network Graphics and is specified at +http://www.libpng.org/pub/png/spec/1.2.

+
+

COMMANDS

+
+
::png::validate file
+

Returns a value indicating if file is a valid PNG file. The file +is checked for PNG signature, each chunks checksum is verified, +existence of a data chunk is verified, first chunk is checked for +header, last chunk is checked for ending. Things not checked +for are: validity of values within a chunk, multiple header chunks, +noncontiguous data chunks, end chunk before actual eof. This procedure +can take lots of time.

+

Possible return values:

+
+
OK
+

File is a valid PNG file.

+
SIG
+

no/broken PNG signature.

+
BADLEN
+

corrupt chunk length.

+
EOF
+

premature end of file.

+
NOHDR
+

missing header chunk.

+
CKSUM
+

crc mismatch.

+
NODATA
+

missing data chunk(s).

+
NOEND
+

missing end marker.

+
+
::png::isPNG file
+

Returns a boolean value indicating if the file file starts with +a PNG signature. This is a much faster and less intensive check than +::png::validate as it does not check if the PNG data is valid.

+
::png::imageInfo file
+

Returns a dictionary with keys width, height, +depth, color, compression, filter, and +interlace. The values are the associated properties of the PNG +image in file. +Throws an error if file is not a PNG image, or if the checksum of the +header is invalid. For information on interpreting the values for the +returned properties see +http://www.libpng.org/pub/png/spec/1.2/PNG-Chunks.html.

+
::png::getTimestamp file
+

Returns the epoch time if a timestamp chunk is found in the PNG image +contained in the file, otherwise returns the empty string. Does +not attempt to verify the checksum of the timestamp chunk. +Throws an error if the file is not a valid PNG image.

+
::png::setTimestamp file time
+

Writes a new timestamp to the file, either replacing the old +timestamp, or adding one just before the data chunks if there was no +previous timestamp. time is the new time in the gmt epoch +format. +Throws an error if file is not a valid PNG image.

+
::png::getComments file
+

Currently supports only uncompressed comments. Does not attempt to +verify the checksums of the comment chunks. Returns a list where each +element is a comment. Each comment is itself a list. The list for a +plain text comment consists of 2 elements: the human readable keyword, +and the text data. A unicode (international) comment consists of 4 +elements: the human readable keyword, the language identifier, the +translated keyword, and the unicode text data. +Throws an error if file is not a valid PNG image.

+
::png::removeComments file
+

Removes all comments from the PNG image in file. Beware - This +uses memory equal to the file size minus comments, to hold the +intermediate result. +Throws an error if file is not a valid PNG image.

+
::png::addComment file keyword text
+

Adds a plain text comment to the PNG image in file, just +before the first data chunk. Will throw an error if no data chunk is +found. keyword has to be less than 80 characters long to conform +to the PNG specification.

+
::png::addComment file keyword lang keyword2 text
+

Adds a unicode (international) comment to the PNG image in file, +just before the first data chunk. Will throw an error if no data chunk +is found. keyword has to be less than 80 characters long to +conform to the PNG specification. keyword2 is the translated +keyword, in the language specified by the language identifier +lang.

+
::png::image file
+

Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor.

+
::png::write file data
+

Takes a list of scanlines in the Tk_GetColor format and writes the represented image +to file.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category png of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3/pop3.html Index: embedded/www/tcllib/files/modules/pop3/pop3.html ================================================================== --- embedded/www/tcllib/files/modules/pop3/pop3.html +++ embedded/www/tcllib/files/modules/pop3/pop3.html @@ -0,0 +1,342 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pop3(n) 1.9 tcllib "Tcl POP3 Client Library"

+

Name

+

pop3 - Tcl client for POP3 email protocol

+
+ + +

Description

+

The pop3 package provides a simple Tcl-only client library +for the POP3 email protocol as specified in +RFC 1939. +It works by opening the standard POP3 socket on the server, +transmitting the username and password, then providing a Tcl API to +access the POP3 protocol commands. All server errors are returned as +Tcl errors (thrown) which must be caught with the Tcl catch +command.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

API

+
+
::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? ?-stls 0|1? ?-tls-callback stls-callback-command? host username password ?port?
+

Open a socket connection to the server specified by host, +transmit the username and password as login information to +the server. The default port number is 110, which can be +overridden using the optional port argument. The return value +is a channel used by all of the other ::pop3 functions.

+

The command recognizes three options

+
+
-msex boolean
+

Setting this option tells the package that the server we are talking +to is an MS Exchange server (which has some oddities we have to work +around). The default is False.

+
-retr-mode retr|list|slow
+

The retrieval mode determines how exactly messages are read from the +server. +The allowed values are retr, list and slow. +The default is retr. See ::pop3::retrieve for more +information.

+
-socketcmd cmdprefix
+

This option allows the user to overide the use of the builtin +socket command with any API-compatible command. The envisioned +main use is the securing of the new connection via SSL, through the +specification of the command tls::socket. This command is +specially recognized as well, changing the default port of the +connection to 995.

+
-stls boolean
+

Setting this option tells the package to secure the connection using +SSL or TLS. It performs STARTTLS as described in IETF RFC 2595, it +first opens a normal, unencrypted connection and then negotiates a +SSLv3 or TLSv1 connection. If the connection cannot be secured, the +connection will be closed and an error will be returned

+
-tls-callback stls-callback-command
+

This option allows the user to overide the tls::callback used during +the -stls SSL/TLS handshake. See the TLS manual for details on how +to implement this callback.

+
+
::pop3::config chan
+

Returns the configuration of the pop3 connection identified by the +channel handle chan as a serialized array.

+
::pop3::status chan
+

Query the server for the status of the mail spool. The status is +returned as a list containing two elements, the first is the number of +email messages on the server and the second is the size (in octets, 8 +bit blocks) of the entire mail spool.

+
::pop3::last chan
+

Query the server for the last email message read from the spool. This +value includes all messages read from all clients connecting to the +login account. This command may not be supported by the email server, +in which case the server may return 0 or an error.

+
::pop3::retrieve chan startIndex ?endIndex?
+

Retrieve a range of messages from the server. If the endIndex +is not specified, only one message will be retrieved. The return +value is a list containing each message as a separate element. See +the startIndex and endIndex descriptions below.

+

The retrieval mode determines how exactly messages are read from the +server. The mode retr assumes that the RETR command delivers +the size of the message as part of the command status and uses this to +read the message efficiently. In mode list RETR does not +deliver the size, but the LIST command does and we use this to +retrieve the message size before the actual retrieval, which can then +be done efficiently. In the last mode, slow, the system is +unable to obtain the size of the message to retrieve in any manner and +falls back to reading the message from the server line by line.

+

It should also be noted that the system checks upon the configured +mode and falls back to the slower modes if the above assumptions are +not true.

+
::pop3::delete chan startIndex ?endIndex?
+

Delete a range of messages from the server. If the endIndex is +not specified, only one message will be deleted. Note, the indices +are not reordered on the server, so if you delete message 1, then the +first message in the queue is message 2 (message index 1 is no longer +valid). See the startIndex and endIndex descriptions +below.

+
+
startIndex
+

The startIndex may be an index of a specific message starting +with the index 1, or it have any of the following values:

+
+
start
+

This is a logical value for the first message in the spool, equivalent +to the value 1.

+
next
+

The message immediately following the last message read, see +::pop3::last.

+
end
+

The most recent message in the spool (the end of the spool). This is +useful to retrieve only the most recent message.

+
+
endIndex
+

The endIndex is an optional parameter and defaults to the value +"-1", which indicates to only retrieve the one message specified by +startIndex. If specified, it may be an index of a specific +message starting with the index "1", or it may have any of the +following values:

+
+
last
+

The message is the last message read by a POP3 client, see +::pop3::last.

+
end
+

The most recent message in the spool (the end of the spool).

+
+
+
::pop3::list chan ?msg?
+

Returns the scan listing of the mailbox. If parameter msg is +given, then the listing only for that message is returned.

+
::pop3::top chan msg n
+

Optional POP3 command, not all servers may support this. +::pop3::top retrieves headers of a message, specified by +parameter msg, and number of n lines from the message +body.

+
::pop3::uidl chan ?msg?
+

Optional POP3 command, not all servers may support this. +::pop3::uidl returns the uid listing of the mailbox. If the +parameter msg is specified, then the listing only for that +message is returned.

+
::pop3::capa chan
+

Optional POP3 command, not all servers may support this. +::pop3::capa returns a list of the capabilities of the server. +TOP, SASL, UIDL, LOGIN-DELAY and STLS are typical capabilities. +See IETF RFC 2449.

+
::pop3::close chan
+

Gracefully close the connect after sending a POP3 QUIT command down +the socket.

+
+
+

Secure mail transfer

+

A pop3 connection can be secured with SSL/TLS by requiring the package +TLS and then using either the option -socketcmd or +the option -stls of the command pop3::open. +The first method, option -socketcmd, will force the use +of the tls::socket command when opening the connection. This is +suitable for POP3 servers which expect SSL connections only. These will +generally be listening on port 995.

+
+	package require tls
+	tls::init -cafile /path/to/ca/cert -keyfile ...
+	# Create secured pop3 channel
+	pop3::open -socketcmd tls::socket \\
+		$thehost $theuser $thepassword
+	...
+
+

The second method, option -stls, will connect to the standard POP3 +port and then perform an STARTTLS handshake. This will only work for POP3 +servers which have this capability. The package will confirm that the +server supports STARTTLS and the handshake was performed correctly before +proceeding with authentication.

+
+	package require tls
+	tls::init -cafile /path/to/ca/cert -keyfile ...
+	# Create secured pop3 channel
+	pop3::open -stls 1 \\
+		$thehost $theuser $thepassword
+	...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d.html ================================================================== --- embedded/www/tcllib/files/modules/pop3d/pop3d.html +++ embedded/www/tcllib/files/modules/pop3d/pop3d.html @@ -0,0 +1,335 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pop3d(n) 1.1.0 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d - Tcl POP3 server implementation

+
+ + +

Description

+
+
::pop3d::new ?serverName?
+

This command creates a new server object with an associated global Tcl +command whose name is serverName.

+
+

The command serverName may be used to invoke various operations +on the server. It has the following general form:

+
+
serverName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A pop3 server can be started on any port the caller has permission for +from the operating system. The default port will be 110, which is the +port defined by the standard specified in +RFC 1939 (http://www.rfc-editor.org/rfc/rfc1939.txt). +After creating, configuring and starting a the server object will +listen for and accept connections on that port and handle them +according to the POP3 protocol.

+

Note: The server provided by this module will handle only the +basic protocol by itself. For the higher levels of user authentication +and handling of the actual mailbox contents callbacks will be invoked.

+

The following commands are possible for server objects:

+
+
serverName up
+

After this call the server will listen for connections on its configured port.

+
serverName down
+

After this call the server will stop listening for connections. This +does not affect existing connections.

+
serverName destroy ?mode?
+

Destroys the server object. Currently open connections are handled +depending on the chosen mode. +The provided modes are:

+
+
kill
+

Destroys the server immediately, and forcefully closes all currently +open connections. This is the default mode.

+
defer
+

Stops the server from accepting new connections and will actually +destroy it only after the last of the currently open connections for +the server is closed.

+
+
serverName configure
+

Returns a list containing all options and their current values in a +format suitable for use by the command array set. The options +themselves are described in section Options.

+
serverName configure -option
+

Returns the current value of the specified option. This is an alias +for the method cget. The options themselves are described in +section Options.

+
serverName configure -option value...
+

Sets the specified option to the provided value. The options +themselves are described in section Options.

+
serverName cget -option
+

Returns the current value of the specified option. The options +themselves are described in section Options.

+
serverName conn list
+

Returns a list containing the ids of all connections currently open.

+
serverName conn state id
+

Returns a list suitable for [array set] containing the +state of the connection referenced by id.

+
+
+

Options

+

The following options are available to pop3 server objects.

+
+
-port port
+

Defines the port to listen on for new connections. Default is +110. This option is a bit special. If port is set to "0" the +server, or rather the operating system, will select a free port on its +own. When querying -port the id of this chosen port will be +returned. Changing the port while the server is up will neither change +the returned value, nor will it change on which port the server is +listening on. Only after resetting the server via a call to +down followed by a call to up will the new port take +effect. It is at that time that the value returned when querying +-port will change too.

+
-auth command
+

Defines a command prefix to call whenever the authentication of +a user is required. If no such command is specified the server will +reject all users. The interface which has to be provided by the +command prefix is described in section Authentication.

+
-storage command
+

Defines a command prefix to call whenever the handling of +mailbox contents is required. If no such command is specified the +server will claim that all mailboxes are empty. The interface which +has to be provided by the command prefix is described in section +Mailboxes.

+
-socket command
+

Defines a command prefix to call for opening the listening socket. +This can be used to make the pop3 server listen on a SSL socket +as provided by the tls package, see the command tls::socket.

+
+
+

Authentication

+

Here we describe the interface which has to be provided by the +authentication callback so that pop3 servers following the interface +of this module are able to use it.

+
+
authCmd exists name
+

This method is given a username and has to return a boolean +value telling whether or not the specified user exists.

+
authCmd lookup name
+

This method is given a username and has to return a two-element +list containing the password for this user and a storage reference, in +this order.

+

The storage reference is passed unchanged to the storage callback, see +sections Options and Mailboxes for either the +option defining it and or the interface to provide, respectively.

+
+
+

Mailboxes

+

Here we describe the interface which has to be provided by the storage +callback so that pop3 servers following the interface of this module +are able to use it. The mbox argument is the storage reference +as returned by the lookup method of the authentication +command, see section Authentication.

+
+
storageCmd dele mbox msgList
+

] +Deletes the messages whose numeric ids are contained in the +msgList from the mailbox specified via mbox.

+
storageCmd lock mbox
+

This method locks the specified mailbox for use by a single connection +to the server. This is necessary to prevent havoc if several +connections to the same mailbox are open. The complementary method is +unlock. The command will return true if the lock could be set +successfully or false if not.

+
storageCmd unlock mbox
+

This is the complementary method to lock, it revokes the lock +on the specified mailbox.

+
storageCmd size mbox ?msgId?
+

Determines the size of the message specified through its id in +msgId, in bytes, and returns this number. The command will +return the size of the whole maildrop if no message id was specified.

+
storageCmd stat mbox
+

Determines the number of messages in the specified mailbox and returns +this number.

+
storageCmd get mbox msgId
+

Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package mime. The pop3 server will use the functionality of +the mime token to send the mail to the requestor at the other end of a +pop3 connection.

+
+
+

Secure mail transfer

+

The option -socket (see Options) enables users of +the package to override how the server opens its listening socket. +The envisioned main use is the specification of the tls::socket +command, see package tls, to secure the communication.

+
+	package require tls
+	tls::init \\
+		...
+	pop3d::new S -socket tls::socket
+	...
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html ================================================================== --- embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html +++ embedded/www/tcllib/files/modules/pop3d/pop3d_dbox.html @@ -0,0 +1,254 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pop3d::dbox(n) 1.0.2 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d::dbox - Simple mailbox database for pop3d

+
+ + +

Description

+

The package pop3d::dbox provides simple/basic mailbox +management facilities. Each mailbox object manages a single base +directory whose subdirectories represent the managed mailboxes. Mails +in a mailbox are represented by files in a mailbox directory, where +each of these files contains a single mail, both headers and body, in +RFC 822 (http://www.rfc-editor.org/rfc/rfc822.txt) conformant +format.

+

Any mailbox object following the interface described below can be used +in conjunction with the pop3 server core provided by the package +pop3d. It is especially possible to directly use the objects +created by this package in the storage callback of pop3 servers +following the same interface as servers created by the package +pop3d.

+
+
::pop3d::dbox::new ?dbName?
+

This command creates a new database object with an associated global +Tcl command whose name is dbName.

+
+

The command dbName may be used to invoke various operations on +the database. It has the following general form:

+
+
dbName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for database objects:

+
+
dbName destroy
+

Destroys the mailbox database and all transient data. The directory +associated with the object is not destroyed.

+
dbName base base
+

Defines the base directory containing the mailboxes to manage. If this +method is not called none of the following methods will work.

+
dbName add mbox
+

Adds a mailbox of name mbox to the database. The name must be a +valid path component.

+
dbName remove mbox
+

Removes the mailbox specified through mbox, and the mails +contained therein, from the database. This method will fail if the +specified mailbox is locked.

+
dbName move old new
+

Changes the name of the mailbox old to new.

+
dbName list
+

Returns a list containing the names of all mailboxes in the directory +associated with the database.

+
dbName exists mbox
+

Returns true if the mailbox with name mbox exists in the +database, or false if not.

+
dbName locked mbox
+

Checks if the mailbox specified through mbox is currently locked.

+
dbName lock mbox
+

This method locks the specified mailbox for use by a single connection +to the server. This is necessary to prevent havoc if several +connections to the same mailbox are open. The complementary method is +unlock. The command will return true if the lock could be set +successfully or false if not.

+
dbName unlock mbox
+

This is the complementary method to lock, it revokes the lock +on the specified mailbox.

+
dbName stat mbox
+

Determines the number of messages in the specified mailbox and returns +this number. This method fails if the mailbox mbox is not +locked.

+
dbName size mbox ?msgId?
+

Determines the size of the message specified through its id in +msgId, in bytes, and returns this number. The command will +return the size of the whole maildrop if no message id was specified. +If specified the msgId has to be in the range "1 ... [dbName stat]" +or this call will fail. If stat was not called before this +call, size will assume that there are zero messages in the +mailbox.

+
dbName dele mbox msgList
+

Deletes the messages whose numeric ids are contained in the +msgList from the mailbox specified via mbox. +The msgList must not be empty or this call will fail. +The numeric ids in msgList have to be in the range "1 ... +[dbName stat]" or this +call will fail. If stat was not called +before this call, dele will assume +that there are zero messages in the mailbox.

+
storageCmd get mbox msgId
+

Returns a handle for the specified message. This handle is a mime +token following the interface described in the documentation of +package mime. The token is read-only. In other +words, the caller is allowed to do anything with the token except to +modify it. +The msgId has to be in the range "1 ... +[dbName stat]" or this +call will fail. If stat was not called +before this call, get will assume +that there are zero messages in the mailbox.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html Index: embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html ================================================================== --- embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html +++ embedded/www/tcllib/files/modules/pop3d/pop3d_udb.html @@ -0,0 +1,213 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pop3d::udb(n) 1.0.1 tcllib "Tcl POP3 Server Package"

+

Name

+

pop3d::udb - Simple user database for pop3d

+
+ + +

Description

+

The package pop3d::udb provides simple in memory databases +which can be used in conjunction with the pop3 server core provided by +the package pop3d. The databases will use the names of users +as keys and associates passwords and storage references with them.

+

Objects created by this package can be directly used in the +authentication callback of pop3 servers following the same interface +as servers created by the package pop3d.

+
+
::pop3d::udb::new ?dbName?
+

This command creates a new database object with an associated global +Tcl command whose name is dbName.

+
+

The command dbName may be used to invoke various operations on +the database. It has the following general form:

+
+
dbName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for database objects:

+
+
dbName destroy
+

Destroys the database object.

+
dbName add user pwd storage
+

Add a new user or changes the data of an existing user. Stores +password and storage reference for the given user.

+
dbName remove user
+

Removes the specified user from the database.

+
dbName rename user newName
+

Changes the name of the specified user to newName.

+
dbName lookup user
+

Searches the database for the specified user and returns a +two-element list containing the associated password and storage +reference, in this order. Throws an error if the user could not be +found. This is the interface as expected by the authentication +callback of package pop3d.

+
dbName exists user
+

Returns true if the specified user is known to the database, +else false.

+
dbName who
+

Returns a list of users known to the database.

+
dbName save ?file?
+

Saves the contents of the database into the given file. If the +file is not specified the system will use the path last used in a call +to dbName read. The generated file can be read by the +read method.

+
dbName read file
+

Reads the specified file and adds the contained user definitions +to the database. As the file is actually source'd a safe +interpreter is employed to safeguard against malicious code. This +interpreter knows the add command for adding users and their +associated data to this database. This command has the same argument +signature as the method add. The path of the file is +remembered internally so that it can be used in the next call of +dbName save without an argument.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pop3d of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/practcl/practcl.html Index: embedded/www/tcllib/files/modules/practcl/practcl.html ================================================================== --- embedded/www/tcllib/files/modules/practcl/practcl.html +++ embedded/www/tcllib/files/modules/practcl/practcl.html @@ -0,0 +1,186 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

practcl(n) 0.1 tcllib "The The Proper Rational API for C to Tool Command Language Module"

+

Name

+

practcl - The Practcl Module

+
+ + +

Description

+

The Practcl module is a tool for integrating large modules for C API +Tcl code that requires custom Tcl types and TclOO objects.

+
+

COMMANDS

+
+
CPUTS varname body ?body...?
+

Appends blocks of text to a buffer. This command tries to reduce the number +of line breaks between bodies.

+
practcl::_isdirectory path
+

Returns true if path is a directory, using the test

+
+
+
practcl::object parent ?keyvaluelist?
+

A generic Practcl object

+
practcl::library ?keyvaluelist?
+

A Practcl object representing a library container

+
practcl::exe ?keyvaluelist?
+

A Practcl object representing a wrapped executable

+
practcl::product parent ?keyvaluelist?
+

A Practcl object representing a compiled product

+
practcl::cheader parent ?keyvaluelist?
+

A Practcl object representing an externally generated c header

+
practcl::csource parent ?keyvaluelist?
+

A Practcl object representing an externally generated c source file

+
practcl::module parent ?keyvaluelist?
+

A Practcl object representing a dynamically generated C/H/Tcl suite

+
practcl::submodule parent ?keyvaluelist?
+

A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category practcl of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

TclOO

+
+ +
ADDED embedded/www/tcllib/files/modules/processman/processman.html Index: embedded/www/tcllib/files/modules/processman/processman.html ================================================================== --- embedded/www/tcllib/files/modules/processman/processman.html +++ embedded/www/tcllib/files/modules/processman/processman.html @@ -0,0 +1,190 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

processman(n) 0.1 tcllib "processman"

+

Name

+

processman - Tool for automating the period callback of commands

+
+ + +

Description

+

The processman package provides a Pure-tcl set of utilities +to manage child processes in a platform-generic nature.

+
+

Commands

+
+
::processman::find_exe name
+

Locate an executable by the name of name in the system path. On windows, +also add the .exe extention if not given.

+
::processman::kill id
+

Kill a child process id.

+
::processman::kill_all
+

Kill all processes spawned by this program

+
::processman::killexe name
+

Kill a process identified by the executable. On Unix, this triggers a killall. +On windows, twapi::get_process_ids is used to map a name one or more IDs, +which are then killed.

+
::processman::onexit id cmd
+

Arrange to execute the script cmd when this programe detects that +process id as terminated.

+
::processman::priority id level
+

Mark process id with the priorty level. Valid levels: low, high, default.

+

On Unix, the process is tagged using the nice command.

+

On Windows, the process is modifed via the twapi::set_priority_class

+
::processman::process_list
+

Return a list of processes that have been triggered by this program, as +well as a boolean flag to indicate if the process is still running.

+
::processman::process_list id
+

Return true if process id is still running, false otherwise.

+
::processman::spawn id cmd args
+

Start a child process, identified by id. cmd is the name +of the command to execute. args are arguments to pass to that command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category odie of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

System

+
+ +
ADDED embedded/www/tcllib/files/modules/profiler/profiler.html Index: embedded/www/tcllib/files/modules/profiler/profiler.html ================================================================== --- embedded/www/tcllib/files/modules/profiler/profiler.html +++ embedded/www/tcllib/files/modules/profiler/profiler.html @@ -0,0 +1,218 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

profiler(n) 0.3 tcllib "Tcl Profiler"

+

Name

+

profiler - Tcl source code profiler

+
+ + +

Description

+

The profiler package provides a simple Tcl source code +profiler. It is a function-level profiler; that is, it collects only +function-level information, not the more detailed line-level +information. It operates by redefining the Tcl proc command. +Profiling is initiated via the ::profiler::init command.

+
+

COMMANDS

+
+
::profiler::init
+

Initiate profiling. All procedures created after this command is +called will be profiled. To profile an entire application, this +command must be called before any other commands.

+
::profiler::dump pattern
+

Dump profiling information for the all functions matching +pattern. If no pattern is specified, information for all +functions will be returned. The result is a list of key/value pairs +that maps function names to information about that function. The +information about each function is in turn a list of key/value pairs. +The keys used and their values are:

+
+
totalCalls
+

The total number of times functionName was called.

+
callerDist
+

A list of key/value pairs mapping each calling function that called +functionName to the number of times it called +functionName.

+
compileTime
+

The runtime, in clock clicks, of functionName the first time +that it was called.

+
totalRuntime
+

The sum of the runtimes of all calls of functionName.

+
averageRuntime
+

Average runtime of functionName.

+
descendantTime
+

Sum of the time spent in descendants of functionName.

+
averageDescendantTime
+

Average time spent in descendants of functionName.

+
+
::profiler::print ?pattern?
+

Print profiling information for all functions matching pattern. +If no pattern is specified, information about all functions will be +displayed. The return result is a human readable display of the +profiling information.

+
::profiler::reset ?pattern?
+

Reset profiling information for all functions matching pattern. +If no pattern is specified, information will be reset for all +functions.

+
::profiler::suspend ?pattern?
+

Suspend profiling for all functions matching pattern. If no +pattern is specified, profiling will be suspended for all +functions. It stops gathering profiling information after this command +is issued. However, it does not erase any profiling information that +has been gathered previously. Use resume command to re-enable +profiling.

+
::profiler::resume ?pattern?
+

Resume profiling for all functions matching pattern. If no +pattern is specified, profiling will be resumed for all functions. +This command should be invoked after suspending the profiler in the +code.

+
::profiler::sortFunctions key
+

Return a list of functions sorted by a particular profiling statistic. +Supported values for key are: calls, +exclusiveTime, compileTime, nonCompileTime, +totalRuntime, avgExclusiveTime, and +avgRuntime. The return result is a list of lists, where each +sublist consists of a function name and the value of key for +that function.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category profiler of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/pt/pt_astree.html Index: embedded/www/tcllib/files/modules/pt/pt_astree.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_astree.html +++ embedded/www/tcllib/files/modules/pt/pt_astree.html @@ -0,0 +1,344 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::ast(n) 1.1 tcllib "Parser Tools"

+

Name

+

pt::ast - Abstract Syntax Tree Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +abstract syntax trees as managed by the Parser Tools, and specified in +section AST serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::ast verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of an abstract syntax tree and will throw an error if +that is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +AST serialization format.

+
::pt::ast verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of an abstract syntax tree and will +throw an error if that is not the case. The result of the command is +the empty string.

+

For the specification of canonical serializations see the section +AST serialization format.

+
::pt::ast canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of an abstract syntax and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of the contained tree and return it as its result. If the input is +already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section AST serialization format.

+
::pt::ast print serial
+

This command assumes that the argument serial contains a valid +serialization of an abstract syntax tree and returns a string +containing that tree in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +AST serialization format.

+
::pt::ast bottomup cmdprefix ast
+

This command walks the abstract syntax tree ast from the bottom +up to the root, invoking the command prefix cmdprefix for each +node. This implies that the children of a node N are handled before N.

+

The command prefix has the signature

+
+
cmdprefix ast
+

I.e. it is invoked with the ast node the walk is currently at.

+

The result returned by the command prefix replaces ast in the +node it was a child of, allowing transformations of the tree.

+

This also means that for all inner node the contents of the children +elements are the results of the command prefix invoked for the +children of this node.

+
+
::pt::ast topdown cmdprefix pe
+

This command walks the abstract syntax tree ast from the root +down to the leaves, invoking the command prefix cmdprefix for +each node. This implies that the children of a node N are handled +after N.

+

The command prefix has the same signature as for bottomup, +see above.

+

The result returned by the command prefix is ignored.

+
::pt::ast equal seriala serialb
+

This command tests the two sbstract syntax trees seriala and +serialb for structural equality. The result of the command is a +boolean value. It will be set to true if the trees are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two trees are +pure Tcl lists.

+
::pt::ast new0 s loc ?child...?
+

This command command constructs the ast for a nonterminal node +refering refering to the symbol s at position loc in the +input, and the set of child nodes child ..., from left +right. The latter may be empty. The constructed node is returned as +the result of the command. The end position is loc-1, i.e. one +character before the start. This type of node is possible for rules +containing optional parts.

+
::pt::ast new s start end ?child...?
+

This command command constructs the ast for a nonterminal node +refering to the symbol s covering the range of positions +start to end in the input, and the set of child nodes +child ..., from left right. The latter may be empty. The +constructed node is returned as the result of the command.

+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html Index: embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html +++ embedded/www/tcllib/files/modules/pt/pt_cparam_config_critcl.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::cparam::configuration::critcl(n) 1.0.2 tcllib "Parser Tools"

+

Name

+

pt::cparam::configuration::critcl - C/PARAM, Canned configuration, Critcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::cparam::configuration::critcl ?1.0.2?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::cparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::cparam to generate +critcl-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::cparam::configuration::critcl def name pkg version cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of critcl-based parsers +whose class is name, in package pkg with version.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::cparam +(pt::peg::to::cparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_cparam_config_tea.html Index: embedded/www/tcllib/files/modules/pt/pt_cparam_config_tea.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_cparam_config_tea.html +++ embedded/www/tcllib/files/modules/pt/pt_cparam_config_tea.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::cparam::configuration::tea(n) 0.1 tcllib "Parser Tools"

+

Name

+

pt::cparam::configuration::tea - C/PARAM, Canned configuration, TEA

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::cparam::configuration::tea ?0.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::cparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::cparam to generate plain parser code +ready for inclusion into a TEA-based C extension.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::cparam::configuration::tea def name pkg version cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of tea-based parsers +whose class is name, in package pkg with version.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::cparam +(pt::peg::to::cparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_from_api.html Index: embedded/www/tcllib/files/modules/pt/pt_from_api.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_from_api.html +++ embedded/www/tcllib/files/modules/pt/pt_from_api.html @@ -0,0 +1,533 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_import_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_import_api - Parser Tools Import API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes two APIs. First the API shared by all packages +for the conversion of some other format into Parsing Expression +Grammars , and then the API shared by the packages which implement the +import plugins sitting on top of the conversion packages.

+

Its intended audience are people who wish to create their own +converter for some type of input, and/or an import plugin for their or +some other converter.

+

It resides in the Import section of the Core Layer of Parser Tools.

+

arch_core_import

+
+

Converter API

+

Any (grammar) import converter has to follow the rules set out below:

+
    +

  1. A converter is a package. Its name is arbitrary, however it is + recommended to put it under the ::pt::peg::from + namespace.

    2. +

  2. The package provides either a single Tcl command following the + API outlined below, or a class command whose instances follow + the same API. The commands which follow the API are called + converter commands.

    3. +

  3. A converter command has to provide the following single method + with the given signature and semantic. Converter commands + are allowed to provide more methods of their own, but not + less, and they may not provide different semantics for the + standardized method.

    +
    +
    CONVERTER convert text
    +

    This method has to accept some text, a parsing expression +grammar in some format. +The result of the method has to be the canonical serialization of a +parsing expression grammar, as specified in section +PEG serialization format, the result of reading and +converting the input text.

    +
    +
    4. +
+
+

Plugin API

+

Any (grammar) import plugin has to follow the rules set out below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + pt::peg::import::FOO, + where FOO is the name of the format the plugin will + accept input for.

    3. +

  3. The plugin can expect that the package + pt::peg::import::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    +

    It is recommended that a plugin does check for the presence of + this package.

    4. +

  4. The plugin can expect that a command named IncludeFile + is present, with the signature

    +
    +
    IncludeFile currentfile path
    +

    This command has to be invoked by the plugin when it has to process an +included file, if the format has the concept of such.

    +

    The plugin has to supply the following arguments

    +
    +
    string currentfile
    +

    The path of the file it is currently processing. This may be the empty +string if no such is known.

    +
    string path
    +

    The path of the include file as specified in the include directive +being processed.

    +
    +

    The result of the command will be a 5-element list containing

    +
      +

    1. A boolean flag indicating the success (True) or failure + (False) of the operation.

      2. +

    2. In case of success the contents of the included file, and the + empty string otherwise.

      3. +

    3. The resolved, i.e. absolute path of the included file, if + possible, or the unchanged path argument. This is for + display in an error message, or as the currentfile + argument of another call to IncludeFile should this file + contain more files.

      4. +

    4. In case of success an empty string, and for failure a code + indicating the reason for it, one of

      +
      +
      notfound
      +

      The specified file could not be found.

      +
      notread
      +

      The specified file was found, but not be read into memory.

      +
      +
      5. +

    5. An empty string in case of success of a notfound + failure, and an additional error message describing the reason + for a notread error in more detail.

      6. +
    +
    +
    5. +

  5. A plugin has to provide a single command, in the global + namespace, with the signature shown below. Plugins are allowed + to provide more commands of their own, but not less, and they + may not provide different semantics for the standardized + command.

    +
    +
    ::import text
    +

    This command has to accept the a text containing a parsing expression +grammar in some format. The result of the command has to be the result +of the converter invoked by the plugin for the input grammar, the +canonical serialization of the parsing expression grammar contained in +the input.

    +
    +
    string text
    +

    This argument will contain the parsing expression grammar for which to +generate the serialization. +The specification of what a canonical serialization is can be +found in the section PEG serialization format.

    +
    +
    +
    6. +

  6. A single usage cycle of a plugin consists of an invokation of + the command import. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    7. +
+
+

Usage

+

To use a converter do

+
+    # Get the converter (single command here, not class)
+    package require the-converter-package
+    # Perform the conversion
+    set serial [theconverter convert $thegrammartext]
+    ... process the result ...
+
+

To use a plugin FOO do

+
+    # Get an import plugin manager
+    package require pt::peg::import
+    pt::peg::import I
+    # Run the plugin, and the converter inside.
+    set serial [I import serial $thegrammartext FOO]
+    ... process the result ...
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_introduction.html Index: embedded/www/tcllib/files/modules/pt/pt_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_introduction.html +++ embedded/www/tcllib/files/modules/pt/pt_introduction.html @@ -0,0 +1,285 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_introduction(n) 1 tcllib "Parser Tools"

+

Name

+

pt_introduction - Introduction to Parser Tools

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Welcome to the Parser Tools, a system for the creation and +manipulation of parsers and the grammars driving them.

+

What are your goals which drove you here ?

+
    +

  1. Do you simply wish to create a parser for some language ?

    +

    In that case have a look at our parser generator application, +pt, or, for a slightly deeper access, the package underneath it, +pt::pgen.

    2. +

  2. Do you wish to know more about the architecture of the system ?

    +

    This is described in the section +Parser Tools Architecture, below

    3. +

  3. Is your interest in the theoretical background upon which the packages +and tools are build ?

    +

    See the Introduction to Parsing Expression Grammars.

    4. +
+
+

Parser Tools Architecture

+

The system can be split into roughly three layers, as seen in the +figure below

+

architecture

+

These layers are, from high to low:

+
    +

  1. At the top we have the application and the packages using the packages +of the layer below to implement common usecases. One example is the +aforementioned pt::pgen which provides a parser generator.

    +

    The list of packages belonging to this layer can be found in section +User Packages

    2. +

  2. In this layer we have the packages which provide the core of the +functionality for the whole system. They are, in essence, a set of +blocks which can be combined in myriad ways, like Lego (tm). The +packages in the previous level are 'just' pre-fabricated combinations +to cover the most important use cases.

    +

    The list of packages belonging to this layer can be found in section +Core Packages

    3. +

  3. Last, but not least is the layer containing support packages providing +generic functionality which not necessarily belong into the module.

    +

    The list of packages belonging to this layer can be found in section +Support Packages

    4. +
+ +

Core Packages

+

This layer is further split into six sections handling the storage, +import, export, transformation, and execution of grammars, plus +grammar specific support packages.

+
+
Storage
+
+
pt::peg::container
+
+
+
Export
+
+
pt::peg::export
+
+
pt::peg::export::container
+
+
pt::peg::export::json
+
+
pt::peg::export::peg
+
+
pt::peg::to::container
+
+
pt::peg::to::json
+
+
pt::peg::to::peg
+
+
pt::peg::to::param
+
+
pt::peg::to::tclparam
+
+
pt::peg::to::cparam
+
+
+
Import
+
+
pt::peg::import
+
+
pt::peg::import::container
+
+
pt::peg::import::json
+
+
pt::peg::import::peg
+
+
pt::peg::from::container
+
+
pt::peg::from::json
+
+
pt::peg::from::peg
+
+
+
Transformation
+
+
Execution
+
+
pt::peg::interp
+
+
pt::rde
+
+
+
Support
+
+
pt::tclparam::configuration::snit
+
+
pt::tclparam::configuration::tcloo
+
+
pt::cparam::configuration::critcl
+
+
pt::ast
+
+
pt::pe
+
+
pt::peg
+
+
+
+
+

Support Packages

+
+
pt::peg::container::peg
+
+
text::write
+
+
configuration
+
+
paths
+
+
char
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_json_language.html Index: embedded/www/tcllib/files/modules/pt/pt_json_language.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_json_language.html +++ embedded/www/tcllib/files/modules/pt/pt_json_language.html @@ -0,0 +1,531 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::json_language(n) 1 tcllib "Parser Tools"

+

Name

+

pt::json_language - The JSON Grammar Exchange Format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_param.html Index: embedded/www/tcllib/files/modules/pt/pt_param.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_param.html +++ embedded/www/tcllib/files/modules/pt/pt_param.html @@ -0,0 +1,579 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::param(n) 1 tcllib "Parser Tools"

+

Name

+

pt::param - PackRat Machine Specification

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the PackRat Machine (short: PARAM), a virtual +machine geared towards the support of recursive descent parsers, +especially packrat parsers. Towards this end it has features like the +caching and reuse of partial results, the caching of the encountered +input, and the ability to backtrack in both input and AST creation.

+

This document specifies the machine in terms of its architectural +state and instruction set.

+
+

Architectural State

+

Any PARAM implementation has to manage at least the following state:

+
+
Input (IN)
+

This is the channel the characters to process are read from.

+

This part of the machine's state is used and modified by the +instructions defined in the section Input Handling.

+
Current Character (CC)
+

The character from the input currently tested against its +possible alternatives.

+

This part of the machine's state is used and modified by the +instructions defined in the section Character Processing.

+
Current Location (CL)
+

The location of the current character in the input, as +offset relative to the beginning of the input. Character offsets are +counted from 0.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Character Processing, +Location Handling, and Nonterminal Execution.

+
Location Stack (LS)
+

A stack of locations in the input, saved for possible +backtracking.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Character Processing, +Location Handling, and Nonterminal Execution.

+
Status (ST)
+

The status of the last attempt of testing the input, indicating +either success or failure.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Status Control, +Character Processing, and Nonterminal Execution.

+
Semantic Value (SV)
+

The current semantic value, either empty, or a node for AST +constructed from the input.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
AST Reduction Stack (ARS)
+

The stack of partial ASTs constructed during the processing of +nonterminal symbols.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
AST Stack (AS)
+

The stack of reduction stacks, saved for possible backtracking.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Value Construction, and +AST Construction.

+
Error Status (ER)
+

The machine's current knowledge of errors. This is either empty, or +set to a pair of location in the input and the set of messages for +that location.

+

Note that this part of the machine's state can be set even if +the last test of the current character was successful. For +example, the *-operator (matching a sub-expression zero or more times) +in a PEG is always successful, even if it encounters a problem further +in the input and has to backtrack. Such problems must not be forgotten +when continuing the parsing.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Error Handling, +Character Processing, and Nonterminal Execution.

+
Error Stack (ES)
+

The stack of error stati, saved for backtracking. This enables the +machine to merge current and older error stati when performing +backtracking in choices after an failed match.

+

This part of the machine's state is used and modified by the +instructions defined in the sections Error Handling, +Character Processing, and Nonterminal Execution.

+
Nonterminal Cache (NC)
+

A cache of machine states keyed by pairs name of nonterminal symbol +and location in the input. Each pair (N, L) is associated with a +4-tuple holding the values to use for CL, ST, SV, and ER after the +nonterminal N was parsed starting from the location L. +It is a performance aid for backtracking parsers, allowing them to +avoid an expensive reparsing of complex nonterminal symbols if they +have been encountered before at a given location.

+

The key location is where machine started the attempt to match the +named nonterminal symbol, and the location in the saved 4-tuple is +where machine ended up after the attempt completed, independent of the +success of the attempt.

+

This part of the machine's state is used and modified by the +instructions defined in the section Nonterminal Execution.

+
Terminal Cache (TC)
+

A cache of characters read from IN, with their location in IN as pair +of line and column, keyed by the location in IN, this time as +character offset from the beginning of IN. +It is a performance aid for backtracking parsers, allowing them to +avoid a possibly expensive rereading of characters from IN, or even +enabling backtracking at, i.e. in the case of IN not randomly +seekable.

+

This part of the machine's state is used and modified by the +instructions defined in the section Input Handling.

+
+
+

Instruction Set

+

With the machine's architectural state specified it is now possible to +specify the instruction set operating on that state and to be +implemented by any realization of the PARAM. The 37 instructions are +grouped roughly by the state they influence and/or query during their +execution.

+

Input Handling

+

The instructions in this section mainly access IN, pulling the +characters to process into the machine.

+
+
input_next msg
+

This method reads the next character, i.e. the character after CL, +from IN. If successful this character becomes CC, CL is advanced by +one, ES is cleared, and the operation is recorded as a success in ST.

+

The operation may read the character from IN if the next character +is not yet known to TC. If successful the new character is stored in +TC, with its location (line, column), and the operation otherwise +behaves as specified above. Future reads from the same location, +possible due to backtracking, will then be satisfied from TC instead +of IN.

+

If, on the other hand, the end of IN was reached, the operation is +recorded as failed in ST, CL is left unchanged, and the pair of CL and +msg becomes the new ES.

+
+
+

Character Processing

+

The instructions in this section mainly access CC, testing it against +character classes, ranges, and individual characters.

+
+
test_alnum
+

This instruction implements the special PE operator "alnum", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_alpha
+

This instruction implements the special PE operator "alpha", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_ascii
+

This instruction implements the special PE operator "ascii", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_char char
+

This instruction implements the character matching operator, i.e. it +checks if CC is char.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_ddigit
+

This instruction implements the special PE operator "ddigit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_digit
+

This instruction implements the special PE operator "digit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_graph
+

This instruction implements the special PE operator "graph", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_lower
+

This instruction implements the special PE operator "lower", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_print
+

This instruction implements the special PE operator "print", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_punct
+

This instruction implements the special PE operator "punct", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_range chars chare
+

This instruction implements the range matching operator, i.e. it +checks if CC falls into the interval of characters spanned up by the +two characters from chars to chare, both inclusive.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_space
+

This instruction implements the special PE operator "space", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_upper
+

This instruction implements the special PE operator "upper", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_wordchar
+

This instruction implements the special PE operator "wordchar", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
test_xdigit
+

This instruction implements the special PE operator "xdigit", which +checks if CC falls into the character class of the same name, or not.

+

Success and failure of the test are both recorded directly in ST. +Success further clears ES, wheras failure sets the pair of CL and +expected input (encoded as a leaf parsing expression) as the new ES +and then rewinds CL by one character, preparing the machine for +another parse attempt by a possible alternative.

+
+
+

Error Handling

+

The instructions in this section mainly access ER and ES.

+
+
error_clear
+

This instruction clears ER.

+
error_push
+

This instruction makes a copy of ER and pushes it on ES.

+
error_pop_merge
+

This instruction takes the topmost entry of ES and merges the error +status it contains with ES, making the result the new ES.

+

The merge is governed by four rules, with the merge result

+
    +

  1. Empty if both states are empty.

    2. +

  2. The non-empty state if only one of the two states is non-empty.

    3. +

  3. The state with the larger location, if the two states specify +different locations.

    4. +

  4. The pair of the location shared by the two states, and the set-union +of their messages for states at the same location.

    5. +
+
error_nonterminal symbol
+

This is a guarded instruction. It does nothing if either ES is empty, +or if the location in ES is not just past the last location saved in +LS. Otherwise it sets the pair of that location and the nonterminal +symbol as the new ES.

+

Note: In the above "just past" means "that location plus one", +or also "the location of the next character after that location".

+
+
+

Status Control

+

The instructions in this section directly manipulate ST.

+
+
status_ok
+

This instruction sets ST to true, recording a success.

+
status_fail
+

This instruction sets ST to false, recording a failure.

+
status_negate
+

This instruction negates ST, turning a failure into a success and vice +versa.

+
+
+

Location Handling

+

The instructions in this section access CL and LS.

+
+
loc_push
+

This instruction makes a copy of CL and pushes it on LS.

+
loc_pop_discard
+

This instructions pops the last saved location from LS.

+
loc_pop_rewind
+

This instruction pops the last saved location from LS and restores it +as CL.

+
+
+

Nonterminal Execution

+

The instructions in this section access and manipulate NC.

+
+
symbol_restore symbol
+

This instruction checks if NC contains data for the nonterminal +symbol at CL, or not. The result of the instruction is a boolean +flag, with True indicating that data was found in the +cache. In that case the instruction has further updated the +architectural state of the machine with the cached information, namely +CL, ST, ER, and SV.

+

The method with which the instruction's result is transformed into +control flow is left undefined and the responsibility of the +implementation.

+
symbol_save symbol
+

This instructions saves the current settings of CL, ST, ER, and SV in +NC, using the pair of nonterminal symbol and the last location +saved in LS as key.

+
+
+

Value Construction

+

The instructions in this section manipulate SV.

+
+
value_clear
+

This instruction clears SV.

+
value_leaf symbol
+

This instruction constructs an AST node for symbol covering the +range of IN from one character after the last location saved on LS to +CL and stores it in SV. ...

+
value_reduce symbol
+

This instruction generally behaves like value_nonterminal_leaf, +except that it takes all AST nodes on ARS, if any, and makes them the +children of the new node, with the last node saved on ARS becoming the +right-most / last child. Note that ARS is not modfied by this +operation.

+
+
+

AST Construction

+

The instructions in this section manipulate ARS and AS.

+
+
ast_value_push
+

This instruction makes a copy of SV and pushes it on ARS.

+
ast_push
+

This instruction pushes the current state of ARS on AS and then clears +ARS.

+
ast_pop_rewind
+

This instruction pops the last entry saved on AS and restores it as +the new state of ARS.

+
ast_pop_discard
+

This instruction pops the last entry saved on AS.

+
+
+

Control Flow

+

Normally this section would contain the specifications of the control +flow instructions of the PARAM, i.e. (un)conditional jumps and the +like. However, this part of the PARAM is intentionally left +unspecified. This allows the implementations to freely choose how to +implement control flow.

+

The implementation of this machine in Parser Tools, i.e the package +pt::rde, is not only coded in Tcl, but also relies on Tcl +commands to provide it with control flow (instructions).

+
+
+

Interaction of the Instructions with the Architectural State

+
+Instruction		Inputs				Outputs
+======================= =======================		====================
+ast_pop_discard		AS			->	AS
+ast_pop_rewind		AS			->	AS, ARS
+ast_push		ARS, AS			->	AS
+ast_value_push		SV, ARS			->	ARS
+======================= =======================		====================
+error_clear		-			->	ER
+error_nonterminal sym	ER, LS			->	ER
+error_pop_merge   	ES, ER			->	ER
+error_push		ES, ER			->	ES
+======================= =======================		====================
+input_next msg		IN			->	TC, CL, CC, ST, ER
+======================= =======================		====================
+loc_pop_discard		LS			->	LS
+loc_pop_rewind		LS			->	LS, CL
+loc_push		CL, LS			->	LS
+======================= =======================		====================
+status_fail		-			->	ST
+status_negate		ST			->	ST
+status_ok		-			->	ST
+======================= =======================		====================
+symbol_restore sym	NC			->	CL, ST, ER, SV
+symbol_save    sym	CL, ST, ER, SV LS	->	NC
+======================= =======================		====================
+test_alnum  		CC			->	ST, ER
+test_alpha		CC			->	ST, ER
+test_ascii		CC			->	ST, ER
+test_char char		CC			->	ST, ER
+test_ddigit		CC			->	ST, ER
+test_digit		CC			->	ST, ER
+test_graph		CC			->	ST, ER
+test_lower		CC			->	ST, ER
+test_print		CC			->	ST, ER
+test_punct		CC			->	ST, ER
+test_range chars chare	CC			->	ST, ER
+test_space		CC			->	ST, ER
+test_upper		CC			->	ST, ER
+test_wordchar		CC			->	ST, ER
+test_xdigit		CC			->	ST, ER
+======================= =======================		====================
+value_clear		-			->	SV
+value_leaf symbol	LS, CL			->	SV
+value_reduce symbol	ARS, LS, CL		->	SV
+======================= =======================		====================
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_parse_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_parse_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_parse_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_parse_peg.html @@ -0,0 +1,222 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_parse_peg(i) 1 tcllib "Parser Tools"

+

Name

+

pt_parse_peg - Parser Tools PEG Parser

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::parse::peg 1
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a class whose instances are parsers for parsing +expression grammars in textual form.

+
+

Class API

+
+
pt::parse::peg ?objectName?
+

The class command constructs parser instances, i.e. objects. The +result of the command is the fully-qualified name of the instance +command.

+

If no objectName is specified the class will generate and use an +automatic name. If the objectName was specified, but is not +fully qualified the command will be created in the current namespace.

+
+
+

Instances API

+

All parser instances provide at least the methods shown below:

+
+
objectName destroy
+

This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command.

+

The result of the command is the empty string.

+
objectName parse chan
+

This method runs the parser using the contents of chan as input +(starting at the current location in the channel), until parsing is +not possible anymore, either because parsing has completed, or run +into a syntax error.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+

Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +AST serialization format. +As a plain nested Tcl-list it can then be processed with any Tcl +commands the user likes, doing transformations, semantic checks, etc. +To help in this the package pt::ast provides a set of +convenience commands for validation of the tree's basic structure, +printing it for debugging, and walking it either from the bottom up, +or top down.

+

When encountering a syntax error the command will throw an error instead. +This error will be a 4-element Tcl-list, containing, in the order +listed below:

+
    +

  1. The string pt::rde identifying it as parser runtime error.

    2. +

  2. The location of the parse error, as character offset from the +beginning of the parsed input.

    3. +

  3. The location of parse error, now as a 2-element list containing +line-number and column in the line.

    4. +

  4. A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. + For the specification of atomic parsing expressions please see the +section PE serialization format.

    5. +
+
objectName parset text
+

This method runs the parser using the string in text as input. +In all other ways it behaves like the method parse, shown +above.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_parser_api.html Index: embedded/www/tcllib/files/modules/pt/pt_parser_api.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_parser_api.html +++ embedded/www/tcllib/files/modules/pt/pt_parser_api.html @@ -0,0 +1,475 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_parser_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_parser_api - Parser API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes the API shared by the grammar interpreter +provided by the package pt::peg::interp and the parsers +generated by the pt application for the result formats +critcl, snit, and oo regarding access +to the actual parsing functionality.

+

Its intended audience are people who wish to create a parser for some +language of theirs and then use that parser within a Tcl-based package +or application.

+

It resides in the User Layer of Parser Tools.

+

arch_user_pkg

+
+

Class API

+
+
className ?objectName?
+

The class command constructs parser instances, i.e. objects. The +result of the command is the fully-qualified name of the instance +command.

+

If no objectName is specified the class will generate and use an +automatic name. If the objectName was specified, but is not +fully qualified the command will be created in the current namespace.

+
+
+

Instance API

+

All parser instances provide at least the methods shown below:

+
+
objectName destroy
+

This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command.

+

The result of the command is the empty string.

+
objectName parse chan
+

This method runs the parser using the contents of chan as input +(starting at the current location in the channel), until parsing is +not possible anymore, either because parsing has completed, or run +into a syntax error.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+

Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +AST serialization format. +As a plain nested Tcl-list it can then be processed with any Tcl +commands the user likes, doing transformations, semantic checks, etc. +To help in this the package pt::ast provides a set of +convenience commands for validation of the tree's basic structure, +printing it for debugging, and walking it either from the bottom up, +or top down.

+

When encountering a syntax error the command will throw an error instead. +This error will be a 4-element Tcl-list, containing, in the order +listed below:

+
    +

  1. The string pt::rde identifying it as parser runtime error.

    2. +

  2. The location of the parse error, as character offset from the +beginning of the parsed input.

    3. +

  3. The location of parse error, now as a 2-element list containing +line-number and column in the line.

    4. +

  4. A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. + For the specification of atomic parsing expressions please see the +section PE serialization format.

    5. +
+
objectName parset text
+

This method runs the parser using the string in text as input. +In all other ways it behaves like the method parse, shown +above.

+
+
+

Usage

+

A generated parser is used like this

+
+    package require the-parser-package ;# Generated by result-formats 'critcl', 'snit' or 'oo' of 'pt'.
+    set parser [the-parser-class]
+    set ast [$parser parse $channel]
+    ... process the abstract syntax tree ...
+
+

When using a grammar interpreter for parsing some differences creep in

+
+    package require the-grammar-package ;# Generated by result-format 'container' of 'pt'.
+    set grammar [the-grammar-class]
+    package require pt::peg::interp
+    set parser [pt::peg::interp]
+    $parser use $grammar
+    set ast [$parser parse $channel]
+    $parser destroy
+    ... process the abstract syntax tree ...
+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_container.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_container.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_container.html @@ -0,0 +1,658 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::container - PEG Storage

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a container class for parsing expression +grammars, with each instance storing a single grammar and allowing the +user to manipulate and query its definition.

+

It resides in the Storage section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_container

+

The other two pillars are, as shown above

+
    +

  1. PEG Import, and

    2. +

  2. PEG Export

    3. +
+

Packages related to this are:

+
+
pt::rde
+

This package provides an implementation of PARAM, a virtual machine +for the parsing of a channel, geared towards the needs of handling +PEGs.

+
pt::peg::interp
+

This package implements an interpreter for PEGs on top of the virtual +machine provided by pt::peg::rde

+
+

Class API

+

The package exports the API described here.

+
+
::pt::peg objectName ?=|:=|<--|as|deserialize src?
+

The command creates a new container object for a parsing expression +grammar and returns the fully qualified name of the object command as +its result. The API of this object command is described in the section +Object API. It may be used to invoke various operations on +the object.

+

The new container will be empty if no src is specified. Otherwise +it will contain a copy of the grammar contained in the src. +All operators except deserialize interpret src as a +container object command. The deserialize operator interprets +src as the serialization of a parsing expression grammar +instead, as specified in section PEG serialization format.

+

An empty grammar has no nonterminal symbols, and the start expression +is the empty expression, i.e. epsilon. It is valid, but not +useful.

+
+
+

Object API

+

All objects created by this package provide the following methods for +the manipulation and querying of their contents:

+
+
objectName destroy
+

This method destroys the object, releasing all claimed memory, and +deleting the associated object command.

+
objectName clear
+

This method resets the object to contain the empty grammar. It does +not destroy the object itself.

+
objectName importer
+

This method returns the import manager object currently attached to +the container, if any.

+
objectName importer object
+

This method attaches the object as import manager to the +container, and returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +import text which takes a text and a format name, and +returns the canonical serialization of the table of contents contained in +the text, assuming the given format.

+
objectName exporter
+

This method returns the export manager object currently attached to +the container, if any.

+
objectName exporter object
+

This method attaches the object as export manager to the +container, and returns it as the result of the command. +Note that the object is not put into ownership of the +container. I.e., destruction of the container will not destroy +the object.

+

It is expected that object provides a method named +export object which takes the container and a format name, +and returns a text encoding table of contents stored in the container, in +the given format. It is further expected that the object will +use the container's method serialize to obtain the +serialization of the table of contents from which to generate the text.

+
objectName = source
+

This method assigns the contents of the PEG object source to +ourselves, overwriting the existing definition. This is the assignment +operator for grammars.

+

This operation is in effect equivalent to

+
+    objectName deserialize = [source serialize]
+
+
+
objectName --> destination
+

This method assigns our contents to the PEG object destination, +overwriting the existing definition. This is the reverse assignment +operator for grammars.

+

This operation is in effect equivalent to

+
+    destination deserialize = [objectName serialize]
+
+
+
objectName serialize ?format?
+

This method returns our grammar in some textual form usable for +transfer, persistent storage, etc. If no format is not specified +the returned result is the canonical serialization of the grammar, as +specified in the section PEG serialization format.

+

Otherwise the object will use the attached export manager to convert +the data to the specified format. In that case the method will fail +with an error if the container has no export manager attached to it.

+
objectName deserialize = data ?format?
+

This is the complementary method to serialize. +It replaces the current definition with the grammar contained in the +data. If no format was specified it is assumed to be the +regular serialization of a grammar, as specified in the section +PEG serialization format

+

Otherwise the object will use the attached import manager to convert +the data from the specified format to a serialization it can handle. +In that case the method will fail with an error if the container has +no import manager attached to it.

+

The result of the method is the empty string.

+
objectName deserialize += data ?format?
+

This method behaves like deserialize = in its essentials, +except that it merges the grammar in the data to its +contents instead of replacing it. +The method will fail with an error and leave the grammar unchanged if +merging is not possible, i.e. would produce an invalid grammar.

+

The result of the method is the empty string.

+
objectName start
+

This method returns the current start expression of the grammar.

+
objectName start pe
+

This method defines the start expression of the grammar. It +replaces the current start expression with the parsing expression +pe, and returns the new start expression.

+

The method will fail with an error and leave the grammar unchanged if +pe does not contain a valid parsing expression as specified in +the section PE serialization format.

+
objectName nonterminals
+

This method returns the set of all nonterminal symbols known to the +grammar.

+
objectName modes
+

This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their semantic modes.

+
objectName modes dict
+

This method takes a dictionary mapping a set of nonterminal symbols +known to the grammar to their semantic modes, and returns the new full +mapping of nonterminal symbols to semantic modes.

+

The method will fail with an error if any of the nonterminal symbols +in the dictionary is not known to the grammar, or the empty string, +i.e. an invalid nonterminal symbol, or if any the chosen modes +is not one of the legal values.

+
objectName rules
+

This method returns a dictionary mapping the set of all nonterminal +symbols known to the grammar to their parsing expressions (right-hand +sides).

+
objectName rules dict
+

This method takes a dictionary mapping a set of nonterminal symbols +known to the grammar to their parsing expressions (right-hand sides), +and returns the new full mapping of nonterminal symbols to parsing +expressions.

+

The method will fail with an error any of the nonterminal symbols in +the dictionary is not known to the grammar, or the empty string, +i.e. an invalid nonterminal symbol, or any of the chosen parsing +expressions is not a valid parsing expression as specified in the +section PE serialization format.

+
objectName add ?nt...?
+

This method adds the nonterminal symbols nt, etc. to the +grammar, and defines default semantic mode and expression for it +(value and epsilon respectively). +The method returns the empty string as its result.

+

The method will fail with an error and leaves the grammar unchanged if +any of the nonterminal symbols are either already defined in our +grammar, or are the empty string (an invalid nonterminal symbol).

+

The method does nothing if no symbol was specified as argument.

+
objectName remove ?nt...?
+

This method removes the named nonterminal symbols nt, etc. from +the set of nonterminal symbols known to our grammar. +The method returns the empty string as its result.

+

The method will fail with an error and leave the grammar unchanged if +any of the nonterminal symbols is not known to the grammar, or is the +empty string, i.e. an invalid nonterminal symbol.

+
objectName exists nt
+

This method tests whether the nonterminal symbol nt is known +to our grammar or not. +The result is a boolean value. It will be set to true if +nt is known, and false otherwise.

+

The method will fail with an error if nt is the empty string, +i.e. an invalid nonterminal symbol.

+
objectName rename ntold ntnew
+

This method renames the nonterminal symbol ntold to ntnew. +The method returns the empty string as its result.

+

The method will fail with an error and leave the grammar unchanged if +either ntold is not known to the grammar, or ntnew is +already known, or any of them is the empty string, i.e. an invalid +nonterminal symbol.

+
objectName mode nt
+

This method returns the current semantic mode for the nonterminal +symbol nt.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol.

+
objectName mode nt mode
+

This mode sets the semantic mode for the nonterminal symbol nt, +and returns the new mode. +The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +the chosen mode is not one of the legal values.

+

The following modes are legal:

+
+
value
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

+
leaf
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

+
void
+

The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

+
+
objectName rule nt
+

This method returns the current parsing expression (right-hand side) +for the nonterminal symbol nt.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol.

+
objectName rule nt pe
+

This method set the parsing expression (right-hand side) of the +nonterminal nt to pe, and returns the new parsing +expression.

+

The method will fail with an error if nt is not known to the +grammar, or the empty string, i.e. an invalid nonterminal symbol, or +pe does not contain a valid parsing expression as specified in +the section PE serialization format.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_container_peg.html @@ -0,0 +1,157 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::container::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::container::peg - PEG Storage. Canned PEG grammar specification

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit
    • +
  • package require pt::peg::container::peg ?1?
    • +
  • package require pt::peg::container
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a sub-type of pt::peg::container which +is preloaded with a parsing expression grammar describing a textual +format for parsing expression grammars.

+

The sub-type provides the exact same API as +pt::peg::container. Instead of duplicating its contents the +reader is asked to read the referenced document.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_export.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_export.html @@ -0,0 +1,530 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::export(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export - PEG Export

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a manager for parsing expression grammars, with +each instance handling a set of plugins for the export of them to +other formats, i.e. their conversion to, for example nroff, +HTML, etc.

+

It resides in the Export section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_export

+

The other two pillars are, as shown above

+
    +

  1. PEG Import, and

    2. +

  2. PEG Storage

    3. +
+

For information about the data structure which is the major input to +the manager objects provided by this package see the section +PEG serialization format.

+

The plugin system of this class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable GRAMMAR_PEG_EXPORT_PLUGINS,

    2. +

  2. the environment variable GRAMMAR_PEG_PLUGINS,

    3. +

  3. the environment variable GRAMMAR_PLUGINS,

    4. +

  4. the path "~/.grammar/peg/export/plugin"

    5. +

  5. the path "~/.grammar/peg/plugin"

    6. +

  6. the path "~/.grammar/plugin"

    7. +

  7. the path "~/.grammar/peg/export/plugins"

    8. +

  8. the path "~/.grammar/peg/plugins"

    9. +

  9. the path "~/.grammar/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\EXPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using the Windows(tm) operating system.

+

The whole system is delivered with three predefined export plugins, +namely

+
+
container
+

See PEG Export Plugin. To CONTAINER format for details.

+
json
+

See PEG Export Plugin. To JSON format for details.

+
peg
+

See PEG Export Plugin. To PEG format for details.

+
+

For readers wishing to write their own export plugin for some format, +i.e. plugin writers, reading and understanding the +Parser Tools Export API specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail.

+
+

API

+

Package commands

+
+
::pt::peg::export objectName
+

This command creates a new export manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::pt::peg::export command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName export serial serial ?format?
+

This method takes the canonical serialization of a parsing expression +grammar stored in serial and converts it to the specified +format, using the export plugin for the format. This will fail +with an error if no plugin could be found for the format. +The string generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to text.

+

The specification of what a canonical serialization is can be +found in the section PEG serialization format.

+

The plugin has to conform to the interface documented in the +Parser Tools Export API specification.

+
objectName export object object ?format?
+

This method is a convenient wrapper around the export serial +method described by the previous item. +It expects that object is an object command supporting a +serialize method returning the canonical serialization of a +parsing expression grammar. It invokes that method, feeds the result +into export serial and returns the resulting string as its +own result.

+
objectName configuration names
+

This method returns a list containing the names of all configuration +options currently known to the object.

+
objectName configuration get
+

This method returns a dictionary containing the names and values of +all configuration options currently known to the object.

+
objectName configuration set name ?value?
+

This method sets the configuration option name to the +specified value and returns the new value of the option.

+

If no value is specified it simply returns the current value, without +changing it.

+

Note that these configuration options and their values are simply +passed to a plugin when the actual export is performed. It is the +plugin which checks the validity, not the manager.

+
objectName configuration unset pattern...
+

This method unsets all configuration options matching the specified +glob patterns. If no pattern is specified it will unset all +currently defined configuration options.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_container.html @@ -0,0 +1,543 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::export::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::container - PEG Export Plugin. Write CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::container ?1?
    • +
  • package require pt::peg::to::container
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of CONTAINER markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::container.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::container and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates CONTAINER markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The CONTAINER export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
enum mode
+

The value of this configuration variable controls which methods of +pt::peg instances the plugin will use to specify the +grammar. There are two legal values

+
+
bulk
+

In this mode the methods start, add, modes, +and rules are used to specify the grammar in a bulk manner, +i.e. as a set of nonterminal symbols, and two dictionaries mapping +from the symbols to their semantic modes and parsing expressions.

+

This mode is the default.

+
incremental
+

In this mode the methods start, add, mode, +and rule are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands.

+
+
string template
+

If this configuration variable is set it is assumed to contain a +string into which to put the generated code and other configuration +data. The various locations are expected to be specified with the +following placeholders:

+
+
@user@
+

To be replaced with the value of the configuration variable user.

+
@format@
+

To be replaced with the the constant CONTAINER.

+
@file@
+

To be replaced with the value of the configuration variable file.

+
@name@
+

To be replaced with the value of the configuration variable name.

+
@mode@
+

To be replaced with the value of the configuration variable mode.

+
@code@
+

To be replaced with the generated code.

+
+

If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "@code@".

+
+

Note that this plugin may ignore the standard configuration +variables user, format, file, and their values, +depending on the chosen template.

+

The content of the standard configuration variable name, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name a_pe_grammar.

+
+

Grammar Container

+

The container format is another form of describing parsing +expression grammars. While data in this format is executable it does +not constitute a parser for the grammar. It always has to be used in +conjunction with the package pt::peg::interp, a grammar +interpreter.

+

The format represents grammars by a snit::type, i.e. class, +whose instances are API-compatible to the instances of the +pt::peg::container package, and which are preloaded with the +grammar in question.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible CONTAINER serialization for it is

+
+snit::type a_pe_grammar {
+    constructor {} {
+        install myg using pt::peg::container ${selfns}::G
+        $myg start {n Expression}
+        $myg add   AddOp Digit Expression Factor MulOp Number Sign Term
+        $myg modes {
+            AddOp      value
+            Digit      value
+            Expression value
+            Factor     value
+            MulOp      value
+            Number     value
+            Sign       value
+            Term       value
+        }
+        $myg rules {
+            AddOp      {/ {t -} {t +}}
+            Digit      {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
+            Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
+            Factor     {x {n Term} {* {x {n AddOp} {n Term}}}}
+            MulOp      {/ {t *} {t /}}
+            Number     {x {? {n Sign}} {+ {n Digit}}}
+            Sign       {/ {t -} {t +}}
+            Term       {n Number}
+        }
+        return
+    }
+    component myg
+    delegate method * to myg
+}
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_json.html @@ -0,0 +1,596 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::export::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::json - PEG Export Plugin. Write JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::json ?1?
    • +
  • package require pt::peg::to::json
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of JSON markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::json.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::json and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates JSON markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The JSON export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
boolean indented
+

If this flag is set the plugin will break the generated JSON code +across lines and indent it according to its inner structure, with each +key of a dictionary on a separate line.

+

If this flag is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
boolean aligned
+

If this flag is set the generator ensures that the values for the keys +in a dictionary are vertically aligned with each other, for a nice +table effect. To make this work this also implies that indented +is set.

+

If this flag is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+

Note that this plugin ignores the standard configuration +variables user, format, file, and name, and +their values.

+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_export_peg.html @@ -0,0 +1,585 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::export::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::export::peg - PEG Export Plugin. Write PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::export::peg ?1?
    • +
  • package require pt::peg::to::peg
    • +
+
    +
  • export serial configuration
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar export plugin +for the generation of PEG markup.

+

It resides in the Export section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::export, the export +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::to::peg.

+

arch_core_eplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::export and the export manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::to::peg and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Export API +specification.

+
+
export serial configuration
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, the configuration, a dictionary, +and generates PEG markup encoding the grammar. +The created string is then returned as the result of the command.

+
+
+

Configuration

+

The PEG export plugin recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
string template
+

If this configuration variable is set it is assumed to contain a +string into which to put the generated text and other configuration +data. The various locations are expected to be specified with the +following placeholders:

+
+
@user@
+

To be replaced with the value of the configuration variable user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the configuration variable file.

+
@name@
+

To be replaced with the value of the configuration variable name.

+
@code@
+

To be replaced with the generated text.

+
+

If this configuration variable is not set, or empty, then the plugin +falls back to a standard template, which is defined as "@code@".

+
+

Note that this plugin may ignore the standard configuration +variables user, format, file, and their values, +depending on the chosen template.

+

The content of the standard configuration variable name, if set, +is used as name of the grammar in the output. Otherwise the plugin +falls back to the default name a_pe_grammar.

+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- "END" WHITESPACE SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG" !([_:] / <alnum>) WHITESPACE ;
+void:   IS              <- "<-"    WHITESPACE ;
+leaf:   VOID            <- "void"  WHITESPACE ; # Implies that definition has no semantic value.
+leaf:   LEAF            <- "leaf"  WHITESPACE ; # Implies that definition has no terminals.
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_container.html @@ -0,0 +1,155 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::from::container(n) 0 tcllib "Parser Tools"

+

Name

+

pt::peg::from::container - PEG Conversion. From CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package does not exist. +There is no need for it. +The CONTAINER format for parsing expression grammars is a piece of Tcl +code which, then sourced, provides a class whose instances have the +grammar we wish to import loaded. +Another way of looking at this is, the CONTAINER output is its own +import package.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_json.html @@ -0,0 +1,564 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::from::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::from::json - PEG Conversion. Read JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::from::json ?1?
    • +
  • package require pt::peg
    • +
  • package require json
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from JSON markup to +parsing expression grammars.

+

It resides in the Import section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the import manager provided by +pt::peg::import. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +pt::peg::import::json sitting between converter +and import manager.

+

arch_core_iplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Import API +specification.

+
+
pt::peg::from::json convert text
+

This command takes the JSON markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_from_peg.html @@ -0,0 +1,543 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::from::peg(n) 1.0.3 tcllib "Parser Tools"

+

Name

+

pt::peg::from::peg - PEG Conversion. Read PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::from::peg ?1.0.3?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from PEG markup to +parsing expression grammars.

+

It resides in the Import section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the import manager provided by +pt::peg::import. The latter is intented for use in untrusted +environments and done through the corresponding import plugin +pt::peg::import::peg sitting between converter +and import manager.

+

arch_core_iplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Import API +specification.

+
+
pt::peg::from::peg convert text
+

This command takes the PEG markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- "END" WHITESPACE SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG" !([_:] / <alnum>) WHITESPACE ;
+void:   IS              <- "<-"    WHITESPACE ;
+leaf:   VOID            <- "void"  WHITESPACE ; # Implies that definition has no semantic value.
+leaf:   LEAF            <- "leaf"  WHITESPACE ; # Implies that definition has no terminals.
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_import.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_import.html @@ -0,0 +1,546 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::import(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import - PEG Import

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a manager for parsing expression grammars, with +each instance handling a set of plugins for the import of them from +other formats, i.e. their conversion from, for example peg, +container, json, etc.

+

It resides in the Import section of the Core Layer of Parser Tools, +and is one of the three pillars the management of parsing expression +grammars resides on.

+

arch_core_import

+

The other two pillars are, as shown above

+
    +

  1. PEG Export, and

    2. +

  2. PEG Storage

    3. +
+

For information about the data structure which is the major output of +the manager objects provided by this package see the section +PEG serialization format.

+

The plugin system of our class is based on the package +pluginmgr, and configured to look for plugins using

+
    +

  1. the environment variable GRAMMAR_PEG_IMPORT_PLUGINS,

    2. +

  2. the environment variable GRAMMAR_PEG_PLUGINS,

    3. +

  3. the environment variable GRAMMAR_PLUGINS,

    4. +

  4. the path "~/.grammar/peg/import/plugin"

    5. +

  5. the path "~/.grammar/peg/plugin"

    6. +

  6. the path "~/.grammar/plugin"

    7. +

  7. the path "~/.grammar/peg/import/plugins"

    8. +

  8. the path "~/.grammar/peg/plugins"

    9. +

  9. the path "~/.grammar/plugins"

    10. +

  10. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS"

    11. +

  11. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"

    12. +

  12. the registry entry "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"

    13. +
+

The last three are used only when the package is run on a machine +using the Windows(tm) operating system.

+

The whole system is delivered with three predefined import plugins, +namely

+
+
container
+

See PEG Import Plugin. From CONTAINER format for details.

+
json
+

See PEG Import Plugin. From JSON format for details.

+
peg
+

See PEG Import Plugin. From PEG format for details.

+
+

For readers wishing to write their own import plugin for some format, +i.e. plugin writers, reading and understanding the +Parser Tools Impport API specification is an absolute +necessity, as it documents the interaction between this package and +its plugins in detail.

+
+

API

+

Package commands

+
+
::pt::peg::import objectName
+

This command creates a new import manager object with an associated +Tcl command whose name is objectName. This object command +is explained in full detail in the sections Object command +and Object methods. The object command will be created +under the current namespace if the objectName is not fully +qualified, and in the specified namespace otherwise.

+
+
+

Object command

+

All objects created by the ::pt::peg::import command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object it is invoked for.

+
objectName import text text ?format?
+

This method takes the text and converts it from the specified +format to the canonical serialization of a parsing expression +grammar using the import plugin for the format. An error is thrown if +no plugin could be found for the format. +The serialization generated by the conversion process is returned as +the result of this method.

+

If no format is specified the method defaults to text.

+

The specification of what a canonical serialization is can be +found in the section PEG serialization format.

+

The plugin has to conform to the interface documented in the +Parser Tools Import API specification.

+
objectName import file path ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It reads the contents of the specified file into memory, feeds the +result into import text and returns the resulting +serialization as its own result.

+
objectName import object text object text ?format?
+

This method is a convenient wrapper around the import text +method described by the previous item. +It expects that object is an object command supporting a +deserialize method expecting the canonical serialization of a +parsing expression grammar. +It imports the text using import text and then feeds the +resulting serialization into the object via deserialize. +This method returns the empty string as it result.

+
objectName import object file object path ?format?
+

This method behaves like import object text, except that it +reads the text to convert from the specified file instead of being +given it as argument.

+
objectName includes
+

This method returns a list containing the currently specified paths to +use to search for include files when processing input. +The order of paths in the list corresponds to the order in which they +are used, from first to last, and also corresponds to the order in +which they were added to the object.

+
objectName include add path
+

This methods adds the specified path to the list of paths to use +to search for include files when processing input. The path is added +to the end of the list, causing it to be searched after all previously +added paths. The result of the command is the empty string.

+

The method does nothing if the path is already known.

+
objectName include remove path
+

This methods removes the specified path from the list of paths +to use to search for include files when processing input. The result +of the command is the empty string.

+

The method does nothing if the path is not known.

+
objectName include clear
+

This method clears the list of paths to use to search for include +files when processing input. The result of the command is the empty +string.

+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_container.html @@ -0,0 +1,155 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::import::container(n) 0 tcllib "Parser Tools"

+

Name

+

pt::peg::import::container - PEG Import Plugin. From CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package does not exist. +There is no need for it. +The CONTAINER format for parsing expression grammars is a piece of Tcl +code which, then sourced, provides a class whose instances have the +grammar we wish to import loaded. +Another way of looking at this is, the CONTAINER output is its own +import package.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_json.html @@ -0,0 +1,572 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::import::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import::json - PEG Import Plugin. Read JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::import::json ?1?
    • +
  • package require pt::peg::to::json
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar import plugin +processing JSON markup.

+

It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::import, the import +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::from::json.

+

arch_core_iplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::import and the import manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::from::json and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Import API +specification.

+
+
import text
+

This command takes the JSON markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_import_peg.html @@ -0,0 +1,553 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::import::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::import::peg - PEG Import Plugin. Read PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::import::peg ?1?
    • +
  • package require pt::peg::to::peg
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the parsing expression grammar import plugin +processing PEG markup.

+

It resides in the Import section of the Core Layer of Parser Tools and +is intended to be used by pt::peg::import, the import +manager, sitting between it and the corresponding core conversion +functionality provided by pt::peg::from::peg.

+

arch_core_iplugins

+

While the direct use of this package with a regular interpreter is +possible, this is strongly disrecommended and requires a number of +contortions to provide the expected environment. +The proper way to use this functionality depends on the situation:

+
    +

  1. In an untrusted environment the proper access is through the package +pt::peg::import and the import manager objects it +provides.

    2. +

  2. In a trusted environment however simply use the package +pt::peg::from::peg and access the core +conversion functionality directly.

    3. +
+
+

API

+

The API provided by this package satisfies the specification of the +Plugin API found in the Parser Tools Import API +specification.

+
+
import text
+

This command takes the PEG markup encoding a parsing +expression grammar and contained in text, and generates the +canonical serialization of said grammar, as specified in section +PEG serialization format. +The created value is then returned as the result of the command.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- "END" WHITESPACE SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG" !([_:] / <alnum>) WHITESPACE ;
+void:   IS              <- "<-"    WHITESPACE ;
+leaf:   VOID            <- "void"  WHITESPACE ; # Implies that definition has no semantic value.
+leaf:   LEAF            <- "leaf"  WHITESPACE ; # Implies that definition has no terminals.
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_interp.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_interp.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_interp.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_interp.html @@ -0,0 +1,472 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::interp(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::peg::interp - Interpreter for parsing expression grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::interp ?1.0.1?
    • +
  • package require pt::rde ?1?
    • +
  • package require snit
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a class whose instances are Packrat parsers +configurable with a parsing expression grammar. The grammar is +executed directly, i.e. interpreted, with the underlying runtime +provided by the package pt::rde, basing everything on the +PARAM.

+

Like the supporting runtime this package resides in the Execution +section of the Core Layer of Parser Tools.

+

arch_core_transform

+

The interpreted grammar is copied from an instance of pt::peg::container, or anything providing the same API, like the +container classes created by pt::peg::to::container or the +associated export plugin pt::peg::export::container.

+

Class API

+

The package exports the API described here.

+
+
::pt::peg::interp objectName grammar
+

The command creates a new parser object and returns the fully +qualified name of the object command as its result. The API of this +object command is described in the section Object API. It +may be used to invoke various operations on the object.

+

This new parser is configured for the execution of an empty PEG. To +configure the object for any other PEG use the method use of +the Object API.

+
+
+

Object API

+

All objects created by this package provide the following methods.

+
+
objectName use grammar
+

This method configures the grammar interpreter / parser for the +execution of the PEG stored in grammar, an object which is +API-compatible to instances of pt::peg::container. The +parser copies the relevant information of the grammar, and does +not take ownership of the object.

+

The information of any previously used grammar is overwritten.

+

The result of the method the empty string.

+
objectName destroy
+

This method destroys the parser instance, releasing all claimed memory +and other resources, and deleting the instance command.

+

The result of the command is the empty string.

+
objectName parse chan
+

This method runs the parser using the contents of chan as input +(starting at the current location in the channel), until parsing is +not possible anymore, either because parsing has completed, or run +into a syntax error.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+

Upon successful completion the command returns an abstract syntax tree +as its result. +This AST is in the form specified in section +AST serialization format. +As a plain nested Tcl-list it can then be processed with any Tcl +commands the user likes, doing transformations, semantic checks, etc. +To help in this the package pt::ast provides a set of +convenience commands for validation of the tree's basic structure, +printing it for debugging, and walking it either from the bottom up, +or top down.

+

When encountering a syntax error the command will throw an error instead. +This error will be a 4-element Tcl-list, containing, in the order +listed below:

+
    +

  1. The string pt::rde identifying it as parser runtime error.

    2. +

  2. The location of the parse error, as character offset from the +beginning of the parsed input.

    3. +

  3. The location of parse error, now as a 2-element list containing +line-number and column in the line.

    4. +

  4. A set of atomic parsing expressions indicating encoding the characters +and/or nonterminal symbols the parser expected to see at the location +of the parse error, but did not get. + For the specification of atomic parsing expressions please see the +section PE serialization format.

    5. +
+
objectName parset text
+

This method runs the parser using the string in text as input. +In all other ways it behaves like the method parse, shown +above.

+
+
+
+

AST serialization format

+

Here we specify the format used by the Parser Tools to serialize +Abstract Syntax Trees (ASTs) as immutable values for transport, +comparison, etc.

+

Each node in an AST represents a nonterminal symbol of a grammar, and +the range of tokens/characters in the input covered by it. ASTs do not +contain terminal symbols, i.e. tokens/characters. These can be +recovered from the input given a symbol's location.

+

We distinguish between regular and canonical +serializations. +While a tree may have more than one regular serialization only exactly +one of them will be canonical.

+
+
Regular serialization
+
    +

  1. The serialization of any AST is the serialization of its root node.

    2. +

  2. The serialization of any node is a Tcl list containing at least three +elements.

    +
      +

    1. The first element is the name of the nonterminal symbol stored in the +node.

      2. +

    2. The second and third element are the locations of the first and last +token in the token stream the node represents (covers).

      +
        +

      1. Locations are provided as non-negative integer offsets from the +beginning of the token stream, with the first token found in the +stream located at offset 0 (zero).

        2. +

      2. The end location has to be equal to or larger than the start location.

        3. +
      +
      3. +

    3. All elements after the first three represent the children of the node, +which are themselves nodes. This means that the serializations of +nodes without children, i.e. leaf nodes, have exactly three elements. +The children are stored in the list with the leftmost child first, and +the rightmost child last.

      4. +
    +
    3. +
+
Canonical serialization
+

The canonical serialization of an abstract syntax tree has the format +as specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this tree.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +
+
+

Example

+

Assuming the parsing expression grammar below

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

and the input string

+
 120+5
+

then a parser should deliver the abstract syntax tree below (except for whitespace)

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

Or, more graphical

+

expr_ast

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_introduction.html @@ -0,0 +1,261 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::pegrammar(n) 1 tcllib "Parser Tools"

+

Name

+

pt::pegrammar - Introduction to Parsing Expression Grammars

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the introduction to Parsing Expression Grammars +(short: PEG), the formalism used by the Parser Tools. +It is assumed that the reader has a basic knowledge of parsing theory, +i.e. Context-Free Grammars (short: CFG), +languages, and associated terms like LL(k), +LR(k), terminal and nonterminal symbols, +etc. +We do not intend to recapitulate such basic definitions or terms like +useful, reachable, (left/right) recursive, +nullable, first/last/follow sets, etc. +Please see the References at the end instead if you are in +need of places and books which provide such background information.

+

PEGs are formally very similar to CFGs, with terminal and nonterminal +symbols, start symbol, and rules defining the structure of each +nonterminal symbol. +The main difference lies in the choice(sic!) of choice +operators. Where CFGs use an unordered choice to represent +alternatives PEGs use prioritized choice. Which is fancy way +of saying that a parser has to try the first alternative first and can +try the other alternatives if only if it fails for the first, and so +on.

+

On the CFG side this gives rise to LL(k) and LR(k) for making the +choice deterministic with a bounded lookahead of k +terminal symbols, where LL is in essence topdown aka +recursive descent parsing, and LR bottomup aka +shift reduce parsing.

+

On the PEG side we can parse input with recursive descent and +backtracking of failed choices, the latter of which amounts to +unlimited lookahead. +By additionally recording the success or failure of nonterminals at +the specific locations they were tried at and reusing this information +after backtracking we can avoid the exponential blowup of running time +usually associated with backtracking and keep the parsing linear. The +memory requirements are of course higher due to this cache, as we are +trading space for time.

+

This is the basic concept behind packrat parsers.

+

A limitation pure PEGs share with LL(k) CFGs is that +left-recursive grammars cannot be parsed, with the associated +recursive descent parser entering an infinite recursion. +This limitation is usually overcome by extending pure PEGs with +explicit operators to specify repetition, zero or more, and one or +more, or, formally spoken, for the kleene closure and +positive kleene closure. +This is what the Parser Tools are doing.

+

Another extension, specific to Parser Tools, is a set of operators +which map more or less directly to various character classes built +into Tcl, i.e. the classes reachable via string is.

+

The remainder of this document consists of the formal definition of +PEGs for the mathematically inclined, and an appendix listing +references to places with more information on PEGs specifically, and +parsing in general.

+
+

Formal definition

+

For the mathematically inclined, a Parsing Expression Grammar is a +4-tuple (VN,VT,R,eS) where

+
    +

  • VN is a set of nonterminal symbols,

    • +

  • VT is a set of terminal symbols,

    • +

  • R is a finite set of rules, where each rule is a pair (A,e), A in VN, +and e a parsing expression.

    • +

  • eS is a parsing expression, the start expression.

    • +
+

Further constraints are

+
    +

  • The intersection of VN and VT is empty.

    • +

  • For all A in VT exists exactly one pair (A,e) in R. In other words, R +is a function from nonterminal symbols to parsing expressions.

    • +
+

Parsing expressions are inductively defined via

+
    +

  • The empty string (epsilon) is a parsing expression.

    • +

  • A terminal symbol a is a parsing expression.

    • +

  • A nonterminal symbol A is a parsing expression.

    • +

  • e1e2 is a parsing expression for parsing expressions +e1 and 2. This is called sequence.

    • +

  • e1/e2 is a parsing expression for parsing expressions +e1 and 2. This is called ordered choice.

    • +

  • e* is a parsing expression for parsing expression +e. This is called zero-or-more repetitions, also known +as kleene closure.

    • +

  • e+ is a parsing expression for parsing expression +e. This is called one-or-more repetitions, also known +as positive kleene closure.

    • +

  • !e is a parsing expression for parsing expression +e1. This is called a not lookahead predicate.

    • +

  • &e is a parsing expression for parsing expression +e1. This is called an and lookahead predicate.

    • +
+

PEGs are used to define a grammatical structure for streams of symbols +over VT. They are a modern phrasing of older formalisms invented by +Alexander Birham. These formalisms were called TS (TMG recognition +scheme), and gTS (generalized TS). Later they were renamed to TPDL +(Top-Down Parsing Languages) and gTPDL (generalized TPDL).

+

They can be easily implemented by recursive descent parsers with +backtracking. This makes them relatives of LL(k) Context-Free +Grammars.

+
+

References

+
    +

  1. The Packrat Parsing and Parsing Expression Grammars Page, +by Bryan Ford, Massachusetts Institute of Technology. This is the main +entry page to PEGs, and their realization through Packrat Parsers.

    2. +

  2. http://en.wikipedia.org/wiki/Parsing_expression_grammar +Wikipedia's entry about Parsing Expression Grammars.

    3. +

  3. Parsing Techniques - A Practical Guide , an online book +offering a clear, accessible, and thorough discussion of many +different parsing techniques with their interrelations and +applicabilities, including error recovery techniques.

    4. +

  4. Compilers and Compiler Generators, an online book using +CoCo/R, a generator for recursive descent parsers.

    5. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_language.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_language.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_language.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_language.html @@ -0,0 +1,520 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg_language(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg_language - PEG Language Tutorial

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
+
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

Welcome to the tutorial / introduction for the +PEG Specification Language. +If you are already familiar with the language we are about to discuss, +and only wish to refresh your memory you can, of course, skip ahead to +the aforementioned section and just read the full formal specification.

+
+

What is it?

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+
+

The elements of the language

+

Basic structure

+

The general outline of a textual PEG is

+
+PEG <<name>> (<<start-expression>>)
+   <<rules>>
+END;
+
+

Note: We are using text in double angle-brackets as +place-holders for things not yet explained.

+
+

Names

+

Names are mostly used to identify the nonterminal symbols of the +grammar, i.e. that which occurs on the left-hand side of a <rule>. +The exception to that is the name given after the keyword PEG +(see previous section), which is the name of the whole grammar itself.

+

The structure of a name is simple:

+
    +

  1. It begins with a letter, underscore, or colon, followed by

    2. +

  2. zero or more letters, digits, underscores, or colons.

    3. +
+

Or, in formal textual notation:

+
+    ([_:] / <alpha>) ([_:] / <alnum>)*
+
+

Examples of names:

+
+    Hello
+    ::world
+    _:submarine55_
+
+

Examples of text which are not names:

+
+    12
+    .bogus
+    0wrong
+    @location
+
+
+

Rules

+

The main body of the text of a grammar specification is taken up by +the rules. Each rule defines the sentence structure of one nonterminal +symbol. Their basic structure is

+
+     <<name>>  <-  <<expression>> ;
+
+

The <name> specifies the nonterminal symbol to be defined, the +<expression> after the arrow (<-) then declares its structure.

+

Note that each rule ends in a single semicolon, even the last. +I.e. the semicolon is a rule terminator, not a separator.

+

We can have as many rules as we like, as long as we define each +nonterminal symbol at most once, and have at least one rule for each +nonterminal symbol which occured in an expression, i.e. in either the +start expression of the grammar, or the right-hande side of a rule.

+
+

Expressions

+

The parsing expressions are the meat of any specification. They +declare the structure of the whole document (<<start-expression>>), +and of all nonterminal symbols.

+

All expressions are made up out of atomic expressions and +operators combining them. We have operators for choosing +between alternatives, repetition of parts, and for look-ahead +constraints. There is no explicit operator for the sequencing (also +known as concatenation) of parts however. This is specified by +simply placing the parts adjacent to each other.

+

Here are the operators, from highest to lowest priority (i.e. strength +of binding):

+
+    # Binary operators.
+    <<expression-1>>     <<expression-2>>  # sequence. parse 1, then 2.
+    <<expression-1>>  /  <<expression-2>>  # alternative. try to parse 1, and parse 2 if 1 failed to parse.
+    # Prefix operators. Lookahead constraints. Same priority.
+    & <<expression>>  # Parse expression, ok on successful parse.
+    ! <<expression>>  # Ditto, except ok on failure to parse.
+    # Suffix operators. Repetition. Same priority.
+    <<expression>> ?  # Parse expression none, or once (repeat 0 or 1).
+    <<expression>> *  # Parse expression zero or more times.
+    <<expression>> +  # Parse expression one or more times.
+    # Expression nesting
+    ( <<expression>> ) # Put an expression in parens to change its priority.
+
+

With this we can now deconstruct the formal expression for names given +in section Names:

+
+    ([_:] / <alpha>) ([_:] / <alnum>)*
+
+

It is a sequence of two parts,

+
    [_:] / <alpha>
+

and

+
    ([_:] / <alnum>)*
+

The parentheses around the parts kept their inner alternatives bound +together against the normally higher priority of the sequence. Each of +the two parts is an alternative, with the second part additionally +repeated zero or more times, leaving us with the three atomic +expressions

+
+    [_:]
+    <alpha>
+    <alnum>
+
+

And atomic expressions are our next topic. They +fall into three classes:

+
    +

  1. names, i.e. nonterminal symbols,

    2. +

  2. string literals, and

    3. +

  3. character classes.

    4. +
+

Names we know about already, or see section Names for a +refresher.

+

String literals are simple. They are delimited by (i.e. start and end +with) either a single or double-apostroph, and in between the +delimiters we can have any character but the delimiter itself. They +can be empty as well. Examples of strings are

+
+    ''
+    ""
+    'hello'
+    "umbra"
+    "'"
+    '"'
+
+

The last two examples show how to place any of the delimiters into a +string.

+

For the last, but not least of our atomic expressions, character +classes, we have a number of predefined classes, shown below, and the +ability to construct or own. The predefined classes are:

+
+    <alnum>    # Any unicode alphabet or digit character (string is alnum).
+    <alpha>    # Any unicode alphabet character (string is alpha).
+    <ascii>    # Any unicode character below codepoint 0x80 (string is ascii).
+    <control>  # Any unicode control character (string is control).
+    <ddigit>   # The digit characters [0-9].
+    <digit>    # Any unicode digit character (string is digit).
+    <graph>    # Any unicode printing character, except space (string is graph).
+    <lower>    # Any unicode lower-case alphabet character (string is lower).
+    <print>    # Any unicode printing character, incl. space (string is print).
+    <punct>    # Any unicode punctuation character (string is punct).
+    <space>    # Any unicode space character (string is space).
+    <upper>    # Any unicode upper-case alphabet character (string is upper).
+    <wordchar> # Any unicode word character (string is wordchar).
+    <xdigit>   # The hexadecimal digit characters [0-9a-fA-F].
+    .          # Any character, except end of input.
+
+

And the syntax of custom-defined character classes is

+
+    [ <<range>>* ]
+
+

where each range is either a single character, or of the form

+
+   <<character>> - <character>>
+
+

Examples for character classes we have seen already in the course of +this introduction are

+
+    [_:]
+    [0-9]
+    [0-9a-fA-F]
+
+

We are nearly done with expressions. The only piece left is to tell +how the characters in character classes and string literals are +specified.

+

Basically characters in the input stand for themselves, and in +addition to that we several types of escape syntax to to repesent +control characters, or characters outside of the encoding the text is +in.

+

All the escaped forms are started with a backslash character ('\', +unicode codepoint 0x5C). This is then followed by a series of octal +digits, or 'u' and hexedecimal digits, or a regular character from a +fixed set for various control characters. Some examples:

+
+    \n \r \t \' \" \[ \] \\ #
+    \000 up to \277         # octal escape, all ascii character, leading 0's can be removed.
+    \u2CA7                  # hexadecimal escape, all unicode characters.
+    #                       # Here 2ca7 <=> Koptic Small Letter Tau
+
+
+

Whitespace and comments

+

One issue not touched upon so far is whitespace and comments.

+

Whitespace is any unicode space character, i.e. anything in the +character class <space>, and comments. The latter are sequences of +characters starting with a '#' (hash, unicode codepoint 0x23) and +ending at the next end-of-line.

+

Whitespace can be freely used between all syntactical elements of a +grammar specification. It cannot be used inside of syntactical +elements, like names, string literals, predefined character classes, +etc.

+
+

Nonterminal attributes

+

Lastly, a more advanced topic. In the section Rules we gave +the structure of a rule as

+
+     <<name>>  <-  <<expression>> ;
+
+

This is not quite true. It is possible to associate a semantic mode +with the nonterminal in the rule, by writing it before the name, +separated from it by a colon, i.e. writing

+
+    <<mode>> : <<name>>  <-  <<expression>> ;
+
+

is also allowed. This mode is optional. The known modes and their +meanings are:

+
+
value
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

+
leaf
+

The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

+
void
+

The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

+
+

Of these three modes only leaf and void can be +specified directly. value is implicitly specified by the +absence of a mode before the nonterminal.

+

Now, with all the above under our belt it should be possible to not +only read, but understand the formal specification of the text +representation shown in the next section, written in itself.

+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- "END" WHITESPACE SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG" !([_:] / <alnum>) WHITESPACE ;
+void:   IS              <- "<-"    WHITESPACE ;
+leaf:   VOID            <- "void"  WHITESPACE ; # Implies that definition has no semantic value.
+leaf:   LEAF            <- "leaf"  WHITESPACE ; # Implies that definition has no terminals.
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_op.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_op.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_op.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_op.html @@ -0,0 +1,270 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_peg_op(i) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt_peg_op - Parser Tools PE Grammar Utility Operations

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a number of utility commands manipulating a PE +grammar (container) in various ways.

+
+

API

+
+
::peg::peg::op called container
+

This command determines the static call structure for the nonterminal +symbols of the grammar stored in the container.

+

The result of the command is a dictionary mapping from each +symbol to the symbols it calls. The empty string is the key used to +represent the start expression of the grammar.

+

The grammar in the container is not modified.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op dechain container
+

This command simplifies all symbols which just chain to a different +symbol by inlining the right hand side of the called symbol in its +callers. This works if and only the modes match properly, per the +decision table below.

+
+caller called | dechain | notes
+--------------+---------+-----------------------
+value  value  |  yes    |  value is passed
+value  leaf   |  yes    |  value is passed
+value  void   |  yes    |  caller is implied void
+leaf   value  |  no     |  generated value was discarded, inlined would not. called may be implied void.
+leaf   leaf   |  no     |  s.a.
+leaf   void   |  no     |  s.a.
+void   value  |  no     |  caller drops value, inlined would not.
+void   leaf   |  no     |  s.a.
+void   void   |  yes    |
+
+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op drop unreachable container
+

This command removes all symbols from the grammar which are not +reachable.

+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op drop unrealizable container
+

This command removes all symbols from the grammar which are not +realizable.

+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op flatten container
+

This command flattens (see pt::pe::op) all expressions in +the grammar, i.e. the start expression and the right hand sides of all +nonterminal symbols.

+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op minimize container
+

This command reduces the provided grammar by applying most of the other methods of this package.

+

After flattening the expressions it removes unreachable and +unrealizable symbols, flattens the expressions again, then optimizes +the symbol modes before collapsing symbol chains as much as possible.

+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op modeopt container
+

This command optimizes the semantic modes of non-terminal symbols +according to the two rules below.

+
    +

  1. If a symbol X with mode value calls no other symbols, + i.e. uses only terminal symbols in whatever combination, then + this can be represented simpler by using mode leaf.

    2. +

  2. If a symbol X is only called from symbols with modes + leaf or void then this symbol should have mode + void also, as any AST it could generate will be + discarded anyway.

    3. +
+

The result of the command is the empty string.

+

The grammar in the container is directly modified. If that is +not wanted, a copy of the original container has to be used.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op reachable container
+

This command computes the set of all nonterminal symbols which are +reachable from the start expression of the grammar. This is +essentially the transitive closure over called and the +symbol's right hand sides, beginning with the start expression.

+

The result of the command is the list of reachable symbols.

+

The grammar in the container is not modified.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
::peg::peg::op realizable container
+

This command computes the set of all nonterminal symbols which are +realizable, i.e. can derive pure terminal phrases. This is done +iteratively, starting with state unrealizable for all and any, and +then updating all symbols which are realizable, propagating changes, +until nothing changes any more.

+

The result of the command is the list of realizable symbols.

+

The grammar in the container is not modified.

+

The container instance has to expose a method API as is +provided by the package pt::peg::container.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_container.html @@ -0,0 +1,557 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::container(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::container - PEG Conversion. Write CONTAINER format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::container ?1?
    • +
  • package require pt::peg
    • +
  • package require text::write
    • +
  • package require char
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to CONTAINER markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::container sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::container reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::container configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::container configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::container configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::container convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates CONTAINER markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the CONTAINER format recognizes the following options +and changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-mode bulk|incremental
+

The value of this option controls which methods of +pt::peg::container instances are used to specify the +grammar, i.e. preload it into the container. There are two legal +values, as listed below. The default is bulk.

+
+
bulk
+

In this mode the methods start, add, modes, +and rules are used to specify the grammar in a bulk manner, +i.e. as a set of nonterminal symbols, and two dictionaries mapping +from the symbols to their semantic modes and parsing expressions.

+

This mode is the default.

+
incremental
+

In this mode the methods start, add, mode, +and rule are used to specify the grammar piecemal, with each +nonterminal having its own block of defining commands.

+
+
-template string
+

The value of this option is a string into which to put the generated +code and the other configuration settings. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant CONTAINER.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@mode@
+

To be replaced with the value of the option -mode.

+
@code@
+

To be replaced with the generated code.

+
+
+
+

Grammar Container

+

The container format is another form of describing parsing +expression grammars. While data in this format is executable it does +not constitute a parser for the grammar. It always has to be used in +conjunction with the package pt::peg::interp, a grammar +interpreter.

+

The format represents grammars by a snit::type, i.e. class, +whose instances are API-compatible to the instances of the +pt::peg::container package, and which are preloaded with the +grammar in question.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible CONTAINER serialization for it is

+
+snit::type a_pe_grammar {
+    constructor {} {
+        install myg using pt::peg::container ${selfns}::G
+        $myg start {n Expression}
+        $myg add   AddOp Digit Expression Factor MulOp Number Sign Term
+        $myg modes {
+            AddOp      value
+            Digit      value
+            Expression value
+            Factor     value
+            MulOp      value
+            Number     value
+            Sign       value
+            Term       value
+        }
+        $myg rules {
+            AddOp      {/ {t -} {t +}}
+            Digit      {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}
+            Expression {/ {x {t \50} {n Expression} {t \51}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}}
+            Factor     {x {n Term} {* {x {n AddOp} {n Term}}}}
+            MulOp      {/ {t *} {t /}}
+            Number     {x {? {n Sign}} {+ {n Digit}}}
+            Sign       {/ {t -} {t +}}
+            Term       {n Number}
+        }
+        return
+    }
+    component myg
+    delegate method * to myg
+}
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_cparam.html @@ -0,0 +1,590 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::cparam(n) 1.1.2 tcllib "Parser Tools"

+

Name

+

pt::peg::to::cparam - PEG Conversion. Write CPARAM format

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to CPARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::cparam sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::cparam reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::cparam configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::cparam configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::cparam configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::cparam convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates CPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to C code recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant C/PARAM.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated Tcl code.

+
+

The following options are special, in that they will +occur within the generated code, and are replaced there as well.

+
+
@statedecl@
+

To be replaced with the value of the option state-decl.

+
@stateref@
+

To be replaced with the value of the option state-ref.

+
@strings@
+

To be replaced with the value of the option string-varname.

+
@self@
+

To be replaced with the value of the option self-command.

+
@def@
+

To be replaced with the value of the option fun-qualifier.

+
@ns@
+

To be replaced with the value of the option namespace.

+
@main@
+

To be replaced with the value of the option main.

+
@prelude@
+

To be replaced with the value of the option prelude.

+
+
-state-decl string
+

A C string representing the argument declaration to use in the +generated parsing functions to refer to the parsing state. In essence +type and argument name. +The default value is the string RDE_PARAM p.

+
-state-ref string
+

A C string representing the argument named used in the generated +parsing functions to refer to the parsing state. +The default value is the string p.

+
-self-command string
+

A C string representing the reference needed to call the generated +parser function (methods ...) from another parser fonction, per the +chosen framework (template). +The default value is the empty string.

+
-fun-qualifier string
+

A C string containing the attributes to give to the generated +functions (methods ...), per the chosen framework (template). +The default value is static.

+
-namespace string
+

The name of the C namespace the parser functions (methods, ...) shall +reside in, or a general prefix to add to the function names. +The default value is the empty string.

+
-main string
+

The name of the main function (method, ...) to be called by the chosen +framework (template) to start parsing input. +The default value is __main.

+
-string-varname string
+

The name of the variable used for the table of strings used by the +generated parser, i.e. error messages, symbol names, etc. +The default value is p_string.

+
-prelude string
+

A snippet of code to be inserted at the head of each generated parsing +function. +The default value is the empty string.

+
-indent integer
+

The number of characters to indent each line of the generated code by. +The default value is 0.

+
-comments boolean
+

A flag controlling the generation of code comments containing the +original parsing expression a parsing function is for. +The default value is on.

+
+

While the high parameterizability of this converter, as shown by the +multitude of options it supports, is an advantage to the advanced +user, allowing her to customize the output of the converter as needed, +a novice user will likely not see the forest for the trees.

+

To help these latter users an adjunct package is provided, containing +a canned configuration which will generate immediately useful full +parsers. It is

+
+
pt::cparam::configuration::critcl
+

Generated parsers are embedded into a Critcl-based framework.

+
+
+

C/PARAM code representation of parsing expression grammars

+

The c format is executable code, a parser for the grammar. The +parser implementation is written in C and can be tweaked to the users' +needs through a multitude of options.

+

The critcl format, for example, is implemented as a canned +configuration of these options on top of the generator for c.

+

The bulk of such a framework has to be specified through the option +-template. The additional options

+
+
-fun-qualifier string
+
+
-main string
+
+
-namespace string
+
+
-prelude string
+
+
-self-command string
+
+
-state-decl string
+
+
-state-ref string
+
+
-string-varname string
+
+
+

provide code snippets which help to glue framework and generated code +together. Their placeholders are in the generated code. +Further the options

+
+
-indent integer
+
+
-comments boolean
+
+
+

allow for the customization of the code indent (default none), and +whether to generate comments showing the parsing expressions a +function is for (default on).

+

Example

+

We are forgoing an example of this representation, with apologies. +It would be way to large for this document.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_json.html @@ -0,0 +1,614 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::json(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::json - PEG Conversion. Write JSON format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::json ?1?
    • +
  • package require pt::peg
    • +
  • package require json::write
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to JSON markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::json sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::json reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::json configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::json configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::json configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::json convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates JSON markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the JSON grammar exchange format recognizes the +following configuration variables and changes its behaviour as they +specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-indented boolean
+

If this option is set the system will break the generated JSON across +lines and indent it according to its inner structure, with each key of +a dictionary on a separate line.

+

If the option is not set (the default), the whole JSON object will be +written on a single line, with minimum spacing between all elements.

+
-aligned boolean
+

If this option is set the system will ensure that the values for the +keys in a dictionary are vertically aligned with each other, for a +nice table effect. +To make this work this also implies that -indented is set.

+

If the option is not set (the default), the output is formatted as per +the value of indented, without trying to align the values for +dictionary keys.

+
+
+

JSON Grammar Exchange Format

+

The json format for parsing expression grammars was written as +a data exchange format not bound to Tcl. It was defined to allow the +exchange of grammars with PackRat/PEG based parser generators for +other languages.

+

It is formally specified by the rules below:

+
    +

  1. The JSON of any PEG is a JSON object.

    2. +

  2. This object holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a JSON object holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a JSON object whose keys are the names of the nonterminal +symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a JSON object itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is a JSON string holding the Tcl serialization of the +parsing expression describing the symbols sentennial structure, as +specified in the section PE serialization format.

      +
      mode
      +

      The value is a JSON holding holding one of three values specifying how +a parser should handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is a JSON string holding the Tcl serialization of the start +parsing expression of the grammar, as specified in the section +PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+

As an aside to the advanced reader, this is pretty much the same as +the Tcl serialization of PE grammars, as specified in section +PEG serialization format, except that the Tcl dictionaries +and lists of that format are mapped to JSON objects and arrays. Only +the parsing expressions themselves are not translated further, but +kept as JSON strings containing a nested Tcl list, and there is no +concept of canonicity for the JSON either.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

a JSON serialization for it is

+
+{
+    "pt::grammar::peg" : {
+        "rules" : {
+            "AddOp"     : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Digit"     : {
+                "is"   : "\/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}",
+                "mode" : "value"
+            },
+            "Expression" : {
+                "is"   : "\/ {x {t (} {n Expression} {t )}} {x {n Factor} {* {x {n MulOp} {n Factor}}}}",
+                "mode" : "value"
+            },
+            "Factor"    : {
+                "is"   : "x {n Term} {* {x {n AddOp} {n Term}}}",
+                "mode" : "value"
+            },
+            "MulOp"     : {
+                "is"   : "\/ {t *} {t \/}",
+                "mode" : "value"
+            },
+            "Number"    : {
+                "is"   : "x {? {n Sign}} {+ {n Digit}}",
+                "mode" : "value"
+            },
+            "Sign"      : {
+                "is"   : "\/ {t -} {t +}",
+                "mode" : "value"
+            },
+            "Term"      : {
+                "is"   : "n Number",
+                "mode" : "value"
+            }
+        },
+        "start" : "n Expression"
+    }
+}
+
+

and a Tcl serialization of the same is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+

The similarity of the latter to the JSON should be quite obvious.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_param.html @@ -0,0 +1,1075 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::param(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg::to::param - PEG Conversion. Write PARAM format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::param ?1?
    • +
  • package require pt::peg
    • +
  • package require pt::pe
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to PARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::param sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::param reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::param configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::param configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::param configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::param convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates PARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to PARAM markup recognizes the following configuration +variables and changes its behaviour as they specify.

+
+
-template string
+

The value of this configuration variable is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the configuration variable -user.

+
@format@
+

To be replaced with the the constant PARAM.

+
@file@
+

To be replaced with the value of the configuration variable -file.

+
@name@
+

To be replaced with the value of the configuration variable -name.

+
@code@
+

To be replaced with the generated text.

+
+
-name string
+

The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is a_pe_grammar.

+
-user string
+

The value of this configuration variable is the name of the user for +which the conversion is run. The default value is unknown.

+
-file string
+

The value of this configuration variable is the name of the file or +other entity from which the grammar came, for which the conversion is +run. The default value is unknown.

+
+
+

PARAM code representation of parsing expression grammars

+

The PARAM code representation of parsing expression grammars is +assembler-like text using the instructions of the virtual machine +documented in the PackRat Machine Specification, plus a +few more for control flow (jump ok, jump fail, call symbol, return).

+

It is not really useful, except possibly as a tool demonstrating how a +grammar is compiled in general, without getting distracted by the +incidentials of a framework, i.e. like the supporting C and Tcl code +generated by the other PARAM-derived formats.

+

It has no direct formal specification beyond what was said above.

+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

one possible PARAM serialization for it is

+
+# -*- text -*-
+# Parsing Expression Grammar 'TEMPLATE'.
+# Generated for unknown, from file 'TEST'
+#
+# Grammar Start Expression
+#
+<<MAIN>>:
+         call              sym_Expression
+         halt
+#
+# value Symbol 'AddOp'
+#
+sym_AddOp:
+# /
+#     '-'
+#     '+'
+         symbol_restore    AddOp
+  found! jump              found_7
+         loc_push
+         call              choice_5
+   fail! value_clear
+     ok! value_leaf        AddOp
+         symbol_save       AddOp
+         error_nonterminal AddOp
+         loc_pop_discard
+found_7:
+     ok! ast_value_push
+         return
+choice_5:
+# /
+#     '-'
+#     '+'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t -"
+     ok! test_char         "-"
+         error_pop_merge
+     ok! jump              oknoast_4
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t +"
+     ok! test_char         "+"
+         error_pop_merge
+     ok! jump              oknoast_4
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_4:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Digit'
+#
+sym_Digit:
+# /
+#     '0'
+#     '1'
+#     '2'
+#     '3'
+#     '4'
+#     '5'
+#     '6'
+#     '7'
+#     '8'
+#     '9'
+         symbol_restore    Digit
+  found! jump              found_22
+         loc_push
+         call              choice_20
+   fail! value_clear
+     ok! value_leaf        Digit
+         symbol_save       Digit
+         error_nonterminal Digit
+         loc_pop_discard
+found_22:
+     ok! ast_value_push
+         return
+choice_20:
+# /
+#     '0'
+#     '1'
+#     '2'
+#     '3'
+#     '4'
+#     '5'
+#     '6'
+#     '7'
+#     '8'
+#     '9'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t 0"
+     ok! test_char         "0"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 1"
+     ok! test_char         "1"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 2"
+     ok! test_char         "2"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 3"
+     ok! test_char         "3"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 4"
+     ok! test_char         "4"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 5"
+     ok! test_char         "5"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 6"
+     ok! test_char         "6"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 7"
+     ok! test_char         "7"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 8"
+     ok! test_char         "8"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t 9"
+     ok! test_char         "9"
+         error_pop_merge
+     ok! jump              oknoast_19
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_19:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Expression'
+#
+sym_Expression:
+# /
+#     x
+#         '\('
+#         (Expression)
+#         '\)'
+#     x
+#         (Factor)
+#         *
+#             x
+#                 (MulOp)
+#                 (Factor)
+         symbol_restore    Expression
+  found! jump              found_46
+         loc_push
+         ast_push
+         call              choice_44
+   fail! value_clear
+     ok! value_reduce      Expression
+         symbol_save       Expression
+         error_nonterminal Expression
+         ast_pop_rewind
+         loc_pop_discard
+found_46:
+     ok! ast_value_push
+         return
+choice_44:
+# /
+#     x
+#         '\('
+#         (Expression)
+#         '\)'
+#     x
+#         (Factor)
+#         *
+#             x
+#                 (MulOp)
+#                 (Factor)
+         error_clear
+         ast_push
+         loc_push
+         error_push
+         call              sequence_27
+         error_pop_merge
+     ok! jump              ok_43
+         ast_pop_rewind
+         loc_pop_rewind
+         ast_push
+         loc_push
+         error_push
+         call              sequence_40
+         error_pop_merge
+     ok! jump              ok_43
+         ast_pop_rewind
+         loc_pop_rewind
+         status_fail
+         return
+ok_43:
+         ast_pop_discard
+         loc_pop_discard
+         return
+sequence_27:
+# x
+#     '\('
+#     (Expression)
+#     '\)'
+         loc_push
+         error_clear
+         error_push
+         input_next        "t ("
+     ok! test_char         "("
+         error_pop_merge
+   fail! jump              failednoast_29
+         ast_push
+         error_push
+         call              sym_Expression
+         error_pop_merge
+   fail! jump              failed_28
+         error_push
+         input_next        "t )"
+     ok! test_char         ")"
+         error_pop_merge
+   fail! jump              failed_28
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_28:
+         ast_pop_rewind
+failednoast_29:
+         loc_pop_rewind
+         return
+sequence_40:
+# x
+#     (Factor)
+#     *
+#         x
+#             (MulOp)
+#             (Factor)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_Factor
+         error_pop_merge
+   fail! jump              failed_41
+         error_push
+         call              kleene_37
+         error_pop_merge
+   fail! jump              failed_41
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_41:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+kleene_37:
+# *
+#     x
+#         (MulOp)
+#         (Factor)
+         loc_push
+         error_push
+         call              sequence_34
+         error_pop_merge
+   fail! jump              failed_38
+         loc_pop_discard
+         jump              kleene_37
+failed_38:
+         loc_pop_rewind
+         status_ok
+         return
+sequence_34:
+# x
+#     (MulOp)
+#     (Factor)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_MulOp
+         error_pop_merge
+   fail! jump              failed_35
+         error_push
+         call              sym_Factor
+         error_pop_merge
+   fail! jump              failed_35
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_35:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+#
+# value Symbol 'Factor'
+#
+sym_Factor:
+# x
+#     (Term)
+#     *
+#         x
+#             (AddOp)
+#             (Term)
+         symbol_restore    Factor
+  found! jump              found_60
+         loc_push
+         ast_push
+         call              sequence_57
+   fail! value_clear
+     ok! value_reduce      Factor
+         symbol_save       Factor
+         error_nonterminal Factor
+         ast_pop_rewind
+         loc_pop_discard
+found_60:
+     ok! ast_value_push
+         return
+sequence_57:
+# x
+#     (Term)
+#     *
+#         x
+#             (AddOp)
+#             (Term)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_Term
+         error_pop_merge
+   fail! jump              failed_58
+         error_push
+         call              kleene_54
+         error_pop_merge
+   fail! jump              failed_58
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_58:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+kleene_54:
+# *
+#     x
+#         (AddOp)
+#         (Term)
+         loc_push
+         error_push
+         call              sequence_51
+         error_pop_merge
+   fail! jump              failed_55
+         loc_pop_discard
+         jump              kleene_54
+failed_55:
+         loc_pop_rewind
+         status_ok
+         return
+sequence_51:
+# x
+#     (AddOp)
+#     (Term)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              sym_AddOp
+         error_pop_merge
+   fail! jump              failed_52
+         error_push
+         call              sym_Term
+         error_pop_merge
+   fail! jump              failed_52
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_52:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+#
+# value Symbol 'MulOp'
+#
+sym_MulOp:
+# /
+#     '*'
+#     '/'
+         symbol_restore    MulOp
+  found! jump              found_67
+         loc_push
+         call              choice_65
+   fail! value_clear
+     ok! value_leaf        MulOp
+         symbol_save       MulOp
+         error_nonterminal MulOp
+         loc_pop_discard
+found_67:
+     ok! ast_value_push
+         return
+choice_65:
+# /
+#     '*'
+#     '/'
+         error_clear
+         loc_push
+         error_push
+         input_next        "t *"
+     ok! test_char         "*"
+         error_pop_merge
+     ok! jump              oknoast_64
+         loc_pop_rewind
+         loc_push
+         error_push
+         input_next        "t /"
+     ok! test_char         "/"
+         error_pop_merge
+     ok! jump              oknoast_64
+         loc_pop_rewind
+         status_fail
+         return
+oknoast_64:
+         loc_pop_discard
+         return
+#
+# value Symbol 'Number'
+#
+sym_Number:
+# x
+#     ?
+#         (Sign)
+#     +
+#         (Digit)
+         symbol_restore    Number
+  found! jump              found_80
+         loc_push
+         ast_push
+         call              sequence_77
+   fail! value_clear
+     ok! value_reduce      Number
+         symbol_save       Number
+         error_nonterminal Number
+         ast_pop_rewind
+         loc_pop_discard
+found_80:
+     ok! ast_value_push
+         return
+sequence_77:
+# x
+#     ?
+#         (Sign)
+#     +
+#         (Digit)
+         ast_push
+         loc_push
+         error_clear
+         error_push
+         call              optional_70
+         error_pop_merge
+   fail! jump              failed_78
+         error_push
+         call              poskleene_73
+         error_pop_merge
+   fail! jump              failed_78
+         ast_pop_discard
+         loc_pop_discard
+         return
+failed_78:
+         ast_pop_rewind
+         loc_pop_rewind
+         return
+optional_70:
+# ?
+#     (Sign)
+         loc_push
+         error_push
+         call              sym_Sign
+         error_pop_merge
+   fail! loc_pop_rewind
+     ok! loc_pop_discard
+         status_ok
+         return
+poskleene_73:
+# +
+#     (Digit)
+         loc_push
+         call              sym_Digit
+   fail! jump              failed_74
+loop_75:
+         loc_pop_discard
+         loc_push
+         error_push
+         call              sym_Digit
+         error_pop_merge
+     ok! jump              loop_75
+         status_ok
+failed_74:
+         loc_pop_rewind
+         return
+#
+# value Symbol 'Sign'
+#
+sym_Sign:
+# /
+#     '-'
+#     '+'
+         symbol_restore    Sign
+  found! jump              found_86
+         loc_push
+         call              choice_5
+   fail! value_clear
+     ok! value_leaf        Sign
+         symbol_save       Sign
+         error_nonterminal Sign
+         loc_pop_discard
+found_86:
+     ok! ast_value_push
+         return
+#
+# value Symbol 'Term'
+#
+sym_Term:
+# (Number)
+         symbol_restore    Term
+  found! jump              found_89
+         loc_push
+         ast_push
+         call              sym_Number
+   fail! value_clear
+     ok! value_reduce      Term
+         symbol_save       Term
+         error_nonterminal Term
+         ast_pop_rewind
+         loc_pop_discard
+found_89:
+     ok! ast_value_push
+         return
+#
+#
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_peg.html @@ -0,0 +1,598 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::peg(n) 1.0.2 tcllib "Parser Tools"

+

Name

+

pt::peg::to::peg - PEG Conversion. Write PEG format

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::peg::to::peg ?1.0.2?
    • +
  • package require pt::peg
    • +
  • package require pt::pe
    • +
  • package require text::write
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to PEG markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::peg sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::peg reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::peg configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::peg configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::peg configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::peg convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates PEG markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to the PEG language recognizes the following options and +changes its behaviour as they specify.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
-template string
+

The value of this option is a string into which to put the generated +text and the values of the other options. The various locations for +user-data are expected to be specified with the placeholders listed +below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the option -user.

+
@format@
+

To be replaced with the the constant PEG.

+
@file@
+

To be replaced with the value of the option -file.

+
@name@
+

To be replaced with the value of the option -name.

+
@code@
+

To be replaced with the generated text.

+
+
+
+

PEG Specification Language

+

peg, a language for the specification of parsing expression +grammars is meant to be human readable, and writable as well, yet +strict enough to allow its processing by machine. Like any computer +language. It was defined to make writing the specification of a +grammar easy, something the other formats found in the Parser Tools do +not lend themselves too.

+

It is formally specified by the grammar shown below, written in +itself. For a tutorial / introduction to the language please go and +read the PEG Language Tutorial.

+
+PEG pe-grammar-for-peg (Grammar)
+	# --------------------------------------------------------------------
+        # Syntactical constructs
+        Grammar         <- WHITESPACE Header Definition* Final EOF ;
+        Header          <- PEG Identifier StartExpr ;
+        Definition      <- Attribute? Identifier IS Expression SEMICOLON ;
+        Attribute       <- (VOID / LEAF) COLON ;
+        Expression      <- Sequence (SLASH Sequence)* ;
+        Sequence        <- Prefix+ ;
+        Prefix          <- (AND / NOT)? Suffix ;
+        Suffix          <- Primary (QUESTION / STAR / PLUS)? ;
+        Primary         <- ALNUM / ALPHA / ASCII / CONTROL / DDIGIT / DIGIT
+                        /  GRAPH / LOWER / PRINTABLE / PUNCT / SPACE / UPPER
+                        /  WORDCHAR / XDIGIT
+                        / Identifier
+                        /  OPEN Expression CLOSE
+                        /  Literal
+                        /  Class
+                        /  DOT
+                        ;
+        Literal         <- APOSTROPH  (!APOSTROPH  Char)* APOSTROPH  WHITESPACE
+                        /  DAPOSTROPH (!DAPOSTROPH Char)* DAPOSTROPH WHITESPACE ;
+        Class           <- OPENB (!CLOSEB Range)* CLOSEB WHITESPACE ;
+        Range           <- Char TO Char / Char ;
+        StartExpr       <- OPEN Expression CLOSE ;
+void:   Final           <- "END" WHITESPACE SEMICOLON WHITESPACE ;
+        # --------------------------------------------------------------------
+        # Lexing constructs
+        Identifier      <- Ident WHITESPACE ;
+leaf:   Ident           <- ([_:] / <alpha>) ([_:] / <alnum>)* ;
+        Char            <- CharSpecial / CharOctalFull / CharOctalPart
+                        /  CharUnicode / CharUnescaped
+                        ;
+leaf:   CharSpecial     <- "\\" [nrt'"\[\]\\] ;
+leaf:   CharOctalFull   <- "\\" [0-2][0-7][0-7] ;
+leaf:   CharOctalPart   <- "\\" [0-7][0-7]? ;
+leaf:   CharUnicode     <- "\\" 'u' HexDigit (HexDigit (HexDigit HexDigit?)?)? ;
+leaf:   CharUnescaped   <- !"\\" . ;
+void:   HexDigit        <- [0-9a-fA-F] ;
+void:   TO              <- '-'           ;
+void:   OPENB           <- "["           ;
+void:   CLOSEB          <- "]"           ;
+void:   APOSTROPH       <- "'"           ;
+void:   DAPOSTROPH      <- '"'           ;
+void:   PEG             <- "PEG" !([_:] / <alnum>) WHITESPACE ;
+void:   IS              <- "<-"    WHITESPACE ;
+leaf:   VOID            <- "void"  WHITESPACE ; # Implies that definition has no semantic value.
+leaf:   LEAF            <- "leaf"  WHITESPACE ; # Implies that definition has no terminals.
+void:   SEMICOLON       <- ";"     WHITESPACE ;
+void:   COLON           <- ":"     WHITESPACE ;
+void:   SLASH           <- "/"     WHITESPACE ;
+leaf:   AND             <- "&"     WHITESPACE ;
+leaf:   NOT             <- "!"     WHITESPACE ;
+leaf:   QUESTION        <- "?"     WHITESPACE ;
+leaf:   STAR            <- "*"     WHITESPACE ;
+leaf:   PLUS            <- "+"     WHITESPACE ;
+void:   OPEN            <- "("     WHITESPACE ;
+void:   CLOSE           <- ")"     WHITESPACE ;
+leaf:   DOT             <- "."     WHITESPACE ;
+leaf:   ALNUM           <- "<alnum>"    WHITESPACE ;
+leaf:   ALPHA           <- "<alpha>"    WHITESPACE ;
+leaf:   ASCII           <- "<ascii>"    WHITESPACE ;
+leaf:   CONTROL         <- "<control>"  WHITESPACE ;
+leaf:   DDIGIT          <- "<ddigit>"   WHITESPACE ;
+leaf:   DIGIT           <- "<digit>"    WHITESPACE ;
+leaf:   GRAPH           <- "<graph>"    WHITESPACE ;
+leaf:   LOWER           <- "<lower>"    WHITESPACE ;
+leaf:   PRINTABLE       <- "<print>"    WHITESPACE ;
+leaf:   PUNCT           <- "<punct>"    WHITESPACE ;
+leaf:   SPACE           <- "<space>"    WHITESPACE ;
+leaf:   UPPER           <- "<upper>"    WHITESPACE ;
+leaf:   WORDCHAR        <- "<wordchar>" WHITESPACE ;
+leaf:   XDIGIT          <- "<xdigit>"   WHITESPACE ;
+void:   WHITESPACE      <- (" " / "\t" / EOL / COMMENT)* ;
+void:   COMMENT         <- '#' (!EOL .)* EOL ;
+void:   EOL             <- "\n\r" / "\n" / "\r" ;
+void:   EOF             <- !. ;
+        # --------------------------------------------------------------------
+END;
+
+

Example

+

Our example specifies the grammar for a basic 4-operation calculator.

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

Using higher-level features of the notation, i.e. the character +classes (predefined and custom), this example can be rewritten as

+
+PEG calculator (Expression)
+    Sign       <- [-+] 						;
+    Number     <- Sign? <ddigit>+				;
+    Expression <- '(' Expression ')' / (Factor (MulOp Factor)*)	;
+    MulOp      <- [*/]						;
+    Factor     <- Term (AddOp Term)*				;
+    AddOp      <- [-+]						;
+    Term       <- Number					;
+END;
+
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html Index: embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html +++ embedded/www/tcllib/files/modules/pt/pt_peg_to_tclparam.html @@ -0,0 +1,561 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg::to::tclparam(n) 1.0.3 tcllib "Parser Tools"

+

Name

+

pt::peg::to::tclparam - PEG Conversion. Write TCLPARAM format

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package implements the converter from parsing expression grammars +to TCLPARAM markup.

+

It resides in the Export section of the Core Layer of Parser Tools, +and can be used either directly with the other packages of this layer, +or indirectly through the export manager provided by +pt::peg::export. The latter is intented for use in untrusted +environments and done through the corresponding export plugin +pt::peg::export::tclparam sitting between converter +and export manager.

+

arch_core_eplugins

+
+

API

+

The API provided by this package satisfies the specification of the +Converter API found in the Parser Tools Export API +specification.

+
+
pt::peg::to::tclparam reset
+

This command resets the configuration of the package to its default +settings.

+
pt::peg::to::tclparam configure
+

This command returns a dictionary containing the current configuration +of the package.

+
pt::peg::to::tclparam configure option
+

This command returns the current value of the specified configuration +option of the package. For the set of legal options, please read +the section Options.

+
pt::peg::to::tclparam configure option value...
+

This command sets the given configuration options of the +package, to the specified values. For the set of legal options, +please read the section Options.

+
pt::peg::to::tclparam convert serial
+

This command takes the canonical serialization of a parsing expression +grammar, as specified in section PEG serialization format, +and contained in serial, and generates TCLPARAM markup +encoding the grammar, per the current package configuration. +The created string is then returned as the result of the command.

+
+
+

Options

+

The converter to Tcl/PARAM markup recognizes the following +configuration variables and changes its behaviour as they specify.

+
+
-template string
+

The value of this configuration variable is a string into which to put +the generated text and the other configuration settings. The various +locations for user-data are expected to be specified with the +placeholders listed below. The default value is "@code@".

+
+
@user@
+

To be replaced with the value of the configuration variable -user.

+
@format@
+

To be replaced with the the constant Tcl/PARAM.

+
@file@
+

To be replaced with the value of the configuration variable -file.

+
@name@
+

To be replaced with the value of the configuration variable -name.

+
@code@
+

To be replaced with the generated Tcl code.

+
+

The following configuration variables are special, in that they will +occur within the generated code, and are replaced there as well.

+
+
@runtime@
+

To be replaced with the value of the configuration variable runtime-command.

+
@self@
+

To be replaced with the value of the configuration variable self-command.

+
@def@
+

To be replaced with the value of the configuration variable proc-command.

+
@ns@
+

To be replaced with the value of the configuration variable namespace.

+
@main@
+

To be replaced with the value of the configuration variable main.

+
@prelude@
+

To be replaced with the value of the configuration variable prelude.

+
+
-name string
+

The value of this configuration variable is the name of the grammar +for which the conversion is run. The default value is a_pe_grammar.

+
-user string
+

The value of this configuration variable is the name of the user for +which the conversion is run. The default value is unknown.

+
-file string
+

The value of this configuration variable is the name of the file or +other entity from which the grammar came, for which the conversion is +run. The default value is unknown.

+
-runtime-command string
+

A Tcl string representing the Tcl command or reference to it used to +call PARAM instruction from parser procedures, per the chosen +framework (template). +The default value is the empty string.

+
-self-command string
+

A Tcl string representing the Tcl command or reference to it used to +call the parser procedures (methods ...) from another parser +procedure, per the chosen framework (template). +The default value is the empty string.

+
-proc-command string
+

The name of the Tcl command used to define procedures (methods ...), +per the chosen framework (template). +The default value is proc.

+
-namespace string
+

The name of the namespace the parser procedures (methods, ...) shall +reside in, including the trailing '::' needed to separate it from the +actual procedure name. +The default value is ::.

+
-main string
+

The name of the main procedure (method, ...) to be called by the +chosen framework (template) to start parsing input. +The default value is __main.

+
-prelude string
+

A snippet of code to be insert at the head of each generated parsing +command. +The default value is the empty string.

+
-indent integer
+

The number of characters to indent each line of the generated code by. +The default value is 0.

+
+

While the high parameterizability of this converter, as shown by the +multitude of options it supports, is an advantage to the advanced +user, allowing her to customize the output of the converter as needed, +a novice user will likely not see the forest for the trees.

+

To help these latter users two adjunct packages are provided, each +containing a canned configuration which will generate immediately +useful full parsers. These are

+
+
pt::tclparam::configuration::snit
+

Generated parsers are classes based on the snit package, +i.e. snit::type's.

+
pt::tclparam::configuration::tcloo
+

Generated parsers are classes based on the OO package.

+
+
+

Tcl/PARAM code representation of parsing expression grammars

+

The Tcl/PARAM representation of parsing expression grammars is Tcl +code whose execution will parse input per the grammar. The code is +based on the virtual machine documented in the +PackRat Machine Specification, using its instructions +and a few more to handle control flow.

+

Note that the generated code by itself is not functional. It expects +to be embedded into a framework which provides services like the PARAM +state, implementations for the PARAM instructions, etc. +The bulk of such a framework has to be specified through the option +-template. The additional options

+
+
-indent integer
+
+
-main string
+
+
-namespace string
+
+
-prelude string
+
+
-proc-command string
+
+
-runtime-command string
+
+
-self-command string
+
+
+

provide code snippets which help to glue framework and generated code +together. Their placeholders are in the generated code.

+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pegrammar.html Index: embedded/www/tcllib/files/modules/pt/pt_pegrammar.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_pegrammar.html +++ embedded/www/tcllib/files/modules/pt/pt_pegrammar.html @@ -0,0 +1,475 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::peg(n) 1 tcllib "Parser Tools"

+

Name

+

pt::peg - Parsing Expression Grammar Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +parsing expression grammars as managed by the Parser Tools, and +specified in section PEG serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::peg verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of a parsing expression and will throw an error if that +is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::peg verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a PEG and will throw an error if +that is not the case. The result of the command is the empty string.

+

For the specification of canonical serializations see the section +PEG serialization format.

+
::pt::peg canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a PEG and will throw an error if that +is not the case.

+

It will then convert the input into the canonical serialization +of the contained PEG and return it as its result. If the input is +already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section PEG serialization format.

+
::pt::peg print serial
+

This command assumes that the argument serial contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +PEG serialization format.

+
::pt::peg merge seriala serialb
+

This command accepts the regular serializations of two grammars and +uses them to create their union. The result of the command is the +canonical serialization of this unified grammar.

+

A merge errors occurs if for any nonterminal symbol S occuring in both +input grammars the two input grammars specify different semantic +modes.

+

The semantic mode of each nonterminal symbol S is the semantic mode of +S in any of its input grammars. The previous rule made sure that for +symbols occuring in both grammars these values are identical.

+

The right-hand side of each nonterminal symbol S occuring in both +input grammars is the choice between the right-hand sides of S in the +input grammars, with the parsing expression of S in seriala +coming first, except if both expressions are identical. In that case +the first expression is taken.

+

The right-hand side of each nonterminal symbol S occuring in only one +of the input grammars is the right-hand side of S in its input +grammar.

+

The start expression of the unified grammar is the choice between the +start expressions of the input grammars, with the start expression of +seriala coming first, except if both expressions are identical. +In that case the first expression is taken

+
::pt::peg equal seriala serialb
+

This command tests the two grammars seriala and serialb +for structural equality. The result of the command is a boolean +value. It will be set to true if the expressions are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two grammars +are pure Tcl lists and dictionaries.

+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html Index: embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html +++ embedded/www/tcllib/files/modules/pt/pt_pexpr_op.html @@ -0,0 +1,338 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::pe::op(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::pe::op - Parsing Expression Utilities

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::pe::op ?1.0.1?
    • +
  • package require pt::pe ?1?
    • +
  • package require struct::set
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides additional commands to work with the +serializations of parsing expressions as managed by the PEG and +related packages, and specified in section +PE serialization format.

+

This is an internal package, for use by the higher level packages +handling PEGs, their conversion into and out of various other formats, +or other uses.

+
+

API

+
+
::pt::pe::op drop dropset pe
+

This command removes all occurences of any of the nonterminals symbols +in the set dropset from the parsing expression pe, and +simplifies it. This may result in the expression becoming "epsilon", +i.e. matching nothing.

+
::pt::pe::op rename nt ntnew pe
+

This command renames all occurences of the nonterminal nt in the +parsing expression pe into ntnew.

+
::pt::pe::op called pe
+

This command extracts the set of all nonterminal symbols used, +i.e. 'called', in the parsing expression pe.

+
::pt::pe::op flatten pe
+

This command transforms the parsing expression by eliminating +sequences nested in sequences, and choices in choices, lifting the +children of the nested expression into the parent. It further +eliminates all sequences and choices with only one child, as these are +redundant.

+

The resulting parsing expression is returned as the result of the +command.

+
::pt::pe::op fusechars pe
+

This command transforms the parsing expression by fusing adjacent +terminals in sequences and adjacent terminals and ranges in choices, +it (re)constructs highlevel strings and +character classes.

+

The resulting pseudo-parsing expression is returned as the result of +the command and may contain the pseudo-operators str for +character sequences, aka strings, and cl for character +choices, aka character classes.

+

The result is called a pseudo-parsing expression because it +is not a true parsing expression anymore, and will fail a check with +::pt::peg verify if the new pseudo-operators +are present in the result, but is otherwise of sound structure for a +parsing expression. +Notably, the commands ::pt::peg bottomup and +::pt::peg topdown will process them without +trouble.

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pexpression.html Index: embedded/www/tcllib/files/modules/pt/pt_pexpression.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_pexpression.html +++ embedded/www/tcllib/files/modules/pt/pt_pexpression.html @@ -0,0 +1,464 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::pe(n) 1.0.1 tcllib "Parser Tools"

+

Name

+

pt::pe - Parsing Expression Serialization

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides commands to work with the serializations of +parsing expressions as managed by the Parser Tools, and specified in +section PE serialization format.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::pe verify serial ?canonvar?
+

This command verifies that the content of serial is a valid +serialization of a parsing expression and will throw an error if that +is not the case. The result of the command is the empty string.

+

If the argument canonvar is specified it is interpreted as the +name of a variable in the calling context. This variable will be +written to if and only if serial is a valid regular +serialization. Its value will be a boolean, with True +indicating that the serialization is not only valid, but also +canonical. False will be written for a valid, but +non-canonical serialization.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::pe verify-as-canonical serial
+

This command verifies that the content of serial is a valid +canonical serialization of a parsing expression and will throw +an error if that is not the case. The result of the command is the +empty string.

+

For the specification of canonical serializations see the section +PE serialization format.

+
::pt::pe canonicalize serial
+

This command assumes that the content of serial is a valid +regular serialization of a parsing expression and will throw an +error if that is not the case.

+

It will then convert the input into the canonical serialization +of this parsing expression and return it as its result. If the input +is already canonical it will be returned unchanged.

+

For the specification of regular and canonical serializations see the +section PE serialization format.

+
::pt::pe print serial
+

This command assumes that the argument serial contains a valid +serialization of a parsing expression and returns a string containing +that PE in a human readable form.

+

The exact format of this form is not specified and cannot be relied on +for parsing or other machine-based activities.

+

For the specification of serializations see the section +PE serialization format.

+
::pt::pe bottomup cmdprefix pe
+

This command walks the parsing expression pe from the bottom up +to the root, invoking the command prefix cmdprefix for each +partial expression. This implies that the children of a parsing +expression PE are handled before PE.

+

The command prefix has the signature

+
+
cmdprefix pe op arguments
+

I.e. it is invoked with the parsing expression pe the walk is +currently at, the op'erator in the pe, and the operator's +arguments.

+

The result returned by the command prefix replaces pe in the +parsing expression it was a child of, allowing transformations of the +expression tree.

+

This also means that for all inner parsing expressions the contents of +arguments are the results of the command prefix invoked for the +children of this inner parsing expression.

+
+
::pt::pe topdown cmdprefix pe
+

This command walks the parsing expression pe from the root down +to the leaves, invoking the command prefix cmdprefix for each +partial expression. This implies that the children of a parsing +expression PE are handled after PE.

+

The command prefix has the same signature as for bottomup, +see above.

+

The result returned by the command prefix is ignored.

+
::pt::pe equal seriala serialb
+

This command tests the two parsing expressions seriala and +serialb for structural equality. The result of the command is a +boolean value. It will be set to true if the expressions are +identical, and false otherwise.

+

String equality is usable only if we can assume that the two parsing +expressions are pure Tcl lists.

+
::pt::pe epsilon
+

This command constructs the atomic parsing expression for epsilon.

+
::pt::pe dot
+

This command constructs the atomic parsing expression for dot.

+
::pt::pe alnum
+

This command constructs the atomic parsing expression for alnum.

+
::pt::pe alpha
+

This command constructs the atomic parsing expression for alpha.

+
::pt::pe ascii
+

This command constructs the atomic parsing expression for ascii.

+
::pt::pe control
+

This command constructs the atomic parsing expression for control.

+
::pt::pe digit
+

This command constructs the atomic parsing expression for digit.

+
::pt::pe graph
+

This command constructs the atomic parsing expression for graph.

+
::pt::pe lower
+

This command constructs the atomic parsing expression for lower.

+
::pt::pe print
+

This command constructs the atomic parsing expression for print.

+
::pt::pe punct
+

This command constructs the atomic parsing expression for punct.

+
::pt::pe space
+

This command constructs the atomic parsing expression for space.

+
::pt::pe upper
+

This command constructs the atomic parsing expression for upper.

+
::pt::pe wordchar
+

This command constructs the atomic parsing expression for wordchar.

+
::pt::pe xdigit
+

This command constructs the atomic parsing expression for xdigit.

+
::pt::pe ddigit
+

This command constructs the atomic parsing expression for ddigit.

+
::pt::pe terminal t
+

This command constructs the atomic parsing expression for the terminal +symbol t.

+
::pt::pe range ta tb
+

This command constructs the atomic parsing expression for the range of +terminal symbols ta ... tb.

+
::pt::pe nonterminal nt
+

This command constructs the atomic parsing expression for the +nonterminal symbol nt.

+
::pt::pe choice pe...
+

This command constructs the parsing expression representing the +ordered or prioritized choice between the argument parsing +expressions. The first argument has the highest priority.

+
::pt::pe sequence pe...
+

This command constructs the parsing expression representing the +sequence of the argument parsing expression. The first argument is the +first element of the sequence.

+
::pt::pe repeat0 pe
+

This command constructs the parsing expression representing the zero +or more repetition of the argument parsing expression pe, also +known as the kleene closure.

+
::pt::pe repeat1 pe
+

This command constructs the parsing expression representing the one or +more repetition of the argument parsing expression pe, also +known as the positive kleene closure.

+
::pt::pe optional pe
+

This command constructs the parsing expression representing the +optionality of the argument parsing expression pe.

+
::pt::pe ahead pe
+

This command constructs the parsing expression representing the +positive lookahead of the argument parsing expression pe.

+
::pt::pe notahead pe
+

This command constructs the parsing expression representing the +negative lookahead of the argument parsing expression pe.

+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_pgen.html Index: embedded/www/tcllib/files/modules/pt/pt_pgen.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_pgen.html +++ embedded/www/tcllib/files/modules/pt/pt_pgen.html @@ -0,0 +1,291 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::pgen(n) 1.0.2 tcllib "Parser Tools"

+

Name

+

pt::pgen - Parser Generator

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::pgen ?1.0.2?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a command implementing a +parser generator +taking parsing expression grammars as input.

+

It is the implementation of method generate of pt, the +Parser Tools Application.

+

As such the intended audience of this document are people wishing to +modify and/or extend this part of pt's functionality. Users of +pt on the other hand are hereby refered to the applications' +manpage, i.e. Parser Tools Application.

+

It resides in the User Package Layer of Parser Tools.

+

arch_user_pkg

+
+

API

+
+
::pt::pgen inputformat text resultformat ?options...?
+

This command takes the parsing expression grammar in text (in +the format specified by inputformat), and returns the same +grammar in the format resultformat as the result of the command.

+

The two known input formats are peg and json. +Introductions to them, including their formal specifications, can be +found in the PEG Language Tutorial and +The JSON Grammar Exchange Format. The packages used to +parse these formats are

+
+
peg
+

pt::peg::from::peg

+
json
+

pt::peg::from::json

+
+

On the output side the known formats, and the packages used to +generate them are

+
+
c
+

pt::peg::to::cparam

+
container
+

pt::peg::to::container

+
critcl
+

pt::peg::to::cparam + + pt::cparam::configuration::critcl

+
json
+

pt::peg::to::json

+
oo
+

pt::peg::to::tclparam + + pt::tclparam::configuration::tcloo

+
peg
+

pt::peg::to::peg

+
snit
+

pt::peg::to::tclparam + + pt::tclparam::configuration::snit

+
+

The options supported by each of these formats are documented +with their respective packages.

+
+
+

Example

+

In this section we are working a complete example, starting with a PEG +grammar and ending with running the parser generated from it over some +input, following the outline shown in the figure below:

+

flow

+

Our grammar, assumed to the stored in the file "calculator.peg" +is

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

From this we create a snit-based parser +using the script "gen"

+
+package require Tcl 8.5
+package require fileutil
+package require pt::pgen
+lassign $argv name
+set grammar [fileutil::cat $name.peg]
+set pclass  [pt::pgen peg $gr snit -class $name -file  $name.peg -name  $name]
+fileutil::writeFile $name.tcl $pclass
+exit 0
+
+

calling it like

+
 tclsh8.5 gen calculator
+

which leaves us with the parser package and class written to the file +"calculator.tcl". +Assuming that this package is then properly installed in a place where +Tcl can find it we can now use this class via a script like

+
+    package require calculator
+    lassign $argv input
+    set channel [open $input r]
+    set parser [calculator]
+    set ast [$parser parse $channel]
+    $parser destroy
+    close $channel
+    ... now process the returned abstract syntax tree ...
+
+

where the abstract syntax tree stored in the variable will look like

+
+set ast {Expression 0 4
+    {Factor 0 4
+        {Term 0 2
+            {Number 0 2
+                {Digit 0 0}
+                {Digit 1 1}
+                {Digit 2 2}
+            }
+        }
+        {AddOp 3 3}
+        {Term 4 4
+            {Number 4 4
+                {Digit 4 4}
+            }
+        }
+    }
+}
+
+

assuming that the input file and channel contained the text

+
 120+5
+

A more graphical representation of the tree would be

+

expr_ast

+

Regardless, at this point it is the user's responsibility to work with +the tree to reach whatever goal she desires. I.e. analyze it, +transform it, etc. The package pt::ast should be of help +here, providing commands to walk such ASTs structures in various ways.

+

One important thing to note is that the parsers used here return a +data structure representing the structure of the input per the grammar +underlying the parser. There are no callbacks during the +parsing process, i.e. no parsing actions, as most other +parsers will have.

+

Going back to the last snippet of code, the execution of the parser +for some input, note how the parser instance follows the specified +Parser API.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_rdengine.html Index: embedded/www/tcllib/files/modules/pt/pt_rdengine.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_rdengine.html +++ embedded/www/tcllib/files/modules/pt/pt_rdengine.html @@ -0,0 +1,824 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::rde(n) 1.1 tcllib "Parser Tools"

+

Name

+

pt::rde - Parsing Runtime Support, PARAM based

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::rde ?1.1?
    • +
  • package require snit
    • +
  • package require struct::stack 1.5
    • +
  • package require pt::ast 1.1
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides a class whose instances provide the runtime +support for recursive descent parsers with backtracking, as is needed +for the execution of, for example, parsing expression grammars. It +implements the PackRat Machine Specification, as such that +document is required reading to understand both this manpage, +and the package itself. The description below does make numerous +shorthand references to the PARAM's instructions and the various parts +of its architectural state.

+

The package resides in the Execution section of the Core Layer of +Parser Tools.

+

arch_core_transform

+

Note: This package not only has the standard Tcl implementation, but +also an accelerator, i.e. a C implementation, based on Critcl.

+

Class API

+

The package exports the API described here.

+
+
::pt::rde objectName
+

The command creates a new runtime object for a recursive descent +parser with backtracking and returns the fully qualified name of the +object command as its result. The API of this object command is +described in the section Object API. It may be used to +invoke various operations on the object.

+
+
+

Object API

+

All objects created by this package provide the following 63 methods +for the manipulation and querying of their state, which is, in essence +the architectural state of a PARAM.

+

First some general methods and the state accessors.

+
+
objectName destroy
+

This method destroys the object, releasing all claimed memory, and +deleting the associated object command.

+
objectName reset chan
+

This method resets the state of the runtme to its defaults, preparing +it for the parsing of the character in the channel chan, which +becomes IN.

+

Note here that the Parser Tools are based on Tcl 8.5+. In other words, +the channel argument is not restricted to files, sockets, etc. We have +the full power of reflected channels available.

+

It should also be noted that the parser pulls the characters from the +input stream as it needs them. If a parser created by this package has +to be operated in a push aka event-driven manner it will be necessary +to go to Tcl 8.6+ and use the coroutine::auto to wrap it +into a coroutine where read is properly changed for +push-operation.

+
objectName complete
+

This method completes parsing, either returning the AST made from the +elements of ARS, or throwing an error containing the current ER.

+
objectName chan
+

This method returns the handle of the channel which is IN.

+
objectName line
+

This method returns the line number for the position IN is currently +at. Note that this may not match with the line number for CL, due to +backtracking.

+
objectName column
+

This method returns the column for the position IN is currently +at. Note that this may not match with the column for CL, due to +backtracking.

+
objectName current
+

This method returns CC.

+
objectName location
+

This method returns CL.

+
objectName locations
+

This method returns the LS. The topmost entry of the stack will be the +first element of the returned list.

+
objectName ok
+

This method returns ST.

+
objectName value
+

This method returns SV.

+
objectName error
+

This method returns ER. This is either the empty string for an empty +ER, or a list of 2 elements, the location the error is for, and a set +of messages which specify which symbols were expected at the +location. The messages are encoded as one of the possible atomic +parsing expressions (special operators, terminal, range, and +nonterminal operator).

+
objectName errors
+

This method returns ES. The topmost entry of the stack will be the +first element of the returned list. Each entry is encoded as described +for error.

+
objectName tokens ?from ?to??
+

This method returns the part of TC for the range of locations of IN +starting at from and ending at to. If to is not +specified it is taken as identical to from. If neither argument +is specified the whole of TC is returned.

+

Each token in the returned list is a list of three elements itself, +containing the character at the location, and the associated line and +column numbers, in this order.

+
objectName symbols
+

This method returns a dictionary containing NC. Keys are two-element +lists containing nonterminal symbol and location, in this order. The +values are 4-tuples containing CL, ST, ER, and SV, in this order. ER +is encoded as specified for the method error.

+
objectName known
+

This method returns a list containing the keys of SC. They are +encoded in the same manner as is done by method symbols.

+
objectName reducible
+

This method returns ARS. The topmost entry of the stack will be the +first element of the returned list

+
objectName asts
+

This method returns AS. The topmost entry of the stack will be the +first element of the returned list

+
objectName ast
+

This is a convenience method returning the topmost element of ARS.

+
objectName position loc
+

This method returns the line and column numbers for the specified +location of IN, assuming that this location has already been reached +during the parsing process.

+
+

The following methods implement all PARAM instructions. They all have +the prefix "i_".

+

The control flow is mainly provided by Tcl's builtin commands, like +if, while, etc., plus a few guarded variants of PARAM +instructions and Tcl commands.. That means that these instruction +variants will do nothing if their guard condition is not +fulfilled. They can be recognized by the prefix "i:ok_" and "i:fail_", +which denote the value ST has to have for the instruction to execute.

+

The instructions are listed in the same order they occur in the +PackRat Machine Specification, with the guard variants +listed after their regular implementation, if any, or in their place.

+
+
objectName i_input_next msg
+

This method implements the PARAM instruction input_next.

+
objectName i_test_alnum
+

This method implements the PARAM instruction test_alnum.

+
objectName i_test_alpha
+

This method implements the PARAM instruction test_alpha.

+
objectName i_test_ascii
+

This method implements the PARAM instruction test_ascii.

+
objectName i_test_char char
+

This method implements the PARAM instruction test_char.

+
objectName i_test_ddigit
+

This method implements the PARAM instruction test_ddigit.

+
objectName i_test_digit
+

This method implements the PARAM instruction test_digit.

+
objectName i_test_graph
+

This method implements the PARAM instruction test_graph.

+
objectName i_test_lower
+

This method implements the PARAM instruction test_lower.

+
objectName i_test_print
+

This method implements the PARAM instruction test_print.

+
objectName i_test_punct
+

This method implements the PARAM instruction test_punct.

+
objectName i_test_range chars chare
+

This method implements the PARAM instruction test_range.

+
objectName i_test_space
+

This method implements the PARAM instruction test_space.

+
objectName i_test_upper
+

This method implements the PARAM instruction test_upper.

+
objectName i_test_wordchar
+

This method implements the PARAM instruction test_wordchar.

+
objectName i_test_xdigit
+

This method implements the PARAM instruction test_xdigit.

+
objectName i_error_clear
+

This method implements the PARAM instruction error_clear.

+
objectName i_error_push
+

This method implements the PARAM instruction error_push.

+
objectName i_error_pop_merge
+

This method implements the PARAM instruction error_pop_merge.

+
objectName i_error_nonterminal symbol
+

This method implements the PARAM instruction error_nonterminal.

+
objectName i_status_ok
+

This method implements the PARAM instruction status_ok.

+
objectName i_status_fail
+

This method implements the PARAM instruction status_fail.

+
objectName i_status_negate
+

This method implements the PARAM instruction status_negate.

+
objectName i_loc_push
+

This method implements the PARAM instruction loc_push.

+
objectName i_loc_pop_discard
+

This method implements the PARAM instruction loc_pop_discard.

+
objectName i_loc_pop_rewind
+

This method implements the PARAM instruction loc_pop_rewind.

+
objectName i:ok_loc_pop_rewind
+

This guarded method, a variant of i_loc_pop_rewind, executes only +for "ST == ok".

+
objectName i_loc_pop_rewind/discard
+

This method is a convenient combination of control flow and the two +PARAM instructions loc_pop_rewind and loc_pop_discard. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_symbol_restore symbol
+

This method implements the PARAM instruction symbol_restore.

+

The boolean result of the check is returned as the result of +the method and can be used with standard Tcl control flow commands.

+
objectName i_symbol_save symbol
+

This method implements the PARAM instruction symbol_save.

+
objectName i_value_clear
+

This method implements the PARAM instruction value_clear.

+
objectName i_value_clear/leaf
+

This method is a convenient combination of control flow and the two +PARAM instructions value_clear and value_leaf. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_value_clear/reduce
+

This method is a convenient combination of control flow and the two +PARAM instructions value_clear and value_reduce. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i:ok_ast_value_push
+

This method implements a guarded variant of the the PARAM instruction +ast_value_push, which executes only for "ST == ok".

+
objectName i_ast_push
+

This method implements the PARAM instruction ast_push.

+
objectName i_ast_pop_rewind
+

This method implements the PARAM instruction ast_pop_rewind.

+
objectName i:fail_ast_pop_rewind
+

This guarded method, a variant of i_ast_pop_rewind, executes only +for "ST == fail".

+
objectName i_ast_pop_rewind/discard
+

This method is a convenient combination of control flow and the two +PARAM instructions ast_pop_rewind and ast_pop_discard. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i_ast_pop_discard
+

This method implements the PARAM instruction ast_pop_discard.

+
objectName i_ast_pop_discard/rewind
+

This method is a convenient combination of control flow and the two +PARAM instructions ast_pop_discard and ast_pop_rewind. The former +is executed for "ST == fail", the latter for "ST == ok".

+
objectName i:ok_continue
+

This guarded method executes only for "ST == ok". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure.

+
objectName i:fail_continue
+

This guarded method executes only for "ST == fail". Then it aborts the +current iteration of the innermost loop in the calling Tcl procedure.

+
objectName i:fail_return
+

This guarded method executes only for "ST == fail". Then it aborts the +calling Tcl procedure.

+
objectName i:ok_return
+

This guarded method executes only for "ST == ok". Then it aborts the +calling Tcl procedure.

+
+

The next set of methods are super instructions, meaning that +each implements a longer sequence of instructions commonly used in +parsers. The combinated instructions of the previous set, i.e. those +with names matching the pattern "i_*/*", are actually super +instructions as well, albeit with limited scope, handling 2 +instructions with their control flow. The upcoming set is much broader +in scope, folding as much as six or more PARAM instructions into a +single method call.

+

In this we can see the reasoning behind their use well:

+
    +

  1. By using less instructions the generated parsers become smaller, as +the common parts are now truly part of the common runtime, and not +explicitly written in the parser's code over and over again.

    2. +

  2. Using less instructions additionally reduces the overhead associated +with calls into the runtime, i.e. the cost of method dispatch and of +setting up the variable context.

    3. +

  3. Another effect of the super instructions is that their internals can +be optimized as well, especially regarding control flow, and stack +use, as the runtime internals are accessible to all instructions +folded into the sequence.

    4. +
+
+
objectName si:void_state_push
+

This method combines

+
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of void sequences and choices +with a void initial branch.

+
objectName si:void2_state_push
+

This method combines

+
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of optional and repeated expressions.

+
objectName si:value_state_push
+

This method combines

+
+i_ast_push
+i_loc_push
+i_error_clear
+i_error_push
+
+

Parsers use it at the beginning of sequences generating an AST and +choices with an initial branch generating an AST.

+
objectName si:void_state_merge
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+
+

Parsers use it at the end of void sequences and choices whose last +branch is void.

+
objectName si:void_state_merge_ok
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+i_status_ok
+
+

Parsers use it at the end of optional expressions

+
objectName si:value_state_merge
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_rewind/discard
+i_loc_pop_rewind/discard
+
+

Parsers use it at the end of sequences generating ASTs and choices +whose last branch generates an AST

+
objectName si:value_notahead_start
+

This method combines

+
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of negative lookahead predicates which +generate ASTs.

+
objectName si:void_notahead_exit
+

This method combines

+
+i_loc_pop_rewind
+i_status_negate
+
+

Parsers use it at the end of void negative lookahead predicates.

+
objectName si:value_notahead_exit
+

This method combines

+
+i_ast_pop_discard/rewind
+i_loc_pop_rewind
+i_status_negate
+
+

Parsers use it at the end of negative lookahead predicates which +generate ASTs.

+
objectName si:kleene_abort
+

This method combines

+
+i_loc_pop_rewind/discard
+i:fail_return
+
+

Parsers use it to stop a positive repetition when its first, required, expression fails.

+
objectName si:kleene_close
+

This method combines

+
+i_error_pop_merge
+i_loc_pop_rewind/discard
+i:fail_status_ok
+i:fail_return
+
+

Parsers use it at the end of repetitions.

+
objectName si:voidvoid_branch
+

This method combines

+
+i_error_pop_merge
+i:ok_loc_pop_discard
+i:ok_return
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when both are void.

+
objectName si:voidvalue_branch
+

This method combines

+
+i_error_pop_merge
+i:ok_loc_pop_discard
+i:ok_return
+i_ast_push
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when the +failing branch is void, and the next to test generates an AST.

+
objectName si:valuevoid_branch
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_rewind/discard
+i:ok_loc_pop_discard
+i:ok_return
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when the +failing branch generates an AST, and the next to test is void.

+
objectName si:valuevalue_branch
+

This method combines

+
+i_error_pop_merge
+i_ast_pop_discard
+i:ok_loc_pop_discard
+i:ok_return
+i_ast_rewind
+i_loc_rewind
+i_error_push
+
+

Parsers use it when transiting between branches of a choice when both +generate ASTs.

+
objectName si:voidvoid_part
+

This method combines

+
+i_error_pop_merge
+i:fail_loc_pop_rewind
+i:fail_return
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and both +are void.

+
objectName si:voidvalue_part
+

This method combines

+
+i_error_pop_merge
+i:fail_loc_pop_rewind
+i:fail_return
+i_ast_push
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and the +sucessfully matched part is void, and after it an AST is generated.

+
objectName si:valuevalue_part
+

This method combines

+
+i_error_pop_merge
+i:fail_ast_pop_rewind
+i:fail_loc_pop_rewind
+i:fail_return
+i_error_push
+
+

Parsers use it when transiting between parts of a sequence and both +parts generate ASTs.

+
objectName si:value_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found:ok_ast_value_push
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a nonterminal symbol generating an +AST, whose right-hand side may have generated an AST as well.

+
objectName si:value_void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found:ok_ast_value_push
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side may generate an AST.

+
objectName si:void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found_return
+i_loc_push
+i_ast_push
+
+

Parsers use it at the beginning of a nonterminal symbol generating an +AST whose right-hand side is void.

+
objectName si:void_void_symbol_start symbol
+

This method combines

+
+if/found? i_symbol_restore $symbol
+i:found_return
+i_loc_push
+
+

Parsers use it at the beginning of a void nonterminal symbol whose +right-hand side is void as well.

+
objectName si:reduce_symbol_end symbol
+

This method combines

+
+i_value_clear/reduce $symbol
+i_symbol_save        $symbol
+i_error_nonterminal  $symbol
+i_ast_pop_rewind
+i_loc_pop_discard
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +using the AST generated by the right-hand side as child.

+
objectName si:void_leaf_symbol_end symbol
+

This method combines

+
+i_value_clear/leaf  $symbol
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +whose right-hand side is void.

+
objectName si:value_leaf_symbol_end symbol
+

This method combines

+
+i_value_clear/leaf  $symbol
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i_ast_pop_rewind
+i:ok_ast_value_push
+
+

Parsers use it at the end of a non-terminal symbol generating an AST +discarding the AST generated by the right-hand side.

+
objectName si:value_clear_symbol_end symbol
+

This method combines

+
+i_value_clear
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+i_ast_pop_rewind
+
+

Parsers use it at the end of a void non-terminal symbol, discarding +the AST generated by the right-hand side.

+
objectName si:void_clear_symbol_end symbol
+

This method combines

+
+i_value_clear
+i_symbol_save       $symbol
+i_error_nonterminal $symbol
+i_loc_pop_discard
+
+

Parsers use it at the end of a void non-terminal symbol with a void +right-hand side.

+
objectName si:next_char tok
+
+
objectName si:next_range toks toke
+
+
objectName si:next_alnum
+
+
objectName si:next_alpha
+
+
objectName si:next_ascii
+
+
objectName si:next_ddigit
+
+
objectName si:next_digit
+
+
objectName si:next_graph
+
+
objectName si:next_lower
+
+
objectName si:next_print
+
+
objectName si:next_punct
+
+
objectName si:next_space
+
+
objectName si:next_upper
+
+
objectName si:next_wordchar
+
+
objectName si:next_xdigit
+

These methods all combine

+
+i_input_next $msg
+i:fail_return
+
+

with the appropriate i_test_xxx instruction. Parsers use them for +handling atomic expressions.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html Index: embedded/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html +++ embedded/www/tcllib/files/modules/pt/pt_tclparam_config_nx.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::tclparam::configuration::nx(n) 1.0.0 tcllib "Parser Tools"

+

Name

+

pt::tclparam::configuration::nx - Tcl/PARAM, Canned configuration, NX

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::tclparam::configuration::nx ?1.0.0?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::tclparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::tclparam to generate +NX-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::tclparam::configuration::nx def name pkg version cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of NX-based parsers +whose class is name, in package pkg with version.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::tclparam +(pt::peg::to::tclparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html Index: embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html +++ embedded/www/tcllib/files/modules/pt/pt_tclparam_config_snit.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::tclparam::configuration::snit(n) 1.0.2 tcllib "Parser Tools"

+

Name

+

pt::tclparam::configuration::snit - Tcl/PARAM, Canned configuration, Snit

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::tclparam::configuration::snit ?1.0.2?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::tclparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::tclparam to generate +snit-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::tclparam::configuration::snit def name pkg version cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of snit-based parsers +whose class is name, in package pkg with version.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::tclparam +(pt::peg::to::tclparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html Index: embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html +++ embedded/www/tcllib/files/modules/pt/pt_tclparam_config_tcloo.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::tclparam::configuration::tcloo(n) 1.0.4 tcllib "Parser Tools"

+

Name

+

pt::tclparam::configuration::tcloo - Tcl/PARAM, Canned configuration, Tcloo

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::tclparam::configuration::tcloo ?1.0.4?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package is an adjunct to pt::peg::to::tclparam, to make +the use of this highly configurable package easier by providing a +canned configuration. When applied this configuration causes the +package pt::peg::to::tclparam to generate +OO-based parser packages.

+

It is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::tclparam::configuration::tcloo def name pkg version cmdprefix
+

The command applies the configuration provided by this package to the +cmdprefix, causing the creation of OO-based parsers +whose class is name, in package pkg with version.

+

The use of a command prefix as API allows application of the +configuration to not only pt::peg::to::tclparam +(pt::peg::to::tclparam configure), but also export manager +instances and PEG containers ($export configuration set and +[$container exporter] configuration set respectively).

+

Or anything other command prefix accepting two arguments, option and +value.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_to_api.html Index: embedded/www/tcllib/files/modules/pt/pt_to_api.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_to_api.html +++ embedded/www/tcllib/files/modules/pt/pt_to_api.html @@ -0,0 +1,547 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt_export_api(i) 1 tcllib "Parser Tools"

+

Name

+

pt_export_api - Parser Tools Export API

+
+ + +

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This document describes two APIs. First the API shared by all packages +for the conversion of Parsing Expression Grammars into some other +format, and then the API shared by the packages which implement the +export plugins sitting on top of the conversion packages.

+

Its intended audience are people who wish to create their own +converter for some type of output, and/or an export plugin for +their or some other converter.

+

It resides in the Export section of the Core Layer of Parser Tools.

+

arch_core_export

+
+

Converter API

+

Any (grammar) export converter has to follow the rules set out below:

+
    +

  1. A converter is a package. Its name is arbitrary, however it is + recommended to put it under the ::pt::peg::to + namespace.

    2. +

  2. The package provides either a single Tcl command following the + API outlined below, or a class command whose instances follow + the same API. The commands which follow the API are called + converter commands.

    3. +

  3. A converter command has to provide the following three methods + with the given signatures and semantics. Converter commands + are allowed to provide more methods of their own, but not + less, and they may not provide different semantics for the + standardized methods.

    +
    +
    CONVERTER reset
    +

    This method has to reset the configuration of the converter to its +default settings. The result of the method has to be the empty +string.

    +
    CONVERTER configure
    +

    This method, in this form, has to return a dictionary containing the +current configuration of the converter.

    +
    CONVERTER configure option
    +

    This method, in this form, has to return the current value of the +specified configuration option of the converter.

    +

    Please read the section Options for the set of standard +options any converter has to accept. +Any other options accepted by a specific converter will be described +in its manpage.

    +
    CONVERTER configure option value...
    +

    This command, in this form, sets the specified options of the +converter to the given values.

    +

    Please read the section Options for the set of standard +options a converter has to accept. +Any other options accepted by a specific converter will be described +in its manpage.

    +
    CONVERTER convert serial
    +

    This method has to accept the canonical serialization of a parsing +expression grammar, as specified in section +PEG serialization format, and contained in serial. +The result of the method has to be the result of converting the input +grammar into whatever the converter is for, per its configuration.

    +
    +
    4. +
+
+

Plugin API

+

Any (grammar) export plugin has to follow the rules set out below:

+
    +

  1. A plugin is a package.

    2. +

  2. The name of a plugin package has the form + pt::peg::export::FOO, + where FOO is the name of the format the plugin will + generate output for.

    3. +

  3. The plugin can expect that the package + pt::peg::export::plugin is present, as + indicator that it was invoked from a genuine plugin manager.

    +

    It is recommended that a plugin does check for the presence of + this package.

    4. +

  4. A plugin has to provide a single command, in the global + namespace, with the signature shown below. Plugins are allowed + to provide more command of their own, but not less, and they + may not provide different semantics for the standardized + command.

    +
    +
    ::export serial configuration
    +

    This command has to accept the canonical serialization of a parsing +expression grammar and the configuration for the converter invoked by +the plugin. The result of the command has to be the result of the +converter invoked by the plugin for th input grammar and +configuration.

    +
    +
    string serial
    +

    This argument will contain the canonical serialization of the +parsing expression grammar for which to generate the output. +The specification of what a canonical serialization is can be +found in the section PEG serialization format.

    +
    dictionary configuration
    +

    This argument will contain the configuration to configure the +converter with before invoking it, as a dictionary mapping from +options to values.

    +

    Please read the section Options for the set of standard +options any converter has to accept, and thus any plugin as well. +Any other options accepted by a specific plugin will be described in +its manpage.

    +
    +
    +
    5. +

  5. A single usage cycle of a plugin consists of an invokation of + the command export. This call has to leave the plugin in + a state where another usage cycle can be run without problems.

    6. +
+
+

Options

+

Each export converter and plugin for an export converter has to accept +the options below in their configure method. Converters are +allowed to ignore the contents of these options when performing a +conversion, but they must not reject them. Plugins are expected to +pass the options given to them to the converter they are invoking.

+
+
-file string
+

The value of this option is the name of the file or other entity from +which the grammar came, for which the command is run. The default +value is unknown.

+
-name string
+

The value of this option is the name of the grammar we are processing. +The default value is a_pe_grammar.

+
-user string
+

The value of this option is the name of the user for which the command +is run. The default value is unknown.

+
+
+

Usage

+

To use a converter do

+
+    # Get the converter (single command here, not class)
+    package require the-converter-package
+    # Provide a configuration
+    theconverter configure ...
+    # Perform the conversion
+    set result [theconverter convert $thegrammarserial]
+    ... process the result ...
+
+

To use a plugin FOO do

+
+    # Get an export plugin manager
+    package require pt::peg::export
+    pt::peg::export E
+    # Provide a configuration
+    E configuration set ...
+    # Run the plugin, and the converter inside.
+    set result [E export serial $grammarserial FOO]
+    ... process the result ...
+
+
+

PEG serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expression Grammars as immutable values for transport, +comparison, etc.

+

We distinguish between regular and canonical +serializations. +While a PEG may have more than one regular serialization only exactly +one of them will be canonical.

+
+
regular serialization
+
    +

  1. The serialization of any PEG is a nested Tcl dictionary.

    2. +

  2. This dictionary holds a single key, pt::grammar::peg, and its +value. This value holds the contents of the grammar.

    3. +

  3. The contents of the grammar are a Tcl dictionary holding the set of +nonterminal symbols and the starting expression. The relevant keys and +their values are

    +
    +
    rules
    +

    The value is a Tcl dictionary whose keys are the names of the +nonterminal symbols known to the grammar.

    +
      +

    1. Each nonterminal symbol may occur only once.

      2. +

    2. The empty string is not a legal nonterminal symbol.

      3. +

    3. The value for each symbol is a Tcl dictionary itself. The relevant +keys and their values in this dictionary are

      +
      +
      is
      +

      The value is the serialization of the parsing expression describing +the symbols sentennial structure, as specified in the section +PE serialization format.

      +
      mode
      +

      The value can be one of three values specifying how a parser should +handle the semantic value produced by the symbol.

      +
      +
      value
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal itself, +which has the ASTs of the symbol's right hand side as its children.

      +
      leaf
      +

      The semantic value of the nonterminal symbol is an abstract syntax +tree consisting of a single node node for the nonterminal, without any +children. Any ASTs generated by the symbol's right hand side are +discarded.

      +
      void
      +

      The nonterminal has no semantic value. Any ASTs generated by the +symbol's right hand side are discarded (as well).

      +
      +
      +
      4. +
    +
    start
    +

    The value is the serialization of the start parsing expression of the +grammar, as specified in the section PE serialization format.

    +
    +
    4. +

  4. The terminal symbols of the grammar are specified implicitly as the +set of all terminal symbols used in the start expression and on the +RHS of the grammar rules.

    5. +
+
canonical serialization
+

The canonical serialization of a grammar has the format as specified +in the previous item, and then additionally satisfies the constraints +below, which make it unique among all the possible serializations of +this grammar.

+
    +

  1. The keys found in all the nested Tcl dictionaries are sorted in +ascending dictionary order, as generated by Tcl's builtin command +lsort -increasing -dict.

    2. +

  2. The string representation of the value is the canonical representation +of a Tcl dictionary. I.e. it does not contain superfluous whitespace.

    3. +
+
+

Example

+

Assuming the following PEG for simple mathematical expressions

+
+PEG calculator (Expression)
+    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
+    Sign       <- '-' / '+'                                     ;
+    Number     <- Sign? Digit+                                  ;
+    Expression <- Term (AddOp Term)*                            ;
+    MulOp      <- '*' / '/'                                     ;
+    Term       <- Factor (MulOp Factor)*                        ;
+    AddOp      <- '+'/'-'                                       ;
+    Factor     <- '(' Expression ')' / Number                   ;
+END;
+
+

then its canonical serialization (except for whitespace) is

+
+pt::grammar::peg {
+    rules {
+        AddOp      {is {/ {t -} {t +}}                                                                mode value}
+        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
+        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
+        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
+        MulOp      {is {/ {t *} {t /}}                                                                mode value}
+        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
+        Sign       {is {/ {t -} {t +}}                                                                mode value}
+        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
+    }
+    start {n Expression}
+}
+
+
+
+

PE serialization format

+

Here we specify the format used by the Parser Tools to serialize +Parsing Expressions as immutable values for transport, comparison, +etc.

+

We distinguish between regular and canonical +serializations. +While a parsing expression may have more than one regular +serialization only exactly one of them will be canonical.

+
+
Regular serialization
+
+
Atomic Parsing Expressions
+
    +

  1. The string epsilon is an atomic parsing expression. It matches +the empty string.

    2. +

  2. The string dot is an atomic parsing expression. It matches +any character.

    3. +

  3. The string alnum is an atomic parsing expression. It matches +any Unicode alphabet or digit character. This is a custom extension of +PEs based on Tcl's builtin command string is.

    4. +

  4. The string alpha is an atomic parsing expression. It matches +any Unicode alphabet character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    5. +

  5. The string ascii is an atomic parsing expression. It matches +any Unicode character below U0080. This is a custom extension of PEs +based on Tcl's builtin command string is.

    6. +

  6. The string control is an atomic parsing expression. It matches +any Unicode control character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    7. +

  7. The string digit is an atomic parsing expression. It matches +any Unicode digit character. Note that this includes characters +outside of the [0..9] range. This is a custom extension of PEs +based on Tcl's builtin command string is.

    8. +

  8. The string graph is an atomic parsing expression. It matches +any Unicode printing character, except for space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    9. +

  9. The string lower is an atomic parsing expression. It matches +any Unicode lower-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    10. +

  10. The string print is an atomic parsing expression. It matches +any Unicode printing character, including space. This is a custom +extension of PEs based on Tcl's builtin command string is.

    11. +

  11. The string punct is an atomic parsing expression. It matches +any Unicode punctuation character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    12. +

  12. The string space is an atomic parsing expression. It matches +any Unicode space character. This is a custom extension of PEs based +on Tcl's builtin command string is.

    13. +

  13. The string upper is an atomic parsing expression. It matches +any Unicode upper-case alphabet character. This is a custom extension +of PEs based on Tcl's builtin command string is.

    14. +

  14. The string wordchar is an atomic parsing expression. It +matches any Unicode word character. This is any alphanumeric character +(see alnum), and any connector punctuation characters (e.g. +underscore). This is a custom extension of PEs based on Tcl's builtin +command string is.

    15. +

  15. The string xdigit is an atomic parsing expression. It matches +any hexadecimal digit character. This is a custom extension of PEs +based on Tcl's builtin command string is.

    16. +

  16. The string ddigit is an atomic parsing expression. It matches +any decimal digit character. This is a custom extension of PEs based +on Tcl's builtin command regexp.

    17. +

  17. The expression + [list t x] +is an atomic parsing expression. It matches the terminal string x.

    18. +

  18. The expression + [list n A] +is an atomic parsing expression. It matches the nonterminal A.

    19. +
+
Combined Parsing Expressions
+
    +

  1. For parsing expressions e1, e2, ... the result of + [list / e1 e2 ... ] +is a parsing expression as well. +This is the ordered choice, aka prioritized choice.

    2. +

  2. For parsing expressions e1, e2, ... the result of + [list x e1 e2 ... ] +is a parsing expression as well. +This is the sequence.

    3. +

  3. For a parsing expression e the result of + [list * e] +is a parsing expression as well. +This is the kleene closure, describing zero or more +repetitions.

    4. +

  4. For a parsing expression e the result of + [list + e] +is a parsing expression as well. +This is the positive kleene closure, describing one or more +repetitions.

    5. +

  5. For a parsing expression e the result of + [list & e] +is a parsing expression as well. +This is the and lookahead predicate.

    6. +

  6. For a parsing expression e the result of + [list ! e] +is a parsing expression as well. +This is the not lookahead predicate.

    7. +

  7. For a parsing expression e the result of + [list ? e] +is a parsing expression as well. +This is the optional input.

    8. +
+
+
Canonical serialization
+

The canonical serialization of a parsing expression has the format as +specified in the previous item, and then additionally satisfies the +constraints below, which make it unique among all the possible +serializations of this parsing expression.

+
    +

  1. The string representation of the value is the canonical representation +of a pure Tcl list. I.e. it does not contain superfluous whitespace.

    2. +

  2. Terminals are not encoded as ranges (where start and end of the +range are identical).

    3. +
+
+

Example

+

Assuming the parsing expression shown on the right-hand side of the +rule

+
+    Expression <- Term (AddOp Term)*
+
+

then its canonical serialization (except for whitespace) is

+
+    {x {n Term} {* {x {n AddOp} {n Term}}}}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/pt/pt_util.html Index: embedded/www/tcllib/files/modules/pt/pt_util.html ================================================================== --- embedded/www/tcllib/files/modules/pt/pt_util.html +++ embedded/www/tcllib/files/modules/pt/pt_util.html @@ -0,0 +1,180 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

pt::util(n) 1.1 tcllib "Parser Tools"

+

Name

+

pt::util - General utilities

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require pt::ast ?1.1?
    • +
+ +
+
+

Description

+

Are you lost ? +Do you have trouble understanding this document ? +In that case please read the overview provided by the +Introduction to Parser Tools. This document is the +entrypoint to the whole system the current package is a part of.

+

This package provides general utility commands.

+

This is a supporting package in the Core Layer of Parser Tools.

+

arch_core_support

+
+

API

+
+
::pt::util error2readable error text
+

This command takes the structured form of a syntax error as +thrown by parser runtimes and the input text to the parser which +caused that error and returns a string describing the error in a +human-readable form.

+

The input text is required to convert the character +position of the error into a more readable line/column format, and to +provide excerpts of the input around the error position.

+
::pt::util error2position error text
+

This command takes the structured form of a syntax error as +thrown by parser runtimes and the input text to the parser which +caused that error and returns a 2-element list containing the line +number and column index for the error's character position in the +input, in this order.

+
::pt::util error2text error
+

This command takes the structured form of a syntax error as +thrown by parser runtimes and returns a list of strings, each +describing a possible expected input in a human-readable form.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category pt of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Parsing and Grammars

+
+ +
ADDED embedded/www/tcllib/files/modules/rc4/rc4.html Index: embedded/www/tcllib/files/modules/rc4/rc4.html ================================================================== --- embedded/www/tcllib/files/modules/rc4/rc4.html +++ embedded/www/tcllib/files/modules/rc4/rc4.html @@ -0,0 +1,224 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

rc4(n) 1.1.0 tcllib "RC4 Stream Cipher"

+

Name

+

rc4 - Implementation of the RC4 stream cipher

+
+ + +

Description

+

This package is an implementation in Tcl of the RC4 stream cipher +developed by Ron Rivest of RSA Data Security Inc. The cipher was a +trade secret of RSA but was reverse-engineered and published to the +internet in 1994. It is used in a number of network protocols for +securing communications. To evade trademark restrictions this cipher +is sometimes known as ARCFOUR.

+
+

COMMANDS

+
+
::rc4::rc4 ?-hex? -key keyvalue ?-command lst? ?-out channel? [ -in channel | -infile filename | string ]
+

Perform the RC4 algorithm on either the data provided by the argument +or on the data read from the -in channel. If an -out +channel is given then the result will be written to this channel. +Giving the -hex option will return a hexadecimal encoded +version of the result if not using an -out channel.

+

The data to be processes can be specified either as a string argument to +the rc4 command, or as a filename or a pre-opened channel. If the +-infile argument is given then the file is opened, the data read +and processed and the file is closed. If the -in argument is +given then data is read from the channel until the end of file. The +channel is not closed. If the -out argument is given then the +processing result is written to this channel.

+

If -command is provided then the rc4 command does not return +anything. Instead the command provided is called with the rc4 result data +appended as the final parameter. This is most useful when reading from Tcl +channels as a fileevent is setup on the channel and the data processed in +chunks

+

Only one of -infile, -in or string should be given.

+
+
+

PROGRAMMING INTERFACE

+
+
::rc4::RC4Init keydata
+

Initialize a new RC4 key. The keydata is any amount of binary +data and is used to initialize the cipher internal state.

+
::rc4::RC4 Key data
+

Encrypt or decrypt the input data using the key obtained by calling +RC4Init.

+
::rc4::RC4Final Key
+

This should be called to clean up resources associated with +Key. Once this function has been called the key is destroyed.

+
+
+

EXAMPLES

+
+% set keydata [binary format H* 0123456789abcdef]
+% rc4::rc4 -hex -key $keydata HelloWorld
+3cf1ae8b7f1c670b612f
+% rc4::rc4 -hex -key $keydata [binary format H* 3cf1ae8b7f1c670b612f]
+HelloWorld
+
+
+ set Key [rc4::RC4Init "key data"]
+ append ciphertext [rc4::RC4 $Key $plaintext]
+ append ciphertext [rc4::RC4 $Key $additional_plaintext]
+ rc4::RC4Final $Key
+
+
+ proc ::Finish {myState data} {
+     DoStuffWith $myState $data
+ }
+ rc4::rc4 -in $socket -command [list ::Finish $ApplicationState]
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rc4 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/rcs/rcs.html Index: embedded/www/tcllib/files/modules/rcs/rcs.html ================================================================== --- embedded/www/tcllib/files/modules/rcs/rcs.html +++ embedded/www/tcllib/files/modules/rcs/rcs.html @@ -0,0 +1,342 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

rcs(n) 2.0.2 tcllib "RCS low level utilities"

+

Name

+

rcs - RCS low level utilities

+
+ + +

Description

+

The Revision Control System, short RCS, is a set of +applications and related data formats which allow a system to persist +the history of changes to a text. It, and its relative SCCS are the +basis for many other such systems, like CVS, etc.

+

This package does not implement RCS.

+

It only provides a number of low level commands which should be useful +in the implementation of any revision management system, namely:

+
    +

  1. The conversion of texts into and out of a data structures which allow +the easy modification of such text by patches, i.e. sequences +of instructions for the transformation of one text into an other.

    2. +

  2. And the conversion of one particular format for patches, the so-called +RCS patches, into and out of data structures which allow +their easy application to texts.

    3. +
+
+

COMMANDS

+
+
::rcs::text2dict text
+

Converts the argument text into a dictionary containing and +representing the same text in an indexed form and returns that +dictionary as its result. +More information about the format of the result can be found in +section TEXT DICT DATA STRUCTURE. This command returns the +canonical representation of the input.

+
::rcs::dict2text dict
+

This command provides the complementary operation to +::rcs::text2dict. It converts a dictionary in the form described +in section TEXT DICT DATA STRUCTURE back into a text and +returns that text as its result. The command does accept non-canonical +representations of the text as its input.

+
::rcs::file2dict filename
+

This command is identical to ::rcs::text2dict, except that it +reads the text to convert from the file with path filename. The +file has to exist and must be readable as well.

+
::rcs::dict2file filename dict
+

This command is identical to ::rcs::2dict2text, except that it +stores the resulting text in the file with path filename. The +file is created if it did not exist, and must be writable. The result +of the command is the empty string.

+
::rcs::decodeRcsPatch text
+

Converts the text argument into a patch command list (PCL) as +specified in the section RCS PATCH COMMAND LIST and +returns this list as its result. +It is assumed that the input text is in diff -n format, also +known as RCS patch format, as specified in the section +RCS PATCH FORMAT. +Please note that the command ignores no-ops in the input, in other +words the resulting PCL contains only instructions doing something.

+
::rcs::encodeRcsPatch pcmds
+

This command provides the complementary operation to +::rcs::decodeRcsPatch. It convert a patch comand list (PCL) list +as specified in the section RCS PATCH COMMAND LIST back +into a text in RCS PATCH FORMAT and returns that text as its result.

+

Note that this command and ::rcs::decodeRcsPatch are not exactly +complementary, as the latter strips no-ops from its input, which the +encoder cannot put back anymore into the generated RCS patch. In other +words, the result of a decode/encode step may not match the original +input at the character level, but it will match it at the functional +level.

+
::rcs::applyRcsPatch text pcmds
+

This operation applies a patch in the form of a PCL to a text given in +the form of a dictionary and returns the modified text, again as +dictionary, as its result.

+

To handle actual text use the commands ::rcs::text2dict (or +equivalent) and ::rcs::decodeRcsPatch to transform the inputs +into data structures acceptable to this command. Analogously use the +command ::rcs::dict2text (or equivalent) to transform the +result of this command into actuall text as required.

+
+
+

TEXT DICT DATA STRUCTURE

+

A text dictionary is a dictionary whose keys are integer numbers and +text strings as the associated values. The keys represent the line +numbers of a text and the values the text of that line. Note that one +text can have many representations as a dictionary, as the index +values only have to be properly ordered for reconstruction, their +exact values do not matter. Similarly the strings may actually span +multiple physical lines.

+

The text

+
Hello World,
+how are you ?
+Fine, and you ?
+

for example can be represented by

+
{{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}}
+

or

+
{{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}}
+

or

+
{{-1 {Hello World,
+how are you ?}} {4 {Fine, and you ?}}}
+

The first dictionary is the canonical representation of the +text, with line numbers starting at 1, increasing in steps of +1 and without gaps, and each value representing exactly one +physical line.

+

All the commands creating dictionaries from text will return the +canonical representation of their input text. The commands taking a +dictionary and returning text will generally accept all +representations, canonical or not.

+

The result of applying a patch to a text dictionary will in general +cause the dictionary to become non-canonical.

+
+

RCS PATCH FORMAT

+

A patch is in general a series of instructions how to transform +an input text T into a different text T', and also encoded in text +form as well.

+

The text format for patches understood by this package is a very +simple one, known under the names RCS patch or +diff -n format.

+

Patches in this format contain only two different commands, for the +deletion of old text, and addition of new text. The replacement of +some text by a different text is handled as combination of a deletion +following by an addition.

+

The format is line oriented, with each line containing either a +command or text data associated with the preceding command. +The first line of a RCS patch is always a command line.

+

The commands are:

+
+
""
+

The empty line is a command which does nothing.

+
"astart n"
+

A line starting with the character a is a command for the +addition of text to the output. It is followed by n lines of +text data. When applying the patch the data is added just between the +lines start and start+1. The same effect is had by +appending the data to the existing text on line start. A +non-existing line start is created.

+
"dstart n"
+

A line starting with the character d is a command for the +deletion of text from the output. When applied it deletes n +lines of text, and the first line deleted is at index start.

+
+

Note that the line indices start always refer to the text which +is transformed as it is in its original state, without taking the +precending changes into account.

+

Note also that the instruction have to be applied in the order they +occur in the patch, or in a manner which produces the same result as +in-order application.

+

This is the format of results returned by the command +::rcs::decodeRcsPatch and accepted by the commands +::rcs::encodeRcsPatch and ::rcs::appplyRcsPatch +resp. +Note however that the decoder will strip no-op commands, and the +encoder will not generate no-ops, making them not fully complementary +at the textual level, only at the functional level.

+

And example of a RCS patch is

+
d1 2
+d4 1
+a4 2
+The named is the mother of all things.
+a11 3
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+
+

RCS PATCH COMMAND LIST

+

Patch command lists (sort: PCL's) are the data structures generated by +patch decoder command and accepted by the patch encoder and applicator +commands. They represent RCS patches in the form of Tcl data +structures.

+

A PCL is a list where each element represents a single patch +instruction, either an addition, or a deletion. The elements are lists +themselves, where the first item specifies the command and the +remainder represent the arguments of the command.

+
+
a
+

This is the instruction for the addition of text. It has two +arguments, the index of the line where to add the text, and the text +to add, in this order.

+
d
+

This is the instruction for the deletion of text. It has two +arguments, the index of the line where to start deleting text, and the +number of lines to delete, in this order.

+
+

This is the format returned by the patch decoder command and accepted +as input by the patch encoder and applicator commands.

+

An example for a patch command is shown below, it represents the +example RCS patch found in section RCS PATCH FORMAT.

+
{{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.
+}} {a 11 {They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!}}}
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rcs of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Text processing

+
+ +
ADDED embedded/www/tcllib/files/modules/report/report.html Index: embedded/www/tcllib/files/modules/report/report.html ================================================================== --- embedded/www/tcllib/files/modules/report/report.html +++ embedded/www/tcllib/files/modules/report/report.html @@ -0,0 +1,470 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

report(n) 0.3.2 tcllib "Matrix reports"

+

Name

+

report - Create and manipulate report objects

+
+ + +

Description

+

This package provides report objects which can be used by the +formatting methods of matrix objects to generate tabular reports of +the matrix in various forms. The report objects defined here break +each report down into three REGIONS and ten classes of +lines (various separator- and data-lines). See the following +section for more detailed explanations.

+
+
::report::report reportName columns ?style style arg...?
+

Creates a new report object for a report having columns columns +with an associated global Tcl command whose name is +reportName. This command may be used to invoke various +configuration operations on the report. It has the following general +form:

+
+
reportName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section REPORT METHODS for more +explanations. If no style is specified the report will use +the builtin style plain as its default configuration.

+
+
::report::defstyle styleName arguments script
+

Defines the new style styleName. See section STYLES +for more information.

+
::report::rmstyle styleName
+

Deletes the style styleName. Trying to delete an unknown or +builtin style will result in an error. Beware, this command will not +check that there are no other styles depending on the deleted +one. Deleting a style which is still used by another style FOO will +result in a runtime error when FOO is applied to a newly instantiated +report.

+
::report::stylearguments styleName
+

This introspection command returns the list of arguments associated +with the style styleName.

+
::report::stylebody styleName
+

This introspection command returns the script associated with the +style styleName.

+
::report::styles
+

This introspection command returns a list containing the names of all +styles known to the package at the time of the call. The order of the +names in the list reflects the order in which the styles were +created. In other words, the first item is the predefined style +plain, followed by the first style defined by the user, and +so on.

+
+
+

REGIONS

+

The three regions are the top caption, +data area and bottom caption. These are, +roughly speaking, the title, the values to report and a title at the +bottom. The size of the caption regions can be specified by the user +as the number of rows they occupy in the matrix to format. The size of +the data area is specified implicitly.

+
+

LINES

+

TEMPLATES are associated with each of the ten line classes, +defining the formatting for this kind of line. The user is able to +enable and disable the separator lines at will, but not the data +lines. Their usage is solely determined by the number of rows +contained in the three regions. Data lines and all enabled separators +must have a template associated with them.

+

Note that the data-lines in a report and the rows in the matrix the +report was generated from are not in a 1:1 relationship if +any row in the matrix has a height greater than one.

+

The different kinds of lines and the codes used by the report methods +to address them are:

+
+
top
+

The topmost line of a report. Separates the report from anything which +came before it. The user can enable the usage of this line at will.

+
topdatasep
+

This line is used to separate the data rows in the top caption region, +if it contains more than one row and the user enabled its usage.

+
topcapsep
+

This line is used to separate the top caption and data regions, if the +top caption is not empty and the user enabled its usage.

+
datasep
+

This line is used to separate the data rows in the data region, if it +contains more than one row and the user enabled its usage.

+
botcapsep
+

This line is used to separate the data and bottom caption regions, if +the bottom caption is not empty and the user enabled its usage.

+
botdatasep
+

This line is used to separate the data rows in the bottom caption +region, if it contains more than one row and the user enabled its +usage.

+
bottom
+

The bottommost line of a report. Separates the report from anything +which comes after it. The user can enable the usage of this line at +will.

+
topdata
+

This line defines the format of data lines in the top caption region +of the report.

+
data
+

This line defines the format of data lines in the data region of the +report.

+
botdata
+

This line defines the format of data lines in the bottom caption +region of the report.

+
+
+

TEMPLATES

+

Each template is a list of strings used to format the line it is +associated with. For a report containing n columns a template +for a data line has to contain "n+1" items and a template for a +separator line "2*n+1" items.

+

The items in a data template specify the strings used to separate the +column information. Together with the corresponding items in the +separator templates they form the vertical lines in the report.

+

Note that the corresponding items in all defined templates +have to be of equal length. This will be checked by the report +object. The first item defines the leftmost vertical line and the last +item defines the rightmost vertical line. The item at index k +("1",...,"n-2") separates the information in the columns +"k-1" and "k".

+

The items in a separator template having an even-numbered index +("0","2",...) specify the column separators. The item at index +"2*k" ("0","2",...,"2*n") corresponds to the items at +index "k" in the data templates.

+

The items in a separator template having an odd-numbered index +("1","3",...) specify the strings used to form the horizontal lines in +the separator lines. The item at index "2*k+1" +("1","3",...,"2*n+1") corresponds to column "k". When +generating the horizontal lines the items are replicated to be at +least as long as the size of their column and then cut to the exact +size.

+
+

STYLES

+

Styles are a way for the user of this package to define common +configurations for report objects and then use them later during the +actual instantiation of report objects. They are defined as tcl +scripts which when executed configure the report object into the +requested configuration.

+

The command to define styles is ::report::defstyle. Its last +argument is the tcl script performing the actual +reconfiguration of the report object to obtain the requested style.

+

In this script the names of all previously defined styles are +available as commands, as are all commands found in a safe interpreter +and the configuration methods of report objects. The latter implicitly +operate on the object currently executing the style script. The +arguments declared here are available in the script as +variables. When calling the command of a previously declared style all +the arguments expected by it have to be defined in the call.

+
+

REPORT METHODS

+

The following commands are possible for report objects:

+
+
reportName destroy
+

Destroys the report, including its storage space and associated +command.

+
reportName templatecode disable|enable
+

Enables or disables the usage of the template addressed by the +templatecode. Only the codes for separator lines are allowed +here. It is not possible to enable or disable data lines.

+

Enabling a template causes the report to check all used templates for +inconsistencies in the definition of the vertical lines (See section +TEMPLATES).

+
reportName templatecode enabled
+

Returns the whether the template addressed by the templatecode +is currently enabled or not.

+
reportName templatecode get
+

Returns the template currently associated with the kind of line +addressed by the templatecode. All known templatecodes are +allowed here.

+
reportName templatecode set templatedata
+

Sets the template associated with the kind of line addressed by the +templatecode to the new value in templatedata. See section +TEMPLATES for constraints on the length of templates.

+
reportName tcaption ?size?
+

Specifies the size of the top caption region as the number rows +it occupies in the matrix to be formatted. Only numbers greater than +or equal to zero are allowed. If no size is specified the +command will return the current size instead.

+

Setting the size of the top caption to a value greater than zero +enables the corresponding data template and causes the report to check +all used templates for inconsistencies in the definition of the +vertical lines (See section TEMPLATES).

+
reportName bcaption size
+

Specifies the size of the bottom caption region as the number +rows it occupies in the matrix to be formatted. Only numbers greater +than or equal to zero are allowed. If no size is specified the +command will return the current size instead.

+

Setting the size of the bottom caption to a value greater than zero +enables the corresponding data template and causes the report to check +all used templates for inconsistencies in the definition of the +vertical lines (See section TEMPLATES).

+
reportName size column ?number|dyn?
+

Specifies the size of the column in the output. The value +dyn means that the columnwidth returned by the matrix to be +formatted for the specified column shall be used. The formatting of +the column is dynamic. If a fixed number is used instead of +dyn it means that the column has a width of that many +characters (padding excluded). Only numbers greater than zero are +allowed here.

+

If no size specification is given the command will return the current +size of the column instead.

+
reportName sizes ?size-list?
+

This method allows the user to specify the sizes of all columns in one +call. Its argument is a list containing the sizes to associate with +the columns. The first item is associated with column 0, the next with +column 1, and so on.

+

If no size-list is specified the command will return a list +containing the currently set sizes instead.

+
reportName pad column ?left|right|both ?padstring??
+

This method allows the user to specify padding on the left, right or +both sides of a column. If the padstring is not specified +it defaults to a single space character. Note: An alternative +way of specifying the padding is to use vertical separator strings +longer than one character in the templates (See section +TEMPLATES).

+

If no pad specification is given at all the command will return the +current state of padding for the column instead. This will be a list +containing two elements, the first element the left padding, the +second describing the right padding.

+
reportName justify column ?left|right|center?
+

Declares how the cell values for a column are filled into the +report given the specified size of a column in the report.

+

For left and right justification a cell value +shorter than the width of the column is bound with its named edge to +the same edge of the column. The other side is filled with spaces. In +the case of center the spaces are placed to both sides of the +value and the left number of spaces is at most one higher than the +right number of spaces.

+

For a value longer than the width of the column the value is cut at +the named edge. This means for left justification that the +tail (i.e. the right part) of the value is made +visible in the output. For center the value is cut at both +sides to fit into the column and the number of characters cut at the +left side of the value is at most one less than the number of +characters cut from the right side.

+

If no justification was specified the command will return the current +justification for the column instead.

+
reportName printmatrix matrix
+

Formats the matrix according to the configuration of the report +and returns the resulting string. The matrix has to have the same +number of columns as the report. The matrix also has to have enough +rows so that the top and bottom caption regions do not overlap. The +data region is allowed to be empty.

+
reportName printmatrix2channel matrix chan
+

Formats the matrix according to the configuration of the report +and writes the result into the channel chan. The matrix has to +have the same number of columns as the report. The matrix also has to +have enough rows so that the top and bottom caption regions do not +overlap. The data region is allowed to be empty.

+
reportName columns
+

Returns the number of columns in the report.

+
+

The methods size, pad and justify all take +a column index as their first argument. This index is allowed to use +all the forms of an index as accepted by the lindex command. The +allowed range for indices is + "0,...,[reportName columns]-1".

+
+

EXAMPLES

+

Our examples define some generally useful report styles.

+

A simple table with lines surrounding all information and vertical +separators, but without internal horizontal separators.

+
+    ::report::defstyle simpletable {} {
+	data	set [split "[string repeat "| "   [columns]]|"]
+	top	set [split "[string repeat "+ - " [columns]]+"]
+	bottom	set [top get]
+	top	enable
+	bottom	enable
+    }
+
+

An extension of a simpletable, see above, with a title area.

+
+    ::report::defstyle captionedtable {{n 1}} {
+	simpletable
+	topdata   set [data get]
+	topcapsep set [top get]
+	topcapsep enable
+	tcaption $n
+    }
+
+

Given the definitions above now an example which actually formats a +matrix into a tabular report. It assumes that the matrix actually +contains useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % r printmatrix m
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % m format 2string r
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category report of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/rest/rest.html Index: embedded/www/tcllib/files/modules/rest/rest.html ================================================================== --- embedded/www/tcllib/files/modules/rest/rest.html +++ embedded/www/tcllib/files/modules/rest/rest.html @@ -0,0 +1,567 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

rest(n) 1.2 tcllib "A framework for RESTful web services"

+

Name

+

rest - define REST web APIs and call them inline or asychronously

+
+ + +

Description

+

There are two types of usage this package supports: simple calls, +and complete interfaces. +In an interface you specify a set of rules and then the package +builds the commands which correspond to the REST methods. These +commands can have many options such as input and output +transformations and data type specific formatting. This results in a +cleaner and simpler script. +On the other hand, while a simple call is easier and quicker +to implement it is also less featureful. It takes the url and a few +options about the command and returns the result directly. Any +formatting or checking is up to rest of the script.

+
+

Simple usage

+

In simple usage you make calls using the http method procedures and +then check or process the returned data yourself

+
+
::rest::simple url query ?config? ?body?
+
+
::rest::get url query ?config? ?body?
+
+
::rest::post url query ?config? ?body?
+
+
::rest::head url query ?config? ?body?
+
+
::rest::put url query ?config? ?body?
+
+
::rest::delete url query ?config? ?body?
+

These commands are all equivalent except for the http method +used. +If you use simple then the method should be specified as an +option in the config dictionary. If that is not done it defaults +to get. If a body is needed then the config +dictionary must be present, however it is allowed to be empty.

+

The config dictionary supports the following keys

+
+
auth
+
+
content-type
+
+
cookie
+
+
error-body
+
+
format
+
+
headers
+
+
method
+
+
+

Two quick examples:

+

Example 1, Yahoo Boss:

+
+    set appid APPID
+    set search tcl
+    set res [rest::get http://boss.yahooapis.com/ysearch/web/v1/$search [list appid $appid]]
+    set res [rest::format_json $res]
+
+

Example 2, Twitter:

+
+    set url   http://twitter.com/statuses/update.json
+    set query [list status $text]
+    set res [rest::simple $url $query {
+        method post
+        auth   {basic user password}
+        format json
+    }]
+
+
+
+
+

Interface usage

+

An interface to a REST API consists of a series of definitions of REST +calls contained in an array. +The name of that array becomes a namespace containing the defined +commands. Each key of the array specifies the name of the call, with +the associated configuration a dictionary, i.e. key/value pairs. +The acceptable keys, i.e. legal configuration options are described +below. +After creating the definitions in the array simply calling +rest::create_interface with the array as argument will then +create the desired commands.

+

Example, Yahoo Weather:

+
+    package require rest
+    set yweather(forecast) {
+       url      http://weather.yahooapis.com/forecastrss
+       req_args { p: }
+       opt_args { u: }
+    }
+    rest::create_interface yweather
+    puts [yweather::forecast -p 94089]
+
+
+
::rest::save name file
+

This command saves a copy of the dynamically created procedures for +all the API calls specified in the array variable name to the +file, for later loading.

+

The result of the command is the empty string

+
::rest::describe name
+

This command prints a description of all API calls specified in the array +variable name to the channel stdout.

+

The result of the command is the empty string.

+
::rest::parameters url ?key?
+

This command parses an url query string into a dictionary and +returns said dictionary as its result.

+

If key is specified the command will not return the +entire dictionary, but only the value of that key.

+
::rest::parse_opts static required optional words
+

This command implements a custom parserfor command options.

+
+
dict static
+

A dictionary of options and their values that are always present in +the output.

+
list required
+

A list of options that must be supplied by words

+
list optional
+

A list of options that may appear in the words, but are not required. +The elements must be in one of three forms:

+
+
name
+

The option may be present or not, no default.

+
name:
+

When present the option requires an argument.

+
name:value
+

When not present use value as default.

+
+
list words
+

The words to parse into options and values.

+
+

The result of the command is a list containing two elements. +The first element is a dictionary containing the parsed options and +their values. The second element is a list of the remaining words.

+
::rest::substitute string var
+

This command takes a string, substitutes values for any option +identifiers found inside and returns the modified string as its +results.

+

The values to substitute are found in the variable var, +which is expected to contain a dictionary mapping from the option +identifiers to replace to their values. +Note that option identifiers which have no key in var are +replaced with the empty string.

+

The option identifiers in string have to follow the +syntax %...% where ... may contain any combination of +lower-case alphanumeric characters, plus underscore, colon and dash.

+
::rest::create_interface name
+

This command creates procedures for all the API calls specified in the +array variable name.

+

The name of that array becomes a namespace containing the defined +commands. Each key of the array specifies the name of the call, with +the associated configuration a dictionary, i.e. key/value pairs. +The legal keys and their meanings are:

+
+
url
+

The value of this required option must be the target of the +http request.

+
description
+

The value of this option must be a short string describing the call. +Default to the empty string, if not specified. +Used only by ::rest::describe.

+
body
+

The value of this option indicates if arguments are required for the +call's request body or not. The acceptable values are listed below. +Defaults to optional if not specified.

+
+
none
+

The call has no request body, none must be supplied.

+
optional
+

A request body can be supplied, but is not required.

+
required
+

A request body must be supplied.

+
argument
+

This value must be followed by the name of an option, treating the +entire string as a list. The request body will be used as the value of +that option.

+
mime_multipart
+

A request body must be supplied and will be interpreted as each +argument representing one part of a mime/multipart document. +Arguments must be lists containing 2 elements, a list of header keys +and values, and the mime part body, in this order.

+
+
method
+

The value of this option must be the name of the HTTP method to call +on the url. +Defaults to GET, if not specified. +The acceptable values are GET, POST, and PUT, +regardless of letter-case.

+
copy
+

When present the value of this option specifies the name of a +previously defined call. The definition of that call is copied to the +current call, except for the options specified by the current call +itself.

+
unset
+

When present the value of this option contains a list of options in +the current call. These options are removed from the definition. Use +this after copying an existing definition to remove options, +instead of overriding their value.

+
headers
+

Specification of additional header fields. The value of this option +must be a dictionary, interpreted to contain the new header fields and +their values. The default is to not add any additional headers.

+
content-type
+

The value of this option specifies the content type for the request data.

+
req_args
+

The value of this option is a list naming the required arguments of +the call. Names ending in a colon will require a value.

+
opt_args
+

The value of this option a list naming the arguments that may be +present for a call but are not required.

+
static_args
+

The value of this option a list naming the arguments that are always +the same. No sense in troubling the user with these. A leading dash +(-) is allowed but not required to maintain consistency with +the command line.

+
auth
+

The value of this option specifies how to authenticate the calls. +No authentication is done if the option is not specified.

+
+
basic
+

The user may configure the basic authentication by overriding +the procedure basic_auth in the namespace of interface. This +procedure takes two arguments, the username and password, in this +order.

+
sign
+

The value must actually be a list with the second element the name of +a procedure which will be called to perform request signing.

+
+
callback
+

If this option is present then the method will be created as an +async call. Such calls will return immediately with the value +of the associated http token instead of the call's result. The event +loop must be active to use this option.

+

The value of this option is treated as a command prefix which +is invoked when the HTTP call is complete. The prefix will receive at +least two additional arguments, the name of the calling procedure and +the status of the result (one of OK or ERROR), in this +order.

+

In case of OK a third argument is added, the data +associated with the result.

+

If and only if the ERROR is a redirection, the location +redirected to will be added as argument. +Further, if the configuration key error-body is set to +true the data associated with the result will be added as +argument as well.

+

The http request header will be available in that procedure via +upvar token token.

+
cookie
+

The value of this option is a list of cookies to be passed in the http +header. This is a shortcut to the headers option.

+
input_transform
+

The value of this option is a command prefix or script to perform a +transformation on the query before invoking the call. A script +transform is wrapped into an automatically generated internal +procedure.

+

If not specified no transformation is done.

+

The command (prefix) must accept a single argument, the query +(a dictionary) to transform, and must return the modified query (again +as dictionary) as its result. +The request body is accessible in the transform command via +upvar body body.

+
format
+
+
result
+

The value of this option specifies the format of the returned +data. +Defaults to auto if not specified. +The acceptable values are:

+
+
auto
+

Auto detect between xml and json.

+
discard
+
+
json
+
+
raw
+
+
rss
+

This is formatted as a special case of xml.

+
tdom
+
+
xml
+
+
+
pre_transform
+

The value of this option is a command prefix or script to perform a +transformation on the result of a call (before the application +of the output transform as per format). A script transform is +wrapped into an automatically generated internal procedure.

+

If not specified no transformation is done.

+

The command (prefix) must accept a single argument, the result +to transform, and must return the modified result as its result.

+

The http request header is accessible in the transform command +via upvar token token

+
post_transform
+

The value of this option is a command prefix or script to perform a +transformation on the result of a call (after the application +of the output transform as per format). A script transform is +wrapped into an automatically generated internal procedure.

+

If not specified no transformation is done.

+

The command (prefix) must accept a single argument, the result +to transform, and must return the modified result as its result.

+

The http request header is accessible in the transform command +via upvar token token

+
check_result
+

The value of this option must be list of two expressions, either of +which may be empty.

+

The first expression is checks the OK condition, it must return +true when the result is satisfactory, and false +otherwise.

+

The second expression is the ERROR condition, it must return +false unless there is an error, then it has to return +true.

+
error_body
+

The value of this option determines whether to return the response +when encountering an HTTP error, or not. The default is to not return +the response body on error.

+

See callback above for more information.

+
+
+
+

Examples

+

Yahoo Geo:

+
+set ygeo(parse) {
+    url http://wherein.yahooapis.com/v1/document
+    method post
+    body { arg documentContent }
+}
+ygeo::parse "san jose ca"
+# "san jose ca" will be interpreted as if it were specified as the -documentContent option
+
+

Google Docs:

+
+set gdocs(upload) {
+    url http://docs.google.com/feeds/default/private/full
+    body mime_multipart
+}
+gdocs::upload [list {Content-Type application/atom+xml} $xml] [list {Content-Type image/jpeg} $filedata]
+
+

Delicious:

+
+set delicious(updated) {
+    url https://api.del.icio.us/v1/posts/update
+    auth basic
+}
+rest::create_interface flickr
+flickr::basic_auth username password
+
+

Flickr:

+
+set flickr(auth.getToken) {
+   url http://api.flickr.com/services/rest/
+   req_args { api_key: secret: }
+   auth { sign do_signature }
+}
+rest::create_interface flickr
+proc ::flickr::do_signature {query} {
+    # perform some operations on the query here
+    return $query
+}
+
+
+

INCLUDED

+

The package provides functional but incomplete implementations for the following services:

+
+
del.icio.us
+
+
facebook
+
+
flickr
+
+
twitter
+
+
google calendar
+
+
yahoo boss
+
+
yahoo weather
+
+
+

Please either read the package's implementation, or use +rest::describe after loading it for their details.

+

Do not forget developers' documentation on the respective sites either.

+
+

TLS

+

The rest package can be used with https-secured +services, by requiring the TLS package and then registering +it with the http package it is sitting on top of. +Example

+
+    package require tls
+    http::register https 443 ::tls::socket
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category rest of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+
ADDED embedded/www/tcllib/files/modules/ripemd/ripemd128.html Index: embedded/www/tcllib/files/modules/ripemd/ripemd128.html ================================================================== --- embedded/www/tcllib/files/modules/ripemd/ripemd128.html +++ embedded/www/tcllib/files/modules/ripemd/ripemd128.html @@ -0,0 +1,272 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ripemd128(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm"

+

Name

+

ripemd128 - RIPEMD-128 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the RIPEMD-128 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and +generates a 128-bit message digest from the input. The RIPEMD-128 +algorithm is based upon the MD4 algorithm (2, 4) but has been +cryptographically strengthened against weaknesses that have been found +in MD4 (4). RIPEMD-128 has been designed to be a drop-in replacement +for MD4 and MD5 (5). If security is the major consideration, then +RIPEMD-160 or SHA1 should be considered.

+

This package will use Trf to +accelerate the digest computation if available. In +the absence of an accelerator package the pure-Tcl implementation will +be used.

+
+

COMMANDS

+
+
::ripemd::ripemd128 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the RIPEMD-128 digest of the data given in string. This is +returned as a binary string by default. Giving the -hex option +will return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the ripemd128 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::ripemd::hmac128 ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the +RIPEMD-128 digest algorithm. HMACs are described in RFC 2104 (6) and +provide a RIPEMD-128 digest that includes a key. All options other +than -key are as for the ::ripemd::ripemd128 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, hash functions can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +uniquely derived from the data that was poured into the bucket. The +programming interface to the hash operates on a token (equivalent to the +bucket). You call RIPEMD128Init to obtain a token and then call +RIPEMD128Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +RIPEMD128Final. An equivalent set of functions gives you a keyed +digest (HMAC).

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Alternatively if both the Trf and Memchan +extensions are available then these will be used. Finally the package +will revert to a pure-Tcl implementation. The programming interface +remains the same, however.

+
+
::ripemd::RIPEMD128Init
+

Begins a new RIPEMD-128 hash. Returns a token ID that must be used for the +remaining functions.

+
::ripemd::RIPEMD128Update token data
+

Add data to the hash identified by token. Calling +RIPEMD128Update $token "abcd" is equivalent to calling +RIPEMD128Update $token "ab" followed by +RIPEMD128Update $token "cb". See EXAMPLES.

+
::ripemd::RIPEMD128Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 128 bit +RIPEMD-128 digest value.

+
::ripemd::RIPEHMAC128Init key
+

This is equivalent to the ::ripemd::RIPEMD128Init command +except that it requires the key that will be included in the HMAC.

+
::ripemd::RIPEHMAC128Update token data
+
+
::ripemd::RIPEHMAC128Final token
+

These commands are identical to the RIPEMD128 equivalent commands.

+
+
+

EXAMPLES

+
+% ripemd::ripemd128 -hex "Tcl does RIPEMD-128"
+3cab177bae65205d81e7978f63556c63
+
+
+% ripemd::hmac128 -hex -key Sekret "Tcl does RIPEMD-128"
+b359dc5971a05beea0be7b106b30e389
+
+
+% set tok [ripemd::RIPEMD128Init]
+::ripemd::1
+% ripemd::RIPEMD128Update $tok "Tcl "
+% ripemd::RIPEMD128Update $tok "does "
+% ripemd::RIPEMD128Update $tok "RIPEMD-128"
+% ripemd::Hex [ripemd::RIPEMD128Final $tok]
+3cab177bae65205d81e7978f63556c63
+
+
+

REFERENCES

+
    +

  1. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    4. +

  4. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology + vol 11 (4), pp. 253-271 (1998)

    5. +

  5. Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, MIT and + RSA Data Security, Inc, April 1992. + (http://www.rfc-editor.org/rfc/rfc1321.txt)

    6. +

  6. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    7. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ripemd of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/ripemd/ripemd160.html Index: embedded/www/tcllib/files/modules/ripemd/ripemd160.html ================================================================== --- embedded/www/tcllib/files/modules/ripemd/ripemd160.html +++ embedded/www/tcllib/files/modules/ripemd/ripemd160.html @@ -0,0 +1,261 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

ripemd160(n) 1.0.5 tcllib "RIPEMD Message-Digest Algorithm"

+

Name

+

ripemd160 - RIPEMD-160 Message-Digest Algorithm

+
+ + +

Description

+

This package is an implementation in Tcl of the RIPEMD-160 message-digest +algorithm (1). This algorithm takes an arbitrary quantity of data and +generates a 160-bit message digest from the input. The RIPEMD-160 +algorithm is based upon the MD4 algorithm (2, 4) but has been +cryptographically strengthened against weaknesses that have been found +in MD4 (4).

+

This package will use cryptkit or Trf to +accelerate the digest computation if either package is available. In +the absence of an accelerator package the pure-Tcl implementation will +be used.

+
+

COMMANDS

+
+
::ripemd::ripemd160 ?-hex? [ -channel channel | -file filename | string ]
+

Calculate the RIPEMD-160 digest of the data given in string. This is +returned as a binary string by default. Giving the -hex option +will return a hexadecimal encoded version of the digest.

+

The data to be hashed can be specified either as a string argument to +the ripemd160 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed.

+

Only one of -file, -channel or string should be given.

+
::ripemd::hmac160 ?-hex? -key key [ -channel channel | -file filename | string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the +RIPEMD-160 digest algorithm. HMACs are described in RFC 2104 (5) and +provide a RIPEMD-160 digest that includes a key. All options other +than -key are as for the ::ripemd::ripemd160 command.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, hash functions can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +uniquely derived from the data that was poured into the bucket. The +programming interface to the hash operates on a token (equivalent to the +bucket). You call RIPEMD160Init to obtain a token and then call +RIPEMD160Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +RIPEMD160Final. An equivalent set of functions gives you a keyed +digest (HMAC).

+
+
::ripemd::RIPEMD160Init
+

Begins a new RIPEMD-160 hash. Returns a token ID that must be used for the +remaining functions.

+
::ripemd::RIPEMD160Update token data
+

Add data to the hash identified by token. Calling +RIPEMD160Update $token "abcd" is equivalent to calling +RIPEMD160Update $token "ab" followed by +RIPEMD160Update $token "cb". See EXAMPLES.

+
::ripemd::RIPEMD160Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 16 bytes representing the 160 bit +RIPEMD-160 digest value.

+
::ripemd::RIPEHMAC160Init key
+

This is equivalent to the ::ripemd::RIPEMD160Init command +except that it requires the key that will be included in the HMAC.

+
::ripemd::RIPEHMAC160Update token data
+
+
::ripemd::RIPEHMAC160Final token
+

These commands are identical to the RIPEMD160 equivalent commands.

+
+
+

EXAMPLES

+
+% ripemd::ripemd160 -hex "Tcl does RIPEMD-160"
+0829dea75a1a7074c702896723fe37763481a0a7
+
+
+% ripemd::hmac160 -hex -key Sekret "Tcl does RIPEMD-160"
+bf0c927231733686731dddb470b64a9c23f7f53b
+
+
+% set tok [ripemd::RIPEMD160Init]
+::ripemd::1
+% ripemd::RIPEMD160Update $tok "Tcl "
+% ripemd::RIPEMD160Update $tok "does "
+% ripemd::RIPEMD160Update $tok "RIPEMD-160"
+% ripemd::Hex [ripemd::RIPEMD160Final $tok]
+0829dea75a1a7074c702896723fe37763481a0a7
+
+
+

REFERENCES

+
    +

  1. H. Dobbertin, A. Bosselaers, B. Preneel, + "RIPEMD-160, a strengthened version of RIPEMD" + http://www.esat.kuleuven.ac.be/~cosicart/pdf/AB-9601/AB-9601.pdf

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Rivest, R., "The MD4 message digest algorithm", in A.J. Menezes + and S.A. Vanstone, editors, Advances in Cryptology - CRYPTO '90 + Proceedings, pages 303-311, Springer-Verlag, 1991.

    4. +

  4. Dobbertin, H., "Cryptanalysis of MD4", Journal of Cryptology + vol 11 (4), pp. 253-271 (1998)

    5. +

  5. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    6. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category ripemd of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/sasl/gtoken.html Index: embedded/www/tcllib/files/modules/sasl/gtoken.html ================================================================== --- embedded/www/tcllib/files/modules/sasl/gtoken.html +++ embedded/www/tcllib/files/modules/sasl/gtoken.html @@ -0,0 +1,175 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

SASL::XGoogleToken(n) 1.0.1 tcllib "Simple Authentication and Security Layer (SASL)"

+

Name

+

SASL::XGoogleToken - Implementation of SASL NTLM mechanism for Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require SASL::XGoogleToken ?1.0.1?
    • +
+
+
+

Description

+

This package provides the XGoogleToken authentication mechanism for +the Simple Authentication and Security Layer (SASL).

+

Please read the documentation for package sasl +for details.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sasl of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/sasl/ntlm.html Index: embedded/www/tcllib/files/modules/sasl/ntlm.html ================================================================== --- embedded/www/tcllib/files/modules/sasl/ntlm.html +++ embedded/www/tcllib/files/modules/sasl/ntlm.html @@ -0,0 +1,160 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

SASL::NTLM(n) 1.1.2 tcllib "Simple Authentication and Security Layer (SASL)"

+

Name

+

SASL::NTLM - Implementation of SASL NTLM mechanism for Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require SASL::NTLM ?1.1.2?
    • +
+
+
+

Description

+

This package provides the NTLM authentication mechanism for +the Simple Authentication and Security Layer (SASL).

+

Please read the documentation for package sasl +for details.

+
+

REFERENCES

+
    +

  1. No official specification is available. However, + http://davenport.sourceforge.net/ntlm.html provides a good + description.

    2. +
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sasl of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/sasl/sasl.html Index: embedded/www/tcllib/files/modules/sasl/sasl.html ================================================================== --- embedded/www/tcllib/files/modules/sasl/sasl.html +++ embedded/www/tcllib/files/modules/sasl/sasl.html @@ -0,0 +1,394 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

SASL(n) 1.3.3 tcllib "Simple Authentication and Security Layer (SASL)"

+

Name

+

SASL - Implementation of SASL mechanisms for Tcl

+
+ + +

Description

+

The Simple Authentication and Security Layer (SASL) is a framework +for providing authentication and authorization to comunications +protocols. The SASL framework is structured to permit negotiation +among a number of authentication mechanisms. SASL may be used in +SMTP, IMAP and HTTP authentication. It is also in use in XMPP, LDAP +and BEEP. See MECHANISMS for the set of available SASL +mechanisms provided with tcllib.

+

The SASL framework operates using a simple multi-step challenge +response mechanism. All the mechanisms work the same way although the +number of steps may vary. In this implementation a callback procedure +must be provided from which the SASL framework will obtain users +details. See CALLBACK PROCEDURE for details of this +procedure.

+
+

COMMANDS

+
+
::SASL::new option value ?...?
+

Contruct a new SASL context. See OPTIONS for details of the +possible options to this command. A context token is required for most +of the SASL procedures.

+
::SASL::configure option value ?...?
+

Modify and inspect the SASL context option. See OPTIONS for +further details.

+
::SASL::step context challenge ?...?
+

This is the core procedure for using the SASL framework. The +step procedure should be called until it returns 0. Each step takes a +server challenge string and the response is calculated and stored in +the context. Each mechanism may require one or more steps. For some +steps there may be no server challenge required in which case an empty +string should be provided for this parameter. All mechanisms should accept +an initial empty challenge.

+
::SASL::response context
+

Returns the next response string that should be sent to the server.

+
::SASL::reset context
+

Re-initialize the SASL context. Discards any internal state and +permits the token to be reused.

+
::SASL::cleanup context
+

Release all resources associated with the SASL context. The context +token may not be used again after this procedure has been called.

+
::SASL::mechanisms ?type? ?minimum?
+

Returns a list of all the available SASL mechanisms. The list is +sorted by the mechanism preference value (see register) with the +preferred mechanisms and the head of the list. Any mechanism with a +preference value less than theminimum (which defaults to 0) is removed +from the returned list. This permits a security threshold to be set. Mechanisms +with a preference less that 25 transmit authentication are particularly +susceptible to eavesdropping and should not be provided unless a secure +channel is in use (eg: tls).

+

The type parameter +may be one of client or server and defaults to client. +Only mechanisms that have an implementation matching the type are +returned (this permits servers to correctly declare support only for +mechanisms that actually provide a server implementation).

+
::SASL::register mechanism preference clientproc ?serverproc?
+

New mechanisms can be added to the package by registering the +mechanism name and the implementing procedures. The server procedure +is optional. The preference value is an integer that is used to order +the list returned by the mechanisms command. Higher values +indicate a preferred mechanism. If the mechanism is already registered +then the recorded values are updated.

+
+
+

OPTIONS

+
+
-callback
+

Specify a command to be evaluated when the SASL mechanism requires +information about the user. The command is called with the current +SASL context and a name specifying the information desired. See +EXAMPLES.

+
-mechanism
+

Set the SASL mechanism to be used. See mechanisms for a list of +supported authentication mechanisms.

+
-service
+

Set the service type for this context. Some mechanisms may make use of +this parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it +defaults to an empty string. If the -type is set to 'server' +then this option should be set to a valid service identity. Some +examples of valid service names are smtp, ldap, beep and xmpp.

+
-server
+

This option is used to set the server name used in SASL challenges +when operating as a SASL server.

+
-type
+

The context type may be one of 'client' or 'server'. The default is to +operate as a client application and respond to server +challenges. Mechanisms may be written to support server-side SASL and +setting this option will cause each step to issue the next +challenge. A new context must be created for each incoming client +connection when in server mode.

+
+
+

CALLBACK PROCEDURE

+

When the SASL framework requires any user details it will call the +procedure provided when the context was created with an argument that +specfies the item of information required.

+

In all cases a single response string should be returned.

+
+
login
+

The callback procedure should return the users authorization identity. +Return an empty string unless this is to be different to the authentication +identity. Read [1] for a discussion about the specific meaning of +authorization and authentication identities within SASL.

+
username
+

The callback procedure should return the users authentication identity. +Read [1] for a discussion about the specific meaning of +authorization and authentication identities within SASL.

+
password
+

The callback procedure should return the password that matches the +authentication identity as used within the current realm.

+

For server mechanisms the password callback should always be called with +the authentication identity and the realm as the first two parameters.

+
realm
+

Some SASL mechanisms use realms to partition authentication identities. +The realm string is protocol dependent and is often the current DNS +domain or in the case of the NTLM mechanism it is the Windows NT domain name.

+
hostname
+

Returns the client host name - typically [info host].

+
+
+

MECHANISMS

+
+
ANONYMOUS
+

As used in FTP this mechanism only passes an email address for +authentication. The ANONYMOUS mechanism is specified in [2].

+
PLAIN
+

This is the simplest mechanism. The users authentication details are +transmitted in plain text. This mechanism should not be provided +unless an encrypted link is in use - typically after SSL or TLS has +been negotiated.

+
LOGIN
+

The LOGIN [1] mechanism transmits the users details with base64 +encoding. This is no more secure than PLAIN and likewise should not be +used without a secure link.

+
CRAM-MD5
+

This mechanism avoids sending the users password over the network in +plain text by hashing the password with a server provided random value +(known as a nonce). A disadvantage of this mechanism is that the +server must maintain a database of plaintext passwords for +comparison. CRAM-MD5 was defined in [4].

+
DIGEST-MD5
+

This mechanism improves upon the CRAM-MD5 mechanism by avoiding the +need for the server to store plaintext passwords. With digest +authentication the server needs to store the MD5 digest of the users +password which helps to make the system more secure. As in CRAM-MD5 +the password is hashed with a server nonce and other data before being +transmitted across the network. Specified in [3].

+
OTP
+

OTP is the One-Time Password system described in RFC 2289 [6]. +This mechanism is secure against replay attacks and also avoids storing +password or password equivalents on the server. Only a digest of a seed +and a passphrase is ever transmitted across the network. Requires the +otp package from tcllib and one or more of the cryptographic +digest packages (md5 or sha-1 are the most commonly used).

+
NTLM
+

This is a proprietary protocol developed by Microsoft [5] and is +in common use for authenticating users in a Windows network +environment. NTLM uses DES encryption and MD4 digests of the users +password to authenticate a connection. Certain weaknesses have been +found in NTLM and thus there are a number of versions of the protocol. +As this mechanism has additional dependencies it is made available as +a separate sub-package. To enable this mechanism your application must +load the SASL::NTLM package.

+
X-GOOGLE-TOKEN
+

This is a proprietary protocol developed by Google and used for +authenticating users for the Google Talk service. This mechanism makes +a pair of HTTP requests over an SSL channel and so this mechanism +depends upon the availability of the tls and http packages. To enable +this mechanism your application must load the SASL::XGoogleToken package. +In addition you are recommended to make use of the autoproxy package to +handle HTTP proxies reasonably transparently.

+
SCRAM
+

This is a protocol specified in RFC 5802 [7]. To enable this mechanism +your application must load the SASL::SCRAM package.

+
+
+

EXAMPLES

+

See the examples subdirectory for more complete samples using SASL +with network protocols. The following should give an idea how the SASL +commands are to be used. In reality this should be event +driven. Each time the step command is called, the last server +response should be provided as the command argument so that the SASL +mechanism can take appropriate action.

+
+proc ClientCallback {context command args} {
+    switch -exact -- $command {
+        login    { return "" }
+        username { return $::tcl_platform(user) }
+        password { return "SecRet" }
+        realm    { return "" }
+        hostname { return [info host] }
+        default  { return -code error unxpected }
+    }
+}
+proc Demo {{mech PLAIN}} {
+    set ctx [SASL::new -mechanism $mech -callback ClientCallback]
+    set challenge ""
+    while {1} {
+        set more_steps [SASL::step $ctx challenge]
+        puts "Send '[SASL::response $ctx]'"
+        puts "Read server response into challenge var"
+        if {!$more_steps} {break}
+    }
+    SASL::cleanup $ctx
+}
+
+
+

REFERENCES

+
    +

  1. Myers, J. "Simple Authentication and Security Layer (SASL)", + RFC 2222, October 1997. + (http://www.ietf.org/rfc/rfc2222.txt)

    2. +

  2. Newman, C. "Anonymous SASL Mechanism", + RFC 2245, November 1997. + (http://www.ietf.org/rfc/rfc2245.txt)

    3. +

  3. Leach, P., Newman, C. "Using Digest Authentication as a SASL + Mechanism", RFC 2831, May 2000, + (http://www.ietf.org/rfc/rfc2831.txt)

    4. +

  4. Klensin, J., Catoe, R. and Krumviede, P., + "IMAP/POP AUTHorize Extension for Simple Challenge/Response" + RFC 2195, September 1997. + (http://www.ietf.org/rfc/rfc2195.txt)

    5. +

  5. No official specification is available. However, + http://davenport.sourceforge.net/ntlm.html provides a good + description.

    6. +

  6. Haller, N. et al., "A One-Time Password System", + RFC 2289, February 1998, + (http://www.ieft.org/rfc/rfc2289.txt)

    7. +

  7. Newman, C. et al., "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms", + RFC 5802, July 2010, + (http://www.ieft.org/rfc/rfc5802.txt)

    8. +
+
+

AUTHORS

+

Pat Thoyts

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sasl of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/sasl/scram.html Index: embedded/www/tcllib/files/modules/sasl/scram.html ================================================================== --- embedded/www/tcllib/files/modules/sasl/scram.html +++ embedded/www/tcllib/files/modules/sasl/scram.html @@ -0,0 +1,160 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

SASL::SCRAM(n) 0.1 tcllib "Simple Authentication and Security Layer (SASL)"

+

Name

+

SASL::SCRAM - Implementation of SASL SCRAM mechanism for Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require SASL::SCRAM ?0.1?
    • +
+
+
+

Description

+

This package provides the SCRAM authentication mechanism for +the Simple Authentication and Security Layer (SASL).

+

Please read the documentation for package sasl +for details.

+
+

REFERENCES

+
    +

  1. Newman, C. et al., "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms", + RFC 5802, July 2010, + (http://www.ieft.org/rfc/rfc5802.txt)

    2. +
+
+

AUTHORS

+

Sergei Golovan

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sasl of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/sha1/sha1.html Index: embedded/www/tcllib/files/modules/sha1/sha1.html ================================================================== --- embedded/www/tcllib/files/modules/sha1/sha1.html +++ embedded/www/tcllib/files/modules/sha1/sha1.html @@ -0,0 +1,271 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

sha1(n) 2.0.3 tcllib "SHA-x Message-Digest Algorithm"

+

Name

+

sha1 - SHA1 Message-Digest Algorithm

+
+ + +

Description

+

This package provides an implementation in Tcl of the SHA1 +message-digest algorithm as specified by FIPS PUB 180-1 (1). This +algorithm takes a message and generates a 160-bit digest from the +input. The SHA1 algorithm is related to the MD4 algorithm (2) but has +been strengthend against certain types of cryptographic attack. SHA1 +should be used in preference to MD4 or MD5 in new applications.

+

This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA1 as the +message-digest.

+
+

COMMANDS

+
+
::sha1::sha1 ?-hex|-bin? [ -channel channel | -file filename | ?--? string ]
+

The command takes a message and returns the SHA1 digest of this message +as a hexadecimal string. You may request the result as binary data by +giving -bin.

+

The data to be hashed can be specified either as a string argument to +the sha1 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed. NOTE use of the channel or filename +options results in the internal use of vwait. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below).

+

Only one of -file, -channel or string should be given.

+

If the string to hash can be mistaken for an option +(leading dash "-"), use the option -- before it to terminate +option processing and force interpretation as a string.

+
::sha1::hmac key string
+
+
::sha1::hmac ?-hex|-bin? -key key [ -channel channel | -file filename | ?--? string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the SHA1 +digest algorithm. HMACs are described in RFC 2104 (3) and provide an SHA1 +digest that includes a key. All options other than -key are as +for the ::sha1::sha1 command.

+

If the string to hash can be mistaken for an option +(leading dash "-"), use the option -- before it to terminate +option processing and force interpretation as a string.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the SHA1 hash can be viewed as a bucket into which +one pours data. When you have finished, you extract a value that is +derived from the data that was poured into the bucket. The programming +interface to the SHA1 hash operates on a token (equivalent to the +bucket). You call SHA1Init to obtain a token and then call +SHA1Update as many times as required to add data to the hash. To +release any resources and obtain the hash value, you then call +SHA1Final. An equivalent set of functions gives you a keyed digest +(HMAC).

+

If you have critcl and have built the tcllibc package +then the implementation of the hashing function will be performed by compiled +code. Failing that if you have the Trf package then this can +be used otherwise there is a pure-tcl equivalent. The programming +interface remains the same in all cases.

+
+
::sha1::SHA1Init
+

Begins a new SHA1 hash. Returns a token ID that must be used for the +remaining functions.

+
::sha1::SHA1Update token data
+

Add data to the hash identified by token. Calling +SHA1Update $token "abcd" is equivalent to calling +SHA1Update $token "ab" followed by +SHA1Update $token "cb". See EXAMPLES.

+
::sha1::SHA1Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 20 bytes representing the 160 bit SHA1 +digest value.

+
::sha1::HMACInit key
+

This is equivalent to the ::sha1::SHA1Init command except that +it requires the key that will be included in the HMAC.

+
::sha1::HMACUpdate token data
+
+
::sha1::HMACFinal token
+

These commands are identical to the SHA1 equivalent commands.

+
+
+

EXAMPLES

+
+% sha1::sha1 "Tcl does SHA1"
+285a6a91c45a9066bf39fcf24425796ef0b2a8bf
+
+
+% sha1::hmac Sekret "Tcl does SHA1"
+ae6251fa51b95b18cba2be95eb031d07475ff03c
+
+
+% set tok [sha1::SHA1Init]
+::sha1::1
+% sha1::SHA1Update $tok "Tcl "
+% sha1::SHA1Update $tok "does "
+% sha1::SHA1Update $tok "SHA1"
+% sha1::Hex [sha1::SHA1Final $tok]
+285a6a91c45a9066bf39fcf24425796ef0b2a8bf
+
+
+

REFERENCES

+
    +

  1. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sha1 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/sha1/sha256.html Index: embedded/www/tcllib/files/modules/sha1/sha256.html ================================================================== --- embedded/www/tcllib/files/modules/sha1/sha256.html +++ embedded/www/tcllib/files/modules/sha1/sha256.html @@ -0,0 +1,280 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

sha256(n) 1.0.3 tcllib "SHA-x Message-Digest Algorithm"

+

Name

+

sha256 - SHA256 Message-Digest Algorithm

+
+ + +

Description

+

This package provides an implementation in Tcl of the SHA256 and +SHA224 message-digest algorithms as specified by FIPS PUB 180-1 +(1). These algorithms take a message and generates a 256-bit (224-bit) +digest from the input. The SHA2 algorithms are related to the SHA1 +algorithm.

+

This package also includes support for creating keyed message-digests +using the HMAC algorithm from RFC 2104 (3) with SHA256 as the +message-digest.

+
+

COMMANDS

+
+
::sha2::sha256 ?-hex|-bin? [ -channel channel | -file filename | ?--? string ]
+

The command takes a message and returns the SHA256 digest of this +message as a hexadecimal string. You may request the result as binary +data by giving -bin.

+

The data to be hashed can be specified either as a string argument to +the sha256 command, or as a filename or a pre-opened channel. If the +-filename argument is given then the file is opened, the data read +and hashed and the file is closed. If the -channel argument is +given then data is read from the channel until the end of file. The +channel is not closed. NOTE use of the channel or filename +options results in the internal use of vwait. To avoid nested +event loops in Tk or tclhttpd applications you should use the +incremental programming API (see below).

+

Only one of -file, -channel or string should be given.

+

If the string to hash can be mistaken for an option +(leading dash "-"), use the option -- before it to terminate +option processing and force interpretation as a string.

+
::sha2::sha224 ?-hex|-bin? [ -channel channel | -file filename | ?--? string ]
+

Like ::sha2::sha256, except that the SHA224 digest is returned.

+
::sha2::hmac key string
+
+
::sha2::hmac ?-hex|-bin? -key key [ -channel channel | -file filename | ?--? string ]
+

Calculate an Hashed Message Authentication digest (HMAC) using the +SHA256 digest algorithm. HMACs are described in RFC 2104 (3) and +provide an SHA256 digest that includes a key. All options other than +-key are as for the ::sha2::sha256 command.

+

If the string to hash can be mistaken for an option +(leading dash "-"), use the option -- before it to terminate +option processing and force interpretation as a string.

+
+
+

PROGRAMMING INTERFACE

+

For the programmer, the SHA256 hash can be viewed as a bucket into +which one pours data. When you have finished, you extract a value that +is derived from the data that was poured into the bucket. The +programming interface to the SHA256 hash operates on a token +(equivalent to the bucket). You call SHA256Init to obtain a +token and then call SHA256Update as many times as required to +add data to the hash. To release any resources and obtain the hash +value, you then call SHA256Final. An equivalent set of +functions gives you a keyed digest (HMAC).

+

If you have critcl and have built the tcllibc +package then the implementation of the hashing function will be +performed by compiled code. Failing that there is a pure-tcl +equivalent. The programming interface remains the same in all cases.

+
+
::sha2::SHA256Init
+
+
::sha2::SHA224Init
+

Begins a new SHA256/SHA224 hash. Returns a token ID that must be used +for the remaining functions.

+
::sha2::SHA256Update token data
+

Add data to the hash identified by token. Calling +SHA256Update $token "abcd" is equivalent to calling +SHA256Update $token "ab" followed by +SHA256Update $token "cb". See EXAMPLES. +Note that this command is used for both SHA256 and SHA224. Only the +initialization and finalization commands of both hashes differ.

+
::sha2::SHA256Final token
+
+
::sha2::SHA224Final token
+

Returns the hash value and releases any resources held by this +token. Once this command completes the token will be invalid. The +result is a binary string of 32/28 bytes representing the 256/224 bit +SHA256 / SHA224 digest value.

+
::sha2::HMACInit key
+

This is equivalent to the ::sha2::SHA256Init command except +that it requires the key that will be included in the HMAC.

+
::sha2::HMACUpdate token data
+
+
::sha2::HMACFinal token
+

These commands are identical to the SHA256 equivalent commands.

+
+
+

EXAMPLES

+
+% sha2::sha256 "Tcl does SHA256"
+0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
+
+
+% sha2::hmac Sekret "Tcl does SHA256"
+4f9352c64d655e8a36abe73e6163a9d7a54039877c1c92ec90b07d48d4e854e0
+
+
+% set tok [sha2::SHA256Init]
+::sha2::1
+% sha2::SHA256Update $tok "Tcl "
+% sha2::SHA256Update $tok "does "
+% sha2::SHA256Update $tok "SHA256"
+% sha2::Hex [sha2::SHA256Final $tok]
+0b91043ee484abd83c3e4b08d6034d71b937026379f0f59bda6e625e6e214789
+
+
+

REFERENCES

+
    +

  1. "Secure Hash Standard", National Institute of Standards + and Technology, U.S. Department Of Commerce, April 1995. + (http://www.itl.nist.gov/fipspubs/fip180-1.htm)

    2. +

  2. Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT, + April 1992. (http://www.rfc-editor.org/rfc/rfc1320.txt)

    3. +

  3. Krawczyk, H., Bellare, M. and Canetti, R. "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + (http://www.rfc-editor.org/rfc/rfc2104.txt)

    4. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category sha1 of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/annealing.html Index: embedded/www/tcllib/files/modules/simulation/annealing.html ================================================================== --- embedded/www/tcllib/files/modules/simulation/annealing.html +++ embedded/www/tcllib/files/modules/simulation/annealing.html @@ -0,0 +1,318 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

simulation::annealing(n) 0.2 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::annealing - Simulated annealing

+
+ + +

Description

+

The technique of simulated annealing provides methods to +estimate the global optimum of a function. It is described in some +detail on the Wiki http://wiki.tcl.tk/.... The idea is simple:

+
    +

  • randomly select points within a given search space

    • +

  • evaluate the function to be optimised for each of these +points and select the point that has the lowest (or highest) +function value or - sometimes - accept a point that has a less optimal +value. The chance by which such a non-optimal point is accepted diminishes over +time.

    • +

  • Accepting less optimal points means the method does not necessarily get +stuck in a local optimum and theoretically it is capable of finding the +global optimum within the search space.

    • +
+

The method resembles the cooling of material, hence the name.

+

The package simulation::annealing offers the command findMinimum:

+
+    puts [::simulation::annealing::findMinimum  -trials 300  -parameters {x -5.0 5.0 y -5.0 5.0}  -function {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
+
+

prints the estimated minimum value of the function f(x,y) = +x**2+y**2+sin(10*x)+4*cos(20*y) and the values of x and y where +the minimum was attained:

+
+result -4.9112922923 x -0.181647676593 y 0.155743646974
+
+
+

PROCEDURES

+

The package defines the following auxiliary procedures:

+
+
::simulation::annealing::getOption keyword
+

Get the value of an option given as part of the findMinimum +command.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::annealing::hasOption keyword
+

Returns 1 if the option is available, 0 if not.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::annealing::setOption keyword value
+

Set the value of the given option.

+
+
string keyword
+

Given keyword (without leading minus)

+
string value
+

(New) value for the option

+
+
+

The main procedures are findMinimum and findCombinatorialMinimum:

+
+
::simulation::annealing::findMinimum args
+

Find the minimum of a function using simulated annealing. The function +and the method's parameters is given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
::simulation::annealing::findCombinatorialMinimum args
+

Find the minimum of a function of discrete variables using simulated +annealing. The function and the method's parameters is given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
+

The findMinimum command predefines the following options:

+
    +

  • -parameters list: triples defining parameters and ranges

    • +

  • -function expr: expression defining the function

    • +

  • -code body: body of code to define the function (takes +precedence over -function). The code should set the variable +"result"

    • +

  • -init code: code to be run at start up +-final code: code to be run at the end +-trials n: number of trials before reducing the temperature +-reduce factor: reduce the temperature by this factor (between 0 and 1) +-initial-temp t: initial temperature +-scale s: scale of the function (order of magnitude of the values) +-estimate-scale y/n: estimate the scale (only if -scale +is not present) +-verbose y/n: print detailed information on progress to the +report file (1) or not (0) +-reportfile file: opened file to print to (defaults to stdout)

    • +
+

Any other options can be used via the getOption procedure +in the body. +The findCombinatorialMinimum command predefines the following +options:

+
    +

  • -number-params n: number of binary parameters (the solution +space consists of lists of 1s and 0s). This is a required option.

    • +

  • -initial-values: list of 1s and 0s constituting the start of +the search.

    • +
+

The other predefined options are identical to those of findMinimum.

+
+

TIPS

+

The procedure findMinimum works by constructing a temporary +procedure that does the actual work. It loops until the point +representing the estimated optimum does not change anymore within the +given number of trials. As the temperature gets lower and lower the +chance of accepting a point with a higher value becomes lower too, so +the procedure will in practice terminate.

+

It is possible to optimise over a non-rectangular region, but some care +must be taken:

+
    +

  • If the point is outside the region of interest, you can specify a very +high value.

    • +

  • This does mean that the automatic determination of a scale factor is +out of the question - the high function values that force the point +inside the region would distort the estimation.

    • +
+

Here is an example of finding an optimum inside a circle:

+
+    puts [::simulation::annealing::findMinimum  -trials 3000  -reduce 0.98  -parameters {x -5.0 5.0 y -5.0 5.0}  -code {
+            if { hypot($x-5.0,$y-5.0) < 4.0 } {
+                set result [expr {$x*$x+$y*$y+sin(10.0*$x)+4.0*cos(20.0*$y)}]
+            } else {
+                set result 1.0e100
+            }
+        }]
+
+

The method is theoretically capable of determining the global optimum, +but often you need to use a large number of trials and a slow reduction +of temperature to get reliable and repeatable estimates.

+

You can use the -final option to use a deterministic optimization +method, once you are sure you are near the required optimum.

+

The findCombinatorialMinimum procedure is suited for situations +where the parameters have the values 0 or 1 (and there can be many of +them). Here is an example:

+
    +

  • We have a function that attains an absolute minimum if the first ten +numbers are 1 and the rest is 0:

    +
    +proc cost {params} {
+    set cost 0
+    foreach p [lrange $params 0 9] {
+        if { $p == 0 } {
+            incr cost
+        }
+    }
+    foreach p [lrange $params 10 end] {
+        if { $p == 1 } {
+            incr cost
+        }
+    }
+    return $cost
+}
+
    +
    • +

  • We want to find the solution that gives this minimum for various lengths +of the solution vector params:

    +
    +foreach n {100 1000 10000} {
+    break
+    puts "Problem size: $n"
+    puts [::simulation::annealing::findCombinatorialMinimum  -trials 300  -verbose 0  -number-params $n  -code {set result [cost $params]}]
+}
+
    +
    • +

  • As the vector grows, the computation time increases, but the procedure +will stop if some kind of equilibrium is reached. To achieve a useful +solution you may want to try different values of the trials parameter +for instance. Also ensure that the function to be minimized depends on +all or most parameters - see the source code for a counter example and +run that.

    • +
+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/montecarlo.html Index: embedded/www/tcllib/files/modules/simulation/montecarlo.html ================================================================== --- embedded/www/tcllib/files/modules/simulation/montecarlo.html +++ embedded/www/tcllib/files/modules/simulation/montecarlo.html @@ -0,0 +1,289 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

simulation::montecarlo(n) 0.1 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::montecarlo - Monte Carlo simulations

+
+ + +

Description

+

The technique of Monte Carlo simulations is basically simple:

+
    +

  • generate random values for one or more parameters.

    • +

  • evaluate the model of some system you are interested in and record the +interesting results for each realisation of these parameters.

    • +

  • after a suitable number of such trials, deduce an overall characteristic +of the model.

    • +
+

You can think of a model of a network of computers, an ecosystem of some +kind or in fact anything that can be quantitatively described and has +some stochastic element in it.

+

The package simulation::montecarlo offers a basic framework for +such a modelling technique:

+
+#
+# MC experiments:
+# Determine the mean and median of a set of points and compare them
+#
+::simulation::montecarlo::singleExperiment -init {
+    package require math::statistics
+    set prng [::simulation::random::prng_Normal 0.0 1.0]
+} -loop {
+    set numbers {}
+    for { set i 0 } { $i < [getOption samples] } { incr i } {
+        lappend numbers [$prng]
+    }
+    set mean   [::math::statistics::mean $numbers]
+    set median [::math::statistics::median $numbers] ;# ? Exists?
+    setTrialResult [list $mean $median]
+} -final {
+    set result [getTrialResults]
+    set means   {}
+    set medians {}
+    foreach r $result {
+        foreach {m M} $r break
+        lappend means   $m
+        lappend medians $M
+    }
+    puts [getOption reportfile] "Correlation: [::math::statistics::corr $means $medians]"
+} -trials 100 -samples 10 -verbose 1 -columns {Mean Median}
+
+

This example attemps to find out how well the median value and the mean +value of a random set of numbers correlate. Sometimes a median value is +a more robust characteristic than a mean value - especially if you have +a statistical distribution with "fat" tails.

+
+

PROCEDURES

+

The package defines the following auxiliary procedures:

+
+
::simulation::montecarlo::getOption keyword
+

Get the value of an option given as part of the singeExperiment command.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::montecarlo::hasOption keyword
+

Returns 1 if the option is available, 0 if not.

+
+
string keyword
+

Given keyword (without leading minus)

+
+
::simulation::montecarlo::setOption keyword value
+

Set the value of the given option.

+
+
string keyword
+

Given keyword (without leading minus)

+
string value
+

(New) value for the option

+
+
::simulation::montecarlo::setTrialResult values
+

Store the results of the trial for later analysis

+
+
list values
+

List of values to be stored

+
+
::simulation::montecarlo::setExpResult values
+

Set the results of the entire experiment (typically used in the final +phase).

+
+
list values
+

List of values to be stored

+
+
::simulation::montecarlo::getTrialResults
+

Get the results of all individual trials for analysis (typically used in +the final phase or after completion of the command).

+
::simulation::montecarlo::getExpResult
+

Get the results of the entire experiment (typically used in the final +phase or even after completion of the singleExperiment command).

+
::simulation::montecarlo::transposeData values
+

Interchange columns and rows of a list of lists and return the result.

+
+
list values
+

List of lists of values

+
+
+

There are two main procedures: integral2D and singleExperiment.

+
+
::simulation::montecarlo::integral2D ...
+

Integrate a function over a two-dimensional region using a Monte Carlo +approach.

+

Arguments PM

+
::simulation::montecarlo::singleExperiment args
+

Iterate code over a number of trials and store the results. The +iteration is gouverned by parameters given via a list of +keyword-value pairs.

+
+
int n
+

List of keyword-value pairs, all of which are available +during the execution via the getOption command.

+
+
+

The singleExperiment command predefines the following +options:

+
    +

  • -init code: code to be run at start up

    • +

  • -loop body: body of code that defines the computation to +be run time and again. The code should use setTrialResult +to store the results of each trial (typically a list of numbers, +but the interpretation is up to the implementation). Note: Required keyword.

    • +

  • -final code: code to be run at the end

    • +

  • -trials n: number of trials in the experiment (required)

    • +

  • -reportfile file: opened file to send the output to (default: stdout)

    • +

  • -verbose: write the intermediate results (1) or not (0) (default: 0)

    • +

  • -analysis proc: either "none" (no automatic analysis), standard +(basic statistics of the trial results and a correlation matrix) or the +name of a procedure that will take care of the analysis.

    • +

  • -columns list: list of column names, useful for verbose output +and the analysis

    • +
+

Any other options can be used via the getOption procedure +in the body.

+
+

TIPS

+

The procedure singleExperiment works by constructing a +temporary procedure that does the actual work. It loops for the given +number of trials.

+

As it constructs a temporary procedure, local variables defined at the +start continue to exist in the loop.

+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/simulation/simulation_random.html Index: embedded/www/tcllib/files/modules/simulation/simulation_random.html ================================================================== --- embedded/www/tcllib/files/modules/simulation/simulation_random.html +++ embedded/www/tcllib/files/modules/simulation/simulation_random.html @@ -0,0 +1,297 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

simulation::random(n) 0.1 tcllib "Tcl Simulation Tools"

+

Name

+

simulation::random - Pseudo-random number generators

+
+ + +

Description

+

This package consists of commands to generate pseudo-random number +generators. These new commands deliver

+
    +

  • numbers that are distributed normally, uniformly, according to a +Pareto or Gumbel distribution and so on

    • +

  • coordinates of points uniformly spread inside a sphere or a rectangle

    • +
+

For example:

+
+    set p [::simulation::random::prng_Normal -1.0 10.0]
+
+

produces a new command (whose name is stored in the variable "p") that +generates normally distributed numbers with a mean of -1.0 and a +standard deviation of 10.0.

+
+

PROCEDURES

+

The package defines the following public procedures for discrete +distributions:

+
+
::simulation::random::prng_Bernoulli p
+

Create a command (PRNG) that generates numbers with a Bernoulli +distribution: the value is either 1 or 0, with a chance p to be 1

+
+
float p
+

Chance the outcome is 1

+
+
::simulation::random::prng_Discrete n
+

Create a command (PRNG) that generates numbers 0 to n-1 with equal +probability.

+
+
int n
+

Number of different values (ranging from 0 to n-1)

+
+
::simulation::random::prng_Poisson lambda
+

Create a command (PRNG) that generates numbers according to the Poisson +distribution.

+
+
float lambda
+

Mean number per time interval

+
+
+

The package defines the following public procedures for continuous distributions:

+
+
::simulation::random::prng_Uniform min max
+

Create a command (PRNG) that generates uniformly distributed numbers +between "min" and "max".

+
+
float min
+

Minimum number that will be generated

+
float max
+

Maximum number that will be generated

+
+
::simulation::random::prng_Exponential min mean
+

Create a command (PRNG) that generates exponentially distributed numbers +with a given minimum value and a given mean value.

+
+
float min
+

Minimum number that will be generated

+
float mean
+

Mean value for the numbers

+
+
::simulation::random::prng_Normal mean stdev
+

Create a command (PRNG) that generates normally distributed numbers +with a given mean value and a given standard deviation.

+
+
float mean
+

Mean value for the numbers

+
float stdev
+

Standard deviation

+
+
::simulation::random::prng_Pareto min steep
+

Create a command (PRNG) that generates numbers distributed according to +Pareto with a given minimum value and a given distribution steepness.

+
+
float min
+

Minimum number that will be generated

+
float steep
+

Steepness of the distribution

+
+
::simulation::random::prng_Gumbel min f
+

Create a command (PRNG) that generates numbers distributed according to +Gumbel with a given minimum value and a given scale factor. The +probability density function is:

+
+     P(v) = exp( -exp(f*(v-min)))
+
+
+
float min
+

Minimum number that will be generated

+
float f
+

Scale factor for the values

+
+
::simulation::random::prng_chiSquared df
+

Create a command (PRNG) that generates numbers distributed according to +the chi-squared distribution with df degrees of freedom. The mean is 0 +and the standard deviation is 1.

+
+
float df
+

Degrees of freedom

+
+
+

The package defines the following public procedures for random point sets:

+
+
::simulation::random::prng_Disk rad
+

Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a disk of given radius.

+
+
float rad
+

Radius of the disk

+
+
::simulation::random::prng_Sphere rad
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over the surface of a sphere of given radius.

+
+
float rad
+

Radius of the disk

+
+
::simulation::random::prng_Ball rad
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread within a ball of given radius.

+
+
float rad
+

Radius of the ball

+
+
::simulation::random::prng_Rectangle length width
+

Create a command (PRNG) that generates (x,y)-coordinates for points +uniformly spread over a rectangle.

+
+
float length
+

Length of the rectangle (x-direction)

+
float width
+

Width of the rectangle (y-direction)

+
+
::simulation::random::prng_Block length width depth
+

Create a command (PRNG) that generates (x,y,z)-coordinates for points +uniformly spread over a block

+
+
float length
+

Length of the block (x-direction)

+
float width
+

Width of the block (y-direction)

+
float depth
+

Depth of the block (z-direction)

+
+
+
+ +

Category

+

Mathematics

+
+ +
ADDED embedded/www/tcllib/files/modules/smtpd/smtpd.html Index: embedded/www/tcllib/files/modules/smtpd/smtpd.html ================================================================== --- embedded/www/tcllib/files/modules/smtpd/smtpd.html +++ embedded/www/tcllib/files/modules/smtpd/smtpd.html @@ -0,0 +1,359 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

smtpd(n) 1.5 tcllib "Tcl SMTP Server Package"

+

Name

+

smtpd - Tcl SMTP server implementation

+
+ + +

Description

+

The smtpd package provides a simple Tcl-only server library +for the Simple Mail Transfer Protocol as described in +RFC 821 (http://www.rfc-editor.org/rfc/rfc821.txt) and +RFC 2821 (http://www.rfc-editor.org/rfc/rfc2821.txt). +By default the server will bind to the default network address and the +standard SMTP port (25).

+

This package was designed to permit testing of Mail User Agent code +from a developers workstation. It does not attempt to deliver mail to your mailbox. Instead users of this package are expected to +write a procedure that will be called when mail arrives. Once this +procedure returns, the server has nothing further to do with the mail.

+
+

SECURITY

+

On Unix platforms binding to the SMTP port requires root privileges. I +would not recommend running any script-based server as root unless +there is some method for dropping root privileges immediately after +the socket is bound. Under Windows platforms, it is not necessary to +have root or administrator privileges to bind low numbered +sockets. However, security on these platforms is weak anyway.

+

In short, this code should probably not be used as a permanently +running Mail Transfer Agent on an Internet connected server, even +though we are careful not to evaluate remote user input. There are +many other well tested and security audited programs that can be used +as mail servers for internet connected hosts.

+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

COMMANDS

+
+
::smtpd::start ?myaddr? ?port?
+

Start the service listening on port or the default port 25. If +myaddr is given as a domain-style name or numerical +dotted-quad IP address then the server socket will be bound to that +network interface. By default the server is bound to all network +interfaces. For example:

+
+  set sock [::smtpd::start [info hostname] 0]
+
+

will bind to the hosts internet interface on the first available port.

+

At present the package only supports a single instance of a SMTP +server. This could be changed if required at the cost of making the +package a little more complicated to read. If there is a good reason +for running multiple SMTP services then it will only be necessary to +fix the options array and the ::smtpd::stopped variable +usage.

+

As the server code uses fileevent(n) handlers to process the +input on sockets you will need to run the event loop. This means +either you should be running from within wish(1) or you +should vwait(n) on the ::smtpd::stopped variable which is +set when the server is stopped.

+
::smtpd::stop
+

Halt the server and release the listening socket. If the server has +not been started then this command does nothing. +The ::smtpd::stopped variable is set for use with +vwait(n).

+

It should be noted that stopping the server does not disconnect any +currently active sessions as these are operating over an independent +channel. Only explicitly tracking and closing these sessions, or +exiting the server process will close down all the running +sessions. This is similar to the usual unix daemon practice where the +server performs a fork(2) and the client session continues on +the child process.

+
::smptd::configure ?option value? ?option value ...?
+

Set configuration options for the SMTP server. Most values are the +name of a callback procedure to be called at various points in the +SMTP protocol. See the CALLBACKS section for details of the +procedures.

+
+
-banner text
+

Text of a custom banner message. The default banner is "tcllib smtpd 1.5". +Note that changing the banner does not affect the bracketing text +in the full greeting, printing status 220, server-address, and timestamp.

+
-validate_host proc
+

Callback to authenticate new connections based on the ip-address of +the client.

+
-validate_sender proc
+

Callback to authenticate new connections based on the senders email +address.

+
-validate_recipient proc
+

Callback to validate and authorize a recipient email address

+
-deliverMIME proc
+

Callback used to deliver mail as a mime token created by the tcllib +mime package.

+
-deliver proc
+

Callback used to deliver email. This option has no effect if +the -deliverMIME option has been set.

+
+
::smtpd::cget ?option?
+

If no option is specified the command will return a list of all +options and their current values. If an option is specified it will +return the value of that option.

+
+
+

CALLBACKS

+
+
validate_host callback
+

This procedure is called with the clients ip address as soon as a +connection request has been accepted and before any protocol commands +are processed. If you wish to deny access to a specific host then an +error should be returned by this callback. For example:

+
+ proc validate_host {ipnum} {
+    if {[string match "192.168.1.*" $ipnum]} {
+       error "go away!"
+    }
+ }
+
+

If access is denied the client will receive a standard message that +includes the text of your error, such as:

+
+ 550 Access denied: I hate you.
+
+

As per the SMTP protocol, the connection is not closed but we wait for +the client to send a QUIT command. Any other commands cause a +503 Bad Sequence error.

+
validate_sender callback
+

The validate_sender callback is called with the senders mail address +during processing of a MAIL command to allow you to accept or reject +mail based upon the declared sender. To reject mail you should throw +an error. For example, to reject mail from user "denied":

+
+ proc validate_sender {address} {
+    eval array set addr [mime::parseaddress $address]
+    if {[string match "denied" $addr(local)]} {
+         error "mailbox $addr(local) denied"
+    }
+    return
+ }
+
+

The content of any error message will not be passed back to the client.

+
validate_recipient callback
+

The validate_recipient callback is similar to the validate_sender +callback and permits you to verify a local mailbox and accept mail for +a local user address during RCPT command handling. To reject mail, +throw an error as above. The error message is ignored.

+
deliverMIME callback
+

] +The deliverMIME callback is called once a mail message has been +successfully passed to the server. A mime token is constructed from +the sender, recipients and data and the users procedure it called with +this single argument. When the call returns, the mime token is cleaned +up so if the user wishes to preserve the data she must make a copy.

+
+ proc deliverMIME {token} {
+     set sender [lindex [mime::getheader $token From] 0]
+     set recipients [lindex [mime::getheader $token To] 0]
+     set mail "From $sender [clock format [clock seconds]]"
+     append mail "\n" [mime::buildmessage $token]
+     puts $mail
+ }
+
+
+
deliver callback
+

The deliver callback is called once a mail message has been +successfully passed to the server and there is no -deliverMIME option +set. The procedure is called with the sender, a list of recipients and +the text of the mail as a list of lines. For example:

+
+ proc deliver {sender recipients data} {
+    set mail "From $sender  [clock format [clock seconds]]"
+    append mail "\n" [join $data "\n"]
+    puts "$mail"
+ }
+
+

Note that the DATA command will return an error if no sender or +recipient has yet been defined.

+
+
+

VARIABLES

+
+
::smtpd::stopped
+

This variable is set to true during the ::smtpd::stop +command to permit the use of the vwait(n) command.

+
+
+ +

LICENSE

+

This software is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file +"license.terms" for more details.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category smtpd of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/snit/snit.html Index: embedded/www/tcllib/files/modules/snit/snit.html ================================================================== --- embedded/www/tcllib/files/modules/snit/snit.html +++ embedded/www/tcllib/files/modules/snit/snit.html @@ -0,0 +1,2070 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

snit(n) 2.3.2 tcllib "Snit's Not Incr Tcl, OO system"

+

Name

+

snit - Snit's Not Incr Tcl

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit ?2.3.2?
    • +
+ +
+
+

Description

+

Snit is a pure Tcl object and megawidget system. It's +unique among Tcl object systems in that it's based not on inheritance +but on delegation. Object systems based on inheritance only allow you +to inherit from classes defined using the same system, which is +limiting. In Tcl, an object is +anything that acts like an object; it shouldn't matter how the object +was implemented. Snit is intended to help you build applications out of +the materials at hand; thus, Snit is designed to be able to +incorporate and build on any object, whether it's a hand-coded object, +a Tk widget, an Incr Tcl object, +a BWidget or almost anything else.

+

This man page is intended to be a reference only; see the accompanying +snitfaq for a gentler, more tutorial introduction to Snit +concepts.

+
+

SNIT VERSIONS

+

This man page covers both Snit 2.2 and Snit 1.3. The primary +difference between the two versions is simply that Snit 2.2 contains +speed optimizations based on new features of Tcl 8.5; Snit 1.3 +supports all of Tcl 8.3, 8.4 and Tcl 8.5. There are a few minor +inconsistencies; they are flagged in the body of the man page with the +label "Snit 1.x Incompatibility"; they are also discussed in the snitfaq.

+
+

REFERENCE

+

Type and Widget Definitions

+

Snit provides the following commands for defining new types:

+
+
snit::type name definition
+

Defines a new abstract data type called name. If name is +not a fully qualified command name, it is assumed to be a name in the +namespace in which the snit::type command was called (usually the +global namespace). It returns the fully qualified name of the new type.

+

The type name is then a command that is used to create objects of the +new type, along with other activities.

+

The snit::type definition block is a script that may +contain the following definitions:

+
+
typevariable name ?-array? ?value?
+

Defines a type variable with the specified name, and optionally +the specified value. Type variables are shared by all instances +of the type. If the -array option is included, then +value should be a dictionary; it will be +assigned to the variable using array set.

+
typemethod name arglist body
+

Defines a type method, a subcommand of the new type command, +with the specified name, argument list, and +body. The arglist is a normal Tcl argument list and may contain +default arguments and the args argument; however, it may not +contain the argument names type, self, selfns, or +win.

+

The variable type is automatically defined in the body to +the type's fully-qualified name. In addition, +type variables are automatically visible in the body +of every type method.

+

If the name consists of two or more tokens, Snit handles it specially:

+
    typemethod {a b} {arg} { puts "Got $arg" }
+
+

This statement implicitly defines a type method called a which +has a subcommand b. b is called like this:

+
    $type a b "Hello, world!"
+
+

a may have any number of subcommands. This makes it possible +to define a hierarchical command structure; see method, below, +for more examples.

+

Type methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type's type methods can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+

Snit 1.x Incompatibility: In Snit 1.x, the following +following two calls to this type method are equivalent:

+
    $type a b "Hello, world!"
+    $type {a b} "Hello, world!"
+
+

In Snit 2.2, the second form is invalid.

+
typeconstructor body
+

The type constructor's body is executed once when the +type is first defined; it is typically used to +initialize array-valued type variables and to add +entries to The Tk Option Database.

+

The variable type is automatically defined in the body, +and contains the type's fully-qualified name. In addition, +type variables are automatically visible in the body of the type +constructor.

+

A type may define at most one type constructor.

+

The type constructor can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type constructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
variable name ?-array? ?value?
+

Defines an instance variable, a private variable associated with each +instance of this type, and optionally its initial value. +If the -array option is included, then +value should be a dictionary; it will be +assigned to the variable using array set.

+
method name arglist body
+

Defines an instance method, a subcommand of each instance of this +type, with the specified name, argument list and body. +The arglist is a normal Tcl argument list and may contain +default arguments and the args argument.

+

The method is implicitly passed the following arguments as well: +type, which contains the fully-qualified type name; self, +which contains the current instance command name; selfns, which +contains the name of the instance's private namespace; and win, +which contains the original instance name. +Consequently, the arglist may not contain the argument names +type, self, selfns, or win.

+

An instance method defined in this way is said to be +locally defined.

+

Type and instance variables are +automatically visible in all instance methods. If the type has +locally defined options, the options array is also visible.

+

If the name consists of two or more tokens, Snit handles it specially:

+
    method {a b} {} { ... }
+
+

This statement implicitly defines a method called a which +has a subcommand b. b is called like this:

+
    $self a b "Hello, world!"
+
+

a may have any number of subcommands. This makes it possible +to define a hierarchical command structure:

+
% snit::type dog {
+    method {tail wag}   {} {return "Wag, wag"}
+    method {tail droop} {} {return "Droop, droop"}
+}
+::dog
+% dog spot
+::spot
+% spot tail wag
+Wag, wag
+% spot tail droop
+Droop, droop
+%
+
+

What we've done is implicitly defined a "tail" method with subcommands +"wag" and "droop". Consequently, it's an error to define "tail" +explicitly.

+

Methods can call commands from the namespace in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the type's methods can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+

Snit 1.x Incompatibility: In Snit 1.x, the following +following two calls to this method are equivalent:

+
    $self a b "Hello, world!"
+    $self {a b} "Hello, world!"
+
+

In Snit 2.2, the second form is invalid.

+
option namespec ?defaultValue?
+
+
option namespec ?options...?
+

Defines an option for instances of this type, and optionally gives it +an initial value. The initial value defaults to the empty string if +no defaultValue is specified.

+

An option defined in this way is said to be locally defined.

+

The namespec is a list defining the option's +name, resource name, and class name, e.g.:

+
    option {-font font Font} {Courier 12}
+
+

The option name must begin with a hyphen, and must not contain any +upper case letters. The resource name and class name are optional; if +not specified, the resource name defaults to the option name, minus +the hyphen, and the class name defaults to the resource name with the +first letter capitalized. Thus, the following statement is equivalent +to the previous example:

+
    option -font {Courier 12}
+
+

See The Tk Option Database for more information about +resource and class names.

+

Options are normally set and retrieved using the standard +instance methods configure and cget; within instance code +(method bodies, etc.), option values are available through the +options array:

+
    set myfont $options(-font)
+
+

If the type defines any option handlers (e.g., -configuremethod), +then it should probably use configure and cget to +access its options to avoid subtle errors.

+

The option statement may include the following options:

+
+
-default defvalue
+

Defines the option's default value; the option's default value +will be "" otherwise.

+
-readonly flag
+

The flag can be any Boolean value recognized by Tcl. +If flag is true, then the option is read-only--it can only +be set using configure or configurelist +at creation time, i.e., in the type's constructor.

+
-type type
+

Every locally-defined option may define its validation type, which may +be either the name of a validation type or a specification for a +validation subtype

+

For example, an option may declare that its value must be an integer +by specifying snit::integer as its validation type:

+
    option -number -type snit::integer
+
+

It may also declare that its value is an integer between 1 and 10 +by specifying a validation subtype:

+
    option -number -type {snit::integer -min 1 -max 10}
+
+

If a validation type or subtype is defined for an option, then +it will be used to validate the option's value whenever it is +changed by the object's configure or +configurelist methods. In addition, all such options +will have their values validated automatically immediately +after the constructor executes.

+

Snit defines a family of validation types and subtypes, and it's +quite simple to define new ones. See +Validation Types for the complete list, and +Defining Validation Types for an explanation of how +to define your own.

+
-cgetmethod methodName
+

Every locally-defined option may define a -cgetmethod; +it is called when the option's value is retrieved using the +cget method. Whatever the method's body returns will +be the return value of the call to cget.

+

The named method must take one argument, the option name. +For example, this code is equivalent to (though slower than) +Snit's default handling of cget:

+
    option -font -cgetmethod GetOption
+    method GetOption {option} {
+        return $options($option)
+    }
+
+

Note that it's possible for any number of options to share a +-cgetmethod.

+
-configuremethod methodName
+

Every locally-defined option may define a -configuremethod; +it is called when the option's value is set using the +configure or configurelist methods. It is the +named method's responsibility to save the option's value; in other +words, the value will not be saved to the options() array unless +the method saves it there.

+

The named method must take two arguments, the option name and +its new value. For example, this code is equivalent to +(though slower than) Snit's default handling of configure:

+
    option -font -configuremethod SetOption
+    method SetOption {option value} {
+        set options($option) $value
+    }
+
+

Note that it's possible for any number of options to share a +single -configuremethod.

+
-validatemethod methodName
+

Every locally-defined option may define a -validatemethod; +it is called when the option's value is set using the +configure or configurelist methods, just before +the -configuremethod (if any). It is the +named method's responsibility to validate the option's new value, +and to throw an error if the value is invalid.

+

The named method must take two arguments, the option name and +its new value. For example, this code verifies that +-flag's value is a valid Boolean value:

+
    option -font -validatemethod CheckBoolean
+    method CheckBoolean {option value} {
+        if {![string is boolean -strict $value]} {
+            error "option $option must have a boolean value."
+        }
+    }
+
+

Note that it's possible for any number of options to share a +single -validatemethod.

+
+
constructor arglist body
+

The constructor definition specifies a body of code to be +executed when a new instance is created. The arglist is a +normal Tcl argument list and may contain default arguments and +the args argument.

+

As with methods, the arguments type, self, selfns, +and win are defined implicitly, and all type and instance +variables are automatically visible in its body.

+

If the definition doesn't explicitly define the constructor, +Snit defines one implicitly. If the type declares at least one option +(whether locally or by delegation), the default constructor will +be defined as follows:

+
    constructor {args} {
+        $self configurelist $args
+    }
+
+

For standard Tk widget behavior, the argument list should be +the single name args, as shown.

+

If the definition defines neither a constructor nor +any options, the default constructor is defined as follows:

+
    constructor {} {}
+
+

As with methods, the constructor can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the constructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
destructor body
+

The destructor is used to code any actions that must take place when +an instance of the type is destroyed: typically, the destruction of +anything created in the constructor.

+

The destructor takes no explicit arguments; as with methods, the +arguments type, self, selfns, and win, are +defined implicitly, and all type and instance +variables are automatically visible in its body. +As with methods, the destructor can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the destructor can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
proc name args body
+

Defines a new Tcl procedure in the type's namespace.

+

The defined proc differs from a normal Tcl proc in that all type +variables are automatically visible. The proc can access +instance variables as well, provided that it is passed +selfns (with precisely that name) as one of its arguments.

+

Although they are not implicitly defined for procs, the argument names +type, self, and win should be avoided.

+

As with methods and typemethods, procs can call commands from the namespace +in which the type is +defined without importing them, e.g., if the type name is +::parentns::typename, then the proc can call +::parentns::someproc just as someproc. +Snit 1.x Incompatibility: This does not work in Snit 1.x, as +it depends on namespace path, a new command in Tcl 8.5.

+
delegate method name to comp ?as target?
+

Delegates method name to component comp. That is, when +method name is called on an instance of this type, the method +and its arguments will be passed to the named component's command +instead. That is, the following statement

+
    delegate method wag to tail
+
+

is roughly equivalent to this explicitly defined method:

+
    method wag {args} {
+        uplevel $tail wag $args
+    }
+
+

As with methods, the name may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method.

+

The optional as clause allows you to specify the delegated +method name and possibly add some arguments:

+
    delegate method wagtail to tail as "wag briskly"
+
+

A method cannot be both locally defined and delegated.

+

Note: All forms of delegate method can delegate to +both instance components and type components.

+
delegate method name ?to comp? using pattern
+

In this form of the delegate statement, the using clause +is used to specify the precise form of the command to which method +name name is delegated. In this form, the to clause is +optional, since the chosen command might not involve any particular +component.

+

The value of the using clause is a list that may contain +any or all of the following substitution codes; these codes are +substituted with the described value to build the delegated command +prefix. Note that the following two statements are equivalent:

+
    delegate method wag to tail
+    delegate method wag to tail using "%c %m"
+
+

Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string.

+

Substitutions:

+
+
%%
+

This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c".

+
%c
+

This is replaced with the named component's command.

+
%m
+

This is replaced with the final token of the method name; if +the method name has one token, this is identical to %M.

+
%M
+

This is replaced by the method name; if the name consists +of multiple tokens, they are joined by space characters.

+
%j
+

This is replaced by the method name; if the name consists +of multiple tokens, they are joined by underscores ("_").

+
%t
+

This is replaced with the fully qualified type name.

+
%n
+

This is replaced with the name of the instance's private namespace.

+
%s
+

This is replaced with the name of the instance command.

+
%w
+

This is replaced with the original name of the instance command; for +Snit widgets and widget adaptors, it will be the Tk window name. +It remains constant, even if the instance command is renamed.

+
+
delegate method * ?to comp? ?using pattern? ?except exceptions?
+

The form delegate method * delegates all unknown method names to the +specified component. The except clause can be used to +specify a list of exceptions, i.e., method names that will not +be so delegated. The using clause is defined as given above. +In this form, the statement must contain the to clause, the +using clause, or both.

+

In fact, the "*" can be a list of two or more tokens whose last +element is "*", as in the following example:

+
    delegate method {tail *} to tail
+
+

This implicitly defines the method tail whose subcommands will +be delegated to the tail component.

+
delegate option namespec to comp
+
+
delegate option namespec to comp as target
+
+
delegate option * to comp
+
+
delegate option * to comp except exceptions
+

Defines a delegated option; the namespec is defined as for the +option statement. +When the configure, configurelist, or cget +instance method is used to set or retrieve the option's value, the +equivalent configure or cget command will be applied +to the component as though the option was defined with the following +-configuremethod and -cgetmethod:

+
    method ConfigureMethod {option value} {
+        $comp configure $option $value
+    }
+    method CgetMethod {option} {
+        return [$comp cget $option]
+    }
+
+

Note that delegated options never appear in the options array.

+

If the as clause is specified, then the target option +name is used in place of name.

+

The form delegate option * delegates all unknown options to the +specified component. The except clause can be used to +specify a list of exceptions, i.e., option names that will not +be so delegated.

+

Warning: options can only be delegated to a component if it supports +the configure and cget instance methods.

+

An option cannot be both locally defined and delegated. +TBD: Continue from here.

+
component comp ?-public method? ?-inherit flag?
+

Explicitly declares a component called comp, and automatically +defines the component's instance variable.

+

If the -public option is specified, then the option is made +public by defining a method whose subcommands are delegated +to the component e.g., specifying -public mycomp is +equivalent to the following:

+
    component mycomp
+    delegate method {mymethod *} to mycomp
+
+

If the -inherit option is specified, then flag must be a +Boolean value; if flag is true then all unknown methods and +options will be delegated to this component. The name -inherit +implies that instances of this new type inherit, in a sense, the +methods and options of the component. That is, -inherit yes is +equivalent to:

+
    component mycomp
+    delegate option * to mycomp
+    delegate method * to mycomp
+
+
+
delegate typemethod name to comp ?as target?
+

Delegates type method name to type component comp. That is, when +type method name is called on this type, the type method +and its arguments will be passed to the named type component's command +instead. That is, the following statement

+
    delegate typemethod lostdogs to pound
+
+

is roughly equivalent to this explicitly defined method:

+
    typemethod lostdogs {args} {
+        uplevel $pound lostdogs $args
+    }
+
+

As with type methods, the name may have multiple tokens; in this +case, the last token of the name is assumed to be the name of the +component's method.

+

The optional as clause allows you to specify the delegated +method name and possibly add some arguments:

+
    delegate typemethod lostdogs to pound as "get lostdogs"
+
+

A type method cannot be both locally defined and delegated.

+
delegate typemethod name ?to comp? using pattern
+

In this form of the delegate statement, the using clause +is used to specify the precise form of the command to which type method +name name is delegated. In this form, the to clause is +optional, since the chosen command might not involve any particular +type component.

+

The value of the using clause is a list that may contain +any or all of the following substitution codes; these codes are +substituted with the described value to build the delegated command +prefix. Note that the following two statements are equivalent:

+
    delegate typemethod lostdogs to pound
+    delegate typemethod lostdogs to pound using "%c %m"
+
+

Each element of the list becomes a single element of the delegated +command--it is never reparsed as a string.

+

Substitutions:

+
+
%%
+

This is replaced with a single "%". Thus, to pass the string "%c" +to the command as an argument, you'd write "%%c".

+
%c
+

This is replaced with the named type component's command.

+
%m
+

This is replaced with the final token of the type method name; if +the type method name has one token, this is identical to %M.

+
%M
+

This is replaced by the type method name; if the name consists +of multiple tokens, they are joined by space characters.

+
%j
+

This is replaced by the type method name; if the name consists +of multiple tokens, they are joined by underscores ("_").

+
%t
+

This is replaced with the fully qualified type name.

+
+
delegate typemethod * ?to comp? ?using pattern? ?except exceptions?
+

The form delegate typemethod * delegates all unknown type +method names to the +specified type component. The except clause can be used to +specify a list of exceptions, i.e., type method names that will not +be so delegated. The using clause is defined as given above. +In this form, the statement must contain the to clause, the +using clause, or both.

+

Note: By default, Snit interprets $type foo, where +foo is +not a defined type method, as equivalent to $type create foo, where +foo is the name of a new instance of the type. If you +use delegate typemethod *, then the create type +method must always be used explicitly.

+

The "*" can be a list of two or more tokens whose last +element is "*", as in the following example:

+
    delegate typemethod {tail *} to tail
+
+

This implicitly defines the type method tail whose subcommands will +be delegated to the tail type component.

+
typecomponent comp ?-public typemethod? ?-inherit flag?
+

Explicitly declares a type component called comp, and automatically +defines the component's type variable. A type component is an arbitrary +command to which type methods and instance methods can be delegated; +the command's name is stored in a type variable.

+

If the -public option is specified, then the type component is made +public by defining a typemethod whose subcommands are delegated to +the type component, e.g., specifying -public mytypemethod +is equivalent to the following:

+
    typecomponent mycomp
+    delegate typemethod {mytypemethod *} to mycomp
+
+

If the -inherit option is specified, then flag must be a +Boolean value; if flag is true then all unknown type methods +will be delegated to this type component. (See the note on "delegate +typemethod *", above.) The name -inherit +implies that this type inherits, in a sense, the behavior of +the type component. That is, -inherit yes is equivalent to:

+
    typecomponent mycomp
+    delegate typemethod * to mycomp
+
+
+
pragma ?options...?
+

The pragma statement provides control over how Snit generates a +type. It takes the following options; in each case, flag must +be a Boolean value recognized by Tcl, e.g., 0, 1, +yes, no, and so +on.

+

By setting the -hastypeinfo, -hastypedestroy, and +-hasinstances pragmas to false and defining appropriate +type methods, you can create an ensemble command without any extraneous +behavior.

+
+
-canreplace flag
+

If false (the default) Snit will not create an instance of a +snit::type that has the same name as an existing command; this +prevents subtle errors. Setting this pragma to true restores the +behavior of Snit V0.93 and earlier versions.

+
-hastypeinfo flag
+

If true (the default), the generated type will have a type method +called info that is used for type introspection; the info +type method is documented below. If false, it will not.

+
-hastypedestroy flag
+

If true (the default), the generated type will have a type method +called destroy that is used to destroy the type and all of its +instances. The destroy type method is documented below. If +false, it will not.

+
-hastypemethods flag
+

If true (the default), the generated type's type command will have +subcommands (type methods) as usual. If false, the type command +will serve only to create instances of the type; the first argument +is the instance name.

+

This pragma and -hasinstances cannot both be set false.

+
-hasinstances flag
+

If true (the default), the generated type will have a type method +called create that is used to create instances of the type, +along with a variety of instance-related features. If false, it will +not.

+

This pragma and -hastypemethods cannot both be set false.

+
-hasinfo flag
+

If true (the default), instances of the generated type will have +an instance method called info that is used for +instance introspection; the info +method is documented below. If false, it will not.

+
-simpledispatch flag
+

This pragma is intended to make simple, heavily-used abstract +data types (e.g., stacks and queues) more efficient.

+

If false (the default), instance methods are dispatched normally. If +true, a faster dispatching scheme is used instead. +The speed comes at a price; with -simpledispatch yes you +get the following limitations:

+
    +

  • Methods cannot be delegated.

    • +

  • uplevel and upvar do not work as expected: the +caller's scope is two levels up rather than one.

    • +

  • The option-handling methods +(cget, configure, and configurelist) are very +slightly slower.

    • +
+
+
expose comp
+
+
expose comp as method
+

Deprecated. To expose component comp publicly, use +component's -public option.

+
onconfigure name arglist body
+

Deprecated. Define option's -configuremethod +option instead.

+

As of version 0.95, the following definitions,

+
    option -myoption
+    onconfigure -myoption {value} {
+        # Code to save the option's value
+    }
+
+

are implemented as follows:

+
    option -myoption -configuremethod _configure-myoption
+    method _configure-myoption {_option value} {
+        # Code to save the option's value
+    }
+
+
+
oncget name body
+

Deprecated. Define option's -cgetmethod +option instead.

+

As of version 0.95, the following definitions,

+
    option -myoption
+    oncget -myoption {
+        # Code to return the option's value
+    }
+
+

are implemented as follows:

+
    option -myoption -cgetmethod _cget-myoption
+    method _cget-myoption {_option} {
+        # Code to return the option's value
+    }
+
+
+
+
snit::widget name definition
+

This command defines a Snit megawidget type with the specified +name. The definition is defined as for snit::type. + A snit::widget differs from a snit::type +in these ways:

+
    +

  • Every instance of a snit::widget has an automatically-created +component called hull, which is normally a Tk frame widget. +Other widgets created as part of the megawidget will be created within +this widget.

    +

    The hull component is initially created with the requested widget +name; then Snit does some magic, renaming the hull component and +installing its own instance command in its place. +The hull component's new name is saved in an instance variable called +hull.

    • +

  • The name of an instance must be valid Tk window name, and the parent +window must exist.

    • +
+

A snit::widget definition can include any of statements allowed +in a snit::type definition, and may also include the following:

+
+
widgetclass name
+

Sets the snit::widget's widget class to name, overriding +the default. See The Tk Option Database for more +information.

+
hulltype type
+

Determines the kind of widget used as the snit::widget's hull. +The type may be frame (the default), toplevel, +labelframe; the qualified equivalents of these, +tk::frame, tk::toplevel, and tk::labelframe; +or, if available, the equivalent Tile widgets: +ttk::frame, ttk::toplevel, and +ttk::labelframe. In practice, any widget that supports the +-class option can be used as a hull widget by +lappend'ing its name to the variable snit::hulltypes.

+
+
snit::widgetadaptor name definition
+

This command defines a Snit megawidget type with the specified name. +It differs from snit::widget in that the instance's hull +component is not created automatically, but is created in the +constructor and installed using the installhull command. Once +the hull is installed, its instance command is renamed and replaced as +with normal snit::widgets. The original command is again +accessible in the instance variable hull.

+

Note that in general it is not possible to change the +widget class of a snit::widgetadaptor's hull widget.

+

See The Tk Option Database for information on how +snit::widgetadaptors interact with the option database.

+
snit::typemethod type name arglist body
+

Defines a new type method (or redefines an existing type method) +for a previously existing type.

+
snit::method type name arglist body
+

Defines a new instance method (or redefines an existing instance +method) for a previously existing type. Note that delegated +instance methods can't be redefined.

+
snit::macro name arglist body
+

Defines a Snit macro with the specified name, arglist, and +body. Macros are used to define new type and widget +definition statements in terms of the statements defined in this man +page.

+

A macro is simply a Tcl proc that is defined in the slave interpreter +used to compile type and widget definitions. Thus, macros have +access to all of the type and widget definition statements. See +Macros and Meta-programming for more details.

+

The macro name cannot be the same as any standard Tcl command, +or any Snit type or widget definition statement, e.g., you can't +redefine the method or delegate statements, or the +standard set, list, or string commands.

+
snit::compile which type body
+

Snit defines a type, widget, or widgetadaptor by "compiling" the +definition into a Tcl script; this script is then evaluated in the +Tcl interpreter, which actually defines the new type.

+

This command exposes the "compiler". Given a definition body +for the named type, where which is type, +widget, or widgetadaptor, snit::compile returns a list +of two elements. The first element is the fully qualified type name; +the second element is the definition script.

+

snit::compile is useful when additional processing +must be done on the Snit-generated code--if it must be instrumented, +for example, or run through the TclDevKit compiler. In addition, the +returned script could be saved in a ".tcl" file and used to define the +type as part of an application or library, thus saving the compilation +overhead at application start-up. Note that the +same version of Snit must be used at run-time as at compile-time.

+
+
+

The Type Command

+

A type or widget definition creates a type command, which is used to +create instances of the type. The type command has this form:

+
+
$type typemethod args...
+

The typemethod can be any of the +Standard Type Methods (e.g., create), +or any type method defined in the type +definition. +The subsequent args depend on the specific typemethod +chosen.

+

The type command is most often used to create new instances of the +type; hence, the create method is assumed if the first +argument to the type command doesn't name a valid type method, unless +the type definition includes delegate typemethod * or the +-hasinstances pragma is set to false.

+

Furthermore, if the -hastypemethods pragma is false, then +Snit type commands can be called with no arguments at +all; in this case, the type command creates an instance with an +automatically generated name. In other words, provided that the +-hastypemethods pragma is false and the type +has instances, the following commands are equivalent:

+
snit::type dog { ... }
+set mydog [dog create %AUTO%]
+set mydog [dog %AUTO%]
+set mydog [dog]
+
+

This doesn't work for Snit widgets, for obvious reasons.

+

Snit 1.x Incompatibility: In Snit 1.x, the above behavior is +available whether -hastypemethods is true (the default) or false.

+
+
+

Standard Type Methods

+

In addition to any type methods in the type's definition, all type and +widget commands will usually have at least the following subcommands:

+
+
$type create name ?option value ...?
+

Creates a new instance of the type, giving it the specified name +and calling the type's constructor.

+

For snit::types, if name is not a fully-qualified command +name, it is assumed to be a name in the namespace in which the call to +snit::type appears. The method returns the fully-qualified +instance name.

+

For snit::widgets and snit::widgetadaptors, name +must be a valid widget name; the method returns the widget name.

+

So long as name does not conflict with any defined type method +name the create keyword may be omitted, unless +the type definition includes delegate typemethod * or the +-hasinstances pragma is set to false.

+

If the name includes the string %AUTO%, it will be +replaced with the string $type$counter where $type is +the type name and $counter is a counter that increments each +time %AUTO% is used for this type.

+

By default, any arguments following the name will be a list of +option names and their values; however, a type's +constructor can specify a different argument list.

+

As of Snit V0.95, create will throw an error if the name +is the same as any existing command--note that this was always true +for snit::widgets and snit::widgetadaptors. You can +restore the previous behavior using the -canreplace pragma.

+
$type info typevars ?pattern?
+

Returns a list of the type's type variables (excluding Snit internal +variables); all variable names are fully-qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$type info typemethods ?pattern?
+

Returns a list of the names of the type's type methods. +If the type has hierarchical +type methods, whether locally-defined or delegated, only the first +word of each will be included in the list.

+

If the type +definition includes delegate typemethod *, the list will +include only the names of those implicitly delegated type methods +that have been called at least once and are still in the type method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$type info args method
+

Returns a list containing the names of the arguments to the type's +method, in order. This method cannot be applied to delegated +type methods.

+
$type info body method
+

Returns the body of typemethod method. This method cannot be +applied to delegated type methods.

+
$type info default method aname varname
+

Returns a boolean value indicating whether the argument aname of +the type's method has a default value (true) or not +(false). If the argument has a default its value is placed into +the variable varname.

+
$type info instances ?pattern?
+

Returns a list of the type's instances. For snit::types, it +will be a list of fully-qualified instance names; +for snit::widgets, it will be a list of Tk widget names.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$type destroy
+

Destroys the type's instances, the type's namespace, and the type +command itself.

+
+
+

The Instance Command

+

A Snit type or widget's create type method creates objects of +the type; each object has a unique name that is also a Tcl command. +This command is used to access the object's methods and data, and has +this form:

+
+
$object method args...
+

The method can be any of the +Standard Instance Methods, or any instance method +defined in the type definition. +The subsequent args depend on the specific method chosen.

+
+
+

Standard Instance Methods

+

In addition to any delegated or locally-defined instance methods in +the type's definition, all Snit objects will have at least the +following subcommands:

+
+
$object configure ?option? ?value? ...
+

Assigns new values to one or more options. If called with one +argument, an option name, returns a list describing the option, +as Tk widgets do; if called with no arguments, returns a list of lists +describing all options, as Tk widgets do.

+

Warning: This information will be available for delegated options only +if the component to which they are delegated has a configure +method that returns this same kind of information.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object configurelist optionlist
+

Like configure, but takes one argument, a list of options and +their values. It's mostly useful in the type constructor, but can be +used anywhere.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object cget option
+

Returns the option's value.

+

Note: Snit defines this method only if the type has at least one +option.

+
$object destroy
+

Destroys the object, calling the destructor and freeing all +related memory.

+

Note: +The destroy method isn't defined for snit::widget or +snit::widgetadaptor objects; instances of these are destroyed by +calling Tk's destroy command, just as normal +widgets are.

+
$object info type
+

Returns the instance's type.

+
$object info vars ?pattern?
+

Returns a list of the object's instance variables (excluding Snit +internal variables). The names are fully qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$object info typevars ?pattern?
+

Returns a list of the object's type's type variables (excluding Snit +internal variables). The names are fully qualified.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+
$object info typemethods ?pattern?
+

Returns a list of the names of the type's type methods. +If the type has hierarchical +type methods, whether locally-defined or delegated, only the first +word of each will be included in the list.

+

If the type +definition includes delegate typemethod *, the list will +include only the names of those implicitly delegated type methods +that have been called at least once and are still in the type method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$object info options ?pattern?
+

Returns a list of the object's option names. This always includes +local options and explicitly delegated options. If unknown options +are delegated as well, and if the component to which they are +delegated responds to $object configure like Tk widgets do, +then the result will include all possible unknown options that can +be delegated to the component.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Note that the return value might be different for different instances +of the same type, if component object types can vary from one instance +to another.

+
$object info methods ?pattern?
+

Returns a list of the names of the instance's methods. +If the type has hierarchical methods, whether locally-defined or +delegated, only the first word of each will be included in the list.

+

If the type +definition includes delegate method *, the list will +include only the names of those implicitly delegated methods that have +been called at least once and are still in the method cache.

+

If pattern is given, it's used as a string match +pattern; only names that match the pattern are returned.

+

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word +names of hierarchical type methods are included in the return value.

+
$object info args method
+

Returns a list containing the names of the arguments to the instance's +method, in order. This method cannot be applied to delegated methods.

+
$object info body method
+

Returns the body of the instance's method method. This method +cannot be applied to delegated methods.

+
$object info default method aname varname
+

Returns a boolean value indicating whether the argument aname of +the instance's method has a default value (true) or not +(false). If the argument has a default its value is placed into +the variable varname.

+
+
+

Commands for use in Object Code

+

Snit defines the following commands for use in your object code: +that is, for use in type methods, instance methods, constructors, +destructors, onconfigure handlers, oncget handlers, and procs. +They do not reside in the ::snit:: namespace; instead, they are +created with the type, and can be used without qualification.

+
+
mymethod name ?args...?
+

The mymethod command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke method name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's +dosomething method to be called when the $button is pressed:

+
    $button configure -command [list $self dosomething myargument]
+    $button configure -command [mymethod dosomething myargument]
+
+

The chief distinction between the two is that the latter form will not +break if the object's command is renamed.

+
mytypemethod name ?args...?
+

The mytypemethod command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke type method name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's dosomething type method +to be called when $button is pressed:

+
    $button configure -command [list $type dosomething myargument]
+    $button configure -command [mytypemethod dosomething myargument]
+
+

Type commands cannot be renamed, so in practice there's little +difference between the two forms. mytypemethod is provided for +parallelism with mymethod.

+
myproc name ?args...?
+

The myproc command is used for formatting callback commands to +be passed to other objects. It returns a command that when called +will invoke the type proc name with the specified arguments, plus of +course any arguments added by the caller. In other words, both of the +following commands will cause the object's dosomething proc +to be called when $button is pressed:

+
    $button configure -command [list ${type}::dosomething myargument]
+    $button configure -command [myproc dosomething myargument]
+
+
+
myvar name
+

Given an instance variable name, returns the fully qualified name. +Use this if you're passing the variable to some other object, e.g., as +a -textvariable to a Tk label widget.

+
mytypevar name
+

Given an type variable name, returns the fully qualified name. Use +this if you're passing the variable to some other object, e.g., as a +-textvariable to a Tk label widget.

+
from argvName option ?defvalue?
+

The from command plucks an option value from a list of options +and their values, such as is passed into a type's constructor. +argvName must be the name of a variable containing such a list; +option is the name of the specific option.

+

from looks for option in the option list. If it is found, +it and its value are removed from the list, and the value is returned. +If option doesn't appear in the list, then the defvalue is +returned. +If the option is locally-defined option, and defvalue is +not specified, then the option's default value as specified in the +type definition will be returned instead.

+
install compName using objType objName args...
+

Creates a new object of type objType called objName +and installs it as component compName, +as described in Components and Delegation. Any additional +args... are passed along with the name to the objType +command. +If this is a snit::type, then the following two commands are +equivalent:

+
    install myComp using myObjType $self.myComp args...
+    set myComp [myObjType $self.myComp args...]
+
+

Note that whichever method is used, compName must still be +declared in the type definition using component, or must be +referenced in at least one delegate statement.

+

If this is a snit::widget or snit::widgetadaptor, and if +options have been delegated to component compName, then those +options will receive default values from the Tk option database. Note +that it doesn't matter whether the component to be installed is a +widget or not. See The Tk Option Database for more +information.

+

install cannot be used to install type components; just assign +the type component's command name to the type component's variable +instead.

+
installhull using widgetType args...
+
+
installhull name
+

The constructor of a snit::widgetadaptor must create a widget to +be the object's hull component; the widget is installed as the hull +component using this command. Note that the installed widget's name +must be $win. +This command has two forms.

+

The first form specifies the widgetType and the args... +(that is, the hardcoded option list) to use in creating the hull. +Given this form, installhull creates the hull widget, and +initializes any options delegated to the hull from the Tk option +database.

+

In the second form, the hull widget has already been created; note +that its name must be "$win". In this case, the Tk option database is +not queried for any options delegated to the hull. +The longer form is preferred; however, the shorter form allows the +programmer to adapt a widget created elsewhere, which is sometimes +useful. For example, it can be used to adapt a "page" widget created +by a BWidgets tabbed notebook or pages manager widget.

+

See The Tk Option Database for more information +about snit::widgetadaptors and the option database.

+
variable name
+

Normally, instance variables are defined in the type definition along +with the options, methods, and so forth; such instance variables are +automatically visible in all instance code (e.g., method bodies). However, +instance code can use the variable command to declare instance variables +that don't appear in the type definition, and also to bring variables +from other namespaces into scope in the usual way.

+

It's generally clearest to define all instance variables in the type +definition, and omit declaring them in methods and so forth.

+

Note that this is an instance-specific version of the standard Tcl +::variable command.

+
typevariable name
+

Normally, type variables are defined in the type definition, along +with the instance variables; such type variables are automatically +visible in all of the type's code. However, type methods, instance +methods and so forth can use typevariable to declare type +variables that don't appear in the type definition.

+

It's generally clearest to declare all type variables in the type +definition, and omit declaring them in methods, type methods, etc.

+
varname name
+

Deprecated. Use myvar instead.

+

Given an instance variable name, returns the fully qualified name. +Use this if you're passing the variable to some other object, e.g., as +a -textvariable to a Tk label widget.

+
typevarname name
+

Deprecated. Use mytypevar instead.

+

Given a type variable name, returns the fully qualified name. Use +this if you're passing the type variable to some other object, e.g., as a +-textvariable to a Tk label widget.

+
codename name
+

Deprecated. Use myproc instead. +Given the name of a proc (but not a type or instance method), returns +the fully-qualified command name, suitable for passing as a callback.

+
+
+

Components and Delegation

+

When an object includes other objects, as when a toolbar contains +buttons or a GUI object contains an object that references a database, +the included object is called a component. The standard way to handle +component objects owned by a Snit object is to declare them using +component, which creates a component instance variable. +In the following example, a dog object has a +tail object:

+
    snit::type dog {
+        component mytail
+        constructor {args} {
+            set mytail [tail %AUTO% -partof $self]
+            $self configurelist $args
+        }
+        method wag {} {
+            $mytail wag
+        }
+    }
+    snit::type tail {
+        option -length 5
+        option -partof
+        method wag {} { return "Wag, wag, wag."}
+    }
+
+

Because the tail object's name is stored in an instance +variable, it's easily accessible in any method.

+

The install command provides an alternate way +to create and install the component:

+
    snit::type dog {
+        component mytail
+        constructor {args} {
+            install mytail using tail %AUTO% -partof $self
+            $self configurelist $args
+        }
+        method wag {} {
+            $mytail wag
+        }
+    }
+
+

For snit::types, the two methods are equivalent; for +snit::widgets and snit::widgetadaptors, the install +command properly initializes the widget's options by querying +The Tk Option Database.

+

In the above examples, the dog object's wag method +simply calls the tail component's wag method. In OO +jargon, this is called delegation. Snit provides an easier way to do +this:

+
    snit::type dog {
+        delegate method wag to mytail
+        constructor {args} {
+            install mytail using tail %AUTO% -partof $self
+            $self configurelist $args
+        }
+    }
+
+

The delegate statement in the type definition implicitly defines +the instance variable mytail to hold the component's name +(though it's good form to use component to declare it explicitly); it +also defines the dog object's wag method, delegating it +to the mytail component.

+

If desired, all otherwise unknown methods can be delegated to a +specific component:

+
+    snit::type dog {
+	delegate method * to mytail
+	constructor {args} {
+	    set mytail [tail %AUTO% -partof $self]
+	    $self configurelist $args
+	}
+	method bark { return "Bark, bark, bark!" }
+    }
+
+

In this case, a dog object will handle its own bark +method; but wag will be passed along to mytail. Any +other method, being recognized by neither dog nor tail, +will simply raise an error.

+

Option delegation is similar to method delegation, except for the +interactions with the Tk option database; this is described in +The Tk Option Database.

+
+

Type Components and Delegation

+

The relationship between type components and instance components is +identical to that between type variables and instance variables, and +that between type methods and instance methods. Just as an instance +component is an instance variable that holds the name of a command, so +a type component is a type variable that holds the name of a command. +In essence, a type component is a component that's shared by every +instance of the type.

+

Just as delegate method can be used to delegate methods to +instance components, as described in +Components and Delegation, so delegate typemethod +can be used to delegate type methods to type components.

+

Note also that as of Snit 0.95 delegate method can delegate +methods to both instance components and type components.

+
+

The Tk Option Database

+

This section describes how Snit interacts with the Tk option database, +and assumes the reader has a working knowledge of the option database +and its uses. The book Practical Programming in Tcl and Tk +by Welch et al has a good introduction to the option database, as does +Effective Tcl/Tk Programming.

+

Snit is implemented so that most of the time it will simply do the +right thing with respect to the option database, provided that the +widget developer does the right thing by Snit. The body of this +section goes into great deal about what Snit requires. The following +is a brief statement of the requirements, for reference.

+
    +

  • If the snit::widget's default widget class is not what is desired, set it +explicitly using widgetclass in the widget definition.

    • +

  • When defining or delegating options, specify the resource and class +names explicitly when if the defaults aren't what you want.

    • +

  • Use installhull using to install the hull for +snit::widgetadaptors.

    • +

  • Use install to install all other components.

    • +
+

The interaction of Tk widgets with the option database is a complex +thing; the interaction of Snit with the option database is even more +so, and repays attention to detail.

+

Setting the widget class: Every Tk widget has a widget class. +For Tk widgets, the widget class name is the just the widget type name +with an initial capital letter, e.g., the widget class for +button widgets is "Button".

+

Similarly, the widget class of a snit::widget defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of

+
    snit::widget ::mylibrary::scrolledText { ... }
+

is "ScrolledText". The widget class can also be set explicitly using +the widgetclass statement within the snit::widget +definition.

+

Any widget can be used as the hulltype provided that it supports +the -class option for changing its widget class name. See +the discussion of the hulltype command, above. The user may pass +-class to the widget at instantion.

+

The widget class of a snit::widgetadaptor is just the widget +class of its hull widget; this cannot be changed unless the hull +widget supports -class, in which case it will +usually make more sense to use snit::widget rather than +snit::widgetadaptor.

+

Setting option resource names and classes: In Tk, every +option has three names: the option name, the resource name, and the +class name. The option name begins with a hyphen and is all lowercase; +it's used when creating widgets, and with the configure and +cget commands.

+

The resource and class names are used to initialize option default +values by querying the Tk option database. The resource name is +usually just the option name minus the hyphen, but may contain +uppercase letters at word boundaries; the class name is usually just +the resource name with an initial capital, but not always. For +example, here are the option, resource, and class names for several +text widget options:

+
    -background         background         Background
+    -borderwidth        borderWidth        BorderWidth
+    -insertborderwidth  insertBorderWidth  BorderWidth
+    -padx               padX               Pad
+
+

As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always.

+

Snit options also have a resource name and a class name. By default, +these names follow the rule given above: the resource name is the +option name without the hyphen, and the class name is the resource +name with an initial capital. This is true for both locally-defined +options and explicitly delegated options:

+
    snit::widget mywidget {
+        option -background
+        delegate option -borderwidth to hull
+        delegate option * to text
+	# ...
+    }
+
+

In this case, the widget class name is "Mywidget". The widget has the +following options: -background, which is locally defined, and +-borderwidth, which is explicitly delegated; all other widgets are +delegated to a component called "text", which is probably a Tk +text widget. If so, mywidget has all the same options as +a text widget. The option, resource, and class names are as +follows:

+
    -background  background  Background
+    -borderwidth borderwidth Borderwidth
+    -padx        padX        Pad
+
+

Note that the locally defined option, -background, happens to have +the same three names as the standard Tk -background option; and +-pad, which is delegated implicitly to the text +component, has the +same three names for mywidget as it does for the text +widget. -borderwidth, on the other hand, has different resource and +class names than usual, because the internal word "width" isn't +capitalized. For consistency, it should be; this is done as follows:

+
    snit::widget mywidget {
+	option -background
+	delegate option {-borderwidth borderWidth} to hull
+	delegate option * to text
+	# ...
+    }
+
+

The class name will default to "BorderWidth", as expected.

+

Suppose, however, that mywidget also delegated +-padx and +-pady to the hull. In this case, both the resource name and the +class name must be specified explicitly:

+
    snit::widget mywidget {
+	option -background
+	delegate option {-borderwidth borderWidth} to hull
+	delegate option {-padx padX Pad} to hull
+	delegate option {-pady padY Pad} to hull
+	delegate option * to text
+	# ...
+    }
+
+

Querying the option database: If you set your widgetclass and +option names as described above, Snit will query the option database +when each instance is created, and will generally do the right thing +when it comes to querying the option database. The remainder of this +section goes into the gory details.

+

Initializing locally defined options: +When an instance of a snit::widget is created, its locally defined +options are initialized as follows: each option's resource and class +names are used to query the Tk option database. If the result is +non-empty, it is used as the option's default; otherwise, the default +hardcoded in the type definition is used. In either case, the default +can be overridden by the caller. For example,

+
    option add *Mywidget.texture pebbled
+    snit::widget mywidget {
+	option -texture smooth
+	# ...
+    }
+    mywidget .mywidget -texture greasy
+
+

Here, -texture would normally default to "smooth", but because of +the entry added to the option database it defaults to "pebbled". +However, the caller has explicitly overridden the default, and so the +new widget will be "greasy".

+

Initializing options delegated to the hull: +A snit::widget's hull is a widget, and given that its class has +been set it is expected to query the option database for itself. The +only exception concerns options that are delegated to it with a +different name. Consider the following code:

+
    option add *Mywidget.borderWidth 5
+    option add *Mywidget.relief sunken
+    option add *Mywidget.hullbackground red
+    option add *Mywidget.background green
+    snit::widget mywidget {
+	delegate option -borderwidth to hull
+	delegate option -hullbackground to hull as -background
+	delegate option * to hull
+	# ...
+    }
+    mywidget .mywidget
+    set A [.mywidget cget -relief]
+    set B [.mywidget cget -hullbackground]
+    set C [.mywidget cget -background]
+    set D [.mywidget cget -borderwidth]
+
+

The question is, what are the values of variables A, B, C and D?

+

The value of A is "sunken". The hull is a Tk frame that has been +given the widget class "Mywidget"; it will automatically query the +option database and pick up this value. Since the -relief +option is implicitly delegated to the hull, Snit takes no action.

+

The value of B is "red". The hull will automatically pick up the +value "green" for its -background option, just as it picked up the +-relief value. However, Snit knows that +-hullbackground is mapped to +the hull's -background option; hence, it queries the option database +for -hullbackground and gets "red" and updates the hull +accordingly.

+

The value of C is also "red", because -background is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +-hullbackground. Note that this case is unusual; in practice, +-background would probably be explicitly delegated to some other +component.

+

The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for -borderwidth +defaults to "borderwidth", whereas the option database entry is +"borderWidth". As with -relief, the hull picks up its +own -borderwidth option before Snit does anything. Because the +option is delegated under its own name, Snit assumes that the correct +thing has happened, and doesn't worry about it any further.

+

For snit::widgetadaptors, the case is somewhat altered. Widget +adaptors retain the widget class of their hull, and the hull is not +created automatically by Snit. Instead, the snit::widgetadaptor +must call installhull in its constructor. The normal way to do +this is as follows:

+
    snit::widgetadaptor mywidget {
+	# ...
+	constructor {args} {
+	    # ...
+	    installhull using text -foreground white
+	    #
+	}
+	#...
+    }
+
+

In this case, the installhull command will create the hull using +a command like this:

+
    set hull [text $win -foreground white]
+
+

The hull is a text widget, so its widget class is "Text". Just +as with snit::widget hulls, Snit assumes that it will pick up +all of its normal option values automatically; options delegated from +a different name are initialized from the option database in the same +way.

+

Initializing options delegated to other components: +Non-hull components are matched against the option database in two +ways. First, a component widget remains a widget still, and therefore +is initialized from the option database in the usual way. +Second, the option database is queried for all options delegated to +the component, and the component is initialized accordingly--provided +that the install command is used to create it.

+

Before option database support was added to Snit, the usual way to +create a component was to simply create it in the constructor and +assign its command name to the component variable:

+
    snit::widget mywidget {
+	delegate option -background to myComp
+	constructor {args} {
+	    set myComp [text $win.text -foreground black]
+	}
+    }
+
+

The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used:

+
    snit::widget mywidget {
+	delegate option -background to myComp
+	constructor {args} {
+	    install myComp using text $win.text -foreground black
+	}
+    }
+
+

The install command does the following:

+
    +

  • Builds a list of the options explicitly included in the install +command -- in this case, -foreground.

    • +

  • Queries the option database for all options delegated explicitly to +the named component.

    • +

  • Creates the component using the specified command, after inserting +into it a list of options and values read from the option database. +Thus, the explicitly included options (-foreground) will override +anything read from the option database.

    • +

  • If the widget definition implicitly delegated options to the component +using delegate option *, then Snit calls the newly created +component's configure method to receive a list of all of the +component's options. From this Snit builds a list of options +implicitly delegated to the component that were not explicitly +included in the install command. For all such options, Snit +queries the option database and configures the component accordingly.

    • +
+

Non-widget components: The option database is never queried +for snit::types, since it can only be queried given a Tk widget +name. +However, snit::widgets can have non-widget components. And if +options are delegated to those components, and if the install +command is used to install those components, then they will be +initialized from the option database just as widget components are.

+
+

Macros and Meta-programming

+

The snit::macro command enables a certain amount of +meta-programming with Snit classes. For example, suppose you like to +define properties: instance variables that have set/get methods. Your +code might look like this:

+
    snit::type dog {
+        variable mood happy
+        method getmood {} {
+            return $mood
+        }
+        method setmood {newmood} {
+            set mood $newmood
+        }
+    }
+
+

That's nine lines of text per property. Or, you could define the +following snit::macro:

+
    snit::macro property {name initValue} {
+        variable $name $initValue
+        method get$name {} "return $name"
+        method set$name {value} "set $name \$value"
+    }
+
+

Note that a snit::macro is just a normal Tcl proc defined in +the slave interpreter used to compile type and widget definitions; as +a result, it has access to all the commands used to define types and +widgets.

+

Given this new macro, you can define a property in one line of code:

+
    snit::type dog {
+        property mood happy
+    }
+
+

Within a macro, the commands variable and proc refer to +the Snit type-definition commands, not the standard Tcl commands. To +get the standard Tcl commands, use _variable and _proc.

+

Because a single slave interpreter is used for compiling all Snit +types and widgets in the application, there's the possibility of macro +name collisions. If you're writing a reuseable package using Snit, +and you use some snit::macros, define them in your package +namespace:

+
    snit::macro mypkg::property {name initValue} { ... }
+    snit::type dog {
+        mypkg::property mood happy
+    }
+
+

This leaves the global namespace open for application authors.

+
+

Validation Types

+

A validation type is an object that can be used to validate +Tcl values of a particular kind. For example, +snit::integer is used to validate that a Tcl value is +an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
    snit::integer validate 5     ;# Does nothing
+    snit::integer validate 5.0   ;# Throws an error (not an integer!)
+
+

The validate method will always return the validated value on success, +and throw the -errorcode INVALID on error.

+

Snit defines a family of validation types, all of which are +implemented as snit::type's. They can be used as is; +in addition, their instances serve as parameterized +subtypes. For example, a probability is a number between 0.0 and 1.0 +inclusive:

+
    snit::double probability -min 0.0 -max 1.0
+
+

The example above creates an instance of snit::double--a +validation subtype--called +probability, which can be used to validate probability values:

+
    probability validate 0.5   ;# Does nothing
+    probability validate 7.9   ;# Throws an error
+
+

Validation subtypes can be defined explicitly, as in the above +example; when a locally-defined option's -type is specified, +they may also be created on the fly:

+
    snit::enum ::dog::breed -values {mutt retriever sheepdog}
+    snit::type dog {
+        # Define subtypes on the fly...
+        option -breed -type {
+            snit::enum -values {mutt retriever sheepdog}
+        }
+        # Or use predefined subtypes...
+        option -breed -type ::dog::breed
+    }
+
+

Any object that has a validate method with the semantics +described above can be used as a validation type; see +Defining Validation Types for information on how to define +new ones.

+

Snit defines the following validation types:

+
+
snit::boolean validate ?value?
+
+
snit::boolean name
+

Validates Tcl boolean values: 1, 0, on, off, +yes, no, true, false. +It's possible to define subtypes--that is, instances--of +snit::boolean, but as it has no options there's no reason to do +so.

+
snit::double validate ?value?
+
+
snit::double name ?option value...?
+

Validates floating-point values. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a floating-point minimum bound; a value is invalid if it is strictly +less than min.

+
-max max
+

Specifies a floating-point maximum bound; a value is invalid if it is strictly +greater than max.

+
+
snit::enum validate ?value?
+
+
snit::enum name ?option value...?
+

Validates that a value comes from an enumerated list. The base +type is of little use by itself, as only subtypes actually have +an enumerated list to validate against. Subtypes may be created +with the following options:

+
+
-values list
+

Specifies a list of valid values. A value is valid if and only if +it's included in the list.

+
+
snit::fpixels validate ?value?
+
+
snit::fpixels name ?option value...?
+

Tk programs only. Validates screen distances, in any of the +forms accepted by winfo fpixels. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a minimum bound; a value is invalid if it is strictly +less than min. The bound may be expressed in any of the +forms accepted by winfo fpixels.

+
-max max
+

Specifies a maximum bound; a value is invalid if it is strictly +greater than max. The bound may be expressed in any of the +forms accepted by winfo fpixels.

+
+
snit::integer validate ?value?
+
+
snit::integer name ?option value...?
+

Validates integer values. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies an integer minimum bound; a value is invalid if it is strictly +less than min.

+
-max max
+

Specifies an integer maximum bound; a value is invalid if it is strictly +greater than max.

+
+
snit::listtype validate ?value?
+
+
snit::listtype name ?option value...?
+

Validates Tcl lists. Subtypes may be created with the +following options:

+
+
-minlen min
+

Specifies a minimum list length; the value is invalid if it has +fewer than min elements. Defaults to 0.

+
-maxlen max
+

Specifies a maximum list length; the value is invalid if it +more than max elements.

+
-type type
+

Specifies the type of the list elements; type must be +the name of a validation type or subtype. In the +following example, the value of -numbers must be a list +of integers.

+
    option -numbers -type {snit::listtype -type snit::integer}
+
+

Note that this option doesn't support defining new validation subtypes +on the fly; that is, the following code will not work (yet, anyway):

+
    option -numbers -type {
+        snit::listtype -type {snit::integer -min 5}
+    }
+
+

Instead, define the subtype explicitly:

+
    snit::integer gt4 -min 5
+    snit::type mytype {
+        option -numbers -type {snit::listtype -type gt4}
+    }
+
+
+
+
snit::pixels validate ?value?
+
+
snit::pixels name ?option value...?
+

Tk programs only. Validates screen distances, in any of the +forms accepted by winfo pixels. Subtypes may be created with the +following options:

+
+
-min min
+

Specifies a minimum bound; a value is invalid if it is strictly +less than min. The bound may be expressed in any of the +forms accepted by winfo pixels.

+
-max max
+

Specifies a maximum bound; a value is invalid if it is strictly +greater than max. The bound may be expressed in any of the +forms accepted by winfo pixels.

+
+
snit::stringtype validate ?value?
+
+
snit::stringtype name ?option value...?
+

Validates Tcl strings. The base type is of little use by itself, +since very Tcl value is also a valid string. Subtypes may be created with the +following options:

+
+
-minlen min
+

Specifies a minimum string length; the value is invalid if it has +fewer than min characters. Defaults to 0.

+
-maxlen max
+

Specifies a maximum string length; the value is invalid if it has +more than max characters.

+
-glob pattern
+

Specifies a string match pattern; the value is invalid +if it doesn't match the pattern.

+
-regexp regexp
+

Specifies a regular expression; the value is invalid if it doesn't +match the regular expression.

+
-nocase flag
+

By default, both -glob and -regexp matches are +case-sensitive. If -nocase is set to true, then both +-glob and -regexp matches are case-insensitive.

+
+
snit::window validate ?value?
+
+
snit::window name
+

Tk programs only. Validates Tk window names. The value must +cause winfo exists to return true; otherwise, the value is +invalid. It's possible to define subtypes--that is, instances--of +snit::window, but as it has no options at present there's no +reason to do so.

+
+
+

Defining Validation Types

+

There are three ways to define a new validation type: as a subtype of +one of Snit's validation types, as a validation type command, and as +a full-fledged validation type similar to those provided by Snit. +Defining subtypes of Snit's validation types is described above, +under Validation Types.

+

The next simplest way to create a new validation type is as a +validation type command. A validation type is simply an +object that has a validate method; the validate +method must take one argument, a value, return the value if it is +valid, and throw an error with -errorcode INVALID if the +value is invalid. This can be done with a simple proc. For +example, the snit::boolean validate type could have been +implemented like this:

+
    proc ::snit::boolean {"validate" value} {
+        if {![string is boolean -strict $value]} {
+            return -code error -errorcode INVALID  "invalid boolean \"$value\", should be one of: 1, 0, ..."
+        }
+        return $value
+    }
+
+

A validation type defined in this way cannot be subtyped, of course; +but for many applications this will be sufficient.

+

Finally, one can define a full-fledged, subtype-able validation type +as a snit::type. Here's a skeleton to get you started:

+
    snit::type myinteger {
+        # First, define any options you'd like to use to define
+        # subtypes.  Give them defaults such that they won't take
+        # effect if they aren't used, and marked them "read-only".
+        # After all, you shouldn't be changing their values after
+        # a subtype is defined.
+        #
+        # For example:
+        option -min -default "" -readonly 1
+        option -max -default "" -readonly 1
+        # Next, define a "validate" type method which should do the
+        # validation in the basic case.  This will allow the
+        # type command to be used as a validation type.
+        typemethod validate {value} {
+            if {![string is integer -strict $value]} {
+                return -code error -errorcode INVALID  "invalid value \"$value\", expected integer"
+            }
+            return $value
+        }
+        # Next, the constructor should validate the subtype options,
+        # if any.  Since they are all readonly, we don't need to worry
+        # about validating the options on change.
+        constructor {args} {
+            # FIRST, get the options
+            $self configurelist $args
+            # NEXT, validate them.
+            # I'll leave this to your imagination.
+        }
+        # Next, define a "validate" instance method; its job is to
+        # validate values for subtypes.
+        method validate {value} {
+            # First, call the type method to do the basic validation.
+            $type validate $value
+            # Now we know it's a valid integer.
+            if {("" != $options(-min) && $value < $options(-min))  ||
+                ("" != $options(-max) && $value > $options(-max))} {
+                # It's out of range; format a detailed message about
+                # the error, and throw it.
+                set msg "...."
+                return -code error -errorcode INVALID $msg
+            }
+            # Otherwise, if it's valid just return it.
+            return $valid
+        }
+    }
+
+

And now you have a type that can be subtyped.

+

The file "validate.tcl" in the Snit distribution defines all of Snit's +validation types; you can find the complete implementation for +snit::integer and the other types there, to use as examples for +your own types.

+
+
+

CAVEATS

+

If you have problems, find bugs, or new ideas you are hereby cordially +invited to submit a report of your problem, bug, or idea as explained +in the section Bugs, Ideas, Feedback below.

+

Additionally, you might wish to join the Snit mailing list; +see http://www.wjduquette.com/snit for details.

+

One particular area to watch is using snit::widgetadaptor to +adapt megawidgets created by other megawidget packages; correct +widget destruction depends on the order of the <Destroy> bindings. +The wisest course is simply not to do this.

+
+

KNOWN BUGS

+
    +

  • Error stack traces returned by Snit 1.x are extremely ugly and typically +contain far too much information about Snit internals. The error +messages are much improved in Snit 2.2.

    • +

  • Also see the Project Trackers as explained in the section +Bugs, Ideas, Feedback below.

    • +
+
+

HISTORY

+

During the course of developing Notebook +(See http://www.wjduquette.com/notebook), my Tcl-based personal +notebook application, I found I was writing it as a collection of +objects. I wasn't using any particular object-oriented framework; I +was just writing objects in pure Tcl following the guidelines in my +Guide to Object Commands +(see http://www.wjduquette.com/tcl/objects.html), along with a +few other tricks I'd picked up since. And though it was working well, +it quickly became tiresome because of the amount of boilerplate +code associated with each new object type.

+

So that was one thing--tedium is a powerful motivator. But the other +thing I noticed is that I wasn't using inheritance at all, and I +wasn't missing it. Instead, I was using delegation: objects that +created other objects and delegated methods to them.

+

And I said to myself, "This is getting tedious...there has got to be a +better way." And one afternoon, on a whim, I started working on Snit, +an object system that works the way Tcl works. Snit doesn't support +inheritance, but it's great at delegation, and it makes creating +megawidgets easy.

+

If you have any comments or suggestions (or bug reports!) don't +hesitate to send me e-mail at will@wjduquette.com. In addition, +there's a Snit mailing list; you can find out more about it at the +Snit home page (see http://www.wjduquette.com/snit).

+
+

CREDITS

+

Snit has been designed and implemented from the very beginning by +William H. Duquette. However, much credit belongs to the following +people for using Snit and providing me with valuable feedback: Rolf +Ade, Colin McCormack, Jose Nazario, Jeff Godfrey, Maurice Diamanti, +Egon Pasztor, David S. Cargo, Tom Krehbiel, Michael Cleverly, +Andreas Kupries, Marty Backe, Andy Goth, Jeff Hobbs, Brian +Griffin, Donal Fellows, Miguel Sofer, Kenneth Green, +and Anton Kovalenko. +If I've forgotten anyone, my apologies; let me know and I'll add +your name to the list.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category snit of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/snit/snitfaq.html Index: embedded/www/tcllib/files/modules/snit/snitfaq.html ================================================================== --- embedded/www/tcllib/files/modules/snit/snitfaq.html +++ embedded/www/tcllib/files/modules/snit/snitfaq.html @@ -0,0 +1,3246 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

snitfaq(n) 2.2 tcllib "Snit's Not Incr Tcl, OO system"

+

Name

+

snitfaq - Snit Frequently Asked Questions

+
+

Table Of Contents

+ +
+ +

OVERVIEW

+

What is this document?

+

This is an atypical FAQ list, in that few of the questions are +frequently asked. Rather, these are the questions I think a newcomer +to Snit should be asking. This file is not a complete reference to +Snit, however; that information is in the snit man page.

+
+

What is Snit?

+

Snit is a framework for defining abstract data types and megawidgets +in pure Tcl. The name "Snit" stands for "Snit's Not Incr Tcl", +signifying that Snit takes a different approach to defining objects +than does Incr Tcl, the best known object framework for Tcl. Had +I realized that Snit would become at all popular, I'd probably have +chosen something else.

+

The primary purpose of Snit is to be object glue--to help you +compose diverse objects from diverse sources into types and +megawidgets with clean, convenient interfaces so that you can more +easily build your application.

+

Snit isn't about theoretical purity or minimalist design; it's about +being able to do powerful things easily and consistently without +having to think about them--so that you can concentrate on building +your application.

+

Snit isn't about implementing thousands of nearly identical +carefully-specified lightweight thingamajigs--not as individual Snit +objects. Traditional Tcl methods will be much faster, and not much +more complicated. But Snit is about implementing a clean interface +to manage a collection of thousands of nearly identical +carefully-specified lightweight thingamajigs (e.g., think of the text +widget and text tags, or the canvas widget and canvas objects). Snit +lets you hide the details of just how those thingamajigs are +stored--so that you can ignore it, and concentrate on building your +application.

+

Snit isn't a way of life, a silver bullet, or the Fountain of +Youth. It's just a way of managing complexity--and of managing some of +the complexity of managing complexity--so that you can concentrate on +building your application.

+
+

What version of Tcl does Snit require?

+

Snit 1.3 requires Tcl 8.3 or later; Snit 2.2 requires Tcl 8.5 or +later. See SNIT VERSIONS for the differences between Snit +1.3 and Snit 2.2.

+
+

Where can I download Snit?

+

Snit is part of Tcllib, the standard Tcl library, so you might already +have it. It's also available at the Snit Home Page, +http://www.wjduquette.com/snit.

+
+

What are Snit's goals?

+
    +

  • A Snit object should be at least as efficient as a hand-coded Tcl +object (see http://www.wjduquette.com/tcl/objects.html).

    • +

  • The fact that Snit was used in an object's implementation should be +transparent (and irrelevant) to clients of that object.

    • +

  • Snit should be able to encapsulate objects from other sources, +particularly Tk widgets.

    • +

  • Snit megawidgets should be (to the extent possible) indistinguishable +in interface from Tk widgets.

    • +

  • Snit should be Tclish--that is, rather than trying to emulate C++, +Smalltalk, or anything else, it should try to emulate Tcl itself.

    • +

  • It should have a simple, easy-to-use, easy-to-remember syntax.

    • +
+
+

How is Snit different from other OO frameworks?

+

Snit is unique among Tcl object systems in that +it is based not on inheritance but on delegation. Object +systems based on inheritance only allow you to inherit from classes +defined using the same system, and that's a shame. In Tcl, an object +is anything that acts like an object; it shouldn't matter how the +object was implemented. I designed Snit to help me build applications +out of the materials at hand; thus, Snit is designed to be able to +incorporate and build on any object, whether it's a hand-coded object, +a Tk widget, an Incr Tcl object, a BWidget or almost anything else.

+

Note that you can achieve the effect of inheritance using +COMPONENTS and DELEGATION--and you can inherit +from anything that looks like a Tcl object.

+
+

What can I do with Snit?

+

Using Snit, a programmer can:

+
    +

  • Create abstract data types and Tk megawidgets.

    • +

  • Define instance variables, type variables, and Tk-style options.

    • +

  • Define constructors, destructors, instance methods, type methods, procs.

    • +

  • Assemble a type out of component types. Instance methods and options +can be delegated to the component types automatically.

    • +
+
+
+

SNIT VERSIONS

+

Which version of Snit should I use?

+

The current Snit distribution includes two versions, Snit 1.3 and Snit +2.2. The reason that both are included is that Snit 2.2 takes +advantage of a number of new features of Tcl 8.5 to improve run-time +efficiency; as a side-effect, the ugliness of Snit's error messages +and stack traces has been reduced considerably. The cost of using +Snit 2.2, of course, is that you must target Tcl 8.5.

+

Snit 1.3, on the other hand, lacks Snit 2.2's optimizations, but +requires only Tcl 8.3 and later.

+

In short, if you're targetting Tcl 8.3 or 8.4 you should use Snit 1.3. If +you can afford to target Tcl 8.5, you should definitely use Snit 2.2. +If you will be targetting both, you can use Snit 1.3 exclusively, or +(if your code is unaffected by the minor incompatibilities between the +two versions) you can use Snit 1.3 for Tcl 8.4 and Snit 2.2 for Tcl +8.5.

+
+

How do I select the version of Snit I want to use?

+

To always use Snit 1.3 (or a later version of Snit 1.x), invoke Snit +as follows:

+
package require snit 1.3
+
+

To always use Snit 2.2 (or a later version of Snit 2.x), say this +instead:

+
package require snit 2.2
+
+

Note that if you request Snit 2.2 explicitly, your application will +halt with Tcl 8.4, since Snit 2.2 is unavailable for Tcl 8.4.

+

If you wish your application to always use the latest available +version of Snit, don't specify a version number:

+
package require snit
+
+

Tcl will find and load the latest version that's available relative to +the version of Tcl being used. In this case, be careful to avoid +using any incompatible features.

+
+

How are Snit 1.3 and Snit 2.2 incompatible?

+

To the extent possible, Snit 2.2 is intended to be a drop-in +replacement for Snit 1.3. Unfortunately, some incompatibilities were +inevitable because Snit 2.2 uses Tcl 8.5's new +namespace ensemble mechanism to implement subcommand dispatch. +This approach is much faster than the mechanism used in Snit 1.3, and +also results in much better error messages; however, it also places +new constraints on the implementation.

+

There are four specific incompatibilities between Snit 1.3 and Snit 2.2.

+
    +

  • Snit 1.3 supports implicit naming of objects. Suppose you define a +new snit::type called dog. You can create instances of +dog in three ways:

    +
    dog spot               ;# Explicit naming
+set obj1 [dog %AUTO%]  ;# Automatic naming
+set obj2 [dog]         ;# Implicit naming
+
    +

    In Snit 2.2, type commands are defined using the namespace ensemble +mechanism; and namespace ensemble doesn't allow an ensemble command +to be called without a subcommand. In short, using +namespace ensemble there's no way to support implicit naming.

    +

    All is not lost, however. If the type has no type methods, then the +type command is a simple command rather than an ensemble, and +namespace ensemble is not used. In this case, implicit naming +is still possible.

    +

    In short, you can have implicit naming if you're willing to do without +type methods (including the standard type methods, like +$type info). To do so, use the -hastypemethods pragma:

    +
    pragma -hastypemethods 0
    +
    • +

  • Hierarchical methods and type methods are implemented differently in +Snit 2.2.

    +

    A hierarchical method is an instance method which has +subcommands; these subcommands are themselves methods. The Tk text +widget's tag command and its subcommands are examples of +hierarchical methods. You can implement such subcommands in Snit +simply by including multiple words in the method names:

    +
    method {tag configure} {tag args} { ... }
+method {tag cget} {tag option} {...}
+
    +

    Here we've implicitly defined a tag method which has two +subcommands, configure and cget.

    +

    In Snit 1.3, hierarchical methods could be called in two ways:

    +
    $obj tag cget -myoption      ;# The good way
+$obj {tag cget} -myoption    ;# The weird way
+
    +

    In the second call, we see that a hierarchical method or type method +is simply one whose name contains multiple words.

    +

    In Snit 2.2 this is no longer the case, and the "weird" way of calling +hierarchical methods and type methods no longer works.

    • +

  • The third incompatibility derives from the second. In Snit 1.3, +hierarchical methods were also simply methods whose name contains +multiple words. As a result, $obj info methods returned the +full names of all hierarchical methods. In the example above, +the list returned by $obj info methods would include +tag configure and tag cget but not tag, since +tag is defined only implicitly.

    +

    In Snit 2.2, hierarchical methods and type methods are no longer +simply ones whose +name contains multiple words; in the above example, the list returned +by $obj info methods would include tag but not +tag configure or tag cget.

    • +

  • The fourth incompatibility is due to a new feature. Snit 2.2 uses +the new namespace path command so that a type's code can +call any command defined in the type's parent namespace without +qualification or importation. For example, suppose you have a +package called mypackage which defines a number of commands +including a type, ::mypackage::mytype. Thanks to +namespace path, the type's code can call any of the other +commands defined in ::mypackage::.

    +

    This is extremely convenient. However, it also means that commands +defined in the parent namespace, ::mypackage:: can block the +type's access to identically named commands in the global namespace. +This can lead to bugs. For example, Tcllib includes a type called +::tie::std::file. This type's code calls the standard +file command. When run with Snit 2.2, the code broke-- +the type's command, ::tie::std::file, is itself a command +in the type's parent namespace, and so instead of calling +the standard file command, the type found itself calling +itself.

    • +
+
+

Are there other differences between Snit 1.x and Snit 2.2?

+

Yes.

+
    +

  • Method dispatch is considerably faster.

    • +

  • Many error messages and stack traces are cleaner.

    • +

  • The -simpledispatch pragma is obsolete, and ignored if +present. In Snit 1.x, -simpledispatch substitutes a faster +mechanism for method dispatch, at the cost of losing certain features. +Snit 2.2 method dispatch is faster still in all cases, so +-simpledispatch is no longer needed.

    • +

  • In Snit 2.2, a type's code (methods, type methods, etc.) can call commands +from the type's parent namespace without qualifying or importing +them, i.e., type ::parentns::mytype's code can call +::parentns::someproc as just someproc.

    +

    This is extremely useful when a type is defined as part of a larger +package, and shares a parent namespace with the rest of the package; +it means that the type can call other commands defined by the +package without any extra work.

    +

    This feature depends on the new Tcl 8.5 namespace path command, +which is why it hasn't been implemented for V1.x. V1.x code can +achieve something similar by placing

    +
    namespace import [namespace parent]::*
    +

    in a type constructor. This is less useful, however, as it picks up +only those commands which have already been exported by the parent +namespace at the time the type is defined.

    • +
+
+
+

OBJECTS

+

What is an object?

+

A full description of object-oriented programming is beyond +the scope of this FAQ, obviously. In simple terms, an object is an instance of +an abstract data type--a coherent bundle of code and data. +There are many ways to represent objects in Tcl/Tk; the best known +examples are the Tk widgets.

+

A Tk widget is an object; it is represented by a Tcl command. +The object's methods are subcommands of the Tcl command. The object's +properties are options accessed using the configure and +cget methods. Snit uses the same conventions as Tk widgets do.

+
+

What is an abstract data type?

+

In computer science terms, an abstract data type is a complex data +structure along with a set of operations--a stack, a queue, a +binary tree, etc--that is to say, in modern terms, an object. In systems +that include some form of inheritance the word class is +usually used instead of abstract data type, but as Snit +doesn't implement inheritance as it's ordinarily understood +the older term seems more appropriate. Sometimes this is called +object-based programming as opposed to object-oriented +programming. Note that you can easily create the effect of +inheritance using COMPONENTS and DELEGATION.

+

In Snit, as in Tk, a type is a command that creates instances +-- objects -- which belong to the type. Most types define some number +of options which can be set at creation time, and usually can be +changed later.

+

Further, an instance is also a Tcl command--a command that +gives access to the operations which are defined for that abstract +data type. Conventionally, the operations are defined as subcommands +of the instance command. For example, to insert +text into a Tk text widget, you use the text widget's insert +subcommand:

+
    # Create a text widget and insert some text in it.
+    text .mytext -width 80 -height 24
+    .mytext insert end "Howdy!"
+
+

In this example, text is the type command and +.mytext is the instance command.

+

In Snit, object subcommands are generally called +INSTANCE METHODS.

+
+

What kinds of abstract data types does Snit provide?

+

Snit allows you to define three kinds of abstract data type:

+
    +

  • snit::type

    • +

  • snit::widget

    • +

  • snit::widgetadaptor

    • +
+
+

What is a snit::type?

+

A snit::type is a non-GUI abstract data type, e.g., a stack or a +queue. snit::types are defined using the snit::type +command. For example, if you were designing a kennel management +system for a dog breeder, you'd need a dog type.

+
% snit::type dog {
+    # ...
+}
+::dog
+%
+
+

This definition defines a new command (::dog, in this case) +that can be used to define dog objects.

+

An instance of a snit::type can have INSTANCE METHODS, +INSTANCE VARIABLES, OPTIONS, and COMPONENTS. +The type itself can have TYPE METHODS, +TYPE VARIABLES, TYPE COMPONENTS, and +PROCS.

+
+

What is a snit::widget?, the short story

+

A snit::widget is a Tk megawidget built using Snit; it is very +similar to a snit::type. See WIDGETS.

+
+

What is a snit::widgetadaptor?, the short story

+

A snit::widgetadaptor uses Snit to wrap an existing widget type +(e.g., a Tk label), modifying its interface to a lesser or greater +extent. It is very similar to a snit::widget. +See WIDGET ADAPTORS.

+
+

How do I create an instance of a snit::type?

+

You create an instance of a snit::type by passing the new +instance's name to the type's create method. In the following +example, we create a dog object called spot.

+
% snit::type dog {
+    # ....
+}
+::dog
+% dog create spot
+::spot
+%
+
+

In general, the create method name can be omitted so long as +the instance name doesn't conflict with any defined +TYPE METHODS. (See TYPE COMPONENTS for the +special case in which this doesn't work.) +So the following example is identical to the +previous example:

+
% snit::type dog {
+    # ....
+}
+::dog
+% dog spot
+::spot
+%
+
+

This document generally uses the shorter form.

+

If the dog type defines OPTIONS, these can usually be +given defaults at creation time:

+
% snit::type dog {
+    option -breed mongrel
+    option -color brown
+    method bark {} { return "$self barks." }
+}
+::dog
+% dog create spot -breed dalmation -color spotted
+::spot
+% spot cget -breed
+dalmation
+% spot cget -color
+spotted
+%
+
+

Once created, the instance name now names a new Tcl command that is used +to manipulate the object. For example, the following code makes the +dog bark:

+
% spot bark
+::spot barks.
+%
+
+
+

How do I refer to an object indirectly?

+

Some programmers prefer to save the object name in a variable, and +reference it that way. For example,

+
% snit::type dog { ... }
+::dog
+% set d [dog spot -breed dalmation -color spotted]
+::spot
+% $d cget -breed
+dalmation
+% $d bark
+::spot barks.
+%
+
+

If you prefer this style, you might prefer to have Snit +generate the instance's name automatically.

+
+

How can I generate the object name automatically?

+

If you'd like Snit to generate an object name for you, +use the %AUTO% keyword as the requested name:

+
% snit::type dog { ... }
+::dog
+% set d [dog %AUTO%]
+::dog2
+% $d bark
+::dog2 barks.
+%
+
+

The %AUTO% keyword can be embedded in a longer string:

+
% set d [dog obj_%AUTO%]
+::obj_dog4
+% $d bark
+::obj_dog4 barks.
+%
+
+
+

Can types be renamed?

+

Tcl's rename command renames other commands. It's a common +technique in Tcl to modify an existing command by renaming it and +defining a new command with the original name; the new command usually +calls the renamed command.

+

snit::type commands, however, should never be renamed; to do so breaks +the connection between the type and its objects.

+
+

Can objects be renamed?

+

Tcl's rename command renames other commands. It's a common +technique in Tcl to modify an existing command by renaming it and +defining a new command with the original name; the new command usually +calls the renamed command.

+

All Snit objects (including widgets and widgetadaptors) +can be renamed, though this flexibility has some consequences:

+
    +

  • In an instance method, the implicit argument self will always +contain the object's current name, so instance methods can always call +other instance methods using $self.

    • +

  • If the object is renamed, however, then $self's value will change. +Therefore, don't use $self for anything that will break if +$self changes. For example, don't pass a callback command to +another object like this:

    +
    +    .btn configure -command [list $self ButtonPress]
+
    +

    You'll get an error if .btn calls your command after your object is +renamed.

    • +

  • Instead, your object should define its callback command like this:

    +
    +    .btn configure -command [mymethod ButtonPress]
+
    +

    The mymethod command returns code that will call the desired +method safely; the caller of the callback can add additional +arguments to the end of the command as usual.

    • +

  • Every object has a private namespace; the name of this namespace is +available in method bodies, etc., as the value of the implicit +argument selfns. This value is constant for the life of the +object. Use $selfns instead of $self if you need a +unique token to identify the object.

    • +

  • When a snit::widget's instance command is renamed, its Tk window +name remains the same -- and is still extremely +important. Consequently, the Tk window name is available in +method bodies as the value of the implicit argument win. +This value is constant for the +life of the object. When creating child windows, it's best to use +$win.child rather than $self.child as the name of the +child window.

    • +
+
+

How do I destroy a Snit object?

+

Any Snit object of any type can be destroyed by renaming +it to the empty string using the Tcl rename command.

+

Snit megawidgets (i.e., instances of snit::widget and +snit::widgetadaptor) can be destroyed like any other widget: by +using the Tk destroy command on the widget or on one of its +ancestors in the window hierarchy.

+

Every instance of a snit::type has a destroy method:

+
% snit::type dog { ... }
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot destroy
+% spot barks
+invalid command name "spot"
+%
+
+

Finally, every Snit type has a type method called destroy; calling it +destroys the type and all of its instances:

+
% snit::type dog { ... }
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% dog destroy
+% spot bark
+invalid command name "spot"
+% dog fido
+invalid command name "dog"
+%
+
+
+
+

INSTANCE METHODS

+

What is an instance method?

+

An instance method is a procedure associated with a specific object +and called as a subcommand of the object's command. It is given free +access to all of the object's type variables, instance variables, and +so forth.

+
+

How do I define an instance method?

+

Instance methods are defined in the type definition using +the method statement. Consider the following code that might be +used to add dogs to a computer simulation:

+
% snit::type dog {
+    method bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing."
+    }
+}
+::dog
+%
+
+

A dog can bark, and it can chase things.

+

The method statement looks just like a normal Tcl proc, +except that it appears in a snit::type definition. Notice that +every instance method gets an implicit argument called self; +this argument contains the object's name. (There's more on +implicit method arguments below.)

+
+

How does a client call an instance method?

+

The method name becomes a subcommand of the object. For example, +let's put a simulated dog through its paces:

+
% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot chase cat
+::spot chases cat.
+%
+
+
+

How does an instance method call another instance method?

+

If method A needs to call method B on the same object, it does so just +as a client does: it calls method B as a subcommand of the object +itself, using the object name stored in the implicit argument self.

+

Suppose, for example, that our dogs never chase anything without +barking at them:

+
% snit::type dog {
+    method bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing.  [$self bark]"
+    }
+}
+::dog
+% dog spot
+::spot
+% spot bark
+::spot barks.
+% spot chase cat
+::spot chases cat.  ::spot barks.
+%
+
+
+

Are there any limitations on instance method names?

+

Not really, so long as you avoid the standard instance method names: +configure, configurelist, cget, +destroy, and info. Also, method names consisting of +multiple words define hierarchical methods.

+
+

What is a hierarchical method?

+

An object's methods are subcommands of the object's instance command. +Hierarchical methods allow an object's methods to have subcommands of +their own; and these can in turn have subcommands, and so on. This +allows the programmer to define a tree-shaped command structure, such +as is used by many of the Tk widgets--the subcommands of the +Tk text widget's tag method are hierarchical methods.

+
+

How do I define a hierarchical method?

+

Define methods whose names consist of multiple words. These words +define the hierarchy implicitly. For example, the following code +defines a tag method with subcommands cget and +configure:

+
snit::widget mytext {
+    method {tag configure} {tag args} { ... }
+    method {tag cget} {tag option} {...}
+}
+
+

Note that there is no explicit definition for the tag method; +it is implicit in the definition of tag configure and +tag cget. If you tried to define tag explicitly in this +example, you'd get an error.

+
+

How do I call hierarchical methods?

+

As subcommands of subcommands.

+
% mytext .text
+.text
+% .text tag configure redtext -foreground red -background black
+% .text tag cget redtext -foreground
+red
+%
+
+
+

How do I make an instance method private?

+

It's often useful to define private methods, that is, instance methods +intended to be called only by other methods of the same object.

+

Snit doesn't implement any access control on instance methods, so all +methods are de facto public. Conventionally, though, the +names of public methods begin with a lower-case letter, and the names +of private methods begin with an upper-case letter.

+

For example, suppose our simulated dogs only bark in response to other +stimuli; they never bark just for fun. So the bark method +becomes Bark to indicate that it is private:

+
% snit::type dog {
+    # Private by convention: begins with uppercase letter.
+    method Bark {} {
+        return "$self barks."
+    }
+    method chase {thing} {
+        return "$self chases $thing. [$self Bark]"
+    }
+}
+::dog
+% dog fido
+::fido
+% fido chase cat
+::fido chases cat. ::fido barks.
+%
+
+
+

Are there any limitations on instance method arguments?

+

Method argument lists are defined just like normal Tcl proc argument +lists; in particular, they can include arguments with default values + and the args argument.

+

However, every method also has a number of implicit arguments +provided by Snit in addition to those explicitly defined. The names +of these implicit arguments may not used to name explicit arguments.

+
+

What implicit arguments are passed to each instance method?

+

The arguments implicitly passed to every method are type, +selfns, win, and self.

+
+

What is $type?

+

The implicit argument type contains the fully qualified name of +the object's type:

+
% snit::type thing {
+    method mytype {} {
+        return $type
+    }
+}
+::thing
+% thing something
+::something
+% something mytype
+::thing
+%
+
+
+

What is $self?

+

The implicit argument self contains the object's fully +qualified name.

+

If the object's command is renamed, then $self will change to +match in subsequent calls. Thus, your code should not assume that +$self is constant unless you know for sure that the object +will never be renamed.

+
% snit::type thing {
+    method myself {} {
+        return $self
+    }
+}
+::thing
+% thing mutt
+::mutt
+% mutt myself
+::mutt
+% rename mutt jeff
+% jeff myself
+::jeff
+%
+
+
+

What is $selfns?

+

Each Snit object has a private namespace in which to store its +INSTANCE VARIABLES and OPTIONS. The implicit argument +selfns contains the name of this namespace; its value never changes, and +is constant for the life of the object, even if the object's name +changes:

+
% snit::type thing {
+    method myNameSpace {} {
+        return $selfns
+    }
+}
+::thing
+% thing jeff
+::jeff
+% jeff myNameSpace
+::thing::Snit_inst3
+% rename jeff mutt
+% mutt myNameSpace
+::thing::Snit_inst3
+%
+
+

The above example reveals how Snit names an instance's private +namespace; however, you should not write code that depends on the +specific naming convention, as it might change in future releases.

+
+

What is $win?

+

The implicit argument win is defined for all Snit methods, +though it really makes sense only for those of +WIDGETS and WIDGET ADAPTORS. $win is simply +the original name of the object, whether it's been renamed or not. +For widgets and widgetadaptors, it is also therefore the name of a Tk +window.

+

When a snit::widgetadaptor is used to modify the interface of a +widget or megawidget, it must rename the widget's original command and +replace it with its own.

+

Thus, using win whenever the Tk window name is called for +means that a snit::widget or snit::widgetadaptor can be +adapted by a snit::widgetadaptor. See WIDGETS for +more information.

+
+

How do I pass an instance method as a callback?

+

It depends on the context.

+

Suppose in my application I have a dog object named fido, +and I want fido to bark when a Tk button called .bark is +pressed. In this case, I create the callback command in the usual +way, using list:

+
    button .bark -text "Bark!" -command [list fido bark]
+
+

In typical Tcl style, we use a callback to hook two independent +components together. But suppose that the dog object has +a graphical interface and owns the button itself? In this case, +the dog must pass one of its own instance methods to the +button it owns. The obvious thing to do is this:

+
% snit::widget dog {
+    constructor {args} {
+        #...
+        button $win.barkbtn -text "Bark!" -command [list $self bark]
+        #...
+    }
+}
+::dog
+%
+
+

(Note that in this example, our dog +becomes a snit::widget, because it has GUI behavior. See +WIDGETS for more.) Thus, if we create a dog called +.spot, it will create a Tk button called .spot.barkbtn; +when pressed, the button will call $self bark.

+

Now, this will work--provided that .spot is never renamed to +something else. But surely renaming widgets is +abnormal? And so it is--unless .spot is the hull component of a +snit::widgetadaptor. If it is, then it will be renamed, and +.spot will become the name of the snit::widgetadaptor +object. When the button is pressed, the command $self bark +will be handled by the snit::widgetadaptor, which might or might +not do the right thing.

+

There's a safer way to do it, and it looks like this:

+
% snit::widget dog {
+    constructor {args} {
+        #...
+        button $win.barkbtn -text "Bark!" -command [mymethod bark]
+        #...
+    }
+}
+::dog
+%
+
+

The command mymethod takes any number of arguments, and can be +used like list to build up a callback command; the only +difference is that mymethod returns a +form of the command that won't change even if the instance's name +changes.

+

On the other hand, you might prefer to allow a widgetadaptor to +override a method such that your renamed widget will call the +widgetadaptor's method instead of its own. In this case, +using [list $self bark] will do what you want...but +this is a technique which should be used only in carefully controlled +circumstances.

+
+ +
+

INSTANCE VARIABLES

+

What is an instance variable?

+

An instance variable is a private variable associated with some +particular Snit object. Instance variables can be scalars or arrays.

+
+

How is a scalar instance variable defined?

+

Scalar instance variables are defined in the type definition using the +variable statement. You can simply name it, or you can +initialize it with a value:

+
snit::type mytype {
+    # Define variable "greeting" and initialize it with "Howdy!"
+    variable greeting "Howdy!"
+}
+
+
+

How is an array instance variable defined?

+

Array instance variables are also defined in the type definition +using the variable command. You can initialize them at the same +time by specifying the -array option:

+
snit::type mytype {
+    # Define array variable "greetings"
+    variable greetings -array {
+        formal "Good Evening"
+        casual "Howdy!"
+    }
+}
+
+
+

What happens if I don't initialize an instance variable?

+

Variables do not really exist until they are given values. If you +do not initialize a variable when you define it, then you must be +sure to assign a value to it (in the constructor, say, or in some +method) before you reference it.

+
+

Are there any limitations on instance variable names?

+

Just a few.

+

First, every Snit object has a built-in instance variable called +options, which should never be redefined.

+

Second, all names beginning with "Snit_" are reserved for +use by Snit internal code.

+

Third, instance variable names containing the namespace delimiter +(::) are likely to cause great confusion.

+
+

Do I need to declare my instance variables in my methods?

+

No. Once you've defined an instance variable in the type definition, +it can be used in any instance code (instance methods, the +constructor, and the destructor) without declaration. This differs +from normal Tcl practice, in which all non-local variables in a proc +need to be declared.

+

There is a speed penalty to having all instance variables implicitly +available in all instance code. Even though your code need not +declare the variables explicitly, Snit must still declare them, +and that takes time. If you have ten instance variables, a method +that uses none of them must still pay the declaration penalty for +all ten. In most cases, the additional runtime cost is negligible. +If extreme cases, you might wish to avoid it; there are two methods +for doing so.

+

The first is to define a single instance variable, an array, and store +all of your instance data in the array. This way, you're only paying +the declaration penalty for one variable--and you probably need the +variable most of the time anyway. This method breaks down if your +instance variables include multiple arrays; in Tcl 8.5, however, +the dict command might come to your rescue.

+

The second method is to declare your instance variables explicitly +in your instance code, while not including them in the type +definition:

+
snit::type dog {
+    constructor {} {
+        variable mood
+        set mood happy
+    }
+    method setmood {newMood} {
+        variable mood
+        set mood $newMood
+    }
+    method getmood {} {
+        variable mood
+        return $mood
+    }
+}
+
+

This allows you to ensure that only the required variables are +included in each method, at the cost of longer code and run-time +errors when you forget to declare a variable you need.

+
+

How do I pass an instance variable's name to another object?

+

In Tk, it's common to pass a widget a variable name; for example, Tk +label widgets have a -textvariable option which names the +variable which will contain the widget's text. This allows the +program to update the label's value just by assigning a new value to +the variable.

+

If you naively pass the instance variable name to the label widget, +you'll be confused by the result; Tk will assume that the name names a +global variable. Instead, you need to provide a fully-qualified +variable name. From within an instance method or a constructor, you +can fully qualify the variable's name using the myvar command:

+
snit::widget mywidget {
+    variable labeltext ""
+    constructor {args} {
+        # ...
+        label $win.label -textvariable [myvar labeltext]
+        # ...
+    }
+}
+
+
+

How do I make an instance variable public?

+

Practically speaking, you don't. Instead, you'll implement public +variables as OPTIONS. +Alternatively, you can write INSTANCE METHODS to set and get +the variable's value.

+
+
+

OPTIONS

+

What is an option?

+

A type's options are the equivalent of what other object-oriented +languages would call public member variables or properties: they are +data values which can be retrieved and (usually) set by the clients of +an object.

+

Snit's implementation of options follows the Tk model fairly exactly, +except that snit::type objects usually don't interact with +THE TK OPTION DATABASE; snit::widget and +snit::widgetadaptor objects, on the other hand, always do.

+
+

How do I define an option?

+

Options are defined in the type definition using the option +statement. Consider the following type, to be used in an application +that manages a list of dogs for a pet store:

+
snit::type dog {
+    option -breed -default mongrel
+    option -color -default brown
+    option -akc   -default 0
+    option -shots -default 0
+}
+
+

According to this, a dog has four notable properties: a +breed, a color, a flag that says whether it's pedigreed with the +American Kennel Club, and another flag that says whether it has had +its shots. The default dog, evidently, is a brown mutt.

+

There are a number of options you can specify when defining an option; +if -default is the only one, you can omit the word +-default as follows:

+
snit::type dog {
+    option -breed mongrel
+    option -color brown
+    option -akc   0
+    option -shots 0
+}
+
+

If no -default value is specified, the option's default value +will be the empty string (but see THE TK OPTION DATABASE).

+

The Snit man page refers to options like these as "locally defined" options.

+
+

How can a client set options at object creation?

+

The normal convention is that the client may pass any number of +options and their values after the object's name at object creation. +For example, the ::dog command defined in the previous answer can now +be used to create individual dogs. Any or all of the options may be +set at creation time.

+
% dog spot -breed beagle -color "mottled" -akc 1 -shots 1
+::spot
+% dog fido -shots 1
+::fido
+%
+
+

So ::spot is a pedigreed beagle; ::fido is a typical mutt, +but his owners evidently take care of him, because he's had his shots.

+

Note: If the type defines a constructor, it can specify a +different object-creation syntax. See CONSTRUCTORS for more +information.

+
+

How can a client retrieve an option's value?

+

Retrieve option values using the cget method:

+
% spot cget -color
+mottled
+% fido cget -breed
+mongrel
+%
+
+
+

How can a client set options after object creation?

+

Any number of options may be set at one time using the +configure instance method. Suppose that closer inspection +shows that ::fido is not a brown mongrel, but rather a rare Arctic Boar +Hound of a lovely dun color:

+
% fido configure -color dun -breed "Arctic Boar Hound"
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+
+

Alternatively, the configurelist method takes a list of +options and values; occasionally this is more convenient:

+
% set features [list -color dun -breed "Arctic Boar Hound"]
+-color dun -breed {Arctic Boar Hound}
+% fido configurelist $features
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+%
+
+

In Tcl 8.5, the * keyword can be used with +configure in this case:

+
% set features [list -color dun -breed "Arctic Boar Hound"]
+-color dun -breed {Arctic Boar Hound}
+% fido configure {*}$features
+% fido cget -color
+dun
+% fido cget -breed
+Arctic Boar Hound
+%
+
+

The results are the same.

+
+

How should an instance method access an option value?

+

There are two ways an instance method can set and retrieve an option's +value. One is to use the configure and cget +methods, as shown below.

+
% snit::type dog {
+    option -weight 10
+    method gainWeight {} {
+        set wt [$self cget -weight]
+        incr wt
+        $self configure -weight $wt
+    }
+}
+::dog
+% dog fido
+::fido
+% fido cget -weight
+10
+% fido gainWeight
+% fido cget -weight
+11
+%
+
+

Alternatively, Snit provides a built-in array instance variable called +options. The indices are the option names; the values are the +option values. The method gainWeight can thus be rewritten as +follows:

+
+    method gainWeight {} {
+        incr options(-weight)
+    }
+
+

As you can see, using the options variable involves considerably +less typing and is the usual way to do it. But if you use +-configuremethod or -cgetmethod (described in the following +answers), you might wish to use the configure and +cget methods anyway, just so that any special processing you've +implemented is sure to get done. Also, if the option is delegated to +a component then configure and cget are the only way +to access it without accessing the component directly. See +DELEGATION for more information.

+
+

How can I make an option read-only?

+

Define the option with -readonly yes.

+

Suppose you've got an option that determines how +instances of your type are constructed; it must be set at creation +time, after which it's constant. For example, a dog never changes its +breed; it might or might not have had its shots, and if not can have +them at a later time. -breed should be read-only, but +-shots should not be.

+
% snit::type dog {
+    option -breed -default mongrel -readonly yes
+    option -shots -default no
+}
+::dog
+% dog fido -breed retriever
+::fido
+% fido configure -shots yes
+% fido configure -breed terrier
+option -breed can only be set at instance creation
+%
+
+
+

How can I catch accesses to an option's value?

+

Define a -cgetmethod for the option.

+
+

What is a -cgetmethod?

+

A -cgetmethod is a method that's called whenever the related +option's value is queried via the +cget instance method. The handler can compute the option's +value, retrieve it from a database, or do anything else you'd like it to do.

+

Here's what the default behavior would look like if +written using a -cgetmethod:

+
snit::type dog {
+    option -color -default brown -cgetmethod GetOption
+    method GetOption {option} {
+        return $options($option)
+    }
+}
+
+

Any instance method can be used, provided that it takes one argument, +the name of the option whose value is to be retrieved.

+
+

How can I catch changes to an option's value?

+

Define a -configuremethod for the option.

+
+

What is a -configuremethod?

+

A -configuremethod is a method that's called whenever the +related option is given a new value via the configure or +configurelist instance methods. The method can +pass the value on to some other object, store it in a database, or do +anything else you'd like it to do.

+

Here's what the default configuration behavior would look like if +written using a -configuremethod:

+
snit::type dog {
+    option -color -default brown -configuremethod SetOption
+    method SetOption {option value} {
+        set options($option) $value
+    }
+}
+
+

Any instance method can be used, provided that it takes two arguments, +the name of the option and the new value.

+

Note that if your method doesn't store the value in the options +array, the options array won't get updated.

+
+

How can I validate an option's value?

+

Define a -validatemethod.

+
+

What is a -validatemethod?

+

A -validatemethod is a method that's called whenever the +related option is given a new value via the configure or +configurelist instance methods. It's the method's +responsibility to determine whether the new value is valid, and throw +an error if it isn't. The -validatemethod, if any, is called +before the value is stored in the options array; in particular, +it's called before the -configuremethod, if any.

+

For example, suppose an option always takes a Boolean value. You can +ensure that the value is in fact a valid Boolean like this:

+
% snit::type dog {
+    option -shots -default no -validatemethod BooleanOption
+    method BooleanOption {option value} {
+        if {![string is boolean -strict $value]} {
+            error "expected a boolean value, got \"$value\""
+        }
+    }
+}
+::dog
+% dog fido
+% fido configure -shots yes
+% fido configure -shots NotABooleanValue
+expected a boolean value, got "NotABooleanValue"
+%
+
+

Note that the same -validatemethod can be used to validate any number +of boolean options.

+

Any method can be a -validatemethod provided that it takes +two arguments, the option name and the new option value.

+
+
+

TYPE VARIABLES

+

What is a type variable?

+

A type variable is a private variable associated with a Snit type +rather than with a particular instance of the type. In C++ and Java, +the term static member variable is used for the same notion. +Type variables can be scalars or arrays.

+
+

How is a scalar type variable defined?

+

Scalar type variables are defined in the type definition using the +typevariable statement. You can simply name it, or you can +initialize it with a value:

+
+snit::type mytype {
+    # Define variable "greeting" and initialize it with "Howdy!"
+    typevariable greeting "Howdy!"
+}
+
+

Every object of type mytype now has access to a single variable +called greeting.

+
+

How is an array-valued type variable defined?

+

Array-valued type variables are also defined using the +typevariable command; to initialize them, include the +-array option:

+
snit::type mytype {
+    # Define typearray variable "greetings"
+    typevariable greetings -array {
+        formal "Good Evening"
+        casual "Howdy!"
+    }
+}
+
+
+

What happens if I don't initialize a type variable?

+

Variables do not really exist until they are given values. If you +do not initialize a variable when you define it, then you must be +sure to assign a value to it (in the type constructor, say) +before you reference it.

+
+

Are there any limitations on type variable names?

+

Type variable names have the same restrictions as +the names of INSTANCE VARIABLES do.

+
+

Do I need to declare my type variables in my methods?

+

No. Once you've defined a type variable in the type definition, it can +be used in INSTANCE METHODS or TYPE METHODS without +declaration. This differs from normal Tcl practice, in which all +non-local variables in a proc need to be declared.

+

Type variables are subject to the same speed/readability tradeoffs +as instance variables; see +Do I need to declare my instance variables in my methods?

+
+

How do I pass a type variable's name to another object?

+

In Tk, it's common to pass a widget a variable name; for example, Tk +label widgets have a -textvariable option which names the +variable which will contain the widget's text. This allows the +program to update the label's value just by assigning a new value to +the variable.

+

If you naively pass a type variable name to the label widget, you'll +be confused by the result; Tk will assume that the name names a global +variable. Instead, you need to provide a fully-qualified variable +name. From within an instance method or a constructor, you can fully +qualify the type variable's name using the mytypevar command:

+
snit::widget mywidget {
+    typevariable labeltext ""
+    constructor {args} {
+        # ...
+        label $win.label -textvariable [mytypevar labeltext]
+        # ...
+    }
+}
+
+
+

How do I make a type variable public?

+

There are two ways to do this. The preferred way is to write a pair +of TYPE METHODS to set and query the type variable's value.

+

Type variables are stored in the type's namespace, which has +the same name as the type itself. Thus, you can also +publicize the type variable's name in your +documentation so that clients can access it directly. For example,

+
snit::type mytype {
+    typevariable myvariable
+}
+set ::mytype::myvariable "New Value"
+
+
+
+

TYPE METHODS

+

What is a type method?

+

A type method is a procedure associated with the type itself rather +than with any specific instance of the type, and called as a +subcommand of the type command.

+
+

How do I define a type method?

+

Type methods are defined in the type definition using the +typemethod statement:

+
snit::type dog {
+    # List of pedigreed dogs
+    typevariable pedigreed
+    typemethod pedigreedDogs {} {
+        return $pedigreed
+    }
+}
+
+

Suppose the dog type maintains a list of the names of the dogs +that have pedigrees. The pedigreedDogs type method returns this +list.

+

The typemethod statement looks just like a normal Tcl +proc, except that it appears in a snit::type definition. +Notice that every type method gets an implicit argument called +type, which contains the fully-qualified type name.

+
+

How does a client call a type method?

+

The type method name becomes a subcommand of the type's command. For +example, assuming that the constructor adds each pedigreed dog to the +list of pedigreedDogs,

+
snit::type dog {
+    option -pedigreed 0
+    # List of pedigreed dogs
+    typevariable pedigreed
+    typemethod pedigreedDogs {} {
+        return $pedigreed
+    }
+    # ...
+}
+dog spot -pedigreed 1
+dog fido
+foreach dog [dog pedigreedDogs] { ... }
+
+
+

Are there any limitations on type method names?

+

Not really, so long as you avoid the standard type method names: +create, destroy, and info.

+
+

How do I make a type method private?

+

It's sometimes useful to define private type methods, that is, type +methods intended to be called only by other type or instance methods +of the same object.

+

Snit doesn't implement any access control on type methods; by +convention, the names of public methods begin with a lower-case +letter, and the names of private methods begin with an upper-case +letter.

+

Alternatively, a Snit proc can be used as a private type method; see +PROCS.

+
+

Are there any limitations on type method arguments?

+

Method argument lists are defined just like normal Tcl proc argument +lists; in particular, they can include arguments with default values +and the args argument.

+

However, every type method is called with an implicit argument called +type that contains the name of the type command. In addition, +type methods should by convention avoid using the names of the +arguments implicitly defined for INSTANCE METHODS.

+
+

How does an instance or type method call a type method?

+

If an instance or type method needs to call a type method, it should +use $type to do so:

+
snit::type dog {
+    typemethod pedigreedDogs {} { ... }
+    typemethod printPedigrees {} {
+        foreach obj [$type pedigreedDogs] { ... }
+    }
+}
+
+
+

How do I pass a type method as a callback?

+

It's common in Tcl to pass a snippet of code to another object, for it +to call later. Because types cannot be renamed, you can just +use the type name, or, if the callback is registered from within +a type method, type. For example, suppose we want to print a +list of pedigreed dogs when a Tk button is pushed:

+
+button .btn -text "Pedigrees" -command [list dog printPedigrees]
+pack .btn
+
+

Alternatively, from a method or type method you can use the +mytypemethod command, just as you would use mymethod +to define a callback command for INSTANCE METHODS.

+
+

Can type methods be hierarchical?

+

Yes, you can define hierarchical type methods in just the same way as +you can define hierarchical instance methods. See +INSTANCE METHODS for more.

+
+
+

PROCS

+

What is a proc?

+

A Snit proc is really just a Tcl proc defined within the type's +namespace. You can use procs for private code that isn't related to +any particular instance.

+
+

How do I define a proc?

+

Procs are defined by including a proc statement in the type +definition:

+
snit::type mytype {
+    # Pops and returns the first item from the list stored in the
+    # listvar, updating the listvar
+   proc pop {listvar} { ... }
+   # ...
+}
+
+
+

Are there any limitations on proc names?

+

Any name can be used, so long as it does not begin with Snit_; +names beginning with Snit_ are reserved for Snit's own use. +However, the wise programmer will avoid proc names (set, +list, if, etc.) that would shadow standard Tcl +command names.

+

proc names, being private, should begin with a capital letter according +to convention; however, as there are typically no public procs +in the type's namespace it doesn't matter much either way.

+
+

How does a method call a proc?

+

Just like it calls any Tcl command. For example,

+
snit::type mytype {
+    # Pops and returns the first item from the list stored in the
+    # listvar, updating the listvar
+    proc pop {listvar} { ... }
+    variable requestQueue {}
+    # Get one request from the queue and process it.
+    method processRequest {} {
+        set req [pop requestQueue]
+    }
+}
+
+
+

How can I pass a proc to another object as a callback?

+

The myproc command returns a callback command for the +proc, just as mymethod does for a method.

+
+
+

TYPE CONSTRUCTORS

+

What is a type constructor?

+

A type constructor is a body of code that initializes the type as a +whole, rather like a C++ static initializer. The body of a type +constructor is executed once when the type is defined, and never +again.

+

A type can have at most one type constructor.

+
+

How do I define a type constructor?

+

A type constructor is defined by using the typeconstructor +statement in the type definition. For example, suppose the type uses +an array-valued type variable as a look-up table, and the values in +the array have to be computed at start-up.

+
% snit::type mytype {
+    typevariable lookupTable
+    typeconstructor {
+        array set lookupTable {key value...}
+    }
+}
+
+
+
+

CONSTRUCTORS

+

What is a constructor?

+

In object-oriented programming, an object's constructor is responsible +for initializing the object completely at creation time. The constructor +receives the list of options passed to the snit::type command's +create method and can then do whatever it likes. That might include +computing instance variable values, reading data from files, creating +other objects, updating type and instance variables, and so forth.

+

The constructor's return value is ignored (unless it's an +error, of course).

+
+

How do I define a constructor?

+

A constructor is defined by using the constructor statement in +the type definition. Suppose that it's desired to keep a list of all +pedigreed dogs. The list can be maintained in a +type variable and retrieved by a type method. Whenever a dog is +created, it can add itself to the list--provided that it's registered +with the American Kennel Club.

+
% snit::type dog {
+    option -akc 0
+    typevariable akcList {}
+    constructor {args} {
+        $self configurelist $args
+        if {$options(-akc)} {
+            lappend akcList $self
+        }
+    }
+    typemethod akclist {} {
+        return $akcList
+    }
+}
+::dog
+% dog spot -akc 1
+::spot
+% dog fido
+::fido
+% dog akclist
+::spot
+%
+
+
+

What does the default constructor do?

+

If you don't provide a constructor explicitly, you get the default +constructor, which is identical to the explicitly-defined +constructor shown here:

+
snit::type dog {
+    constructor {args} {
+        $self configurelist $args
+    }
+}
+
+

When the constructor is called, args will be set to the list of +arguments that follow the object's name. The constructor is allowed +to interpret this list any way it chooses; the normal convention is +to assume that it's a list of option names and values, as shown in the +example above. If you simply want to save the option values, you +should use the configurelist method, as shown.

+
+

Can I choose a different set of arguments for the constructor?

+

Yes, you can. For example, suppose we wanted to be sure that the +breed was explicitly stated for every dog at creation time, and +couldn't be changed thereafter. One way to do that is as follows:

+
% snit::type dog {
+    variable breed
+    option -color brown
+    option -akc 0
+    constructor {theBreed args} {
+        set breed $theBreed
+        $self configurelist $args
+    }
+    method breed {} { return $breed }
+}
+::dog
+% dog spot dalmatian -color spotted -akc 1
+::spot
+% spot breed
+dalmatian
+
+

The drawback is that this syntax is non-standard, and may +limit the compatibility of your new type with other people's code. +For example, Snit assumes that it can create +COMPONENTS using the standard creation syntax.

+
+

Are there any limitations on constructor arguments?

+

Constructor argument lists are subject to the same limitations +as those on instance method argument lists. It has the +same implicit arguments, and can contain default values and the +args argument.

+
+

Is there anything special about writing the constructor?

+

Yes. Writing the constructor can be tricky if you're delegating +options to components, and there are specific issues relating to +snit::widgets and snit::widgetadaptors. See +DELEGATION, WIDGETS, +WIDGET ADAPTORS, and THE TK OPTION DATABASE.

+
+
+

DESTRUCTORS

+

What is a destructor?

+

A destructor is a special kind of method that's called when an object +is destroyed. It's responsible for doing any necessary clean-up when +the object goes away: destroying COMPONENTS, closing files, +and so forth.

+
+

How do I define a destructor?

+

Destructors are defined by using the destructor statement in the +type definition.

+

Suppose we're maintaining a list of pedigreed dogs; +then we'll want to remove dogs from it when they are destroyed.

+
snit::type dog {
+    option -akc 0
+    typevariable akcList {}
+    constructor {args} {
+        $self configurelist $args
+        if {$options(-akc)} {
+            lappend akcList $self
+        }
+    }
+    destructor {
+        set ndx [lsearch $akcList $self]
+        if {$ndx != -1} {
+            set akcList [lreplace $akcList $ndx $ndx]
+        }
+    }
+    typemethod akclist {} {
+        return $akcList
+    }
+}
+
+
+

Are there any limitations on destructor arguments?

+

Yes; a destructor has no explicit arguments.

+
+

What implicit arguments are passed to the destructor?

+

The destructor gets the same implicit arguments that are passed to +INSTANCE METHODS: type, selfns, win, and +self.

+
+

Must components be destroyed explicitly?

+

Yes and no.

+

Any Tk widgets created by a snit::widget or +snit::widgetadaptor will be destroyed automatically by Tk +when the megawidget is destroyed, in keeping with normal Tk behavior +(destroying a parent widget destroys the whole tree).

+

Components of normal snit::types, on the other hand, +are never destroyed automatically, nor are non-widget components +of Snit megawidgets. If your object creates them in its +constructor, then it should generally destroy them in its destructor.

+
+

Is there any special about writing a destructor?

+

Yes. If an object's constructor throws an error, the object's +destructor will be called to clean up; this means that the object +might not be completely constructed when the destructor is called. +This can cause the destructor to throw its own error; the result +is usually misleading, confusing, and unhelpful. Consequently, it's +important to write your destructor so that it's fail-safe.

+

For example, a dog might create a tail component; the +component will need to be destroyed. But suppose there's an error +while processing the creation options--the destructor will be called, +and there will be no tail to destroy. The simplest solution is +generally to catch and ignore any errors while destroying components.

+
snit::type dog {
+    component tail
+    constructor {args} {
+        $self configurelist $args
+        set tail [tail %AUTO%]
+    }
+    destructor {
+        catch {$tail destroy}
+    }
+}
+
+
+
+

COMPONENTS

+

What is a component?

+

Often an object will create and manage a number of other objects. A +Snit megawidget, for example, will often create a number of Tk +widgets. These objects are part of the main object; it is composed +of them, so they are called components of the object.

+

But Snit also has a more precise meaning for +COMPONENT. The components of a Snit object are those +objects to which methods or options can be delegated. +(See DELEGATION for more information about delegation.)

+
+

How do I declare a component?

+

First, you must decide what role a component plays within your object, +and give the role a name. Then, you declare the component using its +role name and the component statement. The component +statement declares an instance variable which is used to +store the component's command name when the component is created.

+

For example, suppose your dog object +creates a tail object (the better to wag with, no doubt):

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        # Create and save the component's command
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+    method wag {} {
+        $mytail wag
+    }
+}
+
+

As shown here, it doesn't matter what the tail object's real +name is; the dog object refers to it by its component name.

+

The above example shows one way to delegate the wag method to +the mytail component; see DELEGATION for an easier way.

+
+

How is a component named?

+

A component has two names. The first name is that of the component +variable; this represents the role the component object plays within +the Snit object. This is the component name proper, and is the name +used to refer to the component within Snit code. The second name is +the name of the actual component object created by the Snit object's +constructor. This second name is always a Tcl command name, and is +referred to as the component's object name.

+

In the example in the previous question, the component name is +mytail; the mytail component's object name is chosen +automatically by Snit since %AUTO% was used when the component +object was created.

+
+

Are there any limitations on component names?

+

Yes. snit::widget and snit::widgetadaptor objects have a special +component called the hull component; thus, the name hull +should be used for no other purpose.

+

Otherwise, since component names are in fact instance variable names +they must follow the rules for INSTANCE VARIABLES.

+
+

What is an owned component?

+

An owned component is a component whose object command's +lifetime is controlled by the snit::type or snit::widget.

+

As stated above, a component is an object to +which our object can delegate methods or options. Under this +definition, our object will usually create its component objects, +but not necessarily. Consider the following: a dog object has a tail +component; but tail knows that it's part of the dog:

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+    destructor {
+        catch {$mytail destroy}
+    }
+    delegate method wagtail to mytail as wag
+    method bark {} {
+        return "$self barked."
+    }
+}
+ snit::type tail {
+     component mydog
+     option -partof -readonly yes
+     constructor {args} {
+         $self configurelist $args
+         set mydog $options(-partof)
+     }
+     method wag {} {
+         return "Wag, wag."
+     }
+     method pull {} {
+         $mydog bark
+     }
+ }
+
+

Thus, if you ask a dog to wag its tail, it tells its tail to wag; +and if you pull the dog's tail, the tail tells the dog to bark. In +this scenario, the tail is a component of the dog, and the dog is a +component of the tail, but the dog owns the tail and not the other way +around.

+
+

What does the install command do?

+

The install command creates an owned component using a specified +command, and assigns the result to the component's instance variable. +For example:

+
snit::type dog {
+    component mytail
+    constructor {args} {
+        # set mytail [tail %AUTO% -partof $self]
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+

In a snit::type's code, the install +command shown above is equivalent to the set mytail command +that's commented out. In a snit::widget's or +snit::widgetadaptor's, code, however, the +install command also queries THE TK OPTION DATABASE +and initializes the new component's options accordingly. For consistency, +it's a good idea to get in the habit of using install for all +owned components.

+
+

Must owned components be created in the constructor?

+

No, not necessarily. In fact, there's no reason why an +object can't destroy and recreate a component multiple times over +its own lifetime.

+
+

Are there any limitations on component object names?

+

Yes.

+

Component objects which are Tk widgets or megawidgets must have valid +Tk window names.

+

Component objects which are not widgets or megawidgets must have +fully-qualified command names, i.e., names which include the full +namespace of the command. Note that Snit always creates objects with +fully qualified names.

+

Next, the object names of components and owned by your object +must be unique. This is no problem for widget components, since +widget names are always unique; but consider the following code:

+
snit::type tail { ... }
+snit::type dog {
+    delegate method wag to mytail
+    constructor {} {
+        install mytail using tail mytail
+    }
+}
+
+

This code uses the component name, mytail, as the component object +name. This is not good, and here's why: Snit instance code executes +in the Snit type's namespace. In this case, the mytail component is +created in the ::dog:: namespace, and will thus have the name +::dog::mytail.

+

Now, suppose you create two dogs. Both dogs will attempt to +create a tail called ::dog::mytail. The first will succeed, +and the second will fail, since Snit won't let you create an object if +its name is already a command. Here are two ways to avoid this situation:

+

First, if the component type is a snit::type you can +specify %AUTO% as its name, and be guaranteed to get a unique name. +This is the safest thing to do:

+
+    install mytail using tail %AUTO%
+
+

If the component type isn't a snit::type you can create +the component in the object's instance namespace:

+
+    install mytail using tail ${selfns}::mytail
+
+

Make sure you pick a unique name within the instance namespace.

+
+

Must I destroy the components I own?

+

That depends. When a parent widget is destroyed, all child widgets +are destroyed automatically. Thus, if your object is a snit::widget +or snit::widgetadaptor you don't need to destroy any components +that are widgets, because they will generally be children or +descendants of your megawidget.

+

If your object is an instance of snit::type, though, none of its +owned components will be destroyed automatically, nor will be +non-widget components of a snit::widget be destroyed +automatically. All such owned components must be destroyed +explicitly, or they won't be destroyed at all.

+
+

Can I expose a component's object command as part of my interface?

+

Yes, and there are two ways to do it. The most appropriate way is +usually to use DELEGATION. Delegation allows you to pass +the options and methods you specify along to particular components. +This effectively hides the components from the users of your type, and +ensures good encapsulation.

+

However, there are times when it's appropriate, not to mention +simpler, just to make the entire component part of your type's public +interface.

+
+

How do I expose a component's object command?

+

When you declare the component, specify the component +statement's -public option. The value of this option is the +name of a method which will be delegated to your component's object +command.

+

For example, supposed you've written a combobox megawidget which owns +a listbox widget, and you want to make the listbox's entire interface +public. You can do it like this:

+
snit::widget combobox {
+     component listbox -public listbox
+     constructor {args} {
+         install listbox using listbox $win.listbox ....
+     }
+}
+combobox .mycombo
+.mycombo listbox configure -width 30
+
+

Your comobox widget, .mycombo, now has a listbox method +which has all of the same subcommands as the listbox widget itself. +Thus, the above code sets the listbox component's width to 30.

+

Usually you'll let the method name be the same as the component name; +however, you can name it anything you like.

+
+
+

TYPE COMPONENTS

+

What is a type component?

+

A type component is a component that belongs to the type itself +instead of to a particular instance of the type. The relationship +between components and type components is the same as the +relationship between INSTANCE VARIABLES and +TYPE VARIABLES. Both INSTANCE METHODS and +TYPE METHODS can be delegated to type components.

+

Once you understand COMPONENTS and +DELEGATION, type components are just more of the same.

+
+

How do I declare a type component?

+

Declare a type component using the typecomponent statement. It +takes the same options (-inherit and -public) as the +component statement does, and defines a type variable to hold +the type component's object command.

+

Suppose in your model you've got many dogs, but only one +veterinarian. You might make the veterinarian a type component.

+
snit::type veterinarian { ... }
+snit::type dog {
+    typecomponent vet
+    # ...
+}
+
+
+

How do I install a type component?

+

Just use the set command to assign the component's object +command to the type component. Because types +(even snit::widget types) are not widgets, and do not have +options anyway, the extra features of the install command are +not needed.

+

You'll usually install type components in the type constructor, as +shown here:

+
snit::type veterinarian { ... }
+snit::type dog {
+    typecomponent vet
+    typeconstructor {
+        set vet [veterinarian %AUTO%]
+    }
+}
+
+
+ +
+

DELEGATION

+

What is delegation?

+

Delegation, simply put, is when you pass a task you've been given to +one of your assistants. (You do have assistants, don't you?) Snit +objects can do the same thing. The following example shows one way in +which the dog object can delegate its wag method and its +-taillength option to its tail component.

+
snit::type dog {
+    variable mytail
+    option -taillength -configuremethod SetTailOption -cgetmethod GetTailOption
+    method SetTailOption {option value} {
+         $mytail configure $option $value
+    }
+    method GetTailOption {option} {
+         $mytail cget $option
+    }
+    method wag {} {
+        $mytail wag
+    }
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+

This is the hard way to do it, by it demonstrates what delegation is +all about. See the following answers for the easy way to do it.

+

Note that the constructor calls the configurelist method +after it creates its tail; otherwise, +if -taillength appeared in the list of args we'd get an +error.

+
+

How can I delegate a method to a component object?

+

Delegation occurs frequently enough that Snit makes it easy. Any +method can be delegated to any component or type component +by placing a single delegate statement in the type definition. +(See COMPONENTS and TYPE COMPONENTS +for more information about component names.)

+

For example, here's a much better way to delegate the dog +object's wag method:

+
% snit::type dog {
+    delegate method wag to mytail
+    constructor {} {
+        install mytail using tail %AUTO%
+    }
+}
+::dog
+% snit::type tail {
+    method wag {} { return "Wag, wag, wag."}
+}
+::tail
+% dog spot
+::spot
+% spot wag
+Wag, wag, wag.
+
+

This code has the same effect as the code shown under the previous +question: when a dog's wag method is called, the call and +its arguments are passed along automatically to the tail object.

+

Note that when a component is mentioned in a delegate statement, +the component's instance variable is defined implicitly. However, +it's still good practice to declare it explicitly using the +component statement.

+

Note also that you can define a method name using the method +statement, or you can define it using delegate; you can't do +both.

+
+

Can I delegate to a method with a different name?

+

Suppose you wanted to delegate the dog's wagtail method to +the tail's wag method. After all you wag the tail, not +the dog. It's easily done:

+
snit::type dog {
+    delegate method wagtail to mytail as wag
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+
+
+

Can I delegate to a method with additional arguments?

+

Suppose the tail's wag method takes as an argument the +number of times the tail should be wagged. You want to delegate the +dog's wagtail method to the tail's wag +method, specifying that the tail should be wagged exactly three times. +This is easily done, too:

+
snit::type dog {
+    delegate method wagtail to mytail as {wag 3}
+    # ...
+}
+snit::type tail {
+    method wag {count} {
+        return [string repeat "Wag " $count]
+    }
+    # ...
+}
+
+
+

Can I delegate a method to something other than an object?

+

Normal method delegation assumes that you're delegating a method (a +subcommand of an object command) to a method of another object (a +subcommand of a different object command). But not all Tcl objects +follow Tk conventions, and not everything you'd to which you'd like +to delegate a method is necessary an object. Consequently, Snit makes +it easy to delegate a method to pretty much anything you like using +the delegate statement's using clause.

+

Suppose your dog simulation stores dogs in a database, each dog as a +single record. The database API you're using provides a number of +commands to manage records; each takes the record ID (a string you +choose) as its first argument. For example, saverec +saves a record. If you let the record ID be the name of the dog +object, you can delegate the dog's save method to the +saverec command as follows:

+
snit::type dog {
+    delegate method save using {saverec %s}
+}
+
+

The %s is replaced with the instance name when the +save method is called; any additional arguments are the +appended to the resulting command.

+

The using clause understands a number of other %-conversions; +in addition to the instance name, you can substitute in the method +name (%m), the type name (%t), the instance +namespace (%n), the Tk window name (%w), and, +if a component or typecomponent name was given in the +delegate statement, the component's object command +(%c).

+
+

How can I delegate a method to a type component object?

+

Just exactly as you would to a component object. The +delegate method statement accepts both component and type +component names in its to clause.

+
+

How can I delegate a type method to a type component object?

+

Use the delegate typemethod statement. It works like +delegate method, with these differences: first, it defines +a type method instead of an instance method; second, the +using clause ignores the %s, %n, +and %w %-conversions.

+

Naturally, you can't delegate a type method to an instance +component...Snit wouldn't know which instance should receive it.

+
+

How can I delegate an option to a component object?

+

The first question in this section (see DELEGATION) shows +one way to delegate an option to a component; but this pattern occurs +often enough that Snit makes it easy. For example, every tail +object has a -length option; we want to allow the creator of +a dog object to set the tail's length. We can do this:

+
% snit::type dog {
+    delegate option -length to mytail
+    constructor {args} {
+        install mytail using tail %AUTO% -partof $self
+        $self configurelist $args
+    }
+}
+::dog
+% snit::type tail {
+    option -partof
+    option -length 5
+}
+::tail
+% dog spot -length 7
+::spot
+% spot cget -length
+7
+
+

This produces nearly the same result as the -configuremethod and +-cgetmethod shown under the first question in this +section: whenever a dog object's -length option is set +or retrieved, the underlying tail object's option is set or +retrieved in turn.

+

Note that you can define an option name using the option +statement, or you can define it using delegate; you can't do +both.

+
+

Can I delegate to an option with a different name?

+

In the previous answer we delegated the dog's -length +option down to its tail. This is, of course, wrong. The dog +has a length, and the tail has a length, and they are different. What +we'd really like to do is give the dog a -taillength +option, but delegate it to the tail's -length option:

+
snit::type dog {
+    delegate option -taillength to mytail as -length
+    constructor {args} {
+        set mytail [tail %AUTO% -partof $self]
+        $self configurelist $args
+    }
+}
+
+
+

How can I delegate any unrecognized method or option to a component object?

+

It may happen that a Snit object gets most of its behavior from one of +its components. This often happens with snit::widgetadaptors, +for example, where we wish to slightly the modify the behavior of an +existing widget. To carry on with our dog example, however, suppose +that we have a snit::type called animal that implements a +variety of animal behaviors--moving, eating, sleeping, and so forth. +We want our dog objects to inherit these same behaviors, while +adding dog-like behaviors of its own. +Here's how we can give a dog methods and options of its own +while delegating all other methods and options to its animal +component:

+
snit::type dog {
+    delegate option * to animal
+    delegate method * to animal
+    option -akc 0
+    constructor {args} {
+        install animal using animal %AUTO% -name $self
+        $self configurelist $args
+    }
+    method wag {} {
+        return "$self wags its tail"
+    }
+}
+
+

That's it. A dog is now an animal that has a +-akc option and can wag its tail.

+

Note that we don't need to specify the full list of method names or +option names that animal will receive. +It gets anything dog doesn't recognize--and if it doesn't +recognize it either, it will simply throw an error, just as it should.

+

You can also delegate all unknown type methods to a type component +using delegate typemethod *.

+
+

How can I delegate all but certain methods or options to a component?

+

In the previous answer, we said that every dog is +an animal by delegating all unknown methods and options to the +animal component. But what if the animal type has some +methods or options that we'd like to suppress?

+

One solution is to explicitly delegate all the options and methods, +and forgo the convenience of delegate method * and +delegate option *. But if we wish to suppress only a few +options or methods, there's an easier way:

+
snit::type dog {
+    delegate option * to animal except -numlegs
+    delegate method * to animal except {fly climb}
+    # ...
+    constructor {args} {
+        install animal using animal %AUTO% -name $self -numlegs 4
+        $self configurelist $args
+    }
+    # ...
+}
+
+

Dogs have four legs, so we specify that explicitly when we create the +animal component, and explicitly exclude -numlegs from the +set of delegated options. Similarly, dogs can neither +fly nor climb, +so we exclude those animal methods as shown.

+
+

Can a hierarchical method be delegated?

+

Yes; just specify multiple words in the delegated method's name:

+
snit::type tail {
+    method wag {} {return "Wag, wag"}
+    method droop {} {return "Droop, droop"}
+}
+snit::type dog {
+    delegate method {tail wag} to mytail
+    delegate method {tail droop} to mytail
+    # ...
+    constructor {args} {
+        install mytail using tail %AUTO%
+        $self configurelist $args
+    }
+    # ...
+}
+
+

Unrecognized hierarchical methods can also be delegated; the following +code delegates all subcommands of the "tail" method to the "mytail" +component:

+
snit::type dog {
+    delegate method {tail *} to mytail
+    # ...
+}
+
+
+
+

WIDGETS

+

What is a snit::widget?

+

A snit::widget is the Snit version of what Tcl programmers +usually call a megawidget: a widget-like object usually +consisting of one or more Tk widgets all contained within a Tk frame.

+

A snit::widget is also a special kind of snit::type. Just +about everything in this FAQ list that relates to snit::types +also applies to snit::widgets.

+
+

How do I define a snit::widget?

+

snit::widgets are defined using the snit::widget command, +just as snit::types are defined by the snit::type command.

+

The body of the definition can contain all of the same kinds of +statements, plus a couple of others which will be mentioned below.

+
+

How do snit::widgets differ from snit::types?

+
    +

  • The name of an instance of a snit::type can be any valid Tcl +command name, in any namespace. +The name of an instance of a snit::widget must be a valid Tk +widget name, and its parent widget must already exist.

    • +

  • An instance of a snit::type can be destroyed by calling +its destroy method. Instances of a snit::widget have no +destroy method; use the Tk destroy command instead.

    • +

  • Every instance of a snit::widget has one predefined component +called its hull component. +The hull is usually a Tk frame or toplevel widget; any other +widgets created as part of the snit::widget will usually be +contained within the hull.

    • +

  • snit::widgets can have their options receive default values from +THE TK OPTION DATABASE.

    • +
+
+

What is a hull component?

+

Snit can't create a Tk widget object; only Tk can do that. +Thus, every instance of a snit::widget must be wrapped around a +genuine Tk widget; this Tk widget is called the hull component. +Snit effectively piggybacks the behavior you define (methods, options, +and so forth) on top of the hull component so that the whole thing +behaves like a standard Tk widget.

+

For snit::widgets the hull component must be a Tk widget that +defines the -class option.

+

snit::widgetadaptors differ from snit::widgets chiefly in +that any kind of widget can be used as the hull component; see +WIDGET ADAPTORS.

+
+

How can I set the hull type for a snit::widget?

+

A snit::widget's hull component will usually be a Tk frame +widget; however, it may be any Tk widget that defines the +-class option. You can +explicitly choose the hull type you prefer by including the hulltype +command in the widget definition:

+
snit::widget mytoplevel {
+    hulltype toplevel
+    # ...
+}
+
+

If no hulltype command appears, the hull will be a frame.

+

By default, Snit recognizes the following hull types: the Tk widgets +frame, labelframe, toplevel, and the Tile widgets +ttk::frame, ttk::labelframe, and ttk::toplevel. To +enable the use of some other kind of widget as the hull type, you can +lappend the widget command to the variable snit::hulltypes (always +provided the widget defines the -class option. For example, +suppose Tk gets a new widget type called a prettyframe:

+
lappend snit::hulltypes prettyframe
+snit::widget mywidget {
+    hulltype prettyframe
+    # ...
+}
+
+
+

How should I name widgets which are components of a snit::widget?

+

Every widget, whether a genuine Tk widget or a Snit megawidget, has to +have a valid Tk window name. When a snit::widget is first +created, its instance name, self, is a Tk window name; +however, if the snit::widget is used as the hull component by a +snit::widgetadaptor its instance name will be changed to +something else. For this reason, every snit::widget method, +constructor, destructor, and so forth is passed another implicit +argument, win, which is the window name of the megawidget. Any +children should be named using win as the root.

+

Thus, suppose you're writing a toolbar widget, a frame consisting of a +number of buttons placed side-by-side. It might look something like +this:

+
snit::widget toolbar {
+    delegate option * to hull
+    constructor {args} {
+        button $win.open -text Open -command [mymethod open]
+        button $win.save -text Save -command [mymethod save]
+        # ....
+        $self configurelist $args
+    }
+}
+
+

See also the question on renaming objects, toward the top of this +file.

+
+
+

WIDGET ADAPTORS

+

What is a snit::widgetadaptor?

+

A snit::widgetadaptor is a kind of snit::widget. Whereas +a snit::widget's hull is automatically created and is always a +Tk frame, a snit::widgetadaptor can be based on any Tk +widget--or on any Snit megawidget, or even (with luck) on megawidgets +defined using some other package.

+

It's called a widget adaptor because it allows you to take an +existing widget and customize its behavior.

+
+

How do I define a snit::widgetadaptor?

+

Use the snit::widgetadaptor command. The definition for a +snit::widgetadaptor looks just like that for a snit::type +or snit::widget, except that the constructor must create and +install the hull component.

+

For example, the following code creates a read-only text widget by the +simple device of turning its insert and delete +methods into no-ops. Then, we define new methods, ins and +del, +which get delegated to the hull component as insert and +delete. Thus, we've adapted the text widget and given it new +behavior while still leaving it fundamentally a text widget.

+
::snit::widgetadaptor rotext {
+    constructor {args} {
+        # Create the text widget; turn off its insert cursor
+        installhull using text -insertwidth 0
+        # Apply any options passed at creation time.
+        $self configurelist $args
+    }
+    # Disable the text widget's insert and delete methods, to
+    # make this readonly.
+    method insert {args} {}
+    method delete {args} {}
+    # Enable ins and del as synonyms, so the program can insert and
+    # delete.
+    delegate method ins to hull as insert
+    delegate method del to hull as delete
+    # Pass all other methods and options to the real text widget, so
+    # that the remaining behavior is as expected.
+    delegate method * to hull
+    delegate option * to hull
+}
+
+

The most important part is in the constructor. +Whereas snit::widget creates the hull for you, +snit::widgetadaptor cannot -- it doesn't know what kind of +widget you want. So the first thing the constructor does is create +the hull component (a Tk text widget in this case), and then installs +it using the installhull command.

+

Note: There is no instance command until you create one by +installing a hull component. Any attempt to pass methods to $self +prior to calling installhull will fail.

+
+

Can I adapt a widget created elsewhere in the program?

+

Yes.

+

At times, it can be convenient to adapt a pre-existing widget instead +of creating your own. +For example, the Bwidget PagesManager widget manages a +set of frame widgets, only one of which is visible at a time. +The application chooses which frame is visible. All of the +These frames are created by the PagesManager itself, using +its add method. It's convenient to adapt these frames to +do what we'd like them to do.

+

In a case like this, the Tk widget will already exist when the +snit::widgetadaptor is created. Snit provides an alternate form +of the installhull command for this purpose:

+
snit::widgetadaptor pageadaptor {
+    constructor {args} {
+        # The widget already exists; just install it.
+        installhull $win
+        # ...
+    }
+}
+
+
+

Can I adapt another megawidget?

+

Maybe. If the other megawidget is a snit::widget or +snit::widgetadaptor, then yes. If it isn't then, again, maybe. +You'll have to try it and see. You're most likely to have trouble +with widget destruction--you have to make sure that your +megawidget code receives the <Destroy> event before the +megawidget you're adapting does.

+
+
+

THE TK OPTION DATABASE

+

What is the Tk option database?

+

The Tk option database is a database of default option values +maintained by Tk itself; every Tk application has one. The concept of +the option database derives from something called the X Windows +resource database; however, the option database is available in every +Tk implementation, including those which do not use the X Windows +system (e.g., Microsoft Windows).

+

Full details about the Tk option database are beyond the scope of this +document; both Practical Programming in Tcl and Tk by Welch, +Jones, and Hobbs, and Effective Tcl/Tk Programming by +Harrison and McClennan., have good introductions to it.

+

Snit is implemented so that most of the time it will simply do the +right thing with respect to the option database, provided that the +widget developer does the right thing by Snit. The body of this +section goes into great deal about what Snit requires. The following +is a brief statement of the requirements, for reference.

+
    +

  • If the widget's default widget class is not what is desired, set it +explicitly using the widgetclass statement in the widget +definition.

    • +

  • When defining or delegating options, specify the resource and class +names explicitly when necessary.

    • +

  • Use the installhull using command to create and install the +hull for snit::widgetadaptors.

    • +

  • Use the install command to create and install all +components which are widgets.

    • +

  • Use the install command to create and install +components which aren't widgets if you'd like them to +receive option values from the option database.

    • +
+

The interaction of Tk widgets with the option database is a complex +thing; the interaction of Snit with the option database is even more +so, and repays attention to detail.

+
+

Do snit::types use the Tk option database?

+

No, they don't; querying the option database requires a Tk window +name, and snit::types don't have one.

+

If you create an instance of a snit::type as a +component of a snit::widget or snit::widgetadaptor, on the +other hand, and if any options are delegated to the component, +and if you use install to create and install it, then +the megawidget will query the option database on the +snit::type's behalf. This might or might not be what you +want, so take care.

+
+

What is my snit::widget's widget class?

+

Every Tk widget has a "widget class": a name that is used when adding +option settings to the database. For Tk widgets, the widget class is +the same as the widget command name with an initial capital. For +example, the widget class of the Tk button widget is +Button.

+

Similarly, the widget class of a snit::widget defaults to the +unqualified type name with the first letter capitalized. For example, +the widget class of

+
snit::widget ::mylibrary::scrolledText { ... }
+
+

is ScrolledText.

+

The widget class can also be set explicitly using the +widgetclass statement within the snit::widget definition:

+
snit::widget ::mylibrary::scrolledText {
+    widgetclass Text
+    # ...
+}
+
+

The above definition says that a scrolledText megawidget has the +same widget class as an ordinary text widget. This might or +might not be a good idea, depending on how the rest of the megawidget +is defined, and how its options are delegated.

+
+

What is my snit::widgetadaptor's widget class?

+

The widget class of a snit::widgetadaptor is just the widget +class of its hull widget; Snit has no control over this.

+

Note that the widget class can be changed only for frame and +toplevel widgets, which is why these are the valid hull types +for snit::widgets.

+

Try to use snit::widgetadaptors only to make small modifications +to another widget's behavior. Then, it will usually not make sense to +change the widget's widget class anyway.

+
+

What are option resource and class names?

+

Every Tk widget option has three names: the option name, the resource +name, and the class name. +The option name begins with a hyphen and is all lowercase; it's used +when creating widgets, and with the configure and cget +commands.

+

The resource and class names are used to initialize option +default values by querying the option database. +The resource name is usually just the option +name minus the hyphen, but may contain uppercase letters at word +boundaries; the class name is usually just the resource +name with an initial capital, but not always. For example, here are +the option, resource, and class names for several Tk text +widget options:

+
    -background         background         Background
+    -borderwidth        borderWidth        BorderWidth
+    -insertborderwidth  insertBorderWidth  BorderWidth
+    -padx               padX               Pad
+
+

As is easily seen, sometimes the resource and class names can be +inferred from the option name, but not always.

+
+

What are the resource and class names for my megawidget's options?

+

For options implicitly delegated to a component using +delegate option *, the resource and class names will be +exactly those defined by the component. The configure method +returns these names, along with the option's default and current +values:

+
% snit::widget mytext {
+    delegate option * to text
+    constructor {args} {
+        install text using text .text
+        # ...
+    }
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -padx
+-padx padX Pad 1 1
+%
+
+

For all other options (whether locally defined or explicitly +delegated), the resource and class names can be defined explicitly, or +they can be allowed to have default values.

+

By default, the resource name is just the option name minus the +hyphen; the the class name is just the option name with an initial +capital letter. For example, suppose we explicitly delegate "-padx":

+
% snit::widget mytext {
+    option -myvalue 5
+    delegate option -padx to text
+    delegate option * to text
+    constructor {args} {
+        install text using text .text
+        # ...
+    }
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -myvalue
+-myvalue myvalue Myvalue 5 5
+% .text configure -padx
+-padx padx Padx 1 1
+%
+
+

Here the resource and class names are chosen using the default rules. +Often these rules are sufficient, but in the case of "-padx" we'd most +likely prefer that the option's resource and class names are the same +as for the built-in Tk widgets. This is easily done:

+
% snit::widget mytext {
+    delegate option {-padx padX Pad} to text
+    # ...
+}
+::mytext
+% mytext .text
+.text
+% .text configure -padx
+-padx padX Pad 1 1
+%
+
+
+

How does Snit initialize my megawidget's locally-defined options?

+

The option database is queried for each of the megawidget's +locally-defined options, using the option's resource and class name. +If the result isn't "", then it replaces the default value given in +widget definition. In either case, the default can be overridden by +the caller. For example,

+
option add *Mywidget.texture pebbled
+snit::widget mywidget {
+    option -texture smooth
+    # ...
+}
+mywidget .mywidget -texture greasy
+
+

Here, -texture would normally default to "smooth", but because of +the entry added to the option database it defaults to "pebbled". +However, the caller has explicitly overridden the default, and so the +new widget will be "greasy".

+
+

How does Snit initialize delegated options?

+

That depends on whether the options are delegated to the hull, or to +some other component.

+
+

How does Snit initialize options delegated to the hull?

+

A snit::widget's hull is a widget, and given that its class has +been set it is expected to query the option database for itself. The +only exception concerns options that are delegated to it with a +different name. Consider the following code:

+
option add *Mywidget.borderWidth 5
+option add *Mywidget.relief sunken
+option add *Mywidget.hullbackground red
+option add *Mywidget.background green
+snit::widget mywidget {
+    delegate option -borderwidth to hull
+    delegate option -hullbackground to hull as -background
+    delegate option * to hull
+    # ...
+}
+mywidget .mywidget
+set A [.mywidget cget -relief]
+set B [.mywidget cget -hullbackground]
+set C [.mywidget cget -background]
+set D [.mywidget cget -borderwidth]
+
+

The question is, what are the values of variables A, B, C and D?

+

The value of A is "sunken". The hull is a Tk frame which has been +given the widget class Mywidget; it will automatically query the +option database and pick up this value. Since the -relief option is +implicitly delegated to the hull, Snit takes no action.

+

The value of B is "red". The hull will automatically pick up the +value "green" for its -background option, just as it picked up the +-relief value. However, Snit knows that -hullbackground +is mapped to the hull's -background option; hence, it queries +the option database for -hullbackground and gets "red" and +updates the hull accordingly.

+

The value of C is also "red", because -background is implicitly +delegated to the hull; thus, retrieving it is the same as retrieving +-hullbackground. Note that this case is unusual; the +-background option should probably have been excluded using the delegate +statement's except clause, or (more likely) delegated to some other +component.

+

The value of D is "5", but not for the reason you think. Note that as +it is defined above, the resource name for -borderwidth defaults to +borderwidth, whereas the option database entry is +borderWidth, in +accordance with the standard Tk naming for this option. As with +-relief, the hull picks up its own -borderwidth +option before Snit +does anything. Because the option is delegated under its own name, +Snit assumes that the correct thing has happened, and doesn't worry +about it any further. To avoid confusion, the +-borderwidth option +should have been delegated like this:

+
    delegate option {-borderwidth borderWidth BorderWidth} to hull
+
+

For snit::widgetadaptors, the case is somewhat altered. Widget +adaptors retain the widget class of their hull, and the hull is not +created automatically by Snit. Instead, the snit::widgetadaptor +must call installhull in its constructor. The normal way +to do this is as follows:

+
snit::widgetadaptor mywidget {
+    # ...
+    constructor {args} {
+        # ...
+        installhull using text -foreground white
+        # ...
+    }
+    # ...
+}
+
+

In this case, the installhull command will create the hull using +a command like this:

+
    set hull [text $win -foreground white]
+
+

The hull is a text widget, so its widget class is Text. Just +as with snit::widget hulls, Snit assumes that it will pick up +all of its normal option values automatically, without help from Snit. +Options delegated from a different name are initialized from the +option database in the same way as described above.

+

In earlier versions of Snit, snit::widgetadaptors were expected +to call installhull like this:

+
    installhull [text $win -foreground white]
+
+

This form still works--but Snit will not query the option database as +described above.

+
+

How does Snit initialize options delegated to other components?

+

For hull components, Snit assumes that Tk will do most of the work +automatically. Non-hull components are somewhat more complicated, because +they are matched against the option database twice.

+

A component widget remains a widget still, and is therefore +initialized from the option database in the usual way. A text +widget remains a text widget whether it is a component of a +megawidget or not, and will be created as such.

+

But then, the option database is queried for all options delegated to +the component, and the component is initialized accordingly--provided +that the install command is used to create it.

+

Before option database support was added to Snit, the usual way to +create a component was to simply create it in the constructor and +assign its command name to the component variable:

+
snit::widget mywidget {
+    delegate option -background to myComp
+    constructor {args} {
+        set myComp [text $win.text -foreground black]
+    }
+}
+
+

The drawback of this method is that Snit has no opportunity to +initialize the component properly. Hence, the following approach is +now used:

+
snit::widget mywidget {
+    delegate option -background to myComp
+    constructor {args} {
+        install myComp using text $win.text -foreground black
+    }
+}
+
+

The install command does the following:

+
    +

  • Builds a list of the options explicitly included in the install +command--in this case, -foreground.

    • +

  • Queries the option database for all options delegated explicitly to +the named component.

    • +

  • Creates the component using the specified command, after inserting +into it a list of options and values read from the option database. +Thus, the explicitly included options (like -foreground) will +override anything read from the option database.

    • +

  • If the widget definition implicitly delegated options to the component +using delegate option *, then Snit calls the newly created +component's configure method to receive a list of all of the +component's options. From this Snit builds a list of options +implicitly delegated to the component which were not explicitly +included in the install command. For all such options, Snit +queries the option database and configures the component accordingly.

    • +
+

You don't really need to know all of this; just use install to +install your components, and Snit will try to do the right thing.

+
+

What happens if I install a non-widget as a component of widget?

+

A snit::type never queries the option database. +However, a snit::widget can have non-widget components. And if +options are delegated to those components, and if the install +command is used to install those components, then they will be +initialized from the option database just as widget components are.

+

However, when used within a megawidget, install assumes that the +created component uses a reasonably standard widget-like creation +syntax. If it doesn't, don't use install.

+
+
+

ENSEMBLE COMMANDS

+

What is an ensemble command?

+

An ensemble command is a command with subcommands. Snit objects are +all ensemble commands; however, the term more usually refers to +commands like the standard Tcl commands string, file, +and clock. In a sense, these are singleton objects--there's +only one instance of them.

+
+

How can I create an ensemble command using Snit?

+

There are two ways--as a snit::type, or as an instance of +a snit::type.

+
+

How can I create an ensemble command using an instance of a snit::type?

+

Define a type whose INSTANCE METHODS are the subcommands +of your ensemble command. Then, create an instance of the type with +the desired name.

+

For example, the following code uses DELEGATION to create +a work-alike for the standard string command:

+
snit::type ::mynamespace::mystringtype {
+    delegate method * to stringhandler
+    constructor {} {
+        set stringhandler string
+    }
+}
+::mynamespace::mystringtype mystring
+
+

We create the type in a namespace, so that the type command is hidden; +then we create a single instance with the desired name-- +mystring, in this case.

+

This method has two drawbacks. First, it leaves the type command +floating about. More seriously, your shiny new ensemble +command will have info and destroy subcommands that +you probably have no use for. But read on.

+
+

How can I create an ensemble command using a snit::type?

+

Define a type whose TYPE METHODS are the subcommands +of your ensemble command.

+

For example, the following code uses DELEGATION to create +a work-alike for the standard string command:

+
snit::type mystring {
+    delegate typemethod * to stringhandler
+    typeconstructor {
+        set stringhandler string
+    }
+}
+
+

Now the type command itself is your ensemble command.

+

This method has only one drawback, and though it's major, it's +also surmountable. Your new ensemble command will have +create, info and destroy subcommands +you don't want. And worse yet, since the create method +can be implicit, users of your command will accidentally be creating +instances of your mystring type if they should mispell one +of the subcommands. The command will succeed--the first time--but +won't do what's wanted. This is very bad.

+

The work around is to set some PRAGMAS, as shown here:

+
snit::type mystring {
+    pragma -hastypeinfo    no
+    pragma -hastypedestroy no
+    pragma -hasinstances   no
+    delegate typemethod * to stringhandler
+    typeconstructor {
+        set stringhandler string
+    }
+}
+
+

Here we've used the pragma statement to tell Snit that we don't +want the info typemethod or the destroy typemethod, +and that our type has no instances; this eliminates the +create typemethod and all related code. As +a result, our ensemble command will be well-behaved, with no +unexpected subcommands.

+
+
+

PRAGMAS

+

What is a pragma?

+

A pragma is an option you can set in your type definitions that +affects how the type is defined and how it works once it is defined.

+
+

How do I set a pragma?

+

Use the pragma statement. Each pragma is an option with a +value; each time you use the pragma statement you can set one or +more of them.

+
+

How can I get rid of the "info" type method?

+

Set the -hastypeinfo pragma to no:

+
snit::type dog {
+    pragma -hastypeinfo no
+    # ...
+}
+
+

Snit will refrain from defining the info type method.

+
+

How can I get rid of the "destroy" type method?

+

Set the -hastypedestroy pragma to no:

+
snit::type dog {
+    pragma -hastypedestroy no
+    # ...
+}
+
+

Snit will refrain from defining the destroy type method.

+
+

How can I get rid of the "create" type method?

+

Set the -hasinstances pragma to no:

+
snit::type dog {
+    pragma -hasinstances no
+    # ...
+}
+
+

Snit will refrain from defining the create type method; +if you call the type command with an unknown method name, you'll get +an error instead of a new instance of the type.

+

This is useful if you wish to use a snit::type to define +an ensemble command rather than a type with instances.

+

Pragmas -hastypemethods and -hasinstances cannot +both be false (or there'd be nothing left).

+
+

How can I get rid of type methods altogether?

+

Normal Tk widget type commands don't have subcommands; all they do is +create widgets--in Snit terms, the type command calls the +create type method directly. To get the same behavior from +Snit, set the -hastypemethods pragma to no:

+
snit::type dog {
+    pragma -hastypemethods no
+    #...
+}
+# Creates ::spot
+dog spot
+# Tries to create an instance called ::create
+dog create spot
+
+

Pragmas -hastypemethods and -hasinstances cannot +both be false (or there'd be nothing left).

+
+

Why can't I create an object that replaces an old object with the same name?

+

Up until Snit 0.95, you could use any name for an instance of a +snit::type, even if the name was already in use by some other +object or command. You could do the following, for example:

+
snit::type dog { ... }
+dog proc
+
+

You now have a new dog named "proc", which is probably not something +that you really wanted to do. As a result, Snit now throws an error +if your chosen instance name names an existing command. To restore +the old behavior, set the -canreplace pragma to yes:

+
snit::type dog {
+    pragma -canreplace yes
+    # ...
+}
+
+
+

How can I make my simple type run faster?

+

In Snit 1.x, you can set the -simpledispatch pragma to yes.

+

Snit 1.x method dispatch is both flexible and fast, but the flexibility +comes with a price. If your type doesn't require the flexibility, the +-simpledispatch pragma allows you to substitute a simpler +dispatch mechanism that runs quite a bit faster. The limitations +are these:

+
    +

  • Methods cannot be delegated.

    • +

  • uplevel and upvar do not work as expected: the +caller's scope is two levels up rather than one.

    • +

  • The option-handling methods +(cget, configure, and configurelist) are very +slightly slower.

    • +
+

In Snit 2.2, the -simpledispatch macro is obsolete, and +ignored; all Snit 2.2 method dispatch is faster than Snit 1.x's +-simpledispatch.

+
+
+

MACROS

+

What is a macro?

+

A Snit macro is nothing more than a Tcl proc that's defined in the +Tcl interpreter used to compile Snit type definitions.

+
+

What are macros good for?

+

You can use Snit macros to define new type definition syntax, and to +support conditional compilation.

+
+

How do I do conditional compilation?

+

Suppose you want your type to use a fast C extension if it's +available; otherwise, you'll fallback to a slower Tcl implementation. +You want to define one set of methods in the first case, and another +set in the second case. But how can your type definition know whether +the fast C extension is available or not?

+

It's easily done. Outside of any type definition, define a macro that +returns 1 if the extension is available, and 0 otherwise:

+
if {$gotFastExtension} {
+    snit::macro fastcode {} {return 1}
+} else {
+    snit::macro fastcode {} {return 0}
+}
+
+

Then, use your macro in your type definition:

+
snit::type dog {
+    if {[fastcode]} {
+        # Fast methods
+        method bark {} {...}
+        method wagtail {} {...}
+    } else {
+        # Slow methods
+        method bark {} {...}
+        method wagtail {} {...}
+    }
+}
+
+
+

How do I define new type definition syntax?

+

Use a macro. For example, your snit::widget's +-background option should be propagated to a number +of component widgets. You could implement that like this:

+
snit::widget mywidget {
+    option -background -default white -configuremethod PropagateBackground
+    method PropagateBackground {option value} {
+        $comp1 configure $option $value
+        $comp2 configure $option $value
+        $comp3 configure $option $value
+    }
+}
+
+

For one option, this is fine; if you've got a number of options, it +becomes tedious and error prone. So package it as a macro:

+
snit::macro propagate {option "to" components} {
+    option $option -configuremethod Propagate$option
+    set body "\n"
+    foreach comp $components {
+        append body "\$$comp configure $option \$value\n"
+    }
+    method Propagate$option {option value} $body
+}
+
+

Then you can use it like this:

+
snit::widget mywidget {
+    option -background default -white
+    option -foreground default -black
+    propagate -background to {comp1 comp2 comp3}
+    propagate -foreground to {comp1 comp2 comp3}
+}
+
+
+

Are there are restrictions on macro names?

+

Yes, there are. You can't redefine any standard Tcl commands or Snit +type definition statements. You can use any other command name, +including the name of a previously defined macro.

+

If you're using Snit macros in your application, go ahead and name +them in the global namespace, as shown above. But if you're using +them to define types or widgets for use by others, you should define +your macros in the same namespace as your types or widgets. That way, +they won't conflict with other people's macros.

+

If my fancy snit::widget is called ::mylib::mywidget, +for example, then I should define my propagate macro as +::mylib::propagate:

+
snit::macro mylib::propagate {option "to" components} { ... }
+snit::widget ::mylib::mywidget {
+    option -background default -white
+    option -foreground default -black
+    mylib::propagate -background to {comp1 comp2 comp3}
+    mylib::propagate -foreground to {comp1 comp2 comp3}
+}
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category snit of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/soundex/soundex.html Index: embedded/www/tcllib/files/modules/soundex/soundex.html ================================================================== --- embedded/www/tcllib/files/modules/soundex/soundex.html +++ embedded/www/tcllib/files/modules/soundex/soundex.html @@ -0,0 +1,166 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

soundex(n) 1.0 tcllib "Soundex"

+

Name

+

soundex - Soundex

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require soundex ?1.0?
    • +
+ +
+
+

Description

+

This package provides soundex algorithms which allow the +comparison of words based on their phonetic likeness.

+

Currently only an algorithm by Knuth is provided, which +is tuned to english names and words.

+
+
::soundex::knuth string
+

Computes the soundex code of the input string using +Knuth's algorithm and returns it as the result of the +command.

+
+
+

EXAMPLES

+
+    % ::soundex::knuth Knuth
+    K530
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category soundex of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/stooop/stooop.html Index: embedded/www/tcllib/files/modules/stooop/stooop.html ================================================================== --- embedded/www/tcllib/files/modules/stooop/stooop.html +++ embedded/www/tcllib/files/modules/stooop/stooop.html @@ -0,0 +1,294 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

stooop(n) 4.4.1 tcllib "Simple Tcl Only Object Oriented Programming"

+

Name

+

stooop - Object oriented extension.

+
+ + +

Description

+

This package provides commands to extend Tcl in an object oriented +manner, using a familiar C++ like syntax and behaviour. Stooop only +introduces a few new commands: class, new, delete, +virtual and classof. Along with a few coding conventions, +that is basically all you need to know to use stooop. Stooop is meant +to be as simple to use as possible.

+

This manual is very succinct and is to be used as a quick reminder for +the programmer, who should have read the thorough stooop_man.html +HTML documentation at this point.

+
+
::stooop::class name body
+

This command creates a class. The body, similar in contents to a Tcl +namespace (which a class actually also is), contains member procedure +definitions. Member procedures can also be defined outside the class +body, by prefixing their name with class::, as you would +proceed with namespace procedures.

+
+
proc class {this ?arg arg ...?} ?base {?arg arg ...?} ...? body
+

This is the constructor procedure for the class. It is invoked +following a new invocation on the class. It must have the same +name as the class and a first argument named this. Any number +of base classes specifications, including arguments to be passed to +their constructor, are allowed before the actual body of the +procedure.

+
proc ~class {this} body
+

This is the destructor procedure for the class. It is invoked +following a delete invocation. Its name must be the +concatenation of a single ~ character followed by the class +name (as in C++). It must have a single argument named this.

+
proc name {this ?arg arg ...?} body
+

This is a member procedure of the class, as its first argument is +named this. It allows a simple access of member data for the +object referenced by this inside the procedure. For example:

+
+   set ($this,data) 0
+
+
+
proc name {?arg arg ...?} body
+

This is a static (as in C++) member procedure of the class, as its +first argument is not named this. Static (global) class data +can be accessed as in:

+
+   set (data) 0
+
+
+
proc class {this copy} body
+

This is the optional copy procedure for the class. It must have the +same name as the class and exactly 2 arguments named this and +copy. It is invoked following a new invocation on an +existing object of the class.

+
+
::stooop::new class ?arg arg ...?
+

This command is used to create an object. The first argument is the +class name and is followed by the arguments needed by the +corresponding class constructor. A unique identifier for the object +just created is returned.

+
::stooop::delete object ?object ...?
+

This command is used to delete one or several objects. It takes one or +more object identifiers as argument(s).

+
::stooop::virtual proc name {this ?arg arg ...?} ?body?
+

The virtual specifier may be used on member procedures to +achieve dynamic binding. A procedure in a base class can then be +redefined (overloaded) in the derived class(es). If the base class +procedure is invoked on an object, it is actually the derived class +procedure which is invoked, if it exists. If the base class procedure +has no body, then it is considered to be a pure virtual and the +derived class procedure is always invoked.

+
::stooop::classof object
+

This command returns the class of the existing object passed as single +parameter.

+
::stooop::new object
+

This command is used to create an object by copying an existing +object. The copy constructor of the corresponding class is invoked if +it exists, otherwise a simple copy of the copied object data members +is performed.

+
+
+

DEBUGGING

+
+
Environment variables
+
+
STOOOPCHECKDATA
+

Setting this variable to any true value will cause stooop to check for +invalid member or class data access.

+
STOOOPCHECKPROCEDURES
+

Setting this variable to any true value will cause stooop to check for +invalid member procedure arguments and pure interface classes +instanciation.

+
STOOOPCHECKALL
+

Setting this variable to any true value will cause stooop to activate +both procedure and data member checking.

+
STOOOPCHECKOBJECTS
+

Setting this variable to any true value will cause stooop to activate +object checking. The following stooop namespace procedures then become +available for debugging: printObjects, record and +report.

+
STOOOPTRACEPROCEDURES
+

Setting this environment variable to either stdout, +stderr or a file name, activates procedure tracing. The +stooop library will then output to the specified channel 1 line of +informational text for each member procedure invocation.

+
STOOOPTRACEPROCEDURESFORMAT
+

Defines the trace procedures output format. Defaults to +"class: %C, procedure: %p, object: %O, arguments: %a".

+
STOOOPTRACEDATA
+

Setting this environment variable to either stdout, +stderr or a file name, activates data tracing. The stooop +library will then output to the specified channel 1 line of +informational text for each member data access.

+
STOOOPTRACEDATAFORMAT
+

Defines the trace data output format. Defaults to +"class: %C, procedure: %p, array: %A, object: %O, member: %m, operation: %o, value: %v".

+
STOOOPTRACEDATAOPERATIONS
+

When tracing data output, by default, all read, write and unsetting +accesses are reported, but the user can set this variable to any +combination of the letters r, w, and u for +more specific tracing (please refer to the trace Tcl manual page +for more information).

+
STOOOPTRACEALL
+

Setting this environment variable to either stdout, +stderr or a file name, enables both procedure and data +tracing.

+
+
::stooop::printObjects ?pattern?
+

Prints an ordered list of existing objects, in creation order, oldest +first. Each output line contains the class name, object identifier and +the procedure within which the creation occurred. The optional pattern +argument (as in the Tcl string match command) can be used to +limit the output to matching class names.

+
::stooop::record
+

When invoked, a snapshot of all existing stooop objects is +taken. Reporting can then be used at a later time to see which objects +were created or deleted in the interval.

+
::stooop::report ?pattern?
+

Prints the created and deleted objects since the ::stooop::record +procedure was invoked last. If present, the pattern argument limits +the output to matching class names.

+
+
+

EXAMPLES

+

Please see the full HTML documentation in stooop_man.html.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stooop of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/stooop/switched.html Index: embedded/www/tcllib/files/modules/stooop/switched.html ================================================================== --- embedded/www/tcllib/files/modules/stooop/switched.html +++ embedded/www/tcllib/files/modules/stooop/switched.html @@ -0,0 +1,371 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

switched(n) 2.2.1 tcllib "Simple Tcl Only Object Oriented Programming"

+

Name

+

switched - switch/option management.

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require switched ?2.2.1?
    • +
+ +
+
+

Description

+

The switched class serves as base class for user classes with +switch / option configuration procedures. It provides facilities for +managing options through a simple interface.

+

For example:

+
+set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
+puts "my car was running on [switched::cget $vehicle -fuel]"
+switched::configure $vehicle -power 40 -fuel electricity
+puts "but is now running on clean [switched::cget $vehicle -fuel]"
+
+

Of course, as you might have guessed, the car class is +derived from the switched class. Let us see how it works:

+
+class car {
+    proc car {this args} switched {$args} {
+        # car specific initialization code here
+        switched::complete $this
+    }
+    ...
+}
+
+

The switched class constructor takes the optional configuration +option / value pairs as parameters. +The switched class layer then completely manages the switched options: +it checks their validity, stores their values and provides a clean +interface to the user layer configuration setting procedures.

+

The switched class members available to the programmer are:

+
+
<switched> complete this
+

This procedure is used to tell the switched layer that the derived +class object (a car in the examples) is completely built. +At that time, the initial configuration of the switched object occurs, +using default option values (see procedure options) +eventually overridden by construction time values, passed at the time +of the new operator invocation. +This procedure must be called only once, usually around or at the end +of the derived class constructor. +(Note: Also check the complete data member later in this +chapter).

+
<switched> options this
+

This procedure must return the configuration description for +all options that the switched object will accept. +It is a pure virtual member procedure and therefore its implementation +is mandatory in the derived class layer. +The procedure must return a list of lists. +Each list pertains to a single option and is composed of the switch +name, the default value for the option and an optional initial value. +For example:

+
+class car {
+    ...
+    proc options {this} {
+        return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
+    }
+    proc set-fuel {this value} {
+        ...
+    }
+    ...
+}
+
+

In this case, 4 options are specified: +fuel, length, power and width. +The default and initial values for the fuel option are +identical and set to petrol. +For the other options, values are all empty.

+

For each option, there must be a corresponding +set-option procedure defined in the derived class +layer. +For example, since we defined a fuel option, there is a +set-fuel procedure in the car class. +The parameters always are the object identifier (since this is not a +static procedure, but rather a dynamically defined virtual one), +followed by the new value for the option. +A set-option procedure is only invoked if the new +value differs from the current one (a caching scheme for improving +performance), or if there is no initial value set in the +options procedure for that option.

+

In this procedure, if the initial value differs from the +default value or is omitted, then initial configuration is forced and +the corresponding set-option procedure is invoked by +the switched complete procedure located at the end of the +derived class constructor. +For example:

+
+class car {
+    ...
+    proc options {this} {
+        return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
+    }
+    ...
+}
+
+

In this case, configuration is forced on the fuel and +power options, that is the corresponding +set-option procedures will be invoked when the +switched object is constructed (see set-option +procedures documentation below).

+

For the fuel option, since there is no initial value, +the set-fuel procedure is called with the default +value (petrol) as argument. +For the power option, since the initial value differs from +the default value, the set-power procedure is called +with the initial value as argument (50).

+

For the other options, since the initial values (last elements +of the option lists) are identical to their default values, the +corresponding set-option procedures will not be +invoked. It is the programmer's responsibility to insure that the +initial option values are correct.

+
<switched> set-option this value
+

These procedures may be viewed as dynamic virtual functions. +There must be one implementation per supported option, as returned by +the options procedure. +For example:

+
+class car {
+    ...
+    proc options {this} {
+        return [list ...
+            [list -width {} {}] ]
+    }
+    ...
+    proc set-width {this value} {
+        ...
+    }
+    ...
+}
+
+

Since the -width option was listed in the options +procedure, a set-width procedure implementation is provided, which +of course would proceed to set the width of the car (and would modify +the looks of a graphical representation, for example).

+

As you add a supported option in the list returned by +the options procedure, the corresponding +set-option procedure may be called as soon as the +switched object is complete, which occurs when the switched level +complete procedure is invoked. +For example:

+
+class car {
+    proc car {this args} switched {args} {
+        ...
+        switched::complete $this
+   }
+    ...
+    proc options {this} {
+        return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
+    }
+    proc set-fuel {this value} {
+        ...
+    }
+    proc set-length {this value} {
+        ...
+    }
+    proc set-power {this value} {
+        ...
+    }
+    proc set-width {this value} {
+        ...
+    }
+}
+new car
+
+

In this case, a new car is created with no options, which +causes the car constructor to be called, which in turns calls the +switched level complete procedure after the car object layer +is completely initialized. +At this point, since there are no initial values in any option list in +the options procedure, the set-fuel procedure is called with +its default value of petrol as parameter, followed by the +set-length call with 4.5 value, set-power +with 350 value and finally with set-width with +1.8 as parameter. +This is a good way to test the set-option procedures +when debugging, and when done, just fill-in the initial option values.

+

The switched layer checks that an option is valid (that is, +listed in the options procedure) but obviously does not check +the validity of the value passed to the set-option +procedure, which should throw an error (for example by using the Tcl +error command) if the value is invalid.

+

The switched layer also keeps track of the options current +values, so that a set-option procedure is called +only when the corresponding option value passed as parameter is +different from the current value (see data members +description).

+
+

The data member is an options current value. +There is one for each option listed in the options procedure. It is a +read-only value which the switched layer checks against when an option +is changed. +It is rarely used at the layer derived from switched, except in the +few cases, such as in the following example:

+
+...
+proc car::options {this} {
+    return {
+        ...
+        {-manufacturer {} {}}
+        ...
+    }
+}
+proc car::set-manufacturer {this value} {}
+proc car::printData {this} {
+    puts "manufacturer: $switched::($this,-manufacturer)"
+    ...
+}
+
+

In this case, the manufacturer's name is stored at the switched +layer level (this is why the set-manufacturer procedure has nothing to +do) and later retrieved in the printData procedure.

+
+

The data member (not to be confused with +the complete procedure) is a boolean. +Its initial value is false and it is set to true at +the very end of the switched complete procedure. +It becomes useful when some options should be set at construction time +only and not dynamically, as the following example shows:

+
+proc car::set-width {this value} {
+    if {$switched::($this,complete)} {
+        error {option -width cannot be set dynamically}
+    }
+    ...
+}
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stooop of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+
ADDED embedded/www/tcllib/files/modules/string/token.html Index: embedded/www/tcllib/files/modules/string/token.html ================================================================== --- embedded/www/tcllib/files/modules/string/token.html +++ embedded/www/tcllib/files/modules/string/token.html @@ -0,0 +1,203 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

string::token(n) 1 tcllib "Text and string utilities"

+

Name

+

string::token - Regex based iterative lexing

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require string::token ?1?
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides commands for regular expression based lexing +(tokenization) of strings.

+

The complete set of procedures is described below.

+
+
::string token text lex string
+

This command takes an ordered dictionary lex mapping regular +expressions to labels, and tokenizes the string according to +this dictionary.

+

The result of the command is a list of tokens, where each token +is a 3-element list of label, start- and end-index in the string.

+

The command will throw an error if it is not able to tokenize +the whole string.

+
::string token file lex path
+

This command is a convenience wrapper around +::string token text above, and fileutil::cat, enabling +the easy tokenization of whole files. +Note that this command loads the file wholly into memory before +starting to process it.

+

If the file is too large for this mode of operation a command +directly based on ::string token chomp below will be +necessary.

+
::string token chomp lex startvar string resultvar
+

This command is the work horse underlying ::string token text +above. It is exposed to enable users to write their own lexers, which, +for example may apply different lexing dictionaries according to some +internal state, etc.

+

The command takes an ordered dictionary lex mapping +regular expressions to labels, a variable startvar which +indicates where to start lexing in the input string, and a +result variable resultvar to extend.

+

The result of the command is a tri-state numeric code +indicating one of

+
+
0
+

No token found.

+
1
+

Token found.

+
2
+

End of string reached.

+
+

Note that recognition of a token from lex is started at the +character index in startvar.

+

If a token was recognized (status 1) the command will +update the index in startvar to point to the first character of +the string past the recognized token, and it will further extend +the resultvar with a 3-element list containing the label +associated with the regular expression of the token, and the start- +and end-character-indices of the token in string.

+

Neither startvar nor resultvar will be updated if +no token is recognized at all.

+

Note that the regular expressions are applied (tested) in the +order they are specified in lex, and the first matching pattern +stops the process. Because of this it is recommended to specify the +patterns to lex with from the most specific to the most general.

+

Further note that all regex patterns are implicitly prefixed +with the constraint escape A to ensure that a match starts +exactly at the character index found in startvar.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/string/token_shell.html Index: embedded/www/tcllib/files/modules/string/token_shell.html ================================================================== --- embedded/www/tcllib/files/modules/string/token_shell.html +++ embedded/www/tcllib/files/modules/string/token_shell.html @@ -0,0 +1,227 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

string::token::shell(n) 1.2 tcllib "Text and string utilities"

+

Name

+

string::token::shell - Parsing of shell command line

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require string::token::shell ?1.2?
    • +
  • package require string::token ?1?
    • +
  • package require fileutil
    • +
+ +
+
+

Description

+

This package provides a command which parses a line of text using +basic sh-syntax into a list of words.

+

The complete set of procedures is described below.

+
+
::string token shell ?-indices? ?-partial? ?--? string
+

This command parses the input string under the assumption of it +following basic sh-syntax. +The result of the command is a list of words in the string. +An error is thrown if the input does not follow the allowed syntax. +The behaviour can be modified by specifying any of the two options +-indices and -partial.

+
+
--
+

When specified option parsing stops at this point. This option is +needed if the input string may start with dash. In other words, +this is pretty much required if string is user input.

+
-indices
+

When specified the output is not a list of words, but a list of +4-tuples describing the words. Each tuple contains the type of the +word, its start- and end-indices in the input, and the actual text of +the word.

+

Note that the length of the word as given by the indices can +differ from the length of the word found in the last element of the +tuple. The indices describe the words extent in the input, including +delimiters, intra-word quoting, etc. whereas for the actual text of +the word delimiters are stripped, intra-word quoting decoded, etc.

+

The possible token types are

+
+
PLAIN
+

Plain word, not quoted.

+
D:QUOTED
+

Word is delimited by double-quotes.

+
S:QUOTED
+

Word is delimited by single-quotes.

+
D:QUOTED:PART
+
+
S:QUOTED:PART
+

Like the previous types, but the word has no closing quote, i.e. is +incomplete. These token types can occur if and only if the option +-partial was specified, and only for the last word of the +result. If the option -partial was not specified such +incomplete words cause the command to thrown an error instead.

+
+
-partial
+

When specified the parser will accept an incomplete quoted word +(i.e. without closing quote) at the end of the line as valid instead +of throwing an error.

+
+

The basic shell syntax accepted here are unquoted, single- and +double-quoted words, separated by whitespace. Leading and trailing +whitespace are possible too, and stripped. +Shell variables in their various forms are not recognized, nor +are sub-shells. +As for the recognized forms of words, see below for the detailed +specification.

+
+
single-quoted word
+

A single-quoted word begins with a single-quote character, i.e. +' (ASCII 39) followed by zero or more unicode characters not a +single-quote, and then closed by a single-quote.

+

The word must be followed by either the end of the string, or +whitespace. A word cannot directly follow the word.

+
double-quoted word
+

A double-quoted word begins with a double-quote character, i.e. +" (ASCII 34) followed by zero or more unicode characters not a +double-quote, and then closed by a double-quote.

+

Contrary to single-quoted words a double-quote can be embedded +into the word, by prefacing, i.e. escaping, i.e. quoting it with a +backslash character \ (ASCII 92). Similarly a backslash +character must be quoted with itself to be inserted literally.

+
unquoted word
+

Unquoted words are not delimited by quotes and thus cannot contain +whitespace or single-quote characters. Double-quote and backslash +characters can be put into unquoted words, by quting them like for +double-quoted words.

+
whitespace
+

Whitespace is any unicode space character. +This is equivalent to string is space, or the regular +expression \\s.

+

Whitespace may occur before the first word, or after the last word. Whitespace must occur between adjacent words.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/stringprep/stringprep.html Index: embedded/www/tcllib/files/modules/stringprep/stringprep.html ================================================================== --- embedded/www/tcllib/files/modules/stringprep/stringprep.html +++ embedded/www/tcllib/files/modules/stringprep/stringprep.html @@ -0,0 +1,224 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

stringprep(n) 1.0.1 tcllib "Preparation of Internationalized Strings"

+

Name

+

stringprep - Implementation of stringprep

+
+ + +

Description

+

This is an implementation in Tcl of the Preparation of Internationalized +Strings ("stringprep"). It allows to define stringprep profiles and use +them to prepare Unicode strings for comparison as defined in RFC-3454.

+
+

COMMANDS

+
+
::stringprep::register profile ?-mapping list? ?-normalization form? ?-prohibited list? ?-prohibitedList list? ?-prohibitedCommand command? ?-prohibitedBidi boolean?
+

Register the stringprep profile named profile. Options +are the following.

+

Option -mapping specifies stringprep mapping tables. +This parameter takes list of tables from appendix B of RFC-3454. The usual +list values are {B.1 B.2} or {B.1 B.3} where B.1 contains characters which +commonly map to nothing, B.3 specifies case folding, and B.2 is used in +profiles with unicode normalization form KC. Defult value is {} which means +no mapping.

+

Option -normalization takes a string and if it is nonempty then it +uses as a name of Unicode normalization form. Any value of "D", "C", "KD" +or "KC" may be used, though RFC-3454 defines only two options: no +normalization or normalization using form KC.

+

Option -prohibited takes a list of RFC-3454 tables with prohibited +characters. Current version does allow to prohibit either all tables from +C.3 to C.9 or neither of them. An example of this list for RFC-3491 is +{A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}.

+

Option -prohibitedList specifies a list of additional prohibited +characters. The list contains not characters themselves but their Unicode +numbers. For example, Nodeprep specification from RFC-3920 forbids the +following codes: {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40} (\" \& \' / : < > @).

+

Option -prohibitedCommand specifies a command which is called for +every character code in mapped and normalized string. If the command returns +true then the character is considered prohibited. This option is useful when +a list for -prohibitedList is too large.

+

Option -prohibitedBidi takes boolean value and if it is true then the +bidirectional character processing rules defined in section 6 of RFC-3454 are +used.

+
::stringprep::stringprep profile string
+

Performs stringprep operations defined in profile profile +to string string. Result is a prepared string or one of the following +errors: invalid_profile (profile profile is not defined), +prohibited_character (string string contains a prohibited character) +or prohibited_bidi (string string contains a prohibited bidirectional +sequence).

+
::stringprep::compare profile string1 string2
+

Compares two unicode strings prepared accordingly to stringprep +profile profile. The command returns 0 if prepared strings are equal, +-1 if string1 is lexicographically less than string2, or +1 if string1 is lexicographically greater than string2.

+
+
+

EXAMPLES

+

Nameprep profile definition (see RFC-3491):

+
+::stringprep::register nameprep  -mapping {B.1 B.2}  -normalization KC  -prohibited {A.1 C.1.2 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedBidi 1
+
+

Nodeprep and resourceprep profile definitions (see RFC-3920):

+
+::stringprep::register nodeprep  -mapping {B.1 B.2}  -normalization KC  -prohibited {A.1 C.1.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedList {0x22 0x26 0x27 0x2f 0x3a 0x3c 0x3e 0x40}  -prohibitedBidi 1
+::stringprep::register resourceprep  -mapping {B.1}  -normalization KC  -prohibited {A.1 C.1.2 C.2.1 C.2.2 C.3 C.4 C.5 C.6 C.7 C.8 C.9}  -prohibitedBidi 1
+
+
+

REFERENCES

+
    +

  1. "Preparation of Internationalized Strings ('stringprep')", + (http://www.ietf.org/rfc/rfc3454.txt)

    2. +

  2. "Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)", + (http://www.ietf.org/rfc/rfc3491.txt)

    3. +

  3. "Extensible Messaging and Presence Protocol (XMPP): Core", + (http://www.ietf.org/rfc/rfc3920.txt)

    4. +
+
+

AUTHORS

+

Sergei Golovan

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/stringprep/stringprep_data.html Index: embedded/www/tcllib/files/modules/stringprep/stringprep_data.html ================================================================== --- embedded/www/tcllib/files/modules/stringprep/stringprep_data.html +++ embedded/www/tcllib/files/modules/stringprep/stringprep_data.html @@ -0,0 +1,145 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

stringprep::data(n) 1.0.1 tcllib "Preparation of Internationalized Strings"

+

Name

+

stringprep::data - stringprep data tables, generated, internal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require stringprep::data 1.0.1
    • +
+
+
+

Description

+

The stringprep::data package is a helper for +stringprep, providing it with the data tables needed to +perform its functions. It is an internal package which should +not be accessed on its own. Because of that it has no publicly +documented API either. Its implementation is generated by a script.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/stringprep/unicode.html Index: embedded/www/tcllib/files/modules/stringprep/unicode.html ================================================================== --- embedded/www/tcllib/files/modules/stringprep/unicode.html +++ embedded/www/tcllib/files/modules/stringprep/unicode.html @@ -0,0 +1,199 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

unicode(n) 1.0.0 tcllib "Unicode normalization"

+

Name

+

unicode - Implementation of Unicode normalization

+
+ + +

Description

+

This is an implementation in Tcl of the Unicode normalization forms.

+
+

COMMANDS

+
+
::unicode::fromstring string
+

Converts string to list of integer Unicode character codes which +is used in unicode for internal string representation.

+
::unicode::tostring uclist
+

Converts list of integers uclist back to Tcl string.

+
::unicode::normalize form uclist
+

Normalizes Unicode characters list ulist according to form +and returns the normalized list. Form form takes one of the following +values: D (canonical decomposition), C (canonical decomposition, followed +by canonical composition), KD (compatibility decomposition), or KC +(compatibility decomposition, followed by canonical composition).

+
::unicode::normalizeS form string
+

A shortcut to +::unicode::tostring [unicode::normalize \$form [::unicode::fromstring \$string]]. +Normalizes Tcl string and returns normalized string.

+
+
+

EXAMPLES

+
+% ::unicode::fromstring "\u0410\u0411\u0412\u0413"
+1040 1041 1042 1043
+% ::unicode::tostring {49 50 51 52 53}
+12345
+%
+
+
+% ::unicode::normalize D {7692 775}
+68 803 775
+% ::unicode::normalizeS KD "\u1d2c"
+A
+%
+
+
+

REFERENCES

+
    +

  1. "Unicode Standard Annex #15: Unicode Normalization Forms", + (http://unicode.org/reports/tr15/)

    2. +
+
+

AUTHORS

+

Sergei Golovan

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/stringprep/unicode_data.html Index: embedded/www/tcllib/files/modules/stringprep/unicode_data.html ================================================================== --- embedded/www/tcllib/files/modules/stringprep/unicode_data.html +++ embedded/www/tcllib/files/modules/stringprep/unicode_data.html @@ -0,0 +1,145 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

unicode::data(n) 1.0.0 tcllib "Preparation of Internationalized Strings"

+

Name

+

unicode::data - unicode data tables, generated, internal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require unicode::data 1.0.0
    • +
+
+
+

Description

+

The unicode::data package is a helper for +unicode, providing it with the data tables needed to +perform its functions. It is an internal package which should +not be accessed on its own. Because of that it has no publicly +documented API either. Its implementation is generated by a script.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category stringprep of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/struct/disjointset.html Index: embedded/www/tcllib/files/modules/struct/disjointset.html ================================================================== --- embedded/www/tcllib/files/modules/struct/disjointset.html +++ embedded/www/tcllib/files/modules/struct/disjointset.html @@ -0,0 +1,241 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::disjointset(n) 1.0 tcllib "Tcl Data Structures"

+

Name

+

struct::disjointset - Disjoint set data structure

+
+ + +

Description

+

This package provides disjoint sets. An alternative name for +this kind of structure is merge-find.

+

Normally when dealing with sets and their elements the question is "Is +this element E contained in this set S?", with both E and S known.

+

Here the question is "Which of several sets contains the element +E?". I.e. while the element is known, the set is not, and we wish to +find it quickly. It is not quite the inverse of the original question, +but close. +Another operation which is often wanted is that of quickly merging two +sets into one, with the result still fast for finding elements. Hence +the alternative term merge-find for this.

+

Why now is this named a disjoint-set ? +Because another way of describing the whole situation is that we have

+
    +

  • a finite set S, containing

    • +

  • a number of elements E, split into

    • +

  • a set of partitions P. The latter term + applies, because the intersection of each pair P, P' of + partitions is empty, with the union of all partitions + covering the whole set.

    • +

  • An alternative name for the partitions would be + equvalence classes, and all elements in the same + class are considered as equal.

    • +
+

Here is a pictorial representation of the concepts listed above:

+
+	+-----------------+ The outer lines are the boundaries of the set S.
+	|           /     | The inner regions delineated by the skewed lines
+	|  *       /   *  | are the partitions P. The *'s denote the elements
+	|      *  / \     | E in the set, each in a single partition, their
+	|*       /   \    | equivalence class.
+	|       /  *  \   |
+	|      / *   /    |
+	| *   /\  * /     |
+	|    /  \  /      |
+	|   /    \/  *    |
+	|  / *    \       |
+	| /     *  \      |
+	+-----------------+
+
+

For more information see http://en.wikipedia.org/wiki/Disjoint_set_data_structure.

+
+

API

+

The package exports a single command, ::struct::disjointset. All +functionality provided here can be reached through a subcommand of +this command.

+
+
::struct::disjointset disjointsetName
+

Creates a new disjoint set object with an associated global Tcl +command whose name is disjointsetName. This command may be used +to invoke various operations on the disjointset. It has the following +general form:

+
+
disjointsetName option ?arg arg ...?
+

The option and the args determine the exact behavior of +the command. The following commands are possible for disjointset +objects:

+
+
disjointsetName add-partition elements
+

Creates a new partition in specified disjoint set, and fills it with +the values found in the set of elements. The command maintains +the integrity of the disjoint set, i.e. it verifies that none of the +elements are already part of the disjoint set and throws an +error otherwise.

+

The result of the command is the empty string.

+
disjointsetName partitions
+

Returns the set of partitions the named disjoint set currently +consists of.

+
disjointsetName num-partitions
+

Returns the number of partitions the named disjoint set currently +consists of.

+
disjointsetName equal a b
+

Determines if the two elements a and b of the disjoint set +belong to the same partition. The result of the method is a boolean +value, True if the two elements are contained in the same +partition, and False otherwise.

+

An error will be thrown if either a or b are not elements +of the disjoint set.

+
disjointsetName merge a b
+

Determines the partitions the elements a and b are +contained in and merges them into a single partition. If the two +elements were already contained in the same partition nothing will +change.

+

The result of the method is the empty string.

+
disjointsetName find e
+

Returns the partition of the disjoint set which contains the element +e.

+
disjointsetName destroy
+

Destroys the disjoint set object and all associated memory.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: disjointset of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/graph.html Index: embedded/www/tcllib/files/modules/struct/graph.html ================================================================== --- embedded/www/tcllib/files/modules/struct/graph.html +++ embedded/www/tcllib/files/modules/struct/graph.html @@ -0,0 +1,779 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::graph(n) 2.4 tcllib "Tcl Data Structures"

+

Name

+

struct::graph - Create and manipulate directed graph objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require struct::graph ?2.4?
    • +
  • package require struct::list ?1.5?
    • +
  • package require struct::set ?2.2.3?
    • +
+ +
+
+

Description

+

A directed graph is a structure containing two collections of +elements, called nodes and arcs respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs.

+

Each arc is connected to two nodes, one of which is called the +source and the other the target. This imposes a +direction upon the arc, which is said to go from the source to the +target. It is allowed that source and target of an arc are the same +node. Such an arc is called a loop. +Whenever a node is either the source or target of an arc both are said +to be adjacent. This extends into a relation between nodes, +i.e. if two nodes are connected through at least one arc they are said +to be adjacent too.

+

Each node can be the source and target for any number of arcs. The +former are called the outgoing arcs of the node, the latter +the incoming arcs of the node. The number of arcs in either +set is called the in-degree resp. the out-degree of the +node.

+

In addition to maintaining the node and arc relationships, this graph +implementation allows any number of named attributes to be +associated with the graph itself, and each node or arc.

+

Note: The major version of the package struct has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +Changes for 2.0 for a full list of all changes, +incompatible and otherwise.

+

Note: A C-implementation of the command can be had from the +location http://www.purl.org/NET/schlenker/tcl/cgraph. See also +http://wiki.tcl.tk/cgraph. This implementation uses a bit less +memory than the tcl version provided here directly, and is faster. Its +support is limited to versions of the package before 2.0.

+

As of version 2.2 of this package a critcl based C implementation is +available from here as well. This implementation however requires Tcl +8.4 to run.

+

The main command of the package is:

+
+
::struct::graph ?graphName? ?=|:=|as|deserialize source?
+

The command creates a new graph object with an associated global Tcl +command whose name is graphName. This command may be used to +invoke various operations on the graph. It has the following general +form:

+
+
graphName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If graphName is not specified a unique name will be generated by +the package itself. If a source is specified the new graph will +be initialized to it. For the operators =, :=, and +as the source argument is interpreted as the name of +another graph object, and the assignment operator = will be +executed. For the operator deserialize the source is a +serialized graph object and deserialize will be executed.

+

In other words

+
+    ::struct::graph mygraph = b
+
+

is equivalent to

+
+    ::struct::graph mygraph
+    mygraph = b
+
+

and

+
+    ::struct::graph mygraph deserialize $b
+
+

is equivalent to

+
+    ::struct::graph mygraph
+    mygraph deserialize $b
+
+
+
+

The following commands are possible for graph objects:

+
+
graphName = sourcegraph
+

This is the assignment operator for graph objects. It copies +the graph contained in the graph object sourcegraph over the +graph data in graphName. The old contents of graphName are +deleted by this operation.

+

This operation is in effect equivalent to

+
+    graphName deserialize [sourcegraph serialize]
+
+

The operation assumes that the sourcegraph provides the method +serialize and that this method returns a valid graph +serialization.

+
graphName --> destgraph
+

This is the reverse assignment operator for graph objects. It +copies the graph contained in the graph object graphName over +the graph data in the object destgraph. +The old contents of destgraph are deleted by this operation.

+

This operation is in effect equivalent to

+
+    destgraph deserialize [graphName serialize]
+
+

The operation assumes that the destgraph provides the method +deserialize and that this method takes a graph serialization.

+
graphName append key value
+

Appends a value to one of the keyed values associated with the graph. +Returns the new value given to the attribute key.

+
graphName deserialize serialization
+

This is the complement to serialize. It replaces the graph +data in graphName with the graph described by the +serialization value. The old contents of graphName are +deleted by this operation.

+
graphName destroy
+

Destroys the graph, including its storage space and associated command.

+
graphName arc append arc key value
+

Appends a value to one of the keyed values associated with an +arc. Returns the new value given to the attribute key.

+
graphName arc attr key
+
+
graphName arc attr key -arcs list
+
+
graphName arc attr key -glob globpattern
+
+
graphName arc attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all arcs in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from arc names to the value of +attribute key at that arc. +Arcs not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-arcs
+

The value is a list of arcs. Only the arcs mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the arcs in the graph whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the arcs in the graph whose +names match this pattern are searched for the attribute.

+
+
graphName arc delete arc ?arc ...?
+

Remove the specified arcs from the graph.

+
graphName arc exists arc
+

Return true if the specified arc exists in the graph.

+
graphName arc flip arc
+

Reverses the direction of the named arc, i.e. the source and +target nodes of the arc are exchanged with each other.

+
graphName arc get arc key
+

Returns the value associated with the key key for the arc.

+
graphName arc getall arc ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the arc. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName arc getunweighted
+

Returns a list containing the names of all arcs in the graph which +have no weight associated with them.

+
graphName arc getweight arc
+

Returns the weight associated with the arc. Throws an error if +the arc has no weight associated with it.

+
graphName arc keys arc ?pattern?
+

Returns a list of keys for the arc. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName arc keyexists arc key
+

Return true if the specified key exists for the arc.

+
graphName arc insert start end ?child?
+

Insert an arc named child into the graph beginning at the node +start and ending at the node end. If the name of the new +arc is not specified the system will generate a unique name of the +form arcx.

+
graphName arc lappend arc key value
+

Appends a value (as a list) to one of the keyed values +associated with an arc. Returns the new value given to the +attribute key.

+
graphName arc rename arc newname
+

Renames the arc arc to newname. An error is thrown if +either the arc does not exist, or a arc with name newname does +exist. The result of the command is the new name of the arc.

+
graphName arc set arc key ?value?
+

Set or get one of the keyed values associated with an arc. +An arc may have any number of keyed values associated with it. +If value is not specified, this command returns the current value assigned to the key; +if value is specified, this command assigns that value to the key, and returns +that value.

+
graphName arc setunweighted ?weight?
+

Sets the weight of all arcs without a weight to weight. Returns +the empty string as its result. If not present weight defaults +to 0.

+
graphName arc setweight arc weight
+

Sets the weight of the arc to weight. Returns weight.

+
graphName arc unsetweight arc
+

Removes the weight of the arc, if present. Does nothing +otherwise. Returns the empty string.

+
graphName arc hasweight arc
+

Determines if the arc has a weight associated with it. The +result is a boolean value, True if a weight is defined, and +False otherwise.

+
graphName arc source arc
+

Return the node the given arc begins at.

+
graphName arc target arc
+

Return the node the given arc ends at.

+
graphName arc nodes arc
+

Return the nodes the given arc begins and ends at, +as a two-element list.

+
graphName arc move-source arc newsource
+

Changes the source node of the arc to newsource. It can be said +that the arc rotates around its target node.

+
graphName arc move-target arc newtarget
+

Changes the target node of the arc to newtarget. It can be said +that the arc rotates around its source node.

+
graphName arc move arc newsource newtarget
+

Changes both source and target nodes of the arc to newsource, +and newtarget resp.

+
graphName arc unset arc key
+

Remove a keyed value from the arc arc. The method will do +nothing if the key does not exist.

+
graphName arc weights
+

Returns a dictionary whose keys are the names of all arcs which have a +weight associated with them, and the values are these weights.

+
graphName arcs ?-key key? ?-value value? ?-filter cmdprefix? ?-in|-out|-adj|-inner|-embedding node node...?
+

Returns a list of arcs in the graph. If no restriction is specified a +list containing all arcs is returned. Restrictions can limit the list +of returned arcs based on the nodes that are connected by the arc, on +the keyed values associated with the arc, or both. A general filter +command can be used as well. The restrictions that involve connected +nodes take a variable number of nodes as argument, specified after the +name of the restriction itself.

+

The restrictions imposed by either -in, -out, +-adj, -inner, or -embedded are applied +first. Specifying more than one of them is illegal.

+

After that the restrictions set via -key (and +-value) are applied. Specifying more than one -key +(and -value) is illegal. Specifying -value alone, +without -key is illegal as well.

+

Any restriction set through -filter is applied +last. Specifying more than one -filter is illegal.

+

Coming back to the restrictions based on a set of nodes, the command +recognizes the following switches:

+
+
-in
+

Return a list of all arcs whose target is one of the nodes in the set +of nodes. I.e. it computes the union of all incoming arcs of the nodes +in the set.

+
-out
+

Return a list of all arcs whose source is one of the nodes in the set +of nodes. I.e. it computes the union of all outgoing arcs of the nodes +in the set.

+
-adj
+

Return a list of all arcs adjacent to at least one of the nodes in the +set. This is the union of the nodes returned by -in and +-out.

+
-inner
+

Return a list of all arcs which are adjacent to two of the nodes in +the set. This is the set of arcs in the subgraph spawned by the +specified nodes.

+
-embedding
+

Return a list of all arcs adjacent to exactly one of the nodes in the +set. This is the set of arcs connecting the subgraph spawned by the +specified nodes to the rest of the graph.

+
-key key
+

Limit the list of arcs that are returned to those arcs that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of arcs that are returned to those +arcs whose associated key key has the value value.

+
-filter cmdrefix
+

Limit the list of arcs that are returned to those arcs that pass the +test. The command in cmdprefix is called with two arguments, the +name of the graph object, and the name of the arc in question. It is +executed in the context of the caller and has to return a boolean +value. Arcs for which the command returns false are removed +from the result list before it is returned to the caller.

+
+
graphName lappend key value
+

Appends a value (as a list) to one of the keyed values +associated with the graph. Returns the new value given to the +attribute key.

+
graphName node append node key value
+

Appends a value to one of the keyed values associated with an +node. Returns the new value given to the attribute key.

+
graphName node attr key
+
+
graphName node attr key -nodes list
+
+
graphName node attr key -glob globpattern
+
+
graphName node attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all nodes in the graph (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from node names to the value of +attribute key at that node. +Nodes not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-nodes
+

The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the nodes in the graph whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the nodes in the graph whose +names match this pattern are searched for the attribute.

+
+
graphName node degree ?-in|-out? node
+

Return the number of arcs adjacent to the specified node. If one +of the restrictions -in or -out is given only the +incoming resp. outgoing arcs are counted.

+
graphName node delete node ?node...?
+

Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs.

+
graphName node exists node
+

Return true if the specified node exists in the graph.

+
graphName node get node key
+

Return the value associated with the key key for the node.

+
graphName node getall node ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName node keys node ?pattern?
+

Returns a list of keys for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName node keyexists node key
+

Return true if the specified key exists for the node.

+
graphName node insert ?node...?
+

Insert one or more nodes into the graph. The new nodes have no arcs +connected to them. If no node is specified one node will be inserted, +and the system will generate a unique name of the form +nodex for it.

+
graphName node lappend node key value
+

Appends a value (as a list) to one of the keyed values +associated with an node. Returns the new value given to the +attribute key.

+
graphName node opposite node arc
+

Return the node at the other end of the specified arc, which has +to be adjacent to the given node.

+
graphName node rename node newname
+

Renames the node node to newname. An error is thrown if +either the node does not exist, or a node with name newname does +exist. The result of the command is the new name of the node.

+
graphName node set node key ?value?
+

Set or get one of the keyed values associated with a node. A node may have any +number of keyed values associated with it. If value is not +specified, this command returns the current value assigned to the key; +if value is specified, this command assigns that value to the +key.

+
graphName node unset node key
+

Remove a keyed value from the node node. The method will do +nothing if the key does not exist.

+
graphName nodes ?-key key? ?-value value? ?-filter cmdprefix? ?-in|-out|-adj|-inner|-embedding node node...?
+

Return a list of nodes in the graph. Restrictions can limit the list +of returned nodes based on neighboring nodes, or based on the keyed +values associated with the node. The restrictions that involve +neighboring nodes have a list of nodes as argument, specified after +the name of the restriction itself.

+

The possible restrictions are the same as for method +arcs. The exact meanings change slightly, as they operate on +nodes instead of arcs. The command recognizes:

+
+
-in
+

Return a list of all nodes with at least one outgoing arc ending in a +node found in the specified set of nodes. Alternatively specified as +the set of source nodes for the -in arcs of the node set. The +incoming neighbours.

+
-out
+

Return a list of all nodes with at least one incoming arc starting in +a node found in the specified set of nodes. Alternatively specified as +the set of target nodes for the -out arcs of the node +set. The outgoing neighbours.

+
-adj
+

This is the union of the nodes returned by -in and +-out. The neighbours.

+
-inner
+

The set of neighbours (see -adj above) which are also in the +set of nodes. I.e. the intersection between the set of nodes and the +neighbours per -adj.

+
-embedding
+

The set of neighbours (see -adj above) which are not in the +set of nodes. I.e. the difference between the neighbours as per +-adj, and the set of nodes.

+
-key key
+

Limit the list of nodes that are returned to those nodes that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of nodes that are returned to those +nodes whose associated key key has the value value.

+
-filter cmdrefix
+

Limit the list of nodes that are returned to those nodes that pass the +test. The command in cmdprefix is called with two arguments, the +name of the graph object, and the name of the node in question. It is +executed in the context of the caller and has to return a boolean +value. Nodes for which the command returns false are removed +from the result list before it is returned to the caller.

+
+
graphName get key
+

Return the value associated with the key key for the graph.

+
graphName getall ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +for the whole graph. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned dictionary. The pattern +is a glob pattern.

+
graphName keys ?pattern?
+

Returns a list of keys for the whole graph. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
graphName keyexists key
+

Return true if the specified key exists for the whole graph.

+
graphName serialize ?node...?
+

This method serializes the sub-graph spanned up by the nodes. In +other words it returns a tcl value completely describing that +graph. If no nodes are specified the whole graph will be serialized. +This allows, for example, the transfer of graph objects (or parts +thereof) over arbitrary channels, persistence, etc. +This method is also the basis for both the copy constructor and +the assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the graph interface. This is what will enable us to +copy graph data between different implementations of the same +interface.

+

The result is a list containing a multiple of three items, plus one! +In other words, '[llength $serial] % 3 == 1'. Valid values +include 1, 4, 7, ...

+

The last element of the list is a dictionary containing the attributes +associated with the whole graph. +Regarding the other elements; each triple consists of

+
    +

  1. The name of the node to be described,

    2. +

  2. A dictionary containing the attributes associated with the node,

    3. +

  3. And a list describing all the arcs starting at that node.

    4. +
+

The elements of the arc list are lists containing three or four +elements each, i.e.

+
    +

  1. The name of the arc described by the element,

    2. +

  2. A reference to the destination node of the arc. This reference is an +integer number given the index of that node in the main serialization +list. As that it is greater than or equal to zero, less than the +length of the serialization, and a multiple of three. +Note: For internal consistency no arc name may be used twice, +whether in the same node, or at some other node. This is a global +consistency requirement for the serialization.

    3. +

  3. And a dictionary containing the attributes associated with the arc.

    4. +

  4. The weight associated with the arc. This value is optional. Its +non-presence means that the arc in question has no weight associated +with it.

    +

    Note: This information is new, compared to the +serialization of graph 2.3 and earlier. By making it an +optional element the new format is maximally compatible with the +old. This means that any graph not using weights will generate a +serialization which is still understood by the older graph package. A +serialization will not be understood any longer by the older packages +if, and only if the graph it was generated from actually has arcs with +weights.

    5. +
+

For all attribute dictionaries they keys are the names of the +attributes, and the values are the values for each name.

+

Note: The order of the nodes in the serialization has no +relevance, nor has the order of the arcs per node.

+
+    # A possible serialization for the graph structure
+    #
+    #        d -----> %2
+    #       /         ^ \\
+    #      /         /   \\
+    #     /         b     \\
+    #    /         /       \\
+    #  %1 <- a - %0         e
+    #    ^         \\      /
+    #     \\        c     /
+    #      \\        \\  /
+    #       \\        v v
+    #        f ------ %3
+    # is
+    #
+    # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
+    #
+    # This assumes that the graph has neither attribute data nor weighted arcs.
+
+
+
graphName set key ?value?
+

Set or get one of the keyed values associated with a graph. A graph +may have any number of keyed values associated with it. If value +is not specified, this command returns the current value assigned to +the key; if value is specified, this command assigns that value +to the key.

+
graphName swap node1 node2
+

Swap the position of node1 and node2 in the graph.

+
graphName unset key
+

Remove a keyed value from the graph. The method will do nothing if the +key does not exist.

+
graphName walk node ?-order order? ?-type type? ?-dir direction? -command cmd
+

Perform a breadth-first or depth-first walk of the graph starting at +the node node going in either the direction of outgoing or +opposite to the incoming arcs.

+

The type of walk, breadth-first or depth-first, is determined by the +value of type; bfs indicates breadth-first, +dfs indicates depth-first. Depth-first is the default.

+

The order of the walk, pre-order, post-order or both-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order. Pre-order is the default. Pre-order walking means that a +node is visited before any of its neighbors (as defined by the +direction, see below). Post-order walking means that a parent is +visited after any of its neighbors. Both-order walking means that a +node is visited before and after any of its neighbors. The +combination of a breadth-first walk with post- or both-order is illegal.

+

The direction of the walk is determined by the value of dir; +backward indicates the direction opposite to the incoming +arcs, forward indicates the direction of the outgoing arcs.

+

As the walk progresses, the command cmd will be evaluated at +each node, with the mode of the call (enter or +leave) and values graphName and the name of the current +node appended. For a pre-order walk, all nodes are entered, for a +post-order all nodes are left. In a both-order walk the first visit of +a node enters it, the second visit leaves it.

+
+
+

Changes for 2.0

+

The following noteworthy changes have occurred:

+
    +

  1. The API for accessing attributes and their values has been +simplified.

    +

    All functionality regarding the default attribute "data" has been +removed. This default attribute does not exist anymore. All accesses +to attributes have to specify the name of the attribute in +question. This backward incompatible change allowed us to +simplify the signature of all methods handling attributes.

    +

    Especially the flag -key is not required anymore, even more, +its use is now forbidden. Please read the documentation for the arc +and node methods set, get, getall, +unset, append, lappend, keyexists +and keys for a description of the new API's.

    2. +

  2. The methods keys and getall now take an optional +pattern argument and will return only attribute data for keys matching +this pattern.

    3. +

  3. Arcs and nodes can now be renamed. See the documentation for the +methods arc rename and node rename.

    4. +

  4. The structure has been extended with API's for the serialization and +deserialization of graph objects, and a number of operations based on +them (graph assignment, copy construction).

    +

    Please read the documentation for the methods serialize, +deserialize, =, and -->, and the +documentation on the construction of graph objects.

    +

    Beyond the copying of whole graph objects these new API's also enable +the transfer of graph objects over arbitrary channels and for easy +persistence.

    5. +

  5. A new method, attr, was added to both arc and +node allowing the query and retrieval of attribute data +without regard to arc and node relationships.

    6. +

  6. Both methods arcs and nodes have been extended with +the ability to select arcs and nodes based on an arbitrary filtering +criterium.

    7. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/graph1.html Index: embedded/www/tcllib/files/modules/struct/graph1.html ================================================================== --- embedded/www/tcllib/files/modules/struct/graph1.html +++ embedded/www/tcllib/files/modules/struct/graph1.html @@ -0,0 +1,406 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::graph_v1(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::graph_v1 - Create and manipulate directed graph objects

+
+ + +

Description

+

The ::struct::graph command creates a new graph object with an +associated global Tcl command whose name is graphName. This +command may be used to invoke various operations on the graph. It has +the following general form:

+
+
graphName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A directed graph is a structure containing two collections of +elements, called nodes and arcs respectively, together +with a relation ("connectivity") that places a general structure upon +the nodes and arcs.

+

Each arc is connected to two nodes, one of which is called the +source and the other the target. This imposes a +direction upon the arc, which is said to go from the source to the +target. It is allowed that source and target of an arc are the same +node. Such an arc is called a loop. Whenever a node is source +or target of an arc both are said to be adjacent. This extends +into a relation between nodes, i.e. if two nodes are connected through +at least one arc they are said to be adjacent too.

+

Each node can be the source and target for any number of arcs. The +former are called the outgoing arcs of the node, the latter +the incoming arcs of the node. The number of edges in either +set is called the in- resp. the out-degree of the node.

+

In addition to maintaining the node and arc relationships, this graph +implementation allows any number of keyed values to be associated with +each node and arc.

+

The following commands are possible for graph objects:

+
+
graphName destroy
+

Destroy the graph, including its storage space and associated command.

+
graphName arc append arc ?-key key? value
+

Appends a value to one of the keyed values associated with an +arc. If no key is specified, the key data is +assumed.

+
graphName arc delete arc ?arc ...?
+

Remove the specified arcs from the graph.

+
graphName arc exists arc
+

Return true if the specified arc exists in the graph.

+
graphName arc get arc ?-key key?
+

Return the value associated with the key key for the arc. +If no key is specified, the key data is assumed.

+
graphName arc getall arc
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the arc.

+
graphName arc keys arc
+

Returns a list of keys for the arc.

+
graphName arc keyexists arc ?-key key?
+

Return true if the specified key exists for the arc. If no +key is specified, the key data is assumed.

+
graphName arc insert start end ?child?
+

Insert an arc named child into the graph beginning at the node +start and ending at the node end. If the name of the new +arc is not specified the system will generate a unique name of the +form arcx.

+
graphName arc lappend arc ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an arc. If no key is specified, the key +data is assumed.

+
graphName arc set arc ?-key key? ?value?
+

Set or get one of the keyed values associated with an arc. If no key +is specified, the key data is assumed. Each arc that is +added to a graph has the empty string assigned to the key +data automatically. An arc may have any number of keyed +values associated with it. If value is not specified, this +command returns the current value assigned to the key; if value +is specified, this command assigns that value to the key.

+
graphName arc source arc
+

Return the node the given arc begins at.

+
graphName arc target arc
+

Return the node the given arc ends at.

+
graphName arc unset arc ?-key key?
+

Remove a keyed value from the arc arc. If no key is specified, +the key data is assumed.

+
graphName arcs ?-key key? ?-value value? ?-in|-out|-adj|-inner|-embedding nodelist?
+

Return a list of arcs in the graph. If no restriction is specified a +list containing all arcs is returned. Restrictions can limit the list +of returned arcs based on the nodes that are connected by the arc, on +the keyed values associated with the arc, or both. The restrictions +that involve connected nodes have a list of nodes as argument, +specified after the name of the restriction itself.

+
+
-in
+

Return a list of all arcs whose target is one of the nodes in the +nodelist.

+
-out
+

Return a list of all arcs whose source is one of the nodes in the +nodelist.

+
-adj
+

Return a list of all arcs adjacent to at least one of the nodes in the +nodelist. This is the union of the nodes returned by +-in and -out.

+
-inner
+

Return a list of all arcs adjacent to two of the nodes in the +nodelist. This is the set of arcs in the subgraph spawned by the +specified nodes.

+
-embedding
+

Return a list of all arcs adjacent to exactly one of the nodes in the +nodelist. This is the set of arcs connecting the subgraph +spawned by the specified nodes to the rest of the graph.

+
-key key
+

Limit the list of arcs that are returned to those arcs that have an +associated key key.

+
-value value
+

This restriction can only be used in combination with +-key. It limits the list of arcs that are returned to those +arcs whose associated key key has the value value.

+
+

The restrictions imposed by either -in, -out, +-adj, -inner, or -embedded are applied +first. Specifying more than one of them is illegal. +At last the restrictions set via -key (and -value) +are applied. +Specifying more than one -key (and -value) is +illegal.

+
graphName node append node ?-key key? value
+

Appends a value to one of the keyed values associated with an +node. If no key is specified, the key data is +assumed.

+
graphName node degree ?-in|-out? node
+

Return the number of arcs adjacent to the specified node. If one +of the restrictions -in or -out is given only the +incoming resp. outgoing arcs are counted.

+
graphName node delete node ?node ...?
+

Remove the specified nodes from the graph. All of the nodes' arcs +will be removed as well to prevent unconnected arcs.

+
graphName node exists node
+

Return true if the specified node exists in the graph.

+
graphName node get node ?-key key?
+

Return the value associated with the key key for the node. +If no key is specified, the key data is assumed.

+
graphName node getall node
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the node.

+
graphName node keys node
+

Returns a list of keys for the node.

+
graphName node keyexists node ?-key key?
+

Return true if the specified key exists for the node. If +no key is specified, the key data is assumed.

+
graphName node insert ?child?
+

Insert a node named child into the graph. The nodes has no arcs +connected to it. If the name of the new child is not specified the +system will generate a unique name of the form nodex.

+
graphName node lappend node ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an node. If no key is specified, the key +data is assumed.

+
graphName node opposite node arc
+

Return the node at the other end of the specified arc, which has +to be adjacent to the given node.

+
graphName node set node ?-key key? ?value?
+

Set or get one of the keyed values associated with a node. If no key +is specified, the key data is assumed. Each node that is +added to a graph has the empty string assigned to the key +data automatically. A node may have any number of keyed +values associated with it. If value is not specified, this +command returns the current value assigned to the key; if value +is specified, this command assigns that value to the key.

+
graphName node unset node ?-key key?
+

Remove a keyed value from the node node. If no key is +specified, the key data is assumed.

+
graphName nodes ?-key key? ?-value value? ?-in|-out|-adj|-inner|-embedding nodelist?
+

Return a list of nodes in the graph. Restrictions can limit the list +of returned nodes based on neighboring nodes, or based on the keyed +values associated with the node. The restrictions that involve +neighboring nodes have a list of nodes as argument, specified after +the name of the restriction itself.

+

The possible restrictions are the same as for method +arcs. The set of nodes to return is computed as the union of +all source and target nodes for all the arcs satisfying the +restriction as defined for arcs.

+
graphName get ?-key key?
+

Return the value associated with the key key for the graph. If +no key is specified, the key data is assumed.

+
graphName getall
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the whole graph.

+
graphName keys
+

Returns a list of keys for the whole graph.

+
graphName keyexists ?-key key?
+

Return true if the specified key exists for the whole graph. If no +key is specified, the key data is assumed.

+
graphName set ?-key key? ?value?
+

Set or get one of the keyed values associated with a graph. If no key +is specified, the key data is assumed. Each graph has the +empty string assigned to the key data automatically. A graph +may have any number of keyed values associated with it. If value +is not specified, this command returns the current value assigned to +the key; if value is specified, this command assigns that value +to the key.

+
graphName swap node1 node2
+

Swap the position of node1 and node2 in the graph.

+
graphName unset ?-key key?
+

Remove a keyed value from the graph. If no key is specified, the key +data is assumed.

+
graphName walk node ?-order order? ?-type type? ?-dir direction? -command cmd
+

Perform a breadth-first or depth-first walk of the graph starting at +the node node going in either the direction of outgoing or +opposite to the incoming arcs.

+

The type of walk, breadth-first or depth-first, is determined by the +value of type; bfs indicates breadth-first, +dfs indicates depth-first. Depth-first is the default.

+

The order of the walk, pre-order, post-order or both-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order. Pre-order is the default. Pre-order walking means that a +node is visited before any of its neighbors (as defined by the +direction, see below). Post-order walking means that a parent is +visited after any of its neighbors. Both-order walking means that a +node is visited before and after any of its neighbors. The +combination of a bread-first walk with post- or both-order is illegal.

+

The direction of the walk is determined by the value of dir; +backward indicates the direction opposite to the incoming +arcs, forward indicates the direction of the outgoing arcs.

+

As the walk progresses, the command cmd will be evaluated at +each node, with the mode of the call (enter or +leave) and values graphName and the name of the current +node appended. For a pre-order walk, all nodes are entered, for a +post-order all nodes are left. In a both-order walk the first visit of +a node enters it, the second visit leaves it.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/graphops.html Index: embedded/www/tcllib/files/modules/struct/graphops.html ================================================================== --- embedded/www/tcllib/files/modules/struct/graphops.html +++ embedded/www/tcllib/files/modules/struct/graphops.html @@ -0,0 +1,1036 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::graph::op(n) 0.11.3 tcllib "Tcl Data Structures"

+

Name

+

struct::graph::op - Operation for (un)directed graph objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require struct::graph::op ?0.11.3?
    • +
+ +
+
+

Description

+

The package described by this document, struct::graph::op, +is a companion to the package struct::graph. It provides a +series of common operations and algorithms applicable to (un)directed +graphs.

+

Despite being a companion the package is not directly dependent on +struct::graph, only on the API defined by that +package. I.e. the operations of this package can be applied to any and +all graph objects which provide the same API as the objects created +through struct::graph.

+
+

Operations

+
+
struct::graph::op::toAdjacencyMatrix g
+

This command takes the graph g and returns a nested list +containing the adjacency matrix of g.

+

The elements of the outer list are the rows of the matrix, the inner +elements are the column values in each row. The matrix has "n+1" +rows and columns, with the first row and column (index 0) containing +the name of the node the row/column is for. All other elements are +boolean values, True if there is an arc between the 2 nodes +of the respective row and column, and False otherwise.

+

Note that the matrix is symmetric. It does not represent the +directionality of arcs, only their presence between nodes. It is also +unable to represent parallel arcs in g.

+
struct::graph::op::toAdjacencyList G ?options...?
+

Procedure creates for input graph G, it's representation as Adjacency List. +It handles both directed and undirected graphs (default is undirected). +It returns dictionary that for each node (key) returns list of nodes adjacent +to it. When considering weighted version, for each adjacent node there is also +weight of the edge included.

+
+
Arguments:
+
+
Graph object G (input)
+

A graph to convert into an Adjacency List.

+
+
Options:
+
+
-directed
+

By default G is operated as if it were an Undirected graph. +Using this option tells the command to handle G as the directed graph it is.

+
-weights
+

By default any weight information the graph G may have is ignored. +Using this option tells the command to put weight information into the result. +In that case it is expected that all arcs have a proper weight, and an error +is thrown if that is not the case.

+
+
+
struct::graph::op::kruskal g
+

This command takes the graph g and returns a list containing the +names of the arcs in g which span up a minimum weight spanning tree +(MST), or, in the case of an un-connected graph, a minimum weight spanning +forest (except for the 1-vertex components). Kruskal's algorithm is used +to compute the tree or forest. +This algorithm has a time complexity of O(E*log E) or O(E* log V), +where V is the number of vertices and E is the number of edges +in graph g.

+

The command will throw an error if one or more arcs in g have no +weight associated with them.

+

A note regarding the result, the command refrains from explicitly +listing the nodes of the MST as this information is implicitly +provided in the arcs already.

+
struct::graph::op::prim g
+

This command takes the graph g and returns a list containing the +names of the arcs in g which span up a minimum weight spanning tree +(MST), or, in the case of an un-connected graph, a minimum weight spanning +forest (except for the 1-vertex components). Prim's algorithm is used to +compute the tree or forest. +This algorithm has a time complexity between O(E+V*log V) and O(V*V), +depending on the implementation (Fibonacci heap + Adjacency list versus +Adjacency Matrix). As usual V is the number of vertices and +E the number of edges in graph g.

+

The command will throw an error if one or more arcs in g have no +weight associated with them.

+

A note regarding the result, the command refrains from explicitly +listing the nodes of the MST as this information is implicitly +provided in the arcs already.

+
struct::graph::op::isBipartite? g ?bipartvar?
+

This command takes the graph g and returns a boolean value +indicating whether it is bipartite (true) or not +(false). If the variable bipartvar is specified the two +partitions of the graph are there as a list, if, and only if the graph +is bipartit. If it is not the variable, if specified, is not touched.

+
struct::graph::op::tarjan g
+

This command computes the set of strongly connected +components (SCCs) of the graph g. The result of the command is a +list of sets, each of which contains the nodes for one of the SCCs of +g. The union of all SCCs covers the whole graph, and no two SCCs +intersect with each other.

+

The graph g is acyclic if all SCCs in the result contain +only a single node. The graph g is strongly connected +if the result contains only a single SCC containing all nodes of +g.

+
struct::graph::op::connectedComponents g
+

This command computes the set of connected components (CCs) of +the graph g. The result of the command is a list of sets, each +of which contains the nodes for one of the CCs of g. The union +of all CCs covers the whole graph, and no two CCs intersect with each +other.

+

The graph g is connected if the result contains only a +single SCC containing all nodes of g.

+
struct::graph::op::connectedComponentOf g n
+

This command computes the connected component (CC) of the graph +g containing the node n. The result of the command is a +sets which contains the nodes for the CC of n in g.

+

The command will throw an error if n is not a node of the graph +g.

+
struct::graph::op::isConnected? g
+

This is a convenience command determining whether the graph g is +connected or not. The result is a boolean value, true +if the graph is connected, and false otherwise.

+
struct::graph::op::isCutVertex? g n
+

This command determines whether the node n in the graph g +is a cut vertex (aka articulation point). The result +is a boolean value, true if the node is a cut vertex, and +false otherwise.

+

The command will throw an error if n is not a node of the graph +g.

+
struct::graph::op::isBridge? g a
+

This command determines whether the arc a in the graph g +is a bridge (aka cut edge, or isthmus). The +result is a boolean value, true if the arc is a bridge, and +false otherwise.

+

The command will throw an error if a is not an arc of the graph +g.

+
struct::graph::op::isEulerian? g ?tourvar?
+

This command determines whether the graph g is eulerian +or not. The result is a boolean value, true if the graph is +eulerian, and false otherwise.

+

If the graph is eulerian and tourvar is specified then an euler +tour is computed as well and stored in the named variable. The tour is +represented by the list of arcs traversed, in the order of traversal.

+
struct::graph::op::isSemiEulerian? g ?pathvar?
+

This command determines whether the graph g is +semi-eulerian or not. The result is a boolean value, true +if the graph is semi-eulerian, and false otherwise.

+

If the graph is semi-eulerian and pathvar is specified then an +euler path is computed as well and stored in the named variable. The +path is represented by the list of arcs traversed, in the order of +traversal.

+
struct::graph::op::dijkstra g start ?options...?
+

This command determines distances in the weighted g from the +node start to all other nodes in the graph. The options specify +how to traverse graphs, and the format of the result.

+

Two options are recognized

+
+
-arcmode mode
+

The accepted mode values are directed and undirected. +For directed traversal all arcs are traversed from source to +target. For undirected traversal all arcs are traversed in the +opposite direction as well. Undirected traversal is the default.

+
-outputformat format
+

The accepted format values are distances and tree. In +both cases the result is a dictionary keyed by the names of all nodes +in the graph. For distances the value is the distance of the +node to start, whereas for tree the value is the path +from the node to start, excluding the node itself, but including +start. Tree format is the default.

+
+
struct::graph::op::distance g origin destination ?options...?
+

This command determines the (un)directed distance between the two +nodes origin and destination in the graph g. It +accepts the option -arcmode of struct::graph::op::dijkstra.

+
struct::graph::op::eccentricity g n ?options...?
+

This command determines the (un)directed eccentricity of the +node n in the graph g. It accepts the option +-arcmode of struct::graph::op::dijkstra.

+

The (un)directed eccentricity of a node is the maximal +(un)directed distance between the node and any other node in the +graph.

+
struct::graph::op::radius g ?options...?
+

This command determines the (un)directed radius of the graph +g. It accepts the option -arcmode of struct::graph::op::dijkstra.

+

The (un)directed radius of a graph is the minimal (un)directed +eccentricity of all nodes in the graph.

+
struct::graph::op::diameter g ?options...?
+

This command determines the (un)directed diameter of the graph +g. It accepts the option -arcmode of struct::graph::op::dijkstra.

+

The (un)directed diameter of a graph is the maximal (un)directed +eccentricity of all nodes in the graph.

+
struct::graph::op::BellmanFord G startnode
+

Searching for shortests paths between chosen node and all other nodes in graph G. Based +on relaxation method. In comparison to struct::graph::op::dijkstra it doesn't need assumption that all weights +on edges in input graph G have to be positive.

+

That generality sets the complexity of algorithm to - O(V*E), where V is the number of vertices +and E is number of edges in graph G.

+
+
Arguments:
+
+
Graph object G (input)
+

Directed, connected and edge weighted graph G, without any negative cycles ( presence of cycles with the negative sum +of weight means that there is no shortest path, since the total weight becomes lower each time the cycle is +traversed ). Negative weights on edges are allowed.

+
Node startnode (input)
+

The node for which we find all shortest paths to each other node in graph G.

+
+
Result:
+

Dictionary containing for each node (key) distances to each other node in graph G.

+
+

Note: If algorithm finds a negative cycle, it will return error message.

+
struct::graph::op::Johnsons G ?options...?
+

Searching for shortest paths between all pairs of vertices in graph. For sparse graphs +asymptotically quicker than struct::graph::op::FloydWarshall algorithm. Johnson's algorithm +uses struct::graph::op::BellmanFord and struct::graph::op::dijkstra as subprocedures.

+

Time complexity: O(n**2*log(n) +n*m), where n is the number of nodes and m is +the number of edges in graph G.

+
+
Arguments:
+
+
Graph object G (input)
+

Directed graph G, weighted on edges and not containing +any cycles with negative sum of weights ( the presence of such cycles means +there is no shortest path, since the total weight becomes lower each time the +cycle is traversed ). Negative weights on edges are allowed.

+
+
Options:
+
+
-filter
+

Returns only existing distances, cuts all Inf values for +non-existing connections between pairs of nodes.

+
+
Result:
+

Dictionary containing distances between all pairs of vertices.

+
+
struct::graph::op::FloydWarshall G
+

Searching for shortest paths between all pairs of edges in weighted graphs.

+

Time complexity: O(V^3) - where V is number of vertices.

+

Memory complexity: O(V^2).

+
+
Arguments:
+
+
Graph object G (input)
+

Directed and weighted graph G.

+
+
Result:
+

Dictionary containing shortest distances to each node from each node.

+
+

Note: Algorithm finds solutions dynamically. It compares all possible paths through the graph +between each pair of vertices. Graph shouldn't possess any cycle with negative +sum of weights (the presence of such cycles means there is no shortest path, +since the total weight becomes lower each time the cycle is traversed).

+

On the other hand algorithm can be used to find those cycles - if any shortest distance +found by algorithm for any nodes v and u (when v is the same node as u) is negative, +that node surely belong to at least one negative cycle.

+
struct::graph::op::MetricTravellingSalesman G
+

Algorithm for solving a metric variation of Travelling salesman problem. +TSP problem is NP-Complete, so there is no efficient algorithm to solve it. Greedy methods +are getting extremely slow, with the increase in the set of nodes.

+
+
Arguments:
+
+
Graph object G (input)
+

Undirected, weighted graph G.

+
+
Result:
+

Approximated solution of minimum Hamilton Cycle - closed path visiting all nodes, +each exactly one time.

+
+

Note: It's 2-approximation algorithm.

+
struct::graph::op::Christofides G
+

Another algorithm for solving metric TSP problem. +Christofides implementation uses Max Matching for reaching better approximation factor.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected, weighted graph G.

+
+
Result:
+

Approximated solution of minimum Hamilton Cycle - closed path visiting all nodes, +each exactly one time.

+
+

Note: It's is a 3/2 approximation algorithm.

+
struct::graph::op::GreedyMaxMatching G
+

Greedy Max Matching procedure, which finds maximal matching (not maximum) +for given graph G. It adds edges to solution, beginning from edges with the +lowest cost.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected graph G.

+
+
Result:
+

Set of edges - the max matching for graph G.

+
+
struct::graph::op::MaxCut G U V
+

Algorithm solving a Maximum Cut Problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

The graph to cut.

+
List U (output)
+

Variable storing first set of nodes (cut) given by solution.

+
List V (output)
+

Variable storing second set of nodes (cut) given by solution.

+
+
Result:
+

Algorithm returns number of edges between found two sets of nodes.

+
+

Note: MaxCut is a 2-approximation algorithm.

+
struct::graph::op::UnweightedKCenter G k
+

Approximation algorithm that solves a k-center problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected complete graph G, which satisfies triangle inequality.

+
Integer k (input)
+

Positive integer that sets the number of nodes that will be included in k-center.

+
+
Result:
+

Set of nodes - k center for graph G.

+
+

Note: UnweightedKCenter is a 2-approximation algorithm.

+
struct::graph::op::WeightedKCenter G nodeWeights W
+

Approximation algorithm that solves a weighted version of k-center problem.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected complete graph G, which satisfies triangle inequality.

+
Integer W (input)
+

Positive integer that sets the maximum possible weight of k-center found by algorithm.

+
List nodeWeights (input)
+

List of nodes and its weights in graph G.

+
+
Result:
+

Set of nodes, which is solution found by algorithm.

+
+

Note:WeightedKCenter is a 3-approximation algorithm.

+
struct::graph::op::GreedyMaxIndependentSet G
+

A maximal independent set is an independent set such that adding any other node +to the set forces the set to contain an edge.

+

Algorithm for input graph G returns set of nodes (list), which are contained in Max Independent +Set found by algorithm.

+
struct::graph::op::GreedyWeightedMaxIndependentSet G nodeWeights
+

Weighted variation of Maximal Independent Set. It takes as an input argument +not only graph G but also set of weights for all vertices in graph G.

+

Note: +Read also Maximal Independent Set description for more info.

+
struct::graph::op::VerticesCover G
+

Vertices cover is a set of vertices such that each edge of the graph is incident to +at least one vertex of the set. This 2-approximation algorithm searches for minimum +vertices cover, which is a classical optimization problem in computer science and +is a typical example of an NP-hard optimization problem that has an approximation +algorithm. +For input graph G algorithm returns the set of edges (list), which is Vertex Cover found by algorithm.

+
struct::graph::op::EdmondsKarp G s t
+

Improved Ford-Fulkerson's algorithm, computing the maximum flow in given flow network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Weighted and directed graph. Each edge should have set integer attribute considered as +maximum throughputs that can be carried by that link (edge).

+
Node s (input)
+

The node that is a source for graph G.

+
Node t (input)
+

The node that is a sink for graph G.

+
+
Result:
+

Procedure returns the dictionary containing throughputs for all edges. For +each key ( the edge between nodes u and v in the form of list u v ) there is +a value that is a throughput for that key. Edges where throughput values +are equal to 0 are not returned ( it is like there was no link in the flow network +between nodes connected by such edge).

+
+

The general idea of algorithm is finding the shortest augumenting paths in graph G, as long +as they exist, and for each path updating the edge's weights along that path, +with maximum possible throughput. The final (maximum) flow is found +when there is no other augumenting path from source to sink.

+

Note: Algorithm complexity : O(V*E), where V is the number of nodes and E is the number +of edges in graph G.

+
struct::graph::op::BusackerGowen G desiredFlow s t
+

Algorithm finds solution for a minimum cost flow problem. So, the goal is to find a flow, +whose max value can be desiredFlow, from source node s to sink node t in given flow network G. +That network except throughputs at edges has also defined a non-negative cost on each edge - cost of using that edge when +directing flow with that edge ( it can illustrate e.g. fuel usage, time or any other measure dependent on usages ).

+
+
Arguments:
+
+
Graph Object G (input)
+

Flow network (directed graph), each edge in graph should have two integer attributes: cost and throughput.

+
Integer desiredFlow (input)
+

Max value of the flow for that network.

+
Node s (input)
+

The source node for graph G.

+
Node t (input)
+

The sink node for graph G.

+
+
Result:
+

Dictionary containing values of used throughputs for each edge ( key ). +found by algorithm.

+
+

Note: Algorithm complexity : O(V**2*desiredFlow), where V is the number of nodes in graph G.

+
struct::graph::op::ShortestsPathsByBFS G s outputFormat
+

Shortest pathfinding algorithm using BFS method. In comparison to struct::graph::op::dijkstra it can +work with negative weights on edges. Of course negative cycles are not allowed. Algorithm is better than dijkstra +for sparse graphs, but also there exist some pathological cases (those cases generally don't appear in practise) that +make time complexity increase exponentially with the growth of the number of nodes.

+
+
Arguments:
+
+
Graph Object G (input)
+

Input graph.

+
Node s (input)
+

Source node for which all distances to each other node in graph G are computed.

+
+
Options and result:
+
+
distances
+

When selected outputFormat is distances - procedure returns dictionary containing +distances between source node s and each other node in graph G.

+
paths
+

When selected outputFormat is paths - procedure returns dictionary containing +for each node v, a list of nodes, which is a path between source node s and node v.

+
+
+
struct::graph::op::BFS G s ?outputFormat...?
+

Breadth-First Search - algorithm creates the BFS Tree. +Memory and time complexity: O(V + E), where V is the number of nodes and E +is number of edges.

+
+
Arguments:
+
+
Graph Object G (input)
+

Input graph.

+
Node s (input)
+

Source node for BFS procedure.

+
+
Options and result:
+
+
graph
+

When selected outputFormat is graph - procedure returns a graph structure (struct::graph), +which is equivalent to BFS tree found by algorithm.

+
tree
+

When selected outputFormat is tree - procedure returns a tree structure (struct::tree), +which is equivalent to BFS tree found by algorithm.

+
+
+
struct::graph::op::MinimumDiameterSpanningTree G
+

The goal is to find for input graph G, the spanning tree that +has the minimum diameter value.

+

General idea of algorithm is to run BFS over all vertices in graph +G. If the diameter d of the tree is odd, then we are sure that tree +given by BFS is minimum (considering diameter value). When, diameter d +is even, then optimal tree can have minimum diameter equal to d or +d-1.

+

In that case, what algorithm does is rebuilding the tree given by BFS, by +adding a vertice between root node and root's child node (nodes), such that +subtree created with child node as root node is the greatest one (has the +greatests height). In the next step for such rebuilded tree, we run again BFS +with new node as root node. If the height of the tree didn't changed, we have found +a better solution.

+

For input graph G algorithm returns the graph structure (struct::graph) that is +a spanning tree with minimum diameter found by algorithm.

+
struct::graph::op::MinimumDegreeSpanningTree G
+

Algorithm finds for input graph G, a spanning tree T with the minimum possible +degree. That problem is NP-hard, so algorithm is an approximation algorithm.

+

Let V be the set of nodes for graph G and let W be any subset of V. Lets +assume also that OPT is optimal solution and ALG is solution found by algorithm for input +graph G.

+

It can be proven that solution found with the algorithm must fulfil inequality:

+

((|W| + k - 1) / |W|) <= ALG <= 2*OPT + log2(n) + 1.

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected simple graph.

+
+
Result:
+

Algorithm returns graph structure, which is equivalent to spanning tree T found by algorithm.

+
+
struct::graph::op::MaximumFlowByDinic G s t blockingFlowAlg
+

Algorithm finds maximum flow for the flow network represented by graph G. It is based on +the blocking-flow finding methods, which give us different complexities what makes a better fit for +different graphs.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Options:
+
+
dinic
+

Procedure will find maximum flow for flow network G using Dinic's algorithm (struct::graph::op::BlockingFlowByDinic) +for blocking flow computation.

+
mkm
+

Procedure will find maximum flow for flow network G using Malhotra, Kumar and Maheshwari's algorithm (struct::graph::op::BlockingFlowByMKM) +for blocking flow computation.

+
+
Result:
+

Algorithm returns dictionary containing it's flow value for each edge (key) in network G.

+
+

Note: struct::graph::op::BlockingFlowByDinic gives O(m*n^2) complexity and +struct::graph::op::BlockingFlowByMKM gives O(n^3) complexity, where n is the number of nodes +and m is the number of edges in flow network G.

+
struct::graph::op::BlockingFlowByDinic G s t
+

Algorithm for given network G with source s and sink t, finds a blocking +flow, which can be used to obtain a maximum flow for that network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Result:
+

Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network G.

+
+

Note: Algorithm's complexity is O(n*m), where n is the number of nodes +and m is the number of edges in flow network G.

+
struct::graph::op::BlockingFlowByMKM G s t
+

Algorithm for given network G with source s and sink t, finds a blocking +flow, which can be used to obtain a maximum flow for that network G.

+
+
Arguments:
+
+
Graph Object G (input)
+

Directed graph G representing the flow network. Each edge should have attribute +throughput set with integer value.

+
Node s (input)
+

The source node for the flow network G.

+
Node t (input)
+

The sink node for the flow network G.

+
+
Result:
+

Algorithm returns dictionary containing it's blocking flow value for each edge (key) in network G.

+
+

Note: Algorithm's complexity is O(n^2), where n is the number of nodes in flow network G.

+
struct::graph::op::createResidualGraph G f
+

Procedure creates a residual graph (or residual network ) for network G and given +flow f.

+
+
Arguments:
+
+
Graph Object G (input)
+

Flow network (directed graph where each edge has set attribute: throughput ).

+
dictionary f (input)
+

Current flows in flow network G.

+
+
Result:
+

Procedure returns graph structure that is a residual graph created from input flow +network G.

+
+
struct::graph::op::createAugmentingNetwork G f path
+

Procedure creates an augmenting network for a given residual network G +, flow f and augmenting path path.

+
+
Arguments:
+
+
Graph Object G (input)
+

Residual network (directed graph), where for every edge there are set two attributes: throughput and cost.

+
Dictionary f (input)
+

Dictionary which contains for every edge (key), current value of the flow on that edge.

+
List path (input)
+

Augmenting path, set of edges (list) for which we create the network modification.

+
+
Result:
+

Algorithm returns graph structure containing the modified augmenting network.

+
+
struct::graph::op::createLevelGraph Gf s
+

For given residual graph Gf procedure finds the level graph.

+
+
Arguments:
+
+
Graph Object Gf (input)
+

Residual network, where each edge has it's attribute throughput set with certain value.

+
Node s (input)
+

The source node for the residual network Gf.

+
+
Result:
+

Procedure returns a level graph created from input residual network.

+
+
struct::graph::op::TSPLocalSearching G C
+

Algorithm is a heuristic of local searching for Travelling Salesman Problem. For some +solution of TSP problem, it checks if it's possible to find a better solution. As TSP +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 2 approximation factor).

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected and complete graph with attributes "weight" set on each single edge.

+
List C (input)
+

A list of edges being Hamiltonian cycle, which is solution of TSP Problem for graph G.

+
+
Result:
+

Algorithm returns the best solution for TSP problem, it was able to find.

+
+

Note: The solution depends on the choosing of the beginning cycle C. It's not true that better cycle +assures that better solution will be found, but practise shows that we should give starting cycle with as small +sum of weights as possible.

+
struct::graph::op::TSPLocalSearching3Approx G C
+

Algorithm is a heuristic of local searching for Travelling Salesman Problem. For some +solution of TSP problem, it checks if it's possible to find a better solution. As TSP +is well known NP-Complete problem, so algorithm is a approximation algorithm (with 3 approximation factor).

+
+
Arguments:
+
+
Graph Object G (input)
+

Undirected and complete graph with attributes "weight" set on each single edge.

+
List C (input)
+

A list of edges being Hamiltonian cycle, which is solution of TSP Problem for graph G.

+
+
Result:
+

Algorithm returns the best solution for TSP problem, it was able to find.

+
+

Note: In practise 3-approximation algorithm turns out to be far more effective than 2-approximation, but it gives +worser approximation factor. Further heuristics of local searching (e.g. 4-approximation) doesn't give enough boost to +square the increase of approximation factor, so 2 and 3 approximations are mainly used.

+
struct::graph::op::createSquaredGraph G
+

X-Squared graph is a graph with the same set of nodes as input graph G, but a different set of edges. X-Squared graph +has edge (u,v), if and only if, the distance between u and v nodes is not greater than X and u != v.

+

Procedure for input graph G, returns its two-squared graph.

+

Note: Distances used in choosing new set of edges are considering the number of edges, not the sum of weights at edges.

+
struct::graph::op::createCompleteGraph G originalEdges
+

For input graph G procedure adds missing arcs to make it a complete graph. It also holds in +variable originalEdges the set of arcs that graph G possessed before that operation.

+
+
+

Background theory and terms

+

Shortest Path Problem

+
+
Definition (single-pair shortest path problem):
+

Formally, given a weighted graph (let V be the set of vertices, and E a set of edges), +and one vertice v of V, find a path P from v to a v' of V so that +the sum of weights on edges along the path is minimal among all paths connecting v to v'.

+
Generalizations:
+
    +

  • The single-source shortest path problem, in which we have to find shortest paths from a source vertex v to all other vertices in the graph.

    • +

  • The single-destination shortest path problem, in which we have to find shortest paths from all vertices in the graph to a single destination vertex v. This can be reduced to the single-source shortest path problem by reversing the edges in the graph.

    • +

  • The all-pairs shortest path problem, in which we have to find shortest paths between every pair of vertices v, v' in the graph.

    • +
+

Note: +The result of Shortest Path problem can be Shortest Path tree, which is a subgraph of a given (possibly weighted) graph constructed so that the +distance between a selected root node and all other nodes is minimal. It is a tree because if there are two paths between the root node and some +vertex v (i.e. a cycle), we can delete the last edge of the longer path without increasing the distance from the root node to any node in the subgraph.

+
+
+

Travelling Salesman Problem

+
+
Definition:
+

For given edge-weighted (weights on edges should be positive) graph the goal is to find the cycle that visits each node in graph +exactly once (Hamiltonian cycle).

+
Generalizations:
+
    +

  • Metric TSP - A very natural restriction of the TSP is to require that the distances between cities form a metric, i.e., +they satisfy the triangle inequality. That is, for any 3 cities A, B and C, the distance between A and C +must be at most the distance from A to B plus the distance from B to C. Most natural instances of TSP +satisfy this constraint.

    • +

  • Euclidean TSP - Euclidean TSP, or planar TSP, is the TSP with the distance being the ordinary Euclidean distance. +Euclidean TSP is a particular case of TSP with triangle inequality, since distances in plane obey triangle inequality. However, +it seems to be easier than general TSP with triangle inequality. For example, the minimum spanning tree of the graph associated +with an instance of Euclidean TSP is a Euclidean minimum spanning tree, and so can be computed in expected O(n log n) time for +n points (considerably less than the number of edges). This enables the simple 2-approximation algorithm for TSP with triangle +inequality above to operate more quickly.

    • +

  • Asymmetric TSP - In most cases, the distance between two nodes in the TSP network is the same in both directions. +The case where the distance from A to B is not equal to the distance from B to A is called asymmetric TSP. +A practical application of an asymmetric TSP is route optimisation using street-level routing (asymmetric due to one-way streets, +slip-roads and motorways).

    • +
+
+
+

Matching Problem

+
+
Definition:
+

Given a graph G = (V,E), a matching or edge-independent set M in G is a set of pairwise non-adjacent edges, +that is, no two edges share a common vertex. A vertex is matched if it is incident to an edge in the matching M. +Otherwise the vertex is unmatched.

+
Generalizations:
+
    +

  • Maximal matching - a matching M of a graph G with the property that if any edge not in M is added to M, +it is no longer a matching, that is, M is maximal if it is not a proper subset of any other matching in graph G. +In other words, a matching M of a graph G is maximal if every edge in G has a non-empty intersection with at least one edge in M.

    • +

  • Maximum matching - a matching that contains the largest possible number of edges. There may be many maximum matchings. +The matching number of a graph G is the size of a maximum matching. Note that every maximum matching is maximal, +but not every maximal matching is a maximum matching.

    • +

  • Perfect matching - a matching which matches all vertices of the graph. That is, every vertex of the graph is incident to exactly one +edge of the matching. Every perfect matching is maximum and hence maximal. In some literature, the term complete matching +is used. A perfect matching is also a minimum-size edge cover. Moreover, the size of a maximum matching is no larger than the +size of a minimum edge cover.

    • +

  • Near-perfect matching - a matching in which exactly one vertex is unmatched. This can only occur when the graph has an odd number of vertices, +and such a matching must be maximum. If, for every vertex in a graph, there is a near-perfect matching that omits only that vertex, the graph +is also called factor-critical.

    • +
+
Related terms:
+
    +

  • Alternating path - given a matching M, an alternating path is a path in which the edges belong alternatively +to the matching and not to the matching.

    • +

  • Augmenting path - given a matching M, an augmenting path is an alternating path that starts from +and ends on free (unmatched) vertices.

    • +
+
+
+

Cut Problems

+
+
Definition:
+

A cut is a partition of the vertices of a graph into two disjoint subsets. The cut-set of the cut is the +set of edges whose end points are in different subsets of the partition. Edges are said to be crossing the cut if they are in its cut-set.

+

Formally:

+
    +

  • a cut C = (S,T) is a partition of V of a graph G = (V, E).

    • +

  • an s-t cut C = (S,T) of a flow network N = (V, E) is a cut of N such that s is included in S +and t is included in T, where s and t are the source and the sink of N respectively.

    • +

  • The cut-set of a cut C = (S,T) is such set of edges from graph G = (V, E) that each edge (u, v) satisfies +condition that u is included in S and v is included in T.

    • +
+

In an unweighted undirected graph, the size or weight of a cut is the number of edges crossing the cut. In a weighted graph, +the same term is defined by the sum of the weights of the edges crossing the cut.

+

In a flow network, an s-t cut is a cut that requires the source and the sink to be in different subsets, +and its cut-set only consists of edges going from the source's side to the sink's side. The capacity of an s-t cut +is defined by the sum of capacity of each edge in the cut-set.

+

The cut of a graph can sometimes refer to its cut-set instead of the partition.

+
Generalizations:
+
    +

  • Minimum cut - A cut is minimum if the size of the cut is not larger than the size of any other cut.

    • +

  • Maximum cut - A cut is maximum if the size of the cut is not smaller than the size of any other cut.

    • +

  • Sparsest cut - The Sparsest cut problem is to bipartition the vertices so as to minimize the ratio of the number +of edges across the cut divided by the number of vertices in the smaller half of the partition.

    • +
+
+
+

K-Center Problem

+
+
Definitions:
+
+
Unweighted K-Center
+

For any set S ( which is subset of V ) and node v, let the connect(v,S) be the +cost of cheapest edge connecting v with any node in S. The goal is to find +such S, that |S| = k and max_v{connect(v,S)} is possibly small.

+

In other words, we can use it i.e. for finding best locations in the city ( nodes +of input graph ) for placing k buildings, such that those buildings will be as close +as possible to all other locations in town.

+
Weighted K-Center
+

The variation of unweighted k-center problem. Besides the fact graph is edge-weighted, +there are also weights on vertices of input graph G. We've got also restriction +W. The goal is to choose such set of nodes S ( which is a subset of V ), that it's +total weight is not greater than W and also function: max_v { min_u { cost(u,v) }} +has the smallest possible worth ( v is a node in V and u is a node in S ).

+
+
+
+

Flow Problems

+
+
Definitions:
+
    +

  • the maximum flow problem - the goal is to find a feasible flow through a single-source, single-sink flow network that is maximum. +The maximum flow problem can be seen as a special case of more complex network flow problems, such as the circulation problem. +The maximum value of an s-t flow is equal to the minimum capacity of an s-t cut in the network, as stated in the +max-flow min-cut theorem.

    +

    More formally for flow network G = (V,E), where for each edge (u, v) we have its throuhgput c(u,v) defined. As flow +F we define set of non-negative integer attributes f(u,v) assigned to edges, satisfying such conditions:

    +
      +

    1. for each edge (u, v) in G such condition should be satisfied: 0 <= f(u,v) <= c(u,v)

      2. +

    2. Network G has source node s such that the flow F is equal to the sum of outcoming flow decreased by the sum of incoming flow from that source node s.

      3. +

    3. Network G has sink node t such that the the -F value is equal to the sum of the incoming flow decreased by the sum of outcoming flow from that sink node t.

      4. +

    4. For each node that is not a source or sink the sum of incoming flow and sum of outcoming flow should be equal.

      5. +
    +
    • +

  • the minimum cost flow problem - the goal is finding the cheapest possible way of sending a certain amount of flow through a flow network.

    • +

  • blocking flow - a blocking flow for a residual network Gf we name such flow b in Gf that:

    +
      +

    1. Each path from sink to source is the shortest path in Gf.

      2. +

    2. Each shortest path in Gf contains an edge with fully used throughput in Gf+b.

      3. +
    +
    • +

  • residual network - for a flow network G and flow f residual network is built with those edges, which can +send larger flow. It contains only those edges, which can send flow larger than 0.

    • +

  • level network - it has the same set of nodes as residual graph, but has only those edges (u,v) from Gf +for which such equality is satisfied: distance(s,u)+1 = distance(s,v).

    • +

  • augmenting network - it is a modification of residual network considering the new +flow values. Structure stays unchanged but values of throughputs and costs at edges +are different.

    • +
+
+
+

Approximation algorithm

+
+
k-approximation algorithm:
+

Algorithm is a k-approximation, when for ALG (solution returned by algorithm) and +OPT (optimal solution), such inequality is true:

+
    +

  • for minimalization problems: ALG/OPT <= k

    • +

  • for maximalization problems: OPT/ALG <= k

    • +
+
+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: graph of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/matrix.html Index: embedded/www/tcllib/files/modules/struct/matrix.html ================================================================== --- embedded/www/tcllib/files/modules/struct/matrix.html +++ embedded/www/tcllib/files/modules/struct/matrix.html @@ -0,0 +1,553 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::matrix(n) 2.0.3 tcllib "Tcl Data Structures"

+

Name

+

struct::matrix - Create and manipulate matrix objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require struct::matrix ?2.0.3?
    • +
+ +
+
+

Description

+

A matrix is a rectangular collection of cells, i.e. organized in rows +and columns. Each cell contains exactly one value of arbitrary +form. The cells in the matrix are addressed by pairs of integer +numbers, with the first (left) number in the pair specifying the +column and the second (right) number specifying the row the cell is +in. These indices are counted from 0 upward. The special non-numeric +index end refers to the last row or column in the matrix, +depending on the context. Indices of the form +end-number are counted from the end of the row or +column, like they are for standard Tcl lists. Trying to access +non-existing cells causes an error.

+

The matrices here are created empty, i.e. they have neither rows nor +columns. The user then has to add rows and columns as needed by his +application. A specialty of this structure is the ability to export an +array-view onto its contents. Such can be used by tkTable, for +example, to link the matrix into the display.

+

The main command of the package is:

+
+
::struct::matrix ?matrixName? ?=|:=|as|deserialize source?
+

The command creates a new matrix object with an associated global Tcl +command whose name is matrixName. This command may be used to +invoke various operations on the matrix. It has the following general +form:

+
+
matrixName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If matrixName is not specified a unique name will be generated +by the package itself. If a source is specified the new matrix +will be initialized to it. For the operators =, :=, +and as the argument source is interpreted as the name of +another matrix object, and the assignment operator = will be +executed. For deserialize the source is a serialized +matrix object and deserialize will be executed.

+

In other words

+
+    ::struct::matrix mymatrix = b
+
+

is equivalent to

+
+    ::struct::matrix mymatrix
+    mymatrix = b
+
+

and

+
+    ::struct::matrix mymatrix deserialize $b
+
+

is equivalent to

+
+    ::struct::matrix mymatrix
+    mymatrix deserialize $b
+
+
+
+

The following commands are possible for matrix objects:

+
+
matrixName = sourcematrix
+

This is the assignment operator for matrix objects. It copies the matrix +contained in the matrix object sourcematrix over the matrix data in +matrixName. The old contents of matrixName are deleted by +this operation.

+

This operation is in effect equivalent to

+
+    matrixName deserialize [sourcematrix serialize]
+
+
+
matrixName --> destmatrix
+

This is the reverse assignment operator for matrix objects. It copies +the matrix contained in the matrix object matrixName over the matrix +data in the object destmatrix. +The old contents of destmatrix are deleted by this operation.

+

This operation is in effect equivalent to

+
+    destmatrix deserialize [matrixName serialize]
+
+
+
matrixName add column ?values?
+

Extends the matrix by one column and then acts like set column +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column.

+
matrixName add row ?values?
+

Extends the matrix by one row and then acts like set row (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row.

+
matrixName add columns n
+

Extends the matrix by n columns. The new cells will be set to +the empty string. The new columns are appended immediately behind the +last existing column. A value of n equal to or smaller than 0 is +not allowed.

+
matrixName add rows n
+

Extends the matrix by n rows. The new cells will be set to the +empty string. The new rows are appended immediately behind the last +existing row. A value of n equal to or smaller than 0 is not +allowed.

+
matrixName cells
+

Returns the number of cells currently managed by the matrix. This is +the product of rows and columns.

+
matrixName cellsize column row
+

Returns the length of the string representation of the value currently +contained in the addressed cell.

+
matrixName columns
+

Returns the number of columns currently managed by the matrix.

+
matrixName columnwidth column
+

Returns the length of the longest string representation of all the +values currently contained in the cells of the addressed column if +these are all spanning only one line. For cell values spanning +multiple lines the length of their longest line goes into the +computation.

+

Note: The command recognizes ANSI color control sequences +and excludes them from the width of a line, as they are logically of +zero width.

+
matrixName delete column column
+

Deletes the specified column from the matrix and shifts all columns +with higher indices one index down.

+
matrixName delete columns n
+

Deletes n columns from the right of the matrix. The value of +n has to satisfy the constraint +"0 < n < [matrixName columns]"

+
matrixName delete row row
+

Deletes the specified row from the matrix and shifts all row with +higher indices one index down.

+
matrixName delete rows n
+

Deletes n rows from the bottom of the matrix. The value of +n has to satisfy the constraint +"0 < n < [matrixName rows]"

+
matrixName deserialize serialization
+

This is the complement to serialize. It replaces matrix data +in matrixName with the matrix described by the serialization +value. The old contents of matrixName are deleted by this +operation.

+
matrixName destroy
+

Destroys the matrix, including its storage space and associated +command.

+
matrixName format 2string ?report?
+

Formats the matrix using the specified report object and returns the +string containing the result of this operation. The report has to +support the printmatrix method. If no report is +specified the system will use an internal report definition to format +the matrix.

+
matrixName format 2chan ??report? channel?
+

Formats the matrix using the specified report object and writes the +string containing the result of this operation into the channel. The +report has to support the printmatrix2channel method. If no +report is specified the system will use an internal report +definition to format the matrix. If no channel is specified the +system will use stdout.

+
matrixName get cell column row
+

Returns the value currently contained in the cell identified by row +and column index.

+
matrixName get column column
+

Returns a list containing the values from all cells in the column +identified by the index. The contents of the cell in row 0 are stored +as the first element of this list.

+
matrixName get rect column_tl row_tl column_br row_br
+

Returns a list of lists of cell values. The values stored in the +result come from the sub-matrix whose top-left and bottom-right cells +are specified by column_tl, row_tl and +column_br, row_br resp. Note that the following equations have +to be true: "column_tl <= column_br" and "row_tl <= +row_br". The result is organized as follows: The outer list is +the list of rows, its elements are lists representing a single +row. The row with the smallest index is the first element of the outer +list. The elements of the row lists represent the selected cell +values. The cell with the smallest index is the first element in each +row list.

+
matrixName get row row
+

Returns a list containing the values from all cells in the row +identified by the index. The contents of the cell in column 0 are +stored as the first element of this list.

+
matrixName insert column column ?values?
+

Extends the matrix by one column and then acts like set column +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is inserted just before the column specified by +the given index. This means, if column is less than or equal to +zero, then the new column is inserted at the beginning of the matrix, +before the first column. If column has the value end, +or if it is greater than or equal to the number of columns in the +matrix, then the new column is appended to the matrix, behind the last +column. The old column at the chosen index and all columns with higher +indices are shifted one index upward.

+
matrixName insert row row ?values?
+

Extends the matrix by one row and then acts like set row (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is inserted just before the row specified by the given index. This +means, if row is less than or equal to zero, then the new row is +inserted at the beginning of the matrix, before the first row. If +row has the value end, or if it is greater than or +equal to the number of rows in the matrix, then the new row is +appended to the matrix, behind the last row. The old row at that index +and all rows with higher indices are shifted one index upward.

+
matrixName link ?-transpose? arrayvar
+

Links the matrix to the specified array variable. This means that the +contents of all cells in the matrix is stored in the array too, with +all changes to the matrix propagated there too. The contents of the +cell (column,row) is stored in the array using the key +column,row. If the option -transpose is specified the +key row,column will be used instead. It is possible to link the +matrix to more than one array. Note that the link is bidirectional, +i.e. changes to the array are mirrored in the matrix too.

+
matrixName links
+

Returns a list containing the names of all array variables the matrix +was linked to through a call to method link.

+
matrixName rowheight row
+

Returns the height of the specified row in lines. This is the highest +number of lines spanned by a cell over all cells in the row.

+
matrixName rows
+

Returns the number of rows currently managed by the matrix.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
+

Searches the whole matrix for cells matching the pattern and +returns a list with all matches. Each item in the aforementioned list +is a list itself and contains the column and row index of the matching +cell, in this order. The results are ordered by column first and row +second, both times in ascending order. This means that matches to the +left and the top of the matrix come before matches to the right and +down.

+

The type of the pattern (string, glob, regular expression) is +determined by the option after the search keyword. If no +option is given it defaults to -exact.

+

If the option -nocase is specified the search will be +case-insensitive.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern
+

Like search all, but the search is restricted to the +specified column.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
+

Like search all, but the search is restricted to the +specified row.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern
+

Like search all, but the search is restricted to the +specified rectangular area of the matrix.

+
matrixName serialize ?column_tl row_tl column_br row_br?
+

This method serializes the sub-matrix spanned up by the rectangle +specification. In other words it returns a tcl value completely +describing that matrix. If no rectangle is specified the whole matrix +will be serialized. +This allows, for example, the transfer of matrix objects (or parts +thereof) over arbitrary channels, persistence, etc. +This method is also the basis for both the copy constructor and the +assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the matrix interface. This is what will enable us +to copy matrix data between different implementations of the same +interface.

+

The result is a list containing exactly three items.

+

The first two elements of the list specify the number of rows and +columns of the matrix, in that order. The values integer numbers +greater than or equal to zero.

+

The last element of the list contains the values of the matrix cells +we have serialized, in the form of a value like it is returned by the +get rect. However empty cells to the right and bottom of +the matrix can be left out of that value as the size information in +the serialization allows the receiver the creation of a matrix with +the proper size despite the missing values.

+
+    # A possible serialization for the matrix structure
+    #
+    # | a b d g |
+    # | c e     |
+    # | f       |
+    #
+    # is
+    #
+    # 3 4 {{a b d g} {c e} {f}}
+
+
+
matrixName set cell column row value
+

Sets the value in the cell identified by row and column index to the +data in the third argument.

+
matrixName set column column values
+

Sets the values in the cells identified by the column index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in row 0 and then upward. If there are less values in the +list than there are rows the remaining rows are set to the empty +string. If there are more values in the list than there are rows the +superfluous elements are ignored. The matrix is not extended by this +operation.

+
matrixName set rect column row values
+

Takes a list of lists of cell values and writes them into the +submatrix whose top-left cell is specified by the two indices. If the +sublists of the outerlist are not of equal length the shorter sublists +will be filled with empty strings to the length of the longest +sublist. If the submatrix specified by the top-left cell and the +number of rows and columns in the values extends beyond the +matrix we are modifying the over-extending parts of the values are +ignored, i.e. essentially cut off. This subcommand expects its input +in the format as returned by get rect.

+
matrixName set row row values
+

Sets the values in the cells identified by the row index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in column 0 and then upward. If there are less values in the +list than there are columns the remaining columns are set to the empty +string. If there are more values in the list than there are columns +the superfluous elements are ignored. The matrix is not extended by +this operation.

+
matrixName sort columns ?-increasing|-decreasing? row
+

Sorts the columns in the matrix using the data in the specified +row as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName sort rows ?-increasing|-decreasing? column
+

Sorts the rows in the matrix using the data in the specified +column as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName swap columns column_a column_b
+

Swaps the contents of the two specified columns.

+
matrixName swap rows row_a row_b
+

Swaps the contents of the two specified rows.

+
matrixName transpose
+

Transposes the contents of the matrix, i.e. swaps rows for columns and +vice versa.

+
matrixName unlink arrayvar
+

Removes the link between the matrix and the specified arrayvariable, +if there is one.

+
+
+

EXAMPLES

+

The examples below assume a 5x5 matrix M with the first row containing +the values 1 to 5, with 1 in the top-left cell. Each other row +contains the contents of the row above it, rotated by one cell to the +right.

+
+ % M get rect 0 0 4 4
+ {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
+
+
+ % M set rect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
+ % M get rect 0 0 4 4
+ {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
+
+

Assuming that the style definitions in the example section of the +manpage for the package report are loaded into the +interpreter now an example which formats a matrix into a tabular +report. The code filling the matrix with data is not shown. contains +useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % m format 2string r
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % r printmatrix m
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: matrix of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/matrix1.html Index: embedded/www/tcllib/files/modules/struct/matrix1.html ================================================================== --- embedded/www/tcllib/files/modules/struct/matrix1.html +++ embedded/www/tcllib/files/modules/struct/matrix1.html @@ -0,0 +1,441 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::matrix_v1(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::matrix_v1 - Create and manipulate matrix objects

+
+ + +

Description

+

The ::struct::matrix command creates a new matrix object with an +associated global Tcl command whose name is matrixName. This +command may be used to invoke various operations on the matrix. It has +the following general form:

+
+
matrixName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A matrix is a rectangular collection of cells, i.e. organized in rows +and columns. Each cell contains exactly one value of arbitrary +form. The cells in the matrix are addressed by pairs of integer +numbers, with the first (left) number in the pair specifying the +column and the second (right) number specifying the row the cell is +in. These indices are counted from 0 upward. The special non-numeric +index end refers to the last row or column in the matrix, +depending on the context. Indices of the form +end-number are counted from the end of the row or +column, like they are for standard Tcl lists. Trying to access +non-existing cells causes an error.

+

The matrices here are created empty, i.e. they have neither rows nor +columns. The user then has to add rows and columns as needed by his +application. A specialty of this structure is the ability to export an +array-view onto its contents. Such can be used by tkTable, for +example, to link the matrix into the display.

+

The following commands are possible for matrix objects:

+
+
matrixName add column ?values?
+

Extends the matrix by one column and then acts like setcolumn +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is appended immediately behind the last +existing column.

+
matrixName add row ?values?
+

Extends the matrix by one row and then acts like setrow (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is appended immediately behind the last existing row.

+
matrixName add columns n
+

Extends the matrix by n columns. The new cells will be set to +the empty string. The new columns are appended immediately behind the +last existing column. A value of n equal to or smaller than 0 is +not allowed.

+
matrixName add rows n
+

Extends the matrix by n rows. The new cells will be set to the +empty string. The new rows are appended immediately behind the last +existing row. A value of n equal to or smaller than 0 is not +allowed.

+
matrixName cells
+

Returns the number of cells currently managed by the matrix. This is +the product of rows and columns.

+
matrixName cellsize column row
+

Returns the length of the string representation of the value currently +contained in the addressed cell.

+
matrixName columns
+

Returns the number of columns currently managed by the matrix.

+
matrixName columnwidth column
+

Returns the length of the longest string representation of all the +values currently contained in the cells of the addressed column if +these are all spanning only one line. For cell values spanning +multiple lines the length of their longest line goes into the +computation.

+
matrixName delete column column
+

Deletes the specified column from the matrix and shifts all columns +with higher indices one index down.

+
matrixName delete row row
+

Deletes the specified row from the matrix and shifts all row with +higher indices one index down.

+
matrixName destroy
+

Destroys the matrix, including its storage space and associated +command.

+
matrixName format 2string ?report?
+

Formats the matrix using the specified report object and returns the +string containing the result of this operation. The report has to +support the printmatrix method. If no report is +specified the system will use an internal report definition to format +the matrix.

+
matrixName format 2chan ??report? channel?
+

Formats the matrix using the specified report object and writes the +string containing the result of this operation into the channel. The +report has to support the printmatrix2channel method. If no +report is specified the system will use an internal report +definition to format the matrix. If no channel is specified the +system will use stdout.

+
matrixName get cell column row
+

Returns the value currently contained in the cell identified by row +and column index.

+
matrixName get column column
+

Returns a list containing the values from all cells in the column +identified by the index. The contents of the cell in row 0 are stored +as the first element of this list.

+
matrixName get rect column_tl row_tl column_br row_br
+

Returns a list of lists of cell values. The values stored in the +result come from the sub-matrix whose top-left and bottom-right cells +are specified by column_tl, row_tl and +column_br, row_br resp. Note that the following equations have +to be true: "column_tl <= column_br" and "row_tl <= +row_br". The result is organized as follows: The outer list is +the list of rows, its elements are lists representing a single +row. The row with the smallest index is the first element of the outer +list. The elements of the row lists represent the selected cell +values. The cell with the smallest index is the first element in each +row list.

+
matrixName get row row
+

Returns a list containing the values from all cells in the row +identified by the index. The contents of the cell in column 0 are +stored as the first element of this list.

+
matrixName insert column column ?values?
+

Extends the matrix by one column and then acts like setcolumn +(see below) on this new column if there were values +supplied. Without values the new cells will be set to the empty +string. The new column is inserted just before the column specified by +the given index. This means, if column is less than or equal to +zero, then the new column is inserted at the beginning of the matrix, +before the first column. If column has the value end, +or if it is greater than or equal to the number of columns in the +matrix, then the new column is appended to the matrix, behind the last +column. The old column at the chosen index and all columns with higher +indices are shifted one index upward.

+
matrixName insert row row ?values?
+

Extends the matrix by one row and then acts like setrow (see +below) on this new row if there were values supplied. Without +values the new cells will be set to the empty string. The new +row is inserted just before the row specified by the given index. This +means, if row is less than or equal to zero, then the new row is +inserted at the beginning of the matrix, before the first row. If +row has the value end, or if it is greater than or +equal to the number of rows in the matrix, then the new row is +appended to the matrix, behind the last row. The old row at that index +and all rows with higher indices are shifted one index upward.

+
matrixName link ?-transpose? arrayvar
+

Links the matrix to the specified array variable. This means that the +contents of all cells in the matrix is stored in the array too, with +all changes to the matrix propagated there too. The contents of the +cell (column,row) is stored in the array using the key +column,row. If the option -transpose is specified the +key row,column will be used instead. It is possible to link the +matrix to more than one array. Note that the link is bidirectional, +i.e. changes to the array are mirrored in the matrix too.

+
matrixName links
+

Returns a list containing the names of all array variables the matrix +was linked to through a call to method link.

+
matrixName rowheight row
+

Returns the height of the specified row in lines. This is the highest +number of lines spanned by a cell over all cells in the row.

+
matrixName rows
+

Returns the number of rows currently managed by the matrix.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? all pattern
+

Searches the whole matrix for cells matching the pattern and +returns a list with all matches. Each item in the aforementioned list +is a list itself and contains the column and row index of the matching +cell, in this order. The results are ordered by column first and row +second, both times in ascending order. This means that matches to the +left and the top of the matrix come before matches to the right and +down.

+

The type of the pattern (string, glob, regular expression) is +determined by the option after the search keyword. If no +option is given it defaults to -exact.

+

If the option -nocase is specified the search will be +case-insensitive.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? column column pattern
+

Like search all, but the search is restricted to the +specified column.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? row row pattern
+

Like search all, but the search is restricted to the +specified row.

+
matrixName search ?-nocase? ?-exact|-glob|-regexp? rect column_tl row_tl column_br row_br pattern
+

Like search all, but the search is restricted to the +specified rectangular area of the matrix.

+
matrixName set cell column row value
+

Sets the value in the cell identified by row and column index to the +data in the third argument.

+
matrixName set column column values
+

Sets the values in the cells identified by the column index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in row 0 and then upward. If there are less values in the +list than there are rows the remaining rows are set to the empty +string. If there are more values in the list than there are rows the +superfluous elements are ignored. The matrix is not extended by this +operation.

+
matrixName set rect column row values
+

Takes a list of lists of cell values and writes them into the +submatrix whose top-left cell is specified by the two indices. If the +sublists of the outerlist are not of equal length the shorter sublists +will be filled with empty strings to the length of the longest +sublist. If the submatrix specified by the top-left cell and the +number of rows and columns in the values extends beyond the +matrix we are modifying the over-extending parts of the values are +ignored, i.e. essentially cut off. This subcommand expects its input +in the format as returned by getrect.

+
matrixName set row row values
+

Sets the values in the cells identified by the row index to the +elements of the list provided as the third argument. Each element of +the list is assigned to one cell, with the first element going into +the cell in column 0 and then upward. If there are less values in the +list than there are columns the remaining columns are set to the empty +string. If there are more values in the list than there are columns +the superfluous elements are ignored. The matrix is not extended by +this operation.

+
matrixName sort columns ?-increasing|-decreasing? row
+

Sorts the columns in the matrix using the data in the specified +row as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName sort rows ?-increasing|-decreasing? column
+

Sorts the rows in the matrix using the data in the specified +column as the key to sort by. The options -increasing +and -decreasing have the same meaning as for lsort. +If no option is specified -increasing is assumed.

+
matrixName swap columns column_a column_b
+

Swaps the contents of the two specified columns.

+
matrixName swap rows row_a row_b
+

Swaps the contents of the two specified rows.

+
matrixName unlink arrayvar
+

Removes the link between the matrix and the specified arrayvariable, +if there is one.

+
+
+

EXAMPLES

+

The examples below assume a 5x5 matrix M with the first row containing +the values 1 to 5, with 1 in the top-left cell. Each other row +contains the contents of the row above it, rotated by one cell to the +right.

+
+ % M getrect 0 0 4 4
+ {{1 2 3 4 5} {5 1 2 3 4} {4 5 1 2 3} {3 4 5 1 2} {2 3 4 5 1}}
+
+
+ % M setrect 1 1 {{0 0 0} {0 0 0} {0 0 0}}
+ % M getrect 0 0 4 4
+ {{1 2 3 4 5} {5 0 0 0 4} {4 0 0 0 3} {3 0 0 0 2} {2 3 4 5 1}}
+
+

Assuming that the style definitions in the example section of the +manpage for the package report are loaded into the +interpreter now an example which formats a matrix into a tabular +report. The code filling the matrix with data is not shown. contains +useful data.

+
+    % ::struct::matrix m
+    % # ... fill m with data, assume 5 columns
+    % ::report::report r 5 style captionedtable 1
+    % m format 2string r
+    +---+-------------------+-------+-------+--------+
+    |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
+    +---+-------------------+-------+-------+--------+
+    |001|CATCH return ok    |7      |13     |53.85   |
+    |002|CATCH return error |68     |91     |74.73   |
+    |003|CATCH no catch used|7      |14     |50.00   |
+    |004|IF if true numeric |12     |33     |36.36   |
+    |005|IF elseif          |15     |47     |31.91   |
+    |   |true numeric       |       |       |        |
+    +---+-------------------+-------+-------+--------+
+    %
+    % # alternate way of doing the above
+    % r printmatrix m
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: matrix of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/pool.html Index: embedded/www/tcllib/files/modules/struct/pool.html ================================================================== --- embedded/www/tcllib/files/modules/struct/pool.html +++ embedded/www/tcllib/files/modules/struct/pool.html @@ -0,0 +1,438 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::pool(n) 1.2.3 tcllib "Tcl Data Structures"

+

Name

+

struct::pool - Create and manipulate pool objects (of discrete items)

+
+ + +

Description

+

This package provides pool objects which can be used to manage +finite collections of discrete items.

+
+
::struct::pool ?poolName? ?maxsize?
+

Creates a new pool object. If no poolName is supplied, then the +new pool will be named poolX, where X is a positive integer. +The optional second argument maxsize has to be a positive +integer indicating the maximum size of the pool; this is the maximum +number of items the pool may hold. The default for this value is +10.

+

The pool object has an associated global Tcl command whose name is +poolName. This command may be used to invoke various +configuration operations on the report. It has the following general +form:

+
+
poolName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. See section POOL OBJECT COMMAND for a detailed +list of options and their behaviour.

+
+
+
+

POOLS AND ALLOCATION

+

The purpose of the pool command and the pool object command that it +generates, is to manage pools of discrete items. +Examples of a pool of discrete items are:

+
    +

  • the seats in a cinema, theatre, train etc.. for which visitors/travelers can make a reservation;

    • +

  • the dynamic IP-addresses that an ISP can dole out to subscribers;

    • +

  • a car rental's collection of cars, which can be rented by customers;

    • +

  • the class rooms in a school building, which need to be scheduled;

    • +

  • the database connections available to client-threads in a web-server application;

    • +

  • the books in a library that customers can borrow;

    • +

  • etc ...

    • +
+

The common denominator in the examples is that there is a more or less +fixed number of items (seats, IP-addresses, cars, ...) that are +supposed to be allocated on a more or less regular basis. An item can +be allocated only once at a time. An item that is allocated, must be +released before it can be re-allocated. While several items in a pool +are being allocated and released continuously, the total number of +items in the pool remains constant.

+

Keeping track of which items are allocated, and by whom, is the +purpose of the pool command and its subordinates.

+

Pool parlance: If we say that an item is +allocated, it means that the item is busy, +owned or occupied; it is not available anymore. If +an item is free, it is available. Deallocating an +item is equivalent to setting free or releasing an item. The person or +entity to which the item has been allotted is said to own the item.

+
+

ITEMS

+

Discrete items

+

The pool command is designed for +discrete items only. Note that there are pools where +allocation occurs on a non-discrete basis, for example computer +memory. There are also pools from which the shares that are doled out +are not expected to be returned, for example a charity fund or a pan +of soup from which you may receive a portion. Finally, there are even +pools from which nothing is ever allocated or returned, like a +swimming pool or a cesspool.

+

Unique item names

+

A pool cannot manage duplicate item names. Therefore, items in a pool +must have unique names.

+

Item equivalence

+

From the point of view of the manager of a pool, items are +equivalent. The manager of a pool is indifferent about which +entity/person occupies a given item. However, clients may have +preferences for a particular item, based on some item property they +know.

+

Preferences

+

A future owner may have a preference for a particular item. Preference +based allocation is supported (see the -prefer option to the +request subcommand). A preference for a particular item is most likely +to result from variability among features associated with the +items. Note that the pool commands themselves are not designed to +manage such item properties. If item properties play a role in an +application, they should be managed separately.

+
+

POOL OBJECT COMMAND

+

The following subcommands and corresponding arguments are available to +any pool object command.

+
+
poolName add itemName1 ?itemName2 itemName3 ...?
+

This command adds the items on the command line to the pool. If +duplicate item names occur on the command line, an error is raised. If +one or more of the items already exist in the pool, this also is +considered an error.

+
poolName clear ?-force?
+

Removes all items from the pool. If there are any allocated items at +the time when the command is invoked, an error is raised. This +behaviour may be modified through the -force argument. If it +is supplied on the command line, the pool will be cleared regardless +the allocation state of its items.

+
poolName destroy ?-force?
+

Destroys the pool data structure, all associated variables and the +associated pool object command. By default, the command checks whether +any items are still allocated and raises an error if such is the +case. This behaviour may be modified through the argument +-force. If it is supplied on the command line, the pool data +structure will be destroyed regardless allocation state of its items.

+
poolName info type ?arg?
+

Returns various information about the pool for further programmatic +use. The type argument indicates the type of information +requested. Only the type allocID uses an additional argument.

+
+
allocID itemName
+

returns the allocID of the item whose name is itemName. Free +items have an allocation id of -1.

+
allitems
+

returns a list of all items in the pool.

+
allocstate
+

Returns a list of key-value pairs, where the keys are the items and +the values are the corresponding allocation id's. Free items have an +allocation id of -1.

+
cursize
+

returns the current pool size, i.e. the number of items in the pool.

+
freeitems
+

returns a list of items that currently are not allocated.

+
maxsize
+

returns the maximum size of the pool.

+
+
poolName maxsize ?maxsize?
+

Sets or queries the maximum size of the pool, depending on whether the +maxsize argument is supplied or not. If maxsize is +supplied, the maximum size of the pool will be set to that value. If +no argument is supplied, the current maximum size of the pool is +returned. In this variant, the command is an alias for:

+

poolName info maxsize.

+

The maxsize argument has to be a positive integer.

+
poolName release itemName
+

Releases the item whose name is itemName that was allocated +previously. An error is raised if the item was not allocated at the +time when the command was issued.

+
poolName remove itemName ?-force?
+

Removes the item whose name is itemName from the pool. If the +item was allocated at the time when the command was invoked, an error +is raised. This behaviour may be modified through the optional +argument -force. If it is supplied on the command line, the +item will be removed regardless its allocation state.

+
poolName request itemVar ?options?
+

Handles a request for an item, taking into account a possible +preference for a particular item. There are two possible outcomes +depending on the availability of items:

+
    +

  1. The request is honoured, an item is allocated and the variable whose +name is passed with the argument itemVar will be set to the name +of the item that was allocated. The command returns 1.

    2. +

  2. The request is denied. No item is allocated. The variable whose name +is itemVar is not set. Attempts to read itemVar may raise an +error if the variable was not defined before issuing the request. The +command returns 0.

    3. +
+

The return values from this command are meant to be inspected. The +examples below show how to do this. Failure to check the return value +may result in erroneous behaviour. If no preference for a particular +item is supplied through the option -prefer (see below), then +all requests are honoured as long as items are available.

+

The following options are supported:

+
+
-allocID allocID
+

If the request is honoured, an item will be allocated to the entity +identified by allocID. If the allocation state of an item is queried, +it is this allocation ID that will be returned. If the option +-allocID is not supplied, the item will be given to and owned +by dummyID. Allocation id's may be anything except the value +-1, which is reserved for free items.

+
-prefer preferredItem
+

This option modifies the allocation strategy as follows: If the item +whose name is preferredItem is not allocated at the time when +the command is invoked, the request is honoured (return value is +1). If the item was allocated at the time when the command was +invoked, the request is denied (return value is 0).

+
+
+
+

EXAMPLES

+

Two examples are provided. The first one mimics a step by step +interactive tclsh session, where each step is explained. The second +example shows the usage in a server application that talks to a +back-end application.

+

Example 1

+

This example presents an interactive tclsh session which considers the +case of a Car rental's collection of cars. Ten steps explain its usage +in chronological order, from the creation of the pool, via the most +important stages in the usage of a pool, to the final destruction.

+

Note aside:

+

In this example, brand names are used to label the various +items. However, a brand name could be regarded as a property of an +item. Because the pool command is not designed to manage properties of +items, they need to be managed separately. In the latter case the +items should be labeled with more neutral names such as: car1, car2, +car3 , etc ... and a separate database or array should hold the brand +names associated with the car labels.

+
+     1. Load the package into an interpreter
+     % package require pool
+     0.1
+     2. Create a pool object called `CarPool' with a maximum size of 55 items (cars):
+     % pool CarPool 55
+     CarPool
+     4. Add items to the pool:
+     % CarPool add Toyota Trabant Chrysler1 Chrysler2 Volkswagen
+     5. Somebody crashed the Toyota. Remove it from the pool as follows:
+     % CarPool remove Toyota
+     6. Acquired a new car for the pool. Add it as follows:
+     % CarPool add Nissan
+     7. Check whether the pool was adjusted correctly:
+     % CarPool info allitems
+     Trabant Chrysler1 Chrysler2 Volkswagen Nissan
+
+

Suspend the interactive session temporarily, and show the programmatic +use of the request subcommand:

+
+     # Mrs. Swift needs a car. She doesn't have a preference for a
+     # particular car. We'll issue a request on her behalf as follows:
+     if { [CarPool request car -allocID "Mrs. Swift"] }  {
+         # request was honoured, process the variable `car'
+         puts "$car has been allocated to [CarPool info allocID $car]."
+     } else {
+         # request was denied
+          puts "No car available."
+     }
+
+

Note how the if command uses the value returned by the +request subcommand.

+
+     # Suppose Mr. Wiggly has a preference for the Trabant:
+     if { [CarPool request car -allocID "Mr. Wiggly" -prefer Trabant] }  {
+         # request was honoured, process the variable `car'
+         puts "$car has been allocated to [CarPool info allocID $car]."
+     } else {
+         # request was denied
+          puts "The Trabant was not available."
+     }
+
+

Resume the interactive session:

+
+     8. When the car is returned then you can render it available by:
+     % CarPool release Trabant
+     9. When done, you delete the pool.
+     % CarPool destroy
+     Couldn't destroy `CarPool' because some items are still allocated.
+     Oops, forgot that Mrs. Swift still occupies a car.
+     10. We force the destruction of the pool as follows:
+     % CarPool destroy -force
+
+

Example 2

+

This example describes the case from which the author's need for pool +management originated. It is an example of a server application that +receives requests from client applications. The client requests are +dispatched onto a back-end application before being returned to the +client application. In many cases there are a few equivalent instances +of back-end applications to which a client request may be passed +along. The file descriptors that identify the channels to these +back-end instances make up a pool of connections. A particular +connection may be allocated to just one client request at a time.

+
+     # Create the pool of connections (pipes)
+     set maxpipes 10
+     pool Pipes $maxpipes
+     for {set i 0} {$i < $maxpipes} {incr i} {
+         set fd [open "|backendApplication" w+]
+         Pipes add $fd
+     }
+     # A client request comes in. The request is identified as `clientX'.
+     # Dispatch it onto an instance of a back-end application
+     if { [Pipes request fd -allocID clientX] } {
+         # a connection was allocated
+         # communicate to the back-end application via the variable `fd'
+         puts $fd "someInstruction"
+         # ...... etc.
+     } else {
+         # all connections are currently occupied
+         # store the client request in a queue for later processing,
+         # or return a 'Server busy' message to the client.
+     }
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: pool of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/prioqueue.html Index: embedded/www/tcllib/files/modules/struct/prioqueue.html ================================================================== --- embedded/www/tcllib/files/modules/struct/prioqueue.html +++ embedded/www/tcllib/files/modules/struct/prioqueue.html @@ -0,0 +1,215 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::prioqueue(n) 1.4 tcllib "Tcl Data Structures"

+

Name

+

struct::prioqueue - Create and manipulate prioqueue objects

+
+ + +

Description

+

This package implements a simple priority queue using nested tcl lists.

+

The command ::struct::prioqueue creates a new priority queue +with default priority key type -integer. This means that keys +given to the put subcommand must have this type.

+

This also sets the priority ordering. For key types -ascii and +-dictionary the data is sorted in ascending order (as with +lsort -increasing), thereas for -integer and +-real the data is sorted in descending order (as with +lsort -decreasing).

+

Prioqueue names are unrestricted, but may be recognized as options if +no priority type is given.

+
+
::struct::prioqueue ?-ascii|-dictionary|-integer|-real? ?prioqueueName?
+

The ::struct::prioqueue command creates a new prioqueue object +with an associated global Tcl command whose name is +prioqueueName. This command may be used to invoke various +operations on the prioqueue. It has the following general form:

+
prioqueueName option ?arg arg ...?
+

option and the args determine the exact behavior of the +command. The following commands are possible for prioqueue objects:

+
prioqueueName clear
+

Remove all items from the prioqueue.

+
prioqueueName remove item
+

Remove the selected item from this priority queue.

+
prioqueueName destroy
+

Destroy the prioqueue, including its storage space and associated +command.

+
prioqueueName get ?count?
+

Return the front count items of the prioqueue (but not their +priorities) and remove them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the prioqueue, this command will throw an +error.

+
prioqueueName peek ?count?
+

Return the front count items of the prioqueue (but not their +priorities), without removing them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the queue, this command will throw an +error.

+
prioqueueName peekpriority ?count?
+

Return the front count items priority keys, without removing +them from the prioqueue. +If count is not specified, it defaults to 1. If count is +1, the result is a simple string; otherwise, it is a list. If +specified, count must be greater than or equal to 1. If there +are no or too few items in the queue, this command will throw an +error.

+
prioqueueName put item prio ?item prio ...?
+

Put the item or items specified into the prioqueue. prio +must be a valid priority key for this type of prioqueue, otherwise an +error is thrown and no item is added. Items are inserted at their +priority ranking. Items with equal priority are added in the order +they were added.

+
prioqueueName size
+

Return the number of items in the prioqueue.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: prioqueue of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/queue.html Index: embedded/www/tcllib/files/modules/struct/queue.html ================================================================== --- embedded/www/tcllib/files/modules/struct/queue.html +++ embedded/www/tcllib/files/modules/struct/queue.html @@ -0,0 +1,194 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::queue(n) 1.4.5 tcllib "Tcl Data Structures"

+

Name

+

struct::queue - Create and manipulate queue objects

+
+ + +

Description

+

The ::struct namespace contains a commands for processing +finite queues.

+

It exports a single command, ::struct::queue. All functionality +provided here can be reached through a subcommand of this command.

+

Note: As of version 1.4.1 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+

The ::struct::queue command creates a new queue object with an +associated global Tcl command whose name is queueName. This +command may be used to invoke various operations on the queue. It has +the following general form:

+
+
queueName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. The following commands are possible for queue objects:

+
queueName clear
+

Remove all items from the queue.

+
queueName destroy
+

Destroy the queue, including its storage space and associated command.

+
queueName get ?count?
+

Return the front count items of the queue and remove them from +the queue. If count is not specified, it defaults to 1. If +count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enough items in the queue to fulfull the request, +this command will throw an error.

+
queueName peek ?count?
+

Return the front count items of the queue, without removing them +from the queue. If count is not specified, it defaults to 1. +If count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enough items in the queue to fulfull the request, +this command will throw an error.

+
queueName put item ?item ...?
+

Put the item or items specified into the queue. If more than +one item is given, they will be added in the order they are +listed.

+
queueName unget item
+

Put the item into the queue, at the front, i.e. before any other +items already in the queue. This makes this operation the complement +to the method get.

+
queueName size
+

Return the number of items in the queue.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: queue of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/record.html Index: embedded/www/tcllib/files/modules/struct/record.html ================================================================== --- embedded/www/tcllib/files/modules/struct/record.html +++ embedded/www/tcllib/files/modules/struct/record.html @@ -0,0 +1,424 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::record(n) 1.2.1 tcllib "Tcl Data Structures"

+

Name

+

struct::record - Define and create records (similar to 'C' structures)

+
+ + +

Description

+

The ::struct::record package provides a mechanism to group variables together +as one data structure, similar to a 'C' structure. The members of a +record can be variables or other records. However, a record can not contain circular +record, i.e. records that contain the same record as a +member.

+

This package was structured so that it is very similar to how Tk objects work. Each record +definition creates a record object that encompasses that definition. Subsequently, that +record object can create instances of that record. These instances can then +be manipulated with the cget and configure methods.

+

The package only contains one top level command, but several sub commands (see below). It also obeys the namespace in which the record was define, hence the objects returned are fully qualified.

+
+
record define recordName recordMembers ?instanceName1 instanceName2 ...?
+

Defines a record. recordName is the name of the record, and is also +used as an object command. This object command is used to create instances of the +record definition. recordMembers are the members of +the record that make up the record definition. These are variables +and other record. If optional instanceName args are given, then an instance +is generated after the definition is created for each instanceName.

+
record show record
+

Returns a list of records that have been defined.

+
record show instances recordName
+

Returns the instances that have been instantiated by +recordName.

+
record show members recordName
+

Returns the members that are defined for +record recordName. It returns the same format as how the +records were defined.

+
record show values instanceName
+

Returns a list of values that are set for the instance +instanceName. The output is a list of key/value pairs. If there +are nested records, then the values of the nested records will +itself be a list.

+
record exists record recordName
+

Tests for the existence of a record with the +name recordName.

+
record exists instance instanceName
+

Tests for the existence of a instance with the +name instanceName.

+
record delete record recordName
+

Deletes recordName, and all instances of recordName. It will return +an error if the record does not exist.

+
record delete instance instanceName
+

Deletes instance with the name of instanceName. It +will return an error if the instance does not exist.

+
+
+

RECORD MEMBERS

+

Record members can either be variables, or other records, However, the +same record can not be nested witin itself (circular). To define a +nested record, you need to specify the record keyword, along +the with name of the record, and the name of the instance of that +nested record. For example, it would look like this:

+
+# this is the nested record
+record define mynestedrecord {
+    nest1
+    nest2
+}
+# This is the main record
+record define myrecord {
+    mem1
+    mem2
+    {record mynestedrecord mem3}
+}
+
+

You can also assign default or initial values to the members of a record, +by enclosing the member entry in braces:

+
+record define myrecord {
+    mem1
+    {mem2 5}
+}
+
+

All instances created from this record definition, will initially have 5 as +the value for mem2. If no default is given, then the value will be the empty string.

+

Getting Values

+

To get a value of a member, there are several ways to do this.

+
    +

  1. To get a member value, then use the instance built-in cget method:

    +

    instanceName cget -mem1

    2. +

  2. To get multiple member values, you can specify them all in one command:

    +

    instanceName cget -mem1 -mem2

    3. +

  3. To get a list of the key/value of all of the members, there are 3 ways:

    +

    - instanceName cget

    +

    - instanceName configure

    +

    - instanceName

    4. +

  4. To get a value of a nested member, then use the dot notation:

    +

    instanceName cget -mem3.nest1

    5. +
+

Setting Values

+

To set a value of a member, there are several ways to do this.

+
    +

  1. To set a member value, then use the instance built-in configure method:

    +

    instanceName configure -mem1 val1

    2. +

  2. To set multiple member values, you can specify them all in one command:

    +

    instanceName configure -mem1 va1 -mem2 val2

    3. +

  3. To set a value of a nested member, then use the dot notation:

    +

    instanceName configure -mem3.nest1 value

    4. +
+

Alias access

+

In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed. However, +there was a concensus to make the interface more Tcl like, which made sense. However, the original alias access still +exists. It might prove to be helpful to some.

+

Basically, for every member of every instance, an alias is created. This alias is used to get and set values for that +member. An example will illustrate the point, using the above defined records:

+
+# Create an instance first
+% myrecord inst1
+::inst1
+% # To get a member of an instance, just use the
+% # alias (it behaves like a Tcl command):
+% inst1.mem1
+%
+% # To set a member via the alias, just include
+% # a value (optionally the equal sign - syntactic sugar)
+% inst1.mem1 = 5
+5
+% inst1.mem1
+5
+% # For nested records, just continue with the
+% # dot notation (note no equal sign)
+% inst1.mem3.nest1 10
+10
+% inst1.mem3.nest1
+10
+% # just the instance by itself gives all
+% # member/values pairs for that instance
+% inst1
+-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
+% # and to get all members within the nested record
+% inst1.mem3
+-nest1 10 -nest2 {}
+%
+
+
+

RECORD COMMAND

+

The following subcommands and corresponding arguments are available to any +record command:

+
+
recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
+

Using the recordName object command that was created from the record definition, +instances of the record definition can be created. Once a instance is +created, then it inherits the members of the record definition, very +similar to how objects work. During instance generation, an object command for the instance +is created as well, using instanceName. This object command is used +to access the data members of the instance. During the instantiation, values for +that instance can be given, but all values must be given, and be given +in key/value pairs. Nested records, need to be in list format.

+

Optionally, #auto can be used in place of instanceName. When #auto is used, +then a instance name will automatically be generated, of the form recordName<integer>, where +<integer> is a unique integer (starting at 0) that is generated.

+
+
+

INSTANCE COMMAND

+

The following subcommands and corresponding arguments are available to +any record instance command:

+
+
instanceName cget ?-member1 -member2 ...?
+

Each instance has the sub command cget associated with it. This +is very similar to how Tk widget's cget command works. It queries +the values of the member for that particular instance. If +no arguments are given, then a key/value list is returned.

+
instanceName configure ?-member1 value1 -member2 value2 ...?
+

Each instance has the sub command configure associated with it. This +is very similar to how Tk widget's configure command works. It sets +the values of the particular member for that particular instance. If +no arguments are given, then a key/value list is returned.

+
+
+

EXAMPLES

+

Two examples are provided to give an good illustration on how to use +this package.

+

Example 1

+

Probably the most obvious example would be to hold contact information, +such as addresses, phone numbers, comments, etc. Since a person can have +multiple phone numbers, multiple email addresses, etc, we will use nested +records to define these. So, the first thing we do is define the nested +records:

+
+##
+##  This is an interactive example, to see what is
+##  returned by each command as well.
+##
+% namespace import ::struct::record::*
+% # define a nested record. Notice that country has default 'USA'.
+% record define locations {
+    street
+    street2
+    city
+    state
+    zipcode
+    {country USA}
+    phone
+}
+::locations
+% # Define the main record. Notice that it uses the location record twice.
+% record define contacts {
+    first
+    middle
+    last
+    {record locations home}
+    {record locations work}
+}
+::contacts
+% # Create an instance for the contacts record.
+% contacts cont1
+::cont1
+% # Display some introspection values
+% record show records
+::contacts ::locations
+% #
+% record show values cont1
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% #
+% record show instances contacts
+::cont1
+% #
+% cont1 config
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% #
+% cont1 cget
+-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
+% # copy one record to another record
+% record define contacts2 [record show members contacts]
+::contacts2
+% record show members contacts2
+first middle last {record locations home} {record locations work}
+% record show members contacts
+first middle last {record locations home} {record locations work}
+%
+
+

Example 1

+

This next example just illustrates a simple linked list

+
+% # define a very simple record for linked list
+% record define llist {
+    value
+    next
+}
+::llist
+% llist lstart
+::lstart
+% lstart config -value 1 -next [llist #auto]
+% [lstart cget -next] config -value 2 -next [llist #auto]
+% [[lstart cget -next] cget -next] config -value 3 -next "end"
+% set next lstart
+lstart
+% while 1 {
+lappend values [$next cget -value]
+set next [$next cget -next]
+if {[string match "end" $next]} {break}
+}
+% puts "$values"
+1 2 3
+% # cleanup linked list
+% # We could just use delete record llist also
+% foreach I [record show instances llist] {
+record delete instance $I
+}
+% record show instances llist
+%
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: record of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/skiplist.html Index: embedded/www/tcllib/files/modules/struct/skiplist.html ================================================================== --- embedded/www/tcllib/files/modules/struct/skiplist.html +++ embedded/www/tcllib/files/modules/struct/skiplist.html @@ -0,0 +1,193 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::skiplist(n) 1.3 tcllib "Tcl Data Structures"

+

Name

+

struct::skiplist - Create and manipulate skiplists

+
+ + +

Description

+

The ::struct::skiplist command creates a new skiplist object +with an associated global Tcl command whose name is +skiplistName. This command may be used to invoke various +operations on the skiplist. It has the following general form:

+
+
skiplistName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

Skip lists are an alternative data structure to binary trees. They can +be used to maintain ordered lists over any sequence of insertions and +deletions. Skip lists use randomness to achieve probabilistic +balancing, and as a result the algorithms for insertion and deletion +in skip lists are much simpler and faster than those for binary trees.

+

To read more about skip lists see Pugh, William. +Skip lists: a probabilistic alternative to balanced trees +In: Communications of the ACM, June 1990, 33(6) 668-676.

+

Currently, the key can be either a number or a string, and comparisons +are performed with the built in greater than operator. +The following commands are possible for skiplist objects:

+
+
skiplistName delete node ?node...?
+

Remove the specified nodes from the skiplist.

+
skiplistName destroy
+

Destroy the skiplist, including its storage space and associated command.

+
skiplistName insert key value
+

Insert a node with the given key and value into the +skiplist. If a node with that key already exists, then the that node's +value is updated and its node level is returned. Otherwise a new node +is created and 0 is returned.

+
skiplistName search node ?-key key?
+

Search for a given key in a skiplist. If not found then 0 is returned. +If found, then a two element list of 1 followed by the node's value is retuned.

+
skiplistName size
+

Return a count of the number of nodes in the skiplist.

+
skiplistName walk cmd
+

Walk the skiplist from the first node to the last. At each node, the +command cmd will be evaluated with the key and value of the +current node appended.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: skiplist of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/stack.html Index: embedded/www/tcllib/files/modules/struct/stack.html ================================================================== --- embedded/www/tcllib/files/modules/struct/stack.html +++ embedded/www/tcllib/files/modules/struct/stack.html @@ -0,0 +1,208 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::stack(n) 1.5.3 tcllib "Tcl Data Structures"

+

Name

+

struct::stack - Create and manipulate stack objects

+
+ + +

Description

+

The ::struct namespace contains a commands for processing +finite stacks.

+

It exports a single command, ::struct::stack. All functionality +provided here can be reached through a subcommand of this command.

+

Note: As of version 1.3.3 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+

The ::struct::stack command creates a new stack object with an +associated global Tcl command whose name is stackName. This +command may be used to invoke various operations on the stack. It has +the following general form:

+
+
stackName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command. The following commands are possible for stack objects:

+
stackName clear
+

Remove all items from the stack.

+
stackName destroy
+

Destroy the stack, including its storage space and associated command.

+
stackName get
+

Returns the whole contents of the stack as a list, without removing +them from the stack.

+
stackName getr
+

A variant of get, which returns the contents in reversed order.

+
stackName peek ?count?
+

Return the top count items of the stack, without removing them from +the stack. If count is not specified, it defaults to 1. If +count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enoughs items on the stack to fulfull the request, +this command will throw an error.

+
stackName peekr ?count?
+

A variant of peek, which returns the items in reversed order.

+
stackName trim ?newsize?
+

Shrinks the stack to contain at most newsize elements and +returns a list containing the elements which were removed. Nothing is +done if the stack is already at the specified size, or smaller. In +that case the result is the empty list.

+
stackName trim* ?newsize?
+

A variant of trim which performs the shrinking, but does not +return the removed elements.

+
stackName pop ?count?
+

Return the top count items of the stack, and remove them +from the stack. If count is not specified, it defaults to 1. +If count is 1, the result is a simple string; otherwise, it is a +list. If specified, count must be greater than or equal to 1. +If there are not enoughs items on the stack to fulfull the request, +this command will throw an error.

+
stackName push item ?item...?
+

Push the item or items specified onto the stack. If more than +one item is given, they will be pushed in the order they are +listed.

+
stackName size
+

Return the number of items on the stack.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: stack of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+
ADDED embedded/www/tcllib/files/modules/struct/struct_list.html Index: embedded/www/tcllib/files/modules/struct/struct_list.html ================================================================== --- embedded/www/tcllib/files/modules/struct/struct_list.html +++ embedded/www/tcllib/files/modules/struct/struct_list.html @@ -0,0 +1,696 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::list(n) 1.8.3 tcllib "Tcl Data Structures"

+

Name

+

struct::list - Procedures for manipulating lists

+
+ + +

Description

+

The ::struct::list namespace contains several useful commands +for processing Tcl lists. Generally speaking, they implement +algorithms more complex or specialized than the ones provided by Tcl +itself.

+

It exports only a single command, struct::list. All +functionality provided here can be reached through a subcommand of +this command.

+
+

COMMANDS

+
+
::struct::list longestCommonSubsequence sequence1 sequence2 ?maxOccurs?
+

Returns the longest common subsequence of elements in the two lists +sequence1 and sequence2. If the maxOccurs parameter +is provided, the common subsequence is restricted to elements that +occur no more than maxOccurs times in sequence2.

+

The return value is a list of two lists of equal length. The first +sublist is of indices into sequence1, and the second sublist is +of indices into sequence2. Each corresponding pair of indices +corresponds to equal elements in the sequences; the sequence returned +is the longest possible.

+
::struct::list longestCommonSubsequence2 sequence1 sequence2 ?maxOccurs?
+

Returns an approximation to the longest common sequence of elements in +the two lists sequence1 and sequence2. +If the maxOccurs parameter is omitted, the subsequence computed +is exactly the longest common subsequence; otherwise, the longest +common subsequence is approximated by first determining the longest +common sequence of only those elements that occur no more than +maxOccurs times in sequence2, and then using that result +to align the two lists, determining the longest common subsequences of +the sublists between the two elements.

+

As with longestCommonSubsequence, the return value is a list +of two lists of equal length. The first sublist is of indices into +sequence1, and the second sublist is of indices into +sequence2. Each corresponding pair of indices corresponds to +equal elements in the sequences. The sequence approximates the +longest common subsequence.

+
::struct::list lcsInvert lcsData len1 len2
+

This command takes a description of a longest common subsequence +(lcsData), inverts it, and returns the result. Inversion means +here that as the input describes which parts of the two sequences are +identical the output describes the differences instead.

+

To be fully defined the lengths of the two sequences have to be known +and are specified through len1 and len2.

+

The result is a list where each element describes one chunk of the +differences between the two sequences. This description is a list +containing three elements, a type and two pairs of indices into +sequence1 and sequence2 respectively, in this order. +The type can be one of three values:

+
+
added
+

Describes an addition. I.e. items which are missing in sequence1 +can be found in sequence2. +The pair of indices into sequence1 describes where the added +range had been expected to be in sequence1. The first index +refers to the item just before the added range, and the second index +refers to the item just after the added range. +The pair of indices into sequence2 describes the range of items +which has been added to it. The first index refers to the first item +in the range, and the second index refers to the last item in the +range.

+
deleted
+

Describes a deletion. I.e. items which are in sequence1 are +missing from sequence2. +The pair of indices into sequence1 describes the range of items +which has been deleted. The first index refers to the first item in +the range, and the second index refers to the last item in the range. +The pair of indices into sequence2 describes where the deleted +range had been expected to be in sequence2. The first index +refers to the item just before the deleted range, and the second index +refers to the item just after the deleted range.

+
changed
+

Describes a general change. I.e a range of items in sequence1 +has been replaced by a different range of items in sequence2. +The pair of indices into sequence1 describes the range of items +which has been replaced. The first index refers to the first item in +the range, and the second index refers to the last item in the range. +The pair of indices into sequence2 describes the range of items +replacing the original range. Again the first index refers to the +first item in the range, and the second index refers to the last item +in the range.

+
+
+    sequence 1 = {a b r a c a d a b r a}
+    lcs 1      =   {1 2   4 5     8 9 10}
+    lcs 2      =   {0 1   3 4     5 6 7}
+    sequence 2 =   {b r i c a     b r a c}
+    Inversion  = {{deleted  {0  0} {-1 0}}
+                  {changed  {3  3}  {2 2}}
+                  {deleted  {6  7}  {4 5}}
+                  {added   {10 11}  {8 8}}}
+
+

Notes:

+
    +

  • An index of -1 in a deleted chunk refers to just before +the first element of the second sequence.

    • +

  • Also an index equal to the length of the first sequence in an +added chunk refers to just behind the end of the sequence.

    • +
+
::struct::list lcsInvert2 lcs1 lcs2 len1 len2
+

Similar to lcsInvert. Instead of directly taking the result +of a call to longestCommonSubsequence this subcommand expects +the indices for the two sequences in two separate lists.

+
::struct::list lcsInvertMerge lcsData len1 len2
+

Similar to lcsInvert. It returns essentially the same +structure as that command, except that it may contain chunks of type +unchanged too.

+

These new chunks describe the parts which are unchanged between the +two sequences. This means that the result of this command describes +both the changed and unchanged parts of the two sequences in one +structure.

+
+    sequence 1 = {a b r a c a d a b r a}
+    lcs 1      =   {1 2   4 5     8 9 10}
+    lcs 2      =   {0 1   3 4     5 6 7}
+    sequence 2 =   {b r i c a     b r a c}
+    Inversion/Merge  = {{deleted   {0  0} {-1 0}}
+                        {unchanged {1  2}  {0 1}}
+                        {changed   {3  3}  {2 2}}
+                        {unchanged {4  5}  {3 4}}
+                        {deleted   {6  7}  {4 5}}
+                        {unchanged {8 10}  {5 7}}
+                        {added    {10 11}  {8 8}}}
+
+
+
::struct::list lcsInvertMerge2 lcs1 lcs2 len1 len2
+

Similar to lcsInvertMerge. Instead of directly taking the +result of a call to longestCommonSubsequence this subcommand +expects the indices for the two sequences in two separate lists.

+
::struct::list reverse sequence
+

The subcommand takes a single sequence as argument and returns a new +sequence containing the elements of the input sequence in reverse +order.

+
::struct::list shuffle list
+

The subcommand takes a list and returns a copy of that list +with the elements it contains in random order. Every possible +ordering of elements is equally likely to be generated. The +Fisher-Yates shuffling algorithm is used internally.

+
::struct::list assign sequence varname ?varname?...
+

The subcommand assigns the first n elements of the input +sequence to the one or more variables whose names were listed +after the sequence, where n is the number of specified +variables.

+

If there are more variables specified than there are elements in the +sequence the empty string will be assigned to the superfluous +variables.

+

If there are more elements in the sequence than variable names +specified the subcommand returns a list containing the unassigned +elements. Else an empty list is returned.

+
+    tclsh> ::struct::list assign {a b c d e} foo bar
+    c d e
+    tclsh> set foo
+    a
+    tclsh> set bar
+    b
+
+
+
::struct::list flatten ?-full? ?--? sequence
+

The subcommand takes a single sequence and returns a new +sequence where one level of nesting was removed from the input +sequence. In other words, the sublists in the input sequence are +replaced by their elements.

+

The subcommand will remove any nesting it finds if the option +-full is specified.

+
+    tclsh> ::struct::list flatten {1 2 3 {4 5} {6 7} {{8 9}} 10}
+    1 2 3 4 5 6 7 {8 9} 10
+    tclsh> ::struct::list flatten -full {1 2 3 {4 5} {6 7} {{8 9}} 10}
+    1 2 3 4 5 6 7 8 9 10
+
+
+
::struct::list map sequence cmdprefix
+

The subcommand takes a sequence to operate on and a command +prefix (cmdprefix) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of the results of that application.

+

The command prefix will be evaluated with a single word appended to +it. The evaluation takes place in the context of the caller of the +subcommand.

+
+    tclsh> # squaring all elements in a list
+    tclsh> proc sqr {x} {expr {$x*$x}}
+    tclsh> ::struct::list map {1 2 3 4 5} sqr
+    1 4 9 16 25
+    tclsh> # Retrieving the second column from a matrix
+    tclsh> # given as list of lists.
+    tclsh> proc projection {n list} {::lindex $list $n}
+    tclsh> ::struct::list map {{a b c} {1 2 3} {d f g}} {projection 1}
+    b 2 f
+
+
+
::struct::list mapfor var sequence script
+

The subcommand takes a sequence to operate on and a tcl script, +applies the script to each element of the sequence and returns a sequence +consisting of the results of that application.

+

The script will be evaluated as is, and has access to the current list element +through the specified iteration variable var. The evaluation takes place +in the context of the caller of the subcommand.

+
+    tclsh> # squaring all elements in a list
+    tclsh> ::struct::list mapfor x {1 2 3 4 5} {
+	expr {$x * $x}
+    }
+    1 4 9 16 25
+    tclsh> # Retrieving the second column from a matrix
+    tclsh> # given as list of lists.
+    tclsh> ::struct::list mapfor x {{a b c} {1 2 3} {d f g}} {
+	lindex $x 1
+    }
+    b 2 f
+
+
+
::struct::list filter sequence cmdprefix
+

The subcommand takes a sequence to operate on and a command +prefix (cmdprefix) specifying an operation, applies the command +prefix to each element of the sequence and returns a sequence +consisting of all elements of the sequence for which the command +prefix returned true. +In other words, this command filters out all elements of the input +sequence which fail the test the cmdprefix represents, and +returns the remaining elements.

+

The command prefix will be evaluated with a single word appended to +it. The evaluation takes place in the context of the caller of the +subcommand.

+
+    tclsh> # removing all odd numbers from the input
+    tclsh> proc even {x} {expr {($x % 2) == 0}}
+    tclsh> ::struct::list filter {1 2 3 4 5} even
+    2 4
+
+

Note: The filter is a specialized application of +fold where the result is extended with the current item or +not, depending o nthe result of the test.

+
::struct::list filterfor var sequence expr
+

The subcommand takes a sequence to operate on and a tcl expression +(expr) specifying a condition, applies the conditionto each element +of the sequence and returns a sequence consisting of all elements of the +sequence for which the expression returned true. +In other words, this command filters out all elements of the input +sequence which fail the test the condition expr represents, and +returns the remaining elements.

+

The expression will be evaluated as is, and has access to the current list +element through the specified iteration variable var. The evaluation +takes place in the context of the caller of the subcommand.

+
+    tclsh> # removing all odd numbers from the input
+    tclsh> ::struct::list filterfor x {1 2 3 4 5} {($x % 2) == 0}
+    2 4
+
+
+
::struct::list split sequence cmdprefix ?passVar failVar?
+

This is a variant of method filter, see above. Instead of +returning just the elements passing the test we get lists of both +passing and failing elements.

+

If no variable names are specified then the result of the command will +be a list containing the list of passing elements, and the list of +failing elements, in this order. Otherwise the lists of passing and +failing elements are stored into the two specified variables, and the +result will be a list containing two numbers, the number of elements +passing the test, and the number of elements failing, in this order.

+

The interface to the test is the same as used by filter.

+
::struct::list fold sequence initialvalue cmdprefix
+

The subcommand takes a sequence to operate on, an arbitrary +string initial value and a command prefix (cmdprefix) +specifying an operation.

+

The command prefix will be evaluated with two words appended to +it. The second of these words will always be an element of the +sequence. The evaluation takes place in the context of the caller of +the subcommand.

+

It then reduces the sequence into a single value through repeated +application of the command prefix and returns that value. This +reduction is done by

+
+
1
+

Application of the command to the initial value and the first element +of the list.

+
2
+

Application of the command to the result of the last call and the +second element of the list.

+
...
+
+
i
+

Application of the command to the result of the last call and the +i'th element of the list.

+
...
+
+
end
+

Application of the command to the result of the last call and the last +element of the list. The result of this call is returned as the result +of the subcommand.

+
+
+    tclsh> # summing the elements in a list.
+    tclsh> proc + {a b} {expr {$a + $b}}
+    tclsh> ::struct::list fold {1 2 3 4 5} 0 +
+    15
+
+
+
::struct::list shift listvar
+

The subcommand takes the list contained in the variable named by +listvar and shifts it down one element. +After the call listvar will contain a list containing the second +to last elements of the input list. The first element of the ist is +returned as the result of the command. Shifting the empty list does +nothing.

+
::struct::list iota n
+

The subcommand returns a list containing the integer numbers +in the range [0,n). The element at index i +of the list contain the number i.

+

For "n == 0" an empty list will be returned.

+
::struct::list equal a b
+

The subcommand compares the two lists a and b for +equality. In other words, they have to be of the same length and have +to contain the same elements in the same order. If an element is a +list the same definition of equality applies recursively.

+

A boolean value will be returned as the result of the command. +This value will be true if the two lists are equal, and +false else.

+
::struct::list repeat size element1 ?element2 element3...?
+

The subcommand creates a list of length +"size * number of elements" by repeating size +times the sequence of elements +element1 element2 .... +size must be a positive integer, elementn can be any +Tcl value. +Note that repeat 1 arg ... is identical to +list arg ..., though the arg is required +with repeat.

+

Examples:

+
+    tclsh> ::struct::list repeat 3 a
+    a a a
+    tclsh> ::struct::list repeat 3 [::struct::list repeat 3 0]
+    {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeat 3 a b c
+    a b c a b c a b c
+    tclsh> ::struct::list repeat 3 [::struct::list repeat 2 a] b c
+    {a a} b c {a a} b c {a a} b c
+
+
+
::struct::list repeatn value size...
+

The subcommand creates a (nested) list containing the value in +all positions. The exact size and degree of nesting is determined by +the size arguments, all of which have to be integer numbers +greater than or equal to zero.

+

A single argument size which is a list of more than one element +will be treated as if more than argument size was specified.

+

If only one argument size is present the returned list will not +be nested, of length size and contain value in all +positions. +If more than one size argument is present the returned +list will be nested, and of the length specified by the last +size argument given to it. The elements of that list +are defined as the result of Repeat for the same arguments, +but with the last size value removed.

+

An empty list will be returned if no size arguments are present.

+
+    tclsh> ::struct::list repeatn  0 3 4
+    {0 0 0} {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeatn  0 {3 4}
+    {0 0 0} {0 0 0} {0 0 0} {0 0 0}
+    tclsh> ::struct::list repeatn  0 {3 4 5}
+    {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}} {{0 0 0} {0 0 0} {0 0 0} {0 0 0}}
+
+
+
::struct::list dbJoin ?-inner|-left|-right|-full? ?-keys varname? {keycol table}...
+

The method performs a table join according to relational algebra. The +execution of any of the possible outer join operation is triggered by +the presence of either option -left, -right, or +-full. If none of these options is present a regular inner +join will be performed. This can also be triggered by specifying +-inner. The various possible join operations are explained in +detail in section TABLE JOIN.

+

If the -keys is present its argument is the name of a +variable to store the full list of found keys into. Depending on the +exact nature of the input table and the join mode the output table may +not contain all the keys by default. In such a case the caller can +declare a variable for this information and then insert it into the +output table on its own, as she will have more information about the +placement than this command.

+

What is left to explain is the format of the arguments.

+

The keycol arguments are the indices of the columns in the +tables which contain the key values to use for the joining. Each +argument applies to the table following immediately after it. The +columns are counted from 0, which references the first +column. The table associated with the column index has to have at +least keycol+1 columns. An error will be thrown if there are +less.

+

The table arguments represent a table or matrix of rows and +columns of values. We use the same representation as generated and +consumed by the methods get rect and set rect of +matrix objects. In other words, each argument is a list, +representing the whole matrix. Its elements are lists too, each +representing a single rows of the matrix. The elements of the +row-lists are the column values.

+

The table resulting from the join operation is returned as the result +of the command. We use the same representation as described above for +the input tables.

+
::struct::list dbJoinKeyed ?-inner|-left|-right|-full? ?-keys varname? table...
+

The operations performed by this method are the same as described +above for dbJoin. The only difference is in the specification +of the keys to use. Instead of using column indices separate from the +table here the keys are provided within the table itself. The row +elements in each table are not the lists of column values, but a +two-element list where the second element is the regular list of +column values and the first element is the key to use.

+
::struct::list swap listvar i j
+

The subcommand exchanges the elements at the indices i and +j in the list stored in the variable named by listvar. The +list is modified in place, and also returned as the result of the +subcommand.

+
::struct::list firstperm list
+

This subcommand returns the lexicographically first permutation of the +input list.

+
::struct::list nextperm perm
+

This subcommand accepts a permutation of a set of elements (provided +by perm) and returns the next permutatation in lexicographic +sequence.

+

The algorithm used here is by Donal E. Knuth, see section +REFERENCES for details.

+
::struct::list permutations list
+

This subcommand returns a list containing all permutations of the +input list in lexicographic order.

+
::struct::list foreachperm var list body
+

This subcommand executes the script body once for each +permutation of the specified list. The permutations are visited +in lexicographic order, and the variable var is set to the +permutation for which body is currently executed. The result of +the loop command is the empty string.

+
+
+

LONGEST COMMON SUBSEQUENCE AND FILE COMPARISON

+

The longestCommonSubsequence subcommand forms the core of a +flexible system for doing differential comparisons of files, similar +to the capability offered by the Unix command diff. +While this procedure is quite rapid for many tasks of file comparison, +its performance degrades severely if sequence2 contains many +equal elements (as, for instance, when using this procedure to compare +two files, a quarter of whose lines are blank. This drawback is +intrinsic to the algorithm used (see the Reference for details).

+

One approach to dealing with the performance problem that is sometimes +effective in practice is arbitrarily to exclude elements that appear +more than a certain number of times. +This number is provided as the maxOccurs parameter. If frequent +lines are excluded in this manner, they will not appear in the common +subsequence that is computed; the result will be the longest common +subsequence of infrequent elements. +The procedure longestCommonSubsequence2 implements this +heuristic. +It functions as a wrapper around longestCommonSubsequence; it +computes the longest common subsequence of infrequent elements, and +then subdivides the subsequences that lie between the matches to +approximate the true longest common subsequence.

+
+

TABLE JOIN

+

This is an operation from relational algebra for relational databases.

+

The easiest way to understand the regular inner join is that it +creates the cartesian product of all the tables involved first and +then keeps only all those rows in the resulting table for which the +values in the specified key columns are equal to each other.

+

Implementing this description naively, i.e. as described above will +generate a huge intermediate result. To avoid this the +cartesian product and the filtering of row are done at the same +time. What is required is a fast way to determine if a key is present +in a table. In a true database this is done through indices. Here we +use arrays internally.

+

An outer join is an extension of the inner join for two +tables. There are three variants of outerjoins, called left, +right, and full outer joins. Their result always +contains all rows from an inner join and then some additional rows.

+
    +

  1. For the left outer join the additional rows are all rows from the left +table for which there is no key in the right table. They are joined to +an empty row of the right table to fit them into the result.

    2. +

  2. For the right outer join the additional rows are all rows from the right +table for which there is no key in the left table. They are joined to +an empty row of the left table to fit them into the result.

    3. +

  3. The full outer join combines both left and right outer join. In other +words, the additional rows are as defined for left outer join, and +right outer join, combined.

    4. +
+

We extend all the joins from two to n tables (n > 2) by +executing

+
+    (...((table1 join table2) join table3) ...) join tableN
+
+

Examples for all the joins:

+
+    Inner Join
+    {0 foo}              {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} inner join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}             {3 driver}
+    Left Outer Join
+    {0 foo}                   {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} left outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                  {3 driver}   {2 blue  {} {}}
+    Right Outer Join
+    {0 foo}                    {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} right outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                   {3 driver}   {{} {}   3 driver}
+    Full Outer Join
+    {0 foo}                   {0 bagel}    {0 foo   0 bagel}
+    {1 snarf} full outer join {1 snatz}  = {1 snarf 1 snatz}
+    {2 blue}                  {3 driver}   {2 blue  {} {}}
+                                           {{} {}   3 driver}
+
+
+

REFERENCES

+
    +

  1. J. W. Hunt and M. D. McIlroy, "An algorithm for differential +file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone +Laboratories (1976). Available on the Web at the second +author's personal site: http://www.cs.dartmouth.edu/~doug/

    2. +

  2. Donald E. Knuth, "Fascicle 2b of 'The Art of Computer Programming' +volume 4". Available on the Web at the author's personal site: +http://www-cs-faculty.stanford.edu/~knuth/fasc2b.ps.gz.

    3. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: list of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_set.html Index: embedded/www/tcllib/files/modules/struct/struct_set.html ================================================================== --- embedded/www/tcllib/files/modules/struct/struct_set.html +++ embedded/www/tcllib/files/modules/struct/struct_set.html @@ -0,0 +1,235 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::set(n) 2.2.3 tcllib "Tcl Data Structures"

+

Name

+

struct::set - Procedures for manipulating sets

+
+ + +

Description

+

The ::struct::set namespace contains several useful commands for +processing finite sets.

+

It exports only a single command, struct::set. All +functionality provided here can be reached through a subcommand of +this command.

+

Note: As of version 2.2 of this package a critcl based C +implementation is available. This implementation however requires Tcl +8.4 to run.

+
+

COMMANDS

+
+
::struct::set empty set
+

Returns a boolean value indicating if the set is +empty (true), or not (false).

+
::struct::set size set
+

Returns an integer number greater than or equal to zero. This is the +number of elements in the set. In other words, its cardinality.

+
::struct::set contains set item
+

Returns a boolean value indicating if the set contains the +element item (true), or not (false).

+
::struct::set union ?set1...?
+

Computes the set containing the union of set1, set2, +etc., i.e. "set1 + set2 + ...", and returns this set +as the result of the command.

+
::struct::set intersect ?set1...?
+

Computes the set containing the intersection of set1, +set2, etc., i.e. "set1 * set2 * ...", and +returns this set as the result of the command.

+
::struct::set difference set1 set2
+

Computes the set containing the difference of set1 and +set2, i.e. ("set1 - set2") and returns this +set as the result of the command.

+
::struct::set symdiff set1 set2
+

Computes the set containing the symmetric difference of set1 and +set2, i.e. ("(set1 - set2) + (set2 - set1)") +and returns this set as the result of the command.

+
::struct::set intersect3 set1 set2
+

This command is a combination of the methods intersect and +difference. +It returns a three-element list containing "set1*set2", +"set1-set2", and "set2-set1", in this +order. In other words, the intersection of the two parameter sets, and +their differences.

+
::struct::set equal set1 set2
+

Returns a boolean value indicating if the two sets are equal +(true) or not (false).

+
::struct::set include svar item
+

The element item is added to the set specified by the variable +name in svar. The return value of the command is empty. This is +the equivalent of lappend for sets. If the variable named by +svar does not exist it will be created.

+
::struct::set exclude svar item
+

The element item is removed from the set specified by the +variable name in svar. The return value of the command is +empty. This is a near-equivalent of lreplace for sets.

+
::struct::set add svar set
+

All the element of set are added to the set specified by the +variable name in svar. The return value of the command is +empty. This is like the method include, but for the addition +of a whole set. If the variable named by svar does not exist it +will be created.

+
::struct::set subtract svar set
+

All the element of set are removed from the set specified by the +variable name in svar. The return value of the command is +empty. This is like the method exclude, but for the removal +of a whole set.

+
::struct::set subsetof A B
+

Returns a boolean value indicating if the set A is a true +subset of or equal to the set B (true), or not +(false).

+
+
+ +

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: set of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_tree.html Index: embedded/www/tcllib/files/modules/struct/struct_tree.html ================================================================== --- embedded/www/tcllib/files/modules/struct/struct_tree.html +++ embedded/www/tcllib/files/modules/struct/struct_tree.html @@ -0,0 +1,690 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::tree(n) 2.1.1 tcllib "Tcl Data Structures"

+

Name

+

struct::tree - Create and manipulate tree objects

+
+ + +

Description

+

A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that +places a hierarchical structure on the nodes. (Data Structures and +Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In +addition to maintaining the node relationships, this tree +implementation allows any number of keyed values to be associated with +each node.

+

The element names can be arbitrary strings.

+

A tree is thus similar to an array, but with three important +differences:

+
    +

  1. Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.)

    2. +

  2. Trees have a hierarchical structure, whereas an array is just an +unordered collection.

    3. +

  3. Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary.

    4. +
+

Note: The major version of the package struct has +been changed to version 2.0, due to backward incompatible changes in +the API of this module. Please read the section +Changes for 2.0 for a full list of all changes, +incompatible and otherwise.

+
+

API

+

Tree CLASS API

+

The main commands of the package are:

+
+
::struct::tree ?treeName? ?=|:=|as|deserialize source?
+

The command creates a new tree object with an associated global Tcl +command whose name is treeName. This command may be used to +invoke various operations on the tree. +It has the following general form:

+
+
treeName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

If treeName is not specified a unique name will be generated by +the package itself. If a source is specified the new tree will +be initialized to it. For the operators =, :=, and +as source is interpreted as the name of another tree +object, and the assignment operator = will be executed. For +deserialize the source is a serialized tree object and +deserialize will be executed.

+

In other words

+
+    ::struct::tree mytree = b
+
+

is equivalent to

+
+    ::struct::tree mytree
+    mytree = b
+
+

and

+
+    ::struct::tree mytree deserialize $b
+
+

is equivalent to

+
+    ::struct::tree mytree
+    mytree deserialize $b
+
+
+
::struct::tree::prune
+

This command is provided outside of the tree methods, as it is not a +tree method per se. It however interacts tightly with the method +walk. When used in the walk script it causes the traversal to +ignore the children of the node we are currently at. +This command cannot be used with the traversal modes which look at +children before their parent, i.e. post and in. The +only applicable orders of traversal are pre and +both. An error is thrown if the command and chosen order of +traversal do not fit.

+
+
+

Tree OBJECT API

+

Two general observations beforehand:

+
    +

  1. The root node of the tree can be used in most places where a node is +asked for. The default name of the rootnode is "root", but this can be +changed with the method rename (see below). Whatever the +current name for the root node of the tree is, it can be retrieved by +calling the method rootname.

    2. +

  2. The method insert is the only way to create new nodes, and +they are automatically added to a parent. A tree object cannot have +nodes without a parent, save the root node.

    3. +
+

And now the methods supported by tree objects created by this package:

+
+
treeName = sourcetree
+

This is the assignment operator for tree objects. It copies the tree +contained in the tree object sourcetree over the tree data in +treeName. The old contents of treeName are deleted by this +operation.

+

This operation is in effect equivalent to

+
+    treeName deserialize [sourcetree serialize]
+
+
+
treeName --> desttree
+

This is the reverse assignment operator for tree objects. It copies the tree +contained in the tree object treeName over the tree data in the object +desttree. The old contents of desttree are deleted by this +operation.

+

This operation is in effect equivalent to

+
+    desttree deserialize [treeName serialize]
+
+
+
treeName ancestors node
+

This method extends the method parent and returns a list +containing all ancestor nodes to the specified node. The +immediate ancestor, in other words, parent node, is the first element +in that list, its parent the second element, and so on until the root +node is reached, making it the last element of the returned list.

+
treeName append node key value
+

Appends a value to one of the keyed values associated with an +node. Returns the new value given to the attribute key.

+
treeName attr key
+
+
treeName attr key -nodes list
+
+
treeName attr key -glob globpattern
+
+
treeName attr key -regexp repattern
+

This method retrieves the value of the attribute named key, for +all nodes in the tree (matching the restriction specified via one of +the possible options) and having the specified attribute.

+

The result is a dictionary mapping from node names to the value of +attribute key at that node. +Nodes not having the attribute key, or not passing a +specified restriction, are not listed in the result.

+

The possible restrictions are:

+
+
-nodes
+

The value is a list of nodes. Only the nodes mentioned in this list +are searched for the attribute.

+
-glob
+

The value is a glob pattern. Only the nodes in the tree whose names +match this pattern are searched for the attribute.

+
-regexp
+

The value is a regular expression. Only the nodes in the tree whose +names match this pattern are searched for the attribute.

+
+
treeName children ?-all? node ?filter cmdprefix?
+

Return a list of the children of node. +If the option -all is specified, then not only the direct +children, but their children, and so on are returned in the result. +If a filter command is specified only those nodes are listed in the +final result which pass the test. The command in cmdprefix is +called with two arguments, the name of the tree object, and the name +of the node in question. It is executed in the context of the caller +and has to return a boolean value. Nodes for which the command returns +false are removed from the result list before it is returned +to the caller.

+

Some examples:

+
+    mytree insert root end 0 ; mytree set 0 volume 30
+    mytree insert root end 1
+    mytree insert root end 2
+    mytree insert 0    end 3
+    mytree insert 0    end 4
+    mytree insert 4    end 5 ; mytree set 5 volume 50
+    mytree insert 4    end 6
+    proc vol {t n} {
+	$t keyexists $n volume
+    }
+    proc vgt40 {t n} {
+	if {![$t keyexists $n volume]} {return 0}
+	expr {[$t get $n volume] > 40}
+    }
+    tclsh> lsort [mytree children -all root filter vol]
+    0 5
+    tclsh> lsort [mytree children -all root filter vgt40]
+    5
+    tclsh> lsort [mytree children root filter vol]
+    0
+    tclsh> puts ([lsort [mytree children root filter vgt40]])
+    ()
+
+
+
treeName cut node
+

Removes the node specified by node from the tree, but not its +children. The children of node are made children of the parent +of the node, at the index at which node was located.

+
treeName delete node ?node ...?
+

Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes.

+
treeName depth node
+

Return the number of steps from node node to the root node.

+
treeName descendants node ?filter cmdprefix?
+

This method extends the method children and returns a list +containing all nodes descending from node, and passing the +filter, if such was specified.

+

This is actually the same as +"treeName children -all". +descendants should be prefered, and "children -all" +will be deprecated sometime in the future.

+
treeName deserialize serialization
+

This is the complement to serialize. It replaces tree data in +treeName with the tree described by the serialization +value. The old contents of treeName are deleted by this +operation.

+
treeName destroy
+

Destroy the tree, including its storage space and associated command.

+
treeName exists node
+

Returns true if the specified node exists in the tree.

+
treeName get node key
+

Returns the value associated with the key key for the node +node.

+
treeName getall node ?pattern?
+

Returns a dictionary (suitable for use with [array set]) +containing the attribute data for the node. +If the glob pattern is specified only the attributes whose names +match the pattern will be part of the dictionary.

+
treeName keys node ?pattern?
+

Returns a list of keys for the node. +If the pattern is specified only the attributes whose names +match the pattern will be part of the returned list. The pattern is a +glob pattern.

+
treeName keyexists node key
+

Return true if the specified key exists for the node.

+
treeName index node
+

Returns the index of node in its parent's list of children. For +example, if a node has nodeFoo, nodeBar, and +nodeBaz as children, in that order, the index of +nodeBar is 1.

+
treeName insert parent index ?child ?child ...??
+

Insert one or more nodes into the tree as children of the node +parent. The nodes will be added in the order they are given. If +parent is root, it refers to the root of the tree. The +new nodes will be added to the parent node's child list at the +index given by index. The index can be end in +which case the new nodes will be added after the current last child. +Indices of the form "end-n" are accepted as well.

+

If any of the specified children already exist in treeName, +those nodes will be moved from their original location to the new +location indicated by this command.

+

If no child is specified, a single node will be added, and a +name will be generated for the new node. The generated name is of the +form nodex, where x is a number. If names are +specified they must neither contain whitespace nor colons (":").

+

The return result from this command is a list of nodes added.

+
treeName isleaf node
+

Returns true if node is a leaf of the tree (if node has no +children), false otherwise.

+
treeName lappend node key value
+

Appends a value (as a list) to one of the keyed values +associated with an node. Returns the new value given to the +attribute key.

+
treeName leaves
+

Return a list containing all leaf nodes known to the tree.

+
treeName move parent index node ?node ...?
+

Make the specified nodes children of parent, inserting them into +the parent's child list at the index given by index. Note that +the command will take all nodes out of the tree before inserting them +under the new parent, and that it determines the position to place +them into after the removal, before the re-insertion. This behaviour +is important when it comes to moving one or more nodes to a different +index without changing their parent node.

+
treeName next node
+

Return the right sibling of node, or the empty string if +node was the last child of its parent.

+
treeName numchildren node
+

Return the number of immediate children of node.

+
treeName nodes
+

Return a list containing all nodes known to the tree.

+
treeName parent node
+

Return the parent of node.

+
treeName previous node
+

Return the left sibling of node, or the empty string if +node was the first child of its parent.

+
treeName rename node newname
+

Renames the node node to newname. An error is thrown if +either the node does not exist, or a node with name newname does +exist. The result of the command is the new name of the node.

+
treeName rootname
+

Returns the name of the root node of the tree.

+
treeName serialize ?node?
+

This method serializes the sub-tree starting at node. In other +words it returns a tcl value completely describing the tree +starting at node. +This allows, for example, the transfer of tree objects (or parts +thereof) over arbitrary channels, persistence, etc. +This method is also the basis for both the copy constructor and +the assignment operator.

+

The result of this method has to be semantically identical over all +implementations of the tree interface. This is what will enable us to +copy tree data between different implementations of the same +interface.

+

The result is a list containing containing a multiple of three +elements. It is like a serialized array except that there are two +values following each key. They are the names of the nodes in the +serialized tree. The two values are a reference to the parent node and +the attribute data, in this order.

+

The reference to the parent node is the empty string for the root node +of the tree. For all other nodes it is the index of the parent node in +the list. This means that they are integers, greater than or equal to +zero, less than the length of the list, and multiples of three. +The order of the nodes in the list is important insofar as it is used +to reconstruct the lists of children for each node. The children of a +node have to be listed in the serialization in the same order as they +are listed in their parent in the tree.

+

The attribute data of a node is a dictionary, i.e. a list of even +length containing a serialized array. For a node without attribute +data the dictionary is the empty list.

+

Note: While the current implementation returns the root node as +the first element of the list, followed by its children and their +children in a depth-first traversal this is not necessarily true for +other implementations. +The only information a reader of the serialized data can rely on for +the structure of the tree is that the root node is signaled by the +empty string for the parent reference, that all other nodes refer to +their parent through the index in the list, and that children occur in +the same order as in their parent.

+
+ A possible serialization for the tree structure
+             +- d
+       +- a -+
+ root -+- b  +- e
+       +- c
+ is
+ {root {} {} a 0 {} d 3 {} e 3 {} b 0 {} c 0 {}}
+ The above assumes that none of the nodes have attributes.
+
+
+
treeName set node key ?value?
+

Set or get one of the keyed values associated with a node. A node may +have any number of keyed values associated with it. If value is +not specified, this command returns the current value assigned to the +key; if value is specified, this command assigns that value to +the key, and returns it.

+
treeName size ?node?
+

Return a count of the number of descendants of the node node; if +no node is specified, root is assumed.

+
treeName splice parent from ?to? ?child?
+

Insert a node named child into the tree as a child of the node +parent. If parent is root, it refers to the root +of the tree. The new node will be added to the parent node's child +list at the index given by from. The children of parent +which are in the range of the indices from and to are made +children of child. If the value of to is not specified it +defaults to end. If no name is given for child, a name +will be generated for the new node. The generated name is of the form +nodex, where x is a number. The return result +from this command is the name of the new node.

+

The arguments from and to are regular list indices, i.e. +the form "end-n" is accepted as well.

+
treeName swap node1 node2
+

Swap the position of node1 and node2 in the tree.

+
treeName unset node key
+

Removes a keyed value from the node node. The method will do +nothing if the key does not exist.

+
treeName walk node ?-order order? ?-type type? loopvar script
+

Perform a breadth-first or depth-first walk of the tree starting at +the node node. The type of walk, breadth-first or depth-first, +is determined by the value of type; bfs indicates +breadth-first, dfs indicates depth-first. Depth-first is the +default. The order of the walk, pre-, post-, both- or in-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order and in indicates in-order. Pre-order is the +default.

+

Pre-order walking means that a parent node is visited before any of +its children. For example, a breadth-first search starting from the +root will visit the root, followed by all of the root's children, +followed by all of the root's grandchildren. Post-order walking means +that a parent node is visited after any of its children. Both-order +walking means that a parent node is visited before and after +any of its children. In-order walking means that a parent node is +visited after its first child and before the second. This is a +generalization of in-order walking for binary trees and will do the +right thing if a binary tree is walked. The combination of a breadth-first +walk with in-order is illegal.

+

As the walk progresses, the script will be evaluated at each +node. The evaluation takes place in the context of the caller of the +method. +Regarding loop variables, these are listed in loopvar. If one +only one variable is specified it will be set to the id of the +node. When two variables are specified, i.e. loopvar is a true +list, then the first variable will be set to the action performed at +the node, and the other to the id of the node itself. +All loop variables are created in the context of the caller.

+

There are three possible actions: enter, leave, +or visit. enter actions occur during pre-order +walks; leave actions occur during post-order walks; +visit actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +enter for the first evaluation, and leave for the +second.

+

Note: The enter action for a node is always performed +before the walker will look at the children of that node. This means +that changes made by the script to the children of the node +will immediately influence the walker and the steps it will take.

+

Any other manipulation, for example of nodes higher in the tree (i.e +already visited), or upon leaving will have undefined results. They +may succeed, error out, silently compute the wrong result, or anything +in between.

+

At last a small table showing the relationship between the various +options and the possible actions.

+
+ order       type    actions         notes
+ -----       ----    -----           -----
+ pre         dfs     enter           parent before children
+ post        dfs     leave           parent after children
+ in          dfs     visit           parent between first and second child.
+ both        dfs     enter, leave    parent before and after children
+ -----       ----    -----           -----
+ pre         bfs     enter           parent before children
+ post        bfs     leave           parent after children
+ in          bfs             -- illegal --
+ both        bfs     enter, leave    parent before and after children
+ -----       ----    -----           -----
+
+

Note the command ::struct::tree::prune. This command can be used +in the walk script to force the command to ignore the children of the +node we are currently at. It will throw an error if the order of +traversal is either post or in as these modes visit +the children before their parent, making pruning non-sensical.

+
treeName walkproc node ?-order order? ?-type type? cmdprefix
+

This method is like method walk in all essentials, except the +interface to the user code. This method invokes a command prefix with +three additional arguments (tree, node, and action), instead of +evaluating a script and passing the node via a loop variable.

+
+
+

Changes for 2.0

+

The following noteworthy changes have occurred:

+
    +

  1. The API for accessing attributes and their values has been +simplified.

    +

    All functionality regarding the default attribute "data" has been +removed. This default attribute does not exist anymore. All accesses +to attributes have to specify the name of the attribute in +question. This backward incompatible change allowed us to +simplify the signature of all methods handling attributes.

    +

    Especially the flag -key is not required anymore, even more, +its use is now forbidden. Please read the documentation for the +methods set, get, getall, unset, +append, lappend, keyexists +and keys for a description of the new API's.

    2. +

  2. The methods keys and getall now take an optional +pattern argument and will return only attribute data for keys matching +this pattern.

    3. +

  3. Nodes can now be renamed. See the documentation for the method +rename.

    4. +

  4. The structure has been extended with API's for the serialization and +deserialization of tree objects, and a number of operations based on +them (tree assignment, copy construction).

    +

    Please read the documentation for the methods serialize, +deserialize, =, and -->, and the +documentation on the construction of tree objects.

    +

    Beyond the copying of whole tree objects these new API's also enable +the transfer of tree objects over arbitrary channels and for easy +persistence.

    5. +

  5. The walker API has been streamlined and made more similar to the +command foreach. In detail:

    +
      +

    • The superfluous option -command has been removed.

      • +

    • Ditto for the place holders. Instead of the placeholders two loop +variables have to be specified to contain node and action information.

      • +

    • The old command argument has been documented as a script now, which it +was in the past too.

      • +

    • The fact that enter actions are called before the walker looks +at the children of a node has been documented now. In other words it +is now officially allowed to manipulate the list of children for a +node under these circumstances. It has been made clear that +changes under any other circumstances will have undefined results, +from silently computing the wrong result to erroring out.

      • +
    +
    6. +

  6. A new method, attr, was added allowing the query and +retrieval of attribute data without regard to the node relationship.

    7. +

  7. The method children has been extended with the ability to +select from the children of the node based on an arbitrary filtering +criterium. Another extension is the ability to look not only at the +immediate children of the node, but the whole tree below it.

    8. +
+
+
+

EXAMPLES

+

The following example demonstrates the creation of new nodes:

+
+    mytree insert root end 0   ; # Create node 0, as child of the root
+    mytree insert root end 1 2 ; # Ditto nodes 1 & 2
+    mytree insert 0    end 3   ; # Now create node 3 as child of node 0
+    mytree insert 0    end     ; # Create another child of 0, with a
+    #                              generated name. The name is returned
+    #                              as the result of the command.
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: tree of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/struct/struct_tree1.html Index: embedded/www/tcllib/files/modules/struct/struct_tree1.html ================================================================== --- embedded/www/tcllib/files/modules/struct/struct_tree1.html +++ embedded/www/tcllib/files/modules/struct/struct_tree1.html @@ -0,0 +1,345 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

struct::tree_v1(n) 1.2.2 tcllib "Tcl Data Structures"

+

Name

+

struct::tree_v1 - Create and manipulate tree objects

+
+ + +

Description

+

The ::struct::tree command creates a new tree object with an +associated global Tcl command whose name is treeName. This +command may be used to invoke various operations on the tree. It has +the following general form:

+
+
treeName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+

A tree is a collection of named elements, called nodes, one of which is +distinguished as a root, along with a relation ("parenthood") that +places a hierarchical structure on the nodes. (Data Structures and +Algorithms; Aho, Hopcroft and Ullman; Addison-Wesley, 1987). In +addition to maintaining the node relationships, this tree +implementation allows any number of keyed values to be associated with +each node.

+

The element names can be arbitrary strings.

+

A tree is thus similar to an array, but with three important +differences:

+
    +

  1. Trees are accessed through an object command, whereas arrays are +accessed as variables. (This means trees cannot be local to a procedure.)

    2. +

  2. Trees have a hierarchical structure, whereas an array is just an +unordered collection.

    3. +

  3. Each node of a tree has a separate collection of attributes and +values. This is like an array where every value is a dictionary.

    4. +
+

The following commands are possible for tree objects:

+
+
treeName append node ?-key key? value
+

Appends a value to one of the keyed values associated with an +node. If no key is specified, the key data is assumed.

+
treeName children node
+

Return a list of the children of node.

+
treeName cut node
+

Removes the node specified by node from the tree, but not its +children. The children of node are made children of the parent +of the node, at the index at which node was located.

+
treeName delete node ?node ...?
+

Removes the specified nodes from the tree. All of the nodes' children +will be removed as well to prevent orphaned nodes.

+
treeName depth node
+

Return the number of steps from node node to the root node.

+
treeName destroy
+

Destroy the tree, including its storage space and associated command.

+
treeName exists node
+

Returns true if the specified node exists in the tree.

+
treeName get node ?-key key?
+

Return the value associated with the key key for the node +node. If no key is specified, the key data is assumed.

+
treeName getall node
+

Returns a serialized list of key/value pairs (suitable for use with +[array set]) for the node.

+
treeName keys node
+

Returns a list of keys for the node.

+
treeName keyexists node ?-key key?
+

Return true if the specified key exists for the node. If +no key is specified, the key data is assumed.

+
treeName index node
+

Returns the index of node in its parent's list of children. For +example, if a node has nodeFoo, nodeBar, and +nodeBaz as children, in that order, the index of +nodeBar is 1.

+
treeName insert parent index ?child ?child ...??
+

Insert one or more nodes into the tree as children of the node +parent. The nodes will be added in the order they are given. If +parent is root, it refers to the root of the tree. The +new nodes will be added to the parent node's child list at the +index given by index. The index can be end in +which case the new nodes will be added after the current last child.

+

If any of the specified children already exist in treeName, +those nodes will be moved from their original location to the new +location indicated by this command.

+

If no child is specified, a single node will be added, and a +name will be generated for the new node. The generated name is of the +form nodex, where x is a number. If names are +specified they must neither contain whitespace nor colons (":").

+

The return result from this command is a list of nodes added.

+
treeName isleaf node
+

Returns true if node is a leaf of the tree (if node has no +children), false otherwise.

+
treeName lappend node ?-key key? value
+

Appends a value (as a list) to one of the keyed values +associated with an node. If no key is specified, the key +data is assumed.

+
treeName move parent index node ?node ...?
+

Make the specified nodes children of parent, inserting them into +the parent's child list at the index given by index. Note that +the command will take all nodes out of the tree before inserting them +under the new parent, and that it determines the position to place +them into after the removal, before the re-insertion. This behaviour +is important when it comes to moving one or more nodes to a different +index without changing their parent node.

+
treeName next node
+

Return the right sibling of node, or the empty string if +node was the last child of its parent.

+
treeName numchildren node
+

Return the number of immediate children of node.

+
treeName parent node
+

Return the parent of node.

+
treeName previous node
+

Return the left sibling of node, or the empty string if +node was the first child of its parent.

+
treeName set node ?-key key? ?value?
+

Set or get one of the keyed values associated with a node. If no key +is specified, the key data is assumed. Each node that is +added to a tree has the value "" assigned to the key data +automatically. A node may have any number of keyed values associated +with it. If value is not specified, this command returns the +current value assigned to the key; if value is specified, this +command assigns that value to the key.

+
treeName size ?node?
+

Return a count of the number of descendants of the node node; if +no node is specified, root is assumed.

+
treeName splice parent from ?to? ?child?
+

Insert a node named child into the tree as a child of the node +parent. If parent is root, it refers to the root +of the tree. The new node will be added to the parent node's child +list at the index given by from. The children of parent +which are in the range of the indices from and to are made +children of child. If the value of to is not specified it +defaults to end. If no name is given for child, a name +will be generated for the new node. The generated name is of the form +nodex, where x is a number. The return result +from this command is the name of the new node.

+
treeName swap node1 node2
+

Swap the position of node1 and node2 in the tree.

+
treeName unset node ?-key key?
+

Removes a keyed value from the node node. If no key is +specified, the key data is assumed.

+
treeName walk node ?-order order? ?-type type? -command cmd
+

Perform a breadth-first or depth-first walk of the tree starting at +the node node. The type of walk, breadth-first or depth-first, +is determined by the value of type; bfs indicates +breadth-first, dfs indicates depth-first. Depth-first is the +default. The order of the walk, pre-, post-, both- or in-order is +determined by the value of order; pre indicates +pre-order, post indicates post-order, both indicates +both-order and in indicates in-order. Pre-order is the +default.

+

Pre-order walking means that a parent node is visited before any of +its children. For example, a breadth-first search starting from the +root will visit the root, followed by all of the root's children, +followed by all of the root's grandchildren. Post-order walking means +that a parent node is visited after any of its children. Both-order +walking means that a parent node is visited before and after +any of its children. In-order walking means that a parent node is +visited after its first child and before the second. This is a +generalization of in-order walking for binary trees and will do the +right thing if a binary is walked. The combination of a breadth-first +walk with in-order is illegal.

+

As the walk progresses, the command cmd will be evaluated at +each node. Percent substitution will be performed on cmd before +evaluation, just as in a bind script. The following +substitutions are recognized:

+
+
%%
+

Insert the literal % character.

+
%t
+

Name of the tree object.

+
%n
+

Name of the current node.

+
%a
+

Name of the action occurring; one of enter, leave, +or visit. enter actions occur during pre-order +walks; leave actions occur during post-order walks; +visit actions occur during in-order walks. In a both-order +walk, the command will be evaluated twice for each node; the action is +enter for the first evaluation, and leave for the +second.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category struct :: tree of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/tar/tar.html Index: embedded/www/tcllib/files/modules/tar/tar.html ================================================================== --- embedded/www/tcllib/files/modules/tar/tar.html +++ embedded/www/tcllib/files/modules/tar/tar.html @@ -0,0 +1,262 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tar(n) 0.10 tcllib "Tar file handling"

+

Name

+

tar - Tar file creation, extraction & manipulation

+
+ + +

Description

+

Note: Starting with version 0.8 the tar reader commands +(contents, stats, get, untar) support the GNU LongName extension +(header type 'L') for large paths.

+
+
::tar::contents tarball ?-chan?
+

Returns a list of the files contained in tarball. The order is not sorted and depends on the order +files were stored in the archive.

+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::stat tarball ?file? ?-chan?
+

Returns a nested dict containing information on the named ?file? in tarball, +or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys +"mode uid gid size mtime type linkname uname gname + devmajor devminor"

+
+% ::tar::stat tarball.tar
+foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
+
+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::untar tarball args
+

Extracts tarball. -file and -glob limit the extraction +to files which exactly match or pattern match the given argument. No error is +thrown if no files match. Returns a list of filenames extracted and the file +size. The size will be null for non regular files. Leading path seperators are +stripped so paths will always be relative.

+
+
-dir dirName
+

Directory to extract to. Uses pwd if none is specified

+
-file fileName
+

Only extract the file with this name. The name is matched against the complete path +stored in the archive including directories.

+
-glob pattern
+

Only extract files patching this glob style pattern. The pattern is matched against the complete path +stored in the archive.

+
-nooverwrite
+

Dont overwrite files that already exist

+
-nomtime
+

Leave the file modification time as the current time instead of setting it to the value in the archive.

+
-noperms
+

In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive.

+
-chan
+

If this option is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
+
+% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
+puts "Extracted $file ($size bytes)"
+}
+
+
+
::tar::get tarball fileName ?-chan?
+

Returns the contents of fileName from the tarball

+
+% set readme [::tar::get tarball.tar doc/README] {
+% puts $readme
+}
+
+

If the option -chan is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for reading, and configured for binary input. +The command will not close the channel.

+
::tar::create tarball files args
+

Creates a new tar file containing the files. files must be specified +as a single argument which is a proper list of filenames.

+
+
-dereference
+

Normally create will store links as an actual link pointing at a file that may +or may not exist in the archive. Specifying this option will cause the actual file point to + by the link to be stored instead.

+
-chan
+

If this option is present tarball is interpreted as an open channel. +It is assumed that the channel was opened for writing, and configured for binary output. +The command will not close the channel.

+
+
+% ::tar::create new.tar [glob -nocomplain file*]
+% ::tar::contents new.tar
+file1 file2 file3
+
+
+
::tar::add tarball files args
+

Appends files to the end of the existing tarball. files must be specified +as a single argument which is a proper list of filenames.

+
+
-dereference
+

Normally add will store links as an actual link pointing at a file that may +or may not exist in the archive. Specifying this option will cause the actual file point to + by the link to be stored instead.

+
-prefix string
+

Normally add will store files under exactly the name specified as +argument. Specifying a ?-prefix? causes the string to be +prepended to every name.

+
-quick
+

The only sure way to find the position in the tarball where new +files can be added is to read it from start, but if tarball was +written with a "blocksize" of 1 (as this package does) then one can +alternatively find this position by seeking from the end. The +?-quick? option tells add to do the latter.

+
+
::tar::remove tarball files
+

Removes files from the tarball. No error will result if the file does not exist in the +tarball. Directory write permission and free disk space equivalent to at least the size of the tarball +will be needed.

+
+% ::tar::remove new.tar {file2 file3}
+% ::tar::contents new.tar
+file3
+
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tar of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+
ADDED embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html Index: embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html ================================================================== --- embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html +++ embedded/www/tcllib/files/modules/tepam/tepam_argument_dialogbox.html @@ -0,0 +1,602 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tepam::argument_dialogbox(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual

+
+ + + +

ARGUMENT DIALOGBOX CALL

+

The TEPAM argument_dialogbox is a flexible and easily usable data entry form generator that is available if Tk has been loaded. Each data entry element of a form is defined via a data entry item that can be provided to argument_dialogbox in two formats:

+
+
tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...?
+

Using this first format, each data entry item is defined via a pair of two arguments. The first one is the item name that defines the entry widget that has to be used in the form. The second argument, called item attributes, specifies the variable which is attributed to the data entry element as well as eventual formatting and context information.

+

The argument_dialogbox returns ok if the entered data have been acknowledged (via the OK button) and validated by a data checker. If the entered data have been rejected (via the Cancel button) the argument_dialogbox returns cancel.

+

A small example illustrates how the argument_dialogbox can be employed:

+
set DialogResult [tepam::argument_dialogbox \
+   -title "Itinerary selection" \
+   -file {-label "Itinerary report" -variable report_file} \
+   -frame {-label "Itinerary start"} \
+      -comment {-text "Specify your itinerary start location"} \
+      -entry {-label "City" -variable start_city -type string} \
+      -entry {-label "Street" -variable start_street -type string -optional 1} \
+      -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
+   -frame {-label "Itinerary destination"} \
+      -comment {-text "Specify your itinerary destination"} \
+      -entry {-label "City" -variable dest_city -type string} \
+      -entry {-label "Street" -variable dest_street -type string -optional 1} \
+      -entry {-label "Street number" -variable dest_street_nbr -type integer -optional 1} \
+   -frame {} \
+   -checkbutton {-label "Don't use highways" -variable no_highway}]
+

This example opens a dialog box that has the title Itinerary selection. A first entry widget in this box allows selecting a report file. It follows two frames to define respectively an itinerary start and end location. Each of these locations that are described with a comment has three entry widgets to specify respectively the city, street and the street number. Bellow the second frame there is a check button that allows specifying if eventual highways should be ignored.

+
tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?}
+

Sometimes it is simpler to provide all the data entry item definitions in form of a single list to argument_dialogbox, and not as individual arguments. The second format that is supported by argument_dialogbox corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to argument_dialogbox. The previous example can therefore also be written in the following way:

+
set DialogResult [tepam::argument_dialogbox {
+   -title "Itinerary selection"
+   -file {-label "Itinerary report" -variable report_file}
+   ...
+   -checkbutton {-label "Don't use highways" -variable no_highway} }]
+
+
+

The commands argument_dialogbox as well as procedure are exported from the namespace tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to import them into the main namespace:

+
namespace import tepam::*
+set DialogResult [argument_dialogbox \
+   -title "Itinerary selection"
+   ...
+

The following subsections explain the different argument item types that are accepted by the argument_dialogbox, classified into three groups. The first data entry item definition format will be used in the remaining document, knowing that this format can always be transformed into the second format by putting all arguments into a single list that is then provided to argument_dialogbox.

+

Context Definition Items

+

The first item group allows specifying some context aspects of an argument dialog box. These items are taking a simple character string as item attribute:

+
tepam::argument_dialogbox \
+   -<argument_name> string \
+   ...
+

The following items are classified into this group:

+
+
-title string
+

The dialog box window title which is by default Dialog can be changed with the -title item:

+
tepam::argument_dialogbox \
+   -title "System configuration" \
+   ...
+
+
-window string
+

The argument dialog box uses by default .dialog as dialog top level window. This path can be changed with the -window item:

+
tepam::argument_dialogbox \
+   -window .dialog \
+   ...
+
+
-parent string
+

By defining a parent window, the argument dialog box will be displayed beside this one. Without explicit parent window definition, the top-level window will be considered as parent window.

+
tepam::argument_dialogbox \
+   -parent .my_appl \
+   ...
+
+
-context string
+

If a context is defined the dialog box state, e.g. the entered data as well as the window size and position, is restored the next time the argument dialog box is called. The assignment of a context allows saving the dialog box state in its context to distinguish between different usages of the argument dialog box.

+
tepam::argument_dialogbox \
+   -context destination_definitions \
+   ...
+
+
+
+

Formatting and Display Options

+

Especially for big, complex forms it becomes important that the different data entry widgets are graphically well organized and commented to provide an immediate and clear overview to the user. A couple of items allow structuring and commenting the dialog boxes.

+

The items of this classification group require as item attributes a definition list, which contains itself attribute name and value pairs:

+
tepam::argument_dialogbox \
+   ...
+   -<argument_name> { 
+      ?-<attribute_name> <attribute_value>?
+      ?-<attribute_name> <attribute_value>?
+      ?...?
+   }
+   ...
+

The following items are classified into this group:

+
+
-frame list
+

The -frame item allows packing all following entry widgets into a labeled frame, until a next frame item is defined or until the last entry widget has been defined. It recognizes the following attributes inside the item attribute list:

+
+
-label string
+

An optional frame label can be specified with the -label statement.

+
+

Example:

+
tepam::argument_dialogbox \
+   ...
+   -frame {-label "Destination address"}
+   ...
+

To close an open frame without opening a new one, an empty list has to be provided to the -frame statement.

+
tepam::argument_dialogbox \
+   ...
+   -frame {}
+   ...
+
+
-sep [const {{}}]
+

Entry widgets can be separated with the -sep statement which doesn't require additional definitions. The related definition list has to exist, but its content is ignored.

+
tepam::argument_dialogbox \
+   ...
+   -sep {}
+   ...
+
+
-comment string
+

Comments and descriptions can be added with the -text attribute of the -comment item. Please note that each entry widget itself can also contain a -text attribute for comments and descriptions. But the -comment item allows for example adding a description between two frames.

+
tepam::argument_dialogbox \
+   ...
+   -comment {-text "Specify bellow the destination address"}
+   ...
+
+
-yscroll 0|1|auto
+

This attribute allows controlling an eventual vertical scrollbar. Setting it to 0 will permanently disable the scrollbar, setting it to 1 will enable it. By default it is set to auto. The scrollbar is enabled in this mode only if the vertical data entry form size exceeds 66% of the screen height.

+
tepam::argument_dialogbox \
+   ...
+   -yscroll auto
+   ...
+
+
+
+

Global Custom Data Validation

+

This item group allows specifying global custom checks to validate the entered data.

+
+
-validatecommand script
+

Custom data checks can be performed via validation commands that are defined with the -validatecommand item. Example:

+
tepam::argument_dialogbox \
+   -entry {-label "Your comment" -variable YourCom} \
+   -validatecommand {IllegalWordDetector $YourCom}
+

The validation command is executed in the context of the calling procedure, once all the basic data checks have been performed and data variables are assigned. All data is accessed via the data variables. Note that there is also an entry widget specific attribute -validatecommand that allows declaring custom checks for specific data entries.

+

The attribute -validatecommand can be repeated to declare multiple custom checks.

+
-validatecommand_error_text string
+

This item allows overriding the default error message for a global custom argument validation (defined by -validatecommand). Also this attribute can be repeated in case multiple checks are declared.

+
-validatecommand2 script
+
+
-validatecommand2_error_text string
+

These items are mainly for TEPAM internal usage.

+

These items corrspond respectively to -validatecommand and -validatecommand_error_text. However, the data validation is not performed in the next upper stack level, but two stack levels higher.

+
+
+

Data Entry Widget Items

+

Data entry widgets are created with the widget items. These items require as item attributes a definition list, which contains itself attribute name and value pairs:

+
tepam::argument_dialogbox \
+   ...
+   -<argument_name> { 
+      ?-<attribute_name> <attribute_value>?
+      ?-<attribute_name> <attribute_value>?
+      ?...?
+   }
+   ...
+

The attribute list can contain various attributes to describe and comment an entry widget and to constrain its entered value. All entry widgets are accepting a common set of attributes that are described in the section Entry Widget Item Attributes.

+

TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional application specific entry widgets (see APPLICATION SPECIFIC ENTRY WIDGETS):

+
+
-entry list
+

The -entry item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings.

+
tepam::argument_dialogbox \
+   -entry {-label Name -variable Entry}
+
+
-text list
+

The -text item generates a multi line text entry widget. The widget height can be selected with the -height attribute.

+
tepam::argument_dialogbox \
+   -text {-label Name -variable Text -height 5}
+
+
-checkbox list
+

A group of check boxes is created with the -checkbox item. The number of check boxes and their option values are specified with a list assigned to the -choices attribute or via a variable declared with the -choicevariable attribute:

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+               -choices {bold italic underline} -default italic}
+

If the labels of the check boxes should differ from the option values, their labels can be defined with the -choicelabels attribute:

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+              -choices {bold italic underline} \
+              -choicelabels {Bold Italic Underline} \
+              -default italic}
+

In contrast to a radio box group, a check box group allows selecting simultaneously several choice options. The selection is stored for this reason inside the defined variable in form of a list, even if only one choice option has been selected.

+
-radiobox list
+

A group of radio boxes is created with the -radiobox item. The number of radio boxes and their option values are specified with a list assigned to the -choices attribute or via a variable declared with the -choicevariable attribute.

+

In contrast to a check box group, a radio box group allows selecting simultaneously only one choice option. The selected option value is stored directly, and not in form of a list, inside the defined variable.

+
tepam::argument_dialogbox \
+   -radiobox {-label "Text adjustment" -variable Adjustment \
+              -choices {left center right} -default left}
+

If the labels of the radio boxes should differ from the option values, their labels can be defined with the -choicelabels attribute:

+
tepam::argument_dialogbox \
+   -radiobox {-label "Text adjustment" -variable Adjustment \
+              -choices {left center right} \
+              -choicelabels {Left Center Right} -default left}
+
+
-checkbutton list
+

The -checkbutton entry widget allows activating or deactivating a single choice option. The result written into the variable will either be 0 if the check button was not activated or 1 if it was activated. An eventually provided default value has also to be either 0 or 1.

+
tepam::argument_dialogbox \
+   -checkbutton {-label Capitalize -variable Capitalize -default 1}
+
+
+

Several types of list and combo boxes are available to handle selection lists.

+
+
-combobox list
+

The combobox is a combination of a normal entry widget together with a drop-down list box. The combobox allows selecting from this drop-down list box a single element. The list of the available elements can be provided either as a list to the -choices attribute, or via a variable that is specified with the -choicevariable attribute.

+
tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
+

And here is an example of using a variable to define the selection list:

+
set TextSizes {8 9 10 12 15 18}
+tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
+
+
-listbox list
+

In contrast to the combo box, the list box is always displayed by the listbox entry widget. Only one element is selectable unless the -multiple_selection attribute is set. The list box height can be selected with the -height attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box size. +The first example uses a variable to define the available choices:

+
set set AvailableSizes
+for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
+tepam::argument_dialogbox \
+   -listbox {-label "Distance" -variable Distance \
+             -choicevariable AvailableSizes -default 6 -height 5}
+

Here is a multi-element selection example. Please note that also the default selection can contain multiple elements:

+
tepam::argument_dialogbox \
+   -listbox {-label "Text styles" -variable Styles \
+             -choices {bold italic underline overstrike} \
+             -choicelabels {Bold Italic Underline Overstrike} \
+             -default {bold underline} -multiple_selection 1 \
+             -height 3}
+
+
-disjointlistbox list
+

A disjoint list box has to be used instead of a normal list box if the selection order is important. The disjoint list box entry widget has in fact two list boxes, one to select elements and one to display the selected elements in the chosen order.

+

Disjoint listboxes allow always selecting multiple elements. With the exception of the -multiple_selection attribute, disjointed list boxes are accepting the same attributes as the normal listbox, e.g. -height, -choices, -choicevariable, -default.

+
tepam::argument_dialogbox \
+   -disjointlistbox {-label "Preferred scripting languages" -variable Languages \
+             -comment "Please select your preferred languages in the order" \
+             -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
+             -default {Tcl Perl Python}}
+
+
+

The file and directory selectors are building a next group of data entry widgets. A paragraph of section Entry Widget Item Attributes explains the widget specific attributes that allow specifying the targeted file types, active directory etc.

+
+
-file list
+

The item -file creates a group composed by an entry widget together with a button that allows opening a file browser. The data type file is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -file {-label "Image file" -variable ImageF \
+          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
+          -initialfile "picture.gif"}
+
+
-existingfile list
+

The item -existingfile creates a group composed by an entry widget together with a button that allows opening a browser to select an existing file. The data type existingfile is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -existingfile {-label "Image file" -variable ImageF \
+                  -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
+                  -initialfile "picture.gif"}
+
+
-directory list
+

The item -directory creates a group composed by an entry widget together with a button that allows opening a directory browser. The data type directory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -directory {-label "Report directory" -variable ReportDir}
+
+
-existingdirectory list
+

The item -existingdirectory creates a group composed by an entry widget together with a button that allows opening a browser to select an existing directory. The data type existingdirectory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -existingdirectory {-label "Report directory" -variable ReportDir}
+
+
+

Finally, there is a last group of some other special data entry widgets.

+
+
-color list
+

The color selector is composed by an entry widget together with a button that allows opening a color browser. The data type color is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute.

+
tepam::argument_dialogbox \
+   -color {-label "Background color" -variable Color -default red}
+
+
-font list
+

The font selector is composed by an entry widget together with a button that allows opening a font browser. The data type font is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute. The entry widget displays an example text in the format of the selected font.

+

The font browser allows selecting by default the font families provided by the font families Tk command as well as a reasonable set of different font sizes between 6 points and 40 points. Different sets of font families and font sizes can be specified respectively via the -font_families or -font_sizes attributes.

+

If no default font is provided via the -default attribute, the default font of the label widget to display the selected font will be used as default selected font. If the font family of this label widget is not part of the available families the first available family is used as default. If the font size of this label widget is not part of the available sizes the next close available size is selected as default size.

+
tepam::argument_dialogbox \
+   -font {-label "Font" -variable Font \
+          -font_sizes {8 10 12 16} \
+          -default {Arial 20 italic}}
+
+
+
+

Entry Widget Item Attributes

+

All the entry widget items are accepting the following attributes:

+
+
-text string
+

Eventual descriptions and comments specified with the -text attribute are displayed above the entry widget.

+
tepam::argument_dialogbox \
+   -entry {-text "Please enter your name bellow" -variable Name}
+
+
-label string
+

The label attribute creates left to the entry widget a label using the provided string as label text:

+
tepam::argument_dialogbox \
+   -entry {-label Name -variable Name}
+
+
-variable string
+

All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget data is stored inside the defined variables.

+
tepam::argument_dialogbox \
+   -existingdirectory {-label "Report directory" -variable ReportDir}
+
+
-default string
+

Eventual default data for the entry widgets can be provided via the -default attribute. The default value is overridden if an argument dialog box with a defined context is called another time. The value acknowledged in a previous call will be used in this case as default value.

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+               -choices {bold italic underline} -default italic}
+
+
-optional 0|1
+

Data can be specified as optional or mandatory with the -optional attribute that requires either 0 (mandatory) or 1 (optional) as attribute data.

+

In case an entry is optional and no data has been entered, e.g. the entry contains an empty character string, the entry will be considered as undefined and the assigned variable will not be defined.

+
tepam::argument_dialogbox \
+   -entry {-label "City" -variable start_city -type string} \
+   -entry {-label "Street" -variable start_street -type string -optional 0} \
+   -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
+
+
-type string
+

If the data type is defined with the -type attribute the argument dialog box will automatically perform a data type check after acknowledging the entered values and before the dialog box is closed. If a type incompatible value is found an error message box appears and the user can correct the value.

+

The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by tepam::procedure (see the tepam::procedure reference manual).

+

Some entry widgets like the file and directory widgets, as well as the color and font widgets are specifying automatically the default data type if no type has been specified explicitly with the -type attribute.

+
tepam::argument_dialogbox \
+   -entry {-label "Street number" -variable start_street_nbr -type integer} \
+
+
-range string
+

Values can be constrained with the -range attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value.

+

The -range attribute has to be used only for numerical arguments, like integers and doubles.

+
tepam::argument_dialogbox \
+   -entry {-label Month -variable Month -type integer -range {1 12}}
+
+
-validatecommand string
+

Custom argument value validations can be performed via specific validation commands that are defined with the -validatecommand attribute. The provided validation command can be a complete script in which the pattern %P is placeholder for the argument value that has to be validated.

+
tepam::argument_dialogbox \
+   -entry {-label "Your comment" -variable YourCom \
+           -validatecommand "IllegalWordDetector %P"}
+

While the purpose of this custom argument validation attribute is the validation of a specific argument, there is also a global data validation attribute -validatecommand that allows performing validation that involves multiple arguments.

+
-validatecommand_error_text string
+

This attribute allows overriding the default error message for a custom argument validation (defined by -validatecommand).

+
+

Some other attributes are supported by the list and combo boxes as well as by the radio and check buttons.

+
+
-choices string
+

Choice lists can directly be defined with the -choices attribute. This way to define choice lists is especially adapted for smaller, fixed selection lists.

+
tepam::argument_dialogbox \
+   -listbox {-label "Text styles" -variable Styles \
+             -choices {bold italic underline} -default underline
+
+
-choicelabels string (only check and radio buttons)
+

If the labels of the check and radio boxes should differ from the option values, they can be defined with the -choicelabels attribute:

+
tepam::argument_dialogbox \
+   -checkbox {-label "Font sytle" -variable FontStyle \
+              -choices {bold italic underline} \
+              -choicelabels {Bold Italic Underline}
+
+
-choicevariable string
+

Another way to define the choice lists is using the -choicevariable attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists.

+
set TextSizes {8 9 10 12 15 18}
+tepam::argument_dialogbox \
+   -combobox {-label "Text size" -variable Size -choicevariable TextSizes}
+
+
-multiple_selection 0|1
+

The list box item (-listbox) allows by default selecting only one list element. By setting the -multiple_selection attribute to 1, multiple elements can be selected.

+
tepam::argument_dialogbox \
+   -listbox {-label "Text styles" -variable Styles \
+             -choices {bold italic underline} -default underline \
+             -multiple_selection 1 -height 3}
+
+
+

Some additional attributes are supported by the file and directory selection widgets.

+
+
-filetypes string
+

The file type attribute is used by the -file and -existingfile items to define the file endings that are searched by the file browser.

+
tepam::argument_dialogbox \
+   -file {-label "Image file" -variable ImageF \
+          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}
+
+
-initialfile string
+

The initial file used by the file browsers of the -file and -existingfile widgets are by default the file defined with the -default attribute, unless a file is specified with the -initialfile attribute.

+
tepam::argument_dialogbox \
+   -file {-variable ImageF -initialfile "picture.gif"}
+
+
-activedir string
+

The -activedir attribute will override the default active search directory used by the file browsers of all file and directory entry widgets. The default active search directory is defined by the directory of a specified initial file (-initialfile) if defined, and otherwise by the directory of the default file/directory, specified with the -default attribute.

+
tepam::argument_dialogbox \
+   -file "-variable ImageF -activedir $pwd"
+
+
+

Finally, there is a last attribute supported by some widgets:

+
+
-height string
+

All widgets containing a selection list (-listbox, -disjointlistbox, -font) as well as the multi line -text widget are accepting the -height attribute that defines the number of displayed rows of the selection lists.

+
tepam::argument_dialogbox \
+   -listbox {-label "Text size" -variable Size \
+             -choices {8 9 10 12 15 18} -default 12 -height 3}
+

If the no height has been explicitly specified the height of the widget will be dynamically adapted to the argument dialog box size.

+
+
+
+

APPLICATION SPECIFIC ENTRY WIDGETS

+

An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the tepam namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes:

+
proc tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
+   upvar Option Option; # if required
+   variable argument_dialogbox; # if required
+   switch $Command {
+      "create" <CreateCommandSequence>
+      "set_choice" <SetChoiceCommandSequence>
+      "set" <SetCommandv>
+      "get" <GetCommandSequence>
+   }
+}
+

Argument_dialogbox takes care about the -label and -text attributes for all entry widgets. For any data entry widget it creates a frame into which the data entry widget components can be placed. The path to this frame is provided via the W argument.

+

The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument Command:

+
+
create
+

The entry widget is called a first time with the command create to build the data entry widget.

+

The frames that are made available by argument_dialogbox for the entry widgets are by default only extendable in the X direction. To make them also extendable in the Y direction, for example for extendable list boxes, the command ad_form(make_expandable) $W has to be executed when an entry widget is built.

+
set_choice
+

The entry widget procedure is only called with the set_choice command if the -choices or -choicevariable has been specified. The command is therefore only relevant for list and combo boxes.

+

The available selection list that is either specified with the -choices or -choicevariable attribute is provided via the Par argument to the entry widget procedure. This list can be used to initialize an available choice list.

+
set
+

If a default value is either defined via the -default attribute or via a preceding call the entry widget procedure is called with the set command. The argument Par contains in this case the value to which the entry widget has to be initialized.

+
get
+

The entry widget procedure command get has to return the current value of the entry widget.

+
+

Eventually specified entry widget item attributes are available via the Option array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the upvar command.

+

There may be a need to store some information in a variable. The array variable argument_dialogbox has to be used for this purpose together with array indexes starting with "$W,", e.g. argument_dialogbox($W,values).

+

Examples of entry widget procedures are directly provided by the TEPAM package source file that specifies the standard entry widget procedures. The simplest procedure is the one for the basic entry widget:

+
proc tepam::ad_form(entry) {W Command {Par ""}} {
+   switch $Command {
+      "create" {pack [entry \$W.entry] -fill x \
+                        -expand yes -pady 4 -side left}
+      "set" {\$W.entry insert 0 $Par}
+      "get" {return [\$W.entry get]}
+   }
+}
+

It is also possible to relay on an existing entry widget procedure to derive a new, more specific one. The radiobox widget is used for example, to create a new entry widget that allows selecting either left, center or right. The original radiobox widget is called with the set_choice command immediately after the create command, to define the fixed list of selection options.

+
proc tepam::ad_form(rcl) {W Command {Par ""}} {
+   set Res [ad_form(radiobox) $W $Command $Par]
+   if {$Command=="create"} {
+      ad_form(radiobox) $W set_choice {left center right}
+   }
+   return $Res
+}
+

Please consult the TEPAM package source file to find additional and more complex examples of entry widget procedures.

+
+

VARIABLES

+

The argument_dialogbox is using two variables inside the namespace ::tepam:

+
+
argument_dialogbox
+

Application specific entry widget procedures can use this array variable to store their own data, using as index the widget path provided to the procedure, e.g. argument_dialogbox($W,<sub_index>).

+
last_parameters
+

This array variable is only used by an argument dialog box if its context has been specified via the -context attribute. The argument dialog box position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time.

+

To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the last_parameter array variable contents in a configuration file which is loaded the next time an application is launched.

+
+
+ + +

Category

+

Argument entry form, mega widget

+
+ +
ADDED embedded/www/tcllib/files/modules/tepam/tepam_doc_gen.html Index: embedded/www/tcllib/files/modules/tepam/tepam_doc_gen.html ================================================================== --- embedded/www/tcllib/files/modules/tepam/tepam_doc_gen.html +++ embedded/www/tcllib/files/modules/tepam/tepam_doc_gen.html @@ -0,0 +1,405 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tepam::doc_gen(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam::doc_gen - TEPAM DOC Generation, reference manual

+
+ + +

Description

+

This package generates documentations of TEPAM procedures (procedures that have been declared with tepam::procedure). The documents are generated in the classic UNIX document style using the following document sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc Gen provides support for various document formats. Support for additional formats can be added if necessary.

+

The TEPAM Doc Gen package provides the following commands:

+
+
tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name
+

This command generates the documentation for a specified procedure (name) in one of the supported formats (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool), or in a custom specific format. The format is specified via ?format?. The flag ?-header_footer? adds to the documentation file header and footer. If ?dest_file? is specified the documentation is stored in a file (the file header and footer are added automatically in this case) and the file name is returned. Otherwise the documentation string is returned by generate.

+
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern search_pattern? ?-src_string src_string | -src_file src_file? ?-dest_file dest_file? ?name?
+

This command inserts procedure documentations into an existing master document at the locations indicated by insertion placeholders which are matching the pattern of ?search_pattern?. The existing master document is either provided as data to the argument (?src_string?) or via a file (?src_file?). The final document is returned by patch if no destination file is defined (?dest_file?). Otherwise, the document is stored in the specified file, and the number of insertion placeholders that could be handled successfully is returned.

+

Any insertion placeholders of the master document are handled by default. By defining the argument ?name? the documentation insertion will be restricted to a particular procedure.

+
+
+

ARGUMENTS

+
+
?-format format?
+

Specifies the documentation format. TEPAM Doc Gen provides support for the following formats:

+
    +

  • TXT - Text format (default)

    • +

  • HTML

    • +

  • POD - Perl Plain Old Documentation format (PerlPOD)

    • +

  • DT - TclLib DocTool format

    • +
+

Section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how support for additional formats can be added.

+
?-style style?
+

The documentation is by default generated in Tcl style (e.g. command arg1 arg2 ...). C-style documentation can be generated by setting this argument to 'C' (e.g. command(arg1,arg2,...)).

+
?-dest_file dest_file?
+

If ?dest_file? is defined the documentation is written into the specified destination file. Otherwise the documentation string is returned by the commands generate and patch.

+
name / ?name?
+

This is the name of the procedure for which the documentation has to be generated. This is a mandatory argument for generate, but an optional argument for patch.

+
?-header_footer?
+

Generate adds to the generated procedure documentation the file header and footer only if a file is generated. By selecting the flag ?-header_footer? the header and footer are also generated if the documentation is returned as string by generate.

+
?-src_string src_string | -src_file src_file?
+

Patch inserts procedure documentations into an existing document that is either provided as string to the argument (?src_string?) or as a file (?src_file?). One of these two arguments need to be specified.

+
?-search_pattern search_pattern?
+

The argument ?search_pattern? defines the documentation insertion placeholder used in a document. It is a regular expression accepted by regexp and needs to contain a parenthesized sub-expression that contains the procedure name for which the documentation needs to be inserted.

+

The default insertion placeholder pattern is \{!(.*?)!\}, which means that the procedure name will be embedded between {! and !}. The section EXAMPLES contains a custom insertion placeholder pattern example.

+
+
+

PREDEFINED DOCUMENT FORMATS

+

TEPAM Doc Gen pre-defines the following document formats:

+

TXT - Text format

+

The documentation will be generated in a simple text format if this format is selected. The format can be customized via the following variable:

+
+
tepam::doc_gen::Option(TXT,MaxLineLength)
+

Default: 80

+

This variable defines the line wrapping limit (character position).

+
+
+

HTML - HTML format

+

TEPAM Doc Gen generates CSS styled HTML files. The HTML documentation can be customized via the following variable:

+
+
tepam::doc_gen::Option(HTML,CssFile)
+

Default: "tepam_doc_stylesheet.css"

+

This variable specifies the CSS stylesheet file that is referred by the generated HTML files.

+
+

The CSS stylesheet can be customized to change the documentation formatting. A good starting point to create a customized CSS stylesheet is to use the CSS file provided by the TEPAM Doc Gen example/demo. The HTML documentation uses the following CSS class styles:

+
    + +

  • h1.tepam_page_title - Document page title. Only used by generate if a file is created or if the header and footer are built (flag ?-header_footer? selected).

    • +

  • div.tepam_command_help - Documentation container. The entire procedure documentation is placed inside this container.

    • +

  • p.tepam_section_title - Section title (e.g. Name, Synopsis, Description, ...)

    • +

  • p.tepam_sub_section_title - Sub-section title (used to separate the documentation of multiple sub-procedures)

    • +

  • p.tepam_name - Name section

    • +

  • p.tepam_synopsis - Synopsis section

    • +

  • p.tepam_description - Single description paragraph

    • +

  • ul.tepam_description_list - Item of a HTML bulleted/unordered list inside the description section

    • +

  • dt.tepam_argument - Item of a HTML description list used to list the procedure arguments

    • +

  • p.tepam_argument_description - Argument description paragraph

    • +

  • p.tepam_argument_attribute - Argument attribute line

    • +

  • pre.tepam_example - Example section

    • +
+
+

POD - Perl document format

+

The documentation is generated in the Perl Plain Old Documentation format (PerlPOD) if this format is selected.

+
+

DT - TclLib DocTools format

+

The documentation is generated in the Tcllib DocTools format if this format is selected.

+
+
+

ADDING SUPPORT FOR NEW DOCUMENT FORMATS

+

Support for a new document format can be added by defining in the tepam::doc_gen namespace a set of procedures that generate the different document components.

+

The following documentation listing contains tokens that refer to the different document generation procedures:

+
      <01>
+ <03> <20s>   NAME<20e>
+      <30s>       message_box - Displays text in a message box<30e>
+      <20s>   SYNOPSYS<20e>
+      <40s>       message_box [-mtype <mtype>] <text><40e>
+      <20s>   DESCRIPTION<20e>
+      <21s>     message_box<21e>
+      <54s>       message_box [-mtype <mtype>] <text><54e>
+      <50s>       This procedure allows displaying a text in an message box. The following
+                  message types are supported:<50e>
+ <51> <53s>       * Info<53e>
+      <53s>       * Warning<53e>
+      <53s>       * Error<53e>                                           <52>
+      <50s>       If the text parameter is use multiple times the different texts are
+                  concatenated to create the message text.<50e>
+      <20s>   ARGUMENTS<20e>
+ <60> <62s>       [-mtype <mtype>]<62e>
+ <63> <65s>          Message type<65e>
+      <66s>          Default: "Warning"<66e>
+      <66s>          Multiple: yes<66e>
+      <66s>          Choices: Info, Warning, Error<66e>                  <64>
+      <62s>       <text><62e>
+ <63> <65s>          One or multiple text lines to display<65e>
+      <66s>          Type: string<66e>
+      <66s>          Multiple: yes<66e>                                  <64><61>
+      <20s>   EXAMPLE<20e>
+ <70> <72s>       message_box "Please save first the document"<72e>
+      <73s>       -> 1<73e>                                              <71><04>
+      <02>
+

There are 2 types of document generation procedures:

+
+ +
Content generation procedures (e.g. <40s>...<40e>)
+

These procedures generate some document content based on the text that is provided as procedure argument. The listing above shows two tokens for these procedures to indicate the beginning and the end of the generated content.

+
Control generation procedures (e.g. <03>)
+

These procedures generate control constructs, for example to generate the prolog code and epilog code for lists, sections, etc. These procedures have no argument.

+
+

The following set of procedures needs to be defined to provide support for a new document format:

+
+
01 - gen($Format,Header) {Text}
+

Only called if doc_gen generates a file or if it is called with the flag ?-header_footer?. The procedure creates the file header. The provided parameter is the procedure name for which the documentation has to be generated.

+
02 - gen($Format,Footer) {Text}
+

Only called if doc_gen generates a file or if it is called with the flag ?-header_footer?. The procedure creates the file footer.

+
03 - gen($Format,Begin) {}
+

Generates the documentation prolog (preamble)

+
04 - gen($Format,End) {}
+

Generates the documentation epilog

+
20 - gen($Format,SectionTitle) {Text}
+

Generates a section title (e.g. Name, Synopsis, Description, ...). The raw title text is provided as parameter

+
21 - gen($Format,SubSectionTitle) {Text}
+

Generates a sub-section title. Sub-sections are used if a single documentation is generated for multiple sub-commands to make a separation between them. The raw title text is provided as parameter

+
30 - gen($Format,Name) {Text}
+

Generates the name section (without title). The raw section text is provided as parameter.

+
40 - gen($Format,Synopsis) {Text}
+

Generates the synopsis section (without title). The section text provided as parameter is pre-formatted (the argument strings are generated by gen($Format,ArgumentString)).

+
50 - gen($Format,Description) {Text}
+

Generates a description paragraph. The raw paragraph text is provided as parameter.

+
51 - gen($Format,DescriptionListBegin) {}
+

Generates the prolog of a bulleted/unordered list inside the description section. This prolog is usually the start code of a list structure.

+
52 - gen($Format,DescriptionListEnd) {}
+

Generates the epilog of a bulleted/unordered list inside the description section. This epilog is usually the end code of a list structure.

+
53 - gen($Format,DescriptionListItem) {Text}
+

Generates a text item in a bulleted/unordered description list. The raw item text is provided as parameter.

+
54 - gen($Format,DescriptionSynopsis) {Text}
+

Generates the synopsis line on the beginning of the description section. The command can return an empty string if no synopsys line is required at this place.

+

Some formats (e.g. Tcl DocTools) require that the synopsis line is defined in the description section, to build then automatically the synopsis section. The section text provided as parameter is pre-formatted (the argument strings are generated by gen($Format,ArgumentString)).

+
60 - gen($Format,ArgumentListBegin) {}
+

Generates the prolog of argument list (definition/non-bulleted list). This prolog is usually the start code of a definition list.

+
61 - gen($Format,ArgumentListEnd) {}
+

Generates the epilog of the argument list. This epilog is usually the end string of a list structure.

+
62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type}
+

Generates an argument item line inside the argument list. This command can rely on gen($Format,ArgumentDetailBegin) since the parameters are identical.

+
63 - gen($Format,ArgumentDetailBegin) {}
+

Generates the argument details prolog (preamble).

+
64 - gen($Format,ArgumentDetailEnd) {}
+

Generates the argument details epilog

+
65 - gen($Format,ArgumentDescription) {Text}
+

Generates the argument description (single paragraph).

+
66 - gen($Format,ArgumentAttribute) {Text}
+

Generates a single argument attribute string. The command is called individually for each attribute.

+
70 - gen($Format,ExampleBegin) {}
+

Generates the example section prolog (preamble)

+
71 - gen($Format,ExampleEnd) {}
+

Generates the example section epilog

+
72 - gen($Format,ExampleCommandLine) {Text}
+

Generates a single command line in the example section. The command is called for each individual command line.

+
73 - gen($Format,ExampleResultLine) {Text}
+

Generates a command result line

+
80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type}
+

Generates the part of the command line or the synopsis that is specific to an argument. The generated string has to indicate if an argument is optional, named and if it is a flag.

+

The following parameters are provided to this procedure:

+
+ +
Name
+

Name of the argument

+
IsOptional
+

If true (=1) the argument is optional which should be indicated by the generated string (for example by putting the argument into brackets {} or into question marks '?'):

+
gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"
+
+
IsNamed
+

If true (=1) an argument is a named argument (option). The generated string should in this case contain the argument/option name, followed by the argument itself:

+
gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype <mtype>"
+

Named arguments can also be optional:

+
gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <mtype>]"
+
+
Type
+

Indicates the type of the argument. If the type is set to none the argument is a flag, which needs to be indicated by the generated string. Example:

+
gen(TXT,ArgumentString) close 1 1 none -> "[-close]"
+
+
+
+
+

EXAMPLES

+

tepam::doc_gen::generate

+

The TEPAM Doc Gen package can be explored by generating the documentation of the command tepam::doc_gen::generate. The following example generates the document in text format (default format):

+
tepam::doc_gen::generate tepam::doc_gen::generate
+

The next example generates the documentation in HTML format:

+
tepam::doc_gen::generate -format HTML tepam::doc_gen::generate
+

The flag ?header_footer? adds also the file header and footer:

+
tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate
+

The documentation can directly be stored in a file. The file header and footer are automatically generated in this way:

+
tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate
+

The generated HTML file refers a CSS stylesheet file (default: tepam_doc_stylesheet.css). To display the HTML file correctly this CSS stylesheet file needs to be copied into the directory of the generated HTML file.

+

The Tcl DOC Tools format can be used as intermediate format to generate other formats, for example HTML:

+
+# Generate the documentation in Tcl Doc Tool format
+set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
+
+# Create a new doc tools object (HTML format)
+package require doctools
+::doctools::new myDoc -format html
+
+# Open the HTML file, and write the HTML formatted documentation
+set fHtml [open doc_gen.dt.html w]
+puts $fHtml [myDoc format $dt]
+close $fHtml
+
+
+

tepam::doc_gen::patch

+

While generate provides a limited number of possibilities to vary the document structure, patch offers more flexibility. Multiple documentations for different procedures and meta information can for example be added.

+

The following listing shows how the patch command works. It defines first a HTML master document string that contains 2 procedure documentation placeholders ({*<ProcedureName>*}). There placeholders are replaced by patch with the generated documentation of the referred procedures. Since nonstandard placeholders are used, patch is called with an explicit placeholder pattern definition (argument search_pattern).

+
+# Define the HTML master document
+set HtmlMasterDoc {\
+<html>
+  <head>
+    <title>tepam::doc_gen</title>
+    <link rel="stylesheet" href="tepam_doc_stylesheet.css">
+    <meta content="documentation" name="keywords"></meta>
+  </head>
+  <body>
+    <h1>tepam::doc_gen</h1>
+      <h2>Generate</h2>
+{*tepam::doc_gen::generate*}
+      <h2>Patch</h2>
+{*tepam::doc_gen::patch*}
+  </body>
+<html>\
+}
+
+# Patch the master document: This will replace the placeholders by the 
+# procedure documentation divisions:
+tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
+                      -src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
+
+
+
+ + +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/tepam/tepam_introduction.html Index: embedded/www/tcllib/files/modules/tepam/tepam_introduction.html ================================================================== --- embedded/www/tcllib/files/modules/tepam/tepam_introduction.html +++ embedded/www/tcllib/files/modules/tepam/tepam_introduction.html @@ -0,0 +1,352 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tepam(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam - An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager

+
+ +

Description

+

This document is an informal introduction into TEPAM, the Tcl's Enhanced Procedure and Argument Manager. Detailed information to the TEPAM package is provided in the tepam::procedure and tepam::argument_dialogbox reference manuals.

+
+

OVERVIEW

+

This package provides a new Tcl procedure declaration syntax that simplifies the implementation of procedure subcommands and the handling of the different types of procedure arguments like flags or switches, options, unnamed arguments, optional and mandatory options and arguments, default values, etc. Procedure declarations can be enriched with detailed information about the procedure and its arguments. This information is used for the following purposes:

+

First of all, a preamble is added in front of the body of a procedure that is declared with TEPAM. This preamble calls an argument manager that that uses the provided information to check the validity of the argument types and values before the procedure body is executed. Then, the information is used to generate help and usage texts if requested, or to generate clear error message in case an argument validation fails. The information also allows generating automatically graphical forms that allows an interactive definition of all arguments, in case a procedure is called interactively. And finally, the additional information helps self-commenting in a clean way the declaration of a procedure and of all its arguments.

+

The graphical form generator that creates the necessary argument specification forms for the interactive procedure calls is also available for other purposes than for procedure argument specifications. It allows creating code efficiently complex parameter entry forms that are usable independently from TEPAM's new procedure definition method.

+

Here is a short overview about all major TEPAM features:

+
    +

  • New self-documenting procedure declaration syntax: The additional information to declare properly a procedure has not to be provided with additional statements, but can be added in a natural syntax directly into the procedure header.

    • +

  • Easy way to specify subcommands: A subcommand is declared like a procedure, simply with a procedure name composed by a base name followed by a subcommand name. Sub-subcommands are created identically using simply procedure names composed by 3 words.

    • +

  • Flexible usage of flags (switches), options (named arguments) and unnamed arguments. Option names are optionally automatically completed.

    • +

  • Support for default values, mandatory/optional options and arguments, choice lists, value ranges, multiple usable options/arguments.

    • +

  • Choice of a named arguments first, unnamed arguments later procedure calling style (typical for Tcl commands) or of an unnamed arguments first, named arguments later procedure calling style (typical for Tk commands).

    • +

  • In case the named arguments first, unnamed arguments later style (Tcl) is selected: Clear separation between options and arguments via the "--" flag. The unnamed arguments can optionally be accessed as options (named arguments).

    • +

  • Automatic type and value check before the procedure body is executed, taking into account validation ranges, choice lists and custom validation commands. Generation of clear error message if necessary.

    • +

  • Many predefined types exist (integer, boolean, double, color, file, font, ...). Other application specific types can easily be added.

    • +

  • Automatic help and usage text generation if a procedure is called with the -help flag.

    • +

  • Automatic generation of an interactive argument definition form, in case a procedure is called with the -interactive flag.

    • +

  • Procedure calls can be logged which is useful to get for interactively called procedures the command call lines.

    • +

  • Powerful and code efficient generation of complex parameter definition forms.

    • +
+
+

PROCEDURE DECLARATION

+

TEPAM's procedure declaration syntax is simple and self-explaining. Instead of declaring a procedure with the Tcl key word proc, a procedure is declared with the TEPAM command procedure which takes as proc also 3 arguments: The procedure name, the procedure header and the procedure body.

+

The following example declares the subcommand message of the procedure display. This command has several named and unnamed arguments:

+
tepam::procedure {display message} {
+   -return            -
+   -short_description "Displays a simple message box"
+   -description       "This procedure allows displaying a configurable message box."
+   -args {
+      {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
+      {-font -type font -default {Arial 10 italic} -description "Message text font"}
+      {-level -type integer -optional -range {1 10} -description "Message level"}
+      {-fg -type color -default black -description "Message color"}
+      {-bg -type color -optional -description "Background color"}
+      {-no_border -type none -description "Use a splash window style (no border)"}
+      {-log_file -type file -optional -description "Optional message log file"}
+      {text -type string -multiple -description "Multiple text lines to display"}
+   }
+} {
+   puts "display message:"
+   foreach var {mtype font level fg bg no_border log_file text} {
+      if {[info exists $var]} {
+         puts  "  $var=[set $var]"
+      }
+   }
+}
+

A call of procedure that has been declared in this way will first invoke the TEPAM argument manager, before the procedure body is executed. The argument manager parses the provided arguments, validates them, completes them eventually with some default values, and makes them finally available to the procedure body as local variables. In case an argument is missing or has a wrong type, the argument manager generates an error message that explains the reason for the error.

+

As the example above shows, the TEPAM command procedure accepts subcommand definitions as procedure name and allows defining much more information than just the argument list inside the procedure header. The procedure body on the other hand is identical between a command declared with proc and a command declared with procedure.

+

The procedure header allows defining in addition to the arguments some procedure attributes, like a description, information concerning the return value, etc. This information is basically used for the automatic generation of comprehensive help and usage texts.

+

A list of argument definition statements assigned to the -args argument is defining the procedure arguments. Each argument definition statement starts with the argument name, optionally followed by some argument attributes.

+

Three types of arguments can be defined: Unnamed arguments, named arguments and flags. The distinction between the named and unnamed arguments is made by the first argument name character which is simply "-" for named arguments. A flag is defined as named argument that has the type none.

+

Named and unnamed arguments are mandatory, unless they are declared with the -optional flag and unless they have a default value specified with the -default option. Named arguments and the last unnamed argument can have the attribute -multiple, which means that they can be defined multiple times. The expected argument data type is specified with the -type option. TEPAM defines a large set of standard data types which can easily be completed with application specific data types.

+

The argument declaration order has only an importance for unnamed arguments that are by default parsed after the named arguments (Tcl style). A variable allows changing this behavior in a way that unnamed arguments are parsed first, before the named arguments (Tk style).

+
+

PROCEDURE HELP

+

The declared procedure can simply be called with the -help option to get the information about the usage of the procedure and its arguments:

+
display message -help
+  ->
+NAME
+      display message - Displays a simple message box
+SYNOPSYS
+      display message
+            [-mtype <mtype>] :
+               Message type, default: "Warning", choices: {Info Warning Error}
+            [-font <font>] :
+               Message text font, type: font, default: Arial 10 italic
+            [-level <level>] :
+               Message level, type: integer, range: 1..10
+            [-fg <fg>] :
+               Message color, type: color, default: black
+            [-bg <bg>] :
+               Background color, type: color
+            [-no_border ] :
+               Use a splash window style (no border)
+            [-log_file <log_file>] :
+               Optional message log file, type: file
+            <text> :
+               Multiple text lines to display, type: string
+DESCRIPTION
+      This procedure allows displaying a configurable message box.
+
+

PROCEDURE CALL

+

The specified procedure can be called in many ways. The following listing shows some valid procedure calls:

+
display message "The document hasn't yet been saved!"
+-> display message:
+     mtype=Warning
+     font=Arial 10 italic
+     fg=black
+     no_border=0
+     text={The document hasn't yet been saved!}
+display message -fg red -bg black "Please save first the document"
+-> display message:
+     mtype=Warning
+     font=Arial 10 italic
+     fg=red
+     bg=black
+     no_border=0
+     text={Please save first the document}
+display message -mtype Error -no_border "Why is here no border?"
+-> display message:
+     mtype=Error
+     font=Arial 10 italic
+     fg=black
+     no_border=1
+     text={Why is here no border?}
+display message -font {Courier 12} -level 10 \
+   "Is there enough space?" "Reduce otherwise the font size!"
+-> display message:
+     mtype=Warning
+     font=Courier 12
+     level=10
+     fg=black
+     no_border=0
+     text={Is there enough space?} {Reduce otherwise the font size!}
+

The next lines show how wrong arguments are recognized. The text argument that is mandatory is missing in the first procedure call:

+
display message -font {Courier 12}
+  -> display message: Required argument is missing: text
+

Only known arguments are accepted:

+
display message -category warning Hello
+  -> display message: Argument '-category' not known
+

Argument types are automatically checked and an error message is generated in case the argument value has not the expected type:

+
display message -fg MyColor "Hello"
+  -> display message: Argument 'fg' requires type 'color'.  Provided value: 'MyColor'
+

Selection choices have to be respected ...

+
display message -mtype Fatal Hello
+  -> display message: Argument (mtype) has to be one of the  following elements: Info, Warning, Error
+

... as well as valid value ranges:

+
display message -level 12 Hello
+  -> display message: Argument (level) has to be between 1 and 10
+
+

INTERACTIVE PROCEDURE CALLS

+

The most intuitive way to call the procedure is using an form that allows specifying all arguments interactively. This form will automatically be generated if the declared procedure is called with the -interactive flag. To use this feature the Tk library has to be loaded.

+
display message -interactive
+

The generated form contains for each argument a data entry widget that is adapted to the argument type. Check buttons are used to specify flags, radio boxes for tiny choice lists, disjoint list boxes for larger choice lists and files, directories, fonts and colors can be selected with dedicated browsers.

+

After acknowledging the specified argument data via an OK button, the entered data are first validated, before the provided arguments are transformed into local variables and the procedure body is executed. In case the entered data are invalid, a message appears and the user can correct them until they are valid.

+

The procedure calls can optionally be logged in a variable. This is for example useful to get the command call lines of interactively called procedures.

+
+

FLEXIBLE ARGUMENT DIALOG BOX

+

The form generator that creates in the previous example the argument dialog box for the interactive procedure call is also available for other purposes than for the definition of procedure arguments. If Tk has been loaded TEPAM provides and argument dialog box that allows creating complex parameter definition forms in a very efficient way.

+

The following example tries to illustrate the simplicity to create complex data entry forms. It creates an input mask that allows specifying a file to copy, a destination folder as well as a checkbox that allows specifying if an eventual existing file can be overwritten. Comfortable browsers can be used to select files and directories. And finally, the form offers also the possibility to accept and decline the selection. Here is the code snippet that is doing all this:

+
tepam::argument_dialogbox \
+   -existingfile {-label "Source file" -variable SourceFile} \
+   -existingdirectory {-label "Destination folder" -variable DestDir} \
+   -checkbutton {-label "Overwrite existing file" -variable Overwrite}
+

The argument_dialogbox returns ok if the entered data are validated. It will return cancel if the data entry has been canceled. After the validation of the entered data, the argument_dialogbox defines all the specified variables with the entered data inside the calling context.

+

An argument_dialogbox requires a pair of arguments for each variable that it has to handle. The first argument defines the entry widget type used to select the variable's value and the second one is a lists of attributes related to the variable and the entry widget.

+

Many entry widget types are available: Beside the simple generic entries, there are different kinds of list and combo boxes available, browsers for existing and new files and directories, check and radio boxes and buttons, as well as color and font pickers. If necessary, additional entry widgets can be defined.

+

The attribute list contains pairs of attribute names and attribute data. The primary attribute is -variable used to specify the variable in the calling context into which the entered data has to be stored. Another often used attribute is -label that allows adding a label to the data entry widget. Other attributes are available that allow specifying default values, the expected data types, valid data ranges, etc.

+

The next example of a more complex argument dialog box provides a good overview about the different available entry widget types and parameter attributes. The example contains also some formatting instructions like -frame and -sep which allows organizing the different entry widgets in frames and sections:

+
set ChoiceList {"Choice 1" "Choice 2" "Choice 3" "Choice 4" "Choice 5" "Choice 6"}
+set Result [tepam::argument_dialogbox \
+   -title "System configuration" \
+   -context test_1 \
+   -frame {-label "Entries"} \
+      -entry {-label Entry1 -variable Entry1} \
+      -entry {-label Entry2 -variable Entry2 -default "my default"} \
+   -frame {-label "Listbox & combobox"} \
+      -listbox {-label "Listbox, single selection" -variable Listbox1 \
+                -choices {1 2 3 4 5 6 7 8} -default 1 -height 3} \
+      -listbox {-label "Listbox, multiple selection" -variable Listbox2
+                -choicevariable ChoiceList -default {"Choice 2" "Choice 3"}
+                -multiple_selection 1 -height 3} \
+      -disjointlistbox {-label "Disjoined listbox" -variable DisJntListbox
+                        -choicevariable ChoiceList \
+                        -default {"Choice 3" "Choice 5"} -height 3} \
+      -combobox {-label "Combobox" -variable Combobox \
+                 -choices {1 2 3 4 5 6 7 8} -default 3} \
+   -frame {-label "Checkbox, radiobox and checkbutton"} \
+      -checkbox {-label Checkbox -variable Checkbox
+                 -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
+                 -default italic} \
+      -radiobox {-label Radiobox -variable Radiobox
+                 -choices {bold italic underline} -choicelabels {Bold Italic Underline} \
+                 -default underline} \
+      -checkbutton {-label CheckButton -variable Checkbutton -default 1} \
+   -frame {-label "Files & directories"} \
+      -existingfile {-label "Input file" -variable InputFile} \
+      -file {-label "Output file" -variable OutputFile} \
+      -sep {} \
+      -existingdirectory {-label "Input directory" -variable InputDirectory} \
+      -directory {-label "Output irectory" -variable OutputDirectory} \
+   -frame {-label "Colors and fonts"} \
+      -color {-label "Background color" -variable Color -default red} \
+      -sep {} \
+      -font {-label "Font" -variable Font -default {Courier 12 italic}}]
+

The argument_dialogbox defines all the specified variables with the entered data and returns ok if the data have been validated via the Ok button. If the data entry is cancelled by activating the Cancel button, the argument_dialogbox returns cancel.

+
if {$Result=="cancel"} {
+   puts "Canceled"
+} else { # $Result=="ok"
+   puts "Arguments: "
+   foreach Var {
+      Entry1 Entry2
+      Listbox1 Listbox2 DisJntListbox
+      Combobox Checkbox Radiobox Checkbutton
+      InputFile OutputFile InputDirectory OutputDirectory
+      Color Font
+   } {
+      puts "  $Var: '[set $Var]'"
+   }
+}
+-> Arguments:
+   Entry1: 'Hello, this is a trial'
+   Entry2: 'my default'
+   Listbox1: '1'
+   Listbox2: '{Choice 2} {Choice 3}'
+   DisJntListbox: '{Choice 3} {Choice 5}'
+   Combobox: '3'
+   Checkbox: 'italic'
+   Radiobox: 'underline'
+   Checkbutton: '1'
+   InputFile: 'c:\tepam\in.txt'
+   OutputFile: 'c:\tepam\out.txt'
+   InputDirectory: 'c:\tepam\input'
+   OutputDirectory: 'c:\tepam\output'
+   Color: 'red'
+   Font: 'Courier 12 italic'
+
+ + +

Category

+

Procedures, arguments, parameters, options

+
+ +
ADDED embedded/www/tcllib/files/modules/tepam/tepam_procedure.html Index: embedded/www/tcllib/files/modules/tepam/tepam_procedure.html ================================================================== --- embedded/www/tcllib/files/modules/tepam/tepam_procedure.html +++ embedded/www/tcllib/files/modules/tepam/tepam_procedure.html @@ -0,0 +1,798 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tepam::procedure(n) 0.5.0 tcllib "Tcl's Enhanced Procedure and Argument Manager"

+

Name

+

tepam::procedure - TEPAM procedure, reference manual

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.3
    • +
  • package require tepam ?0.5?
    • +
+ +
+
+

Description

+

This package provides an alternative way to declare Tcl procedures and to manage its arguments. There is a lot of benefit to declare a procedure with TEPAM rather than with the Tcl standard command proc: TEPAM allows specifying inside the procedure declaration all information that is required to generate comprehensive documentations and help support. The information is also used by an automatically invoked argument checker that validates the provided procedure arguments before the procedure body is executed. Finally, a procedure can be called interactively which will open a graphical form that allows specifying the procedure arguments.

+

TEPAM simplifies also the handling of the different types of argument, like the named arguments (often also called options) and the unnamed arguments. TEPAM supports the named first, unnamed later style (typical Tcl command style) as well as also the unnamed first, named later style (typical Tk command style). TEPAM takes care about default values for arguments, optional arguments, multiple applicable arguments, etc. and eliminates the need to check the validity of the argument inside the procedure bodies.

+

An informal overview of all the TEPAM procedure declaration and calling features as well as a short introduction into TEPAM is provided by tepam(n).

+
+

TERMINOLOGY

+

The exact meaning of several terms that are used in this document will be shortly explained to avoid any ambiguities and misunderstandings.

+
+
Subcommand
+

The usage of subcommands is heavily used in the Tcl language. Several commands are incorporated into a single main command and are selectable via the first argument.

+

The string command is an example of such a command that implements for example subcommands to check a character string length, to compare strings, to extract substrings, etc:

+
string length string
+string compare string string
+string range string first last
+...
+

TEPAM provides a framework that allows implementing easily such subcommands in form of Tcl procedures. It allows not only defining a first level of subcommands, but also a higher level of subcommands. The string command class check could be implemented as independent sub-sub-commands of the string command:

+
string is alnum string
+string is integer string
+string is double string
+...
+
+
Procedure attribute
+

TEPAM allows attaching to a declared procedure different kind of attributes. Some of these attributes are just used for documentation purposes, but other attributes specify the way how the procedure has to be called. Also the procedure arguments are defined in form of a procedure attribute.

+
Argument
+

TEPAM uses the term argument for the parameters of a procedure.

+

The following example calls the subcommand string compare with several arguments:

+
string compare -nocase -length 3 "emphasized" "emphasised"
+

The following paragraphs discuss these different argument types.

+
Named argument
+

Some parameters, as -length 3 of the subcommand string compare have to be provided as pairs of argument names and argument values. This parameter type is often also called option.

+

TEPAM uses the term named argument for such options as well as for the flags (see next item).

+
Flag, switch
+

Another parameter type is the flag or the switch. Flags are provided simply by naming the flag leading with the '-' character. The -nocase of the previous string compare example is such a flag.

+

Flags are considered by TEPAM like a special form of named arguments.

+
Unnamed argument
+

For the other parameters, e.g. the ones for which the argument name has not to be mentioned, TEPAM uses the term unnamed argument. The previous string compare example uses for the two provided character strings two unnamed arguments.

+
Argument attribute
+

TEPAM allows describing the purpose of each procedure argument with argument attributes. While some of them are just documenting the attributes, most attributes are used by an argument manager to control and validate the arguments that are provided during a procedure call. Argument attributes are used to specify default values, parameter classes (integer, xdigit, font, ...), choice validation lists, value ranges, etc.

+
Named arguments first, unnamed arguments later
+

The string compare command of the previous example requires that the named arguments (options, flags) are provided first. The two mandatory (unnamed) arguments have to be provided as last argument.

+
string compare -nocase -length 3 Water $Text
+

This is the usual Tcl style (exceptions exist) which is referred in the TEPAM documentation as named arguments first, unnamed arguments later style.

+
Unnamed arguments first, named arguments later
+

In contrast to most Tcl commands, Tk uses generally (exceptions exist also here) a different calling style where the unnamed arguments have to be provided first, before the named arguments have to be provided:

+
pack .ent1 .ent2 -fill x -expand yes -side left
+

This style is referred in the TEPAM documentation as unnamed arguments first, named arguments later style.

+
+
+

PROCEDURE DECLARATION

+

TEPAM allows declaring new Tcl procedures with the command tepam::procedure that has similar to the standard Tcl command proc also 3 arguments:

+
+
tepam::procedure name attributes body
+
+
+

The TEPAM procedure declaration syntax is demonstrated by the following example:

+
tepam::procedure {display message} {
+   -short_description
+      "Displays a simple message box"
+   -description
+      "This procedure allows displaying a configurable\
+       message box. The default message type that is\
+       created is a warning, but also errors and info can\
+       be generated.
+       The procedure accepts multiple text lines."
+   -example
+      {display message -mtype Warning "Save first your job"}
+   -args {
+      {-mtype -choices {Info Warning Error} \
+              -default Warning -description "Message type"}
+      {text   -type string -multiple \
+              -description "Multiple text lines to display"}
+   }
+} {
+   puts "Message type: $mtype"
+   puts "Message: $text"
+}
+

The 3 arguments of procedure are:

+
+
name
+

The procedure name can be used in very flexible ways. Procedure names can have namespace qualifiers. By providing a two element name list as procedure name, a subcommand of a procedure will be declared. It is even possible to declare sub-sub-commands of a procedure by providing name lists with three elements.

+

Here are some valid procedure declarations using different procedure names (the attribute and body arguments are empty for simplicity):

+
# Simple procedure name:
+tepam::procedure display_message {} {}
+
+# Procedure declared in the main namespace:
+tepam::procedure ::display_message {} {}
+
+# Procedure in the namespace ::ns:
+tepam::procedure ::ns::display_message {} {}
+
+# Declaration of the subcommand message of the procedure display:
+tepam::procedure {display message} {} {}
+
+
attributes
+

All procedure attributes are provided in form of an option list that contains pairs of option names and option values. The example above has as procedure attribute a short and a normal description, but also the procedure arguments are defined in form of a procedure attribute.

+

Most procedure attributes are providing information for documentation purposes. But some of them affect also the way how the procedure can be called. The section Procedure Attributes discusses in detail the available procedure attributes.

+

The procedure arguments are defined in form of a special procedure attribute. Most of the information provided in the argument definition is not just used for documentation purposes. This information is in fact used by the TEPAM argument manager to handle and validate the various forms of arguments that are provided during the procedure calls. The section Argument Declaration discusses in detail all the argument definition attributes.

+
body
+

This is the normal procedure body. The declared arguments will be available to the procedure body in form of variables.

+

The procedure body will only be executed if the provided set of arguments could be validated by the TEPAM argument manager.

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -default Warning -choices {Warning Error}}
+      {text -type string}
+   }
+} {
+   puts "Message type: $mtype"
+   puts "Message: $text"
+}
+
+
+

The commands procedure as well as argument_dialogbox are exported from the namespace tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to import them into the main namespace:

+
namespace import tepam::*
+procedure {display_message} {
+   -args {
+      ...
+

Procedure Attributes

+

The first group of attributes affect the behavior of the declared procedure:

+
+
-named_arguments_first 0|1
+

This attribute defines the calling style of a procedure. TEPAM uses by default the named arguments first, unnamed arguments later style (Tcl). This default behavior can globally be changed by setting the variable tepam::named_arguments_first to 0. This global calling style can be changed individually for a procedure with the -named_arguments_first attribute.

+
-auto_argument_name_completion 0|1
+

The declared procedures will by default automatically try to match eventually abbreviated argument names to the defined arguments names. This default behavior can globally be changed by setting the variable tepam::auto_argument_name_completion to 0. This global setting of the automatic argument name completion can be changed individually for a procedure with the -auto_argument_name_completion procedure attribute.

+
-interactive_display_format extended|short
+

A procedure declared with the TEPAM procedure command can always be called with the -interactive option. By doing so, a graphical form will be generated that allows specifying all procedure argument values. There are two display modes for these interactive forms. While the extended mode is more adapted for small procedure argument sets, the short form is more adequate for huge procedure argument sets.

+

The choice to use short or extended forms can be globally configured via the variable tepam::interactive_display_format. This global setting can then be changed individually for a procedure with the -interactive_display_format procedure attribute.

+
-args list
+

The procedure arguments are declared via the -args attribute. An argument is defined via a list having as first element the argument name, followed by eventual argument attributes. All these argument definition lists are packaged themselves into a global list that is assigned to the -args attribute.

+

The argument definition syntax will be described more in detail in the following sub section.

+
+

The next attributes allow specifying custom argument checks as well as custom error messages in case these checks are failing:

+
+
-validatecommand script
+

Custom argument validations can be performed via specific validation commands that are defined with the -validatecommand attribute.

+

Validation command declaration example:

+
tepam::procedure {display_message} {
+   -args {
+      {text -type string -description "Message text"} }
+   -validatecommand {IllegalWordDetector $text}
+} {
+}
+

The validation command is executed in the context of the declared procedure body. The different argument values are accessed via the argument names. Note there is also an argument attribute -validatecommand that allows declaring custom checks for specific arguments.

+

The attribute -validatecommand can be repeated to declare multiple custom checks.

+
-validatecommand_error_text string
+

This attribute allows overriding the default error message for a custom argument validation (defined by -validatecommand). Also this attribute can be repeated in case multiple argument checks are declared.

+
+

The following attribute allows controlling the logging settings for an individual procedure:

+
+
-command_log 0|1|"interactive"
+

This argument configures the logging of the procedure calls into the list variable tepam::ProcedureCallLogList. The default configuration defined by the variable tepam::command_log will be used if this argument is not defined in a procedure declaration.

+

Setting this argument to 0 will disable any procedure call loggings, setting it to 1 will log any procedure calls and setting it to interactive will log just the procedures that are called interactively (procedures called with the -interactive flag).

+
+

The next group of procedure attributes is just used for the purpose of documentation and help text generation:

+
+
-category string
+

A category can be assigned to a procedure for documentation purposes. Any string is accepted as category.

+
-short_description string
+

The short description of a procedure is used in the documentation summary of a generated procedure list as well as +in the NAME section of a generated procedure manual page.

+
-description string
+

The (full) description assigned to a procedure is used to create user manual and help pages.

+
-return string
+

The -return attribute allows defining the expected return value of a procedure (used for documentation purposes).

+
-example string
+

A help text or manual page of a procedure can be enriched with eventual examples, using the -example attribute.

+
+
+

Argument Declaration

+

The following example shows the structure that is used for the argument definitions in the context of a procedure declaration:

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -default Warning -choices {Info Warning Error} -description "Message type"}
+      {-font -type font -default {Arial 10 italic} -description "Message text font"}
+      {-level -type integer -optional -range {1 10} -description "Message level"}
+      {-fg -type color -optional -description "Message color"}
+      {-log_file -type file -optional -description "Optional message log file"}
+      {text -type string -multiple -description "Multiple text lines to display"}
+   }
+} {
+}
+

Each of the procedure arguments is declared with a list that has as first element the argument name, followed by eventual attributes. The argument definition syntax can be formalized in the following way:

+
tepam::procedure <name> {
+   -args {
+      {<argument_name_1> <arg_attr_name_1a> <arg_attr_value_1a>  <arg_attr_name_1b> <arg_attr_value_1b> ...}
+      {<argument_name_2> <arg_attr_name_2a> <arg_attr_value_2a>  <arg_attr_name_2b> <arg_attr_value_2b> ...}
+      ...
+   }
+} <body>
+

The argument names and attributes have to be used in the following way:

+
+
Argument name (<argument_name_<n>>)
+

The provided argument name specifies whether the argument is an unnamed argument or a named argument. In addition to this, an argument name can also be blank to indicate an argument comment, or it can start with # to indicate a section comment.

+
+
"<Name>"
+

This is the simplest form of an argument name: An argument whose name is not starting with '-' is an unnamed argument. The parameter provided during a procedure call will be assigned to a variable with the name <Name>.

+
tepam::procedure {print_string} {
+   -args {
+      {text -type string -description "This is an unnamed argument"}
+   }
+} {
+   puts $text
+}
+print_string "Hello"
+ -> Hello
+
+
"-<Name>"
+

An argument whose name starts with '-' is a named argument (also called option). The parameter provided during a procedure call will be assigned to a variable with the name <Name> (not -<Name>).

+
tepam::procedure {print_string} {
+   -args {
+      {-text -type string -description "This is a named argument"}
+   }
+} {
+   puts $text
+}
+print_string -text "Hello"
+ -> Hello
+
+
"--"
+

This flag allows clearly specifying the end of the named arguments and the beginning of the unnamed arguments, in case the named arguments first, unnamed arguments later style (Tcl) has been selected.

+

If the unnamed arguments first, named arguments later style (Tk) style is selected, this flag is ignored if the unnamed arguments have already been parsed. Otherwise it will be assigned to the corresponding unnamed argument.

+
"-" or ""
+

A blank argument name (either '-' or '') starts a comment for the following arguments.

+
tepam::procedure {print_time} {
+   -interactive_display_format short
+   -args {
+      {hours -type integer -description "Hour"}
+      {minutes -type integer -description "Minute"}
+      {- The following arguments are optional:}
+      {seconds -type integer -default 0 -description "Seconds"}
+      {milliseconds -type integer -default 0 -description "Milliseconds"}
+   }
+} {
+   puts "${hour}h${minutes}:[expr $seconds+0.001*$milliseconds]"
+}
+

Argument comments are basically used in the graphical argument definition forms that are created if a procedure is called interactively.

+
"#*"
+

An argument definition list that starts with '#' is considered as a section comment. The argument definition list will be trimmed from the '#' characters and the remaining string will be used as section comment.

+

Section comments can be used to structure visually the argument definition code. Section comments are also used to structure the generated help texts and the interactive argument definition forms.

+
tepam::procedure {complex_multiply} {
+   -description "This function perform a complex multiplication"
+   -args {
+      {#### First complex number ####}
+      {-r0 -type double -description "First number real part"}
+      {-i0 -type double -description "First number imaginary part"}
+      {#### Second complex number ####}
+      {-r1 -type double -description "Second number real part"}
+      {-i1 -type double -description "Second number imaginary part"}
+   }
+} {
+   return [expr $r0*$r1 - $i0*$i1]
+}
+
+
+
Argument attributes (<arg_attr_name_<mn>> <arg_attr_value_<mn>>)
+

The following argument attributes are supported:

+
+
-description string
+

The description argument attribute is used for documentation purpose. Interactive argument definition forms use this attribute to provide explanations for an argument.

+
-type type
+

The type argument attribute allows assigning the argument either to a predefined data type, or to an application specific data type. The argument values that are provided during a procedure call are automatically checked with respect to the defined argument type.

+

The section ARGUMENT TYPES provides a list of predefined data types and explains how application specific types can be specified.

+

The argument type none has a special meaning. An argument that has the type none is handled as a flag. A flag is always optional and its related variable contains the logical value 1 if the flag has been defined during the procedure call, or otherwise 0.

+
-default value
+

Eventual default values can be defined with the -default argument attribute. Arguments with default values are automatically optional arguments.

+
-optional|-mandatory
+

Arguments are by default mandatory, unless a default value is defined. The flag -optional transforms an argument into an optional argument.

+

In case an optional argument is not defined during a procedure call, the corresponding variable will not be defined. +The flag -mandatory is the opposite to -optional. This flag exists only for completion reason, since an argument is anyway mandatory by default.

+
-multiple
+

Arguments that have the -multiple attribute can be defined multiple times during a procedure call. The values that are provided during a procedure call for such an argument are stored in a list variable. This is even the case if such an argument is only defined once during a procedure call.

+

The -multiple attribute can be attributed to unnamed arguments and to named arguments. The pair of argument name/argument value has to be repeated for each provided value in case of a named argument. +In case the argument with the -multiple attribute is an unnamed argument, this one has to be the absolute last one of all unnamed arguments.

+
-choices list
+

A possible set of valid argument values can be attributed to an argument via the -choices attribute. The argument value provided during a procedure call will be checked against the provided choice values.

+
-choicelabels list
+

An eventual short description can be attributed to each choice option with the -choicelabels attribute. These descriptions will be used in the generated help texts and as radio and check box labels for the interactive calls.

+

The -choicelabels attribute is optional, but if it is defined, its list needs to have the identical size as the -choices argument list.

+
-range {double double}
+

Another argument constraint can be defined with the -range attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value. The -range attribute has to be used only for numerical arguments, like integers and doubles.

+
-validatecommand script
+

Custom argument value validations can be performed via specific validation commands that are defined with the -validatecommand attribute. The provided validation command can be a complete script in which the pattern %P is replaced by the argument value that has to be validated.

+

Validation command declaration example:

+
tepam::procedure {display_message} {
+   -args {
+      {text -type string -description "Message text" \
+            -validatecommand {IllegalWordDetector %P}}
+} {
+}
+

While the purpose of this custom argument validation attribute is the validation of a specific argument, there is also a global attribute -validatecommand that allows performing validation that involves multiple arguments.

+
-validatecommand_error_text string
+

This attribute allows overriding the default error message for a custom argument validation (defined by -validatecommand).

+
-widget string
+

The widgets that allow defining the different arguments in case of an interactive procedure call are normally selected automatically in function of the argument type. The -widget attribute allows specifying explicitly a certain widget type for an argument.

+
-auxargs list
+

In case a procedure is called interactively, additional argument attributes can be provided to the interactive argument definition form via the -auxargs attribute that is itself a list of attribute name/attribute value pairs:

+
-auxargs {-<arg_attr_name_1a> <arg_attr_value_1a> \
+          -<arg_attr_name_1b> <arg_attr_value_1b>
+          ...
+}
+

For example, if a procedure takes as argument a file name it may be beneficial to specify the required file type for the interactive argument definition form. This information can be provided via the -auxargs attribute to the argument definition form:

+
tepam::procedure LoadPicture {
+   -args {
+      {FileName -type existingfile -description "Picture file" \
+                 -auxargs {-filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}} }}}
+   }
+} {
+}
+
+
-auxargs_commands script
+

If the auxiliary argument attributes are not static but have to be dynamically adaptable, the -auxargs_commands allows defining them via commands that are executed during a procedure call. A list of pairs of auxiliary attribute names and commands has to be provided to the -auxargs_commands attribute. The provided commands are executed in the context of the calling procedure.

+
-auxargs_commands {-<arg_attr_name_1a> <arg_attr_command_1a> \
+                   -<arg_attr_name_1b> <arg_attr_command_1b>
+                   ...
+}
+
+
+
+
+
+

VARIABLES

+

Several variables defined inside the ::tepam namespace impact the mode of operation of the procedures that have been declared with the TEPAM procedure command.

+
+
named_arguments_first
+

This variable defines the general calling style of the procedures. It is by default set to 1 which selects the named arguments first, unnamed arguments later style (Tcl style).

+

By setting this variable to 0, the named arguments first, unnamed arguments later style is globally selected (Tk style):

+
set tepam::named_arguments_first 0
+

While this variable defines the general calling style, the procedure attribute -named_arguments_first can adapt this style individually for each declared procedure.

+
auto_argument_name_completion
+

This variable controls the general automatic argument name matching mode. By default it is set to 1, meaning that the called procedures are trying to match eventually abbreviated argument names with the declared argument names.

+

By setting this variable to 0 the automatic argument name matching mode is disabled:

+
set tepam::auto_argument_name_completion 0
+

While this variable defines the general matching mode, the procedure attribute -auto_argument_name_completion can adapt this mode individually for each declared procedure.

+
interactive_display_format
+

A procedure declared via the TEPAM procedure command can always be called with the -interactive switch. By doing so, a graphical form will be generated that allows entering interactively all procedure arguments.

+

There are two display modes for these interactive forms. The extended mode which is the default mode is more adapted for small procedure argument sets. The short form is more adequate for huge procedure argument sets:

+
set tepam::interactive_display_format "short"
+

The choice to use short or extended forms can be globally configured via the variable interactive_display_format. +This global setting can be changed individually for a procedure with the procedure attribute -interactive_display_format.

+
help_line_length
+

The maximum line length used by the procedure help text generator can be specified with this variable. The default length which is set to 80 (characters) can easily be adapted to the need of an application:

+
set tepam::help_line_length 120
+

Since this variable is applied directly during the help text generation, its value can continuously be adapted to the current need.

+
command_log
+

Procedure calls can be logged inside the list variable tepam::ProcedureCallLogList. The variable tepam::command_log controls the default logging settings for any procedures. The following configurations are supported:

+
    +

  • 0: Disables any procedure call loggings

    • +

  • 1: Enables any procedure call loggings

    • +

  • "interactive": Will log any procedures called interactively (e.g. procedures called with the -interactive flag). This is the default configuration.

    • +
+

This default logging configuration can be changed individually for each procedure with the -command_log attribute.

+
+
+

ARGUMENT TYPES

+

TEPAM provides a comprehensive set of procedure argument types. They can easily be completed with application specific types if necessary.

+

Predefined Argument Types

+

To remember, a type can be assigned to each specified procedure argument:

+
tepam::procedure {warning} {
+   -args {
+      {-font -type font -default {Arial 10 italic}}
+      {-severity_level -type integer -optional -range {1 10}}
+      {-fg -type color -optional -description "Message color"}
+      {text -type string -multiple -description "Multiple text lines to display"}
+   }
+} {
+   ...
+}
+

There are some special purpose types that are building the first category of predefined argument types:

+
    +

  • none

    +

    A flag, also called switch, is defined as a named argument that has the type none. Flags are always optional and the default value of the assigned variable is set to 0. In contrast to the (normal) named arguments, no argument value has to be provided to a flag.

    +
    tepam::procedure flag_test {
+   -args {
+      {-flag -type none -description "This is a flag"}
+   }
+} {
+   puts $flag
+}
+flag_test
+-> 0
+flag_test -flag
+-> 1
    +

    Since no argument value has to be provided to a flag, also no data check is performed for this argument type.

    • +

  • string

    +

    String is a generic argument data type. Any data string can be provided to a string type argument and no data type checks are therefore performed. The string type allows defining single line strings during the interactive procedure calls.

    • +

  • text

    +

    Text is identical to string with the only difference that it allows entering multi line strings during interactive procedure calls.

    • +

  • {}

    +

    A blank argument type signifies an undefined argument type. This is the default argument type that will be used if no type has been explicitly specified. An argument that has a blank type behaves identically than an argument that has a string type, e.g. no argument data checks are performed. The only difference is that the data type string is mentioned in the generated help documentation, while this is not the case for the blank type.

    • +
+

Several numerical types are defined by TEPAM. The type validation procedures are using the string is <type> -strict commands to check the validity of the provided arguments, which assures that no empty strings are accepted as argument value. The type validation expression for the numerical types and the argument types to which this expression is applied are:

+
string is <type_to_check> -strict <argument_value>
+
    +

  • boolean

    • +

  • integer

    • +

  • double

    • +
+

Empty strings are accepted as argument value for all the alpha numeric argument types. The argument types that are falling into this category and validation expression used for them are:

+
string is <type_to_check> <argument_value>
+
    +

  • alnum

    • +

  • alpha

    • +

  • ascii

    • +

  • control

    • +

  • digit

    • +

  • graph

    • +

  • lower

    • +

  • print

    • +

  • punct

    • +

  • space

    • +

  • upper

    • +

  • wordchar

    • +

  • xdigit

    • +
+

In addition to the data types checked with the string is <type> commands, TEPAM specifies some other useful data types:

+
    +

  • char

    +

    Each string that has a length of 1 character meets the character type. The type check is made with the following expression:

    +
    expr [string length <argument_value>]==1
    +
    • +

  • color

    +

    Any character strings that are accepted by Tk as a color are considered as valid color argument. Please note that the Tk package has to be loaded to use the type color. TEPAM is using the following command to validate the color type:

    +
    expr ![catch {winfo rgb . <argument_value>}]
    +
    • +

  • font

    +

    Any character strings that are accepted by Tk as a font are considered as valid font argument. Please note that the Tk package has to be loaded to use the font type. TEPAM is using the following command to validate the color type:

    +
    expr ![catch {font measure <argument_value> ""}]
    +
    • +

  • file

    +

    Any strings that are not containing one of the following characters are considered as valid file names: * ? " < >. It is not necessary that the file and its containing directory exist. Zero-length strings are not considered as valid file names.

    +

    The following expression is used to validate the file names:

    +
    expr [string length <argument_value>]>0 && ![regexp {[\"*?<>:]} <argument_value>]
    +
    • +

  • existingfile

    +

    The argument is valid if it matches with an existing file. The following check is performed to validate the arguments of this type:

    +
    file exists <argument_value>
    +
    • +

  • directory

    +

    The directory argument is validated exactly in the same way as the file arguments.

    • +

  • existingdirectory

    +

    The argument is valid if it matches with an existing directory. The following check is performed to validate the arguments of this type:

    +
    file isdirectory <argument_value>
    +
    • +
+
+

Defining Application Specific Argument Types

+

To add support for a new application specific argument type it is just necessary to add into the namespace tepam a validation function Validation(<type>). This function requires one argument. It has to returns 1 if the provided argument matches with the relevant data type. The function has to return otherwise 0.

+

The validation command section of the "tepam.tcl" package provides sufficient examples of validation functions, since it implements the ones for the standard TEPAM types.

+

The following additional code snippet shows the validation function for a custom argument type that requires values that have a character string length of exactly 2:

+
proc tepam::Validate(two_char) {v} {expr {[string length $v]==2}}
+
+
+

PROCEDURE CALLS

+

Help

+

Each procedure can be called with the -help flag. The procedure will then print a generated help text to stdout and will then return without performing any additional actions.

+

Taking the first procedure declared in PROCEDURE CALLS, the help request and the printed help text would be:

+
display message -help
+->
+NAME
+      display message - Displays a simple message box
+SYNOPSIS
+      display message
+            [-mtype <mtype>]
+               Message type, default: "Warning", choices: {Info, Warning, Error}
+            <text>
+               Multiple text lines to display, type: string
+DESCRIPTION
+      This procedure allows displaying a configurable message box. The default
+      message type that is created is a warning, but also errors and info can
+      be generated.
+      The procedure accepts multiple text lines.
+EXAMPLE
+      display message -mtype Warning "Save first your job"
+

The argument manager is checking if the last provided argument is -help and generates the requested help message if this is the case. So, also the following example will print the help message:

+
display message -mtype Info "It is 7:00" -help
+

On the other hand, the following call will result in an error:

+
display message -help -mtype Info "It is 7:00"
+->
+display message: Argument '-help' not known
+
+

Interactive Procedure Call

+

If Tk has been loaded a procedure can be called with the -interactive flag to open a graphical form that allows specifying interactively all procedure arguments. The following example assures that the Tk library is loaded and shows the command line to call interactively the procedure declared in PROCEDURE CALLS:

+
package require Tk
+display message -interactive
+

Also the -interactive flag has to be placed at the last argument position as this is also required for the -help flag. Arguments defined before the -interactive flag will be ignored. The following example is therefore also a valid interactive procedure call:

+
display message -mtype Info "It is 7:00" -interactive
+
+

Unnamed Arguments

+

Unnamed arguments are typically provided to the called procedure as simple parameters. This procedure calling form requires that the provided arguments are strictly following the order of the specified arguments. Several parameters can be assigned to the last argument if this one has the -multiple attribute. So, the following declared procedure ...

+
tepam::procedure {display_message} {
+   -args {
+      {mtype -choices {Info Warning Error}}
+      {text -type string -multiple}
+   }
+} {
+   puts "$mtype: [join $text]"
+}
+

... can for example be called in the following ways:

+
display_message Info "It is PM 7:00."
+-> Info: It is PM 7:00.
+display_message Info "It is PM 7:00." "You should go home."
+-> Info: It is PM 7:00. You should go home.
+

The nice thing is that unnamed arguments can also be called as named arguments, which can be handy, for example if the exact specified argument order is not known to a user:

+
display_message -mtype Info -text "It is PM 7:00."
+-> Info: It is PM 7:00.
+display_message -text "It is PM 7:00." -mtype Info
+-> Info: It is PM 7:00.
+display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
+-> Info: It is PM 7:00. You should go home.
+display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
+-> Info: It is PM 7:00. You should go home.
+
+

Named Arguments

+

Named arguments have to be provided to a procedure in form of a parameter pairs composed by the argument names and the argument values. The order how they are provided during a procedure call is irrelevant and has not to match with the argument specification order.

+

The following declared procedure ...

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -choices {Info Warning Error}}
+      {-text -type string -multiple}
+   }
+} {
+   puts "$mtype: [join $text]"
+}
+

... can be called in the following ways:

+
display_message -mtype Info -text "It is PM 7:00."
+-> Info: It is PM 7:00.
+display_message -text "It is PM 7:00." -mtype Info
+-> Info: It is PM 7:00.
+display_message -mtype Info -text "It is PM 7:00." -text "You should go home."
+-> Info: It is PM 7:00. You should go home.
+display_message -text "It is PM 7:00." -text "You should go home." -mtype Info
+-> Info: It is PM 7:00. You should go home.
+

Also named arguments that have not the -multiple attribute can be provided multiple times. Only the last provided argument will be retained in such a case:

+
display_message -mtype Info -text "It is PM 7:00." -mtype Warning
+-> Warning: It is PM 7:00.
+
+

Unnamed Arguments First, Named Arguments Later (Tk Style)

+

A procedure that has been defined while the variable tepam::named_arguments_first was set to 1, or with the procedure attribute -named_arguments_first set to 1 has to be called in the Tcl style. The following procedure declaration will be used in this section to illustrate the meaning of this calling style:

+
set tepam::named_arguments_first 1
+tepam::procedure my_proc {
+   -args {
+      {-n1 -default ""}
+      {-n2 -default ""}
+      {u1 -default ""}
+      {u2 -default ""}
+   }
+} {
+   puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
+}
+

The unnamed arguments are placed at the end of procedure call, after the named arguments:

+
my_proc -n1 N1 -n2 N2 U1 U2
+-> n1:'N1', n2:'N2', u1:'U1', u2:'U2'
+

The argument parser considers the first argument that doesn't start with the '-' character as well as all following arguments as unnamed argument:

+
my_proc U1 U2
+-> n1:'', n2:'', u1:'U1', u2:'U2'
+

Named arguments can be defined multiple times. If the named argument has the -multiply attribute, all argument values will be collected in a list. Otherwise, only the last provided attribute value will be retained:

+
my_proc -n1 N1 -n2 N2 -n1 M1 U1 U2
+-> n1:'M1', n2:'N2', u1:'U1', u2:'U2'
+

The name of the first unnamed argument has therefore not to start with the '-' character. The unnamed argument is otherwise considered as name of another named argument. This is especially important if the first unnamed argument is given by a variable that can contain any character strings:

+
my_proc -n1 N1 -n2 N2 "->" "<-"
+-> my_proc: Argument '->' not known
+set U1 "->"
+my_proc -n1 N1 -n2 N2 $U1 U2}]
+my_proc: Argument '->' not known
+

The '--' flag allows separating unambiguously the unnamed arguments from the named arguments. All data after the '--' flag will be considered as unnamed argument:

+
my_proc -n1 N1 -n2 N2 -- "->" "<-"
+-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
+set U1 "->"
+my_proc -n1 N1 -n2 N2 -- $U1 U2
+-> n1:'N1', n2:'N2', u1:'->', u2:'<-'
+
+

Named Arguments First, Unnamed Arguments Later (Tcl Style)

+

The Tk calling style will be chosen if a procedure is defined while the variable tepam::named_arguments_first is set to 0, or if the procedure attribute -named_arguments_first has been set to 0. The following procedure will be used in this section to illustrate this calling style:

+
set tepam::named_arguments_first 0
+tepam::procedure my_proc {
+   -args {
+      {-n1 -default ""}
+      {-n2 -default ""}
+      {u1}
+      {u2 -default "" -multiple}
+   }
+} {
+   puts "n1:'$n1', n2:'$n2', u1:'$u1', u2:'$u2'"
+}
+

The unnamed arguments have to be provided first in this case. The named arguments are provided afterwards:

+
my_proc U1 U2 -n1 N1 -n2 N2
+-> n1:'N1', n1:'N1', u1:'U1', u2:'U2'
+

The argument parser will assign to each defined unnamed argument a value before it switches to read the named arguments. This default behavior changes a bit if there are unnamed arguments that are optional or that can take multiple values.

+

An argument value will only be assigned to an unnamed argument that is optional (that has either the -optional attribute or that has a default value), if the value is not beginning with the '-' character or if no named arguments are defined. The value that starts with '-' is otherwise considered as the name of a named argument.

+

Argument values are assigned to an argument that has the -multiple attribute as long as the parameter value doesn't starts with the '-' character.

+

Values that start with the '-' character can therefore not be assigned to optional unnamed arguments, which restricts the usage of the Tcl procedure calling style. The Tk style may be preferable in some cases, since it allows separating unambiguously the named arguments from the unnamed ones with the '--' flag.

+

Let's explore in a bit less theoretically the ways how the previously defined procedure can be called: The first example calls the procedure without any parameters, which leads to an error since u1 is a mandatory argument:

+
my_proc
+-> my_proc: Required argument is missing: u1
+

The procedure call is valid if one parameter is provided for u1:

+
my_proc U1
+-> n1:'', n2:'', u1:'U1', u2:''
+

If more parameters are provided that are not starting with the '-' character, they will be attributed to the unnamed arguments. U2 will receive 3 of these parameters, since it accepts multiple values:

+
my_proc U1 U2 U3 U4
+-> n1:'', n2:'', u1:'U1', u2:'U2 U3 U4'
+

As soon as one parameter starts with '-' and all unnamed arguments have been assigned, the argument manager tries to interpret the parameter as name of a named argument. The procedure call will fail if a value beginning with '-' is assigned to an unnamed argument:

+
my_proc U1 U2 U3 U4 -U5
+-> my_proc: Argument '-U5' not known
+

The attribution of a parameter to a named argument will fail if there are undefined unnamed (non optional) arguments. The name specification will in this case simply be considered as a parameter value that is attributed to the next unnamed argument. This was certainly not the intention in the following example:

+
my_proc -n1 N1
+-> n1:'', n2:'', u1:'-n1', u2:'N1'
+

The situation is completely different if values have already been assigned to all mandatory unnamed arguments. A parameter beginning with the '-' character will in this case be considered as a name identifier for a named argument:

+
my_proc U1 -n1 N1
+-> n1:'N1', n2:'', u1:'U1', u2:''
+

No unnamed arguments are allowed behind the named arguments:

+
my_proc U1 -n1 N1 U2
+-> my_proc: Argument 'U2' is not an option
+

The '--' flag has no special meaning if not all mandatory arguments have got assigned a value. This flag will simply be attributed to one of the unnamed arguments:

+
my_proc -- -n1 N1
+-> n1:'N1', n2:'', u1:'--', u2:''
+

But the '--' flag is simply ignored if the argument parser has started to handle the named arguments:

+
my_proc U1 -- -n1 N1
+-> n1:'N1', n2:'', u1:'U1', u2:''
+my_proc U1 -n1 N1 -- -n2 N2
+-> n1:'N1', n2:'N2', u1:'U1', u2:''
+
+

Raw Argument List

+

It may be necessary sometimes that the procedure body is able to access the entire list of arguments provided during a procedure call. This can happen via the args variable that contains always the unprocessed argument list:

+
tepam::procedure {display_message} {
+   -args {
+      {-mtype -choices {Warning Error} -default Warning}
+      {text -type string -multiple}
+   }
+} {
+   puts "args: $args"
+}
+display_message -mtype Warning "It is 7:00"
+-> args: -mtype Warning {It is 7:00}
+
+
+ + +

Category

+

Procedures, arguments, parameters, options

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cattr.html Index: embedded/www/tcllib/files/modules/term/ansi_cattr.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_cattr.html +++ embedded/www/tcllib/files/modules/term/ansi_cattr.html @@ -0,0 +1,282 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::code::attr(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code::attr - ANSI attribute sequences

+
+ + +

Description

+

This package provides symbolic names for the ANSI attribute control +codes. For each control code a single command is provided which +returns this code as its result. None of the commands of this package +write to a channel; that is handled by higher level packages, like +term::ansi::send.

+
+

API

+

Introspection

+
+
::term::ansi::code::attr::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::attr::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace attr. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Attributes

+
+
::term::ansi::code::attr::fgblack
+

Set text color to Black.

+
::term::ansi::code::attr::fgred
+

Set text color to Red.

+
::term::ansi::code::attr::fggreen
+

Set text color to Green.

+
::term::ansi::code::attr::fgyellow
+

Set text color to Yellow.

+
::term::ansi::code::attr::fgblue
+

Set text color to Blue.

+
::term::ansi::code::attr::fgmagenta
+

Set text color to Magenta.

+
::term::ansi::code::attr::fgcyan
+

Set text color to Cyan.

+
::term::ansi::code::attr::fgwhite
+

Set text color to White.

+
::term::ansi::code::attr::fgdefault
+

Set default text color (Black).

+
::term::ansi::code::attr::bgblack
+

Set background to Black.

+
::term::ansi::code::attr::bgred
+

Set background to Red.

+
::term::ansi::code::attr::bggreen
+

Set background to Green.

+
::term::ansi::code::attr::bgyellow
+

Set background to Yellow.

+
::term::ansi::code::attr::bgblue
+

Set background to Blue.

+
::term::ansi::code::attr::bgmagenta
+

Set background to Magenta.

+
::term::ansi::code::attr::bgcyan
+

Set background to Cyan.

+
::term::ansi::code::attr::bgwhite
+

Set background to White.

+
::term::ansi::code::attr::bgdefault
+

Set default background (Transparent).

+
::term::ansi::code::attr::bold
+

Bold on.

+
::term::ansi::code::attr::dim
+

Dim on.

+
::term::ansi::code::attr::italic
+

Italics on.

+
::term::ansi::code::attr::underline
+

Underscore on.

+
::term::ansi::code::attr::blink
+

Blink on.

+
::term::ansi::code::attr::revers
+

Reverse on.

+
::term::ansi::code::attr::hidden
+

Hidden on.

+
::term::ansi::code::attr::strike
+

Strike-through on.

+
::term::ansi::code::attr::nobold
+

Bold off.

+
::term::ansi::code::attr::noitalic
+

Italics off.

+
::term::ansi::code::attr::nounderline
+

Underscore off.

+
::term::ansi::code::attr::noblink
+

Blink off.

+
::term::ansi::code::attr::norevers
+

Reverse off.

+
::term::ansi::code::attr::nohidden
+

Hidden off.

+
::term::ansi::code::attr::nostrike
+

Strike-through off.

+
::term::ansi::code::attr::reset
+

Reset all attributes to their default values.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cctrl.html Index: embedded/www/tcllib/files/modules/term/ansi_cctrl.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_cctrl.html +++ embedded/www/tcllib/files/modules/term/ansi_cctrl.html @@ -0,0 +1,462 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::code::ctrl(n) 0.2 tcllib "Terminal control"

+

Name

+

term::ansi::code::ctrl - ANSI control sequences

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::ansi::code ?0.2?
    • +
  • package require term::ansi::code::ctrl ?0.2?
    • +
+ +
+
+

Description

+

This package provides symbolic names for the ANSI control +sequences. For each sequence a single command is provided which +returns the sequence as its result. None of the commands of this +package write to a channel; that is handled by higher level packages, +like term::ansi::send.

+
+

API

+

Introspection

+
+
::term::ansi::code::ctrl::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::ctrl::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace ctrl. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Sequences

+
+
::term::ansi::code::ctrl::eeol
+

Erase (to) End Of Line

+
::term::ansi::code::ctrl::esol
+

Erase (to) Start Of Line

+
::term::ansi::code::ctrl::el
+

Erase (current) Line

+
::term::ansi::code::ctrl::ed
+

Erase Down (to bottom)

+
::term::ansi::code::ctrl::eu
+

Erase Up (to top)

+
::term::ansi::code::ctrl::es
+

Erase Screen

+
::term::ansi::code::ctrl::sd
+

Scroll Down

+
::term::ansi::code::ctrl::su
+

Scroll Up

+
::term::ansi::code::ctrl::ch
+

Cursor Home

+
::term::ansi::code::ctrl::sc
+

Save Cursor

+
::term::ansi::code::ctrl::rc
+

Restore Cursor (Unsave)

+
::term::ansi::code::ctrl::sca
+

Save Cursor + Attributes

+
::term::ansi::code::ctrl::rca
+

Restore Cursor + Attributes

+
::term::ansi::code::ctrl::st
+

Set Tab (@ current position)

+
::term::ansi::code::ctrl::ct
+

Clear Tab (@ current position)

+
::term::ansi::code::ctrl::cat
+

Clear All Tabs

+
::term::ansi::code::ctrl::qdc
+

Query Device Code

+
::term::ansi::code::ctrl::qds
+

Query Device Status

+
::term::ansi::code::ctrl::qcp
+

Query Cursor Position

+
::term::ansi::code::ctrl::rd
+

Reset Device

+
::term::ansi::code::ctrl::elw
+

Enable Line Wrap

+
::term::ansi::code::ctrl::dlw
+

Disable Line Wrap

+
::term::ansi::code::ctrl::eg
+

Enter Graphics Mode

+
::term::ansi::code::ctrl::lg
+

Exit Graphics Mode

+
::term::ansi::code::ctrl::scs0 tag
+

Set default character set

+
::term::ansi::code::ctrl::scs1 tag
+

Set alternate character set +Select Character Set.

+

Choose which character set is used for either default (scs0) or +alternate font (scs1). This does not change whether default or +alternate font are used, only their definition.

+

The legal tags, and their meanings, are:

+
+
A
+

United Kingdom Set

+
B
+

ASCII Set

+
0
+

Special Graphics

+
1
+

Alternate Character ROM Standard Character Set

+
2
+

Alternate Character ROM Special Graphics

+
+
::term::ansi::code::ctrl::sda arg...
+

Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package term::ansi::code::attr. For +convenience this package also provides additional commands each setting a single +specific attribute.

+
::term::ansi::code::ctrl::sda_fgblack
+

Set text color to Black.

+
::term::ansi::code::ctrl::sda_fgred
+

Set text color to Red.

+
::term::ansi::code::ctrl::sda_fggreen
+

Set text color to Green.

+
::term::ansi::code::ctrl::sda_fgyellow
+

Set text color to Yellow.

+
::term::ansi::code::ctrl::sda_fgblue
+

Set text color to Blue.

+
::term::ansi::code::ctrl::sda_fgmagenta
+

Set text color to Magenta.

+
::term::ansi::code::ctrl::sda_fgcyan
+

Set text color to Cyan.

+
::term::ansi::code::ctrl::sda_fgwhite
+

Set text color to White.

+
::term::ansi::code::ctrl::sda_fgdefault
+

Set default text color (Black).

+
::term::ansi::code::ctrl::sda_bgblack
+

Set background to Black.

+
::term::ansi::code::ctrl::sda_bgred
+

Set background to Red.

+
::term::ansi::code::ctrl::sda_bggreen
+

Set background to Green.

+
::term::ansi::code::ctrl::sda_bgyellow
+

Set background to Yellow.

+
::term::ansi::code::ctrl::sda_bgblue
+

Set background to Blue.

+
::term::ansi::code::ctrl::sda_bgmagenta
+

Set background to Magenta.

+
::term::ansi::code::ctrl::sda_bgcyan
+

Set background to Cyan.

+
::term::ansi::code::ctrl::sda_bgwhite
+

Set background to White.

+
::term::ansi::code::ctrl::sda_bgdefault
+

Set default background (Transparent).

+
::term::ansi::code::ctrl::sda_bold
+

Bold on.

+
::term::ansi::code::ctrl::sda_dim
+

Dim on.

+
::term::ansi::code::ctrl::sda_italic
+

Italics on.

+
::term::ansi::code::ctrl::sda_underline
+

Underscore on.

+
::term::ansi::code::ctrl::sda_blink
+

Blink on.

+
::term::ansi::code::ctrl::sda_revers
+

Reverse on.

+
::term::ansi::code::ctrl::sda_hidden
+

Hidden on.

+
::term::ansi::code::ctrl::sda_strike
+

Strike-through on.

+
::term::ansi::code::ctrl::sda_nobold
+

Bold off.

+
::term::ansi::code::ctrl::sda_noitalic
+

Italics off.

+
::term::ansi::code::ctrl::sda_nounderline
+

Underscore off.

+
::term::ansi::code::ctrl::sda_noblink
+

Blink off.

+
::term::ansi::code::ctrl::sda_norevers
+

Reverse off.

+
::term::ansi::code::ctrl::sda_nohidden
+

Hidden off.

+
::term::ansi::code::ctrl::sda_nostrike
+

Strike-through off.

+
::term::ansi::code::ctrl::sda_reset
+

Reset all attributes to their default values.

+
::term::ansi::send::fcp row col
+

Force Cursor Position (aka Go To).

+
::term::ansi::code::ctrl::cu ?n?
+

Cursor Up. n defaults to 1.

+
::term::ansi::code::ctrl::cd ?n?
+

Cursor Down. n defaults to 1.

+
::term::ansi::code::ctrl::cf ?n?
+

Cursor Forward. n defaults to 1.

+
::term::ansi::code::ctrl::cb ?n?
+

Cursor Backward. n defaults to 1.

+
::term::ansi::code::ctrl::ss ?s e?
+

Scroll Screen (entire display, or between rows start end, inclusive).

+
::term::ansi::code::ctrl::skd code str
+

Set Key Definition.

+
::term::ansi::code::ctrl::title str
+

Set the terminal title.

+
::term::ansi::code::ctrl::gron
+

Switch to character/box graphics. I.e. switch to the alternate font.

+
::term::ansi::code::ctrl::groff
+

Switch to regular characters. I.e. switch to the default font.

+
::term::ansi::code::ctrl::tlc
+

Character graphics, Top Left Corner.

+
::term::ansi::code::ctrl::trc
+

Character graphics, Top Right Corner.

+
::term::ansi::code::ctrl::brc
+

Character graphics, Bottom Right Corner.

+
::term::ansi::code::ctrl::blc
+

Character graphics, Bottom Left Corner.

+
::term::ansi::code::ctrl::ltj
+

Character graphics, Left T Junction.

+
::term::ansi::code::ctrl::ttj
+

Character graphics, Top T Junction.

+
::term::ansi::code::ctrl::rtj
+

Character graphics, Right T Junction.

+
::term::ansi::code::ctrl::btj
+

Character graphics, Bottom T Junction.

+
::term::ansi::code::ctrl::fwj
+

Character graphics, Four-Way Junction.

+
::term::ansi::code::ctrl::hl
+

Character graphics, Horizontal Line.

+
::term::ansi::code::ctrl::vl
+

Character graphics, Vertical Line.

+
::term::ansi::code::ctrl::groptim str
+

Optimize character graphics. The generator commands above create way to many +superfluous commands shifting into and out of the graphics mode. This command +removes all shifts which are not needed. To this end it also knows which +characters will look the same in both modes, to handle strings created outside +of this package.

+
::term::ansi::code::ctrl::clear
+

Clear screen. In essence a sequence of CursorHome + EraseDown.

+
::term::ansi::code::ctrl::init
+

Initialize default and alternate fonts to ASCII and box graphics.

+
::term::ansi::code::ctrl::showat row col text
+

Format the block of text for display at the specified location.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_cmacros.html Index: embedded/www/tcllib/files/modules/term/ansi_cmacros.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_cmacros.html +++ embedded/www/tcllib/files/modules/term/ansi_cmacros.html @@ -0,0 +1,191 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::code::macros(n) 0.1 tcllib "Terminal control"

+

Name

+

term::ansi::code::macros - Macro sequences

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require textutil::repeat
    • +
  • package require textutil::tabify
    • +
  • package require term::ansi::code::macros ?0.1?
    • +
+ +
+
+

Description

+

This package provides higher level control sequences for more complex +shapes.

+
+

API

+

Introspection

+
+
::term::ansi::code::macros::names
+

This command is for introspection. It returns as its result a list +containing the names of all attribute commands.

+
::term::ansi::code::macros::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace macros. Note that +this is relative namespace name, placing the imported command into a +child of the current namespace. By default all commands are imported, +this can howver be restricted by listing the names of the wanted +commands after the namespace argument.

+
+
+

Sequences

+
+
::term::ansi::code::macros::menu menu
+

The description of a menu is converted into a formatted rectangular +block of text, with the menu command characters highlighted using bold +red text. The result is returned as the result of the command.

+

The description, menu, is a dictionary mapping from menu label +to command character.

+
::term::ansi::code::macros::frame string
+

The paragraph of text contained in the string is padded with spaces at +the right margin, after normalizing internal tabs, and then put into a +frame made of box-graphics. The result is returned as the result of +the command.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_code.html Index: embedded/www/tcllib/files/modules/term/ansi_code.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_code.html +++ embedded/www/tcllib/files/modules/term/ansi_code.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::code(n) 0.2 tcllib "Terminal control"

+

Name

+

term::ansi::code - Helper for control sequences

+
+ + +

Description

+

This package provides commands enabling the definition of control +sequences in an easy manner.

+
+
::term::ansi::code::esc str
+

This command returns the argument string, prefixed with the ANSI +escape character, "\033."

+
::term::ansi::code::escb str
+

This command returns the argument string, prefixed with a common ANSI +escape sequence, "\033[".

+
::term::ansi::code::define name escape code
+

This command defines a procedure name which returns the control +sequence code, beginning with the specified escape sequence, +either esc, or escb.

+
::term::ansi::code::const name code
+

This command defines a procedure name which returns the control +sequence code.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_ctrlu.html Index: embedded/www/tcllib/files/modules/term/ansi_ctrlu.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_ctrlu.html +++ embedded/www/tcllib/files/modules/term/ansi_ctrlu.html @@ -0,0 +1,199 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::ctrl::unix(n) 0.1.1 tcllib "Terminal control"

+

Name

+

term::ansi::ctrl::unix - Control operations and queries

+
+ + +

Description

+

WARNING: This package is unix-specific and depends on the +availability of two unix system commands for terminal control, +i.e. stty and tput, both of which have to be found +in the $PATH. If any of these two commands is missing the +loading of the package will fail.

+

The package provides commands to switch the standard input of the +current process between raw and cooked input modes, and +to query the size of terminals, i.e. the available number of columns +and lines.

+
+

API

+

Introspection

+
+
::term::ansi::ctrl::unix::import ?ns? ?arg...?
+

This command imports some or all attribute commands into the namespace +ns. This is by default the namespace ctrl. Note that this +is relative namespace name, placing the imported command into a child +of the current namespace. By default all commands are imported, this +can howver be restricted by listing the names of the wanted commands +after the namespace argument.

+
+
+

Operations

+
+
::term::ansi::ctrl::unix::raw
+

This command switches the standard input of the current process to +raw input mode. This means that from then on all characters +typed by the user are immediately reported to the application instead +of waiting in the OS buffer until the Enter/Return key is received.

+
::term::ansi::ctrl::unix::cooked
+

This command switches the standard input of the current process to +cooked input mode. This means that from then on all characters +typed by the user are kept in OS buffers for editing until the +Enter/Return key is received.

+
::term::ansi::ctrl::unix::columns
+

This command queries the terminal connected to the standard input for +the number of columns available for display.

+
::term::ansi::ctrl::unix::rows
+

This command queries the terminal connected to the standard input for +the number of rows (aka lines) available for display.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ansi_send.html Index: embedded/www/tcllib/files/modules/term/ansi_send.html ================================================================== --- embedded/www/tcllib/files/modules/term/ansi_send.html +++ embedded/www/tcllib/files/modules/term/ansi_send.html @@ -0,0 +1,446 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::ansi::send(n) 0.2 tcllib "Terminal control"

+

Name

+

term::ansi::send - Output of ANSI control sequences to terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::ansi::send ?0.2?
    • +
+ +
+
+

Description

+

This package provides commands to send ANSI terminal control sequences to a +terminal. All commands come in two variants, one for sending to any channel, +the other for sending to stdout.

+

The commands are defined using the control sequences provided by the package +term::ansi::code::ctrl. They have the same arguments as the commands +they are based on, with the exception of the variant for sending to any channel. +Their first argument is always a channel handle, then followed by the original +arguments. Below we will list only the variant sending to stdout.

+
+
::term::ansi::send::import ?ns? ...
+

Imports the commands of this package into the namespace ns. If not specified +it defaults to send. Note that this default is a relative namespace name, +i.e. the actual namespace will be created under the current namespace.

+

By default all commands will be imported, this can however be restricted to specific +commands, by listing them after the namespace to import them into.

+
::term::ansi::send::eeol
+

Erase (to) End Of Line.

+
::term::ansi::send::esol
+

Erase (to) Start Of Line.

+
::term::ansi::send::el
+

Erase (current) Line.

+
::term::ansi::send::ed
+

Erase Down (to bottom).

+
::term::ansi::send::eu
+

Erase Up (to top).

+
::term::ansi::send::es
+

Erase Screen.

+
::term::ansi::send::sd
+

Scroll Down.

+
::term::ansi::send::su
+

Scroll Up.

+
::term::ansi::send::ch
+

Cursor Home.

+
::term::ansi::send::sc
+

Save Cursor. Note: Only one saved position can be handled. +This is no unlimited stack. Saving before restoring will +overwrite the saved data.

+
::term::ansi::send::rc
+

Restore Cursor (Unsave).

+
::term::ansi::send::sca
+

Save Cursor + Attributes.

+
::term::ansi::send::rca
+

Restore Cursor + Attributes.

+
::term::ansi::send::st
+

Set Tab (@ current position).

+
::term::ansi::send::ct
+

Clear Tab (@ current position).

+
::term::ansi::send::cat
+

Clear All Tabs.

+
::term::ansi::send::qdc
+

Query Device Code.

+
::term::ansi::send::qds
+

Query Device Status.

+
::term::ansi::send::qcp
+

Query Cursor Position.

+
::term::ansi::send::rd
+

Reset Device.

+
::term::ansi::send::elw
+

Enable Line Wrap.

+
::term::ansi::send::dlw
+

Disable Line Wrap.

+
::term::ansi::send::eg
+

Enter Graphics Mode.

+
::term::ansi::send::lg
+

Exit Graphics Mode.

+
::term::ansi::send::scs0 tag
+
+
::term::ansi::send::scs1 tag
+

Select Character Set.

+

Choose which character set is used for default (scs0) and alternate font (scs1). +This does not change whether default or alternate font are used, just their +definitions.

+

The legal tags, and their meanings, are:

+
+
A
+

United Kingdom Set

+
B
+

ASCII Set

+
0
+

Special Graphics

+
1
+

Alternate Character ROM Standard Character Set

+
2
+

Alternate Character ROM Special Graphics

+
+
::term::ansi::send::sda arg...
+

Set Display Attributes. The arguments are the code sequences for the possible +attributes, as provided by the package term::ansi::code::attr. For +convenience this package also provides additional commands each setting a single +specific attribute.

+
::term::ansi::send::sda_fgblack
+

Set text color to Black.

+
::term::ansi::send::sda_fgred
+

Set text color to Red.

+
::term::ansi::send::sda_fggreen
+

Set text color to Green.

+
::term::ansi::send::sda_fgyellow
+

Set text color to Yellow.

+
::term::ansi::send::sda_fgblue
+

Set text color to Blue.

+
::term::ansi::send::sda_fgmagenta
+

Set text color to Magenta.

+
::term::ansi::send::sda_fgcyan
+

Set text color to Cyan.

+
::term::ansi::send::sda_fgwhite
+

Set text color to White.

+
::term::ansi::send::sda_fgdefault
+

Set default text color (Black).

+
::term::ansi::send::sda_bgblack
+

Set background to Black.

+
::term::ansi::send::sda_bgred
+

Set background to Red.

+
::term::ansi::send::sda_bggreen
+

Set background to Green.

+
::term::ansi::send::sda_bgyellow
+

Set background to Yellow.

+
::term::ansi::send::sda_bgblue
+

Set background to Blue.

+
::term::ansi::send::sda_bgmagenta
+

Set background to Magenta.

+
::term::ansi::send::sda_bgcyan
+

Set background to Cyan.

+
::term::ansi::send::sda_bgwhite
+

Set background to White.

+
::term::ansi::send::sda_bgdefault
+

Set default background (Transparent).

+
::term::ansi::send::sda_bold
+

Bold on.

+
::term::ansi::send::sda_dim
+

Dim on.

+
::term::ansi::send::sda_italic
+

Italics on.

+
::term::ansi::send::sda_underline
+

Underscore on.

+
::term::ansi::send::sda_blink
+

Blink on.

+
::term::ansi::send::sda_revers
+

Reverse on.

+
::term::ansi::send::sda_hidden
+

Hidden on.

+
::term::ansi::send::sda_strike
+

Strike-through on.

+
::term::ansi::send::sda_nobold
+

Bold off.

+
::term::ansi::send::sda_noitalic
+

Italics off.

+
::term::ansi::send::sda_nounderline
+

Underscore off.

+
::term::ansi::send::sda_noblink
+

Blink off.

+
::term::ansi::send::sda_norevers
+

Reverse off.

+
::term::ansi::send::sda_nohidden
+

Hidden off.

+
::term::ansi::send::sda_nostrike
+

Strike-through off.

+
::term::ansi::send::sda_reset
+

Reset all attributes to their default values.

+
::term::ansi::send::fcp row col
+

Force Cursor Position (aka Go To).

+
::term::ansi::send::cu ?n?
+

Cursor Up. n defaults to 1.

+
::term::ansi::send::cd ?n?
+

Cursor Down. n defaults to 1.

+
::term::ansi::send::cf ?n?
+

Cursor Forward. n defaults to 1.

+
::term::ansi::send::cb ?n?
+

Cursor Backward. n defaults to 1.

+
::term::ansi::send::ss ?s e?
+

Scroll Screen (entire display, or between rows start end, inclusive).

+
::term::ansi::send::skd code str
+

Set Key Definition.

+
::term::ansi::send::title str
+

Set the terminal title.

+
::term::ansi::send::gron
+

Switch to character/box graphics. I.e. switch to the alternate font.

+
::term::ansi::send::groff
+

Switch to regular characters. I.e. switch to the default font.

+
::term::ansi::send::tlc
+

Character graphics, Top Left Corner.

+
::term::ansi::send::trc
+

Character graphics, Top Right Corner.

+
::term::ansi::send::brc
+

Character graphics, Bottom Right Corner.

+
::term::ansi::send::blc
+

Character graphics, Bottom Left Corner.

+
::term::ansi::send::ltj
+

Character graphics, Left T Junction.

+
::term::ansi::send::ttj
+

Character graphics, Top T Junction.

+
::term::ansi::send::rtj
+

Character graphics, Right T Junction.

+
::term::ansi::send::btj
+

Character graphics, Bottom T Junction.

+
::term::ansi::send::fwj
+

Character graphics, Four-Way Junction.

+
::term::ansi::send::hl
+

Character graphics, Horizontal Line.

+
::term::ansi::send::vl
+

Character graphics, Vertical Line.

+
::term::ansi::send::groptim str
+

Optimize character graphics. The generator commands above create way to many +superfluous commands shifting into and out of the graphics mode. This command +removes all shifts which are not needed. To this end it also knows which +characters will look the same in both modes, to handle strings created outside +of this package.

+
::term::ansi::send::clear
+

Clear screen. In essence a sequence of CursorHome + EraseDown.

+
::term::ansi::send::init
+

Initialize default and alternate fonts to ASCII and box graphics.

+
::term::ansi::send::showat row col text
+

Show the block of text at the specified location.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/imenu.html Index: embedded/www/tcllib/files/modules/term/imenu.html ================================================================== --- embedded/www/tcllib/files/modules/term/imenu.html +++ embedded/www/tcllib/files/modules/term/imenu.html @@ -0,0 +1,252 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::interact::menu(n) 0.1 tcllib "Terminal control"

+

Name

+

term::interact::menu - Terminal widget, menu

+
+ + +

Description

+

This package provides a class for the creation of a simple menu +control.

+
+

Class API

+

The package exports a single command, the class command, enabling the +creation of menu instances. Its API is:

+
+
term::interact::menu object dict ?options...?
+

This command creates a new menu object with the name object, +initializes it, and returns the fully qualified name of the object +command as its result.

+

The argument is the menu to show, possibly followed by configuration +options and their values. The options are explained in the section +Configuration. The menu is a dictionary maping labels +to symbolic action codes.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object interact
+

Shows the menu in the screen at the configured location and starts +interacting with it. This opens its own event loop for the processing +of incoming characters. The method returns when the interaction has +completed. See section Interaction for a description of the +possible interaction.

+

The method returns the symbolic action of the menu item selected by +the user at the end of the interaction.

+
object done
+

This method can be used by user supplied actions to terminate the +interaction with the object.

+
object clear
+

This method can be used by user supplied actions to remove the menu +from the terminal.

+
object configure
+
+
object configure option
+
+
object configure option value...
+
+
object cget option
+

Standard methods to retrieve and configure the options of the menu.

+
+
+

Configuration

+

A menu instance recognizes the following options:

+
+
-in chan
+

Specifies the channel to read character sequences from. Defaults to +stdin.

+
-out chan
+

Specifies the channel to write the menu contents to. Defaults to +stdout.

+
-column int
+

Specifies the column of the terminal where the left margin of the +menu display should appear. Defaults to 0, i.e. the left-most +column.

+
-line int
+

Specifies the line of the terminal where the top margin of the menu +display should appear. Defaults to 0, i.e. the top-most line.

+
-height int
+

Specifies the number of lines of text to show at most in the +display. Defaults to 25.

+
-actions dict
+

Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section Interaction.

+
-hilitleft int
+
+
-hilitright int
+

By default the entire selected menu entry is highlighted in revers +output. However, when present these two options restrict revers dispay +to the specified sub-range of the entry.

+
-framed bool
+

By default the menu is shown using only header and footer out of +characters box graphics. If this flag is set the menu is fully +enclosed in a box.

+
+
+

Interaction

+

A menu object recognizes the control sequences listed below and acts +as described. The user can supply more control sequences to act on via +the configuration, but is not able to overide these defaults.

+
+
Cursor Up
+

The selection is moved up one entry, except if the first entry of the +menu is already selected.

+
Cursor Down
+

The selection is moved down one entry, except if the last entry of the +menu is already selected.

+
Enter/Return
+

The interaction with the object is terminated.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/ipager.html Index: embedded/www/tcllib/files/modules/term/ipager.html ================================================================== --- embedded/www/tcllib/files/modules/term/ipager.html +++ embedded/www/tcllib/files/modules/term/ipager.html @@ -0,0 +1,252 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::interact::pager(n) 0.1 tcllib "Terminal control"

+

Name

+

term::interact::pager - Terminal widget, paging

+
+ + +

Description

+

This package provides a class for the creation of a simple paging +text display.

+
+

Class API

+

The package exports a single command, the class command, enabling the +creation of pager instances. Its API is:

+
+
term::interact::pager object text ?options...?
+

This command creates a new pager object with the name object, +initializes it, and returns the fully qualified name of the object +command as its result.

+

The argument is the text to show, possibly followed by configuration +options and their values. The options are explained in the section +Configuration.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object interact
+

Show the pager in the screen at the configured location and start +interacting with it. This opens its own event loop for the processing +of incoming characters. The method returns when the interaction has +completed. See section Interaction for a description of the +possible interaction.

+
object done
+

This method can be used by user supplied actions to terminate the +interaction with the object.

+
object clear
+

This method can be used by user supplied actions to remove the pager +from the terminal.

+
object text text
+

This method can be used to change the text shown by the pager. +The pager will reset the dispay to show the first line of the +text at the top.

+
object configure
+
+
object configure option
+
+
object configure option value...
+
+
object cget option
+

Standard methods to retrieve and configure the options of the pager.

+
+
+

Configuration

+

A pager instance recognizes the following options:

+
+
-in chan
+

Specifies the channel to read character sequences from. Defaults to +stdin.

+
-out chan
+

Specifies the channel to write the pager contents to. Defaults to +stdout.

+
-column int
+

Specifies the column of the terminal where the left margin of the +pager display should appear. Defaults to 0, i.e. the left-most +column.

+
-line int
+

Specifies the line of the terminal where the top margin of the pager +display should appear. Defaults to 0, i.e. the top-most line.

+
-height int
+

Specifies the number of lines of text to show at most in the +display. Defaults to 25.

+
-actions dict
+

Specifies a dictionary containing additional actions, using character +sequences as keys. Note that these sequences cannot override the +hardwired sequences described in section Interaction.

+
+
+

Interaction

+

A pager object recognizes the control sequences listed below and acts +as described. The user can supply more control sequences to act on via +the configuration, but is not able to overide these defaults.

+
+
Cursor Up
+

The text is scrolled down a single line, making one more line visible +at the top. The pager will not react if the first line of the text is +already shown.

+
Cursor Down
+

The text is scrolled up a single line, making one more line visible at +the bottom. The pager will not react if the last line of the text is +already shown.

+
Page Up
+

The text is scrolled down a page. The pager will not react if the +first line of the text is already shown.

+
Page Down
+

The text is scrolled up a page. The pager will not react if the last +line of the text is already shown.

+
Enter/Return
+

The interaction with the object is terminated.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/receive.html Index: embedded/www/tcllib/files/modules/term/receive.html ================================================================== --- embedded/www/tcllib/files/modules/term/receive.html +++ embedded/www/tcllib/files/modules/term/receive.html @@ -0,0 +1,181 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::receive(n) 0.1 tcllib "Terminal control"

+

Name

+

term::receive - General input from terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::receive ?0.1?
    • +
+ +
+
+

Description

+

This package provides the most primitive commands for receiving +characters to a terminal. They are in essence convenient wrappers +around the builtin commands read and fileevent.

+
+
::term::receive::getch ?chan?
+

This command reads a single character from the channel with handle +chan and returns it as the result of the command.

+

If not specified chan defaults to stdin.

+

It is the responsibility of the caller to make sure that the channel +can provide single characters. On unix this can be done, for example, +by using the command of package term::ansi::ctrl::unix.

+
::term::receive::listen cmd ?chan?
+

This command sets up a filevent listener for the channel with handle +chan and invokes the command prefix cmd whenever +characters have been received, or EOF was reached.

+

If not specified chan defaults to stdin.

+

The signature of the command prefix is

+
+
cmd process string
+

This method is invoked when characters were received, and string +holds them for processing.

+
cmd eof
+

This method is invoked when EOF was reached on the channel we listen +on. It will be the last call to be received by the callback.

+
+
::term::receive::unlisten ?chan?
+

This command disables the filevent listener for the channel with handle +chan.

+

If not specified chan defaults to stdin.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term.html Index: embedded/www/tcllib/files/modules/term/term.html ================================================================== --- embedded/www/tcllib/files/modules/term/term.html +++ embedded/www/tcllib/files/modules/term/term.html @@ -0,0 +1,148 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term(n) 0.1 tcllib "Terminal control"

+

Name

+

term - General terminal control

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term ?0.1?
    • +
+
+
+

Description

+

It is planned to have this package provide highlevel general terminal control +commands, in the vein of ncurses or similar packages. Currently nothing has +been implemented however. I.e. this package is empty. It can be loaded, yet +provides nothing.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term_bind.html Index: embedded/www/tcllib/files/modules/term/term_bind.html ================================================================== --- embedded/www/tcllib/files/modules/term/term_bind.html +++ embedded/www/tcllib/files/modules/term/term_bind.html @@ -0,0 +1,225 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::receive::bind(n) 0.1 tcllib "Terminal control"

+

Name

+

term::receive::bind - Keyboard dispatch from terminals

+
+ + +

Description

+

This package provides a class for the creation of simple dispatchers +from character sequences to actions. Internally each dispatcher is in +essence a deterministic finite automaton with tree structure.

+
+

Class API

+

The package exports a single command, the +class command, enabling the creation of +dispatcher instances. Its API +is:

+
+
term::receive::bind object ?map?
+

This command creates a new dispatcher object with the name +object, initializes it, and returns the fully qualified name of +the object command as its result.

+

The argument is a dictionary mapping from strings, i.e. character +sequences to the command prefices to invoke when the sequence is found +in the input stream.

+
+
+

Object API

+

The objects created by the class command provide the methods listed +below:

+
+
object map str cmd
+

This method adds an additional mapping from the string str to +the action cmd. The mapping will take effect immediately +should the processor be in a prefix of str, or at the next +reset operation. The action is a command prefix and will be invoked +with one argument appended to it, the character sequence causing +the invokation. It is executed in the global namespace.

+
object default cmd
+

This method defines a default action cmd which will be invoked +whenever an unknown character sequence is encountered. The command +prefix is handled in the same as the regular action defined via +method map.

+
object listen ?chan?
+

This methods sets up a filevent listener for the channel with handle +chan and invokes the dispatcher object whenever characters have +been received, or EOF was reached.

+

If not specified chan defaults to stdin.

+
object unlisten ?chan?
+

This methods removes the filevent listener for the channel with handle +chan.

+

If not specified chan defaults to stdin.

+
object reset
+

This method resets the character processor +to the beginning of the tree.

+
object next char
+

This method causes the character processor to process the character +c. This may simply advance the internal state, or invoke an +associated action for a recognized sequence.

+
object process str
+

This method causes the character processor to process the character +sequence str, advancing the internal state and invoking action +as necessary. This is a callback for listen.

+
object eof
+

This method causes the character processor to handle EOF on the +input. This is currently no-op. +This is a callback for listen.

+
+
+

Notes

+

The simplicity of the DFA means that it is not possible to recognize a +character sequence with has a another recognized character sequence as +its prefix.

+

In other words, the set of recognized strings has to form a +prefix code.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/term/term_send.html Index: embedded/www/tcllib/files/modules/term/term_send.html ================================================================== --- embedded/www/tcllib/files/modules/term/term_send.html +++ embedded/www/tcllib/files/modules/term/term_send.html @@ -0,0 +1,162 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

term::send(n) 0.1 tcllib "Terminal control"

+

Name

+

term::send - General output to terminals

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require term::send ?0.1?
    • +
+ +
+
+

Description

+

This package provides the most primitive commands for sending characters +to a terminal. They are in essence convenient wrappers around the +builtin command puts.

+
+
::term::send::wrch chan str
+

Send the text str to the channel specified by the handle chan. +In contrast to the builtin command puts this command does not +terminate the string with a line terminator. It also forces an flush of +Tcl internal and OS buffers to ensure that the characters are processed +immediately.

+
::term::send::wr str
+

This convenience command is like ::term::send::wrch, except that the +destination channel is fixed to stdout.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category term of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Terminal control

+
+ +
ADDED embedded/www/tcllib/files/modules/textutil/adjust.html Index: embedded/www/tcllib/files/modules/textutil/adjust.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/adjust.html +++ embedded/www/tcllib/files/modules/textutil/adjust.html @@ -0,0 +1,269 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::adjust(n) 0.7.3 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::adjust - Procedures to adjust, indent, and undent paragraphs

+
+ + +

Description

+

The package textutil::adjust provides commands that manipulate +strings or texts (a.k.a. long strings or string with embedded newlines +or paragraphs), adjusting, or indenting them.

+

The complete set of procedures is described below.

+
+
::textutil::adjust::adjust string ?option value...?
+

Do a justification on the string according to the options. The +string is taken as one big paragraph, ignoring any newlines. Then the +line is formatted according to the options used, and the command +returns a new string with enough lines to contain all the printable +chars in the input string. A line is a set of characters between the +beginning of the string and a newline, or between 2 newlines, or +between a newline and the end of the string. If the input string is +small enough, the returned string won't contain any newlines.

+

Together with ::textutil::adjust::indent it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+

By default, any occurrence of space or tabulation characters are +replaced by a single space so that each word in a line is separated +from the next one by exactly one space character, and this forms a +real line. +Each real line is placed in a logical line, which has +exactly a given length (see the option -length below). +The real line may be shorter. Again by default, trailing spaces +are ignored before returning the string (see the option -full +below).

+

The following options may be used after the string parameter, +and change the way the command places a real line in a +logical line.

+
+
-full boolean
+

If set to false (default), trailing space characters are +deleted before returning the string. If set to true, any +trailing space characters are left in the string.

+
-hyphenate boolean
+

If set to false (default), no hyphenation will be done. If set +to true, the command will try to hyphenate the last word of a +line. Note: Hyphenation patterns must be loaded prior, using +the command ::textutil::adjust::readPatterns.

+
-justify center|left|plain|right
+

Sets the justification of the returned string to either left +(default), center, plain or right. The +justification means that any line in the returned string but the last +one is build according to the value. +If the justification is set to plain and the number of +printable chars in the last line is less than 90% of the length of a +line (see the option -length), then this line is justified +with the left value, avoiding the expansion of this line when +it is too small. The meaning of each value is:

+
+
center
+

The real line is centered in the logical line. If needed, a set of +space characters are added at the beginning (half of the needed set) +and at the end (half of the needed set) of the line if required (see +the option -full).

+
left
+

The real line is set on the left of the logical line. It means that +there are no space chars at the beginning of this line. If required, +all needed space chars are added at the end of the line (see the +option -full).

+
plain
+

The real line is exactly set in the logical line. It means that there +are no leading or trailing space chars. All the needed space chars are +added in the real line, between 2 (or more) words.

+
right
+

The real line is set on the right of the logical line. It means that +there are no space chars at the end of this line, and there may be +some space chars at the beginning, despite of the -full option.

+
+
-length integer
+

Set the length of the logical line in the string to +integer. integer must be a positive integer +value. Defaults to 72.

+
-strictlength
+

boolean] +If set to false (default), a line can exceed the specified +-length if a single word is longer than -length. If +set to true, words that are longer than -length are +split so that no line exceeds the specified -length.

+
+
::textutil::adjust::readPatterns filename
+

Loads the internal storage for hyphenation patterns with the contents +of the file filename. This has to be done prior to calling +command ::textutil::adjust::adjust with "-hyphenate +true", or the hyphenation process will not work correctly.

+

The package comes with a number of predefined pattern files, and the +command ::textutil::adjust::listPredefined can be used to find +out their names.

+
::textutil::adjust::listPredefined
+

This command returns a list containing the names of the hyphenation +files coming with this package.

+
::textutil::adjust::getPredefined filename
+

Use this command to query the package for the full path name of the +hyphenation file filename coming with the package. Only the +filenames found in the list returned by +::textutil::adjust::listPredefined are legal arguments for this +command.

+
::textutil::adjust::indent string prefix ?skip?
+

Each line in the string is indented by adding the string +prefix at its beginning. The modified string is returned +as the result of the command.

+

If skip is specified the first skip lines are left +untouched. The default for skip is 0, causing the +modification of all lines. Negative values for skip are treated +like 0. In other words, skip > 0 creates a +hanging indentation.

+

Together with ::textutil::adjust::adjust it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+
::textutil::adjust::undent string
+

The command computes the common prefix for all lines in string +consisting solely out of whitespace, removes this from each line and +returns the modified string.

+

Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove.

+

Together with ::textutil::adjust::adjust it is possible to +create properly wrapped paragraphs with arbitrary indentations.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/expander.html Index: embedded/www/tcllib/files/modules/textutil/expander.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/expander.html +++ embedded/www/tcllib/files/modules/textutil/expander.html @@ -0,0 +1,508 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::expander(n) 1.3.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::expander - Procedures to process templates and expand text.

+
+ + +

Description

+

The Tcl subst command is often used to support a kind of +template processing. Given a string with embedded variables or +function calls, subst will interpolate the variable and function +values, returning the new string:

+
+    % set greeting "Howdy"
+    Howdy
+    % proc place {} {return "World"}
+    % subst {$greeting, [place]!}
+    Howdy, World!
+    %
+
+

By defining a suitable set of Tcl commands, subst can be used to +implement a markup language similar to HTML.

+

The subst command is efficient, but it has three drawbacks for +this kind of template processing:

+
    +

  • There's no way to identify and process the plain text between two +embedded Tcl commands; that makes it difficult to handle plain text in +a context-sensitive way.

    • +

  • Embedded commands are necessarily bracketed by [ and +]; it's convenient to be able to choose different brackets +in special cases. Someone producing web pages that include a large +quantity of Tcl code examples might easily prefer to use << +and >> as the embedded code delimiters instead.

    • +

  • There's no easy way to handle incremental input, as one might wish to +do when reading data from a socket.

    • +
+

At present, expander solves the first two problems; eventually it will +solve the third problem as well.

+

The following section describes the command API to the expander; this +is followed by the tutorial sections, see TUTORIAL.

+
+

EXPANDER API

+

The textutil::expander package provides only one command, +described below. The rest of the section is taken by a description of +the methods for the expander objects created by this command.

+
+
::textutil::expander expanderName
+

The command creates a new expander object with an associated Tcl +command whose name is expanderName. This command may be used to +invoke various operations on the graph. If the expanderName is +not fully qualified it is interpreted as relative to the current +namespace. The command has the following general form:

+
+expanderName option ?arg arg ...?
+
+

Option and the args determine the exact behavior of the +command.

+
+

The following commands are possible for expander objects:

+
+
expanderName cappend text
+

Appends a string to the output in the current context. This command +should rarely be used by macros or application code.

+
expanderName cget varname
+

Retrieves the value of variable varname, defined in the current +context.

+
expanderName cis cname
+

Determines whether or not the name of the current context is +cname.

+
expanderName cname
+

Returns the name of the current context.

+
expanderName cpop cname
+

Pops a context from the context stack, returning all accumulated +output in that context. The context must be named cname, or an +error results.

+
expanderName ctopandclear
+

Returns the output currently captured in the topmost context and +clears that buffer. This is similar to a combination of cpop +followed by cpush, except that internal state (brackets) is +preserved here.

+
expanderName cpush cname
+

Pushes a context named cname onto the context stack. The +context must be popped by cpop before expansion ends or an +error results.

+
expanderName cset varname value
+

Sets variable varname to value in the current context.

+
expanderName cvar varname
+

Retrieves the internal variable name of context variable +varname; this allows the variable to be passed to commands like +lappend.

+
expanderName errmode newErrmode
+

Sets the macro expansion error mode to one of nothing, +macro, error, or fail; the default value is +fail. The value determines what the expander does if an +error is detected during expansion of a macro.

+
+
fail
+

The error propagates normally and can be caught or ignored by the +application.

+
error
+

The macro expands into a detailed error message, and expansion +continues.

+
macro
+

The macro expands to itself; that is, it is passed along to the output +unchanged.

+
nothing
+

The macro expands to the empty string, and is effectively ignored.

+
+
expanderName evalcmd ?newEvalCmd?
+

Returns the current evaluation command, which defaults to +uplevel #0. If specified, newEvalCmd will be saved for +future use and then returned; it must be a Tcl command expecting one +additional argument: the macro to evaluate.

+
expanderName expand string ?brackets?
+

Expands the input string, replacing embedded macros with their +expanded values, and returns the expanded string.

+

Note that this method pushes a new (empty) context on the stack of +contexts while it is running, and removes it on return.

+

If brackets is given, it must be a list of two strings; the +items will be used as the left and right macro expansion bracket +sequences for this expansion only.

+
expanderName lb ?newbracket?
+

Returns the current value of the left macro expansion bracket; this is +for use as or within a macro, when the bracket needs to be included in +the output text. If newbracket is specified, it becomes the new +bracket, and is returned.

+
expanderName rb ?newbracket?
+

Returns the current value of the right macro expansion bracket; this +is for use as or within a macro, when the bracket needs to be included +in the output text. If newbracket is specified, it becomes the +new bracket, and is returned.

+
expanderName reset
+

Resets all expander settings to their initial values. Unusual results +are likely if this command is called from within a call to +expand.

+
expanderName setbrackets lbrack rbrack
+

Sets the left and right macro expansion brackets. This command is for +use as or within a macro, or to permanently change the bracket +definitions. By default, the brackets are [ and +], but any non-empty string can be used; for example, +< and > or (* and *) or even +Hello, and World!.

+
expanderName textcmd ?newTextCmd?
+

Returns the current command for processing plain text, which defaults +to the empty string, meaning identity. If specified, +newTextCmd will be saved for future use and then returned; it +must be a Tcl command expecting one additional argument: the text to +process. The expander object will this command for all plain text it +encounters, giving the user of the object the ability to process all +plain text in some standard way before writing it to the output. The +object expects that the command returns the processed plain text.

+

Note that the combination of "textcmd plaintext" +is run through the evalcmd for the actual evaluation. In other +words, the textcmd is treated as a special macro implicitly +surrounding all plain text in the template.

+
expanderName where
+

Returns a three-element list containing the current character +position, line, and column the expander is at in the processing of the +current input string.

+
+
+

TUTORIAL

+

Basics

+

To begin, create an expander object:

+
+    % package require textutil::expander
+    1.2
+    % ::textutil::expander myexp
+    ::myexp
+    %
+
+

The created ::myexp object can be used to expand text strings +containing embedded Tcl commands. By default, embedded commands are +delimited by square brackets. Note that expander doesn't attempt to +interpolate variables, since variables can be referenced by embedded +commands:

+
+    % set greeting "Howdy"
+    Howdy
+    % proc place {} {return "World"}
+    % ::myexp expand {[set greeting], [place]!}
+    Howdy, World!
+    %
+
+
+

Embedding Macros

+

An expander macro is simply a Tcl script embedded within a text +string. Expander evaluates the script in the global context, and +replaces it with its result string. For example,

+
+    % set greetings {Howdy Hi "What's up"}
+    Howdy Hi "What's up"
+    % ::myexp expand {There are many ways to say "Hello, World!":
+    [set result {}
+    foreach greeting $greetings {
+	append result "$greeting, World!\\n"
+    }
+    set result]
+    And that's just a small sample!}
+    There are many ways to say "Hello, World!":
+    Howdy, World!
+    Hi, World!
+    What's up, World!
+    And that's just a small sample!
+    %
+
+
+

Writing Macro Commands

+

More typically, macro commands are used to create a markup +language. A macro command is just a Tcl command that returns an +output string. For example, expand can be used to implement a generic +document markup language that can be retargeted to HTML or any other +output format:

+
+    % proc bold {} {return "<b>"}
+    % proc /bold {} {return "</b>"}
+    % ::myexp expand {Some of this text is in [bold]boldface[/bold]}
+    Some of this text is in <b>boldface</b>
+    %
+
+

The above definitions of bold and /bold returns HTML, but +such commands can be as complicated as needed; they could, for +example, decide what to return based on the desired output format.

+
+

Changing the Expansion Brackets

+

By default, embedded macros are enclosed in square brackets, +[ and ]. If square brackets need to be +included in the output, the input can contain the lb and +rb commands. Alternatively, or if square brackets are +objectionable for some other reason, the macro expansion brackets can +be changed to any pair of non-empty strings.

+

The setbrackets command changes the brackets permanently. +For example, you can write pseudo-html by change them to < +and >:

+
+    % ::myexp setbrackets < >
+    % ::myexp expand {<bold>This is boldface</bold>}
+    <b>This is boldface</b>
+
+

Alternatively, you can change the expansion brackets temporarily by +passing the desired brackets to the expand command:

+
+    % ::myexp setbrackets "\\[" "\\]"
+    % ::myexp expand {<bold>This is boldface</bold>} {< >}
+    <b>This is boldface</b>
+    %
+
+
+

Customized Macro Expansion

+

By default, macros are evaluated using the Tcl uplevel #0 +command, so that the embedded code executes in the global context. +The application can provide a different evaluation command using +evalcmd; this allows the application to use a safe +interpreter, for example, or even to evaluated something other than +Tcl code. There is one caveat: to be recognized as valid, a macro +must return 1 when passed to Tcl's "info complete" command.

+

For example, the following code "evaluates" each macro by returning +the macro text itself.

+
+    proc identity {macro} {return $macro}
+    ::myexp evalcmd identity
+
+
+

Using the Context Stack

+

Often it's desirable to define a pair of macros which operate in some +way on the plain text between them. Consider a set of macros for +adding footnotes to a web page: one could have implement something +like this:

+
+    Dr. Pangloss, however, thinks that this is the best of all
+    possible worlds.[footnote "See Candide, by Voltaire"]
+
+

The footnote macro would, presumably, assign a number to this +footnote and save the text to be formatted later on. However, this +solution is ugly if the footnote text is long or should contain +additional markup. Consider the following instead:

+
+    Dr. Pangloss, however, thinks that this is the best of all
+    possible worlds.[footnote]See [bookTitle "Candide"], by
+    [authorsName "Voltaire"], for more information.[/footnote]
+
+

Here the footnote text is contained between footnote and +/footnote macros, continues onto a second line, and contains +several macros of its own. This is both clearer and more flexible; +however, with the features presented so far there's no easy way to do +it. That's the purpose of the context stack.

+

All macro expansion takes place in a particular context. Here, the +footnote macro pushes a new context onto the context stack. +Then, all expanded text gets placed in that new context. +/footnote retrieves it by popping the context. Here's a +skeleton implementation of these two macros:

+
+    proc footnote {} {
+        ::myexp cpush footnote
+    }
+    proc /footnote {} {
+        set footnoteText [::myexp cpop footnote]
+        # Save the footnote text, and return an appropriate footnote
+        # number and link.
+    }
+
+

The cpush command pushes a new context onto the stack; the +argument is the context's name. It can be any string, but would +typically be the name of the macro itself. Then, cpop +verifies that the current context has the expected name, pops it off +of the stack, and returns the accumulated text.

+

Expand provides several other tools related to the context stack. +Suppose the first macro in a context pair takes arguments or computes +values which the second macro in the pair needs. After calling +cpush, the first macro can define one or more context +variables; the second macro can retrieve their values any time before +calling cpop. For example, suppose the document must specify +the footnote number explicitly:

+
+    proc footnote {footnoteNumber} {
+        ::myexp cpush footnote
+        ::myexp csave num $footnoteNumber
+        # Return an appropriate link
+    }
+    proc /footnote {} {
+        set footnoteNumber [::myexp cget num]
+        set footnoteText [::myexp cpop footnote]
+        # Save the footnote text and its footnoteNumber for future
+        # output.
+    }
+
+

At times, it might be desirable to define macros that are valid only +within a particular context pair; such macros should verify that they +are only called within the correct context using either cis +or cname.

+
+
+

HISTORY

+

expander was written by William H. Duquette; it is a repackaging +of the central algorithm of the expand macro processing tool.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

[uri, http://www.wjduquette.com/expand, regexp, split, string

+
+ +

Category

+

Documentation tools

+
+ +
ADDED embedded/www/tcllib/files/modules/textutil/repeat.html Index: embedded/www/tcllib/files/modules/textutil/repeat.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/repeat.html +++ embedded/www/tcllib/files/modules/textutil/repeat.html @@ -0,0 +1,163 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::repeat(n) 0.7.1 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::repeat - Procedures to repeat strings.

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil::repeat ?0.7?
    • +
+ +
+
+

Description

+

The package textutil::repeat provides commands to generate +long strings by repeating a shorter string many times.

+

The complete set of procedures is described below.

+
+
::textutil::repeat::strRepeat text num
+

This command returns a string containing the text repeated +num times. The repetitions are joined without characters between +them. A value of num <= 0 causes the command to return an empty +string.

+

Note: If the Tcl core the package is loaded in provides the +command string repeat then this command will be implemented in +its terms, for maximum possible speed. Otherwise a fast implementation +in Tcl will be used.

+
::textutil::repeat::blank num
+

A convenience command. Returns a string of num spaces.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/tabify.html Index: embedded/www/tcllib/files/modules/textutil/tabify.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/tabify.html +++ embedded/www/tcllib/files/modules/textutil/tabify.html @@ -0,0 +1,183 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::tabify(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::tabify - Procedures to (un)tabify strings

+
+ + +

Description

+

The package textutil::tabify provides commands that convert +between tabulation and ordinary whitespace in strings.

+

The complete set of procedures is described below.

+
+
::textutil::tabify::tabify string ?num?
+

Tabify the string by replacing any substring of num space +chars by a tabulation and return the result as a new string. num +defaults to 8.

+
::textutil::tabify::tabify2 string ?num?
+

Similar to ::textutil::tabify this command tabifies the +string and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +num spaces this command works more like an editor. num +defaults to 8.

+

Each line of the text in string is treated as if there are +tabstops every num columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs.

+
::textutil::tabify::untabify string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of num space chars and return the result as a new +string. num defaults to 8.

+
::textutil::tabify::untabify2 string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of at most num space chars and return the result as a +new string. Unlike textutil::tabify::untabify each tab is not +replaced by a fixed number of space characters. The command overlays +each line in the string with tabstops every num columns +instead and replaces tabs with just enough space characters to reach +the next tabstop. This is the complement of the actions taken by +::textutil::tabify::tabify2. num defaults to 8.

+

There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil.html Index: embedded/www/tcllib/files/modules/textutil/textutil.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/textutil.html +++ embedded/www/tcllib/files/modules/textutil/textutil.html @@ -0,0 +1,416 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil(n) 0.8 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil - Procedures to manipulate texts and strings.

+
+ + +

Description

+

The package textutil provides commands that manipulate +strings or texts (a.k.a. long strings or string with embedded newlines +or paragraphs). +It is actually a bundle providing the commands of the six packages

+
+
textutil::adjust
+
+
textutil::repeat
+
+
textutil::split
+
+
textutil::string
+
+
textutil::tabify
+
+
textutil::trim
+
+
+

in the namespace textutil.

+

The bundle is deprecated, and it will be removed in a future +release of Tcllib, after the next release. It is recommended to use the +relevant sub packages instead for whatever functionality is needed by +the using package or application.

+

The complete set of procedures is described below.

+
+
::textutil::adjust string args
+

Do a justification on the string according to args. The +string is taken as one big paragraph, ignoring any newlines. Then the +line is formatted according to the options used, and the command +return a new string with enough lines to contain all the printable +chars in the input string. A line is a set of chars between the +beginning of the string and a newline, or between 2 newlines, or +between a newline and the end of the string. If the input string is +small enough, the returned string won't contain any newlines.

+

Together with ::textutil::indent it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+

By default, any occurrence of spaces characters or tabulation are +replaced by a single space so each word in a line is separated from +the next one by exactly one space char, and this forms a real +line. Each real line is placed in a logical line, which +have exactly a given length (see -length option below). The +real line may have a lesser length. Again by default, any +trailing spaces are ignored before returning the string (see +-full option below). The following options may be used after the +string parameter, and change the way the command place a +real line in a logical line.

+
+
-full boolean
+

If set to false, any trailing space chars are deleted before +returning the string. If set to true, any trailing space +chars are left in the string. Default to false.

+
-hyphenate boolean
+

if set to false, no hyphenation will be done. If set to +true, the last word of a line is tried to be hyphenated. +Defaults to false. Note: hyphenation patterns must be loaded +prior, using the command ::textutil::adjust::readPatterns.

+
-justify center|left|plain|right
+

Set the justification of the returned string to center, +left, plain or right. By default, it is set to +left. The justification means that any line in the returned +string but the last one is build according to the value. If the +justification is set to plain and the number of printable +chars in the last line is less than 90% of the length of a line (see +-length), then this line is justified with the left +value, avoiding the expansion of this line when it is too small. The +meaning of each value is:

+
+
center
+

The real line is centered in the logical line. If needed, a set of +space characters are added at the beginning (half of the needed set) +and at the end (half of the needed set) of the line if required (see +the option -full).

+
left
+

The real line is set on the left of the logical line. It means that +there are no space chars at the beginning of this line. If required, +all needed space chars are added at the end of the line (see the +option -full).

+
plain
+

The real line is exactly set in the logical line. It means that there +are no leading or trailing space chars. All the needed space chars are +added in the real line, between 2 (or more) words.

+
right
+

The real line is set on the right of the logical line. It means that +there are no space chars at the end of this line, and there may be +some space chars at the beginning, despite of the -full option.

+
+
-length integer
+

Set the length of the logical line in the string to +integer. integer must be a positive integer +value. Defaults to 72.

+
-strictlength boolean
+

If set to false, a line can exceed the specified +-length if a single word is longer than -length. If +set to true, words that are longer than -length are +split so that no line exceeds the specified -length. Defaults +to false.

+
+
::textutil::adjust::readPatterns filename
+

Loads the internal storage for hyphenation patterns with the contents +of the file filename. This has to be done prior to calling +command ::textutil::adjust with +"-hyphenate true", or the hyphenation process will +not work correctly.

+

The package comes with a number of predefined pattern files, and the +command ::textutil::adjust::listPredefined can be used to find +out their names.

+
::textutil::adjust::listPredefined
+

This command returns a list containing the names of the hyphenation +files coming with this package.

+
::textutil::adjust::getPredefined filename
+

Use this command to query the package for the full path name of the +hyphenation file filename coming with the package. Only the +filenames found in the list returned by +::textutil::adjust::listPredefined are legal arguments for this +command.

+
::textutil::indent string prefix ?skip?
+

Each line in the string indented by adding the string +prefix at its beginning. The modified string is returned +as the result of the command.

+

If skip is specified the first skip lines are left +untouched. The default for skip is 0, causing the +modification of all lines. Negative values for skip are treated +like 0. In other words, skip > 0 creates a +hanging indentation.

+

Together with ::textutil::adjust it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+
::textutil::undent string
+

The command computes the common prefix for all +lines in string consisting solely out of whitespace, +removes this from each line and returns the modified string.

+

Lines containing only whitespace are always reduced to completely +empty lines. They and empty lines are also ignored when computing the +prefix to remove.

+

Together with ::textutil::adjust it is possible to create +properly wrapped paragraphs with arbitrary indentations.

+
::textutil::splitn string ?len?
+

This command splits the given string into chunks of len +characters and returns a list containing these chunks. The argument +len defaults to 1 if none is specified. A negative +length is not allowed and will cause the command to throw an +error. Providing an empty string as input is allowed, the command will +then return an empty list. If the length of the string is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than len.

+
::textutil::splitx string ?regexp?
+

Split the string and return a list. The string is split +according to the regular expression regexp instead of a simple +list of chars. Note that if you add parenthesis into the regexp, +the parentheses part of separator would be added into list as +additional element. If the string is empty the result is the +empty list, like for split. If regexp is empty the +string is split at every character, like split does. +The regular expression regexp defaults to "[\\t \\r\\n]+".

+
::textutil::tabify string ?num?
+

Tabify the string by replacing any substring of num space +chars by a tabulation and return the result as a new string. num +defaults to 8.

+
::textutil::tabify2 string ?num?
+

Similar to ::textutil::tabify this command tabifies the +string and returns the result as a new string. A different +algorithm is used however. Instead of replacing any substring of +num spaces this command works more like an editor. num +defaults to 8.

+

Each line of the text in string is treated as if there are +tabstops every num columns. Only sequences of space characters +containing more than one space character and found immediately before +a tabstop are replaced with tabs.

+
::textutil::trim string ?regexp?
+

Remove in string any leading and trailing substring according to +the regular expression regexp and return the result as a new +string. This apply on any line in the string, that is any +substring between 2 newline chars, or between the beginning of the +string and a newline, or between a newline and the end of the string, +or, if the string contain no newline, between the beginning and the +end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimleft string ?regexp?
+

Remove in string any leading substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimright string ?regexp?
+

Remove in string any trailing substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trimPrefix string prefix
+

Removes the prefix from the beginning of string and +returns the result. The string is left unchanged if it doesn't +have prefix at its beginning.

+
::textutil::trimEmptyHeading string
+

Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the string and removes it. The modified +string is returned as the result of the command.

+
::textutil::untabify string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of num space chars and return the result as a new +string. num defaults to 8.

+
::textutil::untabify2 string ?num?
+

Untabify the string by replacing any tabulation char by a +substring of at most num space chars and return the result as a +new string. Unlike textutil::untabify each tab is not replaced +by a fixed number of space characters. The command overlays each line +in the string with tabstops every num columns instead and +replaces tabs with just enough space characters to reach the next +tabstop. This is the complement of the actions taken by +::textutil::tabify2. num defaults to 8.

+

There is one asymmetry though: A tab can be replaced with a single +space, but not the other way around.

+
::textutil::strRepeat text num
+

The implementation depends on the core executing the package. Used +string repeat if it is present, or a fast tcl implementation +if it is not. Returns a string containing the text repeated +num times. The repetitions are joined without characters between +them. A value of num <= 0 causes the command to return an empty +string.

+
::textutil::blank num
+

A convenience command. Returns a string of num spaces.

+
::textutil::chop string
+

A convenience command. Removes the last character of string and +returns the shortened string.

+
::textutil::tail string
+

A convenience command. Removes the first character of string and +returns the shortened string.

+
::textutil::cap string
+

Capitalizes the first character of string and returns the modified string.

+
::textutil::uncap string
+

The complementary operation to ::textutil::cap. Forces the first +character of string to lower case and returns the modified +string.

+
::textutil::longestCommonPrefixList list
+
+
::textutil::longestCommonPrefix ?string...?
+

Computes the longest common prefix for either the strings given +to the command, or the strings specified in the single list, and +returns it as the result of the command.

+

If no strings were specified the result is the empty string. If only +one string was specified, the string itself is returned, as it is its +own longest common prefix.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil_split.html Index: embedded/www/tcllib/files/modules/textutil/textutil_split.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/textutil_split.html +++ embedded/www/tcllib/files/modules/textutil/textutil_split.html @@ -0,0 +1,171 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::split(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::split - Procedures to split texts

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require textutil::split ?0.7?
    • +
+ +
+
+

Description

+

The package textutil::split provides commands that split +strings by size and arbitrary regular expressions.

+

The complete set of procedures is described below.

+
+
::textutil::split::splitn string ?len?
+

This command splits the given string into chunks of len +characters and returns a list containing these chunks. The argument +len defaults to 1 if none is specified. A negative +length is not allowed and will cause the command to throw an +error. Providing an empty string as input is allowed, the command will +then return an empty list. If the length of the string is not an +entire multiple of the chunk length, then the last chunk in the +generated list will be shorter than len.

+
::textutil::split::splitx string ?regexp?
+

This command splits the string and return a list. The string is +split according to the regular expression regexp instead of a +simple list of chars. +Note that if you parentheses are added into the regexp, the +parentheses part of separator will be added into the result list as +additional element. If the string is empty the result is the +empty list, like for split. If regexp is empty the +string is split at every character, like split does. +The regular expression regexp defaults to "[\\t \\r\\n]+".

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/textutil_string.html Index: embedded/www/tcllib/files/modules/textutil/textutil_string.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/textutil_string.html +++ embedded/www/tcllib/files/modules/textutil/textutil_string.html @@ -0,0 +1,184 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::string(n) 0.8 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::string - Procedures to manipulate texts and strings.

+
+ + +

Description

+

The package textutil::string provides miscellaneous string +manipulation commands.

+

The complete set of procedures is described below.

+
+
::textutil::string::chop string
+

A convenience command. Removes the last character of string and +returns the shortened string.

+
::textutil::string::tail string
+

A convenience command. Removes the first character of string and +returns the shortened string.

+
::textutil::string::cap string
+

Capitalizes the first character of string and returns the +modified string.

+
::textutil::string::capEachWord string
+

Capitalizes the first character of word of the string and +returns the modified string. Words quoted with either backslash or +dollar-sign are left untouched.

+
::textutil::string::uncap string
+

The complementary operation to ::textutil::string::cap. Forces +the first character of string to lower case and returns the +modified string.

+
::textutil::string::longestCommonPrefixList list
+
+
::textutil::string::longestCommonPrefix ?string...?
+

Computes the longest common prefix for either the strings given +to the command, or the strings specified in the single list, and +returns it as the result of the command.

+

If no strings were specified the result is the empty string. If only +one string was specified, the string itself is returned, as it is its +own longest common prefix.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/textutil/trim.html Index: embedded/www/tcllib/files/modules/textutil/trim.html ================================================================== --- embedded/www/tcllib/files/modules/textutil/trim.html +++ embedded/www/tcllib/files/modules/textutil/trim.html @@ -0,0 +1,188 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

textutil::trim(n) 0.7 tcllib "Text and string utilities, macro processing"

+

Name

+

textutil::trim - Procedures to trim strings

+
+ + +

Description

+

The package textutil::trim provides commands that trim +strings using arbitrary regular expressions.

+

The complete set of procedures is described below.

+
+
::textutil::trim::trim string ?regexp?
+

Remove in string any leading and trailing substring according to +the regular expression regexp and return the result as a new +string. This is done for all lines in the string, that is any +substring between 2 newline chars, or between the beginning of the +string and a newline, or between a newline and the end of the string, +or, if the string contain no newline, between the beginning and the +end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimleft string ?regexp?
+

Remove in string any leading substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimright string ?regexp?
+

Remove in string any trailing substring according to the regular +expression regexp and return the result as a new string. This +apply on any line in the string, that is any substring between +2 newline chars, or between the beginning of the string and a newline, +or between a newline and the end of the string, or, if the string +contain no newline, between the beginning and the end of the string. +The regular expression regexp defaults to "[ \\t]+".

+
::textutil::trim::trimPrefix string prefix
+

Removes the prefix from the beginning of string and +returns the result. The string is left unchanged if it doesn't +have prefix at its beginning.

+
::textutil::trim::trimEmptyHeading string
+

Looks for empty lines (including lines consisting of only whitespace) +at the beginning of the string and removes it. The modified +string is returned as the result of the command.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category textutil of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

regexp(n), split(n), string(n)

+
+ +

Category

+

Text processing

+
+
ADDED embedded/www/tcllib/files/modules/tie/tie.html Index: embedded/www/tcllib/files/modules/tie/tie.html ================================================================== --- embedded/www/tcllib/files/modules/tie/tie.html +++ embedded/www/tcllib/files/modules/tie/tie.html @@ -0,0 +1,499 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tie(n) 1.1 tcllib "Tcl Data Structures"

+

Name

+

tie - Array persistence

+
+ + +

Description

+

The tie package provides a framework for the creation of +persistent Tcl array variables. It should be noted that the provided +mechanism is generic enough to also allow its usage for the +distribution of the contents of Tcl arrays over multiple threads and +processes, i.e. communication.

+

This, persistence and communication, is accomplished by tying) +a Tcl array variable to a data source. Examples of data +sources are other Tcl arrays and files.

+

It should be noted that a single Tcl array variable can be tied to +more than one data source. It is this feature which allows +the framework to be used for communication as well. Just tie several +Tcl arrays in many client processes to a Tcl array in a server and all +changes to any of them will be distributed to all. Less centralized +variants of this are of course possible as well.

+
+

USING TIES

+

TIE API

+

This section describes the basic API used to establish and remove ties +between Tcl array variables and data sources. This interface is the +only one a casual user has to be concerned about. The following +sections about the various internal interfaces can be safely skipped.

+
+
::tie::tie arrayvarname options... dstype dsname...
+

This command establishes a tie between the Tcl array whose name is +provided by the argument arrayvarname and the +data source identified by the dstype and its series of +dsname arguments. All changes made to the Tcl array after this +command returns will be saved to the data source for +safekeeping (or distribution).

+

The result of the command is always a token which identifies the new +tie. This token can be used later to destroy this specific tie.

+
+
varname arrayvarname (in)
+

The name of the Tcl array variable to connect the new tie to.

+
name|command dstype (in)
+

This argument specifies the type of the data source we wish +to access. +The dstype can be one of log, array, +remotearray, file, growfile, or +dsource; in addition, the programmer can register additional +data source types. +Each dstype is followed by one or more arguments that identify +the data source to which the array is to be tied.

+
string dsname (in)
+

The series of dsname arguments coming after the dstype +identifies the data source we wish to connect to, and has to +be appropriate for the chosen type.

+
+

The command understands a number of additional options which guide the +process of setting up the connection between Tcl array and +data source.

+
+
-open
+

The Tcl array for the new tie is loaded from the +data source, and the previously existing contents of the Tcl +array are erased. Care is taken to not erase the previous +contents should the creation of the tie fail.

+

This option and the option -save exclude each other. If +neither this nor option -save are specified then this option +is assumed as default.

+
-save
+

The Tcl array for the new tie is saved to the +data source, and the previously existing contents of the +data source are erased.

+

This option and the option -open exclude each other. If +neither this nor option -open are specified then option +-open is assumed as default.

+
-merge
+

Using this option prevents the erasure of any previously existing +content and merges the data instead. It can be specified in +conjunction with either -open or -save. They +determine how data existing in both Tcl array and +data source, i.e duplicates, are dealt with.

+

When used with -open data in the data source has +precedence. +In other words, for duplicates the data in the data source is +loaded into the Tcl array.

+

When used with -save data in the Tcl array has precedence. In +other words, for duplicates the data in the Tcl array is saved into +the data source.

+
+
::tie::untie arrayvarname ?token?
+

This command dissolves one or more ties associated with the Tcl array +named by arrayvarname. If no token is specified then all +ties to that Tcl array are dissolved. Otherwise only the tie the token +stands for is removed, if it is actually connected to the +array. Trying to remove a specific tie not belonging to the provided +array will cause an error.

+

It should be noted that while severing a tie will destroy management +information internal to the package the data source which was +handled by the tie will not be touched, only closed.

+

After the command returns none of changes made to the array will be +saved to the data source anymore.

+

The result of the command is an empty string.

+
+
varname arrayname (in)
+

The name of a Tcl array variable which may have ties.

+
handle token (in)
+

A handle representing a specific tie. This argument is optional.

+
+
::tie::info ties arrayvarname
+

This command returns a list of ties associated with the Tcl array +variable named by arrayvarname. The result list will be empty if +the variable has no ties associated with it.

+
::tie::info types
+

This command returns a dictionary of registered types, and the class +commands they are associated with.

+
::tie::info type dstype
+

This command returns the fully resolved class command for a type +name. This means that the command will follow a chain of type +definitions ot its end.

+
+
+

STANDARD DATA SOURCE TYPES

+

This package provides the six following types as examples and standard +data sources.

+
+
log
+

This data source does not maintain any actual data, nor +persistence. It does not accept any identifying arguments. All changes +are simply logged to stdout.

+
array
+

This data source uses a regular Tcl array as the origin of +the persistent data. It accepts a single identifying argument, the +name of this Tcl array. All changes are mirrored to that array.

+
remotearray
+

This data source is similar to array. The difference +is that the Tcl array to which we are mirroring is not directly +accessible, but through a send-like command.

+

It accepts three identifying arguments, the name of the other Tcl +array, the command prefix for the send-like accessor command, +and an identifier for the remote entity hosting the array, in this +order. All changes are mirrored to that array, via the command +prefix. All commands will be executed in the context of the global +namespace.

+

send-like means that the command prefix has to have send +syntax and semantics. I.e. it is a channel over which we can send +arbitrary commands to some other entity. +The remote array data source however uses only the commands +set, unset, array exists, array names, array set, and +array get to retrieve and set values in the remote array.

+

The command prefix and the entity id are separate to allow the data +source to use options like -async when assembling the actual +commands.

+

Examples of command prefixes, listed with the id of the remote entity, +without options. In reality only the part before the id is the command +prefix:

+
+
send tkname
+

The Tcl array is in a remote interpreter and is accessed via Tk's X +communication.

+
comm::comm send hostportid
+

The Tcl array is in a remote interpreter and is accessed through a +socket.

+
thread::send threadid
+

The Tcl array is in a remote interpreter in a different thread of this +process.

+
+
file
+

This data source uses a single file as origin of the +persistent data. It accepts a single identifying argument, the path to +this file. The file has to be both readable and writable. It may not +exist, the data source will create it in that case. This (and +only this) situation will require that the directory for the file +exists and is writable as well.

+

All changes are saved in the file, as proper Tcl commands, one command +per operation. In other words, the file will always contain a proper +Tcl script.

+

If the file exists when the tie using it is set up, then it will be +compacted, i.e. superfluous operations are removed, if the operations +log stored in it contains either at least one operation clearing the +whole array, or at least 1.5 times more operations than entries in the +loaded array.

+
growfile
+

This data source is like file in terms of the storage +medium for the array data, and how it is configured. In constrast to +the former it however assumes and ensures that the tied array will +never shrink. I.e. the creation of new array entries, and the +modification of existing entries is allowed, but the deletion of +entries is not, and causes the data source to throw errors.

+

This restriction allows us to simplify both file format and access to +the file radically. For one, the file is read only once and the +internal cache cannot be invalidated. Second, writing data is reduced +to a simple append, and no compaction step is necessary. The format of +the contents is the string representation of a dictionary which can be +incrementally extended forever at the end.

+
dsource
+

This data source uses an explicitly specified +data source object as the source for the persistent +data. It accepts a single identifying argument, the command prefix, +i.e. object command.

+

To use this type it is necessary to know how the framework manages +ties and what data source objects are.

+

All changes are delegated to the specified object.

+
+
+
+

CREATING NEW DATA SOURCES

+

This section is of no interest to the casual user of ties. Only +developers wishing to create new data sources have to know the +information provided herein.

+

DATA SOURCE OBJECTS

+

All ties are represented internally by an in-memory object which +mediates between the tie framework and the specific +data source, like an array, file, etc. +This is the data source object.

+

Its class, the data source class is not generic, +but specific to the type of the data source. Writing a new +data source requires us to write such a class, and then +registering it with the framework as a new type.

+

The following subsections describe the various APIs a +data source class and the objects it generates will have +to follow to be compatible with the tie framework.

+

Data source objects are normally automatically created and destroyed +by the framework when a tie is created, or removed. This management +can be explicitly bypassed through the usage of the "dsource" type. +The data source for this type is a +data source object itself, and this object is outside of the +scope of the tie framework and not managed by it. +In other words, this type allows the creation of ties which talk to +pre-existing data source objects, and these objects will +survive the removal of the ties using them as well.

+
+

REGISTERING A NEW DATA SOURCE CLASS

+

After a data source class has been written it is necessary +to register it as a new type with the framework.

+
+
::tie::register dsclasscmd as dstype
+

Using this command causes the tie framework to remember the class +command dsclasscmd of a data source class under the +type name dstype.

+

After the call the argument dstype of the basic user command +::tie::tie will accept dstype as a type name and translate +it internally to the appropriate class command for the creation of +data source objects for the new data source.

+
+
+

DATA SOURCE CLASS

+

Each data source class is represented by a single command, also called +the class command, or object creation command. Its +syntax is

+
+
dsclasscmd objname ?dsname...?
+

The first argument of the class command is the name of the +data source object to create. +The framework itself will always supply the string %AUTO%, to +signal that the class command has to generate not only the object, but +the object name as well.

+

This is followed by a series of arguments identifying the data source +the new object is for. These are the same dsname arguments which +are given to the basic user command ::tie::tie. Their actual +meaning is dependent on the data source class.

+

The result of the class command has to be the fully-qualified name of +the new data source object, i.e. the name of the +object command. +The interface this command has to follow is described in the section +DATA SOURCE OBJECT API

+
+
+

DATA SOURCE OBJECT API

+

Please read the section DATA SOURCE CLASS first, to know +how to generate new object commands.

+

Each object command for a data source object has to +provide at least the methods listed below for proper inter-operation +with the tie framework. Note that the names of most of the methods +match the subcommands of the builtin array command.

+
+
ds destroy
+

This method is called when the object ds is destroyed. It now +has to release all its internal resources associated with the external +data source.

+
ds names
+

This command has to return a list containing the names of all keys +found in the data source the object talks to. This is +equivalent to array names.

+
ds size
+

This command has to return an integer number specifying the number of +keys found in the data source the object talks to. This is +equivalent to array size.

+
ds get
+

This command has to return a dictionary containing the data found in +the data source the object talks to. This is equivalent to +array get.

+
ds set dict
+

This command takes a dictionary and adds its contents to the data +source the object talks to. This is equivalent to array set.

+
ds unset ?pattern?
+

This command takes a pattern and removes all elements whose keys +matching it from the data source. If no pattern is specified +it defaults to *, causing the removal of all elements. This +is nearly equivalent to array unset.

+
ds setv index value
+

This command has to save the value in the data source +the object talks to, under the key index.

+

The result of the command is ignored. If an error is thrown then this +error will show up as error of the set operation which caused the +method call.

+
ds unsetv index
+

This command has to remove the value under the key index from +the data source the object talks to.

+

The result of the command is ignored. If an error is thrown then this +error will show up as error of the unset operation which caused the +method call.

+
ds getv index
+

This command has to return the value for the key index in the +data source the object talks to.

+
+

And here a small table comparing the data source methods to +the regular Tcl commands for accessing an array.

+
+        Regular Tcl             Data source
+        -----------             -----------
+        array names a           ds names
+        array size  a           ds size
+        array get   a           ds get
+        array set   a dict      ds set   dict
+        array unset a pattern   ds unset ?pattern?
+        -----------             -----------
+        set a($idx) $val        ds setv   idx val
+        unset a($idx)           ds unsetv idx
+        $a($idx)                ds getv   idx
+        -----------             -----------
+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tie of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/tie/tie_std.html Index: embedded/www/tcllib/files/modules/tie/tie_std.html ================================================================== --- embedded/www/tcllib/files/modules/tie/tie_std.html +++ embedded/www/tcllib/files/modules/tie/tie_std.html @@ -0,0 +1,155 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tie(n) 1.1 tcllib "Tcl Data Structures"

+

Name

+

tie - Array persistence, standard data sources

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require tie::std::log ?1.0?
    • +
  • package require tie::std::array ?1.0?
    • +
  • package require tie::std::rarray ?1.0.1?
    • +
  • package require tie::std::file ?1.0.4?
    • +
  • package require tie::std::growfile ?1.0?
    • +
  • package require tie::std::dsource ?1.0?
    • +
+
+
+

Description

+

The packages listed as requirements for this document are internal +packages providing the standard data sources of package tie, +as described in section STANDARD DATA SOURCE TYPES of +tie's documentation.

+

They are automatically loaded and registered by tie when it +itself is requested, and as such there is no need to request them on +their own, although it is possible to do so.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tie of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/tiff/tiff.html Index: embedded/www/tcllib/files/modules/tiff/tiff.html ================================================================== --- embedded/www/tcllib/files/modules/tiff/tiff.html +++ embedded/www/tcllib/files/modules/tiff/tiff.html @@ -0,0 +1,285 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tiff(n) 0.2.1 tcllib "TIFF image manipulation"

+

Name

+

tiff - TIFF reading, writing, and querying and manipulation of meta data

+
+ + +

Description

+

This package provides commands to query, modify, read, and write TIFF images. +TIFF stands for Tagged Image File Format and is a standard +for lossless storage of photographical images and associated metadata. +It is specified at http://partners.adobe.com/public/developer/tiff/index.html.

+

Multiple images may be stored in a single TIFF file. The ?image? options to the functions +in this package are for accessing images other than the first. Data in a TIFF image is +stored as a series of tags having a numerical value, which are represented in either a 4 digit +hexadecimal format or a string name. For a reference on defined tags and their meanings see +http://www.awaresystems.be/imaging/tiff/tifftags.html

+
+

COMMANDS

+
+
::tiff::isTIFF file
+

Returns a boolean value indicating if file is a +TIFF image.

+
::tiff::byteOrder file
+

Returns either big or little. +Throws an error if file is not a TIFF image.

+
::tiff::numImages file
+

Returns the number of images in file. +Throws an error if file is not a TIFF image.

+
::tiff::dimensions file ?image?
+

Returns the dimensions of image number ?image? in file as a list of the +horizontal and vertical pixel count. +Throws an error if file is not a TIFF image.

+
::tiff::imageInfo file ?image?
+

Returns a dictionary with keys ImageWidth, ImageLength, +BitsPerSample, Compression, PhotometricInterpretation, +ImageDescription, Orientation, XResolution, +YResolution, ResolutionUnit, DateTime, Artist, +and HostComputer. The values are the associated properties of +the TIFF ?image? in file. Values may be empty if the associated tag is not +present in the file.

+
+    puts [::tiff::imageInfo photo.tif]
+    ImageWidth 686 ImageLength 1024 BitsPerSample {8 8 8} Compression 1
+    PhotometricInterpretation 2 ImageDescription {} Orientation 1
+    XResolution 170.667 YResolution 170.667 ResolutionUnit 2 DateTime {2005:12:28 19:44:45}
+    Artist {} HostComputer {}
+
+

There is nothing special about these tags, this is simply a convience procedure which calls +getEntry with common entries. +Throws an error if file is not a TIFF image.

+
::tiff::entries file ?image?
+

Returns a list of all entries in the given file and ?image? +in hexadecimal format. +Throws an error if file is not a TIFF image.

+
::tiff::getEntry file entry ?image?
+

Returns the value of entry from image ?image? in the TIFF file. +entry may be a list of multiple entries. If an entry does not exist, an +empty string is returned

+
+    set data [::tiff::getEntry photo.tif {0131 0132}]
+    puts "file was written at [lindex $data 0] with software [lindex $data 1]"
+
+

Throws an error if file is not a TIFF image.

+
::tiff::addEntry file entry ?image?
+

Adds the specified entries to the image named by ?image? (default 0), or optionally all. +entry must be a list where each element is a list of tag, type, and value. If a tag already +exists, it is overwritten.

+
+    ::tiff::addEntry photo.tif {{010e 2 "an example photo"} {013b 2 "Aaron F"}}
+
+

The data types are defined as follows

+
+
1
+

BYTE (8 bit unsigned integer)

+
2
+

ASCII

+
3
+

SHORT (16 bit unsigned integer)

+
4
+

LONG (32 bit unsigned integer)

+
5
+

RATIONAL

+
6
+

SBYTE (8 bit signed byte)

+
7
+

UNDEFINED (uninterpreted binary data)

+
8
+

SSHORT (signed 16 bit integer)

+
9
+

SLONG (signed 32 bit integer)

+
10
+

SRATIONAL

+
11
+

FLOAT (32 bit floating point number)

+
12
+

DOUBLE (64 bit floating point number)

+
+

Throws an error if file is not a TIFF image.

+
::tiff::deleteEntry file entry ?image?
+

Deletes the specified entries from the image named by ?image? (default 0), or optionally all. +Throws an error if file is not a TIFF image.

+
::tiff::getImage file ?image?
+

Returns the name of a Tk image containing the image at index ?image? from file +Throws an error if file is not a TIFF image, or if image is an unsupported format. +Supported formats are uncompressed 24 bit RGB and uncompressed 8 bit palette.

+
::tiff::writeImage image file ?entry?
+

Writes the contents of the Tk image image to a tiff file file. Files are +written in the 24 bit uncompressed format, with big endian byte order. Additional entries +to be added to the image may be specified, in the same format as tiff::addEntry

+
::tiff::nametotag names
+

Returns a list with names translated from string to 4 digit format. 4 digit names +in the input are passed through unchanged. Strings without a defined tag name will throw +an error.

+
::tiff::tagtoname tags
+

Returns a list with tags translated from 4 digit to string format. If a tag does +not have a defined name it is passed through unchanged.

+
::tiff::debug file
+

Prints everything we know about the given file in a nice format.

+
+
+

VARIABLES

+

The mapping of 4 digit tag names to string names uses the array ::tiff::tiff_tags. The reverse +mapping uses the array ::tiff::tiff_sgat.

+
+

LIMITATIONS

+
    +

  1. Cannot write exif ifd

    2. +

  2. Reading limited to uncompressed 8 bit rgb and 8 bit palletized images

    3. +

  3. Writing limited to uncompressed 8 bit rgb

    4. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tiff of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File formats

+
+ +
ADDED embedded/www/tcllib/files/modules/tool/meta.html Index: embedded/www/tcllib/files/modules/tool/meta.html ================================================================== --- embedded/www/tcllib/files/modules/tool/meta.html +++ embedded/www/tcllib/files/modules/tool/meta.html @@ -0,0 +1,273 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

oo::util(n) 1.2.2 tcllib "Utility commands for TclOO"

+

Name

+

oo::util - Utility commands for TclOO

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require oo::util ?1.2.2?
    • +
+ +
+
+

Description

+

This package provides a convenience command for the easy specification +of instance methods as callback commands, like timers, file events, Tk +bindings, etc.

+
+

COMMANDS

+
+
mymethod method ?arg...?
+

This command is available within instance methods. It takes a method +name and, possibly, arguments for the method and returns a command +prefix which, when executed, will invoke the named method of the +object we are in, with the provided arguments, and any others supplied +at the time of actual invokation.

+

Note: The command is equivalent to and named after the command +provided by the OO package snit for the same purpose.

+
classmethod name arguments body
+

This command is available within class definitions. It takes a method +name and, possibly, arguments for the method and creates a method on the +class, available to a user of the class and of derived classes.

+

Note: The command is equivalent to the command typemethod +provided by the OO package snit for the same purpose.

+

Example

+
+oo::class create ActiveRecord {
+    classmethod find args { puts "[self] called with arguments: $args" }
+}
+oo::class create Table {
+    superclass ActiveRecord
+}
+puts [Table find foo bar]
+# ======
+# which will write
+# ======
+# ::Table called with arguments: foo bar
+
+
+
classvariable ?arg...?
+

This command is available within instance methods. It takes a series +of variable names and makes them available in the method's scope. The +originating scope for the variables is the class (instance) the object +instance belongs to. In other words, the referenced variables are shared +between all instances of their class.

+

Note: The command is roughly equivalent to the command +typevariable provided by the OO package snit for the +same purpose. The difference is that it cannot be used in the class +definition itself.

+

Example:

+
+% oo::class create Foo {
+    method bar {z} {
+        classvariable x y
+        return [incr x $z],[incr y]
+    }
+}
+::Foo
+% Foo create a
+::a
+% Foo create b
+::b
+% a bar 2
+2,1
+% a bar 3
+5,2
+% b bar 7
+12,3
+% b bar -1
+11,4
+% a bar 0
+11,5
+
+
+
link method...
+
+
link {alias method}...
+

This command is available within instance methods. It takes a list of +method names and/or pairs of alias- and method-name and makes the +named methods available to all instance methods without requiring the +my command.

+

The alias name under which the method becomes available defaults +to the method name, except where explicitly specified through an +alias/method pair.

+

Examples:

+
+    link foo
+    # The method foo is now directly accessible as foo instead of my foo.
+    link {bar foo}
+    # The method foo is now directly accessible as bar.
+    link a b c
+    # The methods a, b, and c all become directly acessible under their
+    # own names.
+
+

The main use of this command is expected to be in instance constructors, +for convenience, or to set up some methods for use in a mini DSL.

+
ooutil::singleton ?arg...?
+

This command is a meta-class, i.e. a variant of the builtin +oo::class which ensures that it creates only a single +instance of the classes defined with it.

+

Syntax and results are like for oo::class.

+

Example:

+
+% oo::class create example {
+   self mixin singleton
+   method foo {} {self}
+}
+::example
+% [example new] foo
+::oo::Obj22
+% [example new] foo
+::oo::Obj22
+
+
+
+
+

AUTHORS

+

Donal Fellows, Andreas Kupries

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category oo::util of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/tool/tool.html Index: embedded/www/tcllib/files/modules/tool/tool.html ================================================================== --- embedded/www/tcllib/files/modules/tool/tool.html +++ embedded/www/tcllib/files/modules/tool/tool.html @@ -0,0 +1,343 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tool(n) 0.4.2 tcllib "Standardized OO Framework for development"

+

Name

+

tool - Dictionary Tools

+
+ + +

Description

+

This module implements the Tcl Object Oriented Library framework, or TOOL. It is +intended to be a general purpose framework that is useable in its own right, and +easily extensible.

+

TOOL defines a metaclass with provides several additional keywords to the TclOO +description langauge, default behaviors for its consituent objects, and +top-down integration with the capabilities provided by the oo::meta package.

+

The TOOL metaclass was build with the oo::dialect package, and thus can +be used as the basis for additional metaclasses. As a metaclass, TOOL has it's own +"class" class, "object" class, and define namespace.

+
+package require tool
+# tool::class workds just like oo::class
+tool::class create myclass {
+}
+# tool::define works just like oo::define
+tool::define myclass method noop {} {}
+# tool::define and tool::class understand additional keywords
+tool::define myclass array_ensemble mysettings mysettings {}
+# And tool interoperates with oo::define
+oo::define myclass method do_something {} { return something }
+# TOOL and TclOO objects are interchangeable
+oo::class create myooclass {
+  superclass myclass
+}
+
+

Several manual pages go into more detail about specific keywords and methods.

+
+
tool::array_ensemble
+
+
tool::dict_ensemble
+
+
tool::method_ensemble
+
+
tool::object
+
+
tool::option_handling
+
+
+
+

Keywords

+

TOOL adds new (or modifies) keywords used in the definitions of classes. However, +the new keywords are only available via calls to tool::class create or tool::define

+
+
tool::define class_method arglist body
+

Defines a method for the class object itself. This method will be passed on to descendents of the class, +unlike self method.

+
tool::define array name contents
+

Declares a variable name which will be initialized as an array, populated with contents for objects of this class, as well as any +objects for classes which are descendents of this class.

+
tool::define array_ensemble methodname varname ?cases?
+

Declares a method ensemble methodname which will control access to variable +varname. Cases are a key/value list of method names and bodies which will be +overlaid on top of the standard template. See tool::array_ensemble.

+

One method name is reserved: initialize. initialize Declares the initial values to be populated in the array, as a key/value list, +and will not be expressed as a method for the ensemble.

+
tool::define dict_ensemble methodname varname ?cases?
+

Declares a method ensemble methodname which will control access to variable +varname. Cases are a key/value list of method names and bodies which will be +overlaid on top of the standard template. See tool::dict_ensemble.

+

One method name is reserved: initialize. initialize Declares the initial values to be populated in the array, as a key/value list, +and will not be expressed as a method for the ensemble.

+
tool::define method methodname arglist body
+

If methodname contains ::, the method is considered to be +part of a method ensemble. See tool::method_ensembles. Otherwise +this command behaves exactly like the standard oo::define method +command.

+
tool::define option name dictopts
+

Declares an option. dictopts is a key/value list defining parameters for the option. See tool::option_handling.

+
+tool::class create myclass {
+  option color {
+    post-command: {puts [list %self%'s %field% is now %value%]}
+    default: green
+  }
+}
+myclass create foo
+foo configure color purple
+> foo's color is now purple
+
+
+
tool::define property ?branch? field value
+

Defines a new leaf in the class metadata tree. With no branch, the +leaf will appear in the const section, accessible by either the +object's property method, or via oo::meta::info class get const field:

+
tool::define variable name value
+

Declares a variable name which will be initialized with the value value for objects of this class, as well as any +objects for classes which are descendents of this class.

+
+
+

Public Object Methods

+

The TOOL object mother of all classes defines several methods to enforces consistent +behavior throughout the framework.

+
+
object cget option
+

Return the value of this object's option option. If the property options_strict is true +for this class, calling an option which was not declared by the option keyword will throw +an error. In all other cases if the value is present in the object's options array that +value is returned. If it does not exist, the object will attempt to retrieve a property of the same +name.

+
object configure ?keyvaluelist?
+
+
object configure field value ?field? ?value? ?...?
+

This command will inject new values into the objects options array, according to the rules +as set forth by the option descriptions. See tool::option_handling for details. +configure will strip leading -'s off of field names, allowing it to behave in a quasi-backward +compatible manner to tk options.

+
object configurelist ?keyvaluelist?
+

This command will inject new values into the objects options array, according to the rules +as set forth by the option descriptions. This command will perform validation and alternate storage +rules. It will not invoke trigger rules. See tool::option_handling for details.

+
object forward stub forward
+

A passthrough to oo:objdefine [self] forward

+
object graft stub forward
+

Delegates the <stub> method to the object or command designated by forward

+
+tool::object create A
+tool::object create B
+A graft buddy B
+A configure color red
+B configure color blue
+A cget color
+> red
+A <buddy> cget color
+> blue
+
+
+
+
+

Private Object Methods

+
+
object InitializePublic
+

Consults the metadata for the class to ensure every array, option, and variable +which has been declared but not initialized is initialized with the default value. +This method is called by the constructor and the morph method. It is safe to +invoke multiple times.

+
object Eval_Script ?script?
+

Executes a block of text within the namespace of the object. Lines that +begin with a # are ignored as comments. Commands +that begin with :: are interpreted as calling a global command. All other +Tcl commands that lack a "my" prefix are given one, to allow the script +to exercise internal methods. This method is intended for configuration scripts, +where the object's methods are intepreting a domain specific language.

+
+tool::class myclass {
+  constructor script {
+    my Eval_Script $script
+  }
+  method node {nodename info} {
+    my variable node
+    dict set node $nodename $info
+  }
+  method get {args} {
+    my variable node
+    return [dict get $node $args]
+  }
+}
+myclass create movies {
+  # This block of code is executed by the object
+  node {The Day the Earth Stood Still} {
+    date: 1952
+    characters: {GORT Klatoo}
+  }
+}
+movies get {The Day the Earth Stood Still} date:
+> 1952
+
+
+
object Option_Default field
+

Computes the default value for an option. See tool::option_handling.

+
+
+

AUTHORS

+

Sean Woods

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tool of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/tool/tool_dict_ensemble.html Index: embedded/www/tcllib/files/modules/tool/tool_dict_ensemble.html ================================================================== --- embedded/www/tcllib/files/modules/tool/tool_dict_ensemble.html +++ embedded/www/tcllib/files/modules/tool/tool_dict_ensemble.html @@ -0,0 +1,161 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tool::dict_ensemble(n) 0.4.2 tcllib "Standardized OO Framework for development"

+

Name

+

tool::dict_ensemble - Dictionary Tools

+
+ +

Synopsis

+
+
    +
  • package require tool ?0.4.2?
    • +
+ +
+
+

Description

+

The dict_ensemble command is a keyword added by tool. It defines +a public variable (stored as a dict), and an access function to manipulated and +access the values stored in that dict.

+
+
object ensemble add field
+

] value value ...] +Adds elements to a list maintained with the field leaf of the dict maintained +my this ensemble. +Declares a variable name which will be initialized as an array, populated with contents for objects of this class, as well as any +objects for classes which are descendents of this class.

+
+
+

AUTHORS

+

Sean Woods

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category tool of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/connect.html Index: embedded/www/tcllib/files/modules/transfer/connect.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/connect.html +++ embedded/www/tcllib/files/modules/transfer/connect.html @@ -0,0 +1,332 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::connect(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::connect - Connection setup

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::connect ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects holding enough information to enable +them to either actively connect to a counterpart, or to passively wait +for a connection from said counterpart. +I.e. any object created by this packages is always in one of two +complementary modes, called active (the object initiates the +connection) and passive (the object receives the connection).

+

Of the two objects in a connecting pair one has to be configured for +active mode, and the other then has to be configured for +passive mode. This establishes which of the two partners +connects to whom (the active to the other), or, who is waiting +on whom (the passive on the other). +Note that this is completely independent of the direction of any data +transmission using the connection after it has been established. +An active object can, after establishing the connection, either +transmit or receive data. Equivalently the passive object can do the +same after the waiting for its partner has ended.

+
+

API

+

Package commands

+
+
transfer::connect objectName ?options...?
+

This command creates a new connection object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::connect command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. +This is safe to do for an active object when a connection has +been started, as the completion callback is synchronous. +For a passive object currently waiting for its partner to +establish the connection however this is not safe and will cause +errors later on, when the connection setup completes and tries to +access the now missing data structures of the destroyed object.

+
objectName connect command
+

This method starts the connection setup per the configuration of the +object. When the connection is established the callback command +will be invoked with one additional argument, the channel handle of +the socket over which data can be transfered.

+

The detailed behaviour of the method depends on the configured +mode.

+
+
active
+

The connection setup is done synchronously. The object waits until the +connection is established. The method returns the empty string as its +result.

+
passive
+

The connection setup is done asynchronously. The method returns +immediately after a listening socket has been set up. The connection +will be established in the background. +The method returns the port number of the listening socket, for use by +the caller. One important use is the transfer of this information to +the counterpart so that it knows where it has to connect to.

+

This is necessary as the object might have been configured for port +0, allowing the operating system to choose the actual port it +will listen on.

+

The listening port is closed immediately when the connection was +established by the partner, to keep the time interval small within +which a third party can connect to the port too. +Even so it is recommended to use additional measures in the protocol +outside of the connect and transfer object to ensure that a connection +is not used with an unidentified/unauthorized partner +One possibility for this is the use of SSL/TLS. +See the option -socketcmd and section +Secure connections for information on how to do this.

+
+
+
+

Options

+

Connection objects support the set of options listed below.

+
+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::connect C -socketcmd tls::socket ...
+    ...
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/copyops.html Index: embedded/www/tcllib/files/modules/transfer/copyops.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/copyops.html +++ embedded/www/tcllib/files/modules/transfer/copyops.html @@ -0,0 +1,248 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::copy(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::copy - Data transfer foundation

+
+ + +

Description

+

This package provides a number of commands for the asynchronous of +information contained in either a string or channel. The main point of +this package is that the commands here provide a nicer callback API +than the builtin command fcopy, making the use of these +facilities simpler than the builtin.

+
+

API

+
+
transfer::copy::do chan|string data outchannel ?options...?
+

This command transfers the information in data to the +outchannel, according to the options. The type of the +information in data is determined by the first argument.

+

The options available to this command are the same as are available to +the command transfer::copy::options, and explained there.

+
+
chan
+

The argument data contains the handle of a channel and the +actual infomration to transfer is read from that channel.

+
string
+

The argument data contains a string and this is the information +to be transfered.

+
+
transfer::copy::chan channel outchannel ?options...?
+

This command is a shorter and more direct form for the command +transfer::copy::do chan.

+
transfer::copy::string string outchannel ?options...?
+

This command is a shorter and more direct form for the command +transfer::copy::do string.

+
transfer::copy::doChan channel outchannel optvar
+

This command is an alternate form of transfer::copy::chan which +reads its options out of the array variable named by optvar +instead of from a variable length argument list.

+
transfer::copy::doString string outchannel optvar
+

This command is an alternate form of transfer::copy::string which +reads its options out of the array variable named by optvar +instead of from a variable length argument list.

+
transfer::copy::options outchannel optionlist optvar
+

This command is the option processor used by all the commands above +which read their options from a variable length argument list. It +first reads default settings from the channel handle outchannel, +then processes the list of options in optionlist, at last stores +the results in the array variable named by optvar. The contents +of that variable are in a format which is directly understood by all +the commands above which read their options out of an array variable.

+

The recognized options are:

+
+
-blocksize int
+

This option specifies the size of the chunks to transfer in one +operation. It is optional and defaults to the value of +-buffersize as configured for the output channel.

+

If specified its value has to be an integer number greater than zero.

+
-command commandprefix
+

This option specifies the completion callback of the operation. This +option has to be specified. An error will be thrown if it is not, or +if the empty list was specified as argument to it.

+

Its value has to be a command prefix, i.e. a list whose first word is +the command to execute, followed by words containing fixed +arguments. When the callback is invoked one or two additional +arguments are appended to the prefix. The first argument is the number +of bytes which were transfered. The optional second argument is an +error message and added if and only if an error occured during the the +transfer.

+
-progress commandprefix
+

This option specifies the progress callback of the operation. It is +optional and defaults to the empty list. This last possibility signals +that no feedback was asked for and disabled it.

+

Its value has to be a command prefix, see above, -command for +a more detailed explanation. When the callback is invoked a single +additional arguments is appended to the prefix. This argument is the +number of bytes which were transfered so far.

+
-size int
+

This option specifies the number of bytes to read from the input data +and transfer. It is optional and defaults to "Transfer everything". +Its value has to be an integer number and any value less than zero has +the same meaning, i.e. to transfer all available data. Any other value +is the amount of bytes to transfer.

+

All transfer commands will throw error an when their user tries to +transfer more data than is available in the input. This happens +immediately, before the transfer is actually started, should the input +be a string. Otherwise the, i.e. for a channel as input, the error is +thrown the moment the underflow condition is actually detected.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure and provide the settings for the output channel which +are to be active during the transfer, and only then. I.e. the settings +of the output channel before the transfer are saved, and restored at +the end of a transfer, regardless of its success or failure. None of +these options are required, and they default to the settings of the +output channel if not specified.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/ddest.html Index: embedded/www/tcllib/files/modules/transfer/ddest.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/ddest.html +++ embedded/www/tcllib/files/modules/transfer/ddest.html @@ -0,0 +1,248 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::data::destination(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::data::destination - Data destination

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::data::destination ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects mainly describing the destination of a +data transfer. They are also able to initiate the reception of +information from a channel into the described destination.

+
+

API

+
+
transfer::data::destination objectName ?options...?
+

This command creates a new data destination object with an associated +Tcl command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+

Object command

+

All objects created by the ::transfer::data::destination command +have the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while the object is busy +with the reception of information from a channel will cause errors +later on, when the reception completes and tries to access the now +missing data structures of the destroyed object.

+
objectName put chunk
+

The main receptor method. Saves the received chunk of data into +the configured destination. It has to be called for each piece of data +received.

+
objectName done
+

The secondary receptor method. Finalizes the receiver. It has to be +called when the receiving channel signals EOF. Afterward neither +itself nor method put can be called anymore.

+
objectName valid msgvar
+

This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is True if the +object is valid, and False otherwise. In the latter case the +variable whose name is stored in msgvar is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched.

+
objectName receive channel done
+

This method initiates the reception of data from the specified +channel. The received data will be stored into the configured +destination, via calls to the methods put and done. +When the reception completes the command prefix done is invoked, +with the number of received characters appended to it as the sole +additional argument.

+
+
+

Options

+

All data destinations support the options listed below. It should be +noted that all are semi-exclusive, each specifying a different type of +destination and associated information. If these options are specified +more than once then the last option specified is used to actually +configure the object.

+
+
-channel handle
+

This option specifies that the destination of the data is a channel, +and its associated argument is the handle of the channel to write the +received data to.

+
-file path
+

This option specifies that the destination of the data is a file, and +its associated argument is the path of the file to write the received +data to.

+
-variable varname
+

This option specifies that the destination of the data is a variable, +and its associated argument contains the name of the variable to write +the received data to. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes received, allowing the user to monitor the progress of +the reception of the data. The callback is always invoked with one +additional argument, the number of bytes received so far.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/dsource.html Index: embedded/www/tcllib/files/modules/transfer/dsource.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/dsource.html +++ embedded/www/tcllib/files/modules/transfer/dsource.html @@ -0,0 +1,280 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::data::source(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::data::source - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::data::source ?0.2?
    • +
+ +
+
+

Description

+

This package provides objects mainly describing the origin of some +data to transfer. They are also able to initiate transfers of the +described information to a channel using the foundation package +transfer::copy.

+
+

API

+

Package commands

+
+
transfer::data::source objectName ?options...?
+

This command creates a new data source object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::data::source command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a transfer initiated +by the object is active is safe as all data required for the transfer +itself was copied, and the completion of the transfer will not try to +access the initiating object anymore. i.e. the transfer is completely +separate from the source object itself.

+
objectName type
+

This method returns a string describing the type of the data the +object is refering to. The possible values and their meanings are:

+
+
undefined
+

No data was specified at all, or it was specified incompletely. The +object does not know the type.

+
string
+

The data to transfer is contained in a string.

+
channel
+

The data to transfer is contained in a channel.

+
+
objectName data
+

This method returns a value depending on the type of the data the +object refers to, through which the data can be accessed. +The method throws an error if the type is undefined. For type +string the returned result is the data itself, whereas for +type channel the returned result is the handle of the channel +containing the data.

+
objectName size
+

This method returns a value depending on the type of the data the +object refers to, the size of the data. +The method throws an error if the type is undefined. Return of +a negative value signals that the object is unable to determine an +absolute size upfront (like for data in a channel).

+
objectName valid msgvar
+

This method checks the configuration of the object for validity. It +returns a boolean flag as result, whose value is True if the +object is valid, and False otherwise. In the latter case the +variable whose name is stored in msgvar is set to an error +message describing the problem found with the configuration. Otherwise +this variable is not touched.

+
objectName transmit channel blocksize done
+

This method initiates a transfer of the referenced data to the +specified channel. +When the transfer completes the command prefix done is invoked, +per the rules for the option -command of command +transfer::copy::do in the package transfer::copy. +The blocksize specifies the size of the chunks to transfer in +one go. See the option -blocksize of command +transfer::copy::do in the package transfer::copy.

+
+
+

Options

+

All data sources support the options listed below. It should be noted +that the first four options are semi-exclusive, each specifying a +different type of data source and associated content. If these options +are specified more than once then the last option specified is used to +actually configure the object.

+
+
-string text
+

This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question.

+
-channel handle
+

This option specifies that the source of the data is a channel, and +its associated argument is the handle of the channel containing the +data.

+
-file path
+

This option specifies that the source of the data is a file, and its +associated argument is the path of the file containing the data.

+
-variable varname
+

This option specifies that the source of the data is a string stored +in a variable, and its associated argument contains the name of the +variable in question. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-size int
+

This option specifies the size of the data transfer. It is optional +and defaults to -1. This value, and any other value less than zero +signals to transfer all the data from the source.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes transmitted, allowing the user to monitor the progress +of the transmission of the data. The callback is always invoked with +one additional argument, the number of bytes transmitted so far.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/receiver.html Index: embedded/www/tcllib/files/modules/transfer/receiver.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/receiver.html +++ embedded/www/tcllib/files/modules/transfer/receiver.html @@ -0,0 +1,371 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::receiver(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::receiver - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::data::destination ?0.2?
    • +
  • package require transfer::connect ?0.2?
    • +
  • package require transfer::receiver ?0.2?
    • +
+ +
+
+

Description

+

This package pulls data destinations and connection setup together +into a combined object for the reception of information coming in over +a socket. +These objects understand all the options from objects created by the +packages transfer::data::destination and +transfer::connect.

+
+

API

+

Package commands

+
+
transfer::receiver object ?options...?
+

This command creates a new receiver object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
transfer::receiver stream channel chan host port ?arg...?
+

This method creates a fire-and-forget transfer for the data coming +from the source at host/port (details below) and writing to the +channel chan, starting at the current seek location. The channel +is configured to use binary translation and encoding for the transfer. +The channel is not closed when the transfer has completed. This +is left to the completion callback.

+

If both host and port are provided an active +connection to the data source is made. If only a port is +specified (with host the empty string) then a passive +connection is made instead, i.e. the receiver then waits for a +conneciton by the transmitter.

+

Any arguments after the port are treated as options and are used to +configure the internal receiver object. +See the section Options for a list of the supported options +and their meaning. +Note however that the signature of the command prefix specified +for the -command callback differs from the signature for the +same option of the receiver object. +This callback is only given the number of bytes and transfered, and +possibly an error message. No reference to the internally used +receiver object is made.

+

The result returned by the command is the empty string +if it was set to make an active connection, and the port the +internal receiver object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
transfer::receiver stream file path host port ?arg...?
+

This method is like stream channel, except that the +received data is written to the file path, replacing any prior +content.

+
+
+

Object command

+

All objects created by the ::transfer::receiver command have the +following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a reception is on +progress will cause errors later on, when the reception completes +and tries to access the now missing data structures of the destroyed +object.

+
objectName start
+

This method initiates the data reception, setting up the connection +first and then copying the received information into the +destination. +The method will throw an error if a reception is already/still in +progress. +I.e. it is not possible to run two receptions in parallel, only in +sequence. +Errors will also be thrown if the configuration of the data +destination is invalid, or if no completion callback was specified.

+

The result returned by the method is the empty string +for an object configured to make an active connection, and the port the + object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
objectName busy
+

This method returns a boolean value telling us whether a reception +is in progress (True), or not (False).

+
+
+

Options

+

All receiver objects support the union of the options supported by +their connect and data destination components, plus one of their own. +See also the documentation for the packages +transfer::data::destination and transfer::connect.

+
+ +
-command cmdprefix
+

This option specifies the command to invoke when the reception of +the information has been completed. +The arguments given to this command are the same as given to the +completion callback of the command transfer::copy::do provided +by the package transfer::copy.

+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
-channel handle
+

This option specifies that the destination of the data is a channel, +and its associated argument is the handle of the channel to write the +received data to.

+
-file path
+

This option specifies that the destination of the data is a file, and +its associated argument is the path of the file to write the received +data to.

+
-variable varname
+

This option specifies that the destination of the data is a variable, +and its associated argument contains the name of the variable to write +the received data to. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes received, allowing the user to monitor the progress of +the reception of the data. The callback is always invoked with one +additional argument, the number of bytes received so far.

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::receiver R -socketcmd tls::socket ...
+    ...
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/tqueue.html Index: embedded/www/tcllib/files/modules/transfer/tqueue.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/tqueue.html +++ embedded/www/tcllib/files/modules/transfer/tqueue.html @@ -0,0 +1,269 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::copy::queue(n) 0.1 tcllib "Data transfer facilities"

+

Name

+

transfer::copy::queue - Queued transfers

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require struct::queue ?1.4?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::copy::queue ?0.1?
    • +
+ +
+
+

Description

+

This package provides objects which serialize transfer requests for a +single channel by means of a fifo queue. Accumulated requests are +executed in order of entrance, with the first request reaching an idle +object starting the execution in general. New requests can be added +while the object is active and are defered until all requests entered +before them have been completed successfully.

+

When a request causes a transfer error execution stops and all +requests coming after it are not served. Currently this means that +their completion callbacks are never triggered at all.

+

NOTE: + Not triggering the completion callbacks of the unserved + requests after an error stops the queue object is something I + am not fully sure that it makes sense. It forces the user of + the queue to remember the callbacks as well and run + them. Because otherwise everything in the system which depends + on getting a notification about the status of a request will + hang in the air. I am slowly convincing myself that it is more + sensible to trigger the relevant completion callbacks with an + error message about the queue abort, and 0 bytes transfered.

+

All transfer requests are of the form

+
+	{type data options...}
+
+

where type is in {chan, string}, and data +specifies the information to transfer. +For chan the data is the handle of the channel containing the +actual information to transfer, whereas for string data +contains directly the information to transfer. +The options are a list of them and their values, and are the +same as are accepted by the low-level copy operations of the package +transfer::copy. +Note how just prepending the request with transfer::copy::do and +inserting a channel handle in between data and options +easily transforms it from a pure data structure into a command whose +evaluation will perform the request.

+
+

API

+

Package commands

+
+
transfer::copy::queue objectName outchannel ?options...?
+

This command creates a new queue object for the management of the +channel outchannel, with an associated Tcl command whose name is +objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
+
+

Object command

+

All objects created by the ::transfer::copy::queue command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while the object is busy +will cause errors later on, when the currently executed request +completes and tries to access the now missing data structures of the +destroyed object.

+
objectName busy
+

This method returns a boolean value telling us if the object is +currently serving a request (i.e. busy, value True), or +not (i.e. idle, value False).

+
objectName pending
+

This method returns the number of requests currently waiting in the +queue for their execution. A request currently served is not counted +as waiting.

+
objectName put request
+

This method enters the transfer request into the object's queue +of waiting requests. +If the object is idle it will become busy, immediately +servicing the request. Otherwise servicing the new request will be +defered until all preceding requests have been served.

+
+
+
+

Options

+

The only option known is -on-status-change. It is optional +and defaults to the empty list, disabling the reporting of status +changes. Otherwise its argument is a command prefix which is invoked +whenever the internal status of the object changed. The callback is +invoked with two additional arguments, the result of the methods +pending and busy, in this order. This allows any +user to easily know, for example, when the object has processed all +outstanding requests.

+
+

Use

+

A possible application of this package and class is within a HTTP 1.1 +server, managing the results waiting for transfer to the client.

+

It should be noted that in this application the system also needs an +additional data structure which keeps track of outstanding results as +they may come back in a different order than the requests from the +client, and releases them to the actual queue in the proper order.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/transfer/transmitter.html Index: embedded/www/tcllib/files/modules/transfer/transmitter.html ================================================================== --- embedded/www/tcllib/files/modules/transfer/transmitter.html +++ embedded/www/tcllib/files/modules/transfer/transmitter.html @@ -0,0 +1,376 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

transfer::transmitter(n) 0.2 tcllib "Data transfer facilities"

+

Name

+

transfer::transmitter - Data source

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require snit ?1.0?
    • +
  • package require transfer::copy ?0.2?
    • +
  • package require transfer::data::source ?0.2?
    • +
  • package require transfer::connect ?0.2?
    • +
  • package require transfer::transmitter ?0.2?
    • +
+ +
+
+

Description

+

This package pulls data sources and connection setup together into a +combined object for the transmission of information over a socket. +These objects understand all the options from objects created +by the packages transfer::data::source and +transfer::connect.

+
+

API

+

Package commands

+
+
transfer::transmitter objectName ?options...?
+

This command creates a new transmitter object with an associated Tcl +command whose name is objectName. +This object command is explained in full detail in the sections +Object command and Object methods. The set of +supported options is explained in section Options.

+

The object command will be created under the current namespace if the +objectName is not fully qualified, and in the specified +namespace otherwise. +The fully qualified name of the object command is returned as the +result of the command.

+
transfer::transmitter stream channel chan host port ?arg...?
+

This method creates a fire-and-forget transfer for the data contained +in the channel chan, starting at the current seek location. The +channel is configured to use binary translation and encoding for the +transfer. +The channel is automatically closed when the transfer has completed.

+

If both host and port are provided an active +connection to the destination is made. If only a port is +specified (with host the empty string) then a passive +connection is made instead.

+

Any arguments after the port are treated as options and are used to +configure the internal transmitter object. +See the section Options for a list of the supported options +and their meaning. +Note however that the signature of the command prefix specified +for the -command callback differs from the signature for the +same option of the transmitter object. +This callback is only given the number of bytes and transfered, and +possibly an error message. No reference to the internally used +transmitter object is made.

+

The result returned by the command is the empty string +if it was set to make an active connection, and the port the +internal transmitter object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
transfer::transmitter stream file path host port ?arg...?
+

This method is like stream channel, except that the data +contained in the file path is transfered.

+
+
+

Object command

+

All objects created by the ::transfer::transmitter command have +the following general form:

+
+
objectName method ?arg arg ...?
+

The method method and its arg'uments determine the +exact behavior of the command. +See section Object methods for the detailed +specifications.

+
+
+

Object methods

+
+
objectName destroy
+

This method destroys the object. Doing so while a transmission is in +progress will cause errors later on, when the transmission completes +and tries to access the now missing data structures of the destroyed +object.

+
objectName start
+

This method initiates the data transmission, setting up the connection +first and then copying the information. +The method will throw an error if a transmission is already/still in +progress. +I.e. it is not possible to run two transmissions in parallel on a +single object, only in sequence. Multiple transmitter objects are +needed to manage parallel transfers, one per transmission. +Errors will also be thrown if the configuration of the data source is +invalid, or if no completion callback was specified.

+

The result returned by the method is the empty string +for an object configured to make an active connection, and the port the + object is listening on otherwise, i.e when it is +configured to connect passively. +See also the package transfer::connect and the description +of the method connect for where this behaviour comes from.

+
objectName busy
+

This method returns a boolean value telling us whether a transmission +is in progress (True), or not (False).

+
+
+

Options

+

All transmitter objects support the union of the options supported +by their connect and data source components, plus two of their own. +See also the documentation for the packages +transfer::data::source and transfer::connect.

+
+
-blocksize int
+

This option specifies the size of the chunks to be transmitted in one +block. Usage is optional, its default value is 1024.

+
-command cmdprefix
+

This option specifies the command to invoke when the transmission of +the information has been completed. +The arguments given to this command are the same as given to the +completion callback of the command transfer::copy::do provided +by the package transfer::copy.

+
-mode mode
+

This option specifies the mode the object is in. It is optional and +defaults to active mode. The two possible modes are:

+
+
active
+

In this mode the two options -host and -port are +relevant and specify the host and TCP port the object has to connect +to. The host is given by either name or IP address.

+
passive
+

In this mode the option -host has no relevance and is ignored +should it be configured. +The only option the object needs is -port, and it specifies +the TCP port on which the listening socket is opened to await the +connection from the partner.

+
+
-host hostname-or-ipaddr
+

This option specifies the host to connect to in active mode, +either by name or ip-address. An object configured for passive +mode ignores this option.

+
-port int
+

For active mode this option specifies the port the object is +expected to connect to. For passive mode however it is the port +where the object creates the listening socket waiting for a +connection. It defaults to 0, which allows the OS to choose +the actual port to listen on.

+
-socketcmd command
+

This option allows the user to specify which command to use to open a +socket. The default is to use the builtin ::socket. Any +compatible with that command is allowed.

+

The envisioned main use is the specfication of tls::socket. I.e. +this option allows the creation of secure transfer channels, without +making this package explicitly dependent on the tls package.

+

See also section Secure connections.

+
-encoding encodingname
+
+
-eofchar eofspec
+
+
-translation transspec
+

These options are the same as are recognized by the builtin command +fconfigure. They provide the configuration to be set for the +channel between the two partners after it has been established, but +before the callback is invoked (See method connect).

+
-string text
+

This option specifies that the source of the data is an immediate +string, and its associated argument contains the string in question.

+
-channel handle
+

This option specifies that the source of the data is a channel, and +its associated argument is the handle of the channel containing the +data.

+
-file path
+

This option specifies that the source of the data is a file, and its +associated argument is the path of the file containing the data.

+
-variable varname
+

This option specifies that the source of the data is a string stored +in a variable, and its associated argument contains the name of the +variable in question. The variable is assumed to be global or +namespaced, anchored at the global namespace.

+
-size int
+

This option specifies the size of the data transfer. It is optional +and defaults to -1. This value, and any other value less than zero +signals to transfer all the data from the source.

+
-progress command
+

This option, if specified, defines a command to be invoked for each +chunk of bytes transmitted, allowing the user to monitor the progress +of the transmission of the data. The callback is always invoked with +one additional argument, the number of bytes transmitted so far.

+
+
+
+

Secure connections

+

One way to secure connections made by objects of this package is to +require the package tls and then configure the option +-socketcmd to force the use of command tls::socket to +open the socket.

+
+    # Load and initialize tls
+    package require tls
+    tls::init -cafile /path/to/ca/cert -keyfile ...
+    # Create a connector with secure socket setup,
+    transfer::transmitter T -socketcmd tls::socket ...
+    ...
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category transfer of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Transfer module

+
+ +
ADDED embedded/www/tcllib/files/modules/treeql/treeql.html Index: embedded/www/tcllib/files/modules/treeql/treeql.html ================================================================== --- embedded/www/tcllib/files/modules/treeql/treeql.html +++ embedded/www/tcllib/files/modules/treeql/treeql.html @@ -0,0 +1,648 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

treeql(n) 1.3.1 tcllib "Tree Query Language"

+

Name

+

treeql - Query tree objects

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require snit
    • +
  • package require struct::list
    • +
  • package require struct::set
    • +
  • package require treeql ?1.3.1?
    • +
+ +
+
+

Description

+

This package provides objects which can be used to query and transform +tree objects following the API of tree objects created by the package +struct::tree.

+

The tree query and manipulation language used here, TreeQL, is +inspired by Cost (See section References for more +information).

+

treeql, the package, is a fairly thin query facility over +tree-structured data types. It implements an ordered set of nodes +(really a list) which are generated and filtered through the +application of TreeQL operators to each node in turn.

+
+

API

+

TreeQL CLASS API

+

The command treeql is a snit::type which implements +the Treeql Query Language. This means that it follows the API for +class commands as specified by the package snit. +Its general syntax is

+
+
treeql objectname -tree tree ?-query query? ?-nodes nodes? ?args...?
+

The command creates a new tree query object and returns the fully +qualified name of the object command as its result. +The API the returned command is following is described in the section +TreeQL OBJECT API

+

Each query object is associated with a single tree object. This +is the object all queries will be run against.

+

If the option -nodes was specified then its argument is +treated as a list of nodes. This list is used to initialize the node +set. It defaults to the empty list.

+

If the option -query was specified then its argument will be +interpreted as an object, the parent query of this query. It +defaults to the object itself. All queries will be interpreted in the +environment of this object.

+

Any arguments coming after the options are treated as a query and run +immediately, after the node set has been initialized. This +uses the same syntax for the query as the method query.

+

The operations of the TreeQL available for this are explained in the +section about The Tree Query Language. This section also +explains the term node set used above.

+
+
+

TreeQL OBJECT API

+

As treeql has been implemented in snit all the +standard methods of snit-based classes are available to the +user and therefore not listed here. Please read the documentation for +snit for what they are and what functionality they provide

+

The methods provided by the package treeql itself are listed +and explained below.

+
+
qo query args...
+

This method interprets its arguments as a series of TreeQL operators +and interpretes them from the left to right (i.e. first to last). +Note that the first operator uses the node set currently +known to the object to perform its actions. +In other words, the node set is not cleared, or +modified in other ways, before the query is run. This allows the user +to run several queries one after the other and have each use the +results of the last. Any initialization has to be done by any query +itself, using TreeQL operators. +The result of the method is the node set after the last +operator of the query has been executed.

+

Note that uncaught errors will leave the node set of +the object in an intermediate state, per the TreeQL operators which +were executed successfully before the error occurred.

+

The above means in detail that:

+
    +

  1. The first argument is interpreted as the name of a query operator, the +number of arguments required by that operator is then determined, and +taken from the immediately following arguments.

    +

    Because of this operators cannot have optional arguments, all +arguments have to be present as defined. Failure to do this will, at +least, confuse the query interpreter, but more likely cause errors.

    2. +

  2. The operator is applied to the current node set, yielding a new node +set, and/or manipulating the tree object the query object is connected +to.

    3. +

  3. The arguments used (i.e. operator name and arguments) are removed from +the list of method arguments, and then the whole process is repeated +from step [1], until the list of arguments is empty or an error +occurred.

    4. +
+
+    # q is the query object.
+    q query root children get data
+    # The above query
+    # - Resets the node set to the root node - root
+    # - Adds the children of root to the set - children
+    # - Replaces the node set with the       - get data
+    #   values for the attribute 'data',
+    #   for all nodes in the set which
+    #   have such an attribute.
+    # - And returns this information.
+    # Below we can see the same query, but rewritten
+    # to show the structure as it is seen by the query
+    # interpreter.
+    q query \\
+	    root \\
+	    children \\
+	    get data
+
+

The operators of the TreeQL language available for this are explained +in the section about The Tree Query Language. This section +also explains the term node set used above.

+
qo result
+

This method returns a list containing the current node set.

+
qo discard
+

This method returns the current node set (like method +result), but also destroys the query object (qo). +This is useful when constructing and using sub-queries (%AUTO% objects +immediately destroyed after use).

+
+
+
+

The Tree Query Language

+

This and the following sections specify the Tree Query Language used +by the query objects of this package in detail.

+

First we explain the general concepts underneath the language which +are required to comprehend it. This is followed by the specifications +for all the available query operators. They fall into eight +categories, and each category has its own section.

+
    +

  1. TreeQL Concepts

    2. +

  2. Structural generators

    3. +

  3. Attribute Filters

    4. +

  4. Attribute Mutators

    5. +

  5. Attribute String Accessors

    6. +

  6. Sub-queries

    7. +

  7. Node Set Operators

    8. +

  8. Node Set Iterators

    9. +

  9. Typed node support

    10. +
+

TreeQL Concepts

+

The main concept which has to be understood is that of the +node set. +Each query object maintains exactly one such node set, and +essentially all operators use it and input argument and for their +result. +This structure simply contains the handles of all nodes which are +currently of interest to the query object. +To name it a set is a bit of a misnomer, because

+
    +

  1. A node (handle) can occur in the structure more than once, and

    2. +

  2. the order of nodes in the structure is important as well. +Whenever an operator processes all nodes in the node set it will do so +in the order they occur in the structure.

    3. +
+

Regarding the possible multiple occurrence of a node, consider a node +set containing two nodes A and B, both having node P as their +immediate parent. Application of the TreeQL operator "parent" will +then add P to the new node set twice, once per node it was parent +of. I.e. the new node set will then be {P P}.

+
+

Structural generators

+

All tree-structural operators locate nodes in the tree based on a +structural relation ship to the nodes currently in the set and then +replace the current node set with the set of nodes found +Nodes which fulfill such a relationship multiple times are added to +the result as often as they fulfill the relationship.

+

It is important to note that the found nodes are collected in a +separate storage area while processing the node set, and are added to +(or replacing) the current node set only after the current node set +has been processed completely. +In other words, the new nodes are not processed by the operator +as well and do not affect the iteration.

+

When describing an operator the variable N will be used to refer +to any node in the node set.

+
+
ancestors
+

Replaces the current node set with the ancestors for all nodes N +in the node set, should N have a parent. In other words, nodes +without a parent do not contribute to the new node set. In other +words, uses all nodes on the path from node N to root, in this +order (root last), for all nodes N in the node set. This +includes the root, but not the node itself.

+
rootpath
+

Replaces the current node set with the ancestors for all nodes N +in the node set, should N have a parent. In other words, nodes +without a parent do not contribute to the new node set. +In contrast to the operator ancestors the nodes are added in +reverse order however, i.e. the root node first.

+
parent
+

Replaces the current node set with the parent of node N, for all +nodes N in the node set, should N have a parent. In other +words, nodes without a parent do not contribute to the new node set.

+
children
+

Replaces the current node set with the immediate children of node +N, for all nodes N in the node set, should N have +children. In other words, nodes without children do not contribute to +the new node set.

+
left
+

Replaces the current node set with the previous/left sibling for all +nodes N in the node set, should N have siblings to the +left. In other words, nodes without left siblings do not contribute to +the new node set.

+
right
+

Replaces the current node set with the next/right sibling for all +nodes N in the node set, should N have siblings to the +right. In other words, nodes without right siblings do not contribute +to the new node set.

+
prev
+

Replaces the current node set with all previous/left siblings of node +N, for all nodes N in the node set, should N have +siblings to the left. In other words, nodes without left siblings are +ignored. The left sibling adjacent to the node is added first, and the +leftmost sibling last (reverse tree order).

+
esib
+

Replaces the current node set with all previous/left siblings of node +N, for all nodes N in the node set, should N have +siblings to the left. In other words, nodes without left siblings are +ignored. The leftmost sibling is added first, and the left sibling +adjacent to the node last (tree order).

+

The method name is a shorthand for Earlier SIBling.

+
next
+

Replaces the current node set with all next/right siblings of node +N, for all nodes N in the node set, should N have +siblings to the right. In other words, nodes without right siblings do +not contribute to the new node set. The right sibling adjacent to the +node is added first, and the rightmost sibling last (tree order).

+
root
+

Replaces the current node set with a node set containing a single +node, the root of the tree.

+
tree
+

Replaces the current node set with a node set containing all nodes +found in the tree. The nodes are added in pre-order (parent first, +then children, the latter from left to right, first to last).

+
descendants
+

Replaces the current node set with the nodes in all subtrees rooted at +node N, for all nodes N in the node set, should N +have children. In other words, nodes without children do not +contribute to the new node set.

+

This is like the operator children, but covers the children +of children as well, i.e. all the proper descendants. "Rooted +at N" means that N itself is not added to the new set, +which is also implied by proper descendants.

+
subtree
+

Like operator descendants, but includes the node N. In +other words:

+

Replaces the current node set with the nodes of the subtree of node +N, for all nodes N in the node set, should N have +children. In other words, nodes without children do not contribute to +the new node set. I.e this is like the operator children, but +covers the children of children, etc. as well. "Of N" means that +N itself is added to the new set.

+
forward
+

Replaces the current node set with the nodes in the subtrees rooted at +the right siblings of node N, for all nodes N in the node +set, should N have right siblings, and they children. In other +words, nodes without right siblings, and them without children are +ignored.

+

This is equivalent to the operator sequence

+
next descendants
+
+
later
+

This is an alias for the operator forward.

+
backward
+

Replaces the current node set with the nodes in the flattened previous +subtrees, in reverse tree order.

+

This is nearly equivalent to the operator sequence

+
prev descendants
+

The only difference is that this uses the nodes in reverse order.

+
earlier
+

Replaces the current node set with the nodes in the flattened previous +subtrees, in tree order.

+

This is equivalent to the operator sequence

+
prev subtree
+
+
+
+

Attribute Filters

+

These operators filter the node set by reference to attributes of +nodes and their properties. Filter means that all nodes not fulfilling +the criteria are removed from the node set. In other words, the node +set is replaced by the set of nodes fulfilling the filter criteria.

+
+
hasatt attr
+

Reduces the node set to nodes which have an attribute named +attr.

+
withatt attr value
+

Reduces the node set to nodes which have an attribute named +attr, and where the value of that attribute is equal to +value (The "==" operator is string equal -nocase).

+
withatt! attr val
+

This is the same as withatt, but all nodes in the node set +have to have the attribute, and the "==" operator is +string equal, i.e. no -nocase. +The operator will fail with an error if they don't have the attribute.

+
attof attr vals
+

Reduces the node set to nodes which which have an attribute named +attr and where the value of that attribute is contained in the +list vals of legal values. The contained-in operator used here +does glob matching (using the attribute value as pattern) and ignores +the case of the attribute value, but not for the elements of +vals.

+
attmatch attr match
+

Same as withatt, but string match is used as the "==" +operator, and match is the pattern checked for.

+

Note that match is a interpreted as a partial argument +list for string match. This means that it is +interpreted as a list containing the pattern, and the pattern element +can be preceded by options understand by string match, like +-nocase. +This is especially important should the pattern contain spaces. It has +to be wrapped into a list for correct interpretation by this operator

+
+
+

Attribute Mutators

+

These operators change node attributes within the underlying tree. In +other words, all these operators have side effects.

+
+
set attr val
+

Sets the attribute attr to the value val, for all nodes +N in the node set. +The operator will fail if a node does not have an attribute named +attr. The tree will be left in a partially modified state.

+
unset attr
+

Unsets the attribute attr, for all nodes N in the node +set. +The operator will fail if a node does not have an attribute named +attr. The tree will be left in a partially modified state.

+
+
+

Attribute String Accessors

+

These operators retrieve the values of node attributes from the +underlying tree. The collected results are stored in the node set, but +are not actually nodes.

+

In other words, they redefine the semantics of the node set stored by +the query object to contain non-node data after their completion.

+

The query interpreter will terminate after it has finished processing +one of these operators, silently discarding any later query elements. +It also means that our talk about maintenance of a node set is not +quite true. It is a node set while the interpreter is processing +commands, but can be left as an attribute value set at the end of +query processing.

+
+
string op attr
+

Applies the string operator op to the attribute named +attr, for all nodes N in the node set, collects the +results of that application and places them into the node set.

+

The operator will fail if a node does not have an attribute named +attr.

+

The argument op is interpreted as partial argument list for the +builtin command string. Its first word has to be any of the +sub-commands understood by string. This has to be followed by +all arguments required for the subcommand, except the last. that last +argument is supplied by the attribute value.

+
get pattern
+

For all nodes N in the node set it determines all their +attributes with names matching the glob pattern, then the values +of these attributes, at last it replaces the node set with the list of +these attribute values.

+
attlist
+

This is a convenience definition for the operator +getvals *. In other words, it replaces the node set with a +list of the attribute values for all attributes for all nodes N +in the node set.

+
attrs glob
+

Replaces the current node set with a list of attribute lists, one +attribute list per for all nodes N in the node set.

+
attval attname
+

Reduces the current node set with the operator hasatt, and +then replaces it with a list containing the values of the attribute +named attname for all nodes N in the node set.

+
+
+

Sub-queries

+

Sub-queries yield node sets which are then used to augment, reduce or +replace the current node set.

+
+
andq query
+

Replaces the node set with the set-intersection of the node set +generated by the sub-query query and itself.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
orq query
+

Replaces the node set with the set-union of the node set generated by +the sub-query query and itself. Duplicate nodes are removed.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
notq query
+

Replaces the node set with the set of nodes generated by the sub-query +query which are also not in the current node set. In other word +the set difference of itself and the node set generated by the +sub-query.

+

The execution of the sub-query uses the current node set as its own +initial node set.

+
+
+

Node Set Operators

+

These operators change the node set directly, without referring to the +tree.

+
+
unique
+

Removes duplicate nodes from the node set, preserving order. In other +words, the earliest occurrence of a node handle is preserved, every +other occurrence is removed.

+
select
+

Replaces the current node set with a node set containing only the +first node from the current node set

+
transform query var body
+

First it interprets the sub-query query, using the current node +set as its initial node set. +Then it iterates over the result of that query, binding the handle of +each node to the variable named in var, and executing the script +body. +The collected results of these executions is made the new node set, +replacing the current one.

+

The script body is executed in the context of the caller.

+
map var body
+

Iterates over the current node set, binding the handle of each node to +the variable named in var, and executing the script body. +The collected results of these executions is made the new node set, +replacing the current one.

+

The script body is executed in the context of the caller.

+
quote val
+

Appends the literal value val to the current node set.

+
replace val
+

Replaces the current node set with the literal list value val.

+
+
+

Node Set Iterators

+
+
foreach query var body
+

Interprets the sub-query query, then performs the equivalent of +operator over on the nodes in the node set created by that +query. The current node set is not changed, except through side +effects from the script body.

+

The script body is executed in the context of the caller.

+
with query body
+

Interprets the query, then runs the script body on the +node set generated by the query. At last it restores the current node +set as it was before the execution of the query.

+

The script body is executed in the context of the caller.

+
over var body
+

Executes the script body for each node in the node set, with the +variable named by var bound to the name of the current node. +The script body is executed in the context of the caller.

+

This is like the builtin foreach, with the node set as the +source of the list to iterate over.

+

The results of executing the body are ignored.

+
delete
+

Deletes all the nodes contained in the current node set from the tree.

+
+
+

Typed node support

+

These filters and accessors assume the existence of an attribute +called @type, and are short-hand forms useful for cost-like +tree query, html tree editing, and so on.

+
+
nodetype
+

Returns the node type of nodes. +Attribute string accessor. This is equivalent to

+
get @type
+
+
oftype t
+

Reduces the node set to nodes whose type is equal to t, with +letter case ignored.

+
nottype t
+

Reduces the node set to nodes whose type is not equal to t, with +letter case ignored.

+
oftypes attrs
+

Reduces set to nodes whose @type is an element in the list attrs +of types. The value of @type is used as a glob pattern, and letter +case is relevant.

+
+
+
+

Examples

+

... TODO ...

+
+

References

+
    +

  1. COST on the Tcler's Wiki.

    2. +

  2. TreeQL on the Tcler's Wiki. Discuss +this package there.

    3. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category treeql of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Data structures

+
+ +
ADDED embedded/www/tcllib/files/modules/try/tcllib_throw.html Index: embedded/www/tcllib/files/modules/try/tcllib_throw.html ================================================================== --- embedded/www/tcllib/files/modules/try/tcllib_throw.html +++ embedded/www/tcllib/files/modules/try/tcllib_throw.html @@ -0,0 +1,166 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

throw(n) 1 tcllib "Forward compatibility implementation of [throw]"

+

Name

+

throw - throw - Throw an error exception with a message

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require throw ?1?
    • +
+ +
+
+

Description

+

This package provides a forward-compatibility implementation of Tcl +8.6's throw command (TIP 329), for Tcl 8.5. The code was +directly pulled from Tcl 8.6 revision ?, when try/finally was +implemented as Tcl procedure instead of in C.

+
+
::throw error_code error_message
+

throw is merely a reordering of the arguments of the error command. It throws an error with the indicated +error code and error message.

+
+
+

EXAMPLES

+
+throw {MYERROR CODE} "My error message"
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category try of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

error(n)

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/try/tcllib_try.html Index: embedded/www/tcllib/files/modules/try/tcllib_try.html ================================================================== --- embedded/www/tcllib/files/modules/try/tcllib_try.html +++ embedded/www/tcllib/files/modules/try/tcllib_try.html @@ -0,0 +1,231 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

try(n) 1 tcllib "Forward compatibility implementation of [try]"

+

Name

+

try - try - Trap and process errors and exceptions

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require try ?1?
    • +
+ +
+
+

Description

+

This package provides a forward-compatibility implementation of Tcl +8.6's try/finally command (TIP 329), for Tcl 8.5. The code was +directly pulled from Tcl 8.6 revision ?, when try/finally was +implemented as Tcl procedure instead of in C.

+
+
::try body ?handler...? ?finally script?
+

This command executes the script body and, depending on what the +outcome of that script is (normal exit, error, or some other +exceptional result), runs a handler script to deal with the case. Once +that has all happened, if the finally clause is present, the +script it includes will be run and the result of the handler (or +the body if no handler matched) is allowed to continue to +propagate. Note that the finally clause is processed even if +an error occurs and irrespective of which, if any, handler is +used.

+

The handler clauses are each expressed as several words, +and must have one of the following forms:

+
+
on code variableList script
+

This clause matches if the evaluation of body completed with the +exception code code. The code may be expressed as an +integer or one of the following literal words: +ok, error, return, break, or +continue. Those literals correspond to the integers 0 through +4 respectively.

+
trap pattern variableList script
+

This clause matches if the evaluation of body resulted in an +error and the prefix of the -errorcode from the interpreter's +status dictionary is equal to the pattern. The number of prefix +words taken from the -errorcode is equal to the list-length +of pattern, and inter-word spaces are normalized in both the +-errorcode and pattern before comparison.

+

The variableList word in each handler is always +interpreted as a list of variable names. If the first word of the list +is present and non-empty, it names a variable into which the result of +the evaluation of body (from the main try) will be placed; +this will contain the human-readable form of any errors. If the second +word of the list is present and non-empty, it names a variable into +which the options dictionary of the interpreter at the moment of +completion of execution of body will be placed.

+

The script word of each handler is also always +interpreted the same: as a Tcl script to evaluate if the clause is +matched. If script is a literal - and the handler +is not the last one, the script of the following handler +is invoked instead (just like with the switch command).

+

Note that handler clauses are matched against in order, +and that the first matching one is always selected. +At most one handler clause will selected. +As a consequence, an on error will mask any subsequent +trap in the try. Also note that on error is +equivalent to trap {}.

+

If an exception (i.e. any non-ok result) occurs during +the evaluation of either the handler or the finally +clause, the original exception's status dictionary will be added to +the new exception's status dictionary under the -during key.

+
+
+
+

EXAMPLES

+

Ensure that a file is closed no matter what:

+
+set f [open /some/file/name a]
+try {
+    puts \$f "some message"
+    # ...
+} finally {
+    close \$f
+}
+
+

Handle different reasons for a file to not be openable for reading:

+
+try {
+    set f [open /some/file/name]
+} trap {POSIX EISDIR} {} {
+    puts "failed to open /some/file/name: it's a directory"
+} trap {POSIX ENOENT} {} {
+    puts "failed to open /some/file/name: it doesn't exist"
+}
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category try of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+

See Also

+

catch(n), error(n), return(n), throw(n)

+
+ +

Category

+

Utility

+
+ +
ADDED embedded/www/tcllib/files/modules/udpcluster/udpcluster.html Index: embedded/www/tcllib/files/modules/udpcluster/udpcluster.html ================================================================== --- embedded/www/tcllib/files/modules/udpcluster/udpcluster.html +++ embedded/www/tcllib/files/modules/udpcluster/udpcluster.html @@ -0,0 +1,175 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

udpcluster(n) 0.3 tcllib "Lightweight UDP based tool for cluster node discovery"

+

Name

+

udpcluster - UDP Peer-to-Peer cluster

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require ip
    • +
  • package require nettool
    • +
  • package require comm
    • +
  • package require interp
    • +
  • package require dicttool
    • +
  • package require cron
    • +
+
+
+

Description

+

This package is a lightweight alternative to Zeroconf. It utilizes UDP packets to +populate a table of services provided by each node on a local network. Each participant +broadcasts a key/value list in plain UTF-8 which lists what ports are open, and what +protocols are expected on those ports. Developers are free to add any additional key/value +pairs beyond those.

+

Using udpcluster.

+

For every service you wish to publish invoke:

+
+cluster::publish echo@[cluster::macid] {port 10000 protocol echo}
+
+

To query what services are available on the local network:

+
+set results [cluster::search PATTERN]
+# And inside that result...
+echo@LOCALMACID {
+   port 10000
+   protocol echo
+}
+
+

To unpublish a service:

+
+cluster::unpublish echo@[cluster::macid]
+
+

Results will +Historical Notes:

+

This tool was originally known as nns::cluster, but as development progressed, it was +clear that it wasn't interacting with any of the other facilities in NNS.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category nameserv of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+ +
ADDED embedded/www/tcllib/files/modules/uev/uevent.html Index: embedded/www/tcllib/files/modules/uev/uevent.html ================================================================== --- embedded/www/tcllib/files/modules/uev/uevent.html +++ embedded/www/tcllib/files/modules/uev/uevent.html @@ -0,0 +1,277 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uevent(n) 0.3.1 tcllib "User events"

+

Name

+

uevent - User events

+
+ + +

Description

+

This package provides a general facility for the handling of user +events. Allows the binding of arbitrary commands to arbitrary events +on arbitrary tags, removal of bindings, and event generation.

+

The main difference to the event system built into the Tcl/Tk core is +that the latter can generate only virtual events, and only for +widgets. It is not possible to use the builtin facilities to bind to +events on arbitrary (pseudo-)objects, nor is it able to generate +events for such.

+

Here we can, by assuming that each object in question is represented +by its own tag. Which is possible as we allow arbitrary tags.

+

More differences:

+
    +

  1. The package uses only a two-level hierarchy, tags and events, to +handle everything, whereas the Tcl/Tk system uses three levels, i.e. +objects, tags, and events, with a n:m relationship between objects and +tags.

    2. +

  2. This package triggers all bound commands for a tag/event combination, +and they are independent of each other. A bound command cannot force +the event processing core to abort the processing of command coming +after it.

    3. +
+
+

API

+

The package exports eight commands, as specified below. Note that when +the package is used from within Tcl 8.5+ all the higher commands are +ensembles, i.e. the :: separators can be replaceed by spaces.

+
+
::uevent::bind tag event command
+

Using this command registers the command prefix to be triggered +when the event occurs for the tag. The result of the +command is an opaque token representing the binding. Note that if the +same combination of <tag,event,command> is used +multiple times the same token is returned by every call.

+

The signature of the command prefix is

+
+
command tag event details
+
+
+

where details contains the argument(s) of the event. Its +contents are event specific and have to be agreed upon between actual +event generator and consumer. This package simply transfers the +information and does not perform any processing beyond that.

+
::uevent::unbind token
+

This command releases the event binding represented by the +token. The token has to be the result of a call to +::uevent::bind. The result of the command is the empty string.

+
::uevent::generate tag event ?details?
+

This command generates an event for the tag, triggering +all commands bound to that combination. The details argument is +simply passed unchanged to all event handlers. It is the +responsibility of the code generating and consuming the event to have +an agreement about the format and contents of the information carried +therein. The result of the command is the empty string.

+

Note that all bound commands are triggered, independently of each +other. The event handlers cannot assume a specific order. They are +also not called synchronously with the invokation of this +command, but simply put into the event queue for processing when the +system returns to the event loop.

+

Generating an event for an unknown tag, or for a +<tag,event> combination which has no commands bound to it +is allowed, such calls will be ignored.

+
::uevent::list
+

In this form the command returns a list containing the names of all +tags which have events with commands bound to them.

+
::uevent::list tag
+

In this format the command returns a list containing the names of all +events for the tag with commands bound to them. Specifying an +unknown tag, i.e. a tag without event and commands, will cause the +command to throw an error.

+
::uevent::list tag event
+

In this format the command returns a list containing all commands +bound to the event for the tag. Specifying an unknown tag +or unknown event, will cause the command to throw an error.

+
::uevent::watch::tag::add pattern command
+

This command sets up a sort of reverse events. Events generated, +i.e. the command prefix invoked, when observers bind to and +unbind from specific tags.

+

Note that the command prefix is only invoked twice per tag, +first when the first command is bound to any event of the tag, and +second when the last command bound to the tag is removed.

+

The signature of the command prefix is

+
+
{*}command bound tag
+
+
{*}command unbound tag
+
+
+

The result of the command is a token representing the watcher.

+
::uevent::watch::tag::remove token
+

This command removes a watcher for (un)bind events on tags.

+

The result of the command is the empty string.

+
::uevent::watch::event::add tag_pattern event_pattern command
+

This command sets up a sort of reverse events. Events generated, +i.e. the command prefix invoked, when observers bind to and +unbind from specific combinations of tags and events.

+

Note that the command prefix is only invoked twice per +tag/event combination, first when the first command is bound to it, +and second when the last command bound to the it is removed.

+

The signature of the command prefix is

+
+
{*}command bound tag event
+
+
{*}command unbound tag event
+
+
+

The result of the command is a token representing the watcher.

+
::uevent::watch::event::remove token
+

This command removes a watcher for (un)bind events on tag/event +combinations.

+

The result of the command is the empty string.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uevent of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/uev/uevent_onidle.html Index: embedded/www/tcllib/files/modules/uev/uevent_onidle.html ================================================================== --- embedded/www/tcllib/files/modules/uev/uevent_onidle.html +++ embedded/www/tcllib/files/modules/uev/uevent_onidle.html @@ -0,0 +1,177 @@ +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uevent::onidle(n) 0.1 tcllib "User events"

+

Name

+

uevent::onidle - Request merging and deferal to idle time

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require uevent::onidle ?0.1?
    • +
  • package require logger
    • +
+ +
+
+

Description

+

This package provides objects which can merge multiple requestes for +an action and execute the action the moment the system (event loop) +becomes idle. The action to be run is configured during object +construction.

+
+

API

+

The package exports a class, uevent::onidle, as specified +below.

+
+
::uevent::onidle objectName commandprefix
+

The command creates a new onidle object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object.

+

The commandprefix is the action to perform when the event loop +is idle and the user asked for it using the method request +(See below).

+
+

The object commands created by the class commands above have +the form:

+
+
objectName request
+

This method requests the execution of the command prefix specified +during the construction of objectName the next time the event +loop is idle. Multiple requests are merged and cause only one +execution of the command prefix.

+
+
+

Examples

+

Examples of this type of deferal are buried in the (C-level) +implementations all the Tk widgets, defering geometry calculations and +window redraw activity in this manner.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uevent of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/units/units.html Index: embedded/www/tcllib/files/modules/units/units.html ================================================================== --- embedded/www/tcllib/files/modules/units/units.html +++ embedded/www/tcllib/files/modules/units/units.html @@ -0,0 +1,469 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

units(n) 1.2 tcllib "Convert and manipulate quantities with units"

+

Name

+

units - unit conversion

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.1
    • +
  • package require units ?2.1?
    • +
+ +
+
+

Description

+

This library provides a conversion facility from a variety of +scientific and engineering shorthand notations into floating point +numbers. This allows application developers to easily convert +values with different units into uniformly scaled numbers.

+

The units conversion facility is also able to convert between +compatible units. If, for example, a application is expecting a value +in ohms (Resistance), and the user specifies units of +milliwebers/femtocoulomb, the conversion routine will +handle it appropriately. An error will be generated if an incorrect +conversion is attempted.

+

Values are scaled from one set of units to another by dimensional +analysis. Both the value units and the target units are reduced into +primitive units and a scale factor. Units are checked for +compatibility, and the scale factors are applied by multiplication and +division. This technique is extremely flexible and quite robust.

+

New units and new unit abbreviations can be defined in terms of +existing units and abbreviations. It is also possible to define a new +primitive unit, although that will probably be unnecessary. New units +will most commonly be defined to accommodate non-SI measurement +systems, such as defining the unit inch as 2.54 cm.

+
+

COMMANDS

+
+
::units::convert value targetUnits
+

Converts the value string into a floating point number, scaled to the +specified targetUnits. The value string may contain a +number and units. If units are specified, then they must be +compatible with the targetUnits. If units are not specified +for the value, then it will be scaled to the target units. For +example,

+
+% ::units::convert "2.3 miles" km
+3.7014912
+% ::units::convert 300m/s miles/hour
+671.080887616
+% ::units::convert "1.0 m kg/s^2" newton
+1.0
+% ::units::convert 1.0 millimeter
+1000.0
+
+
+
::units::reduce unitString
+

Returns a unit string consisting of a scale factor followed by a space +separated list of sorted and reduced primitive units. The reduced +unit string may include a forward-slash (separated from the +surrounding primitive subunits by spaces) indicating that the +remaining subunits are in the denominator. Generates an error if the +unitString is invalid.

+
+% ::units::reduce pascal
+1000.0 gram / meter second second
+
+
+
::units::new name baseUnits
+

Creates a new unit conversion with the specified name. The new unit +name must be only alphabetic (upper or lower case) letters. +The baseUnits string can consist of any valid units conversion +string, including constant factors, numerator and denominator parts, +units with prefixes, and exponents. The baseUnits may contain any +number of subunits, but it must reduce to primitive units. BaseUnits +could also be the string -primitive to represent a new +kind of quantity which cannot be derived from other units. But you +probably would not do that unless you have discovered some kind of new +universal property.

+
+% ::units::new furlong "220 yards"
+% ::units::new fortnight "14 days"
+% ::units::convert 100m/s furlongs/fortnight
+601288.475303
+
+
+
+
+

UNIT STRING FORMAT

+

Value and unit string format is quite flexible. It is possible to +define virtually any combination of units, prefixes, and powers. +Valid unit strings must conform to these rules.

+
    +

  • A unit string consists of an optional scale factor followed by zero or +more subunits. The scale factor must be a valid floating point +number, and may or may not be separated from the subunits. The scale +factor could be negative.

    • +

  • Subunits are separated form each other by one or more separator +characters, which are space (" "), hyphen ("-"), asterisk ("*"), and +forward-slash ("/"). Sure, go ahead and complain about using a minus +sign ("-") to represent multiplication. It just isn't sound +mathematics, and, by rights, we should require everyone to use the +asterisk ("*") to separate all units. But the bottom line is that +complex unit strings like m-kg/s^2 are pleasantly +readable.

    • +

  • The forward-slash seperator ("/") indicates that following subunits are +in the denominator. There can be at most one forward-slash separator.

    • +

  • Subunits can be floating point scale factors, but with the exception +of the leading scale factor, they must be surrounded by valid +separators. Subunit scale factors cannot be negative. (Remember that +the hyphen is a unit separator.)

    • +

  • Subunits can be valid units or abbreviations. They may include a +prefix. They may include a plural suffix "s" or "es". They may also +include a power string denoted by a circumflex ("^"), followed by a +integer, after the unit name (or plural suffix, if there is one). +Negative exponents are not allowed. (Remember that the hyphen is a +unit separator.)

    • +
+

Example Valid Unit Strings

+
+Unit String              Reduced Unit String
+------------------------------------------------------------
+meter                    1.0 meter
+kilometer                1000.0 meter
+km                       1000.0 meter
+km/s                     1000.0 meter / second
+/microsecond             1000000.0 / second
+/us                      1000000.0 / second
+kg-m/s^2                 1000.0 gram meter / second second
+30second                 30.0 second
+30 second                30.0 second
+30 seconds               30.0 second
+200*meter/20.5*second    9.75609756098 meter / second
+
+
+
+

SI UNITS

+

The standard SI units are predefined according to NIST Special +Publication 330. Standard units for both SI Base Units (Table +1) and SI Derived Units with Special Names (Tables 3a and 3b) are +included here for reference. Each standard unit name and abbreviation +are included in this package.

+

SI Base Units

+
+Quantity                Unit Name    Abbr.
+---------------------------------------------
+Length                  meter        m
+Mass                    kilogram     kg
+Time                    second       s
+Current                 ampere       A
+Temperature             kelvin       K
+Amount                  mole         mol
+Luminous Intensity      candela      cd
+
+
+

SI Derived Units with Special Names

+
+Quantity                Unit Name    Abbr.   Units     Base Units
+--------------------------------------------------------------------
+plane angle             radian      rad     m/m       m/m
+solid angle             steradian   sr      m^2/m^2   m^2/m^2
+frequency               hertz       Hz                /s
+force                   newton      N                 m-kg/s^2
+pressure                pascal      Pa      N/m^2     kg/m-s^2
+energy, work            joule       J       N-m       m^2-kg/s^2
+power, radiant flux     watt        W       J/s       m^2-kg/s^3
+electric charge         coulomb     C                 s-A
+electric potential      volt        V       W/A       m^2-kg/s^3-A
+capacitance             farad       F       C/V       s^4-A^2/m^2-kg
+electric resistance     ohm                 V/A       m^2-kg/s^3-A^2
+electric conductance    siemens     S       A/V       s^3-A^2/m^2-kg
+magnetic flux           weber       Wb      V-s       m^2-kg/s^2-A
+magnetic flux density   tesla       T       Wb/m^2    kg/s^2-A
+inductance              henry       H       Wb/A      m^2-kg/s^2-A^2
+luminous flux           lumen       lm                cd-sr
+illuminance             lux         lx      lm/m^2    cd-sr/m^2
+activity (of a
+radionuclide)           becquerel   Bq                /s
+absorbed dose           gray        Gy      J/kg      m^2/s^2
+dose equivalent         sievert     Sv      J/kg      m^2/s^2
+
+

Note that the SI unit kilograms is actually implemented as grams +because 1e-6 kilogram = 1 milligram, not 1 microkilogram. The +abbreviation for Electric Resistance (ohms), which is the omega +character, is not supported.

+

Also note that there is no support for Celsius or Farenheit +temperature. The units conversion routines can only scale values +with multiplication and division, so it is not possible to convert +from thermodynamic temperature (kelvins) to absolute degrees Celsius +or Farenheit. Conversion of thermodynamic quantities, such as +thermal expansion (per unit temperature), however, are easy to add +to the units library.

+

SI Units can have a multiple or sub-multiple prefix. The prefix or its +abbreviation should appear before the unit, without spaces. Compound +prefixes are not allowed, and a prefix should never be used alone. +These prefixes are defined in Table 5 of Special Publication +330.

+
+

SI Prefixes

+
+Prefix Name     Abbr.   Factor
+---------------------------------------
+yotta           Y       1e24
+zetta           Z       1e21
+exa             E       1e18
+peta            P       1e15
+tera            T       1e12
+giga            G       1e9
+mega            M       1e6
+kilo            k       1e3
+hecto           h       1e2
+deka            da      1e1
+deca                    1e1
+deci            d       1e-1
+centi           c       1e-2
+milli           m       1e-3
+micro           u       1e-6
+nano            n       1e-9
+pico            p       1e-12
+femto           f       1e-15
+atto            a       1e-18
+zepto           z       1e-21
+yocto           y       1e-24
+
+

Note that we define the same prefix with both the USA ("deka") and +non-USA ("deca") spellings. Also note that we take the liberty of +allowing "micro" to be typed as a "u" instead of the Greek character +mu.

+

Many non-SI units are commonly used in applications. Appendix B.8 of +NIST Special Publication 811 lists many non-SI conversion +factors. It is not possible to include all possible unit definitions +in this package. In some cases, many different conversion factors +exist for a given unit, depending on the context. (The appendix lists +over 40 conversions for British thermal units!) Application specific +conversions can always be added using the new +command, but some well known and often used conversions are included +in this package.

+
+

Non-SI Units

+
+Unit Name            Abbr.    Base Units
+--------------------------------------------------
+angstrom                      1.0E-10 m
+astronomicalUnit     AU       1.495979E11 m
+atmosphere                    1.01325E5 Pa
+bar                           1.0E5 Pa
+calorie                       4.1868 J
+curie                         3.7E10 Bq
+day                           8.64E4 s
+degree                        1.745329E-2 rad
+erg                           1.0E-7 J
+faraday                       9.648531 C
+fermi                         1.0E-15 m
+foot                 ft       3.048E-1 m
+gauss                         1.0E-4 T
+gilbert                       7.957747E-1 A
+grain                gr       6.479891E-5 kg
+hectare              ha       1.0E4 m^2
+hour                 h        3.6E3 s
+inch                 in       2.54E-2 m
+lightYear                     9.46073E15 m
+liter                L        1.0E-3 m^3
+maxwell              Mx       1.0E-8 Wb
+mho                           1.0 S
+micron                        1.0E-6 m
+mil                           2.54E-5 m
+mile                 mi       1.609344E3 m
+minute               min      6.0E1 s
+parsec               pc       3.085E16 m
+pica                          4.233333E-3 m
+pound                lb       4.535924E-1 kg
+revolution                    6.283185 rad
+revolutionPerMinute  rpm      1.047198E-1 rad/s
+yard                 yd       9.144E-1 m
+year                          3.1536E7 s
+
+
+

Quantities and Derived Units with Special Names

+

This units conversion package is limited specifically to unit +reduction, comparison, and scaling. This package does not consider +any of the quantity names for either base or derived units. A similar +implementation or an extension in a typed or object-oriented language +might introduce user defined types for the quantities. Quantity type +checking could be used, for example, to ensure that all +length values properly reduced to meters, or +that all velocity values properly reduced to +meters/second.

+

A C implementation of this package has been created to work in +conjunction with the Simplified Wrapper Interface Generator +(http://www.swig.org/). That package (units.i) exploits SWIG's typemap +system to automatically convert script quantity strings into floating +point quantities. Function arguments are specified as quantity types +(e.g., typedef float Length), and target units (expected +by the C application code) are specified in an associative array. +Default units are also defined for each quantity type, and are applied +to any unit-less quantity strings.

+

A units system enhanced with quantity type checking might benefit from +inclusion of other derived types which are expressed in terms of +special units, as illustrated in Table 2 of NIST Publication +330. The quantity area, for example, could be +defined as units properly reducing to meter^2, although +the utility of defining a unit named square meter is +arguable.

+
+
+

REFERENCES

+

The unit names, abbreviations, and conversion values are derived from +those published by the United States Department of Commerce Technology +Administration, National Institute of Standards and Technology (NIST) +in NIST Special Publication 330: The International System of +Units (SI) and NIST Special Publication 811: Guide for +the Use of the International System of Units (SI). Both of +these publications are available (as of December 2000) from +http://physics.nist.gov/cuu/Reference/contents.html

+

The ideas behind implementation of this package is based in part on +code written in 1993 by Adrian Mariano which performed dimensional +analysis of unit strings using fixed size tables of C structs. After +going missing in the late 1990's, Adrian's code has reappeared in the +GNU Units program at http://www.gnu.org/software/units/

+
+

AUTHORS

+

Robert W. Techentin

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category units of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +
ADDED embedded/www/tcllib/files/modules/uri/uri.html Index: embedded/www/tcllib/files/modules/uri/uri.html ================================================================== --- embedded/www/tcllib/files/modules/uri/uri.html +++ embedded/www/tcllib/files/modules/uri/uri.html @@ -0,0 +1,266 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uri(n) 1.2.6 tcllib "Tcl Uniform Resource Identifier Management"

+

Name

+

uri - URI utilities

+
+ + +

Description

+

This package contains two parts. First it provides regular expressions +for a number of url/uri schemes. Second it provides a number of +commands for manipulating urls/uris and fetching data specified by +them. For the latter this package analyses the requested url/uri and +then dispatches it to the appropriate package (http, ftp, ...) for +actual fetching.

+

The package currently does not conform to +RFC 2396 (http://www.rfc-editor.org/rfc/rfc2396.txt), +but quite likely should be. Patches and other help are welcome.

+
+

COMMANDS

+
+
uri::split url ?defaultscheme?
+

uri::split takes an url, decodes it and then returns a +list of key/value pairs suitable for array set containing the +constituents of the url. If the scheme is missing from the url +it defaults to the value of defaultscheme if it was specified, +or http else. Currently only the schemes http, +ftp, mailto, urn, news, ldap and +file are supported by the package itself. +See section EXTENDING on how to expand that range.

+

The set of constituents of an url (= the set of keys in the returned +dictionary) is dependent on the scheme of the url. The only key which +is therefore always present is scheme. For the following +schemes the constituents and their keys are known:

+
+
ftp
+

user, pwd, host, port, +path, type

+
http(s)
+

user, pwd, host, port, +path, query, fragment. The fragment +is optional.

+
file
+

path, host. The host is optional.

+
mailto
+

user, host. The host is optional.

+
news
+

Either message-id or newsgroup-name.

+
+
uri::join ?key value?...
+

uri::join takes a list of key/value pairs (generated by +uri::split, for example) and returns the canonical url they +represent. Currently only the schemes http, ftp, +mailto, urn, news, ldap and file +are supported. See section EXTENDING on how to expand that +range.

+
uri::resolve base url
+

uri::resolve resolves the specified url relative to +base. In other words: A non-relative url is returned +unchanged, whereas for a relative url the missing parts are +taken from base and prepended to it. The result of this +operation is returned. For an empty url the result is +base.

+
uri::isrelative url
+

uri::isrelative determines whether the specified url is +absolute or relative.

+
uri::geturl url ?options...?
+

uri::geturl decodes the specified url and then dispatches +the request to the package appropriate for the scheme found in the +url. The command assumes that the package to handle the given scheme +either has the same name as the scheme itself (including possible +capitalization) followed by ::geturl, or, in case of this +failing, has the same name as the scheme itself (including possible +capitalization). It further assumes that whatever package was loaded +provides a geturl-command in the namespace of the same name as +the package itself. This command is called with the given url +and all given options. Currently geturl does not handle +any options itself.

+

Note: file-urls are an exception to the rule +described above. They are handled internally.

+

It is not possible to specify results of the command. They depend on +the geturl-command for the scheme the request was dispatched to.

+
uri::canonicalize uri
+

uri::canonicalize returns the canonical form of a URI. The +canonical form of a URI is one where relative path specifications, +ie. . and .., have been resolved.

+
uri::register schemeList script
+

uri::register registers the first element of schemeList as +a new scheme and the remaining elements as aliases for this scheme. It +creates the namespace for the scheme and executes the script in +the new namespace. The script has to declare variables containing the +regular expressions relevant to the scheme. At least the variable +schemepart has to be declared as that one is used to extend +the variables keeping track of the registered schemes.

+
+
+

SCHEMES

+

In addition to the commands mentioned above this package provides +regular expression to recognize urls for a number of url schemes.

+

For each supported scheme a namespace of the same name as the scheme +itself is provided inside of the namespace uri containing the +variable url whose contents are a regular expression to +recognize urls of that scheme. Additional variables may contain +regular expressions for parts of urls for that scheme.

+

The variable uri::schemes contains a list of all supported +schemes. Currently these are ftp, ldap, file, +http, gopher, mailto, news, +wais and prospero.

+
+

EXTENDING

+

Extending the range of schemes supported by uri::split and +uri::join is easy because both commands do not handle the +request by themselves but dispatch it to another command in the +uri namespace using the scheme of the url as criterion.

+

uri::split and uri::join +call Split[string totitle <scheme>] +and Join[string totitle <scheme>] respectively.

+
+

CREDITS

+

Original code (regular expressions) by Andreas Kupries. +Modularisation by Steve Ball, also the split/join/resolve +functionality.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uri of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/uri/urn-scheme.html Index: embedded/www/tcllib/files/modules/uri/urn-scheme.html ================================================================== --- embedded/www/tcllib/files/modules/uri/urn-scheme.html +++ embedded/www/tcllib/files/modules/uri/urn-scheme.html @@ -0,0 +1,163 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uri_urn(n) 1.0.3 tcllib "Tcl Uniform Resource Identifier Management"

+

Name

+

uri_urn - URI utilities, URN scheme

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.2
    • +
  • package require uri::urn ?1.0.3?
    • +
+ +
+
+

Description

+

This package provides two commands to quote and unquote the disallowed +characters for url using the urn scheme, registers the scheme +with the package uri, and provides internal helpers which +will be automatically used by the commands uri::split and +uri::join of package uri to handle urls using the +urn scheme.

+
+

COMMANDS

+
+
uri::urn::quote url
+

This command quotes the characters disallowed by the urn scheme +(per RFC 2141 sec2.2) in the url and returns the modified url as +its result.

+
uri::urn::unquote url
+

This commands performs the reverse of ::uri::urn::quote. It +takes an urn url, removes the quoting from all disallowed +characters, and returns the modified urls as its result.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uri of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/uuid/uuid.html Index: embedded/www/tcllib/files/modules/uuid/uuid.html ================================================================== --- embedded/www/tcllib/files/modules/uuid/uuid.html +++ embedded/www/tcllib/files/modules/uuid/uuid.html @@ -0,0 +1,177 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

uuid(n) 1.0.4 tcllib "uuid"

+

Name

+

uuid - UUID generation and comparison

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require uuid ?1.0.4?
    • +
+ +
+
+

Description

+

This package provides a generator of universally unique identifiers +(UUID) also known as globally unique identifiers (GUID). This +implementation follows the draft specification from (1) although this +is actually an expired draft document.

+
+

COMMANDS

+
+
::uuid::uuid generate
+

Creates a type 4 uuid by MD5 hashing a number of bits of variant data +including the time and hostname. +Returns the string representation of the new uuid.

+
::uuid::uuid equal id1 id2
+

Compares two uuids and returns true if both arguments are the same uuid.

+
+
+

EXAMPLES

+
+% uuid::uuid generate
+b12dc22c-5c36-41d2-57da-e29d0ef5839c
+
+
+

REFERENCES

+
    +

  1. Paul J. Leach, "UUIDs and GUIDs", February 1998. + (http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt)

    2. +
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category uuid of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Hashes, checksums, and encryption

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/cc_amex.html Index: embedded/www/tcllib/files/modules/valtype/cc_amex.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/cc_amex.html +++ embedded/www/tcllib/files/modules/valtype/cc_amex.html @@ -0,0 +1,211 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::creditcard::amex(n) 1 tcllib "Validation types"

+

Name

+

valtype::creditcard::amex - Validation for AMEX creditcard number

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::creditcard::amex ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an AMEX creditcard number.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::creditcard::amex validate .... ;# Does nothing
+    valtype::creditcard::amex validate .... ;# Throws an error (bad American Expresss creditcard number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::creditcard::amex validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::creditcard::amex checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +CREDITCARD AMEX. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID CREDITCARD AMEX CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an AMEX creditcard number.

+
INVALID CREDITCARD AMEX CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID CREDITCARD AMEX LENGTH
+

The input value is of the wrong length to be an AMEX creditcard number.

+
INVALID CREDITCARD AMEX PREFIX
+

The input value does not start with the magic value(s) required for it +to be an AMEX creditcard number.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/cc_discover.html Index: embedded/www/tcllib/files/modules/valtype/cc_discover.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/cc_discover.html +++ embedded/www/tcllib/files/modules/valtype/cc_discover.html @@ -0,0 +1,211 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::creditcard::discover(n) 1 tcllib "Validation types"

+

Name

+

valtype::creditcard::discover - Validation for Discover creditcard number

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::creditcard::discover ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a Discover creditcard number.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::creditcard::discover validate .... ;# Does nothing
+    valtype::creditcard::discover validate .... ;# Throws an error (bad Discover creditcard number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::creditcard::discover validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::creditcard::discover checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +CREDITCARD DISCOVER. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID CREDITCARD DISCOVER CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a Discover creditcard number.

+
INVALID CREDITCARD DISCOVER CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID CREDITCARD DISCOVER LENGTH
+

The input value is of the wrong length to be a Discover creditcard number.

+
INVALID CREDITCARD DISCOVER PREFIX
+

The input value does not start with the magic value(s) required for it +to be a Discover creditcard number.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/cc_mastercard.html Index: embedded/www/tcllib/files/modules/valtype/cc_mastercard.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/cc_mastercard.html +++ embedded/www/tcllib/files/modules/valtype/cc_mastercard.html @@ -0,0 +1,211 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::creditcard::mastercard(n) 1 tcllib "Validation types"

+

Name

+

valtype::creditcard::mastercard - Validation for Mastercard creditcard number

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::creditcard::mastercard ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a Mastercard creditcard number.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::creditcard::mastercard validate .... ;# Does nothing
+    valtype::creditcard::mastercard validate .... ;# Throws an error (bad Mastercard creditcard number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::creditcard::mastercard validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::creditcard::mastercard checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +CREDITCARD MASTERCARD. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID CREDITCARD MASTERCARD CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a Mastercard creditcard number.

+
INVALID CREDITCARD MASTERCARD CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID CREDITCARD MASTERCARD LENGTH
+

The input value is of the wrong length to be a Mastercard creditcard number.

+
INVALID CREDITCARD MASTERCARD PREFIX
+

The input value does not start with the magic value(s) required for it +to be a Mastercard creditcard number.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/cc_visa.html Index: embedded/www/tcllib/files/modules/valtype/cc_visa.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/cc_visa.html +++ embedded/www/tcllib/files/modules/valtype/cc_visa.html @@ -0,0 +1,211 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::creditcard::visa(n) 1 tcllib "Validation types"

+

Name

+

valtype::creditcard::visa - Validation for VISA creditcard number

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::creditcard::visa ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a VISA creditcard number.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::creditcard::visa validate .... ;# Does nothing
+    valtype::creditcard::visa validate .... ;# Throws an error (bad VISA creditcard number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::creditcard::visa validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::creditcard::visa checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +CREDITCARD VISA. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID CREDITCARD VISA CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a VISA creditcard number.

+
INVALID CREDITCARD VISA CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID CREDITCARD VISA LENGTH
+

The input value is of the wrong length to be a VISA creditcard number.

+
INVALID CREDITCARD VISA PREFIX
+

The input value does not start with the magic value(s) required for it +to be a VISA creditcard number.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/ean13.html Index: embedded/www/tcllib/files/modules/valtype/ean13.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/ean13.html +++ embedded/www/tcllib/files/modules/valtype/ean13.html @@ -0,0 +1,207 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::gs1::ean13(n) 1 tcllib "Validation types"

+

Name

+

valtype::gs1::ean13 - Validation for EAN13

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::gs1::ean13 ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an EAN13.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::gs1::ean13 validate .... ;# Does nothing
+    valtype::gs1::ean13 validate .... ;# Throws an error (bad EAN13).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::gs1::ean13 validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::gs1::ean13 checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +EAN13. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID EAN13 CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an EAN13.

+
INVALID EAN13 CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID EAN13 LENGTH
+

The input value is of the wrong length to be an EAN13.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/iban.html Index: embedded/www/tcllib/files/modules/valtype/iban.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/iban.html +++ embedded/www/tcllib/files/modules/valtype/iban.html @@ -0,0 +1,205 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::iban(n) 1.6 tcllib "Validation types"

+

Name

+

valtype::iban - Validation for IBAN

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::iban ?1.6?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an IBAN.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::iban validate .... ;# Does nothing
+    valtype::iban validate .... ;# Throws an error (bad International Bank Account Number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::iban validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::iban checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +IBAN. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID IBAN CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an IBAN.

+
INVALID IBAN CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/imei.html Index: embedded/www/tcllib/files/modules/valtype/imei.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/imei.html +++ embedded/www/tcllib/files/modules/valtype/imei.html @@ -0,0 +1,208 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::imei(n) 1 tcllib "Validation types"

+

Name

+

valtype::imei - Validation for IMEI

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::imei ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an IMEI.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::imei validate .... ;# Does nothing
+    valtype::imei validate .... ;# Throws an error (bad International Mobile Equipment Identity (IMEI) number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::imei validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::imei checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +IMEI. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID IMEI CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an IMEI.

+
INVALID IMEI CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID IMEI LENGTH
+

The input value is of the wrong length to be an IMEI.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/isbn.html Index: embedded/www/tcllib/files/modules/valtype/isbn.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/isbn.html +++ embedded/www/tcllib/files/modules/valtype/isbn.html @@ -0,0 +1,214 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::isbn(n) 1 tcllib "Validation types"

+

Name

+

valtype::isbn - Validation for ISBN

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::isbn ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an ISBN.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::isbn validate .... ;# Does nothing
+    valtype::isbn validate .... ;# Throws an error (bad ISBN).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::isbn validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::isbn checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
valtype::isbn 13of value
+

This method expects an old-style 10-digit ISBN and returns the +canonical modern 13-digit ISBN. +This is used by validate to canonicalize the input, so that +all parts of the system after the validation can expect to work with +modern 13-digit ISBNs.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +ISBN. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID ISBN CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an ISBN.

+
INVALID ISBN CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID ISBN LENGTH
+

The input value is of the wrong length to be an ISBN.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/luhn.html Index: embedded/www/tcllib/files/modules/valtype/luhn.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/luhn.html +++ embedded/www/tcllib/files/modules/valtype/luhn.html @@ -0,0 +1,205 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::luhn(n) 1 tcllib "Validation types"

+

Name

+

valtype::luhn - Validation for plain number with a LUHN checkdigit

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a plain number with a LUHN checkdigit.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::luhn validate .... ;# Does nothing
+    valtype::luhn validate .... ;# Throws an error (bad luhn checkdigit).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::luhn validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::luhn checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +LUHN. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID LUHN CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a plain number with a LUHN checkdigit.

+
INVALID LUHN CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/luhn5.html Index: embedded/www/tcllib/files/modules/valtype/luhn5.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/luhn5.html +++ embedded/www/tcllib/files/modules/valtype/luhn5.html @@ -0,0 +1,205 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::luhn5(n) 1 tcllib "Validation types"

+

Name

+

valtype::luhn5 - Validation for plain number with a LUHN5 checkdigit

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn5 ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a plain number with a LUHN5 checkdigit.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::luhn5 validate .... ;# Does nothing
+    valtype::luhn5 validate .... ;# Throws an error (bad luhn5 checkdigit).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::luhn5 validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::luhn5 checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +LUHN5. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID LUHN5 CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a plain number with a LUHN5 checkdigit.

+
INVALID LUHN5 CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/usnpi.html Index: embedded/www/tcllib/files/modules/valtype/usnpi.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/usnpi.html +++ embedded/www/tcllib/files/modules/valtype/usnpi.html @@ -0,0 +1,208 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::usnpi(n) 1 tcllib "Validation types"

+

Name

+

valtype::usnpi - Validation for USNPI

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::luhn
    • +
  • package require valtype::usnpi ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for an USNPI.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::usnpi validate .... ;# Does nothing
+    valtype::usnpi validate .... ;# Throws an error (bad US National Provider Identifier (US-NPI) number).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::usnpi validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::usnpi checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +USNPI. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID USNPI CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be an USNPI.

+
INVALID USNPI CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID USNPI LENGTH
+

The input value is of the wrong length to be an USNPI.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/valtype_common.html Index: embedded/www/tcllib/files/modules/valtype/valtype_common.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/valtype_common.html +++ embedded/www/tcllib/files/modules/valtype/valtype_common.html @@ -0,0 +1,218 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::common(n) 1 tcllib "Validation types"

+

Name

+

valtype::common - Validation, common code

+
+ + +

Description

+

This package implements a number of common commands used by the +validation types in this module. These commands essentially +encapsulate the throwing of validation errors, ensuring that a proper +-errorcode is used. See section Error Codes.

+
+

API

+
+
valtype::common::reject code text
+

The core command of this package it throws an INVALID error +with the specified text. The first argument is a list of codes +extending the INVALID with detail information.

+
valtype::common::badchar code ?text?
+

This command throws an INVALID CHAR error with the specified +text. The first argument is a list of codes providing +details. These are inserted between the codes INVALID and +CHARACTER.

+
valtype::common::badcheck code ?text?
+

This command throws an INVALID CHECK-DIGIT error with the +specified text, if any, extended by the standard text "the check +digit is incorrect". The first argument is a list of codes providing +details. These are inserted between the codes INVALID and +CHECK_DIGIT.

+
valtype::common::badlength code lengths ?text?
+

This command throws an INVALID LENGTH error with the +specified text, if any, extended by the standard text "incorrect +length, expected ... character(s)". The first argument is a list of +codes providing details. +These are inserted between the codes INVALID and +LENGTH. The argument lengths is a list of the input +lengths which had been expected, i.e. these are the valid lengths.

+
valtype::common::badprefix code prefixes ?text?
+

This command throws an INVALID PREFIX error with the +specified text, if any, extended by the standard text "incorrect +prefix, expected ...". The first argument is a list of codes providing +details. +These are inserted between the codes INVALID and +PREFIX. The argument prefixes is a list of the input +prefixes which had been expected, i.e. these are the valid prefixes.

+
+
+

Error Codes

+

The errors thrown by the commands of this package all use the +-errorcode INVALID to distinguish the input validation +failures they represent from package internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. This is +supplied by the caller. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can be +thrown by this package are shown below, with <> a placeholder +for both the caller-supplied type-information, the type description.

+
+
INVALID <> CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a <>.

+
INVALID <> CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
INVALID <> LENGTH
+

The input value is of the wrong length to be a <>.

+
INVALID <> PREFIX
+

The input value does not start with the magic value(s) required for it +to be a <>.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/valtype/verhoeff.html Index: embedded/www/tcllib/files/modules/valtype/verhoeff.html ================================================================== --- embedded/www/tcllib/files/modules/valtype/verhoeff.html +++ embedded/www/tcllib/files/modules/valtype/verhoeff.html @@ -0,0 +1,205 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

valtype::verhoeff(n) 1 tcllib "Validation types"

+

Name

+

valtype::verhoeff - Validation for plain number with a VERHOEFF checkdigit

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require snit 2
    • +
  • package require valtype::common
    • +
  • package require valtype::verhoeff ?1?
    • +
+ +
+
+

Description

+

This package implements a snit validation type for a plain number with a VERHOEFF checkdigit.

+

A validation type is an object that can be used to validate Tcl values +of a particular kind. For example, snit::integer, a validation +type defined by the snit package is used to validate that a +Tcl value is an integer.

+

Every validation type has a validate method which is used to +do the validation. This method must take a single argument, the value +to be validated; further, it must do nothing if the value is valid, +but throw an error if the value is invalid:

+
+    valtype::verhoeff validate .... ;# Does nothing
+    valtype::verhoeff validate .... ;# Throws an error (bad verhoeff checkdigit).
+
+

The validate method will always return the validated value on +success, and throw the -errorcode INVALID on error, possibly +with additional elements which provide more details about the problem.

+
+

API

+

The API provided by this package satisfies the specification +of snit validation types found in the documentation of +Snit's Not Incr Tcl.

+
+
valtype::verhoeff validate value
+

This method validates the value and returns it, possibly in a +canonical form, if it passes. If the value does not pass the +validation an error is thrown.

+
valtype::verhoeff checkdigit value
+

This method computes a check digit for the value. Before doing +so it is validated, except for a checkdigit. If the value does not +pass the validation no check digit is calculated and an error is +thrown instead.

+
+
+

Error Codes

+

As said in the package description, the errors thrown by the commands +of this package in response to input validation failures use the +-errorcode INVALID to distinguish themselves from package +internal errors.

+

To provide more detailed information about why the validation +failed the -errorCode goes actually beyond that. +First, it will contain a code detailing the type itself. Here this is +VERHOEFF. This is then followed by values detailing the +reason for the failure. The full set of -errorCodes which can +be thrown by this package are:

+
+
INVALID VERHOEFF CHARACTER
+

The input value contained one or more bad characters, i.e. characters +which must not occur in the input for it to be a plain number with a VERHOEFF checkdigit.

+
INVALID VERHOEFF CHECK-DIGIT
+

The check digit of the input value is wrong. This usually signals a +data-entry error, with digits transposed, forgotten, etc. Of course, +th input may be an outright fake too.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category valtype of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Validation, Type checking

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/cat.html Index: embedded/www/tcllib/files/modules/virtchannel_base/cat.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/cat.html +++ embedded/www/tcllib/files/modules/virtchannel_base/cat.html @@ -0,0 +1,169 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::cat(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::cat - Concatenation channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::cat ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::cat package provides a command creating +concatenation channels. These are non-seekable channels owning a list +of subordinate channels whose contents they return in order, until all +are exhausted. In this manner the channel is the concatentation of the +contents of all the sub-ordinate channels.

+

Note that the created channels take ownership of the channels +they were constructed with. Whenever they have exhausted one of their +channel it will be closed. Similarly, closing the cat channel will +close all the sub-ordinates it still has.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::core framework.

+

Event handling is delegated to the currently active sub-channel.

+
+

API

+
+
::tcl::chan::cat chan...
+

This command creates the concatenation channel using all the provided +channels, and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/facade.html Index: embedded/www/tcllib/files/modules/virtchannel_base/facade.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/facade.html +++ embedded/www/tcllib/files/modules/virtchannel_base/facade.html @@ -0,0 +1,187 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::facade(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::facade - Facade channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require logger
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::facade ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::facade package provides a command creating +facades to other channels. These are channels which own a single +subordinate channel and delegate all operations to.

+

The main use for facades is the debugging of actions on a +channel. While most of the information could be tracked by a virtual +channel transformation it does not have access to the event-related +operation, and furthermore they are only available in Tcl 8.6.

+

Therefore this channel, usable with Tcl 8.5, and having access +to everything going on for a channel.

+

The intercepted actions on channel are logged through package +logger.

+

Beyond that facades provide the following additional channel +configuration options:

+
+
-self
+

The TclOO object handling the facade.

+
-fd
+

The handle of the subordinate, i.e. wrapped channel.

+
-used
+

The last time the wrapped channel was read from or written to by +the facade, as per clock milliseconds. A value of 0 +indicates that the subordinate channel was not accessed at all, yet.

+
-created
+

The time the facade was created, as per clock milliseconds.

+
-user
+

A free-form value identifying the user of the facade and its +wrapped channel.

+
+

Of these only option -user is writable.

+
+

API

+
+
::tcl::chan::facade chan
+

This command creates the facade channel around the provided +channel chan, and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html Index: embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html +++ embedded/www/tcllib/files/modules/virtchannel_base/halfpipe.html @@ -0,0 +1,193 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::halfpipe(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::halfpipe - In-memory channel, half of a fifo2

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::halfpipe package provides a command creating +one half of a tcl::chan::fifo2 pair. Writing into such a +channel invokes a set of callbacks which then handle the data. This is +similar to a channel handler, except having a much simpler API.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::halfpipe ?-option value...?
+

This command creates a halfpipe channel and configures it with the +callbacks to run when the channel is closed, data was written to it, +or ran empty. See the section Options for the list of +options and associated semantics. +The result of the command is a list containing two elements, the +handle of the new channel, and the object command of the channel +handler, in this order. +The latter is supplied to the caller to provide her with access to the +put method for adding data to the channel.

+

Two halfpipes with a bit of glue logic in the callbacks make +for one tcl::chan::fifo2.

+
objectCmd put bytes
+

This method of the channel handler object puts the data bytes +into the channel so that it can be read from it.

+
+
+

Options

+
+
-close-command cmdprefix
+

This callback is invoked when the channel is closed. +A single argument is supplied, the handle of the channel being closed. +The result of the callback is ignored.

+
-write-command cmdprefix
+

This callback is invoked when data is written to the channel. +Two arguments are supplied, the handle of the channel written to, and the data written. +The result of the callback is ignored.

+
-empty-command cmdprefix
+

This callback is invoked when the channel has run out of data to read. +A single argument is supplied, the handle of the channel.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html Index: embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html +++ embedded/www/tcllib/files/modules/virtchannel_base/nullzero.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::nullzero(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::nullzero - Null/Zero channel combination

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::nullzero ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::nullzero package provides a command creating channels, +which are a combination of null and zero devices. They immediately forget +whatever is written to them, and on reading return an infinite stream of null +characters.

+

Packages related to this are tcl::chan::null and +tcl::chan::zero.

+

The internal TclOO class implementing the channel handler +is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::nullzero
+

This command creates a new nullzero channel and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/randseed.html Index: embedded/www/tcllib/files/modules/virtchannel_base/randseed.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/randseed.html +++ embedded/www/tcllib/files/modules/virtchannel_base/randseed.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::randomseed(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::randomseed - Utilities for random channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::randomseed ?1?
    • +
+ +
+
+

Description

+

The tcl::randomseed package provides a a few utility commands +to help with the seeding of tcl::chan::random channels.

+
+

API

+
+
::tcl::randomseed
+

This command creates returns a list of seed integers suitable as seed +argument for random channels. The numbers are derived from the process +id, current time, and Tcl random number generator.

+
::tcl::combine seed1 seed2
+

This command takes to seed lists and combines them into a single list +by XORing them elementwise, modulo 256. If the lists are not of equial +length the shorter of the two is padded with 0s before merging.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/std.html Index: embedded/www/tcllib/files/modules/virtchannel_base/std.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/std.html +++ embedded/www/tcllib/files/modules/virtchannel_base/std.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::std(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::std - Standard I/O, unification of stdin and stdout

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::std ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::std package provides a command creating +a standard channel which unifies stdin and stdout into a single +read- and writable channel. The result is not seek-able, like +the original standard channels.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::core framework.

+
+

API

+
+
::tcl::chan::std
+

This command creates the std channel and returns its handle.

+

The channel is created only once, on the first call, and all +future calls simply return this handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo.html @@ -0,0 +1,165 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::fifo(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::fifo - In-memory fifo channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::fifo ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::fifo package provides a command creating +channels which live purely in memory. Access is fifo-like, i.e. things +are read out of the channel in the order they were written to it. +This is equivalent to the fifo channels provided by the package +Mmechan, except that this is written in pure Tcl, not C. On +the other hand, Memchan is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::fifo
+

This command creates a new fifo channel and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_fifo2.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::fifo2(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::fifo2 - In-memory interconnected fifo channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::halfpipe ?1?
    • +
  • package require tcl::chan::fifo2 ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::fifo2 package provides a command creating +pairs of channels which live purely in memory and are connected to +each other in a fifo manner. What is written to one half of the pair +can be read from the other half, in the same order. One particular +application for this is communication between threads, with one half +of the pair moved to the thread to talk to. +This is equivalent to the fifo2 channels provided by the package +Mmechan, except that this is written in pure Tcl, not C. On +the other hand, Memchan is usable with Tcl 8.4 and before, +whereas this package requires Tcl 8.5 or higher, and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::fifo2
+

This command creates a new connected pair of fifo channels and returns +their handles, as a list containing two elements.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_memchan.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::memchan(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::memchan - In-memory channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::memchan ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::memchan package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. This is equivalent to the memchan channels provided by +the package Memchan, except that this is written in pure Tcl, +not C. On the other hand, Memchan is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +TclOO.

+

Packages related to this are tcl::chan::string and +tcl::chan::variable.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::memchan
+

This command creates a new memchan channel and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_null.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_null.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_null.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_null.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::null(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::null - Null channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::null ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::null package provides a command creating null +channels, i.e. write-only channels which immediately forget whatever +is written to them. This is equivalent to the null channels provided by +the package Memchan, except that this is written in pure Tcl, +not C. On the other hand, Memchan is usable with Tcl 8.4 and +before, whereas this package requires Tcl 8.5 or higher, and +TclOO.

+

Packages related to this are tcl::chan::zero and +tcl::chan::nullzero.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::null
+

This command creates a new null channel and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_random.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_random.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_random.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_random.html @@ -0,0 +1,168 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::random(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::random - Random channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::random ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::random package provides a command creating +random channels, i.e. read-only channels which return an infinite +stream of pseudo-random characters upon reading. This is similar to +the random channels provided by the package Memchan, except +that this is written in pure Tcl, not C, and uses a much simpler +generator as well. On the other hand, Memchan is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::random seed
+

This command creates a new random channel and returns its handle. +The seed is a list of integer numbers used to initialize the +internal feedback shift register of the generator.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_string.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_string.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_string.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_string.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::string(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::string - Read-only in-memory channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::string ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::string package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. +In contrast to the channels created by tcl::chan::memchan +they are read-only however, their content is provided at the time of +construction and immutable afterward.

+

Packages related to this are tcl::chan::memchan and +tcl::chan::variable.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::string content
+

This command creates a new string channel and returns its handle. The +channel provides random read-only access to the content string.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_variable.html @@ -0,0 +1,168 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::variable(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::variable - In-memory channel using variable for storage

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::variable ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::variable package provides a command creating +channels which live purely in memory. They provide random-access, +i.e. are seekable. +In contrast to the channels created by tcl::chan::memchan +the data is not hidden in the channel however, but stored in an +associated variable, specified at the time of construction.

+

Packages related to this are tcl::chan::memchan and +tcl::chan::string.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::variable varname
+

This command creates a new variable channel and returns its handle. +The content of the channel is stored in the associated namespace +variable varname.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html Index: embedded/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html +++ embedded/www/tcllib/files/modules/virtchannel_base/tcllib_zero.html @@ -0,0 +1,167 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::zero(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::zero - Zero channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::zero ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::zero package provides a command creating zero +channels, i.e. read-only channels which return an infinite stream of null +characters upon reading. This is equivalent to the zero channels +provided by the package Memchan, except that this is written +in pure Tcl, not C. On the other hand, Memchan is usable with +Tcl 8.4 and before, whereas this package requires Tcl 8.5 or higher, +and TclOO.

+

Packages related to this are tcl::chan::null and +tcl::chan::nullzero.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::zero
+

This command creates a new zero channel and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html Index: embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html +++ embedded/www/tcllib/files/modules/virtchannel_base/textwindow.html @@ -0,0 +1,162 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::textwindow(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::textwindow - Textwindow channel

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::events ?1?
    • +
  • package require tcl::chan::textwindow ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::textwindow package provides a command creating +write-only channels connected to text widgets. Anything written to the +channel is printed into the associated widget.

+

The internal TclOO class implementing the channel +handler is a sub-class of the tcl::chan::events framework.

+
+

API

+
+
::tcl::chan::textwindow widget
+

This command creates a new textwindow channel and returns its handle. +Data written to this channel will appear in the associated widget.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/core.html Index: embedded/www/tcllib/files/modules/virtchannel_core/core.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_core/core.html +++ embedded/www/tcllib/files/modules/virtchannel_core/core.html @@ -0,0 +1,191 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::core(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::core - Basic reflected/virtual channel support

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::core package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel (initialization, finalization).

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::chan::core objectName
+

This command creates a new channel core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of channel core instances provides only two methods, both +corresponding to channel handler commands (For reference see +TIP 219). They expect to be called +from whichever object instance the channel core was made a part of.

+
+
objectName initialize thechannel mode
+

This method implements standard behaviour for the initialize +method of channel handlers. Using introspection it finds the handler +methods supported by the instance and returns a list containing their +names, as expected by the support for reflected channels in the Tcl +core.

+

It further remembers the channel handle in an instance variable +for access by sub-classes.

+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It simply destroys itself.

+
objectName destroy
+

Destroying the channel core instance closes the channel it was +initialized for, see the method initialize. When destroyed +from within a call of finalize this does not happen, under +the assumption that the channel is being destroyed by Tcl.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/events.html Index: embedded/www/tcllib/files/modules/virtchannel_core/events.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_core/events.html +++ embedded/www/tcllib/files/modules/virtchannel_core/events.html @@ -0,0 +1,199 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::chan::events(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::chan::events - Event support for reflected/virtual channels

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::chan::core ?1?
    • +
  • package require tcl::chan::events ?1?
    • +
+ +
+
+

Description

+

The tcl::chan::events package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel supporting event driven IO. It is a +sub-class of tcl::chan::core, inheriting all of its behaviour.

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::chan::events objectName
+

This command creates a new channel event core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of channel event core instances provides only four methods, two +corresponding to channel handler commands (For reference see +TIP 219), and the other two for use by +sub-classes to control event generation. They former expect to be called +from whichever object instance the channel event core was made a part of.

+
+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It overrides the behaviour inherited from +tcl::chan::core and additionally disables any and all event +generation before destroying itself.

+
objectName watch thechannel eventmask
+

This method implements standard behaviour for the watch +method of channel handlers. Called by the IO system whenever the +interest in event changes it updates the instance state to activate +and/or suppress the generation of the events of (non-)interest.

+
objectName allow eventname...
+
+
objectName disallow eventname...
+

These two methods are exported to sub-classes, so that their instances +can notify their event core of the events the channel they implement +can (allow) or cannot (disallow) generate. +Together with the information about the events requested by Tcl's IO +system coming in through the watch method the event core is +able to determine which events it should (not) generate and act +accordingly.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html Index: embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html +++ embedded/www/tcllib/files/modules/virtchannel_core/transformcore.html @@ -0,0 +1,191 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::core(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::core - Basic reflected/virtual channel transform support

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.5
    • +
  • package require TclOO
    • +
  • package require tcl::transform::core ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::core package provides a TclOO +class implementing common behaviour needed by virtually every +reflected or virtual channel transformation (initialization, finalization).

+

This class expects to be used as either superclass of a concrete +channel class, or to be mixed into such a class.

+
+

Class API

+
+
::tcl::transform::core objectName
+

This command creates a new transform core object with an associated +global Tcl command whose name is objectName. This command may +be used to invoke various operations on the object, as described in +the section for the Instance API.

+
+
+

Instance API

+

The API of transform core instances provides only two methods, both +corresponding to transform handler commands (For reference see +TIP 230). They expect to be called +from whichever object instance the transform core was made a part of.

+
+
objectName initialize thechannel mode
+

This method implements standard behaviour for the initialize +method of transform handlers. Using introspection it finds the handler +methods supported by the instance and returns a list containing their +names, as expected by the support for reflected transformation in the +Tcl core.

+

It further remembers the channel handle in an instance variable +for access by sub-classes.

+
objectName finalize thechannel
+

This method implements standard behaviour for the finalize +method of channel handlers. It simply destroys itself.

+
objectName destroy
+

Destroying the transform core instance closes the channel and transform +it was initialized for, see the method initialize. When destroyed +from within a call of finalize this does not happen, under +the assumption that the channel and transform are being destroyed by Tcl.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/adler32.html @@ -0,0 +1,184 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::adler32(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::adler32 - Adler32 transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::adler32 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::adler32 package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally continuously computes the adler32 checksums of the data +it has seen for each direction and stores them in Tcl variables +specified at construction time.

+

Related transformations in this module are +tcl::transform::counter, +tcl::transform::crc32, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::adler32 chan -option value...
+

This command creates an adler32 checksumming transformation on top of +the channel chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +adler32 checksum of the data read from the channel.

+

If not specified, or the empty string, the checksum of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +adler32 checksum of the data written to the channel.

+

If not specified, or the empty string, the checksum of the +write direction is not saved.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/hex.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/hex.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/hex.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/hex.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::hex(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::hex - Hexadecimal encoding transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::hex ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::hex package provides a command creating +a channel transformation which hex encodes data written to it, and +decodes the data read from it.

+

A related transformations in this module is +tcl::transform::base64.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::hex chan
+

This command creates a hex transformation on top of the channel +chan and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/identity.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/identity.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/identity.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/identity.html @@ -0,0 +1,171 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::identity(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::identity - Identity transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::identity ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::identity package provides a command +creating an identity channel transformation, which does nothing but +pass the read and written bytes through it unchanged. Not really +useful in an application, however as the prototypical observer +transformation its code is a useful starting point for any other +observers people may wish to write.

+

The transformations in this module which derived from +identity's code are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::crc32, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::identity chan
+

This command creates an identity transformation on top of the channel +chan and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/limitsize.html @@ -0,0 +1,166 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::limitsize(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::limitsize - limiting input

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::limitsize ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::limitsize package provides a command +creating a channel transformation which limits the number of +characters which can be read from the channel. A generator for an +artificial EOF.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::limitsize chan max
+

This command creates a size limiting transformation on top of the +channel chan and returns its handle.

+

max is the number of bytes which can be read from the +channel before EOF is signaled by the transformation. Note that +popping the transformation clears the EOF it generated as well.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/observe.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/observe.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/observe.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/observe.html @@ -0,0 +1,170 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::observe(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::observe - Observer transformation, stream copy

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::observe ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::observer package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally copies the data it has seen for each direction into +channels specified at construction time.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::crc32, and +tcl::transform::identity.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::observe chan logw logr
+

This command creates an observer transformation on top of the channel +chan and returns its handle. The channel handles logr and +logw are there the data is copied to.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/rot.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/rot.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/rot.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/rot.html @@ -0,0 +1,171 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::rot(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::rot - rot-encryption

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::rot ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::rot package provides a command creating +a channel transformation which performs primitive encryption (on +writing) and decryption (on reading) on the alphabetic characters. The +algorithm is the Caesar-cipher, a specific variant of which is rot13.

+

A related transformations in this module is +tcl::transform::otp.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::rot chan key
+

This command creates a rot encryption transformation on top of the +channel chan and returns its handle.

+

The "key" specifies how far characters are rotated in the +alphabet, and is wrapped to the range "0...25".

+

Note that this transformation affects only bytes in the ranges +ASCII 65...90, and 97...122, i.e. the upper- and lower-case alphabetic +characters, i.e. "A...Z" and "a...z". All other bytes are passed +through unchanged.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/spacer.html @@ -0,0 +1,166 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::spacer(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::spacer - Space insertation and removal

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::spacer ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::spacer package provides a command +creating a channel transformation which adds spacing to the data +written to it, and removes such spacing from the data read from it.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::spacer chan n ?space?
+

This command creates a spacer transformation on top of the channel +chan and returns its handle.

+

The space character sequence will be added every n +bytes of data written, and on the read side the same is done in +reverse, removing the spacing. If space is not specified it +defaults to a single space character (ASCII 32).

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/tcllib_zlib.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::zlib(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::zlib - zlib (de)compression

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::zlib ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::zlib package provides a command creating +a channel transformation which zlib compresses the written data, and +decompresses on reading.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::zlib chan ?level?
+

This command creates a zlib compressor transformation on top of the +channel chan and returns its handle.

+

The level specifies how much effort is put into the +compression, from 0 to 9, and defaults to 4.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/vt_base64.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/vt_base64.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/vt_base64.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/vt_base64.html @@ -0,0 +1,164 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::base64(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::base64 - Base64 encoding transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::base64 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::base64 package provides a command +creating a channel transformation which base64 encodes data written to +it, and decodes the data read from it.

+

A related transformations in this module is +tcl::transform::hex.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::base64 chan
+

This command creates a base64 transformation on top of the channel +chan and returns its handle.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/vt_counter.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/vt_counter.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/vt_counter.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/vt_counter.html @@ -0,0 +1,183 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::counter(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::counter - Counter transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::counter ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::counterr package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally counts the bytes it has seen for each direction and +stores these counts in Tcl variables specified at construction time.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::crc32, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::counter chan -option value...
+

This command creates a counter transformation on top of the channel +chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +byte count of the data read from the channel.

+

If not specified, or the empty string, the counter of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +byte count of the data written to the channel.

+

If not specified, or the empty string, the counter of the +write direction is not saved.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/vt_crc32.html @@ -0,0 +1,184 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::crc32(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::crc32 - Crc32 transformation

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::crc32 ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::crc32 package provides a command +creating a channel transformation which passes the read and written +bytes through unchanged (like tcl::transform::identity), but +additionally continuously computes the crc32 checksums of the data it +has seen for each direction and stores them in Tcl variables specified +at construction time. The checksum in question is zlib's crc32.

+

Related transformations in this module are +tcl::transform::adler32, +tcl::transform::counter, +tcl::transform::identity, and +tcl::transform::observe.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::crc32 chan -option value...
+

This command creates a crc32 checksumming transformation on top of +the channel chan and returns its handle. The accepted options are

+
+
-read-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +crc32 checksum of the data read from the channel.

+

If not specified, or the empty string, the checksum of the read +direction is not saved.

+
-write-variable varname
+

The value of the option is the name of a global or namespaced +variable, the location where the transformation has to store the +crc32 checksum of the data written to the channel.

+

If not specified, or the empty string, the checksum of the +write direction is not saved.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/virtchannel_transform/vt_otp.html Index: embedded/www/tcllib/files/modules/virtchannel_transform/vt_otp.html ================================================================== --- embedded/www/tcllib/files/modules/virtchannel_transform/vt_otp.html +++ embedded/www/tcllib/files/modules/virtchannel_transform/vt_otp.html @@ -0,0 +1,168 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

tcl::transform::otp(n) 1 tcllib "Reflected/virtual channel support"

+

Name

+

tcl::transform::otp - Encryption via one-time pad

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.6
    • +
  • package require tcl::transform::core ?1?
    • +
  • package require tcl::transform::otp ?1?
    • +
+ +
+
+

Description

+

The tcl::transform::otp package provides a command creating +a channel transformation which uses externally provided one-time pads +to perform encryption (on writing) and decryption (on reading).

+

A related transformations in this module is +tcl::transform::rot.

+

The internal TclOO class implementing the transform +handler is a sub-class of the tcl::transform::core +framework.

+
+

API

+
+
::tcl::transform::otp chan keychanw keychanr
+

This command creates a one-time pad based encryption transformation on +top of the channel chan and returns its handle.

+

The two channels keychanw and keychanr contain the +one-time pads for the write and read directions, respectively. Their +contents are reads and xored with the bytes written to and read from +the channel.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category virtchannel of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Channels

+
+ +
ADDED embedded/www/tcllib/files/modules/websocket/websocket.html Index: embedded/www/tcllib/files/modules/websocket/websocket.html ================================================================== --- embedded/www/tcllib/files/modules/websocket/websocket.html +++ embedded/www/tcllib/files/modules/websocket/websocket.html @@ -0,0 +1,496 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

websocket(n) 1.3.1 tcllib "websocket client and server"

+

Name

+

websocket - Tcl implementation of the websocket protocol

+
+ + +

Description

+

NOTE: THIS DOCUMENTATION IS WORK IN PROGRESS...

+

The websocket library is a pure Tcl implementation of the WebSocket +specification covering the needs of both clients and servers. +Websockets provide a way to upgrade a regular HTTP connection into a +long-lived and continuous binary or text communication between the +client and the server. The library offers a high-level interface to +receive and send data as specified in RFC 6455 (v. 13 of the +protocol), relieving callers from all necessary protocol framing and +reassembly. It implements the ping facility specified by the +standard, together with levers to control it. Pings are server-driven +and ensure the liveness of the connection across home (NAT) networks. +The library has a number of introspection facilities to inquire about +the current state of the connection, but also to receive notifications +of incoming pings, if necessary. Finally, the library contains a +number of helper procedures to facilitate the upgrading handshaking in +existing web servers.

+

Central to the library is the procedure websocket::takeover that +will take over a regular socket and treat it as a WebSocket, thus +performing all necessary protocol framing, packetisation and +reassembly in servers and clients. The procedure also takes a +handler, a command that will be called back each time a (possibly +reassembled) packet from the remote end is ready for delivery at the +original caller. While exported by the package, the command +websocket::takeover is seldom called in applications, since the +package provides other commands that are specifically tuned for the +needs of clients and servers.

+

Typically, clients will open a connection to a remote server by +providing a WebSocket URL (ws: or wss: schemes) and the +handler described above to the command websocket::open. The +opening procedure is a wrapper around the latest http::geturl +implementations: it arranges to keep the socket created within the +http library opened for reuse, but confiscates it from its (internal) +map of known sockets for its own use.

+

Servers will start by registering themselves through the command +::websocket::server and a number of handlers for paths using the +command ::websocket::live. Then for each incoming client +connection, they should test the incoming request to detect if it is +an upgrade request using ::websocket::test and perform the final +handshake to place the socket connection under the control of the +websocket library and its central procedure using ::websocket::upgrade.

+

Apart from these main commands, the package provides a number of +commands for introspection and basic operations on the websockets that +it has under its control. As WebSockets connections are long-lived, +most remaining communication with the library will be by way of +callbacks, i.e. commands that are triggered whenever important events +within the library have occur, but mostly whenever data has been +received on a WebSocket.

+
+

Callbacks

+

A number of commands of the library take a handler handler command as +an argument, a command which will be called back upon reception of +data, but also upon important events within the library or events +resulting from control messages sent by the remote end. For each +callback being performed, the following arguments will be appended:

+
+
sock
+

The identifier of the WebSocket, as returned for example by +::websocket::open

+
type
+

A textual type describing the event or message content, can be one of +the following

+
+
text
+

Complete text message

+
binary
+

Complete binary message

+
ping
+

Incoming ping message

+
connect
+

Notification of successful connection to server

+
disconnect
+

Disconnection from remote end

+
close
+

Pending closure of connection

+
+
msg
+

Will contain the data of the message, whenever this is relevant, +i.e. when the type is text, binary or +ping and whenever there is data available.

+
+
+

API

+
+
::websocket::open url handler ?options?
+

This command is used in clients to open a WebSocket to a remote +websocket-enabled HTTP server. The URL provided as an argument in +url should start with ws: or wss:, which are the WebSockets +counterpart of http: and https:. The handler is a command that +will be called back on data reception or whenever important events +occur during the life of the websocket. +::websocket::open will return a socket which serves as both the +identifier of the websocket and of the physical low-level socket to +the server. This socket can be used in a number of other commands for +introspection or for controlling the behaviour of the library. +Being essentially a wrapper around the ::http::geturl command, +this command provides mostly the same set of dash-led options than +::http::geturl. Documented below are the options that differ +from ::http::geturl and which are specific to the WebSocket +library.

+
+
-headers
+

This option is supported, knowing that a number of headers will be +automatically added internally in the library in order to be able to +handshake the upgrading of the socket from a regular HTTP socket to a +WebSocket with the server.

+
-validate
+

This option is not supported as it has no real point for WebSockets.

+
-handler
+

This option is used internally by the websocket library and cannot be +used.

+
-command
+

This option is used internally by the websocket library and cannot be +used.

+
-protocol
+

This option specifies a list of application protocols to handshake +with the server. This protocols might help the server triggering +application specific features.

+
-timeout
+

This option is supported, but will implemented as part of the library +to enable a number of finalising cleanups.

+
+
::websocket::send sock type ?msg? ?final?
+

This command will send a fragment or a control message to the remote +end of the WebSocket identified by sock. The type of the +message specified in type can either be an integer according to +the specification or (preferrably) one of the following case +insensitive strings: "text", "binary" or "ping". The content of the +message to send to the remote end is contained in msg and +message fragmentation is made possible by the setting the argument +final to non-true, knowing that the type of each fragment has +then to be the same. +The command returns the number of bytes that were effectively sent, or +-1 on errors. Serious errors, such as when sock does not +identify a known WebSocket or when the connection is not stable yet +will generate errors that must be catched.

+
::websocket::server sock
+

This command registers the (accept) socket sock as the +identifier fo an HTTP server that is capable of doing WebSockets. +Paths onto which this server will listen for incoming connections +should be declared using ::websocket::live.

+
::websocket::live sock path cb ?proto?
+

This procedure registers callbacks that will be performed on a +WebSocket compliant server registered with ::websocket::server] +whenever a client connects to a matching path and protocol. +sock is the listening socket of the websocket compliant server +declared using ::websocket::server. path is a glob-style +path to match in client request, whenever this will occur. cb +is the command to callback (see Callbacks). proto is a +glob-style protocol name matcher.

+
::websocket::test srvSock cliSock path ?hdrs? ?qry?
+

This procedure will test if the connection from an incoming client on +socket cliSock and on the path path is the opening of a +WebSocket stream within a known server srvSock. The incoming +request is not upgraded at once, instead a (temporary) context for the +incoming connection is created. This allows server code to perform a +number of actions, if necessary, before the WebSocket stream +connection goes live. The text is made by analysing the content of +the headers hdrs which should contain a dictionary list of the +HTTP headers of the incoming client connection. +The command will return 1 if this is an incoming WebSocket +upgrade request and 0 otherwise.

+
::websocket::upgrade sock
+

Upgrade the socket sock that had been deemed by +::websocket::test to be a WebSocket connection request to a true +WebSocket as recognised by this library. As a result, the necessary +connection handshake will be sent to the client, and the command will +arrange for relevant callbacks to be made during the life of the +WebSocket, notably using the specifications described by +::websocket::live.

+
::websocket::takeover sock handler ?server?
+

Take over the existing opened socket sock to implement sending +and receiving WebSocket framing on top of the socket. The procedure +arranges for handler to be called back whenever messages, +control messages or other important internal events are received or +occured. server defaults to 0 and can be set to +1 (or a boolean that evaluates to true) to specify that this is a +WebSocket within a server. Apart from specificities in the protocol, +servers should ping their clients at regular intervals in order to +keep the connection opened at all time. When server is set to +true, the library will arrange to send these pings automatically.

+
::websocket::conninfo sock what
+

Provides callers with some introspection facilities in order to get +some semi-internal information about an existing websocket +connection. Depending on the value of the what argument, the +procedure returns the following piece of information:

+
+
peername
+

Name (preferred) or IP of remote end.

+
sockname
+

or name Name or IP of local end.

+
closed
+

1 if the connection is closed, 0 otherwise

+
client
+

1 if the connection is a client websocket, 0 otherwise

+
server
+

1 if the connection is a server websocket, 0 otherwise

+
type
+

server if the connection is a server websocket, client otherwise.

+
handler
+

The handler command associated to the websocket

+
state
+

The state of the websocket, which can be one of:

+
+
CONNECTING
+

Connection to remote end is in progress.

+
CONNECTED
+

Connection is connected to remote end.

+
CLOSED
+

Connection is closed.

+
+
+
::websocket::find ?host? ?port?
+

Look among existing websocket connections for the ones that match the +hostname and port number filters passed as parameters. This lookup +takes the remote end into account and the host argument is +matched both against the hostname (whenever available) and the IP +address of the remote end. Both the host and port +arguments are glob-style string matching filters and default to +*, i.e. will match any host and/or port number.

+
::websocket::configure sock args
+

This command takes a number of dash-led options (and their values) to +configure the behaviour of an existing websocket connection. The +recognised options are the following (they can be shortened to the +lowest common denominator):

+
+
-keepalive
+

is the number of seconds between each +keepalive pings being sent along the connection. A zero or negative +number will effectively turn off the feature. In servers, +-keepalive defaults to 30 seconds, and in clients, no pings +are initiated.

+
-ping
+

is the text that is used during the automated +pings. This text defaults to the empty string, leading to an empty ping.

+
+
::websocket::loglevel ?loglvl?
+

Set or query the log level of the library, which defaults to error. +Logging is built on top of the logger module, and the library makes +use of the following levels: debug, info, notice, +warn and error. When called with no argument, this procedure will +simply return the current log level. Otherwise loglvl should contain +the desired log level.

+
::websocket::close sock ?code? ?reason?
+

Gracefully close a websocket that was directly or indirectly passed to +::websocket::takeover. The procedure will optionally send the +code and describing reason as part of the closure handshake. +Good defaults are provided, so that reasons for a number of known codes will +be sent back. Only the first 125 characters of a reason string will be kept and +sent as part of the handshake. The known codes are:

+
+
1000
+

Normal closure (the default code when none provided).

+
1001
+

Endpoint going away

+
1002
+

Protocol Error

+
1003
+

Received incompatible data type

+
1006
+

Abnormal closure

+
1007
+

Received data not consistent with type

+
1008
+

Policy violation

+
1009
+

Received message too big

+
1010
+

Missing extension

+
1011
+

Unexpected condition

+
1015
+

TLS handshake error

+
+
+
+

Examples

+

The following example opens a websocket connection to the echo +service, waits 400ms to ensure that the connection is really +established and sends a single textual message which should be echoed +back by the echo service. A real example would probably use the +connect callback to know when connection to the remote +server has been establish and would only send data at that time.

+
+package require websocket
+::websocket::loglevel debug
+proc handler { sock type msg } {
+    switch -glob -nocase -- $type {
+	co* {
+	    puts "Connected on $sock"
+	}
+	te* {
+	    puts "RECEIVED: $msg"
+	}
+	cl* -
+	dis* {
+	}
+    }
+    
+}
+proc test { sock } {
+    puts "[::websocket::conninfo $sock type] from [::websocket::conninfo $sock sockname] to [::websocket::conninfo $sock peername]"
+    
+    ::websocket::send $sock text "Testing, testing..."
+}
+set sock [::websocket::open ws://echo.websocket.org/ handler]
+after 400 test $sock
+vwait forever
+
+
+

TLS Security Considerations

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

+

Policy decisions like the set of protocols to support and what +ciphers to use are not the responsibility of TLS, nor of +this package itself however. +Such decisions are the responsibility of whichever application is +using the package, and are likely influenced by the set of servers +the application will talk to as well.

+

For example, in light of the recent +POODLE attack discovered by Google many servers will disable support +for the SSLv3 protocol. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. +Such a patch may be as simple as generally activating tls1 +support, as shown in the example below.

+
+    package require tls
+    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
+    ... your own application code ...
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category websocket of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + +

Category

+

Networking

+
+
ADDED embedded/www/tcllib/files/modules/wip/wip.html Index: embedded/www/tcllib/files/modules/wip/wip.html ================================================================== --- embedded/www/tcllib/files/modules/wip/wip.html +++ embedded/www/tcllib/files/modules/wip/wip.html @@ -0,0 +1,407 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

wip(n) 2.2 tcllib "Word Interpreter"

+

Name

+

wip - Word Interpreter

+
+ + +

Description

+

This package provides a micro interpreter for lists of words. Domain +specific languages based on this will have a bit of a Forth feel, with +the input stream segmented into words and any other structuring left +to whatever the language desired. Note that we have here in essence +only the core dispatch loop, and no actual commands whatsoever, making +this definitely only a Forth feel and not an actual Forth.

+

The idea is derived from Colin McCormack's treeql processor, +modified to require less boiler plate within the command +implementations, at the expense of, likely, execution speed. In +addition the interface between processor core and commands is more +complex too.

+
+

GENERAL BEHAVIOUR

+

Word interpreters have a mappping from the names of the language +commands they shall recognize to the methods in the engine to invoke +for them, and possibly fixed arguments for these methods. This mapping +is largely static, however it is possible to change it during the +execution of a word list (= program).

+

At the time a language command is defined the word interpreter will +use snit's introspection capabilities to determine the +number of arguments expected by the method of the egnine, and together +with the number of fixed arguments supplied in the method prefix of +the mapping it then knows how many arguments the language command is +expecting. This is the command's arity. Variable-argument +methods (i.e. with the last argument named args) are not +allowed and will cause the word interpreter to throw an error at +definition time.

+

Note that while I said snit's abilities the engine object +can be written in any way, as long as it understands the method +info args, which takes a method name and returns the list +of arguments for that method.

+

When executing a list of words (aka program) the first word is always +taken as the name of a language command, and the next words as its +arguments, per the arity of the command. Command and argument +words are removed from the list and then associated method of the +engine is executed with the argument words. The process then repeats +using the then-first word of the list.

+

Note that the methods implementing the language commands may have full +access to the list of words and are allowed to manipulate as they see +fit.

+
    +

  1. This means, for example, that while we cannot specify +variable-argument methods directly they can consume words after their +fixed arguments before returning to the execution loop. This may be +under the control of their fixed arguments.

    2. +

  2. Another possibility is the use of method run_next and its +variants to execute commands coming after the current command, +changing the order of execution.

    3. +

  3. Execution can be further changed by use of the program accessor +methods which allow a command implementation to modify the remaining +list of words (insert, replace, prepend, append words) without +executing them immediately.

    4. +

  4. At last the basic run methods save and restore an existing +list of words when used, enabling recursive use from within command +implementations.

    5. +
+
+

CLASS API

+

The main command of the package is:

+
+
::wip wipName engine arg...
+

The command creates a new word interpreter object with an associated +global Tcl command whose name is wipName. If however the string +%AUTO% was used as object name the package will generate its +own unique name for the object.

+

The engine is the object the word interpreter will dispatch all +recognized commands to, and the arguments are a word list which +defines an initial mapping from language words to engine methods.

+

The recognized language of this word list is

+
+
def name
+

Defines name as command of the language, to be mapped to a +method of the engine having the same name.

+
def name method_prefix
+

Defines name as command of the language, to be mapped to the +method of the engine named in the method_prefix.

+
+

The returned command may be used to invoke various operations on the +object. It has the following general form:

+
+
wipName option ?arg arg ...?
+

Option and the args determine the exact behavior of the +command.

+
+
+

The package additionally exports the command:

+
+
wip::dsl ?suffix?
+

This command is for use within snit types which wish to use one or +more wip interpreters as a component. Use within the type definition +installs most of the boilerplate needed to setup and use a word +interpreter.

+

It installs a component named wip, and a method +wip_setup for initializing it. This method has to be called +from within the constructor of the type using the word interpreter. +If further installs a series of procedures which make the object API +of the word interpreter directly available to the type's methods, +without having to specify the component.

+

Note that this does and cannot install the language to +interpret, i.e. the mapping from words to engine methods.

+

It is possible to instantiate multiple word interpreter components +within a type by using different suffices as arguments to the command. +In that case the name of the component changes to +'wip_$suffix', the setup command becomes +'wip_$suffix_setup' and all the procedures also get the suffix +'_$suffix'.

+
+
+

OBJECT API

+

The following commands are possible for word interpreter objects:

+
+
wipName def name ?method_prefix?
+

Defines a language command name and maps it to the method named +in the engine's method_prefix. If the method_prefix name +is not specified it is simply the name of the language command.

+
wipName defl names
+

Defines a series of language commands, specified through the list of +names, all of which are mapped to engine methods of the same +name.

+
wipName defd dict
+

Defines a series of language commands, specified through the +dictionary dict of names and method prefixes.

+
wipName deflva name...
+

As method defl, however the list of names is specified +through multiple arguments.

+
wipName defdva (name method_prefix)...
+

As method defd, however the dictionary of names and method +prefixes is specified through multiple arguments.

+
wipName undefl names
+

Removes the named series of language commands from the mapping.

+
wipName undefva name...
+

As method undefl, however the list of names is specified +through multiple arguments.

+
wipName unknown cmdprefix
+

Sets the handler for unknown words to cmdprefix. This command +prefix takes one argument, the current word, and either throws some +error, or returns the result of executing the word, as defined by the +handler. The default handler simply throws an error.

+
wipName runl wordlist
+

Treats the list of words in wordlist as a program and executes +the contained command one by one. The result of the command executed +last is returned as the result of this command.

+

The wordlist is stored in the object for access by the other +run-methods, and the general program accessor methods (see +below). A previously stored wordlist is saved during the execution of +this method and restored before it returns. This enables the recursive +execution of word lists within word lists.

+
wipName run word...
+

As method runl, however the list of words to execute is +specified through multiple arguments.

+
wipName run_next
+

Low-level method. Determines the next word in the list of words, and +its arguments, and then executes it. The result of the executed word +is the result of this method.

+

Exposed for use within command implementations. +The methods run and runl use it to execute words +until their word list is exhausted.

+
wipName run_next_while acceptable
+

Low-level method. Invokes the method run_next as long as the +next word is in the set of acceptable words, and the program is +not empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_until rejected
+

Low-level method. Invokes the method run_next until the next +word is in the set of rejected words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_if acceptable
+

Low-level method. Invokes the method run_next if the next +word is in the set of acceptable words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName run_next_ifnot rejected
+

Low-level method. Invokes the method run_next if the next +word is not in the set of rejected words, and the program is not +empty. The result of the command executed last is returned as the +result of this command.

+

Exposed for use within command implementations to change the order of +execution.

+
wipName next
+

Returns the next word in the programm. The word is also removed.

+
wipName peek
+

Returns the next word in the programm without removing it

+
wipName peekall
+

Returns the remaining programm in toto.

+
wipName insertl at wordlist
+

Basic programm accessor method. Inserts the specified wordlist +into the program, just before the word at position at. Positions +are counted from zero.

+
wipName replacel wordlist
+

Basic programm accessor method. Replaces the whole stored program with +the specified wordlist.

+
wipName pushl wordlist
+

Program accessor method. The specified wordlist is added to the +front of the remaining program. Equivalent to

+
$wip insertl 0 $wordlist
+
+
wipName addl wordlist
+

Program accessor method. The specified wordlist is appended at +the end of the remaining program. Equivalent to

+
$wip insertl end $wordlist
+
+
wipName insert at word...
+

Like method insertl, except the words are specified through +multiple arguments.

+
wipName replace word...
+

Like method setl, except the words are specified through +multiple arguments.

+
wipName push word...
+

Like method pushl, except the words are specified through +multiple arguments.

+
wipName add word...
+

Like method addl, except the words are specified through +multiple arguments.

+
+
+

EXAMPLES

+

No examples yet.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category wip of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

Programming tools

+
+ +
ADDED embedded/www/tcllib/files/modules/yaml/huddle.html Index: embedded/www/tcllib/files/modules/yaml/huddle.html ================================================================== --- embedded/www/tcllib/files/modules/yaml/huddle.html +++ embedded/www/tcllib/files/modules/yaml/huddle.html @@ -0,0 +1,619 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

huddle(n) 0.2 tcllib "HUDDLE"

+

Name

+

huddle - Create and manipulate huddle object

+
+ + +

Description

+

Huddle provides a generic Tcl-based serialization/intermediary format. +Currently, each node is wrapped in a tag with simple type information.

+

When converting huddle-notation to other serialization formats like +JSON or YAML this type information is used to select the proper notation. +And when going from JSON/YAML/... to huddle their notation can be used +to select the proper huddle type.

+

In that manner huddle can serve as a common intermediary format.

+
+huddle-format: >
+  {HUDDLE {huddle-node}}
+huddle-node: >
+  {tag content}
+each content of tag means:
+  s: (content is a) string
+  L: list, each sub node is a huddle-node
+  D: dict, each sub node is a huddle-node
+confirmed:
+  - JSON
+  - YAML(generally, but cannot discribe YAML-tags)
+limitation:
+  - cannot discribe aliases from a node to other node.
+
+

The huddle package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
huddle create key value ?key value ...?
+

Create a huddle object as a dict. It can contain other huddle objects.

+
huddle list ?value value ...?
+

Create a huddle object as a list. It can contain other huddle objects.

+
huddle number number
+

Create a huddle object as a number.

+
huddle string string
+

Create a huddle object as a string.

+
huddle boolean expression to evaluate as true or false
+

Create a huddle object as a boolean evaluating an expression as true or false-

+
huddle true
+

Create a huddle object as a boolean true.

+
huddle false
+

Create a huddle object as a boolean false.

+
huddle null
+

Create a huddle object as a null.

+
huddle get object key ?key ...?
+

Almost the same as dict get. +Get a sub-object from the huddle object. +key can be used to huddle-list's index.

+
huddle gets object key ?key ...?
+

Get a sub-object from the huddle object, stripped.

+
huddle set objectVar key ?key ...? value
+

Almost the same as dict set. +Set a sub-object from the huddle object. +key can be used to huddle-list's index.

+
huddle remove object key ?key ...?
+

Almost the same as dict remove. +Remove a sub-object from the huddle object. +key can be used to huddle-list's index.

+
huddle combine object1 object2 ?object3 ...?
+

Merging huddle objects given.

+
+% set aa [huddle create a b c d]
+HUDDLE {D {a {s b} c {s d}}}
+% set bb [huddle create a k l m]
+HUDDLE {D {a {s k} l {s m}}}
+% huddle combine $aa $bb
+HUDDLE {D {a {s k} c {s d} l {s m}}}
+
+
+
huddle equal object1 object2
+

Comparing two huddle objects recursively. +When to equal, returns 1, otherwise 0.

+
+% set aa [huddle create a b c d]
+HUDDLE {D {a {s b} c {s d}}}
+% set bb [huddle create c d a b]
+HUDDLE {D {c {s d} a {s b}}}
+% huddle equal $aa $bb
+1
+
+
+
huddle append objectVar key value ?key value ...?
+
+
huddle append objectVar value ?value ...?
+

Appending child elements. When for dicts, giving key/value. When for lists, giving values.

+
+% set aa [huddle create a b c d]
+HUDDLE {D {a {s b} c {s d}}}
+% huddle append aa a k l m
+HUDDLE {D {a {s k} c {s d} l {s m}}}
+% set bb [huddle list i j k l]
+HUDDLE {L {{s i} {s j} {s k} {s l}}}
+% huddle append bb g h i
+HUDDLE {L {{s i} {s j} {s k} {s l} {s g} {s h} {s i}}}
+
+
+
huddle keys object
+

The same as dict keys.

+
huddle llength object
+

The same as llength.

+
huddle type object ?key key...?
+

Return the element type of specified by keys. +if ?key? is not given, returns the type of root node.

+
+
string
+

the node is a tcl's string.

+
dict
+

the node is a dict.

+
list
+

the node is a list.

+
number
+

the node is a number.

+
boolean
+

the node is a boolean.

+
null
+

the node is a null.

+
+
+% huddle type {HUDDLE {s str}}
+string
+% huddle type {HUDDLE {L {{s a} {s b} {s c}}}}
+list
+% huddle type {HUDDLE {D {aa {s b} cc {s d}}}} cc
+string
+
+
+
huddle strip object
+

Stripped all tags. Converted to normal Tcl's list/dict.

+
huddle jsondump object ?offset? ?newline? ?begin_offset?
+

dump a json-stream from the huddle-object.

+
+
offset ""
+

begin offset as spaces " ".

+
+
# normal output has some indents. some strings are escaped.
+% huddle jsondump {HUDDLE {L {{L {{s i} {s baa} {s \\k} {L {{s 1.0} {s true} {s /g} {s h}}} {L {{s g}}}}} {s t}}}}
+[
+  [
+    "i",
+    "baa",
+    "\\k",
+    [
+      1.0,
+      true,
+      "\/g",
+      "h"
+    ],
+    ["g"]
+  ],
+  "t"
+]
+# stripped output
+% huddle jsondump {HUDDLE {D {dd {D {bb {D {a {s baa} c {s {d
+a}}}} cc {D {g {s h}}}}} ee {D {i {s j} k {s 1} j {s { m\a}}}}}}} "" ""
+{"dd": {"bb": {"a": "baa","c": "d\na"},"cc": {"g": "h"}},"ee": {"i": "j","k": 1,"j": " m\\a"}}
+
+
+
huddle compile spec data
+

construct a huddle object from plain old tcl values. +spec is defined as follows:

+
+
string
+

data is simply a string

+
list
+

data is a tcl list of strings

+
dict
+

data is a tcl dict of strings

+
list list
+

data is a tcl list of lists

+
list dict
+

data is a tcl list of dicts

+
dict xx list
+

data is a tcl dict where the value of key xx is a tcl list

+
dict * list
+

data is a tcl dict of lists +data is plain old tcl values

+
+
% huddle compile {dict * list} {a {1 2 3} b {4 5}}
+HUDDLE {D {a {L {{s 1} {s 2} {s 3}}} b {L {{s 4} {s 5}}}}}
+% huddle compile {dict * {list {dict d list}}} {a {{c 1} {d {2 2 2} e 3}} b {{f 4 g 5}}}
+HUDDLE {D {a {L {{D {c {s 1}}} {D {d {L {{s 2} {s 2} {s 2}}} e {s 3}}}}} b {L {{D {f {s 4} g {s 5}}}}}}}
+
+
+
huddle isHuddle object
+

if object is a huddle, returns 1. the other, returns 0.

+
huddle checkHuddle object
+

if object is not a huddle, rises an error.

+
huddle to_node object ?tag?
+

for type-callbacks.

+

if object is a huddle, returns root-node. the other, returns [list s $object].

+
+% huddle to_node str
+s str
+% huddle to_node str !!str
+!!str str
+% huddle to_node {HUDDLE {s str}}
+s str
+% huddle to_node {HUDDLE {l {a b c}}}
+l {a b c}
+
+
+
huddle wrap tag src
+

for type-callbacks.

+

Create a huddle object from src with specified tag.

+
+% huddle wrap "" str
+HUDDLE str
+% huddle wrap s str
+HUDDLE {s str}
+
+
+
huddle call tag command args
+

for type-callbacks.

+

devolving command to default tag-callback

+
huddle addType callback
+

add a user-specified-type/tag to the huddle library. +To see "Additional Type".

+
+
callback
+

callback function name for additional type.

+
+
+
+

TYPE CALLBACK

+

The definition of callback for user-type.

+
+
callback command ?args?
+
+
command
+

huddle subcomand which is needed to reply by the callback.

+
args
+

arguments of subcommand. The number of list of arguments is different for each subcommand.

+
+
+

The callback procedure shuould reply the following subcommands.

+
+
setting
+

only returns a fixed dict of the type infomation for setting the user-tag.

+
+
type typename
+

typename of the type

+
method {method1 method2 method3 ...}
+

method list as huddle subcommand. Then, you can call [huddle method1 ...]

+
tag {tag1 child/parent tag2 child/parent ...}
+

tag list for huddle-node as a dict. if the type has child-nodes, use "parent", otherwise use "child".

+
+
get_sub src key
+

returns a sub node specified by key.

+
+
src
+

a node content in huddle object.

+
+
strip src
+

returns stripped node contents. if the type has child nodes, every node must be stripped.

+
set src key value
+

sets a sub-node from the tagged-content, and returns self.

+
remove src key value
+

removes a sub-node from the tagged-content, and returns self.

+
+

strip must be defined at all types. +get_sub must be defined at container types. +set/remove shuould be defined, if you call them.

+
+# callback sample for my-dict
+proc my_dict_setting {command args} {
+    switch -- $command {
+        setting { ; # type definition
+            return {
+                type dict
+                method {create keys}
+                tag {d child D parent}
+                constructor create
+                str s
+            }
+            # type:   the type-name
+            # method: add methods to huddle's subcommand.
+            #          "get_sub/strip/set/remove/equal/append" called by huddle module.
+            #          "strip" must be defined at all types.
+            #          "get_sub" must be defined at container types.
+            #          "set/remove/equal/append" shuould be defined, if you call them.
+            # tag:    tag definition("child/parent" word is maybe obsoleted)
+        }
+        get_sub { ; # get a sub-node specified by "key" from the tagged-content
+            foreach {src key} $args break
+            return [dict get $src $key]
+        }
+        strip { ; # strip from the tagged-content
+            foreach {src nop} $args break
+            foreach {key val} $src {
+                lappend result $key [huddle strip $val]
+            }
+            return $result
+        }
+        set { ; # set a sub-node from the tagged-content
+            foreach {src key value} $args break
+            dict set src $key $value
+            return $src
+        }
+        remove { ; # remove a sub-node from the tagged-content
+            foreach {src key value} $args break
+            return [dict remove $src $key]
+        }
+        equal { ; # check equal for each node
+            foreach {src1 src2} $args break
+            if {[llength $src1] != [llength $src2]} {return 0}
+            foreach {key1 val1} $src1 {
+                if {![dict exists $src2 $key1]} {return 0}
+                if {![huddle _equal_subs $val1 [dict get $src2 $key1]]} {return 0}
+            }
+            return 1
+        }
+        append { ; # append nodes
+            foreach {str src list} $args break
+            if {[llength $list] % 2} {error {wrong # args: should be "huddle append objvar ?key value ...?"}}
+            set resultL $src
+            foreach {key value} $list {
+                if {$str ne ""} {
+                    lappend resultL $key [huddle to_node $value $str]
+                } else {
+                    lappend resultL $key $value
+                }
+            }
+            return [eval dict create $resultL]
+        }
+        create { ; # $args: all arguments after "huddle create"
+            if {[llength $args] % 2} {error {wrong # args: should be "huddle create ?key value ...?"}}
+            set resultL {}
+            foreach {key value} $args {
+                lappend resultL $key [huddle to_node $value]
+            }
+            return [huddle wrap D $resultL]
+        }
+        keys {
+            foreach {src nop} $args break
+            return [dict keys [lindex [lindex $src 1] 1]]
+        }
+        default {
+            error "$command is not callback for dict"
+        }
+    }
+}
+
+
+# inheritance sample from default dict-callback
+proc ::yaml::_huddle_mapping {command args} {
+    switch -- $command {
+        setting { ; # type definition
+            return {
+                type dict
+                method {mapping}
+                tag {!!map parent}
+                constructor mapping
+                str !!str
+            }
+        }
+        mapping { ; # $args: all arguments after "huddle mapping"
+            if {[llength $args] % 2} {error {wrong # args: should be "huddle mapping ?key value ...?"}}
+            set resultL {}
+            foreach {key value} $args {
+                lappend resultL $key [huddle to_node $value !!str]
+            }
+            return [huddle wrap !!map $resultL]
+        }
+        default { ; # devolving to default dict-callback
+            return [huddle call D $command $args]
+        }
+    }
+}
+
+
+

How to add type

+

You can add huddle-node types e.g. ::struct::tree. +To do so, first, define a callback-procedure for additional tagged-type. +The proc get argments as command and ?args?. It has some switch-sections.

+

And, addType subcommand will called.

+
+huddle addType my_dict_setting
+
+
+

WORKING SAMPLE

+
+# create as a dict
+% set bb [huddle create a b c d]
+HUDDLE {D {a {s b} c {s d}}}
+# create as a list
+% set cc [huddle list e f g h]
+HUDDLE {L {{s e} {s f} {s g} {s h}}}
+% set bbcc [huddle create bb $bb cc $cc]
+HUDDLE {D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}}
+% set folding [huddle list $bbcc p [huddle list q r] s]
+HUDDLE {L {{D {bb {D {a {s b} c {s d}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}
+# normal Tcl's notation
+% huddle strip $folding
+{bb {a b c d} cc {e f g h}} p {q r} s
+# get a sub node
+% huddle get $folding 0 bb
+HUDDLE {D {a {s b} c {s d}}}
+% huddle gets $folding 0 bb
+a b c d
+# overwrite a node
+% huddle set folding 0 bb c kkk
+HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q} {s r}}} {s s}}}
+# remove a node
+% huddle remove $folding 2 1
+HUDDLE {L {{D {bb {D {a {s b} c {s kkk}}} cc {L {{s e} {s f} {s g} {s h}}}}} {s p} {L {{s q}}} {s s}}}
+% huddle strip $folding
+{bb {a b c kkk} cc {e f g h}} p {q r} s
+# dump as a JSON stream
+% huddle jsondump $folding
+[
+  {
+    "bb": {
+      "a": "b",
+      "c": "kkk"
+    },
+    "cc": [
+      "e",
+      "f",
+      "g",
+      "h"
+    ]
+  },
+  "p",
+  [
+    "q",
+    "r"
+  ],
+  "s"
+]
+
+
+

LIMITATIONS

+

now printing.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category huddle of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/yaml/yaml.html Index: embedded/www/tcllib/files/modules/yaml/yaml.html ================================================================== --- embedded/www/tcllib/files/modules/yaml/yaml.html +++ embedded/www/tcllib/files/modules/yaml/yaml.html @@ -0,0 +1,277 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

yaml(n) 0.3.9 tcllib "YAML processing"

+

Name

+

yaml - YAML Format Encoder/Decoder

+
+ + +

Description

+

The yaml package provides a simple Tcl-only library for parsing the +YAML http://www.yaml.org/ data exchange format as specified in +http://www.yaml.org/spec/1.1/.

+

The yaml package returns +data as a Tcl dict. Either the dict package or Tcl 8.5 is +required for use.

+
+

COMMANDS

+
+
::yaml::yaml2dict ?options? txt
+
+
::yaml::yaml2huddle ?options? txt
+

Parse yaml formatted text txt into a Tcl dict/huddle and return the value.

+
+
-file
+

txt is a filename of YAML-stream.

+
-stream
+

txt is just a YAML-stream.

+
-types list
+

The list is a type list for the yaml-scalar types.(e.g. !!str !!timestamp !!integer !!true ...)

+
 -types {timestamp integer null true false}
+

In this case, if a string matched "timestamp", converted to the TCL internal timestamp.(e.g. "2001-12-15T02:59:43.1Z" => 1008385183)

+
-m:true param
+

The param is two elements of list for the value of true, and considered strings.

+
 -m:true {1 {true on + yes y}}
+

In this case, the string "yes" found in YAML Stream, automatically converted 1.

+
-m:false param
+

The param is two elements of list for the value of false, and considered strings.

+
 -m:false {0 {false off - no n}}
+
+
-m:null param
+

The param is two elements of list for the value of null, and considered strings.

+
 -m:null {"" {null nil "" ~}}
+
+
-validate
+

Experiment,old: Output stream contains YAML's-tag, each node.

+
% puts [::yaml::load -validate {[aaa, bbb]}]
+=>
+!!seq {{!!str aaa} {!!str bbb}}
+
+
+
+
::yaml::setOption ?options?
+

Change implicit options for the library. +Now, the params are the same as ::yaml::yaml2dict. +Arguments of::yaml::yaml2dict is more priority than this setting.

+
::yaml::dict2yaml dict ?indent? ?wordwrap?
+
+
::yaml::list2yaml list ?indent? ?wordwrap?
+
+
::yaml::huddle2yaml huddle ?indent? ?wordwrap?
+

Convert a dict/list/huddle object into YAML stream.

+
+
indent
+

spaces indent of each block node. +currently default is 2.

+
wordwrap
+

word wrap for YAML stream. +currently default is 40.

+
+
+
+

EXAMPLES

+

An example of a yaml stream converted to Tcl. A yaml stream is returned as a +single item with multiple elements.

+
{
+--- !<tag:clarkevans.com,2002:invoice>
+invoice: 34843
+date   : 2001-01-23
+bill-to: &id001
+    given  : Chris
+    family : Dumars
+    address:
+        lines: |
+            458 Walkman Dr.
+            Suite #292
+        city    : Royal Oak
+        state   : MI
+        postal  : 48046
+ship-to: *id001
+product:
+    - sku         : BL394D
+      quantity    : 4
+      description : Basketball
+      price       : 450.00
+    - sku         : BL4438H
+      quantity    : 1
+      description : Super Hoop
+      price       : 2392.00
+tax  : 251.42
+total: 4443.52
+comments:
+    Late afternoon is best.
+    Backup contact is Nancy
+    Billsmer @ 338-4338.
+}
+=>
+invoice 34843 date 2001-01-23 bill-to {given Chris family Dumars address {lines {458 Walkman Dr.
+Suite #292
+} city {Royal Oak} state MI postal 48046}} ship-to {given Chris family Dumars address {lines {458 Walkman Dr.
+Suite #292
+} city {Royal Oak} state MI postal 48046}} product {{sku BL394D quantity 4 description Basketball price 450.00} {sku BL4438H quantity 1 description {Super Hoop} price 2392.00}} tax 251.42 total 4443.52 comments {Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.}
+

An example of a yaml object converted to Tcl. A yaml object is returned as a +multi-element list (a dict).

+
{
+---
+- [name        , hr, avg  ]
+- [Mark McGwire, 65, 0.278]
+- [Sammy Sosa  , 63, 0.288]
+-
+  Mark McGwire: {hr: 65, avg: 0.278}
+  Sammy Sosa: { hr: 63, avg: 0.288}
+}
+=>
+{name hr avg} {{Mark McGwire} 65 0.278} {{Sammy Sosa} 63 0.288} {{Mark McGwire} {hr 65 avg 0.278} {Sammy Sosa} {hr 63 avg 0.288}}
+
+
+

LIMITATIONS

+

tag parser not implemented. currentry, tags are merely ignored.

+

Only Anchor => Aliases ordering. back alias-referring is not supported.

+

Too many braces, or too few braces.

+

Not enough character set of line feeds. Please use only "\n" as line breaks.

+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category yaml of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ + + +
ADDED embedded/www/tcllib/files/modules/zip/decode.html Index: embedded/www/tcllib/files/modules/zip/decode.html ================================================================== --- embedded/www/tcllib/files/modules/zip/decode.html +++ embedded/www/tcllib/files/modules/zip/decode.html @@ -0,0 +1,229 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

zipfile::decode(n) 0.7.1 tcllib "Zip archive handling"

+

Name

+

zipfile::decode - Access to zip archives

+
+ + +

Description

+

This package provides commands to decompress and access the contents +of zip archives.

+
+

API

+
+
::zipfile::decode::archive
+

This command decodes the last opened (and not yet closed) zip archive +file. +The result of the command is a dictionary describing the contents of +the archive. The structure of this dictionary is not public. Proper +access should be made through the provided accessor command of this +package.

+
::zipfile::decode::close
+

This command releases all state associated with the last call of +::zipfile::decode::open. +The result of the command is the empty string.

+
::zipfile::decode::comment adict
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +returns the global comment of the archive.

+
::zipfile::decode::content archive
+

This is a convenience command which decodes the specified zip +archive file and returns the list of paths found in it as its +result.

+
::zipfile::decode::copyfile adict path dst
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +copies the decompressed contents of the file path in the archive +to the the file dst. +An error is thrown if the file is not found in the archive.

+
::zipfile::decode::files adict
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +returns the list of files found in the archive.

+
::zipfile::decode::getfile zdict path
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +returns the decompressed contents of the file path in the archive. +An error is thrown if the file is not found in the archive.

+
::zipfile::decode::hasfile adict path
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +check if the specified path is found in the archive. +The result of the command is a boolean flag, true if the path +is found, and false otherwise.

+
::zipfile::decode::iszip archive
+

This command takes the path of a presumed zip archive file and +returns a boolean flag as the result of the command telling us if it +actually is a zip archive (true), or not (false).

+
::zipfile::decode::open archive
+

This command takes the path of a zip archive file and prepares +it for decoding. +The result of the command is the empty string. +All important information is stored in global state. If multiple open +calls are made one after the other only the state of the last call is +available to the other commands.

+
::zipfile::decode::unzip adict dstdir
+

This command takes a dictionary describing the currently open zip +archive file, as returned by ::zipfile::decode::archive, and +unpacks the archive in the given destination directory dstdir. +The result of the command is the empty string.

+
::zipfile::decode::unzipfile archive dstdir
+

This is a convenience command which unpacks the specified zip +archive file in the given destination directory dstdir.

+

The result of the command is the empty string.

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category zipfile of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File

+
+ +
ADDED embedded/www/tcllib/files/modules/zip/encode.html Index: embedded/www/tcllib/files/modules/zip/encode.html ================================================================== --- embedded/www/tcllib/files/modules/zip/encode.html +++ embedded/www/tcllib/files/modules/zip/encode.html @@ -0,0 +1,201 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

zipfile::encode(n) 0.4 tcllib "Zip archive handling"

+

Name

+

zipfile::encode - Generation of zip archives

+
+ +

Synopsis

+
+
    +
  • package require Tcl 8.4
    • +
  • package require logger
    • +
  • package require Trf
    • +
  • package require crc32
    • +
  • package require snit
    • +
  • package require zlibtcl
    • +
  • package require fileutil
    • +
  • package require zipfile::encode ?0.4?
    • +
+ +
+
+

Description

+

This package provides a class for the generation of zip archives.

+
+

Class API

+
+
::zipfile::encode ?objectName?
+

The class command constructs encoder instances, i.e. objects. The +result of the command is the fully-qualified name of the instance +command.

+

If no objectName is specified the class will generate and use an +automatic name. If the objectName was specified, but is not +fully qualified the command will be created in the current namespace.

+
+
+

Instance API

+
+
<encoder> comment: text
+

This method specifies the text of the global comment for the archive. +The result of the method is the empty string. +In case of multiple calls to this method for the same encoder the data +from the last call prevails over all previous texts.

+
<encoder> file: dst owned src ?noCompress?
+

This method adds a new file to the archive. +The contents of the file are found in the filesystem at src, and +will be stored in the archive under path dst. +If the file is declared as owned by the archive the original +file will be deleted when the archive is constructed and written. +If noCompress is set to true the file will not be +compressed on writing. Otherwise (the default) the file is compressed +if it is advantageous. +The result of the method is an empty string.

+
<encoder> write archive
+

This method takes the global comment and all added files, encodes them +as a zip archive and stores the result at path archive in the +filesystem. +All added files which were owned by the archive are deleted at this +point. +On the issue of ordering, the files are added to the archive in the +same order as they were specified via file:. Note that +this behaviour is new for version 0.4 and higher. Before 0.4 no +specific order was documented. It was lexicographically sorted. The +change was made to support zip-based file formats which require +a specific order of files in the archive, for example ".epub".

+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category zipfile of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File

+
+ +
ADDED embedded/www/tcllib/files/modules/zip/mkzip.html Index: embedded/www/tcllib/files/modules/zip/mkzip.html ================================================================== --- embedded/www/tcllib/files/modules/zip/mkzip.html +++ embedded/www/tcllib/files/modules/zip/mkzip.html @@ -0,0 +1,213 @@ + +
+ +
[ + Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications + ]
+
+

zipfile::mkzip(n) 1.2 tcllib "Zip archive creation"

+

Name

+

zipfile::mkzip - Build a zip archive

+
+ + +

Description

+

This package utilizes the zlib functions in Tcl 8.6 to build zip +archives.

+
+

API

+
+
::zipfile::mkzip::mkzip zipfile ?-zipkit? ?-runtime prefix? ?-comment string? ?-directory rootpath? ?-exclude exclude? ?--? ?path...?
+

From http://wiki.tcl.tk/15158

+

This command constructs a zip archive from a directory tree +using nothing but Tcl 8.6 core features. The resulting zip file should +be compatible with other zip programs - with the possible +exception of unicode support. The files generated by this command use +utf-8 encoding for all filenames and comments and it has been noticed +particularly on Windows the info-zip and the Windows built-in +zip view have rather poor support for this part of the ZIP file +specification. The 7-Zip program does correctly display utf8 +filenames however and the vfs::zip package will use these of +course.

+

If you use

+
::mkzip::mkzip mystuff.tm -zipkit -directory mystuff.vfs
+

it will pack your "mystuff.vfs/" virtual filesystem tree into a +zip archive with a suitable header such that on unix you may mark it +executable and it should run with tclkit. Or you can run it with +tclsh or wish 8.6 if you like.

+

To change the executable header, specify the -runtime +"preface" where preface is a file containing code you want +prefixed. For instance, on Windows you can create a self-extracting +zip archive using

+
+mkzip mystuff.exe -directory mystuff.vfs -runtime unzipsfx.exe
+
+

The "unzipsfx.exe" is the Info-Zip self-extracting stub.

+

Accepted options:

+
+
-runtime path
+

This option specifies a file to use as prefix to the actual zip +archive. If specified -zipkit will be ignored.

+
-zipkit
+

Instructs the command to generate a prefix which makes the archive a +zip-based starkit. Ignored if -runtime is present.

+
-comment string
+

This options specifies a global comment to place into the generated +archive.

+
-directory path
+

This option specifies the directory to place into the generated +archive. If specified any argument paths are ignored.

+
-exclude list
+

This option specifies a list of glob patterns. All paths matching at +least one of the patterns are not placed into the generated archive. +This option defaults to

+
+    CVS/* */CVS/* *~ ".#*" "*/.#*"
+
+
+
--
+

This option signals the end of the options, forcing processing of all +further words as arguments, even if they begin with a dash character.

+
+

Accepted arguments:

+
+
path path
+

Each path is a directory or file to place into the generated archive. +Note however that these will be ignored when option -directory +is specified.

+
+
+
+

Bugs, Ideas, Feedback

+

This document, and the package it describes, will undoubtedly contain +bugs and other problems. +Please report such in the category zipfile of the +Tcllib Trackers. +Please also report any ideas for enhancements you may have for either +package and/or documentation.

+
+ +

Category

+

File

+
+ +
ADDED embedded/www/tcllib/toc.html Index: embedded/www/tcllib/toc.html ================================================================== --- embedded/www/tcllib/toc.html +++ embedded/www/tcllib/toc.html @@ -0,0 +1,1794 @@ +
+ +
[ + Keyword Index +| Categories +| Modules +| Applications + ]
+

Table Of Contents

+

tcllib

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aesImplementation of the AES block cipher
ascii85ascii85-encode/decode binary data
asnASN.1 BER encoder/decoder
autoproxyAutomatic HTTP proxy usage and authentication
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
base64base64-encode/decode binary data
beeBitTorrent Serialization Format Encoder/Decoder
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
bibtexParse bibtex files
blowfishImplementation of the Blowfish block cipher
cache::asyncAsynchronous in-memory cache
cksumCalculate a cksum(1) compatible checksum
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
cmdlineProcedures to process command lines and options.
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
controlProcedures for control flow structures.
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
counterProcedures for counters and histograms
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
cronTool for automating the period callback of commands
csvProcedures to handle CSV data.
debugdebug narrative - core
debug::callerdebug narrative - caller
debug::heartbeatdebug narrative - heartbeat
debug::timestampdebug narrative - timestamping
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
desImplementation of the DES and triple-DES ciphers
dicttoolDictionary Tools
dnsTcl Domain Name Service Client
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools2idx_introductionDocTools - Keyword indices
doctools2toc_introductionDocTools - Tables of Contents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::idxdocidx - Processing indices
doctools::idxHolding keyword indices
doctools::idx::exportExporting keyword indices
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::importImporting keyword indices
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcatMessage catalog management for the various document parsers
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
doctools::tocHolding tables of contents
doctools::tocdoctoc - Processing tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::importImporting keyword indices
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
dtpliteLightweight DocTools Markup Processor
dtpliteLightweight DocTools Markup Processor
fileutilProcedures implementing some file utilities
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
ftpdTcl FTP server implementation
generatorProcedures for creating and using generators.
gpxExtracts waypoints, tracks and routes from GPX files
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
hookHooks
htmlProcedures to generate HTML structures
htmlparseProcedures to parse HTML strings
huddleCreate and manipulate huddle object
identIdent protocol client
imap4imap client-side tcl implementation of imap protocol
inifileParsing of Windows INI files
interpInterp creation and aliasing
ircCreate IRC connection and interface.
javascriptProcedures to generate HTML and Java Script structures.
jpegJPEG querying and manipulation of meta data
jsonJSON parser
json::writeJSON generation
lambdaUtility commands for anonymous procedures
ldapLDAP client
ldapxLDAP extended object interface
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
mapprojMap projection routines
markdownConverts Markdown text to HTML
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::calculus::symdiffSymbolic differentiation for Tcl
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::exactExact Real Arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
md4MD4 Message-Digest Algorithm
md5MD5 Message-Digest Algorithm
md5cryptMD5-based password encryption
mimeManipulation of MIME body parts
mpexpandMarkup processor
multiplexerOne-to-many communication with sockets.
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
namespacexNamespace utility commands
ncgiProcedures to manipulate CGI values.
nettoolTools for networked applications
nmeaProcess NMEA data
nnsName service facility, Commandline Client Application
nns_introName service facility, introduction
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
nntpTcl client for the NNTP protocol
ntp_timeTcl Time Service Client
oauthoauth API base signature
oo::utilUtility commands for TclOO
oo::utilUtility commands for TclOO
otpOne-Time Passwords
pageParser Generator
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
picoircSmall and simple embeddable IRC client.
pkiImplementation of the public key cipher
pluginmgrManage a plugin
pngPNG querying and manipulation of meta data
pop3Tcl client for POP3 email protocol
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
practclThe Practcl Module
processmanTool for automating the period callback of commands
profilerTcl source code profiler
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::cparam::configuration::teaC/PARAM, Canned configuration, TEA
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::nxTcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt::utilGeneral utilities
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parse_pegParser Tools PEG Parser
pt_parser_apiParser API
pt_peg_opParser Tools PE Grammar Utility Operations
rc4Implementation of the RC4 stream cipher
rcsRCS low level utilities
reportCreate and manipulate report objects
restdefine REST web APIs and call them inline or asychronously
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
S3Amazon S3 Web Service Interface
SASLImplementation of SASL mechanisms for Tcl
SASL::NTLMImplementation of SASL NTLM mechanism for Tcl
SASL::SCRAMImplementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleTokenImplementation of SASL NTLM mechanism for Tcl
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
smtpClient-side tcl implementation of the smtp protocol
smtpdTcl SMTP server implementation
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
soundexSoundex
stooopObject oriented extension.
string::tokenRegex based iterative lexing
string::token::shellParsing of shell command line
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
sumCalculate a sum(1) compatible checksum
switchedswitch/option management.
tarTar file creation, extraction & manipulation
tcl::chan::catConcatenation channel
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::randomseedUtilities for random channels
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::coreBasic reflected/virtual channel transform support
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
tclDESImplementation of the DES and triple-DES ciphers
tclDESjrImplementation of the DES and triple-DES ciphers
tcldocstripTcl-based Docstrip Processor
tcllib_ipIPv4 and IPv6 address manipulation
tclrep/machineparametersCompute double precision machine parameters.
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
tepam::doc_genTEPAM DOC Generation, reference manual
tepam::procedureTEPAM procedure, reference manual
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::expanderProcedures to process templates and expand text.
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
throwthrow - Throw an error exception with a message
tieArray persistence, standard data sources
tieArray persistence
tiffTIFF reading, writing, and querying and manipulation of meta data
toolDictionary Tools
tool::dict_ensembleDictionary Tools
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
treeqlQuery tree objects
trytry - Trap and process errors and exceptions
udpclusterUDP Peer-to-Peer cluster
ueventUser events
uevent::onidleRequest merging and deferal to idle time
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
unitsunit conversion
uriURI utilities
uri_urnURI utilities, URN scheme
uuencodeUU-encode/decode binary data
uuidUUID generation and comparison
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
websocketTcl implementation of the websocket protocol
wipWord Interpreter
xsxpeXtremely Simple Xml Parser
yamlYAML Format Encoder/Decoder
yencodeY-encode/decode binary data
zipfile::decodeAccess to zip archives
zipfile::encodeGeneration of zip archives
zipfile::mkzipBuild a zip archive
+
ADDED embedded/www/toc.html Index: embedded/www/toc.html ================================================================== --- embedded/www/toc.html +++ embedded/www/toc.html @@ -0,0 +1,3937 @@ +
+ +
[ + Keyword Index +| Categories +| Modules +| Applications + ]
+

Table Of Contents

+

+
By Categories
+
Argument entry form, mega widget
+ + + + + +
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
+
Benchmark tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
CGI programming
+ + + + + + + + + + + + + + + + + + + + + +
htmlProcedures to generate HTML structures
javascriptProcedures to generate HTML and Java Script structures.
jsonJSON parser
json::writeJSON generation
ncgiProcedures to manipulate CGI values.
+
Channels
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::randomseedUtilities for random channels
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::coreBasic reflected/virtual channel transform support
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
Coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
Data structures
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
counterProcedures for counters and histograms
reportCreate and manipulate report objects
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
treeqlQuery tree objects
+
debugging, tracing, and logging
+ + + + + + + + + + + + + + + + + +
debugdebug narrative - core
debug::callerdebug narrative - caller
debug::heartbeatdebug narrative - heartbeat
debug::timestampdebug narrative - timestamping
+
Documentation tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools2idx_introductionDocTools - Keyword indices
doctools2toc_introductionDocTools - Tables of Contents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::idxHolding keyword indices
doctools::idxdocidx - Processing indices
doctools::idx::exportExporting keyword indices
doctools::idx::importImporting keyword indices
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcatMessage catalog management for the various document parsers
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
doctools::tocHolding tables of contents
doctools::tocdoctoc - Processing tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::importImporting keyword indices
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
dtpliteLightweight DocTools Markup Processor
dtpliteLightweight DocTools Markup Processor
mpexpandMarkup processor
tcldocstripTcl-based Docstrip Processor
tepam::doc_genTEPAM DOC Generation, reference manual
textutil::expanderProcedures to process templates and expand text.
+
File
+ + + + + + + + + + + + + +
zipfile::decodeAccess to zip archives
zipfile::encodeGeneration of zip archives
zipfile::mkzipBuild a zip archive
+
File formats
+ + + + + + + + + + + + + + + + + + + + + +
gpxExtracts waypoints, tracks and routes from GPX files
jpegJPEG querying and manipulation of meta data
pngPNG querying and manipulation of meta data
tarTar file creation, extraction & manipulation
tiffTIFF reading, writing, and querying and manipulation of meta data
+
Grammars and finite automata
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
Hashes, checksums, and encryption
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aesImplementation of the AES block cipher
blowfishImplementation of the Blowfish block cipher
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
desImplementation of the DES and triple-DES ciphers
md4MD4 Message-Digest Algorithm
md5MD5 Message-Digest Algorithm
md5cryptMD5-based password encryption
otpOne-Time Passwords
pkiImplementation of the public key cipher
rc4Implementation of the RC4 stream cipher
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
soundexSoundex
sumCalculate a sum(1) compatible checksum
tclDESImplementation of the DES and triple-DES ciphers
tclDESjrImplementation of the DES and triple-DES ciphers
uuidUUID generation and comparison
+
Mathematics
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::exactExact Real Arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
Networking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
asnASN.1 BER encoder/decoder
autoproxyAutomatic HTTP proxy usage and authentication
beeBitTorrent Serialization Format Encoder/Decoder
dnsTcl Domain Name Service Client
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
ftpdTcl FTP server implementation
identIdent protocol client
ircCreate IRC connection and interface.
ldapLDAP client
ldapxLDAP extended object interface
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nmeaProcess NMEA data
nnsName service facility, Commandline Client Application
nns_introName service facility, introduction
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
nntpTcl client for the NNTP protocol
ntp_timeTcl Time Service Client
oauthoauth API base signature
picoircSmall and simple embeddable IRC client.
pop3Tcl client for POP3 email protocol
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
S3Amazon S3 Web Service Interface
SASLImplementation of SASL mechanisms for Tcl
SASL::NTLMImplementation of SASL NTLM mechanism for Tcl
SASL::SCRAMImplementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleTokenImplementation of SASL NTLM mechanism for Tcl
smtpClient-side tcl implementation of the smtp protocol
smtpdTcl SMTP server implementation
tcllib_ipIPv4 and IPv6 address manipulation
udpclusterUDP Peer-to-Peer cluster
uriURI utilities
uri_urnURI utilities, URN scheme
websocketTcl implementation of the websocket protocol
+
Page Parser Generator
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pageParser Generator
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
Parsing and Grammars
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::cparam::configuration::teaC/PARAM, Canned configuration, TEA
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::nxTcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt::utilGeneral utilities
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parse_pegParser Tools PEG Parser
pt_parser_apiParser API
pt_peg_opParser Tools PE Grammar Utility Operations
+
Procedures, arguments, parameters, options
+ + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::procedureTEPAM procedure, reference manual
+
Programming tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cmdlineProcedures to process command lines and options.
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
controlProcedures for control flow structures.
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
fileutilProcedures implementing some file utilities
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
hookHooks
interpInterp creation and aliasing
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
multiplexerOne-to-many communication with sockets.
pluginmgrManage a plugin
profilerTcl source code profiler
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
stooopObject oriented extension.
switchedswitch/option management.
tieArray persistence
tieArray persistence, standard data sources
ueventUser events
wipWord Interpreter
+
System
+ + + + + + + + + + + + + +
cronTool for automating the period callback of commands
nettoolTools for networked applications
processmanTool for automating the period callback of commands
+
TclOO
+ + + + + +
practclThe Practcl Module
+
Terminal control
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
Text formatter plugin
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
+
Text processing
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
base64base64-encode/decode binary data
bibtexParse bibtex files
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
csvProcedures to handle CSV data.
htmlparseProcedures to parse HTML strings
inifileParsing of Windows INI files
markdownConverts Markdown text to HTML
mimeManipulation of MIME body parts
rcsRCS low level utilities
string::tokenRegex based iterative lexing
string::token::shellParsing of shell command line
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
uuencodeUU-encode/decode binary data
xsxpeXtremely Simple Xml Parser
yencodeY-encode/decode binary data
+
Transfer module
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
Unfiled
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cache::asyncAsynchronous in-memory cache
generatorProcedures for creating and using generators.
huddleCreate and manipulate huddle object
imap4imap client-side tcl implementation of imap protocol
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
mapprojMap projection routines
math::calculus::symdiffSymbolic differentiation for Tcl
namespacexNamespace utility commands
restdefine REST web APIs and call them inline or asychronously
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
tclrep/machineparametersCompute double precision machine parameters.
uevent::onidleRequest merging and deferal to idle time
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
unitsunit conversion
yamlYAML Format Encoder/Decoder
+
Utilites
+ + + + + +
dicttoolDictionary Tools
+
Utility
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lambdaUtility commands for anonymous procedures
oo::utilUtility commands for TclOO
oo::utilUtility commands for TclOO
throwthrow - Throw an error exception with a message
toolDictionary Tools
tool::dict_ensembleDictionary Tools
trytry - Trap and process errors and exceptions
+
Validation, Type checking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
By Type
+
Applications
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
dtpliteLightweight DocTools Markup Processor
nnsName service facility, Commandline Client Application
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
pageParser Generator
ptParser Tools Application
tcldocstripTcl-based Docstrip Processor
+
Modules
+
aes
+ + + + + +
aesImplementation of the AES block cipher
+
amazon-s3
+ + + + + + + + + +
S3Amazon S3 Web Service Interface
xsxpeXtremely Simple Xml Parser
+
asn
+ + + + + +
asnASN.1 BER encoder/decoder
+
base32
+ + + + + + + + + + + + + +
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
+
base64
+ + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base64base64-encode/decode binary data
uuencodeUU-encode/decode binary data
yencodeY-encode/decode binary data
+
bee
+ + + + + +
beeBitTorrent Serialization Format Encoder/Decoder
+
bench
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
bibtex
+ + + + + +
bibtexParse bibtex files
+
blowfish
+ + + + + +
blowfishImplementation of the Blowfish block cipher
+
cache
+ + + + + +
cache::asyncAsynchronous in-memory cache
+
clock
+ + + + + + + + + +
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
+
cmdline
+ + + + + +
cmdlineProcedures to process command lines and options.
+
comm
+ + + + + + + + + +
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
+
control
+ + + + + +
controlProcedures for control flow structures.
+
coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
counter
+ + + + + +
counterProcedures for counters and histograms
+
crc
+ + + + + + + + + + + + + + + + + +
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
sumCalculate a sum(1) compatible checksum
+
cron
+ + + + + +
cronTool for automating the period callback of commands
+
csv
+ + + + + +
csvProcedures to handle CSV data.
+
debug
+ + + + + + + + + + + + + + + + + +
debugdebug narrative - core
debug::callerdebug narrative - caller
debug::heartbeatdebug narrative - heartbeat
debug::timestampdebug narrative - timestamping
+
des
+ + + + + + + + + + + + + +
desImplementation of the DES and triple-DES ciphers
tclDESImplementation of the DES and triple-DES ciphers
tclDESjrImplementation of the DES and triple-DES ciphers
+
dicttool
+ + + + + +
dicttoolDictionary Tools
+
dns
+ + + + + + + + + +
dnsTcl Domain Name Service Client
tcllib_ipIPv4 and IPv6 address manipulation
+
docstrip
+ + + + + + + + + +
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
+
doctools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::idxdocidx - Processing indices
doctools::tocdoctoc - Processing tables of contents
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
mpexpandMarkup processor
+
doctools2base
+ + + + + + + + + + + + + + + + + +
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::msgcatMessage catalog management for the various document parsers
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
+
doctools2idx
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2idx_introductionDocTools - Keyword indices
doctools::idxHolding keyword indices
doctools::idx::exportExporting keyword indices
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::importImporting keyword indices
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
+
doctools2toc
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2toc_introductionDocTools - Tables of Contents
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::tocHolding tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::importImporting keyword indices
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
+
dtplite
+ + + + + +
dtpliteLightweight DocTools Markup Processor
+
fileutil
+ + + + + + + + + + + + + + + + + +
fileutilProcedures implementing some file utilities
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
+
ftp
+ + + + + + + + + +
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
+
ftpd
+ + + + + +
ftpdTcl FTP server implementation
+
fumagic
+ + + + + + + + + + + + + + + + + +
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
+
generator
+ + + + + +
generatorProcedures for creating and using generators.
+
gpx
+ + + + + +
gpxExtracts waypoints, tracks and routes from GPX files
+
grammar_aycock
+ + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
+
grammar_fa
+ + + + + + + + + + + + + + + + + +
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
+
grammar_me
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
+
grammar_peg
+ + + + + + + + + +
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
hook
+ + + + + +
hookHooks
+
html
+ + + + + +
htmlProcedures to generate HTML structures
+
htmlparse
+ + + + + +
htmlparseProcedures to parse HTML strings
+
http
+ + + + + +
autoproxyAutomatic HTTP proxy usage and authentication
+
ident
+ + + + + +
identIdent protocol client
+
imap4
+ + + + + +
imap4imap client-side tcl implementation of imap protocol
+
inifile
+ + + + + +
inifileParsing of Windows INI files
+
interp
+ + + + + + + + + + + + + +
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
interpInterp creation and aliasing
+
irc
+ + + + + + + + + +
ircCreate IRC connection and interface.
picoircSmall and simple embeddable IRC client.
+
javascript
+ + + + + +
javascriptProcedures to generate HTML and Java Script structures.
+
jpeg
+ + + + + +
jpegJPEG querying and manipulation of meta data
+
json
+ + + + + + + + + +
jsonJSON parser
json::writeJSON generation
+
lambda
+ + + + + +
lambdaUtility commands for anonymous procedures
+
ldap
+ + + + + + + + + +
ldapLDAP client
ldapxLDAP extended object interface
+
log
+ + + + + + + + + + + + + + + + + +
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
+
map
+ + + + + + + + + + + + + + + + + +
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
+
mapproj
+ + + + + +
mapprojMap projection routines
+
markdown
+ + + + + +
markdownConverts Markdown text to HTML
+
math
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::calculus::symdiffSymbolic differentiation for Tcl
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::exactExact Real Arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
tclrep/machineparametersCompute double precision machine parameters.
+
md4
+ + + + + +
md4MD4 Message-Digest Algorithm
+
md5
+ + + + + +
md5MD5 Message-Digest Algorithm
+
md5crypt
+ + + + + +
md5cryptMD5-based password encryption
+
mime
+ + + + + + + + + +
mimeManipulation of MIME body parts
smtpClient-side tcl implementation of the smtp protocol
+
multiplexer
+ + + + + +
multiplexerOne-to-many communication with sockets.
+
namespacex
+ + + + + +
namespacexNamespace utility commands
+
ncgi
+ + + + + +
ncgiProcedures to manipulate CGI values.
+
nettool
+ + + + + +
nettoolTools for networked applications
+
nmea
+ + + + + +
nmeaProcess NMEA data
+
nns
+ + + + + + + + + + + + + + + + + + + + + + + + + +
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nns_introName service facility, introduction
+
nntp
+ + + + + +
nntpTcl client for the NNTP protocol
+
ntp
+ + + + + +
ntp_timeTcl Time Service Client
+
oauth
+ + + + + +
oauthoauth API base signature
+
ooutil
+ + + + + +
oo::utilUtility commands for TclOO
+
otp
+ + + + + +
otpOne-Time Passwords
+
page
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
pki
+ + + + + +
pkiImplementation of the public key cipher
+
pluginmgr
+ + + + + +
pluginmgrManage a plugin
+
png
+ + + + + +
pngPNG querying and manipulation of meta data
+
pop3
+ + + + + +
pop3Tcl client for POP3 email protocol
+
pop3d
+ + + + + + + + + + + + + +
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
+
practcl
+ + + + + +
practclThe Practcl Module
+
processman
+ + + + + +
processmanTool for automating the period callback of commands
+
profiler
+ + + + + +
profilerTcl source code profiler
+
pt
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::cparam::configuration::teaC/PARAM, Canned configuration, TEA
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::nxTcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt::utilGeneral utilities
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parse_pegParser Tools PEG Parser
pt_parser_apiParser API
pt_peg_opParser Tools PE Grammar Utility Operations
+
rc4
+ + + + + +
rc4Implementation of the RC4 stream cipher
+
rcs
+ + + + + +
rcsRCS low level utilities
+
report
+ + + + + +
reportCreate and manipulate report objects
+
rest
+ + + + + +
restdefine REST web APIs and call them inline or asychronously
+
ripemd
+ + + + + + + + + +
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
+
sasl
+ + + + + + + + + + + + + + + + + +
SASLImplementation of SASL mechanisms for Tcl
SASL::NTLMImplementation of SASL NTLM mechanism for Tcl
SASL::SCRAMImplementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleTokenImplementation of SASL NTLM mechanism for Tcl
+
sha1
+ + + + + + + + + +
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
+
simulation
+ + + + + + + + + + + + + +
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
smtpd
+ + + + + +
smtpdTcl SMTP server implementation
+
snit
+ + + + + + + + + +
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
+
soundex
+ + + + + +
soundexSoundex
+
stooop
+ + + + + + + + + +
stooopObject oriented extension.
switchedswitch/option management.
+
string
+ + + + + + + + + +
string::tokenRegex based iterative lexing
string::token::shellParsing of shell command line
+
stringprep
+ + + + + + + + + + + + + + + + + +
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
+
struct
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
+
tar
+ + + + + +
tarTar file creation, extraction & manipulation
+
tepam
+ + + + + + + + + + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
tepam::doc_genTEPAM DOC Generation, reference manual
tepam::procedureTEPAM procedure, reference manual
+
term
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
textutil
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::expanderProcedures to process templates and expand text.
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
+
tie
+ + + + + + + + + +
tieArray persistence
tieArray persistence, standard data sources
+
tiff
+ + + + + +
tiffTIFF reading, writing, and querying and manipulation of meta data
+
tool
+ + + + + + + + + + + + + +
oo::utilUtility commands for TclOO
toolDictionary Tools
tool::dict_ensembleDictionary Tools
+
transfer
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
treeql
+ + + + + +
treeqlQuery tree objects
+
try
+ + + + + + + + + +
throwthrow - Throw an error exception with a message
trytry - Trap and process errors and exceptions
+
udpcluster
+ + + + + +
udpclusterUDP Peer-to-Peer cluster
+
uev
+ + + + + + + + + +
ueventUser events
uevent::onidleRequest merging and deferal to idle time
+
units
+ + + + + +
unitsunit conversion
+
uri
+ + + + + + + + + +
uriURI utilities
uri_urnURI utilities, URN scheme
+
uuid
+ + + + + +
uuidUUID generation and comparison
+
valtype
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
virtchannel_base
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::randomseedUtilities for random channels
+
virtchannel_core
+ + + + + + + + + + + + + +
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::transform::coreBasic reflected/virtual channel transform support
+
virtchannel_transform
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
websocket
+ + + + + +
websocketTcl implementation of the websocket protocol
+
wip
+ + + + + +
wipWord Interpreter
+
yaml
+ + + + + + + + + +
huddleCreate and manipulate huddle object
yamlYAML Format Encoder/Decoder
+
zip
+ + + + + + + + + + + + + +
zipfile::decodeAccess to zip archives
zipfile::encodeGeneration of zip archives
zipfile::mkzipBuild a zip archive
+
ADDED embedded/www/toc0.html Index: embedded/www/toc0.html ================================================================== --- embedded/www/toc0.html +++ embedded/www/toc0.html @@ -0,0 +1,1877 @@ +
+ +
[ + Keyword Index +| Categories +| Modules +| Applications + ]
+

Table Of Contents

+

+
By Categories
+
Argument entry form, mega widget
+ + + + + +
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
+
Benchmark tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
CGI programming
+ + + + + + + + + + + + + + + + + + + + + +
htmlProcedures to generate HTML structures
javascriptProcedures to generate HTML and Java Script structures.
jsonJSON parser
json::writeJSON generation
ncgiProcedures to manipulate CGI values.
+
Channels
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::randomseedUtilities for random channels
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::coreBasic reflected/virtual channel transform support
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
Coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
Data structures
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
counterProcedures for counters and histograms
reportCreate and manipulate report objects
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
treeqlQuery tree objects
+
debugging, tracing, and logging
+ + + + + + + + + + + + + + + + + +
debugdebug narrative - core
debug::callerdebug narrative - caller
debug::heartbeatdebug narrative - heartbeat
debug::timestampdebug narrative - timestamping
+
Documentation tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools2idx_introductionDocTools - Keyword indices
doctools2toc_introductionDocTools - Tables of Contents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::idxHolding keyword indices
doctools::idxdocidx - Processing indices
doctools::idx::exportExporting keyword indices
doctools::idx::importImporting keyword indices
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcatMessage catalog management for the various document parsers
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
doctools::tocHolding tables of contents
doctools::tocdoctoc - Processing tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::importImporting keyword indices
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
dtpliteLightweight DocTools Markup Processor
dtpliteLightweight DocTools Markup Processor
mpexpandMarkup processor
tcldocstripTcl-based Docstrip Processor
tepam::doc_genTEPAM DOC Generation, reference manual
textutil::expanderProcedures to process templates and expand text.
+
File
+ + + + + + + + + + + + + +
zipfile::decodeAccess to zip archives
zipfile::encodeGeneration of zip archives
zipfile::mkzipBuild a zip archive
+
File formats
+ + + + + + + + + + + + + + + + + + + + + +
gpxExtracts waypoints, tracks and routes from GPX files
jpegJPEG querying and manipulation of meta data
pngPNG querying and manipulation of meta data
tarTar file creation, extraction & manipulation
tiffTIFF reading, writing, and querying and manipulation of meta data
+
Grammars and finite automata
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
Hashes, checksums, and encryption
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
aesImplementation of the AES block cipher
blowfishImplementation of the Blowfish block cipher
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
desImplementation of the DES and triple-DES ciphers
md4MD4 Message-Digest Algorithm
md5MD5 Message-Digest Algorithm
md5cryptMD5-based password encryption
otpOne-Time Passwords
pkiImplementation of the public key cipher
rc4Implementation of the RC4 stream cipher
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
soundexSoundex
sumCalculate a sum(1) compatible checksum
tclDESImplementation of the DES and triple-DES ciphers
tclDESjrImplementation of the DES and triple-DES ciphers
uuidUUID generation and comparison
+
Mathematics
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::exactExact Real Arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
Networking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
asnASN.1 BER encoder/decoder
autoproxyAutomatic HTTP proxy usage and authentication
beeBitTorrent Serialization Format Encoder/Decoder
dnsTcl Domain Name Service Client
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
ftpdTcl FTP server implementation
identIdent protocol client
ircCreate IRC connection and interface.
ldapLDAP client
ldapxLDAP extended object interface
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nmeaProcess NMEA data
nnsName service facility, Commandline Client Application
nns_introName service facility, introduction
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
nntpTcl client for the NNTP protocol
ntp_timeTcl Time Service Client
oauthoauth API base signature
picoircSmall and simple embeddable IRC client.
pop3Tcl client for POP3 email protocol
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
S3Amazon S3 Web Service Interface
SASLImplementation of SASL mechanisms for Tcl
SASL::NTLMImplementation of SASL NTLM mechanism for Tcl
SASL::SCRAMImplementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleTokenImplementation of SASL NTLM mechanism for Tcl
smtpClient-side tcl implementation of the smtp protocol
smtpdTcl SMTP server implementation
tcllib_ipIPv4 and IPv6 address manipulation
udpclusterUDP Peer-to-Peer cluster
uriURI utilities
uri_urnURI utilities, URN scheme
websocketTcl implementation of the websocket protocol
+
Page Parser Generator
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pageParser Generator
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
Parsing and Grammars
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ptParser Tools Application
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::cparam::configuration::teaC/PARAM, Canned configuration, TEA
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::nxTcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt::utilGeneral utilities
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parse_pegParser Tools PEG Parser
pt_parser_apiParser API
pt_peg_opParser Tools PE Grammar Utility Operations
+
Procedures, arguments, parameters, options
+ + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::procedureTEPAM procedure, reference manual
+
Programming tools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cmdlineProcedures to process command lines and options.
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
controlProcedures for control flow structures.
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
fileutilProcedures implementing some file utilities
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
hookHooks
interpInterp creation and aliasing
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
multiplexerOne-to-many communication with sockets.
pluginmgrManage a plugin
profilerTcl source code profiler
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
stooopObject oriented extension.
switchedswitch/option management.
tieArray persistence
tieArray persistence, standard data sources
ueventUser events
wipWord Interpreter
+
System
+ + + + + + + + + + + + + +
cronTool for automating the period callback of commands
nettoolTools for networked applications
processmanTool for automating the period callback of commands
+
TclOO
+ + + + + +
practclThe Practcl Module
+
Terminal control
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
Text formatter plugin
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
+
Text processing
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
base64base64-encode/decode binary data
bibtexParse bibtex files
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
csvProcedures to handle CSV data.
htmlparseProcedures to parse HTML strings
inifileParsing of Windows INI files
markdownConverts Markdown text to HTML
mimeManipulation of MIME body parts
rcsRCS low level utilities
string::tokenRegex based iterative lexing
string::token::shellParsing of shell command line
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
uuencodeUU-encode/decode binary data
xsxpeXtremely Simple Xml Parser
yencodeY-encode/decode binary data
+
Transfer module
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
Unfiled
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
cache::asyncAsynchronous in-memory cache
generatorProcedures for creating and using generators.
huddleCreate and manipulate huddle object
imap4imap client-side tcl implementation of imap protocol
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
mapprojMap projection routines
math::calculus::symdiffSymbolic differentiation for Tcl
namespacexNamespace utility commands
restdefine REST web APIs and call them inline or asychronously
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
tclrep/machineparametersCompute double precision machine parameters.
uevent::onidleRequest merging and deferal to idle time
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
unitsunit conversion
yamlYAML Format Encoder/Decoder
+
Utilites
+ + + + + +
dicttoolDictionary Tools
+
Utility
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lambdaUtility commands for anonymous procedures
oo::utilUtility commands for TclOO
oo::utilUtility commands for TclOO
throwthrow - Throw an error exception with a message
toolDictionary Tools
tool::dict_ensembleDictionary Tools
trytry - Trap and process errors and exceptions
+
Validation, Type checking
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
ADDED embedded/www/toc1.html Index: embedded/www/toc1.html ================================================================== --- embedded/www/toc1.html +++ embedded/www/toc1.html @@ -0,0 +1,2128 @@ +
+ +
[ + Keyword Index +| Categories +| Modules +| Applications + ]
+

Table Of Contents

+

+
Modules
+
aes
+ + + + + +
aesImplementation of the AES block cipher
+
amazon-s3
+ + + + + + + + + +
S3Amazon S3 Web Service Interface
xsxpeXtremely Simple Xml Parser
+
asn
+ + + + + +
asnASN.1 BER encoder/decoder
+
base32
+ + + + + + + + + + + + + +
base32base32 standard encoding
base32::coreExpanding basic base32 maps
base32::hexbase32 extended hex encoding
+
base64
+ + + + + + + + + + + + + + + + + +
ascii85ascii85-encode/decode binary data
base64base64-encode/decode binary data
uuencodeUU-encode/decode binary data
yencodeY-encode/decode binary data
+
bee
+ + + + + +
beeBitTorrent Serialization Format Encoder/Decoder
+
bench
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
benchbench - Processing benchmark suites
bench::inbench::in - Reading benchmark results
bench::out::csvbench::out::csv - Formatting benchmark results as CSV
bench::out::textbench::out::text - Formatting benchmark results as human readable text
bench_introbench introduction
bench_lang_introbench language introduction
bench_lang_specbench language specification
+
bibtex
+ + + + + +
bibtexParse bibtex files
+
blowfish
+ + + + + +
blowfishImplementation of the Blowfish block cipher
+
cache
+ + + + + +
cache::asyncAsynchronous in-memory cache
+
clock
+ + + + + + + + + +
clock_iso8601Parsing ISO 8601 dates/times
clock_rfc2822Parsing ISO 8601 dates/times
+
cmdline
+ + + + + +
cmdlineProcedures to process command lines and options.
+
comm
+ + + + + + + + + +
commA remote communication facility for Tcl (8.3 and later)
comm_wireThe comm wire protocol
+
control
+ + + + + +
controlProcedures for control flow structures.
+
coroutine
+ + + + + + + + + +
coroutineCoroutine based event and IO handling
coroutine::autoAutomatic event and IO coroutine awareness
+
counter
+ + + + + +
counterProcedures for counters and histograms
+
crc
+ + + + + + + + + + + + + + + + + +
cksumCalculate a cksum(1) compatible checksum
crc16Perform a 16bit Cyclic Redundancy Check
crc32Perform a 32bit Cyclic Redundancy Check
sumCalculate a sum(1) compatible checksum
+
cron
+ + + + + +
cronTool for automating the period callback of commands
+
csv
+ + + + + +
csvProcedures to handle CSV data.
+
debug
+ + + + + + + + + + + + + + + + + +
debugdebug narrative - core
debug::callerdebug narrative - caller
debug::heartbeatdebug narrative - heartbeat
debug::timestampdebug narrative - timestamping
+
des
+ + + + + + + + + + + + + +
desImplementation of the DES and triple-DES ciphers
tclDESImplementation of the DES and triple-DES ciphers
tclDESjrImplementation of the DES and triple-DES ciphers
+
dicttool
+ + + + + +
dicttoolDictionary Tools
+
dns
+ + + + + + + + + +
dnsTcl Domain Name Service Client
tcllib_ipIPv4 and IPv6 address manipulation
+
docstrip
+ + + + + + + + + +
docstripDocstrip style source code extraction
docstrip_utilDocstrip-related utilities
+
doctools
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
docidx_introdocidx introduction
docidx_lang_cmdrefdocidx language command reference
docidx_lang_faqdocidx language faq
docidx_lang_introdocidx language introduction
docidx_lang_syntaxdocidx language syntax
docidx_plugin_apirefdocidx plugin API reference
doctoc_introdoctoc introduction
doctoc_lang_cmdrefdoctoc language command reference
doctoc_lang_faqdoctoc language faq
doctoc_lang_introdoctoc language introduction
doctoc_lang_syntaxdoctoc language syntax
doctoc_plugin_apirefdoctoc plugin API reference
doctoolsdoctools - Processing documents
doctools::changelogProcessing text in Emacs ChangeLog format
doctools::cvsProcessing text in 'cvs log' format
doctools::idxdocidx - Processing indices
doctools::tocdoctoc - Processing tables of contents
doctools_introdoctools introduction
doctools_lang_cmdrefdoctools language command reference
doctools_lang_faqdoctools language faq
doctools_lang_introdoctools language introduction
doctools_lang_syntaxdoctools language syntax
doctools_plugin_apirefdoctools plugin API reference
mpexpandMarkup processor
+
doctools2base
+ + + + + + + + + + + + + + + + + +
doctools::html::cssdefaultsDefault CSS style for HTML export plugins
doctools::msgcatMessage catalog management for the various document parsers
doctools::nroff::man_macrosDefault CSS style for NROFF export plugins
doctools::tcl::parseProcessing text in 'subst -novariables' format
+
doctools2idx
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2idx_introductionDocTools - Keyword indices
doctools::idxHolding keyword indices
doctools::idx::exportExporting keyword indices
doctools::idx::export::docidxdocidx export plugin
doctools::idx::export::htmlHTML export plugin
doctools::idx::export::jsonJSON export plugin
doctools::idx::export::nroffnroff export plugin
doctools::idx::export::textplain text export plugin
doctools::idx::export::wikiwiki export plugin
doctools::idx::importImporting keyword indices
doctools::idx::import::docidxdocidx import plugin
doctools::idx::import::jsonJSON import plugin
doctools::idx::parseParsing text in docidx format
doctools::idx::structureDocidx serialization utilities
doctools::msgcat::idx::cMessage catalog for the docidx parser (C)
doctools::msgcat::idx::deMessage catalog for the docidx parser (DE)
doctools::msgcat::idx::enMessage catalog for the docidx parser (EN)
doctools::msgcat::idx::frMessage catalog for the docidx parser (FR)
+
doctools2toc
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
doctools2toc_introductionDocTools - Tables of Contents
doctools::msgcat::toc::cMessage catalog for the doctoc parser (C)
doctools::msgcat::toc::deMessage catalog for the doctoc parser (DE)
doctools::msgcat::toc::enMessage catalog for the doctoc parser (EN)
doctools::msgcat::toc::frMessage catalog for the doctoc parser (FR)
doctools::tocHolding tables of contents
doctools::toc::exportExporting tables of contents
doctools::toc::export::doctocdoctoc export plugin
doctools::toc::export::htmlHTML export plugin
doctools::toc::export::jsonJSON export plugin
doctools::toc::export::nroffnroff export plugin
doctools::toc::export::textplain text export plugin
doctools::toc::export::wikiwiki export plugin
doctools::toc::importImporting keyword indices
doctools::toc::import::doctocdoctoc import plugin
doctools::toc::import::jsonJSON import plugin
doctools::toc::parseParsing text in doctoc format
doctools::toc::structureDoctoc serialization utilities
+
dtplite
+ + + + + +
dtpliteLightweight DocTools Markup Processor
+
fileutil
+ + + + + + + + + + + + + + + + + +
fileutilProcedures implementing some file utilities
fileutil::multiMulti-file operation, scatter/gather, standard object
fileutil::multi::opMulti-file operation, scatter/gather
fileutil_traverseIterative directory traversal
+
ftp
+ + + + + + + + + +
ftpClient-side tcl implementation of the ftp protocol
ftp::geturlUri handler for ftp urls
+
ftpd
+ + + + + +
ftpdTcl FTP server implementation
+
fumagic
+ + + + + + + + + + + + + + + + + +
fileutil::magic::cfrontGenerator core for compiler of magic(5) files
fileutil::magic::cgenGenerator core for compiler of magic(5) files
fileutil::magic::filetypeProcedures implementing file-type recognition
fileutil::magic::rtRuntime core for file type recognition engines written in pure Tcl
+
generator
+ + + + + +
generatorProcedures for creating and using generators.
+
gpx
+ + + + + +
gpxExtracts waypoints, tracks and routes from GPX files
+
grammar_aycock
+ + + + + +
grammar::aycockAycock-Horspool-Earley parser generator for Tcl
+
grammar_fa
+ + + + + + + + + + + + + + + + + +
grammar::faCreate and manipulate finite automatons
grammar::fa::dacceptorCreate and use deterministic acceptors
grammar::fa::dexecExecute deterministic finite automatons
grammar::fa::opOperations on finite automatons
+
grammar_me
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
grammar::me::cpuVirtual machine implementation II for parsing token streams
grammar::me::cpu::coreME virtual machine state manipulation
grammar::me::cpu::gasmME assembler
grammar::me::tclVirtual machine implementation I for parsing token streams
grammar::me::utilAST utilities
grammar::me_astVarious representations of ASTs
grammar::me_introIntroduction to virtual machines for parsing token streams
grammar::me_vmVirtual machine for parsing token streams
+
grammar_peg
+ + + + + + + + + +
grammar::pegCreate and manipulate parsing expression grammars
grammar::peg::interpInterpreter for parsing expression grammars
+
hook
+ + + + + +
hookHooks
+
html
+ + + + + +
htmlProcedures to generate HTML structures
+
htmlparse
+ + + + + +
htmlparseProcedures to parse HTML strings
+
http
+ + + + + +
autoproxyAutomatic HTTP proxy usage and authentication
+
ident
+ + + + + +
identIdent protocol client
+
imap4
+ + + + + +
imap4imap client-side tcl implementation of imap protocol
+
inifile
+ + + + + +
inifileParsing of Windows INI files
+
interp
+ + + + + + + + + + + + + +
deleg_methodCreation of comm delegates (snit methods)
deleg_procCreation of comm delegates (procedures)
interpInterp creation and aliasing
+
irc
+ + + + + + + + + +
ircCreate IRC connection and interface.
picoircSmall and simple embeddable IRC client.
+
javascript
+ + + + + +
javascriptProcedures to generate HTML and Java Script structures.
+
jpeg
+ + + + + +
jpegJPEG querying and manipulation of meta data
+
json
+ + + + + + + + + +
jsonJSON parser
json::writeJSON generation
+
lambda
+ + + + + +
lambdaUtility commands for anonymous procedures
+
ldap
+ + + + + + + + + +
ldapLDAP client
ldapxLDAP extended object interface
+
log
+ + + + + + + + + + + + + + + + + +
logProcedures to log messages of libraries and applications.
loggerSystem to control logging of events.
logger::appenderCollection of predefined appenders for logger
logger::utilsUtilities for logger
+
map
+ + + + + + + + + + + + + + + + + +
map::geocode::nominatimResolving geographical names with a Nominatim service
map::slippyCommon code for slippy based map packages
map::slippy::cacheManagement of a tile cache in the local filesystem
map::slippy::fetcherAccessing a server providing tiles for slippy-based maps
+
mapproj
+ + + + + +
mapprojMap projection routines
+
markdown
+ + + + + +
markdownConverts Markdown text to HTML
+
math
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mathTcl Math Library
math::bigfloatArbitrary precision floating-point numbers
math::bignumArbitrary precision integer numbers
math::calculusIntegration and ordinary differential equations
math::calculus::rombergRomberg integration
math::calculus::symdiffSymbolic differentiation for Tcl
math::combinatoricsCombinatorial functions in the Tcl Math Library
math::complexnumbersStraightforward complex number package
math::constantsMathematical and numerical constants
math::decimalGeneral decimal arithmetic
math::exactExact Real Arithmetic
math::fourierDiscrete and fast fourier transforms
math::fuzzyFuzzy comparison of floating-point numbers
math::geometryGeometrical computations
math::interpolateInterpolation routines
math::linearalgebraLinear Algebra
math::numtheoryNumber Theory
math::optimizeOptimisation routines
math::polynomialsPolynomial functions
math::rationalfunctionsPolynomial functions
math::romanTools for creating and manipulating roman numerals
math::specialSpecial mathematical functions
math::statisticsBasic statistical functions and procedures
tclrep/machineparametersCompute double precision machine parameters.
+
md4
+ + + + + +
md4MD4 Message-Digest Algorithm
+
md5
+ + + + + +
md5MD5 Message-Digest Algorithm
+
md5crypt
+ + + + + +
md5cryptMD5-based password encryption
+
mime
+ + + + + + + + + +
mimeManipulation of MIME body parts
smtpClient-side tcl implementation of the smtp protocol
+
multiplexer
+ + + + + +
multiplexerOne-to-many communication with sockets.
+
namespacex
+ + + + + +
namespacexNamespace utility commands
+
ncgi
+ + + + + +
ncgiProcedures to manipulate CGI values.
+
nettool
+ + + + + +
nettoolTools for networked applications
+
nmea
+ + + + + +
nmeaProcess NMEA data
+
nns
+ + + + + + + + + + + + + + + + + + + + + + + + + +
nameservName service facility, Client
nameserv::autoName service facility, Client Extension
nameserv::commonName service facility, shared definitions
nameserv::protocolName service facility, client/server protocol
nameserv::serverName service facility, Server
nns_introName service facility, introduction
+
nntp
+ + + + + +
nntpTcl client for the NNTP protocol
+
ntp
+ + + + + +
ntp_timeTcl Time Service Client
+
oauth
+ + + + + +
oauthoauth API base signature
+
ooutil
+ + + + + +
oo::utilUtility commands for TclOO
+
otp
+ + + + + +
otpOne-Time Passwords
+
page
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
page_intropage introduction
page_pluginmgrpage plugin manager
page_util_flowpage dataflow/treewalker utility
page_util_norm_lemonpage AST normalization, LEMON
page_util_norm_pegpage AST normalization, PEG
page_util_pegpage PEG transformation utilities
page_util_quotepage character quoting utilities
+
pki
+ + + + + +
pkiImplementation of the public key cipher
+
pluginmgr
+ + + + + +
pluginmgrManage a plugin
+
png
+ + + + + +
pngPNG querying and manipulation of meta data
+
pop3
+ + + + + +
pop3Tcl client for POP3 email protocol
+
pop3d
+ + + + + + + + + + + + + +
pop3dTcl POP3 server implementation
pop3d::dboxSimple mailbox database for pop3d
pop3d::udbSimple user database for pop3d
+
practcl
+ + + + + +
practclThe Practcl Module
+
processman
+ + + + + +
processmanTool for automating the period callback of commands
+
profiler
+ + + + + +
profilerTcl source code profiler
+
pt
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
pt::astAbstract Syntax Tree Serialization
pt::cparam::configuration::critclC/PARAM, Canned configuration, Critcl
pt::cparam::configuration::teaC/PARAM, Canned configuration, TEA
pt::json_languageThe JSON Grammar Exchange Format
pt::paramPackRat Machine Specification
pt::peParsing Expression Serialization
pt::pe::opParsing Expression Utilities
pt::pegParsing Expression Grammar Serialization
pt::peg::containerPEG Storage
pt::peg::container::pegPEG Storage. Canned PEG grammar specification
pt::peg::exportPEG Export
pt::peg::export::containerPEG Export Plugin. Write CONTAINER format
pt::peg::export::jsonPEG Export Plugin. Write JSON format
pt::peg::export::pegPEG Export Plugin. Write PEG format
pt::peg::from::containerPEG Conversion. From CONTAINER format
pt::peg::from::jsonPEG Conversion. Read JSON format
pt::peg::from::pegPEG Conversion. Read PEG format
pt::peg::importPEG Import
pt::peg::import::containerPEG Import Plugin. From CONTAINER format
pt::peg::import::jsonPEG Import Plugin. Read JSON format
pt::peg::import::pegPEG Import Plugin. Read PEG format
pt::peg::interpInterpreter for parsing expression grammars
pt::peg::to::containerPEG Conversion. Write CONTAINER format
pt::peg::to::cparamPEG Conversion. Write CPARAM format
pt::peg::to::jsonPEG Conversion. Write JSON format
pt::peg::to::paramPEG Conversion. Write PARAM format
pt::peg::to::pegPEG Conversion. Write PEG format
pt::peg::to::tclparamPEG Conversion. Write TCLPARAM format
pt::peg_languagePEG Language Tutorial
pt::pegrammarIntroduction to Parsing Expression Grammars
pt::pgenParser Generator
pt::rdeParsing Runtime Support, PARAM based
pt::tclparam::configuration::nxTcl/PARAM, Canned configuration, NX
pt::tclparam::configuration::snitTcl/PARAM, Canned configuration, Snit
pt::tclparam::configuration::tclooTcl/PARAM, Canned configuration, Tcloo
pt::utilGeneral utilities
pt_export_apiParser Tools Export API
pt_import_apiParser Tools Import API
pt_introductionIntroduction to Parser Tools
pt_parse_pegParser Tools PEG Parser
pt_parser_apiParser API
pt_peg_opParser Tools PE Grammar Utility Operations
+
rc4
+ + + + + +
rc4Implementation of the RC4 stream cipher
+
rcs
+ + + + + +
rcsRCS low level utilities
+
report
+ + + + + +
reportCreate and manipulate report objects
+
rest
+ + + + + +
restdefine REST web APIs and call them inline or asychronously
+
ripemd
+ + + + + + + + + +
ripemd128RIPEMD-128 Message-Digest Algorithm
ripemd160RIPEMD-160 Message-Digest Algorithm
+
sasl
+ + + + + + + + + + + + + + + + + +
SASLImplementation of SASL mechanisms for Tcl
SASL::NTLMImplementation of SASL NTLM mechanism for Tcl
SASL::SCRAMImplementation of SASL SCRAM mechanism for Tcl
SASL::XGoogleTokenImplementation of SASL NTLM mechanism for Tcl
+
sha1
+ + + + + + + + + +
sha1SHA1 Message-Digest Algorithm
sha256SHA256 Message-Digest Algorithm
+
simulation
+ + + + + + + + + + + + + +
simulation::annealingSimulated annealing
simulation::montecarloMonte Carlo simulations
simulation::randomPseudo-random number generators
+
smtpd
+ + + + + +
smtpdTcl SMTP server implementation
+
snit
+ + + + + + + + + +
snitSnit's Not Incr Tcl
snitfaqSnit Frequently Asked Questions
+
soundex
+ + + + + +
soundexSoundex
+
stooop
+ + + + + + + + + +
stooopObject oriented extension.
switchedswitch/option management.
+
string
+ + + + + + + + + +
string::tokenRegex based iterative lexing
string::token::shellParsing of shell command line
+
stringprep
+ + + + + + + + + + + + + + + + + +
stringprepImplementation of stringprep
stringprep::datastringprep data tables, generated, internal
unicodeImplementation of Unicode normalization
unicode::dataunicode data tables, generated, internal
+
struct
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
struct::disjointsetDisjoint set data structure
struct::graphCreate and manipulate directed graph objects
struct::graph::opOperation for (un)directed graph objects
struct::graph_v1Create and manipulate directed graph objects
struct::listProcedures for manipulating lists
struct::matrixCreate and manipulate matrix objects
struct::matrix_v1Create and manipulate matrix objects
struct::poolCreate and manipulate pool objects (of discrete items)
struct::prioqueueCreate and manipulate prioqueue objects
struct::queueCreate and manipulate queue objects
struct::recordDefine and create records (similar to 'C' structures)
struct::setProcedures for manipulating sets
struct::skiplistCreate and manipulate skiplists
struct::stackCreate and manipulate stack objects
struct::treeCreate and manipulate tree objects
struct::tree_v1Create and manipulate tree objects
+
tar
+ + + + + +
tarTar file creation, extraction & manipulation
+
tepam
+ + + + + + + + + + + + + + + + + +
tepamAn introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager
tepam::argument_dialogboxTEPAM argument_dialogbox, reference manual
tepam::doc_genTEPAM DOC Generation, reference manual
tepam::procedureTEPAM procedure, reference manual
+
term
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
termGeneral terminal control
term::ansi::codeHelper for control sequences
term::ansi::code::attrANSI attribute sequences
term::ansi::code::ctrlANSI control sequences
term::ansi::code::macrosMacro sequences
term::ansi::ctrl::unixControl operations and queries
term::ansi::sendOutput of ANSI control sequences to terminals
term::interact::menuTerminal widget, menu
term::interact::pagerTerminal widget, paging
term::receiveGeneral input from terminals
term::receive::bindKeyboard dispatch from terminals
term::sendGeneral output to terminals
+
textutil
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
textutilProcedures to manipulate texts and strings.
textutil::adjustProcedures to adjust, indent, and undent paragraphs
textutil::expanderProcedures to process templates and expand text.
textutil::repeatProcedures to repeat strings.
textutil::splitProcedures to split texts
textutil::stringProcedures to manipulate texts and strings.
textutil::tabifyProcedures to (un)tabify strings
textutil::trimProcedures to trim strings
+
tie
+ + + + + + + + + +
tieArray persistence
tieArray persistence, standard data sources
+
tiff
+ + + + + +
tiffTIFF reading, writing, and querying and manipulation of meta data
+
tool
+ + + + + + + + + + + + + +
oo::utilUtility commands for TclOO
toolDictionary Tools
tool::dict_ensembleDictionary Tools
+
transfer
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
transfer::connectConnection setup
transfer::copyData transfer foundation
transfer::copy::queueQueued transfers
transfer::data::destinationData destination
transfer::data::sourceData source
transfer::receiverData source
transfer::transmitterData source
+
treeql
+ + + + + +
treeqlQuery tree objects
+
try
+ + + + + + + + + +
throwthrow - Throw an error exception with a message
trytry - Trap and process errors and exceptions
+
udpcluster
+ + + + + +
udpclusterUDP Peer-to-Peer cluster
+
uev
+ + + + + + + + + +
ueventUser events
uevent::onidleRequest merging and deferal to idle time
+
units
+ + + + + +
unitsunit conversion
+
uri
+ + + + + + + + + +
uriURI utilities
uri_urnURI utilities, URN scheme
+
uuid
+ + + + + +
uuidUUID generation and comparison
+
valtype
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
valtype::commonValidation, common code
valtype::creditcard::amexValidation for AMEX creditcard number
valtype::creditcard::discoverValidation for Discover creditcard number
valtype::creditcard::mastercardValidation for Mastercard creditcard number
valtype::creditcard::visaValidation for VISA creditcard number
valtype::gs1::ean13Validation for EAN13
valtype::ibanValidation for IBAN
valtype::imeiValidation for IMEI
valtype::isbnValidation for ISBN
valtype::luhnValidation for plain number with a LUHN checkdigit
valtype::luhn5Validation for plain number with a LUHN5 checkdigit
valtype::usnpiValidation for USNPI
valtype::verhoeffValidation for plain number with a VERHOEFF checkdigit
+
virtchannel_base
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::chan::catConcatenation channel
tcl::chan::facadeFacade channel
tcl::chan::fifoIn-memory fifo channel
tcl::chan::fifo2In-memory interconnected fifo channels
tcl::chan::halfpipeIn-memory channel, half of a fifo2
tcl::chan::memchanIn-memory channel
tcl::chan::nullNull channel
tcl::chan::nullzeroNull/Zero channel combination
tcl::chan::randomRandom channel
tcl::chan::stdStandard I/O, unification of stdin and stdout
tcl::chan::stringRead-only in-memory channel
tcl::chan::textwindowTextwindow channel
tcl::chan::variableIn-memory channel using variable for storage
tcl::chan::zeroZero channel
tcl::randomseedUtilities for random channels
+
virtchannel_core
+ + + + + + + + + + + + + +
tcl::chan::coreBasic reflected/virtual channel support
tcl::chan::eventsEvent support for reflected/virtual channels
tcl::transform::coreBasic reflected/virtual channel transform support
+
virtchannel_transform
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
tcl::transform::adler32Adler32 transformation
tcl::transform::base64Base64 encoding transformation
tcl::transform::counterCounter transformation
tcl::transform::crc32Crc32 transformation
tcl::transform::hexHexadecimal encoding transformation
tcl::transform::identityIdentity transformation
tcl::transform::limitsizelimiting input
tcl::transform::observeObserver transformation, stream copy
tcl::transform::otpEncryption via one-time pad
tcl::transform::rotrot-encryption
tcl::transform::spacerSpace insertation and removal
tcl::transform::zlibzlib (de)compression
+
websocket
+ + + + + +
websocketTcl implementation of the websocket protocol
+
wip
+ + + + + +
wipWord Interpreter
+
yaml
+ + + + + + + + + +
huddleCreate and manipulate huddle object
yamlYAML Format Encoder/Decoder
+
zip
+ + + + + + + + + + + + + +
zipfile::decodeAccess to zip archives
zipfile::encodeGeneration of zip archives
zipfile::mkzipBuild a zip archive
+
ADDED embedded/www/toc2.html Index: embedded/www/toc2.html ================================================================== --- embedded/www/toc2.html +++ embedded/www/toc2.html @@ -0,0 +1,131 @@ +
+ +
[ + Keyword Index +| Categories +| Modules +| Applications + ]
+

Table Of Contents

+

+
Applications
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
dtpliteLightweight DocTools Markup Processor
nnsName service facility, Commandline Client Application
nnsdName service facility, Commandline Server Application
nnslogName service facility, Commandline Logging Client Application
pageParser Generator
ptParser Tools Application
tcldocstripTcl-based Docstrip Processor
+
Index: examples/ftp/hpupdate.tcl ================================================================== --- examples/ftp/hpupdate.tcl +++ examples/ftp/hpupdate.tcl @@ -70,13 +70,13 @@ .menu.file add separator .menu.file add command -label "Exit" -underline 0 -command Quit -accelerator Alt+X #menu .menu.edit -tearoff 0 #.menu add cascade -label "Bearbeiten" -menu .menu.edit -underline 0 -#.menu.edit add command -label "Alle Löschen" -underline 0 -state disabled -command { +#.menu.edit add command -label "Alle Löschen" -underline 0 -state disabled -command { # .view.remote.list selection set 0 end; BusyCommand DeleteremoteFiles} -#.menu.edit add command -label "Alle Ãœbertragen" -underline 0 -state disabled -command Quit +#.menu.edit add command -label "Alle Übertragen" -underline 0 -state disabled -command Quit menu .menu.view -tearoff 0 .menu add cascade -label "View" -menu .menu.view -underline 0 .menu.view add command -label "Refresh" -underline 0 -command {BusyCommand Refresh} -accelerator Alt+R Index: examples/httpd/htdocs/content.file.md ================================================================== --- examples/httpd/htdocs/content.file.md +++ examples/httpd/htdocs/content.file.md @@ -1,55 +1,55 @@ -httpd::content::file -==================== -Back to: [Index](index.md) | [Package httpd::content](content.md) - -The **httpd::content::file** class implements a system for sharing a -local file structure via http. - -## Special file handling - -### Directories - -When a directory path is requested, the system searches for one of the following (in order): - -* index.tml -* index.md -* index.html - -If one of these files is found, it is delivered as the response to the request. If no index file -was found, the object will call the object's *DirectoryListing* method to -deliver a dynamic listing of the files in the directory. - -### .md files - -Files with the .md extension are parsed using the *Markdown* package. - -### .tml files - -Files with the .tml extension are parsed using a call to *subst*. -This allows them to deliver content in the same manner as tclhttpd. The -contents of the *query_headers* are loaded as local variables prior to -the *subst* call. NOTE: Unlike Tclhttpd, the substitution is performed -inside of the reply object's namespace, not the local interpreter. Thus, -template files can exercise the object's methods using the "my" command. - -## Dispatch Parameters - -Objects of this class needs additional information from the server in -order to operate. These fields should be coded into the **add_root** call. - -### path *filepath* - -The **path** parameter specifies the root of the file path to be exposed. - -## Methods - -### DirectoryListing *local_file* - -Generates an HTML listing of a file path. The default implementation is a *very* -rudimentary **glob --nocomplain [file join $local_path \*]** - -### FileName - -Converts the **REQUEST_URI** from query_headers into a local file path. This -method searches first for the file name verbatim. If not found, it then searches -for the same file name with a .md, .html, or .tml extension (in that order.) +httpd::content::file +==================== +Back to: [Index](index.md) | [Package httpd::content](content.md) + +The **httpd::content::file** class implements a system for sharing a +local file structure via http. + +## Special file handling + +### Directories + +When a directory path is requested, the system searches for one of the following (in order): + +* index.tml +* index.md +* index.html + +If one of these files is found, it is delivered as the response to the request. If no index file +was found, the object will call the object's *DirectoryListing* method to +deliver a dynamic listing of the files in the directory. + +### .md files + +Files with the .md extension are parsed using the *Markdown* package. + +### .tml files + +Files with the .tml extension are parsed using a call to *subst*. +This allows them to deliver content in the same manner as tclhttpd. The +contents of the *query_headers* are loaded as local variables prior to +the *subst* call. NOTE: Unlike Tclhttpd, the substitution is performed +inside of the reply object's namespace, not the local interpreter. Thus, +template files can exercise the object's methods using the "my" command. + +## Dispatch Parameters + +Objects of this class needs additional information from the server in +order to operate. These fields should be coded into the **add_root** call. + +### path *filepath* + +The **path** parameter specifies the root of the file path to be exposed. + +## Methods + +### DirectoryListing *local_file* + +Generates an HTML listing of a file path. The default implementation is a *very* +rudimentary **glob --nocomplain [file join $local_path \*]** + +### FileName + +Converts the **REQUEST_URI** from query_headers into a local file path. This +method searches first for the file name verbatim. If not found, it then searches +for the same file name with a .md, .html, or .tml extension (in that order.) Index: examples/httpd/htdocs/content.md ================================================================== --- examples/httpd/htdocs/content.md +++ examples/httpd/htdocs/content.md @@ -1,14 +1,14 @@ -http::content -============= -[Back to Index](index.md) - -The **httpd::content** package is an extension to the core **httpd** package -which provides all of the bread and butter functions needed to implement a -basic webserver. - -* [Content Server](content.server.md) -* [Form handler](content.form.md) -* [File handler](content.file.md) -* [SCGI handler](content.scgi.md) -* [Proxy handler](content.proxy.md) +http::content +============= +[Back to Index](index.md) + +The **httpd::content** package is an extension to the core **httpd** package +which provides all of the bread and butter functions needed to implement a +basic webserver. + +* [Content Server](content.server.md) +* [Form handler](content.form.md) +* [File handler](content.file.md) +* [SCGI handler](content.scgi.md) +* [Proxy handler](content.proxy.md) Index: examples/httpd/htdocs/content.proxy.md ================================================================== --- examples/httpd/htdocs/content.proxy.md +++ examples/httpd/htdocs/content.proxy.md @@ -1,20 +1,20 @@ -httpd::content::proxy -============= -Back to: [Index](index.md) | [Package httpd::content](content.md) - -The proxy handler farms out the generation of content to an external process running -on a known port. The external process is assumed to be a proxy server, and it is the job -of this object to transform the query as received into a form that is understood by -the external server. - -To implement a proxy handler, replace **proxy_info** with one that will return a list -containing the following: - - PROXYHOST PROXYPORT PROXYURI - -* PROXYHOST - The hostname or IP address of the server running the process -* PROXYPORT - The port to connect to -* PROXYURI - The replacement GET/POST/etc request to make to the external process. - -The **proxy_info** method also makes a handly place to spawn a locally hosted process on demand. +httpd::content::proxy +============= +Back to: [Index](index.md) | [Package httpd::content](content.md) + +The proxy handler farms out the generation of content to an external process running +on a known port. The external process is assumed to be a proxy server, and it is the job +of this object to transform the query as received into a form that is understood by +the external server. + +To implement a proxy handler, replace **proxy_info** with one that will return a list +containing the following: + + PROXYHOST PROXYPORT PROXYURI + +* PROXYHOST - The hostname or IP address of the server running the process +* PROXYPORT - The port to connect to +* PROXYURI - The replacement GET/POST/etc request to make to the external process. + +The **proxy_info** method also makes a handly place to spawn a locally hosted process on demand. For an example of this, see the [docserver.tcl](docserver.tcl) Example. Index: examples/httpd/htdocs/content.scgi.md ================================================================== --- examples/httpd/htdocs/content.scgi.md +++ examples/httpd/htdocs/content.scgi.md @@ -1,20 +1,20 @@ -httpd::content::scgi -============= -Back to: [Index](index.md) | [Package httpd::content](content.md) - -The SCGI handler farms out the generation of content to an external process -running at a known port. Because this process is persistent, the SCGI system -avoids the overhead of spawning and spooling up an external process with -every page view. - -To implement an SCGI handler, replace the **scgi_info** method with one -that will return a list containing the following: - - SCGIHOST SCGIPORT SCGISCRIPT - -* SCGIHOST - The hostname or IP address of the server running the process -* SCGIPORT - The port to connect to -* SCGISCRIPT - The SCGISCRIPT parameter which will be passed to the external process via headers. - -The **scgi_info** method also makes a handly place to spawn a locally hosted process on demand. +httpd::content::scgi +============= +Back to: [Index](index.md) | [Package httpd::content](content.md) + +The SCGI handler farms out the generation of content to an external process +running at a known port. Because this process is persistent, the SCGI system +avoids the overhead of spawning and spooling up an external process with +every page view. + +To implement an SCGI handler, replace the **scgi_info** method with one +that will return a list containing the following: + + SCGIHOST SCGIPORT SCGISCRIPT + +* SCGIHOST - The hostname or IP address of the server running the process +* SCGIPORT - The port to connect to +* SCGISCRIPT - The SCGISCRIPT parameter which will be passed to the external process via headers. + +The **scgi_info** method also makes a handly place to spawn a locally hosted process on demand. For an example of this, see the [docserver.tcl](docserver.tcl) Example. Index: examples/httpd/htdocs/content.server.md ================================================================== --- examples/httpd/htdocs/content.server.md +++ examples/httpd/htdocs/content.server.md @@ -1,42 +1,42 @@ -http::content -============= -Back to: [Index](index.md) | [Package httpd::content](content.md) - - -## Class: httpd::server::dispatch - -The **httpd::server::dispatch** adds additional functionality to the basic -**httpd::server** class. It's *dispatch* method performs a pattern search -based on url's registered via the *add_uri* method. That *add_uri* method -allows the developer to specify which class will handle replies, as well as -pass configuration information onto those objects. - -### Option doc_root - -Specifiying a *doc_root* will introduce a pattern search of last resort to -find a matching URI as a file subordinate to the *doc_root*. Also, if the -*doc_root* is specified, the system will search the root folder for the following -templates: - -* notfound.tml - A site specific "404 File not found" template -* internal_error.tml - A site specific "505 Internal Server Error" template - -### Method add_uri *pattern* *info* - -*add_uri* appends a new pattern to the server's internal pattern search dict. -Patterns utilize **string match**, so any global characters or patterns for -string match will work. - -Patterns are matched in the order in which they were given. In the example: - -
SERVER add_uri /home* {...}
-SERVER add_uri /home/star/runner* {...}
- -The pattern for /home/star/runner* will never be reached because /home* was specified first. - -The **info** argument contains a dict that will be passed by the *connect* method of the -server to the *dispatch* method of the reply. Only two fields are reserved by the core of -httpd: - -* class - The base class for the reply -* mixin - The class to be mixed into the new object immediately prior to invoking the object's *dispatch* method. +http::content +============= +Back to: [Index](index.md) | [Package httpd::content](content.md) + + +## Class: httpd::server::dispatch + +The **httpd::server::dispatch** adds additional functionality to the basic +**httpd::server** class. It's *dispatch* method performs a pattern search +based on url's registered via the *add_uri* method. That *add_uri* method +allows the developer to specify which class will handle replies, as well as +pass configuration information onto those objects. + +### Option doc_root + +Specifiying a *doc_root* will introduce a pattern search of last resort to +find a matching URI as a file subordinate to the *doc_root*. Also, if the +*doc_root* is specified, the system will search the root folder for the following +templates: + +* notfound.tml - A site specific "404 File not found" template +* internal_error.tml - A site specific "505 Internal Server Error" template + +### Method add_uri *pattern* *info* + +*add_uri* appends a new pattern to the server's internal pattern search dict. +Patterns utilize **string match**, so any global characters or patterns for +string match will work. + +Patterns are matched in the order in which they were given. In the example: + +
SERVER add_uri /home* {...}
+SERVER add_uri /home/star/runner* {...}
+ +The pattern for /home/star/runner* will never be reached because /home* was specified first. + +The **info** argument contains a dict that will be passed by the *connect* method of the +server to the *dispatch* method of the reply. Only two fields are reserved by the core of +httpd: + +* class - The base class for the reply +* mixin - The class to be mixed into the new object immediately prior to invoking the object's *dispatch* method. Index: examples/httpd/htdocs/example.md ================================================================== --- examples/httpd/htdocs/example.md +++ examples/httpd/htdocs/example.md @@ -1,157 +1,157 @@ -An h1 header -============ - -Paragraphs are separated by a blank line. - -2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists -look like: - - * this one - * that one - * the other one - -Note that --- not considering the asterisk --- the actual text -content starts at 4-columns in. - -> Block quotes are -> written like so. -> -> They can span multiple paragraphs, -> if you like. - -Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all -in chapters 12--14"). Three dots ... will be converted to an ellipsis. -Unicode is supported. ☺ - - - -An h2 header ------------- - -Here's a numbered list: - - 1. first item - 2. second item - 3. third item - -Note again how the actual text starts at 4 columns in (4 characters -from the left side). Here's a code sample: - - # Let me re-iterate ... - for i in 1 .. 10 { do-something(i) } - -As you probably guessed, indented 4 spaces. By the way, instead of -indenting the block, you can use delimited blocks, if you like: - -~~~ -define foobar() { - print "Welcome to flavor country!"; -} -~~~ - -(which makes copying & pasting easier). You can optionally mark the -delimited block for Pandoc to syntax highlight it: - -~~~python -import time -# Quick, count to ten! -for i in range(10): - # (but not *too* quick) - time.sleep(0.5) - print i -~~~ - - - -### An h3 header ### - -Now a nested list: - - 1. First, get these ingredients: - - * carrots - * celery - * lentils - - 2. Boil some water. - - 3. Dump everything in the pot and follow - this algorithm: - - find wooden spoon - uncover pot - stir - cover pot - balance wooden spoon precariously on pot handle - wait 10 minutes - goto first step (or shut off burner when done) - - Do not bump wooden spoon or it will fall. - -Notice again how text always lines up on 4-space indents (including -that last line which continues item 3 above). - -Here's a link to [a website](http://foo.bar), to a [local -doc](local-doc.html), and to a [section heading in the current -doc](#an-h2-header). Here's a footnote [^1]. - -[^1]: Footnote text goes here. - -Tables can look like this: - -size material color ----- ------------ ------------ -9 leather brown -10 hemp canvas natural -11 glass transparent - -Table: Shoes, their sizes, and what they're made of - -(The above is the caption for the table.) Pandoc also supports -multi-line tables: - --------- ----------------------- -keyword text --------- ----------------------- -red Sunsets, apples, and - other red or reddish - things. - -green Leaves, grass, frogs - and other things it's - not easy being. --------- ----------------------- - -A horizontal rule follows. - -*** - -Here's a definition list: - -apples - : Good for making applesauce. -oranges - : Citrus! -tomatoes - : There's no "e" in tomatoe. - -Again, text is indented 4 spaces. (Put a blank line between each -term/definition pair to spread things out more.) - -Here's a "line block": - -| Line one -| Line too -| Line tree - -and images can be specified like so: - -![example image](plume.png "An exemplary image") - -Inline math equations go in like so: $\omega = d\phi / dt$. Display -math should get its own line and be put in in double-dollarsigns: - -$$I = \int \rho R^{2} dV$$ - -And note that you can backslash-escape any punctuation characters +An h1 header +============ + +Paragraphs are separated by a blank line. + +2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists +look like: + + * this one + * that one + * the other one + +Note that --- not considering the asterisk --- the actual text +content starts at 4-columns in. + +> Block quotes are +> written like so. +> +> They can span multiple paragraphs, +> if you like. + +Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all +in chapters 12--14"). Three dots ... will be converted to an ellipsis. +Unicode is supported. ☺ + + + +An h2 header +------------ + +Here's a numbered list: + + 1. first item + 2. second item + 3. third item + +Note again how the actual text starts at 4 columns in (4 characters +from the left side). Here's a code sample: + + # Let me re-iterate ... + for i in 1 .. 10 { do-something(i) } + +As you probably guessed, indented 4 spaces. By the way, instead of +indenting the block, you can use delimited blocks, if you like: + +~~~ +define foobar() { + print "Welcome to flavor country!"; +} +~~~ + +(which makes copying & pasting easier). You can optionally mark the +delimited block for Pandoc to syntax highlight it: + +~~~python +import time +# Quick, count to ten! +for i in range(10): + # (but not *too* quick) + time.sleep(0.5) + print i +~~~ + + + +### An h3 header ### + +Now a nested list: + + 1. First, get these ingredients: + + * carrots + * celery + * lentils + + 2. Boil some water. + + 3. Dump everything in the pot and follow + this algorithm: + + find wooden spoon + uncover pot + stir + cover pot + balance wooden spoon precariously on pot handle + wait 10 minutes + goto first step (or shut off burner when done) + + Do not bump wooden spoon or it will fall. + +Notice again how text always lines up on 4-space indents (including +that last line which continues item 3 above). + +Here's a link to [a website](http://foo.bar), to a [local +doc](local-doc.html), and to a [section heading in the current +doc](#an-h2-header). Here's a footnote [^1]. + +[^1]: Footnote text goes here. + +Tables can look like this: + +size material color +---- ------------ ------------ +9 leather brown +10 hemp canvas natural +11 glass transparent + +Table: Shoes, their sizes, and what they're made of + +(The above is the caption for the table.) Pandoc also supports +multi-line tables: + +-------- ----------------------- +keyword text +-------- ----------------------- +red Sunsets, apples, and + other red or reddish + things. + +green Leaves, grass, frogs + and other things it's + not easy being. +-------- ----------------------- + +A horizontal rule follows. + +*** + +Here's a definition list: + +apples + : Good for making applesauce. +oranges + : Citrus! +tomatoes + : There's no "e" in tomatoe. + +Again, text is indented 4 spaces. (Put a blank line between each +term/definition pair to spread things out more.) + +Here's a "line block": + +| Line one +| Line too +| Line tree + +and images can be specified like so: + +![example image](plume.png "An exemplary image") + +Inline math equations go in like so: $\omega = d\phi / dt$. Display +math should get its own line and be put in in double-dollarsigns: + +$$I = \int \rho R^{2} dV$$ + +And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc. Index: examples/httpd/htdocs/index.md ================================================================== --- examples/httpd/htdocs/index.md +++ examples/httpd/htdocs/index.md @@ -1,31 +1,22 @@ -Your test server works! - -* [Tcllib embedded docs](/tcllib/index.html) -* [Tcllib's fossil repo (hosted via SCGI)](/fossil) -* [Standard Markdown Example Page](example.md) -* [Static HTML Page](html_static_page.html) -* [Template HTML Page](header.tml) - -A locally served image: -![Locally Served Image](/tcllib/image/arch_core_container.png "Core Container") - -Internal documentation for httpd: - -* [Operating Principals](operations.md) -* [Program Listing for docserver.tcl](docserver.tcl) -* [Class httpd::reply](reply.md) -* [Class httpd::server](server.md) -* [Class httpd::content](content.md) - * [Content Server](content.server.md) - * [Form handler](content.form.md) - * [File handler](content.file.md) - * [SCGI handler](content.scgi.md) +Your test server works! + +* [Tcllib embedded docs](/tcllib/index.html) +* [Tcllib's fossil repo (hosted via SCGI)](/fossil) +* [Standard Markdown Example Page](example.md) +* [Static HTML Page](html_static_page.html) + +A locally served image: +![Locally Served Image](/tcllib/image/arch_core_container.png "Core Container") + +Internal documentation for httpd: + +* [Operating Principals](operations.md) +* [Program Listing for docserver.tcl](docserver.tcl) +* [Class httpd::reply](reply.md) +* [Class httpd::server](server.md) +* [Class httpd::content](content.md) + * [Content Server](content.server.md) + * [Form handler](content.form.md) + * [File handler](content.file.md) + * [SCGI handler](content.scgi.md) * [Proxy handler](content.proxy.md) - -_Upload Test_ - -
- - - -
Index: examples/httpd/htdocs/operations.md ================================================================== --- examples/httpd/htdocs/operations.md +++ examples/httpd/htdocs/operations.md @@ -1,30 +1,30 @@ -httpd: Operations Manual -=============================== -[Back to Index](index.md) - -The httpd module is designed to be an http server which is embeddable within another project. - -1. When a reply socket is opened, the *connect* method is exercised. -2. The *connect* method then populates a dict with basic information such as the REMOTE_IP and the URI. -3. *connect* calls the Server's *dispatch* method with this new dict as a parameter. -4. *dispatch* returns with a dict describing the response to this request, or an empty list to indicate that this is an invalid request. -5. A new object is created to manage the reply. - * If a **class** field is present in the dispatch dict, a new object will be of that class. - * If no **class** was given, the new object will be of the class specified by the server's *reply_class* property. -6. If the field *mixin* is present and non-empty, the new reply object will mixin the class specified. -7. The server object will then call the reply object's *dispatch* process, with the complete reply description dict as a paramter. -8. The server adds the object to a list of objects it is tracking. If the reply object does not destroy itself within 2 minutes, the server will destroy it. - -Once the *dispatch* method is called, it is the reply object's job to: - -1. Parse the HTTP headers of the incoming request -2. Formulate a response -3. Transmit that response back across the request socket. -4. Destroy itself when finished. -5. On destruction, unregister itself from the server object. - -The basic reply class perfoms the following: - -1. Reads the HTTP years -2. Invokes the *content* class, which utilizes the *puts* method to populate an internal buffer. -3. Invokes the *output* class which will prepare reply headers and output the reply buffer to the request socket. +httpd: Operations Manual +=============================== +[Back to Index](index.md) + +The httpd module is designed to be an http server which is embeddable within another project. + +1. When a reply socket is opened, the *connect* method is exercised. +2. The *connect* method then populates a dict with basic information such as the REMOTE_IP and the URI. +3. *connect* calls the Server's *dispatch* method with this new dict as a parameter. +4. *dispatch* returns with a dict describing the response to this request, or an empty list to indicate that this is an invalid request. +5. A new object is created to manage the reply. + * If a **class** field is present in the dispatch dict, a new object will be of that class. + * If no **class** was given, the new object will be of the class specified by the server's *reply_class* property. +6. If the field *mixin* is present and non-empty, the new reply object will mixin the class specified. +7. The server object will then call the reply object's *dispatch* process, with the complete reply description dict as a paramter. +8. The server adds the object to a list of objects it is tracking. If the reply object does not destroy itself within 2 minutes, the server will destroy it. + +Once the *dispatch* method is called, it is the reply object's job to: + +1. Parse the HTTP headers of the incoming request +2. Formulate a response +3. Transmit that response back across the request socket. +4. Destroy itself when finished. +5. On destruction, unregister itself from the server object. + +The basic reply class perfoms the following: + +1. Reads the HTTP years +2. Invokes the *content* class, which utilizes the *puts* method to populate an internal buffer. +3. Invokes the *output* class which will prepare reply headers and output the reply buffer to the request socket. Index: examples/httpd/htdocs/reply.md ================================================================== --- examples/httpd/htdocs/reply.md +++ examples/httpd/htdocs/reply.md @@ -1,16 +1,16 @@ -### Method Url_Decode *data* - -Translates a standard http query encoding string into a stream of key/value pairs. - -### Method FormData - -For GET requests, this method will convert the Query portion of the URI (after the ?) -to key/value pairs. - -For POST requests, this method will read the body of the request and convert -that block of text to a stream of key/value pairs. - -### Method PostData - -Returns the raw block of data from the post headers section of the transaction, up to +### Method Url_Decode *data* + +Translates a standard http query encoding string into a stream of key/value pairs. + +### Method FormData + +For GET requests, this method will convert the Query portion of the URI (after the ?) +to key/value pairs. + +For POST requests, this method will read the body of the request and convert +that block of text to a stream of key/value pairs. + +### Method PostData + +Returns the raw block of data from the post headers section of the transaction, up to the Content-Length specified in the headers. Index: examples/httpd/httpd.tcl ================================================================== --- examples/httpd/httpd.tcl +++ examples/httpd/httpd.tcl @@ -4,11 +4,13 @@ set DIR [file dirname [file normalize [info script]]] set DEMOROOT [file join $DIR htdocs] set tcllibroot [file normalize [file join $DIR .. ..]] set auto_path [linsert $auto_path 0 [file normalize [file join $tcllibroot modules]]] -package require httpd 4.1 +package require httpd +package require httpd::content + ### # This script creates two toplevel domains: # * Hosting the tcllib embedded documentation as static content # * Hosting a local fossil mirror of the tcllib repository ### @@ -25,65 +27,50 @@ return $::fossil_exe } return [exec ${::fossil_exe} {*}$args] } -clay::define httpd::content.fossil_node_proxy { - - superclass httpd::content.proxy - - method FileName {} { - set uri [my request get REQUEST_URI] - set prefix [my clay get prefix] - set module [lindex [split $uri /] 2] - if {![info exists ::fossil_process($module)]} { - set dbfiles [::fossil-list] - foreach file [lsort -dictionary $dbfiles] { - dict set result [file rootname [file tail $file]] $file - } - if {![dict exists $result $module]} { - return {} - } - set dbfile [dict get $result $module] - if {![file exists $dbfile]} { - return {} - } - set ::fossil_process($module) $dbfile - } - return [list $module $::fossil_process($module)] - } - - method proxy_path {} { - set uri [string trimleft [my request get REQUEST_URI] /] - set prefix [my clay get prefix] - set module [lindex [split $uri /] 1] - set path /[string range $uri [string length $prefix/$module] end] - return $path - } - - method proxy_channel {} { - ### - # This method returns a channel to the - # proxied socket/stdout/etc - ### - lassign [my FileName] module dbfile - set EXE [my Cgi_Executable fossil] - set baseurl http://[my request get HTTP_HOST][my clay get prefix]/$module - if { $::tcl_platform(platform) eq "windows"} { - return [open "|fossil.exe http $dbfile -baseurl $baseurl" r+] - } else { - return [open "|fossil http $dbfile -baseurl $baseurl 2>@1" r+] - } - } -} - -clay::define httpd::content.fossil_node_scgi { - - superclass httpd::content.scgi +tool::class create httpd::content::fossil_root { + + method content {} { + my reset + my puts "Local Fossil Repositories" + global recipe + my puts "
    " + set dbfiles [::fossil-list] + foreach file [lsort -dictionary $dbfiles] { + dict set result [file rootname [file tail $file]] $file + } + foreach {module dbfile} [lsort -dictionary -stride 2 $result] { + my puts "
  • $module" + } + my puts {
} + } +} + +### +# This driver for fossil is not a standard SCGI module +# it's more or less cargo culted from a working prototype +# developed for the GORT project. You'll note it does some +# things that are non-standard for SCGI, and that's to work +# around quirks in Fossil SCGI implementation. +# +# (Either that or my reading of SCGI specs is way, way off. +# I'm 75% sure I'm doing something wrong.) +# +# Actually, according to DRH we should really be using CGI +# because that is better supported. So until we get the +# CGI functions fleshed out, here's FOSSIL... +# +# --Sean "The Hypnotoad" Woods +### +tool::class create httpd::content::fossil_node_scgi { + + superclass httpd::content::scgi method scgi_info {} { - set uri [my request get REQUEST_URI] - set prefix [my clay get prefix] + set uri [my query_headers get REQUEST_URI] + set prefix [my query_headers get prefix] set module [lindex [split $uri /] 2] file mkdir ~/tmp if {![info exists ::fossil_process($module)]} { package require processman package require nettool @@ -97,11 +84,11 @@ if {![file exists $dbfile]} { tailcall my error 400 {Not Found} } set mport [my port_listening] set cmd [list [::fossil] server $dbfile --port $port --localhost --scgi 2>~/tmp/$module.err >~/tmp/$module.log] - + dict set ::fossil_process($module) port $port dict set ::fossil_process($module) handle $handle dict set ::fossil_process($module) cmd $cmd dict set ::fossil_process($module) SCRIPT_NAME $prefix/$module } @@ -111,86 +98,143 @@ my varname paused after 500 } return [list localhost $port $SCRIPT_NAME] } -} - -::clay::define ::docserver::server { - superclass ::httpd::server - - method debug args { - #puts [list DEBUG {*}$args] - } - method log args { - #puts [list LOG {*}$args] - } - -} - -set serveropts [::httpd::server clay get server/] -foreach {f v} [::clay::args_to_options {*}$::argv] { - if {[dict exists $serveropts $f]} { + + method content {} { + my variable sock chan + set sockinfo [my scgi_info] + if {$sockinfo eq {}} { + my error 404 {Not Found} + return + } + lassign $sockinfo scgihost scgiport scgiscript + set sock [::socket $scgihost $scgiport] + # Add a few headers that SCGI needs + my query_headers set SCRIPT_NAME $scgiscript + my query_headers set SCGI 1.0 + + chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096 + chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096 + ### + # Convert our query headers into netstring format. Note that + # MimeParse as already rigged it such that CONTENT_LENGTH is first + # and always populated (even if zero), per SCGI requirements + ### + set block [my query_headers netstring] + puts -nonewline $sock $block + set length [my query_headers get CONTENT_LENGTH] + if {$length} { + ### + # Send any POST/PUT/etc content + ### + chan copy $chan $sock -size $length + } + chan flush $sock + ### + # Wake this object up after the SCGI process starts to respond + ### + #chan configure $sock -translation {auto crlf} -blocking 0 -buffering line + chan event $sock readable [namespace code {my output}] + } + + method dispatch {newsock datastate} { + my query_headers replace $datastate + my variable chan rawrequest dipatched_time + set chan $newsock + chan event $chan readable {} + chan configure $chan -translation {auto crlf} -buffering line + set dispatched_time [clock seconds] + try { + set rawrequest [my HttpHeaders $chan] + foreach {field value} [my MimeParse $rawrequest] { + my query_headers set $field $value + } + # Dispatch to the URL implementation. + my content + } on error {err info} { + dict print $info + #puts stderr $::errorInfo + my error 500 $err + } finally { + my output + } + } + + method output {} { + if {[my query_headers getnull HTTP_ERROR] ne {}} { + ### + # If something croaked internally, handle this page as a normal reply + ### + next + } + my variable sock chan + set replyhead [my HttpHeaders $sock] + set replydat [my MimeParse $replyhead] + ### + # Convert the Status: header from the SCGI service to + # a standard service reply line from a web server, but + # otherwise spit out the rest of the headers verbatim + ### + set replybuffer "HTTP/1.1 [dict get $replydat HTTP_STATUS]\n" + append replybuffer $replyhead + chan configure $chan -translation {auto crlf} -blocking 0 -buffering full -buffersize 4096 + puts $chan $replybuffer + ### + # Output the body + ### + chan configure $sock -translation binary -blocking 0 -buffering full -buffersize 4096 + chan configure $chan -translation binary -blocking 0 -buffering full -buffersize 4096 + set length [dict get $replydat CONTENT_LENGTH] + if {$length} { + ### + # Send any POST/PUT/etc content + ### + chan copy $sock $chan -command [namespace code [list my TransferComplete $sock]] + } else { + catch {close $sock} + chan flush $chan + my destroy + } + } + +} + +tool::class create ::docserver::server { + superclass ::httpd::server::dispatch ::httpd::server + + + method log args { + puts [list {*}$args] + } + +} +set opts [::tool::args_to_options {*}$argv] +set serveropts {} +set optinfo [::docserver::server meta getnull option] +foreach {f v} $opts { + if {[dict exists $optinfo $f]} { dict set serveropts $f $v } } -if {[dict exists $serveropts fossil]} { - set ::fossil_exe [dict get $serveropts fossil] +puts $serveropts +set fossilopts {} +set optinfo [::httpd::content::fossil_root meta getnull option] +foreach {f v} $opts { + if {[dict exists $optinfo $f]} { + dict set fossilopts $f $v + } +} +if {[dict exists $opts fossil]} { + set ::fossil_exe [dict get $opts fossil] } +puts "Server Options: $serveropts" +puts "Fossil Options: $fossilopts" + ::docserver::server create appmain doc_root $DEMOROOT {*}$argv -appmain plugin basic_url ::httpd::plugin.dict_dispatch -appmain uri add * /tcllib* [list mixin {reply httpd::content.file} path [file join $tcllibroot embedded www]] -appmain uri direct * /fossil {} { - my puts "Local Fossil Repositories" - global recipe - my puts "
    " - set dbfiles [::fossil-list] - foreach file [lsort -dictionary $dbfiles] { - dict set result [file rootname [file tail $file]] $file - } - foreach {module dbfile} [lsort -dictionary -stride 2 $result] { - my puts "
  • $module" - } - my puts {
} -} -appmain uri add * /fossil/* [list mixin {reply httpd::content.fossil_node_proxy}] -appmain uri direct * /upload {} { - my puts "IRM Dispatch Server" - my puts "" - set FORMDAT [my FormData] - foreach {f v} [my FormData] { - my puts "" - } - my puts "" - foreach {f v} [my clay dump] { - my puts "" - } - my puts "" - foreach part [dict getnull $FORMDAT MIME_PARTS] { - my puts "" - foreach f [::mime::getheader $part -names] { - my puts "" - } - my puts "" - } - my puts "" - my puts
$f$v
$f$v
$f[mime::getheader $part $f]
[::mime::getbody $part -decode]
File Size[my request get CONTENT_LENGTH]
- my puts -} -appmain uri direct * /dynamic {} { - my puts "IRM Dispatch Server" - my puts "" - foreach {f v} [my request dump] { - my puts "" - } - my puts "" - foreach {f v} [my clay dump] { - my puts "" - } - my puts "" - my puts
$f$v
$f$v
File Size[my request get CONTENT_LENGTH]
- my puts -} - -puts [list LISTENING on [appmain port_listening]] -cron::main +appmain add_uri /tcllib* [list mixin httpd::content::file path [file join $tcllibroot embedded www]] +appmain add_uri /fossil [list mixin httpd::content::fossil_root {*}$fossilopts] +appmain add_uri /fossil/* [list mixin httpd::content::fossil_node_scgi {*}$fossilopts] +puts [list LISTENING] +tool::main Index: examples/math/bigfloat.demo.tcl ================================================================== --- examples/math/bigfloat.demo.tcl +++ examples/math/bigfloat.demo.tcl @@ -165,16 +165,16 @@ pack $c.fenter -in $c -side left # the functions for numbers frame .functions pack .functions set f .functions - # chaque fonction est associée, d'une part, - # à un bouton portant un libellé, et d'autre part - # à une commande Tcl - # ici nous associons le bouton "add" à la commande "add" + # chaque fonction est associée, d'une part, + # à un bouton portant un libellé, et d'autre part + # à une commande Tcl + # ici nous associons le bouton "add" à la commande "add" addButtonTwo add - # toutes ces commandes se trouvent à la fin de ce fichier + # toutes ces commandes se trouvent à la fin de ce fichier addButtonTwo sub addButtonTwo mul addButtonTwo div addButtonTwo mod addButtonOne opp @@ -302,7 +302,7 @@ # initialize the calculator and create the widgets (GUI) init # chaque fois qu'une commande modifie la pile de nombres, -# la commande drawStack sera appelée pour la réactualiser +# la commande drawStack sera appelée pour la réactualiser trace add variable ::stack write drawStack Index: idoc/man/files/apps/dtplite.n ================================================================== --- idoc/man/files/apps/dtplite.n +++ idoc/man/files/apps/dtplite.n @@ -612,18 +612,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx introduction, doctoc introduction, doctools introduction .SH KEYWORDS HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff .SH CATEGORY Index: idoc/man/files/apps/nns.n ================================================================== --- idoc/man/files/apps/nns.n +++ idoc/man/files/apps/nns.n @@ -374,18 +374,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv(n), nameserv::common(n) .SH KEYWORDS application, client, name service .SH CATEGORY Index: idoc/man/files/apps/nnsd.n ================================================================== --- idoc/man/files/apps/nnsd.n +++ idoc/man/files/apps/nnsd.n @@ -332,18 +332,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv::common(n), nameserv::server(n) .SH KEYWORDS application, name service, server .SH CATEGORY Index: idoc/man/files/apps/nnslog.n ================================================================== --- idoc/man/files/apps/nnslog.n +++ idoc/man/files/apps/nnslog.n @@ -335,18 +335,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv(n), nameserv::common(n) .SH KEYWORDS application, client, name service .SH CATEGORY Index: idoc/man/files/apps/page.n ================================================================== --- idoc/man/files/apps/page.n +++ idoc/man/files/apps/page.n @@ -664,18 +664,10 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" page::pluginmgr .SH KEYWORDS parser generator, text processing .SH CATEGORY Index: idoc/man/files/apps/pt.n ================================================================== --- idoc/man/files/apps/pt.n +++ idoc/man/files/apps/pt.n @@ -955,22 +955,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/apps/tcldocstrip.n ================================================================== --- idoc/man/files/apps/tcldocstrip.n +++ idoc/man/files/apps/tcldocstrip.n @@ -422,18 +422,10 @@ bugs and other problems\&. Please report such in the category \fIdocstrip\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docstrip .SH KEYWORDS \\\&.dtx, LaTeX, conversion, docstrip, documentation, literate programming, markup, source .SH CATEGORY DELETED idoc/man/files/devdoc/tcl_community_communication.n Index: idoc/man/files/devdoc/tcl_community_communication.n ================================================================== --- idoc/man/files/devdoc/tcl_community_communication.n +++ idoc/man/files/devdoc/tcl_community_communication.n @@ -1,434 +0,0 @@ -'\" -'\" Generated from file 'tcl_community_communication\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcl_community_communication" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcl_community_communication \- Tcl Community - Kind Communication -.SH DESCRIPTION -The Tcl Community encourages contributions from anyone who wishes to -advance the development of: -.IP \(bu -The Tcl Language -.IP \(bu -Tcl derived languages -.IP \(bu -Tcl related libraries -.IP \(bu -Tcl extensions -.IP \(bu -External Projects that Integrate Tcl -.PP -.PP -We welcome those contributions from anyone\&. We are blind to -gender, race, religion, cultural background, cybernetic nature, and -any other demographic characteristics, as well as personal political -views\&. -.PP -A community lives and dies by communications\&. And occasionally -our communications are peppered with patterns that are harsh, -unfriendly, unwelcoming and/or otherwise unkind\&. As a volunteer -community, we need all of the help we can get\&. Therefore, we ask all -contributors to make a conscious effort, in Tcl Community discussions, -to communicate in ways that are welcoming\&. Ways that are -friendly\&. Ways that are, in a word: kind\&. -.PP -These guidelines suggest specific ways to accomplish that goal\&. -.PP -Please note: for the balance of this document any reference to -"People", "Persons", "anybody" or "somebody" can refer to any sentient -being, not merely corporeal members of the species Homo Sapien\&. -.TP -We are a Sanctuary not a Clubhouse -The Tcl Community is a collective of amateurs and professionals who -code, test, and use tools\&. Our community is open to all\&. There is no -velvet rope\&. There is no bouncer at the door\&. There are no secret -handshakes\&. Any sentient being who enters our midst is welcome\&. If -someone is ever asked to leave, it is only because they are being -disruptive to the functioning of the community\&. -.TP -We Merit Ideas, Not People -A good idea can come from anyone, regardless of how little time they -have been with us\&. A bad idea can come from anyone, regardless of how -much time or how little time they have been with us\&. We judge a -concept by how it stands up to scrutiny of logic, implementation, and -regression testing\&. We don’t judge ideas based on who had the idea -first, who agrees with the idea, or who disagrees with it\&. -.TP -Treat Everyone with Respect -Everyone is deserving of respect and courtesy at all times\&. -.TP -Refer to people by the names they use\&. -If grammar requires you to state a gender for a person, honor their -preferences about their gender identity\&. If you are unsure as to the -gender of an individual, ask\&. If someone had to guess about your -gender and got it wrong, please correct them and do not take it -personally\&. -.TP -Do not take a harsh tone towards other participants\&. -Do not make personal attacks against anyone (participant or not\&.) -.sp -Criticize statements and actions, never people\&. -.TP -Don’t Take Things Personally -When in doubt, assume the best in people\&. A criticism of your -statements is not a personal attack on you\&. -.TP -Persons, not People -Stereotypes are an unhelpful tool on many accounts\&. They are generally -oversimplified\&. They are usually flat out wrong\&. And even if "right" -they are of absolutely no utility in determining the capabilities, -motivations, or fitness of an individual\&. -.sp -Don’t use them in Tcl Community communications\&. -.TP -Mistakes Happen -The human condition is a series of trials and errors\&. Progress is when -we get one more trial than error\&. Being wrong or making a mistake is -the default state of humanity\&. Accept the errors of your fellow -sentient beings, and be aware that you are also fallible\&. -.TP -Keep it Real -Please respond to what people actually say\&. We are all amazing -individuals, but none among us are mind readers\&. If you find yourself -responding to what you imagine someone is thinking, odds are you are -going to be wrong\&. -.sp -If you must criticize someone, stick to things they have -actually done\&. Never criticize for something you speculate they have -done\&. Or imagine they have done\&. Or something someone who shares some -attribute with them has done in the past\&. -.sp -Keep discussions about any non-Tcl subjects to what can be -stated factually and without emotion or judgement\&. -.TP -When Trouble Arises, Don’t Escalate -If you feel you are being personally attacked or offended, take the -high road\&. Punching back in a public forum will only makes things -worse\&. Address the matter in a private correspondence\&. Be -polite\&. Express your feelings, but note that you are expressing your -feelings\&. When writing, look for a way to calm matters down\&. And when -in doubt, sleep on your letter before pressing send\&. And when not in -doubt, sleep on it for another day after that\&. -.sp -If you are a spectator to a fight in progress, politely request -the two parties take the matter to a more private forum\&. -.TP -Always get the Last Word: I’m Sorry -If an personal argument does arise, be the first to apologize\&. An -apology does not concede a logical point\&. It merely acknowledges that -at some point the discussion left either logic, community decency, or -both\&. Return to the topic when cooler heads can prevail\&. -.TP -Nobody is Keeping Score -There is no prize for being right\&. There is no cost for being wrong\&. A -hard sell is not going to advance your idea along any more than a -logical argument\&. You aren’t running for office\&. This isn’t debate -club\&. If you find yourself continuing a discussion beyond where a -topic can be logically discussed, stop\&. -.TP -No Evangelizing -The Tcl Community is not the place to promote your chosen operating -system, political outlook, religion, marketing scheme, or economic -model\&. Period\&. -.sp -(And if you do bring it up, be prepared to have your chosen -topic discussed logically\&. And odds are, not favorably\&.) -.TP -Respect the Community -If the Community has come to a decision on a course of action, please -stop arguing\&. -.sp -If someone complains about how you are expressing your ideas, -listen\&. -.sp -If your words are hurting people, stop\&. There is no amount of -being "right" that makes up for someone leaving our midst because they -felt insulted, threatened, or ignored\&. -.PP -By following these guidelines, we will build our community, encourage -more contribution to our projects, and our discussions will be -friendlier and reach conclusions more easily\&. -.PP -Thank You\&. -.SH SIGNATORIES -.IP \(bu -Sean "the Hypnotoad" Woods -.IP \(bu -Andreas Kupries -.PP -.SH AUTHORS -.TP -Primary -Sean "the Hypnotoad" Woods -.TP -Light editing -Andreas Kupries -.PP DELETED idoc/man/files/devdoc/tcllib_devguide.n Index: idoc/man/files/devdoc/tcllib_devguide.n ================================================================== --- idoc/man/files/devdoc/tcllib_devguide.n +++ idoc/man/files/devdoc/tcllib_devguide.n @@ -1,1307 +0,0 @@ -'\" -'\" Generated from file 'tcllib_devguide\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcllib_devguide" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcllib_devguide \- Tcllib - The Developer's Guide -.SH SYNOPSIS -\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR -.sp -\fBApplication\fR \fIname\fR -.sp -\fBExclude\fR \fIname\fR -.sp -.BE -.SH DESCRIPTION -Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a -package itself\&. It is a collection of (semi-independent) \fITcl\fR -packages that provide utility functions useful to a large collection -of Tcl programmers\&. -.PP -This document is a guide for developers working on Tcllib, -i\&.e\&. maintainers fixing bugs, extending the collection's -functionality, etc\&. -.PP -Please read -.IP [1] -\fITcllib - How To Get The Sources\fR and -.IP [2] -\fITcllib - The Installer's Guide\fR -.PP -first, if that was not done already\&. -.PP -Here we assume that the sources are already available in a -directory of your choice, and that you not only know how to build and -install them, but also have all the necessary requisites to actually -do so\&. The guide to the sources in particular also explains which -source code management system is used, where to find it, how to set it -up, etc\&. -.SH COMMITMENTS -.SS CONTRIBUTOR -As a contributor to Tcllib you are committing yourself to: -.IP [1] -keep the guidelines written down in -\fITcl Community - Kind Communication\fR in your mind\&. -The main point to take away from there is -\fIto be kind to each other\fR\&. -.IP [2] -Your contributions getting distributed under a BSD/MIT license\&. -For the details see \fITcllib - License\fR -.PP -Contributions are made by entering tickets into our tracker, providing -patches, bundles or branches of code for inclusion, or posting to the -Tcllib related mailing lists\&. -.SS MAINTAINER -When contributing one or more packages for full inclusion into Tcllib -you are committing yourself to -.IP [1] -Keep the guidelines written down in -\fITcl Community - Kind Communication\fR -(as any contributor) in your mind\&. The main point to take away -from there is \fIto be kind to each other\fR\&. -.IP [2] -Your packages getting distributed under a BSD/MIT license\&. For -the details see \fITcllib - License\fR -.IP [3] -Maintenance of the new packages for a period of two years under -the following rules, and responsibilities: -.RS -.IP [1] -A maintainer may step down after the mandatory period as -they see fit\&. -.IP [2] -A maintainer may step down before the end of the -mandatory period, under the condition that a replacement -maintainer is immediately available and has agreed to -serve the remainder of the period, plus their own -mandatory period (see below)\&. -.IP [3] -When stepping down without a replacement maintainer -taking over the relevant packages have to be flagged as -\fBunmaintained\fR\&. -.IP [4] -When a replacement mantainer is brought in for a package -it is (kept) marked as \fBmaintained\fR (again)\&. -.sp -A replacement maintainer is bound by the same rules as -the original maintainer, except that the mandatory -period of maintenance is shortened to one year\&. -.IP [5] -For any \fBunmaintained\fR package a contributor -interested in becoming its maintainer can become so by -flagging them as \fBmaintained\fR with their name and -contact information, committing themselves to the rules -of a replacement maintainer (see previous point)\&. -.IP [6] -For any already \fBmaintained\fR package a contributor -interested in becoming a co-maintainer can become so -with the agreement of the existing maintainer(s), -committing themselves to the rules of a replacement -maintainer (see two points previous)\&. -.RE -.sp -The responsibilities as a maintainer include: -.RS -.IP [1] -Watching Tcllib's ticket tracker for bugs, bug fixes, -and feature requests related to the new packages\&. -.IP [2] -Reviewing the aforementioned tickets, rejecting or -applying them -.IP [3] -Coordination and discussion with ticket submitter during -the development and/or application of bug fixes\&. -.RE -.IP [4] -Follow the \fBBranching and Workflow\fR of this guide\&. -.PP -.SH "BRANCHING AND WORKFLOW" -.SS "PACKAGE DEPENDENCIES" -Regarding packages and dependencies between them Tcllib occupies a -middle position between two extremes: -.IP [1] -On one side a strongly interdependent set of packages, usually -by a single author, for a single project\&. Looking at my -(Andreas Kupries) own work examples of such are -\fIMarpa\fR [https://core\&.tcl\&.tk/akupries/marpa/index], -\fICRIMP\fR [https://core\&.tcl\&.tk/akupries/crimp/index], -\fIKinetcl\fR [https://core\&.tcl\&.tk/akupries/kinetcl/index], etc\&. -.sp -For every change the author of the project handles all the -modifications cascading from any incompatibilities it -introduced to the system\&. -.IP [2] -On the other side, the world of semi-independent projects by -many different authors where authors know what packages their -own creations depend on, yet usually do not know who else -depends on them\&. -.sp -The best thing an author making an (incompatible) change to -their project can do is to for one announce such changes in -some way, and for two use versioning to distinguish the code -before and after the change\&. -.sp -The world is then responsible for adapting, be it by updating -their own projects to the new version, or by sticking to the -old\&. -.PP -As mentioned already, Tcllib lives in the middle of that\&. -.PP -While we as maintainers cannot be aware of all users of -Tcllib's packages, and thus have to rely on the mechanisms -touched on in point 2 above for that, the dependencies between -the packages contained in Tcllib are a different matter\&. -.PP -As we are collectively responsible for the usability of Tcllib -in toto to the outside world, it behooves us to be individually -mindful even of Tcllib packages we are not directly -maintaining, when they depend on packages under our -maintainership\&. -This may be as simple as coordinating with the maintainers of -the affected packages\&. -It may also require us to choose how to adapt affected packages -which do not have maintainers, i\&.e\&. modify them to use our -changed package properly, or modify them to properly depend on -the unchanged version of our package\&. -.PP -Note that the above is not only a chore but an opportunity as -well\&. -Additional insight can be had by forcing ourselves to look at -our package and the planned change(s) from an outside -perspective, to consider the ramifications of our actions on -others in general, and on dependent packages in particular\&. -.SS TRUNK -The management and use of branches is an important part of working -with a \fIDistributed Version Control System\fR (\fIDVCS\fR) like -\fIfossil\fR [https://www\&.fossil-scm\&.org/]\&. -.PP -For Tcllib the main branch of the collection is -\fItrunk\fR\&. In \fIgit\fR this branch would be called -\fImaster\fR, and this is exactly the case in the -\fIgithub mirror\fR [https://github\&.com/tcltk/tcllib/] of -Tcllib\&. -.PP -To properly support debugging \fIeach commit\fR on this -branch \fIhas to pass the entire testsuite\fR of the -collection\&. Using bisection to determine when an issue appeared -is an example of an action made easier by this constraint\&. -.PP -This is part of our collective responsibility for the usability -of Tcllib in toto to the outside world\&. -As \fIfossil\fR has no mechanism to enforce this condition -this is handled on the honor system for developers and maintainers\&. -.PP -To make the task easier Tcllib comes with a tool -("\fIsak\&.tcl\fR") providing a number of commands in -support\&. These commands are explained in the following sections -of this guide\&. -.PP -While it is possible and allowed to commit directly to trunk -remember the above constraint regarding the testsuite, and the -coming notes about other possible issues with a commit\&. -.SS BRANCHES -Given the constraints placed on the \fItrunk\fR branch of the -repository it is (strongly) recommended to perform any development -going beyond trivial changes on a non-trunk branch\&. -.PP -Outside of the trunk developers are allowed to commit -intermediate broken states of their work\&. -Only at the end of a development cycle, when the relevant -branch is considered ready for merging, will it be necessary to -perform full the set of validations ensuring that the merge to -come will create a good commit on trunk\&. -.PP -Note that while a review from a second developer is not a -required condition for merging a branch it is recommended to -seek out such an independent opinion as a means of -cross-checking the work\&. -.PP -It also recommended to give any new branch a name which aids in -determining additional details about it\&. Examples of good -things to stick into a branch name would be -.IP \(bu -Developer (nick)name -.IP \(bu -Ticket hash/reference -.IP \(bu -One or two keywords applicable to the work -.IP \(bu -\&.\&.\&. -.PP -.PP -Further, while most development branches are likely quite -short-lived, no prohibitions exist against making longer-lived -branches\&. -Creators should however be mindful that the longer such a -branch exists without merges the more divergent they will tend -to be, with an associated increase in the effort which will -have to be spent on either merging from and merging to trunk\&. -.SS "WORKING WITH BRANCHES" -In the hope of engendering good work practices now a few example -operations which will come up with branches, and their associated -fossil command (sequences)\&. -.TP -\fIAwareness\fR -When developing we have to keep ourselves aware of the context of our -work\&. On what branch are we ? What files have we changed ? What new -files are not yet known to the repository ? What has happened remotely -since we used our checkout ? -The answers to these questions become especially important when using -a long-lived checkout and coming back to it after some time away\&. -.sp -Commands to answer questions like the above are: -.RS -.TP -\fBfossil pull\fR -Get all changes done on the remote since the last pull or sync -from it\&. This has to be done first, before any of the commands -below\&. -.sp -Even if the commit in our checkout refers to the branch we want -right now control operations committed to the remote may have -changed that from underneath us\&. -.TP -\fBfossil info | grep tags\fR -.TP -\fBfossil branch list | grep '\\*'\fR -Two different ways of determining the branch our checkout is -on\&. -.TP -\fBfossil timeline\fR -What have we (and others) done recently ? -.sp -\fIAttention\fR, this information is very likely outdated, the -more the longer we did not use this checkout\&. -Run \fBfossil pull\fR first to get latest information from -the remote repository of the project\&. -.TP -\fBfossil timeline current\fR -Place the commit our checkout is based on at the top of the -timeline\&. -.TP -\fBfossil changes\fR -Lists the files we have changed compared to the commit the -checkout is based on\&. -.TP -\fBfossil extra\fR -Lists the files we have in the checkout the repository does not -know about\&. This may be leftover chaff from our work, or -something we have forgotten to \fBfossil add\fR to the -repository yet\&. -.RE -.TP -\fIClean checkouts\fR -Be aware of where you are (see first definition)\&. -.sp -For pretty much all the operation recipes below a clean -checkout is at least desired, often required\&. -To check that a checkout is clean invoke -.CS - - - fossil changes - fossil extra - -.CE -.IP -How to clean up when uncommitted changes of all sorts are found is -context-specific and outside of the scope of this guide\&. -.TP -\fIStarting a new branch\fR -Be aware of where you are (see first definition)\&. -.sp -Ensure that you have clean checkout (see second definition)\&. -It is \fIrequired\fR\&. -.sp -In most situations you want to be on branch \fItrunk\fR, and -you want to be on the latest commit for it\&. To get there use -.CS - - - fossil pull - fossil update trunk - -.CE -.IP -If some other branch is desired as the starting point for the coming -work replace \fItrunk\fR in the commands above with the name of that -branch\&. -.sp -With the base line established we now have two ways of creating -the new branch, with differing (dis)advantages\&. -The simpler way is to -.CS - - - fossil branch new NAME_OF_NEW_BRANCH - -.CE -.IP -and start developing\&. The advantage here is that you cannot forget to -create the branch\&. The disadvantages are that we have a branch commit -unchanged from where we branched from, and that we have to use -high-handed techniques like hiding or shunning to get rid of the -commit should we decide to abandon the work before the first actual -commit on the branch\&. -.sp -The other way of creating the branch is to start developing, -and then on the first commit use the option \fB--branch\fR to tell -\fBfossil\fR that we are starting a branch now\&. I\&.e\&. run -.CS - - - fossil commit --branch NAME_OF_NEW_BRANCH \&.\&.\&. - -.CE -.IP -where \fI\&.\&.\&.\fR are any other options used to supply the commit -message, files to commit, etc\&. -.sp -The (dis)advantages are now reversed\&. -.sp -We have no superflous commit, only what is actually -developed\&. The work is hidden until we commit to make our first -commit\&. -.sp -We may forget to use \fB--branch NAME_OF_NEW_BRANCH\fR and -then have to correct that oversight via the fossil web -interface (I am currently unaware of ways of doing such from -the command line, although some magic incantantion of -\fBfossil tag create\fR may work)\&. -.sp -It helps to keep awareness, like checking before any commit -that we are on the desired branch\&. -.TP -\fIMerging a branch into trunk\fR -Be aware of where you are (see first definition)\&. -.sp -Ensure that you have clean checkout (see second definition)\&. -In the full-blown sequence (zig-zag) it is \fIrequired\fR, due -to the merging from trunk\&. In the shorter sequence it is only -desired\&. That said, keeping the checkout clean before -any major operations is a good habit to have, in my opinion\&. -.sp -The full-blown sequencing with checks all the way is to -.RS -.IP [1] -Validate the checkout, i\&.e\&. last commit on your branch\&. Run the -full test suite and other validations, fix all the issues which -have cropped up\&. -.IP [2] -Merge the latest state of the \fItrunk\fR (see next definition)\&. -.IP [3] -Validate the checkout again\&. The incoming trunk changes may -have broken something now\&. Do any required fixes\&. -.IP [4] -Now merge to the trunk using -.CS - - - fossil update trunk - fossil merge --integrate YOUR_BRANCH - -.CE -.IP [5] -At this point the checkout should be in the same state as at -the end of point (3) above, because we resolved any issues with -the trunk already\&. Thus a simple -.CS - - - fossil commit \&.\&.\&. - -.CE -.IP -should be sufficient now to commit the merge back and close the -branch (due to the \fB--integrate\fR we used on the merge)\&. -.sp -The more paranoid may validate the checkout a third time before -commiting\&. -.RE -.sp -I call this a \fIzig-zag merge\fR because of how the arrows -look in the timeline, from trunk to feature branch for the -first merge, and then back for the final merge\&. -.sp -A less paranoid can do what I call a \fIsimple merge\fR, -which moves step (2) after step (4) and skips step (3) -entirely\&. The resulting shorter sequence is -.RS -.IP [1] -Validate -.IP [2] -Merge to trunk -.IP [3] -Validate again -.IP [4] -Commit to trunk -.RE -.IP -The last step after either zig-zag or plain merge is to -.CS - - - fossil sync - -.CE -.IP -This saves our work to the remote side, and further gives us any other -work done while we were doing our merge\&. It especially allows us to -check if we raced somebody else, resulting in a split trunk\&. -.sp -When that happens we should coordinate with the other developer -on who fixes the split, to ensure that we do not race each -other again\&. -.TP -\fIMerging from trunk\fR -Be aware of where you are (see first definition)\&. -.sp -Ensure that you have clean checkout (see second definition)\&. -It is \fIrequired\fR\&. -.sp -In most situations you want to import the latest commit of -branch \fItrunk\fR (or other origin)\&. To get it use -.CS - - - fossil pull - -.CE -.sp -With that done we can now import this commit into our current -branch with -.CS - - - fossil merge trunk - -.CE -.sp -Even if \fBfossil\fR does not report any conflicts it is a -good idea to check that the operation has not broken the new -and/or changed functionality we are working on\&. -.sp -With the establishment of a good merge we then save the state -with -.CS - - - fossil commit \&.\&.\&. - -.CE -.IP -before continuing development\&. -.PP -.SS "VERSION NUMBERS" -In Tcllib all changes to a package have to come with an increment of -its version number\&. What part is incremented (patchlevel, minor, major -version) depends on the kind of change made\&. With multiple changes in -a commit the highest "wins"\&. -.PP -When working in a development branch the version change can be -deferred until it is time to merge, and then has to cover all -the changes in the branch\&. -.PP -Below a list of the kinds of changes and their associated -version increments: -.TP -\fID - documentation\fR -No increment -.TP -\fIT - testsuite\fR -No increment -.TP -\fIB - bugfix\fR -Patchlevel -.TP -\fII - implementation tweak\fR -Patchlevel -.TP -\fIP - performance tweak\fR -Patchlevel -.TP -\fIE - backward-compatible extension\fR -Minor -.TP -\fIAPI - incompatible change\fR -Major -.PP -.PP -Note that a commit containing a version increment has to -mention the new version number in its commit message, as well -as the kind of change which caused it\&. -.PP -Note further that the version number of a package currently -exists in three places\&. An increment has to update all of them: -.IP [1] -The package implementation\&. -.IP [2] -The package index ("\fIpkgIndex\&.tcl\fR") -.IP [3] -The package documentation\&. -.PP -.PP -The "\fIsak\&.tcl\fR" command \fBvalidate version\fR helps -finding discrepancies between the first two\&. -All the other \fBvalidate\fR methods are also of interest to -any developer\&. Invoke it with -.CS - - sak\&.tcl help validate -.CE -to see their documentation\&. -.SH "STRUCTURAL OVERVIEW" -.SS "MAIN DIRECTORIES" -The main directories in the Tcllib toplevel directory and of interest -to a developer are: -.TP -"\fImodules\fR" -Each child directory represents one or more packages\&. -In the case of the latter the packages are usually related in some -way\&. Examples are "\fIbase64\fR", "\fImath\fR", and "\fIstruct\fR", with -loose (base64) to strong (math) relations between the packages in the -directory\&. -.TP -"\fIapps\fR" -This directory contains all the installable applications, with their -documentation\&. Note that this directory is currently \fInot\fR split -into sub-directories\&. -.TP -"\fIexamples\fR" -Each child directory "\fIfoo\fR" contains one or more example -application for the packages in "\fImodules/foo\fR"\&. These examples are -generally not polished enough to be considered for installation\&. -.PP -.SS "MORE DIRECTORIES" -.TP -"\fIconfig\fR" -This directory contains files supporting the Unix build system, -i\&.e\&. "\fIconfigure\fR" and "\fIMakefile\&.in\fR"\&. -.TP -"\fIdevdoc\fR" -This directories contains the doctools sources for the global -documentation, like this document and its sibling guides\&. -.TP -"\fIembedded\fR" -This directory contains the entire documentation formatted for -\fIHTML\fR and styled to properly mix into the web site generated by -fossil for the repository\&. -.sp -This is the documentation accessible from the Tcllib home -directory, represented in the repository as "\fIembedded/index\&.md\fR"\&. -.TP -"\fIidoc\fR" -This directory contains the entire documentation formatted for -\fInroff\fR and \fIHTML\fR, the latter without any styling\&. -This is the documentation which will be installed\&. -.TP -"\fIsupport\fR" -This directory contains the sources of internal packages and utilities -used in the implementation of the "\fIinstaller\&.tcl\fR" and -"\fIsak\&.tcl\fR" scripts/tools\&. -.PP -.SS "TOP FILES" -.TP -"\fIaclocal\&.m4\fR" -.TP -"\fIconfigure\fR" -.TP -"\fIconfigure\&.in\fR" -.TP -"\fIMakefile\&.in\fR" -These four files comprise the Unix build system layered on top of the -"\fIinstaller\&.tcl\fR" script\&. -.TP -"\fIinstaller\&.tcl\fR" -The Tcl-based installation script/tool\&. -.TP -"\fIproject\&.shed\fR" -Configuration file for \fISean Wood\fR's \fBPracTcl\fR -buildsystem\&. -.TP -"\fIsak\&.tcl\fR" -This is the main tool for developers and release managers, the -\fISwiss Army Knife\fR of management operations on the collection\&. -.TP -"\fIChangeLog\fR" -The log of changes to the global support, when the sources were held -in \fICVS\fR\&. Not relevant any longer with the switch to the -\fIfossil\fR SCM\&. -.TP -"\fIlicense\&.terms\fR" -The license in plain ASCII\&. See also \fITcllib - License\fR for the -nicely formatted form\&. The text is identical\&. -.TP -"\fIREADME\&.md\fR" -.TP -"\fI\&.github/CONTRIBUTING\&.md\fR" -.TP -"\fI\&.github/ISSUE_TEMPLATE\&.md\fR" -.TP -"\fI\&.github/PULL_REQUEST_TEMPLATE\&.md\fR" -These markdown-formatted documents are used and shown by the github -mirror of these sources, pointing people back to the official location -and issue trackers\&. -.TP -"\fIDESCRIPTION\&.txt\fR" -.TP -"\fISTATUS\fR" -.TP -"\fItcllib\&.spec\fR" -.TP -"\fItcllib\&.tap\fR" -.TP -"\fItcllib\&.yml\fR" -???? -.PP -.SS "FILE TYPES" -The most common file types, by file extension, are: -.TP -"\fI\&.tcl\fR" -Tcl code for a package, application, or example\&. -.TP -"\fI\&.man\fR" -Doctools-formatted documentation, usually for a package\&. -.TP -"\fI\&.test\fR" -Test suite for a package, or part of\&. -Based on \fBtcltest\fR\&. -.TP -"\fI\&.bench\fR" -Performance benchmarks for a package, or part of\&. -Based on "\fImodules/bench\fR"\&. -.TP -"\fI\&.pcx\fR" -Syntax rules for \fITclDevKit\fR's \fBtclchecker\fR\&. Using these -rules allows the checker to validate the use of commands of a Tcllib -package \fBfoo\fR without having to scan the "\fI\&.tcl\fR" files -implementing it\&. -.PP -.SH "TESTSUITE TOOLING" -Testsuites in Tcllib are based on Tcl's standard test package -\fBtcltest\fR, plus utilities found in the directory -"\fImodules/devtools\fR" -.PP -Tcllib developers invoke the suites through the -\fBtest run\fR method of the "\fIsak\&.tcl\fR" tool, with other methods -of \fBtest\fR providing management operations, for example setting a -list of standard Tcl shells to use\&. -.SS "INVOKE THE TESTSUITES OF A SPECIFIC MODULE" -Invoke either -.CS - - \&./sak\&.tcl test run foo -.CE -or -.CS - - \&./sak\&.tcl test run modules/foo -.CE -to invoke the testsuites found in a specific module "\fIfoo\fR"\&. -.SS "INVOKE THE TESTSUITES OF ALL MODULES" -Invoke the tool without a module name, i\&.e\&. -.CS - - \&./sak\&.tcl test run -.CE -to invoke the testsuites of all modules\&. -.SS "DETAILED TEST LOGS" -In all the previous examples the test runner will write a combination -of progress display and testsuite log to the standard output, showing -for each module only the tests that passed or failed and how many of -each in a summary at the end\&. -.PP -To get a detailed log, it is necessary to invoke the test -runner with additional options\&. -.PP -For one: -.CS - - - \&./sak\&.tcl test run --log LOG foo - -.CE -While this shows the same short log on the terminal as before, it also -writes a detailed log to the file "\fILOG\&.log\fR", and excerpts to -other files ("\fILOG\&.summary\fR", "\fILOG\&.failures\fR", etc\&.)\&. -.PP -For two: -.CS - - - \&./sak\&.tcl test run -v foo - -.CE -This writes the detailed log to the standard output, instead of the -short log\&. -.PP -Regardless of form, the detailed log contains a list of all test -cases executed, which failed, and how they failed (expected versus -actual results)\&. -.SS "SHELL SELECTION" -By default the test runner will use all the Tcl shells specified via -\fBtest add\fR to invoke the specified testsuites, if any\&. If no -such are specified it will fall back to the Tcl shell used to run the -tool itself\&. -.PP -Use option \fB--shell\fR to explicitly specify the Tcl shell -to use, like -.CS - - - \&./sak\&.tcl test run --shell /path/to/tclsh \&.\&.\&. - -.CE -.SS HELP -Invoke the tool as -.CS - - \&./sak\&.tcl help test -.CE -to see the detailed help for all methods of \fBtest\fR, and the -associated options\&. -.SH "DOCUMENTATION TOOLING" -The standard format used for documentation of packages and other -things in Tcllib is \fIdoctools\fR\&. -Its supporting packages are a part of Tcllib, see the directories -"\fImodules/doctools\fR" and "\fImodules/dtplite\fR"\&. The latter is -an application package, with the actual application -"\fIapps/dtplite\fR" a light wrapper around it\&. -.PP -Tcllib developers gain access to these through the \fBdoc\fR -method of the "\fIsak\&.tcl\fR" tool, another (internal) wrapper around -the "\fImodules/dtplite\fR" application package\&. -.SS "GENERATE DOCUMENTATION FOR A SPECIFIC MODULE" -Invoke either -.CS - - \&./sak\&.tcl doc html foo -.CE -or -.CS - - \&./sak\&.tcl doc html modules/foo -.CE -to generate HTML for the documentation found in the module "\fIfoo\fR"\&. -Instead of \fBhtml\fR any other supported format can be used here, -of course\&. -.PP -The generated formatted documentation will be placed into a -directory "\fIdoc\fR" in the current working directory\&. -.SS "GENERATE DOCUMENTATION FOR ALL MODULES" -Invoke the tool without a module name, i\&.e\&. -.CS - - \&./sak\&.tcl doc html -.CE -to generate HTML for the documentation found in all modules\&. -Instead of \fBhtml\fR any other supported format can be used here, -of course\&. -.PP -The generated formatted documentation will be placed into a -directory "\fIdoc\fR" in the current working directory\&. -.SS "AVAILABLE OUTPUT FORMATS, HELP" -Invoke the tool as -.CS - - \&./sak\&.tcl help doc -.CE -to see the entire set of supported output formats which can be -generated\&. -.SS "VALIDATION WITHOUT OUTPUT" -Note the special format \fBvalidate\fR\&. -.PP -Using this value as the name of the format to generate forces -the tool to simply check that the documentation is syntactically -correct, without generating actual output\&. -.PP -Invoke it as either -.CS - - \&./sak\&.tcl doc validate (modules/)foo -.CE -or -.CS - - \&./sak\&.tcl doc validate -.CE -to either check the packages of a specific module or check all of -them\&. -.SH "NOTES ON WRITING A TESTSUITE" -While previous sections talked about running the testsuites for a -module and the packages therein, this has no meaning if the module in -question has no testsuites at all\&. -.PP -This section gives a very basic overview on possible -methodologies for writing tests and testsuites\&. -.PP -First there are "drudgery" tests\&. Written to check absolutely -basic assumptions which should never fail\&. -.PP -For example for a command FOO taking two arguments, three tests -calling it with zero, one, and three arguments\&. The basic checks that -the command fails if it has not enough arguments, or too many\&. -.PP -After that come the tests checking things based on our -knowledge of the command, about its properties and assumptions\&. Some -examples based on the graph operations added during Google's Summer of -Code 2009 are: -.IP \(bu -The BellmanFord command in struct::graph::ops takes a -\fIstartnode\fR as argument, and this node should be a node of -the graph\&. This equals one test case checking the behavior when the -specified node is not a node of the graph\&. -.sp -This often gives rise to code in the implementation which -explicitly checks the assumption and throws an understandable error, -instead of letting the algorithm fail later in some weird -non-deterministic way\&. -.sp -It is not always possible to do such checks\&. The graph argument -for example is just a command in itself, and while we expect -it to exhibit a certain interface, i\&.e\&. a set of sub-commands -aka methods, we cannot check that it has them, except by -actually trying to use them\&. That is done by the algorithm -anyway, so an explicit check is just overhead we can get by -without\&. -.IP \(bu -IIRC one of the distinguishing characteristic of either -BellmanFord and/or Johnson is that they are able to handle -negative weights\&. Whereas Dijkstra requires positive weights\&. -.sp -This induces (at least) three testcases \&.\&.\&. Graph with all -positive weights, all negative, and a mix of positive and -negative weights\&. -Thinking further does the algorithm handle the weight -\fB0\fR as well ? Another test case, or several, if we mix -zero with positive and negative weights\&. -.IP \(bu -The two algorithms we are currently thinking about are about -distances between nodes, and distance can be 'Inf'inity, -i\&.e\&. nodes may not be connected\&. This means that good test -cases are -.RS -.IP [1] -Strongly connected graph -.IP [2] -Connected graph -.IP [3] -Disconnected graph\&. -.RE -.sp -At the extremes of strongly connected and disconnected -we have the fully connected graphs and graphs without edges, -only nodes, i\&.e\&. completely disconnected\&. -.IP \(bu -IIRC both of the algorithms take weighted arcs, and fill in a -default if arcs are left unweighted in the input graph\&. -.sp -This also induces three test cases: -.RS -.IP [1] -Graph will all arcs with explicit weights\&. -.IP [2] -Graph without weights at all\&. -.IP [3] -Graph with mixture of weighted and unweighted graphs\&. -.RE -.PP -.PP -What was described above via examples is called -\fIblack-box\fR testing\&. Test cases are designed and written based on -the developer's knowledge of the properties of the algorithm and its -inputs, without referencing a particular implementation\&. -.PP -Going further, a complement to \fIblack-box\fR testing is -\fIwhite-box\fR\&. For this we know the implementation of the -algorithm, we look at it and design our tests cases so that they force -the code through all possible paths in the implementation\&. Wherever a -decision is made we have a test case forcing a specific direction of -the decision, for all possible combinations and directions\&. It is easy -to get a combinatorial explosion in the number of needed test-cases\&. -.PP -In practice I often hope that the black-box tests I have made -are enough to cover all the paths, obviating the need for white-box -tests\&. -.PP -The above should be enough to make it clear that writing tests -for an algorithm takes at least as much time as coding the algorithm, -and often more time\&. Much more time\&. -See for example also \fIhttp://sqlite\&.org/testing\&.html\fR, a writeup -on how the Sqlite database engine is tested\&. Another article of -interest might be \fIhttps://www\&.researchgate\&.net/publication/298896236\fR\&. -While geared to a particular numerical algorithm it still shows that -even a simple-looking algorithm can lead to an incredible number of -test cases\&. -.PP -An interesting connection is to documentation\&. In one -direction, the properties checked with black-box testing are exactly -the properties which should be documented in the algorithm's man -page\&. And conversely, the documentation of the properties of an -algorithm makes a good reference to base the black-box tests on\&. -.PP -In practice test cases and documentation often get written -together, cross-influencing each other\&. And the actual writing of test -cases is a mix of black and white box, possibly influencing the -implementation while writing the tests\&. Like writing a test for a -condition like \fIstartnode not in input graph\fR serving as -reminder to put a check for this condition into the code\&. -.SH "INSTALLATION TOOLING" -A last thing to consider when adding a new package to the collection -is installation\&. -.PP -How to \fIuse\fR the "\fIinstaller\&.tcl\fR" script is documented -in \fITcllib - The Installer's Guide\fR\&. -.PP -Here we document how to extend said installer so that it may -install new package(s) and/or application(s)\&. -.PP -In most cases only a single file has to be modified, the -"\fIsupport/installation/modules\&.tcl\fR" holding one command per module -and application to install\&. -.PP -The relevant commands are: -.TP -\fBModule\fR \fIname\fR \fIcode-action\fR \fIdoc-action\fR \fIexample-action\fR -Install the packages of module \fIname\fR, found in -"\fImodules/\fIname\fR\fR"\&. -.sp -The \fIcode-action\fR is responsible for installing the -packages and their index\&. The system currently provides -.RS -.TP -\fB_tcl\fR -Copy all "\fI\&.tcl\fR" files found in -"\fImodules/\fIname\fR\fR" into the installation\&. -.TP -\fB_tcr\fR -As \fB_tcl\fR, copy the "\fI\&.tcl\fR" files found in -the subdirectories of "\fImodules/\fIname\fR\fR" as well\&. -.TP -\fB_tci\fR -As \fB_tcl\fR, and copy the "\fItclIndex\&.tcl\fR" file -as well\&. -.TP -\fB_msg\fR -As \fB_tcl\fR, and copy the subdirectory "\fImsgs\fR" -as well\&. -.TP -\fB_doc\fR -As \fB_tcl\fR, and copy the subdirectory -"\fImpformats\fR" as well\&. -.TP -\fB_tex\fR -As \fB_tcl\fR, and copy "\fI\&.tex\fR" files as well\&. -.RE -.sp -The \fIdoc-action\fR is responsible for installing the package -documentation\&. The system currently provides -.RS -.TP -\fB_null\fR -No documentation available, do nothing\&. -.TP -\fB_man\fR -Process the "\fI\&.man\fR" files found in -"\fImodules/\fIname\fR\fR" and install the results (nroff and/or HTML) -in the proper location, as given to the installer\&. -.sp -This is actually a fallback, normally the installer uses the -pre-made formatted documentation found under "\fIidoc\fR"\&. -.RE -.sp -The \fIexample-action\fR is responsible for installing the -examples\&. The system currently provides -.RS -.TP -\fB_null\fR -No examples available, do nothing\&. -.TP -\fB_exa\fR -Copy the the directory "\fIexamples/\fIname\fR\fR" -recursively to the install location for examples\&. -.RE -.TP -\fBApplication\fR \fIname\fR -Install the application with \fIname\fR, found in "\fIapps\fR"\&. -.TP -\fBExclude\fR \fIname\fR -This command signals to the installer which of the listed modules to -\fInot\fR install\&. I\&.e\&. they name the deprecated modules of Tcllib\&. -.PP -.PP -If, and only if the above actions are not suitable for the new -module then a second file has to be modified, -"\fIsupport/installation/actions\&.tcl\fR"\&. -.PP -This file contains the implementations of the available -actions, and is the place where any custom action needed to handle the -special circumstances of module has to be added\&. DELETED idoc/man/files/devdoc/tcllib_installer.n Index: idoc/man/files/devdoc/tcllib_installer.n ================================================================== --- idoc/man/files/devdoc/tcllib_installer.n +++ idoc/man/files/devdoc/tcllib_installer.n @@ -1,597 +0,0 @@ -'\" -'\" Generated from file 'tcllib_installer\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcllib_install_guide" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcllib_install_guide \- Tcllib - The Installer's Guide -.SH DESCRIPTION -Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a -package itself\&. It is a collection of (semi-independent) \fITcl\fR -packages that provide utility functions useful to a large collection -of Tcl programmers\&. -.PP -The audience of this document is anyone wishing to build and install -the packages found in Tcllib, for either themselves, or others\&. -.PP -For developers intending to work on the packages themselves we -additionally provide -.IP [1] -\fITcllib - The Developer's Guide\fR\&. -.PP -.PP -Please read \fITcllib - How To Get The Sources\fR first, if that -was not done already\&. Here we assume that the sources are already -available in a directory of your choice\&. -.PP -.SH REQUISITES -Before Tcllib can be build and used a number of requisites must be installed\&. -These are: -.IP [1] -The scripting language Tcl\&. -For details see \fBTcl\fR\&. -.IP [2] -Optionally, the \fBcritcl\fR package (C embedding) for \fBTcl\fR\&. -For details see \fBCriTcl\fR\&. -.PP -This list assumes that the machine where Tcllib is to be installed is -essentially clean\&. Of course, if parts of the dependencies listed -below are already installed the associated steps can be skipped\&. It is -still recommended to read their sections though, to validate that the -dependencies they talk about are indeed installed\&. -.SS TCL -As we are installing a number of Tcl packages and applications it -should be pretty much obvious that a working installation of Tcl -itself is needed, and I will not belabor the point\&. -.PP -Out of the many possibilities use whatever you are comfortable -with, as long as it provides at the very least Tcl 8\&.2, or higher\&. -This may be a Tcl installation provided by your operating system -distribution, from a distribution-independent vendor, or built by -yourself\&. -.PP -\fINote\fR that the packages in Tcllib have begun to require -8\&.4, 8\&.5, and even 8\&.6\&. Older versions of Tcl will not be able to use -such packages\&. Trying to use them will result in -\fIpackage not found\fR errors, as their package index files will -not register them in versions of the core unable to use them\&. -.PP -Myself, I used (and still use) -\fIActiveState's\fR [http://www\&.activestate\&.com] -ActiveTcl 8\&.5 distribution during development, as I am most familiar -with it\&. -.PP -\fI(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them)\&.\fR\&. -I am currently working for SUSE Software Canada ULC, although not in -Tcl-related areas\&. -.PP -This distribution can be found at -\fIhttp://www\&.activestate\&.com/activetcl\fR\&. Retrieve the archive of -ActiveTcl 8\&.5 (or higher) for your platform and install it as directed -by ActiveState\&. -.PP -For those wishing to build and install Tcl on their own, the -relevant sources can be found at -.TP -Tcl -\fIhttp://core\&.tcl-lang\&.org/tcl/\fR -.PP -together with the necessary instructions on how to build it\&. -.PP -If there are problems with building, installing, or using Tcl, -please file a ticket against \fITcl\fR, or the vendor of your -distribution, and \fInot\fR \fITcllib\fR\&. -.SS CRITCL -The \fBcritcl\fR tool is an \fIoptional\fR dependency\&. -.PP -It is only required when trying to build the C-based -\fIaccelerators\fR for a number of packages, as explained in -\fBCritcl & Accelerators\fR -.PP -Tcllib's build system looks for it in the , -using the name \fBcritcl\fR\&. This is for Unix\&. -On Windows on the other hand the search is more complex\&. First we look -for a proper application \fBcritcl\&.exe\fR\&. When that is not found -we look for a combination of interpreter (\fBtclkitsh\&.exe\fR, -\fBtclsh\&.exe\fR) and starkit (\fBcritcl\&.kit\fR, \fBcritcl\fR) -instead\&. \fINote\fR that the choice of starkit can be overriden via -the environment variable \&. -.PP -Tcllib requires Critcl version 2 or higher\&. -.PP -The github repository providing releases of version 2 and -higher, and the associated sources, can be found at -\fIhttp://andreas-kupries\&.github\&.com/critcl\fR\&. -.PP -Any branch of the repository can be used (if not using the -prebuild starkit or starpack), although the use of the stable branch -\fImaster\fR is recommended\&. -.PP -At the above url is also an explanation on how to build and -install Critcl, including a list of its dependencies\&. -.PP -Its instructions will not be repeated here\&. If there are -problems with these directions please file a ticket against the -\fICritcl\fR project, and not Tcllib\&. -.SH "BUILD & INSTALLATION INSTRUCTIONS" -As Tcllib is mainly a bundle of packages written in pure Tcl building -it is the same as installing it\&. The exceptions to this have their own -subsection, \fBCritcl & Accelerators\fR, later on\&. -.PP -Before that however comes the standard case, differentiated by -the platforms with material differences in the instruction, i\&.e\&. -\fIUnix\fR-like, versus \fIWindows\fR\&. -.PP -Regarding the latter it should also be noted that it is -possible set up an \fIUnix\fR-like environment using projects -like \fIMSYS\fR, \fICygwin\fR, and others\&. In that case the -user has the choice of which instructions to follow\&. -.PP -Regardless of environment or platform, a suitable \fITcl\fR -has to be installed, and its \fBtclsh\fR should be placed on -the (\fIUnix\fR) or associated with -"\fI\&.tcl\fR" files (\fIWindows\fR)\&. -.SS "INSTALLING ON UNIX" -For \fIUnix\fR-like environments Tcllib comes with the standard set -of files to make -.CS - - - \&./configure - make install - -.CE -a suitable way of installing it\&. -This is a standard non-interactive install automatically figuring out -where to place everything, i\&.e\&. packages, applications, and the -manpages\&. -.PP -To get a graphical installer invoke -.CS - - - \&./installer\&.tcl - -.CE -instead\&. -.SS "INSTALLING ON WINDOWS" -In a Windows environment we have the \fBinstaller\&.tcl\fR script to -perform installation\&. -.PP -If the desired \fBtclsh\fR is associated "\fI\&.tcl\fR" files -then double-clicking / opening the \fBinstaller\&.tcl\fR is -enough to invoke it in graphical mode\&. -This assumes that \fITk\fR is installed and available as well\&. -.PP -Without \fITk\fR the only way to invoke the installer are to -open a DOS window, i\&.e\&. \fBcmd\&.exe\fR, and then to invoke -.CS - - - \&./installer\&.tcl - -.CE -inside it\&. -.SS "CRITCL & ACCELERATORS" -While the majority of Tcllib consists of packages written in pure Tcl -a number of packages also have \fIaccelerators\fR associated with them\&. -These are \fBcritcl\fR-based C packages whose use will boost the -performance of the packages using them\&. -These accelerators are optional, and they are not built by default\&. -If they are built according to the instructions below then they will -also be installed as well\&. -.PP -To build the accelerators the normally optional dependency on -\fBcritcl\fR becomes required\&. -.PP -To build and install Tcllib with the accelerators in a -Unix-like environment invoke: -.CS - - - \&./configure - make critcl # Builds the shared library and package holding - # the accelerators, tcllibc - make install # Installs all packages, including the new tcllibc\&. - -.CE -.PP -The underlying tool is "\fIsak\&.tcl\fR" in the toplevel directory -of Tcllib and the command \fBmake critcl\fR is just a wrapper around -.CS - - - \&./sak\&.tcl critcl - -.CE -.PP -Therefore in a Windows environment instead invoke -.CS - - - \&./sak\&.tcl critcl - \&./installer\&.tcl - -.CE -from within a DOS window, i\&.e\&. \fBcmd\&.exe\fR\&. -.SS TOOLING -The core of Tcllib's build system is the script "\fIinstaller\&.tcl\fR" -found in the toplevel directory of a checkout or release\&. -.PP -The -.CS - - - configure ; make install - -.CE -setup available to -developers on Unix-like systems is just a wrapper around it\&. -To go beyond the standard embodied in the wrapper it is -necessary to directly invoke this script\&. -.PP -On Windows system using it directly is the only way to invoke -it\&. -.PP -For basic help invoke it as -.CS - - - \&./installer\&.tcl -help - -.CE -This will print a short list of all the available options to -the standard output channel\&. -.PP -The commands associated with the various \fIinstall\fR targets -in the \fIMakefile\&.in\fR for Unix can be used as additional -examples on how to use this tool as well\&. -.PP -The installer can operate in GUI and CLI modes\&. -By default it chooses the mode automatically, based on if the -Tcl package \fBTk\fR can be used or not\&. -The option \fB-no-gui\fR can be used to force CLI mode\&. -.PP -Note that it is possible to specify options on the command line -even if the installer ultimatively selects GUI mode\&. In that -case the hardwired defaults and the options determine the data -presented to the user for editing\&. -.PP -The installer will select a number of defaults for the -locations of packages, examples, and documentation, and also -the format of the documentation\&. The user can overide these -defaults in the GUI, or by specifying additional options\&. -The defaults depend on the platform detected (Unix/Windows) and -on the \fBtclsh\fR executable used to run the installer\&. -.PP -\fIOptions\fR -.TP -\fB-help\fR -Show the list of options explained here on the standard output channel -and exit\&. -.TP -\fB+excluded\fR -Include deprecated packages in the installation\&. -.TP -\fB-no-gui\fR -Force command line operation of the installer -.TP -\fB-no-wait\fR -In CLI mode the installer will by default ask the user to confirm that -the chosen configuration (destination paths, things to install) is -correct before performing any action\&. Using this option causes the -installer to skip this query and immediately jump to installation\&. -.TP -\fB-app-path\fR \fIpath\fR -.TP -\fB-example-path\fR \fIpath\fR -.TP -\fB-html-path\fR \fIpath\fR -.TP -\fB-nroff-path\fR \fIpath\fR -.TP -\fB-pkg-path\fR \fIpath\fR -Declare the destination paths for the applications, examples, html -documentation, nroff manpages, and packages\&. The defaults are derived -from the location of the \fBtclsh\fR used to run the installer\&. -.TP -\fB-dry-run\fR -.TP -\fB-simulate\fR -Run the installer without modifying the destination directories\&. -.TP -\fB-apps\fR -.TP -\fB-no-apps\fR -.TP -\fB-examples\fR -.TP -\fB-no-examples\fR -.TP -\fB-pkgs\fR -.TP -\fB-no-pkgs\fR -.TP -\fB-html\fR -.TP -\fB-no-html\fR -.TP -\fB-nroff\fR -.TP -\fB-no-nroff\fR -(De)activate the installation of applications, examples, packages, -html documentation, and nroff manpages\&. -.sp -Applications, examples, and packages are installed by default\&. -.sp -On Windows the html documentation is installed by default\&. -.sp -On Unix the nroff manpages are installed by default\&. -.PP DELETED idoc/man/files/devdoc/tcllib_license.n Index: idoc/man/files/devdoc/tcllib_license.n ================================================================== --- idoc/man/files/devdoc/tcllib_license.n +++ idoc/man/files/devdoc/tcllib_license.n @@ -1,321 +0,0 @@ -'\" -'\" Generated from file 'tcllib_license\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcllib_license" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcllib_license \- Tcllib - License -.SH DESCRIPTION -Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a -package itself\&. It is a collection of (semi-independent) \fITcl\fR -packages that provide utility functions useful to a large collection -of Tcl programmers\&. -.PP -The collection is under the BSD license\&. -.SH LICENSE -.PP -This software is copyrighted by Ajuba Solutions and other parties\&. -The following terms apply to all files associated with the software -unless explicitly disclaimed in individual files\&. -.PP -The authors hereby grant permission to use, copy, modify, distribute, -and license this software and its documentation for any purpose, -provided that existing copyright notices are retained in all copies -and that this notice is included verbatim in any distributions\&. No -written agreement, license, or royalty fee is required for any of the -authorized uses\&. Modifications to this software may be copyrighted by -their authors and need not follow the licensing terms described here, -provided that the new terms are clearly indicated on the first page of -each file where they apply\&. -.PP -IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY -FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY -DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE\&. -.PP -THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND -NON-INFRINGEMENT\&. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND -THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE -MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS\&. -.PP -GOVERNMENT USE: If you are acquiring this software on behalf of the -U\&.S\&. government, the Government shall have only "Restricted Rights" in -the software and related documentation as defined in the Federal -Acquisition Regulations (FARs) in Clause 52\&.227\&.19 (c) (2)\&. If you -are acquiring the software on behalf of the Department of Defense, the -software shall be classified as "Commercial Computer Software" and the -Government shall have only "Restricted Rights" as defined in Clause -252\&.227-7013 (c) (1) of DFARs\&. Notwithstanding the foregoing, the -authors grant the U\&.S\&. Government and others acting in its behalf -permission to use and distribute the software in accordance with the -terms specified in this license\&. DELETED idoc/man/files/devdoc/tcllib_releasemgr.n Index: idoc/man/files/devdoc/tcllib_releasemgr.n ================================================================== --- idoc/man/files/devdoc/tcllib_releasemgr.n +++ idoc/man/files/devdoc/tcllib_releasemgr.n @@ -1,359 +0,0 @@ -'\" -'\" Generated from file 'tcllib_releasemgr\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcllib_releasemgr" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcllib_releasemgr \- Tcllib - The Release Manager's Guide -.SH DESCRIPTION -Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a -package itself\&. It is a collection of (semi-independent) \fITcl\fR -packages that provide utility functions useful to a large collection -of Tcl programmers\&. -.PP -The audience of this document is the release manager for Tcllib, their -deputies, and anybody else interested in the task of creating -an official release of Tcllib for distribution\&. -.PP -Please read \fITcllib - How To Get The Sources\fR first, if that -was not done already\&. Here we assume that the sources are already -available in a directory of your choice\&. -.PP -.SH TOOLS -The "\fIsak\&.tcl\fR" script in the toplevel directory of a Tcllib -checkout is the one tool used by the release manager to perform its -\fBTasks\fR\&. -.PP -The main commands to be used are -.CS - - - sak\&.tcl validate - sak\&.tcl test run - sak\&.tcl review - sak\&.tcl readme - sak\&.tcl localdoc - sak\&.tcl release - -.CE -More detail will be provided in the explanations of the various -\fBTasks\fR\&. -.SH TASKS -.SS "START A RELEASE CANDIDATE" -todo: open a candidate for release -.SS "READY THE CANDIDATE" -todo: test, validate and check that the candidate is worthy of release -fix testsuites, possibly fix packages, documentation -regenerate docs -coordinate with package maintainers wrt fixes -big thing: going over the packages, classify changes since last -release to generate a nice readme\&. -.SS "MAKE IT OFFICIAL" -todo: finalize release, make candidate official -.SS "DISTRIBUTE THE RELEASE" -With the release made it has to be published and the world notified of -its existence\&. -.IP [1] -Create a proper fossil event for the release, via -\fIhttp://core\&.tcl-lang\&.org/tcllib/eventedit\fR\&. -.sp -An \fIexisting event\fR [http://core\&.tcl-lang\&.org/tcllib/event/dac0ddcd2e990234143196b4dc438fe01e7b9817] should be used as template\&. -.IP [2] -Update a number of web locations: -.RS -.IP [1] -\fIHome page\fR [http://core\&.tcl-lang\&.org/tcllib/doc/trunk/embedded/index\&.md] -.IP [2] -\fIDownloads\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Downloads] -.IP [3] -\fIPast Releases\fR [http://core\&.tcl-lang\&.org/tcllib/wiki?name=Past+Releases] -.IP [4] -\fIhttp://www\&.tcl-lang\&.org/home/release\&.txt\fR -.IP [5] -\fIhttp://www\&.tcl-lang\&.org/software/tcllib/*\&.tml\fR -.IP [6] -\fIhttp://wiki\&.tcl-lang\&.org/page/Tcllib\fR -.RE -.IP -The first location maps to the file "\fIembedded/index\&.md\fR" in the -repository itself, as such it can edited as part of the release -process\&. This is where reference to the new fossil event is added, as -the new current release\&. -.sp -The next two locations are in the fossil tcllib wiki and -require admin or wiki write permissions for -\fIhttp://core\&.tcl-lang\&.org/tcllib\fR\&. -.sp -The last two locations require ssh access to -\fIhttp://www\&.tcl-lang\&.org\fR and permission to edit -files in the web area\&. -.IP [3] -***TODO*** mailing lists and other places to send notes to\&. -.PP DELETED idoc/man/files/devdoc/tcllib_sources.n Index: idoc/man/files/devdoc/tcllib_sources.n ================================================================== --- idoc/man/files/devdoc/tcllib_sources.n +++ idoc/man/files/devdoc/tcllib_sources.n @@ -1,332 +0,0 @@ -'\" -'\" Generated from file 'tcllib_sources\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "tcllib_sources" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -tcllib_sources \- Tcllib - How To Get The Sources -.SH DESCRIPTION -Welcome to Tcllib, the Tcl Standard Library\&. Note that Tcllib is not a -package itself\&. It is a collection of (semi-independent) \fITcl\fR -packages that provide utility functions useful to a large collection -of Tcl programmers\&. -.PP -The audience of this document is anyone wishing to either have just a -look at Tcllib's source code, or build the packages, or to extend and -modify them\&. -.PP -For builders and developers we additionally provide -.IP [1] -\fITcllib - The Installer's Guide\fR\&. -.IP [2] -\fITcllib - The Developer's Guide\fR\&. -.PP -respectively\&. -.SH "SOURCE LOCATION" -The official repository for Tcllib can be found at -\fIhttp://core\&.tcl-lang\&.org/tcllib\fR -.SH RETRIEVAL -Assuming that you simply wish to look at the sources, or build a -specific revision, the easiest way of retrieving it is to: -.IP [1] -Log into this site, as "anonymous", using the semi-random password in the captcha\&. -.IP [2] -Go to the "Timeline"\&. -.IP [3] -Choose the revision you wish to have\&. -.IP [4] -Follow its link to its detailed information page\&. -.IP [5] -On that page, choose either the "ZIP" or "Tarball" link to get -a copy of this revision in the format of your choice\&. -.PP -.SH "SOURCE CODE MANAGEMENT" -For the curious (or a developer-to-be), the sources are managed by the -\fIFossil SCM\fR [http://www\&.fossil-scm\&.org]\&. -Binaries for popular platforms can be found directly at its -\fIdownload page\fR [http://www\&.fossil-scm\&.org/download\&.html]\&. -.PP -With that tool available the full history can be retrieved via: -.CS - - - fossil clone http://core\&.tcl-lang\&.org/tcllib tcllib\&.fossil - -.CE -followed by -.CS - - - mkdir tcllib - cd tcllib - fossil open \&.\&./tcllib\&.fossil - -.CE -to get a checkout of the head of the trunk\&. Index: idoc/man/files/modules/aes/aes.n ================================================================== --- idoc/man/files/modules/aes/aes.n +++ idoc/man/files/modules/aes/aes.n @@ -403,18 +403,10 @@ bugs and other problems\&. Please report such in the category \fIaes\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" blowfish(n), des(n), md5(n), sha1(n) .SH KEYWORDS aes, block cipher, data integrity, encryption, security .SH CATEGORY Index: idoc/man/files/modules/amazon-s3/S3.n ================================================================== --- idoc/man/files/modules/amazon-s3/S3.n +++ idoc/man/files/modules/amazon-s3/S3.n @@ -1612,13 +1612,12 @@ be invoked on multiple machines to run scripts on all the machines, each moving on to the next unstarted task as it finishes each\&. This is still being designed, and it is intended primarily to be run on Amazon's Elastic Compute Cloud\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -1646,22 +1645,14 @@ bugs and other problems\&. Please report such in the category \fIamazon-s3\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS amazon, cloud, s3 .SH CATEGORY Networking .SH COPYRIGHT .nf 2006,2008 Darren New\&. All Rights Reserved\&. See LICENSE\&.TXT for terms\&. .fi Index: idoc/man/files/modules/amazon-s3/xsxp.n ================================================================== --- idoc/man/files/modules/amazon-s3/xsxp.n +++ idoc/man/files/modules/amazon-s3/xsxp.n @@ -409,22 +409,14 @@ bugs and other problems\&. Please report such in the category \fIamazon-s3\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS dom, parser, xml .SH CATEGORY Text processing .SH COPYRIGHT .nf 2006 Darren New\&. All Rights Reserved\&. .fi Index: idoc/man/files/modules/asn/asn.n ================================================================== --- idoc/man/files/modules/asn/asn.n +++ idoc/man/files/modules/asn/asn.n @@ -733,18 +733,10 @@ bugs and other problems\&. Please report such in the category \fIasn\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS asn, ber, cer, der, internet, protocol, x\&.208, x\&.209 .SH CATEGORY Networking .SH COPYRIGHT Index: idoc/man/files/modules/base32/base32.n ================================================================== --- idoc/man/files/modules/base32/base32.n +++ idoc/man/files/modules/base32/base32.n @@ -343,22 +343,14 @@ bugs and other problems\&. Please report such in the category \fIbase32\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS base32, rfc3548 .SH CATEGORY Text processing .SH COPYRIGHT .nf Public domain .fi Index: idoc/man/files/modules/base32/base32core.n ================================================================== --- idoc/man/files/modules/base32/base32core.n +++ idoc/man/files/modules/base32/base32core.n @@ -331,22 +331,14 @@ bugs and other problems\&. Please report such in the category \fIbase32\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS base32 .SH CATEGORY Text processing .SH COPYRIGHT .nf Public domain .fi Index: idoc/man/files/modules/base32/base32hex.n ================================================================== --- idoc/man/files/modules/base32/base32hex.n +++ idoc/man/files/modules/base32/base32hex.n @@ -345,22 +345,14 @@ bugs and other problems\&. Please report such in the category \fIbase32\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS base32, hex, rfc3548 .SH CATEGORY Text processing .SH COPYRIGHT .nf Public domain .fi Index: idoc/man/files/modules/base64/ascii85.n ================================================================== --- idoc/man/files/modules/base64/ascii85.n +++ idoc/man/files/modules/base64/ascii85.n @@ -344,22 +344,14 @@ bugs and other problems\&. Please report such in the category \fIbase64\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ascii85, encoding .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2010, Emiliano Gavilán .fi Index: idoc/man/files/modules/base64/base64.n ================================================================== --- idoc/man/files/modules/base64/base64.n +++ idoc/man/files/modules/base64/base64.n @@ -340,18 +340,10 @@ bugs and other problems\&. Please report such in the category \fIbase64\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS base64, encoding .SH CATEGORY Text processing .SH COPYRIGHT Index: idoc/man/files/modules/base64/uuencode.n ================================================================== --- idoc/man/files/modules/base64/uuencode.n +++ idoc/man/files/modules/base64/uuencode.n @@ -369,22 +369,14 @@ bugs and other problems\&. Please report such in the category \fIbase64\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS encoding, uuencode .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts .fi Index: idoc/man/files/modules/base64/yencode.n ================================================================== --- idoc/man/files/modules/base64/yencode.n +++ idoc/man/files/modules/base64/yencode.n @@ -352,22 +352,14 @@ bugs and other problems\&. Please report such in the category \fIbase64\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS encoding, yEnc, ydecode, yencode .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts .fi Index: idoc/man/files/modules/bee/bee.n ================================================================== --- idoc/man/files/modules/bee/bee.n +++ idoc/man/files/modules/bee/bee.n @@ -562,22 +562,14 @@ bugs and other problems\&. Please report such in the category \fIbee\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS BitTorrent, bee, bittorrent, serialization, torrent .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries .fi Index: idoc/man/files/modules/bench/bench.n ================================================================== --- idoc/man/files/modules/bench/bench.n +++ idoc/man/files/modules/bench/bench.n @@ -502,18 +502,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench_intro, bench_lang_intro, bench_lang_spec, bench_read, bench_wcsv, bench_wtext .SH KEYWORDS benchmark, merging, normalization, performance, testing .SH CATEGORY Index: idoc/man/files/modules/bench/bench_intro.n ================================================================== --- idoc/man/files/modules/bench/bench_intro.n +++ idoc/man/files/modules/bench/bench_intro.n @@ -314,18 +314,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench, bench_lang_faq, bench_lang_intro, bench_lang_spec .SH KEYWORDS bench language, benchmark, performance, testing .SH CATEGORY Index: idoc/man/files/modules/bench/bench_lang_intro.n ================================================================== --- idoc/man/files/modules/bench/bench_lang_intro.n +++ idoc/man/files/modules/bench/bench_lang_intro.n @@ -392,18 +392,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench_intro, bench_lang_spec .SH KEYWORDS bench language, benchmark, examples, performance, testing .SH CATEGORY Index: idoc/man/files/modules/bench/bench_lang_spec.n ================================================================== --- idoc/man/files/modules/bench/bench_lang_spec.n +++ idoc/man/files/modules/bench/bench_lang_spec.n @@ -380,18 +380,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench_intro, bench_lang_intro .SH KEYWORDS bench language, benchmark, performance, specification, testing .SH CATEGORY Index: idoc/man/files/modules/bench/bench_read.n ================================================================== --- idoc/man/files/modules/bench/bench_read.n +++ idoc/man/files/modules/bench/bench_read.n @@ -320,18 +320,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench, bench::out::csv, bench::out::text, bench_intro .SH KEYWORDS benchmark, csv, formatting, human readable, parsing, performance, reading, testing, text .SH CATEGORY Index: idoc/man/files/modules/bench/bench_wcsv.n ================================================================== --- idoc/man/files/modules/bench/bench_wcsv.n +++ idoc/man/files/modules/bench/bench_wcsv.n @@ -308,18 +308,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench, bench::out::text .SH KEYWORDS benchmark, csv, formatting, performance, testing .SH CATEGORY Index: idoc/man/files/modules/bench/bench_wtext.n ================================================================== --- idoc/man/files/modules/bench/bench_wtext.n +++ idoc/man/files/modules/bench/bench_wtext.n @@ -308,18 +308,10 @@ bugs and other problems\&. Please report such in the category \fIbench\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" bench, bench::out::csv .SH KEYWORDS benchmark, formatting, human readable, performance, testing, text .SH CATEGORY Index: idoc/man/files/modules/bibtex/bibtex.n ================================================================== --- idoc/man/files/modules/bibtex/bibtex.n +++ idoc/man/files/modules/bibtex/bibtex.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'bibtex\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2005 for documentation, Andreas Kupries '\" -.TH "bibtex" n 0\&.7 tcllib "bibtex" +.TH "bibtex" n 0\&.6 tcllib "bibtex" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME bibtex \- Parse bibtex files .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBbibtex ?0\&.7?\fR +package require \fBbibtex ?0\&.6?\fR .sp \fB::bibtex::parse\fR ?\fIoptions\fR? ?\fItext\fR? .sp \fB::bibtex::parse\fR \fItext\fR .sp @@ -420,22 +420,14 @@ bugs and other problems\&. Please report such in the category \fIbibtex\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS bibliography, bibtex, parsing, text processing .SH CATEGORY Text processing .SH COPYRIGHT .nf Copyright (c) 2005 for documentation, Andreas Kupries .fi Index: idoc/man/files/modules/blowfish/blowfish.n ================================================================== --- idoc/man/files/modules/blowfish/blowfish.n +++ idoc/man/files/modules/blowfish/blowfish.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'blowfish\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003, Pat Thoyts '\" -.TH "blowfish" n 1\&.0\&.5 tcllib "Blowfish Block Cipher" +.TH "blowfish" n 1\&.0\&.3 tcllib "Blowfish Block Cipher" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME blowfish \- Implementation of the Blowfish block cipher .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBblowfish ?1\&.0\&.5?\fR +package require \fBblowfish ?1\&.0\&.4?\fR .sp \fB::blowfish::blowfish\fR ?\fI-mode [ecb|cbc]\fR? ?\fI-dir [encrypt|decrypt]\fR? \fI-key keydata\fR ?\fI-iv vector\fR? ?\fI-out channel\fR? ?\fI-chunksize size\fR? ?\fI-pad padchar\fR? [ \fI-in channel\fR | ?\fI--\fR? \fIdata\fR ] .sp \fB::blowfish::Init\fR \fImode\fR \fIkeydata\fR \fIiv\fR .sp @@ -402,18 +402,10 @@ bugs and other problems\&. Please report such in the category \fIblowfish\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" 3des, des, rc4 .SH KEYWORDS block cipher, blowfish, cryptography, encryption, security .SH CATEGORY Index: idoc/man/files/modules/cache/async.n ================================================================== --- idoc/man/files/modules/cache/async.n +++ idoc/man/files/modules/cache/async.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'async\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2008 Andreas Kupries '\" -.TH "cache::async" n 0\&.3\&.1 tcllib "In-memory caches" +.TH "cache::async" n 0\&.3 tcllib "In-memory caches" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME cache::async \- Asynchronous in-memory cache .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBcache::async ?0\&.3\&.1?\fR +package require \fBcache::async ?0\&.3?\fR .sp \fB::cache::async\fR \fIobjectName\fR \fIcommandprefix\fR ?\fIoptions\fR\&.\&.\&.? .sp \fIobjectName\fR \fBget\fR \fIkey\fR \fIdonecmdprefix\fR .sp @@ -395,20 +395,12 @@ bugs and other problems\&. Please report such in the category \fIcache\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS asynchronous, cache, callback, synchronous .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries .fi DELETED idoc/man/files/modules/clay/clay.n Index: idoc/man/files/modules/clay/clay.n ================================================================== --- idoc/man/files/modules/clay/clay.n +++ idoc/man/files/modules/clay/clay.n @@ -1,1071 +0,0 @@ -'\" -'\" Generated from file 'clay\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2018 Sean Woods -'\" -.TH "clay" n 0\&.8\&.6 tcllib "Clay Framework" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -clay \- A minimalist framework for large scale OO Projects -.SH SYNOPSIS -package require \fBTcl 8\&.6\fR -.sp -package require \fBuuid \fR -.sp -package require \fBoo::dialect \fR -.sp -proc \fBclay::PROC\fR \fIname\fR \fIarglist\fR \fIbody\fR ?\fIninja\fR \fB\fR? -.sp -proc \fBclay::_ancestors\fR \fIresultvar\fR \fIclass\fR -.sp -proc \fBclay::ancestors\fR ?\fIargs\fR? -.sp -proc \fBclay::args_to_dict\fR ?\fIargs\fR? -.sp -proc \fBclay::args_to_options\fR ?\fIargs\fR? -.sp -proc \fBclay::dynamic_arguments\fR \fIensemble\fR \fImethod\fR \fIarglist\fR ?\fIargs\fR? -.sp -proc \fBclay::dynamic_wrongargs_message\fR \fIarglist\fR -.sp -proc \fBclay::is_dict\fR \fId\fR -.sp -proc \fBclay::is_null\fR \fIvalue\fR -.sp -proc \fBclay::leaf\fR ?\fIargs\fR? -.sp -proc \fBclay::K\fR \fIa\fR \fIb\fR -.sp -proc \fBclay::noop\fR ?\fIargs\fR? -.sp -proc \fBclay::cleanup\fR -.sp -proc \fBclay::object_create\fR \fIobjname\fR ?\fIclass\fR \fB\fR? -.sp -proc \fBclay::object_rename\fR \fIobject\fR \fInewname\fR -.sp -proc \fBclay::object_destroy\fR ?\fIargs\fR? -.sp -proc \fBclay::path\fR ?\fIargs\fR? -.sp -proc \fBclay::putb\fR ?\fImap\fR? \fItext\fR -.sp -proc \fBclay::script_path\fR -.sp -proc \fBclay::NSNormalize\fR \fIqualname\fR -.sp -proc \fBclay::uuid_generate\fR ?\fIargs\fR? -.sp -proc \fBclay::uuid::generate_tcl_machinfo\fR -.sp -proc \fBclay::uuid::tostring\fR \fIuuid\fR -.sp -proc \fBclay::uuid::fromstring\fR \fIuuid\fR -.sp -proc \fBclay::uuid::equal\fR \fIleft\fR \fIright\fR -.sp -proc \fBclay::uuid\fR \fIcmd\fR ?\fIargs\fR? -.sp -proc \fBclay::tree::sanitize\fR \fIdict\fR -.sp -proc \fBclay::tree::_sanitizeb\fR \fIpath\fR \fIvarname\fR \fIdict\fR -.sp -proc \fBclay::tree::storage\fR \fIrawpath\fR -.sp -proc \fBclay::tree::dictset\fR \fIvarname\fR ?\fIargs\fR? -.sp -proc \fBclay::tree::dictmerge\fR \fIvarname\fR ?\fIargs\fR? -.sp -proc \fBclay::tree::merge\fR ?\fIargs\fR? -.sp -proc \fBdictargs::proc\fR \fIname\fR \fIargspec\fR \fIbody\fR -.sp -proc \fBdictargs::method\fR \fIname\fR \fIargspec\fR \fIbody\fR -.sp -proc \fBclay::dialect::Push\fR \fIclass\fR -.sp -proc \fBclay::dialect::Peek\fR -.sp -proc \fBclay::dialect::Pop\fR -.sp -proc \fBclay::dialect::create\fR \fIname\fR ?\fIparent\fR \fB\fR? -.sp -proc \fBclay::dialect::NSNormalize\fR \fInamespace\fR \fIqualname\fR -.sp -proc \fBclay::dialect::DefineThunk\fR \fItarget\fR ?\fIargs\fR? -.sp -proc \fBclay::dialect::Canonical\fR \fInamespace\fR \fINSpace\fR \fIclass\fR -.sp -proc \fBclay::dialect::Define\fR \fInamespace\fR \fIclass\fR ?\fIargs\fR? -.sp -proc \fBclay::dialect::Aliases\fR \fInamespace\fR ?\fIargs\fR? -.sp -proc \fBclay::dialect::SuperClass\fR \fInamespace\fR ?\fIargs\fR? -.sp -proc \fBclay::dynamic_methods\fR \fIclass\fR -.sp -proc \fBclay::dynamic_methods_class\fR \fIthisclass\fR -.sp -proc \fBclay::define::Array\fR \fIname\fR ?\fIvalues\fR \fB\fR? -.sp -proc \fBclay::define::Delegate\fR \fIname\fR \fIinfo\fR -.sp -proc \fBclay::define::constructor\fR \fIarglist\fR \fIrawbody\fR -.sp -proc \fBclay::define::Class_Method\fR \fIname\fR \fIarglist\fR \fIbody\fR -.sp -proc \fBclay::define::class_method\fR \fIname\fR \fIarglist\fR \fIbody\fR -.sp -proc \fBclay::define::clay\fR ?\fIargs\fR? -.sp -proc \fBclay::define::destructor\fR \fIrawbody\fR -.sp -proc \fBclay::define::Dict\fR \fIname\fR ?\fIvalues\fR \fB\fR? -.sp -proc \fBclay::define::Option\fR \fIname\fR ?\fIargs\fR? -.sp -proc \fBclay::define::Method\fR \fIname\fR \fIargstyle\fR \fIargspec\fR \fIbody\fR -.sp -proc \fBclay::define::Option_Class\fR \fIname\fR ?\fIargs\fR? -.sp -proc \fBclay::define::Variable\fR \fIname\fR ?\fIdefault\fR \fB\fR? -.sp -proc \fBclay::ensemble_methodbody\fR \fIensemble\fR \fIeinfo\fR -.sp -proc \fBclay::define::Ensemble\fR \fIrawmethod\fR ?\fIargs\fR? -.sp -proc \fBclay::event::cancel\fR \fIself\fR ?\fItask\fR \fB*\fR? -.sp -proc \fBclay::event::generate\fR \fIself\fR \fIevent\fR ?\fIargs\fR? -.sp -proc \fBclay::event::nextid\fR -.sp -proc \fBclay::event::Notification_list\fR \fIself\fR \fIevent\fR ?\fIstackvar\fR \fB\fR? -.sp -proc \fBclay::event::notify\fR \fIrcpt\fR \fIsender\fR \fIevent\fR \fIeventinfo\fR -.sp -proc \fBclay::event::process\fR \fIself\fR \fIhandle\fR \fIscript\fR -.sp -proc \fBclay::event::schedule\fR \fIself\fR \fIhandle\fR \fIinterval\fR \fIscript\fR -.sp -proc \fBclay::event::subscribe\fR \fIself\fR \fIwho\fR \fIevent\fR -.sp -proc \fBclay::event::unsubscribe\fR \fIself\fR ?\fIargs\fR? -.sp -proc \fBclay::singleton\fR \fIname\fR \fIscript\fR -.sp -method \fBclay ancestors\fR -.sp -method \fBclay dump\fR -.sp -method \fBclay find\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay GET\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR? -.sp -method \fBclay replace\fR \fIdictionary\fR -.sp -method \fBclay search\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR -.sp -method \fBclay ancestors\fR -.sp -method \fBclay cache\fR \fIpath\fR \fIvalue\fR -.sp -method \fBclay cget\fR \fIfield\fR -.sp -method \fBclay delegate\fR ?\fIstub\fR? ?\fIobject\fR? -.sp -method \fBclay dump\fR -.sp -method \fBclay ensemble_map\fR -.sp -method \fBclay eval\fR \fIscript\fR -.sp -method \fBclay evolve\fR -.sp -method \fBclay exists\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay flush\fR -.sp -method \fBclay forward\fR \fImethod\fR \fIobject\fR -.sp -method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay leaf\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR? -.sp -method \fBclay mixin\fR \fIclass\fR ?\fBclass\&.\&.\&.\fR? -.sp -method \fBclay mixinmap\fR ?\fIstub\fR? ?\fIclasses\fR? -.sp -method \fBclay provenance\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -.sp -method \fBclay replace\fR \fIdictionary\fR -.sp -method \fBclay search\fR \fIpath\fR \fIvaluevar\fR \fIisleafvar\fR -.sp -method \fBclay source\fR \fIfilename\fR -.sp -method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR -.sp -method \fBInitializePublic\fR -.sp -.BE -.SH DESCRIPTION -Clay introduces a method ensemble to both \fBoo::class\fR and \fBoo::object\fR called -clay\&. This ensemble handles all of the high level interactions within the framework\&. -Clay stores structured data\&. Clan manages method delegation\&. Clay has facilities to -manage the complex interactions that come about with mixins\&. -.PP -The central concept is that inside of every object and class -(which are actually objects too) is a dict called clay\&. What is stored in that dict is -left to the imagination\&. But because this dict is exposed via a public method, we can -share structured data between object, classes, and mixins\&. -.PP -.SS "STRUCTURED DATA" -Clay uses a standardized set of method interactions and introspection that TclOO already provides to perform on-the-fly searches\&. On-the-fly searches mean that the data is never stale, and we avoid many of the sorts of collisions that would arise when objects start mixing in other classes during operation\&. -.PP -The \fBclay\fR methods for both classes and objects have a get and a set method\&. For objects, get will search through the local clay dict\&. If the requested leaf is not found, or the query is for a branch, the system will then begin to poll the clay methods of all of the class that implements the object, all of that classes’ ancestors, as well as all of the classes that have been mixed into this object, and all of their ancestors\&. -.PP -Intended branches on a tree end with a directory slash (/)\&. Intended leaves are left unadorned\&. This is a guide for the tool that builds the search -results to know what parts of a dict are intended to be branches and which are intended to be leaves\&. -For simple cases, branch marking can be ignored: -.CS - - -::oo::class create ::foo { } -::foo clay set property/ color blue -::foo clay set property/ shape round - -set A [::foo new] -$A clay get property/ -{color blue shape round} - -$A clay set property/ shape square -$A clay get property/ -{color blue shape square} - -.CE -.PP -But when you start storing blocks of text, guessing what field is a dict and what isn’t gets messy: -.CS - - -::foo clay set description {A generic thing of designated color and shape} - -$A clay get description -{A generic thing of designated color and shape} - -Without a convention for discerning branches for leaves what should have been a value can be accidentally parsed as a dictionary, and merged with all of the other values that were never intended to be merge\&. Here is an example of it all going wrong: -::oo::class create ::foo { } -# Add description as a leaf -::foo clay set description {A generic thing of designated color and shape} -# Add description as a branch -::foo clay set description/ {A generic thing of designated color and shape} - -::oo::class create ::bar { - superclass foo -} -# Add description as a leaf -::bar clay set description {A drinking establishment of designated color and shape and size} -# Add description as a branch -::bar clay set description/ {A drinking establishment of designated color and shape and size} - -set B [::bar new] -# As a leaf we get the value verbatim from he nearest ancestor -$B clay get description - {A drinking establishment of designated color and shape and size} -# As a branch we get a recursive merge -$B clay get description/ -{A drinking establishment of designated color and size thing of} - -.CE -.SS "CLAY DIALECT" -Clay is built using the oo::dialect module from Tcllib\&. oo::dialect allows you to either add keywords directly to clay, or to create your own -metaclass and keyword set using Clay as a foundation\&. For details on the keywords and what they do, consult the functions in the ::clay::define namespace\&. -.SS "METHOD DELEGATION" -Method Delegation -It is sometimes useful to have an external object that can be invoked as if it were a method of the object\&. Clay provides a delegate ensemble method to perform that delegation, as well as introspect which methods are delegated in that manner\&. All delegated methods are marked with html-like tag markings (< >) around them\&. -.CS - - -::clay::define counter { - Variable counter 0 - method incr {{howmuch 1}} { - my variable counter - incr counter $howmuch - } - method value {} { - my variable counter - return $counter - } - method reset {} { - my variable counter - set counter 0 - } -} -::clay::define example { - variable buffer - constructor {} { - # Build a counter object - set obj [namespace current]::counter - ::counter create $obj - # Delegate the counter - my delegate $obj - } - method line {text} { - my incr - append buffer $text - } -} - -set A [example new] -$A line {Who’s line is it anyway?} -$A value -1 - -.CE -.SH COMMANDS -.TP -proc \fBclay::PROC\fR \fIname\fR \fIarglist\fR \fIbody\fR ?\fIninja\fR \fB\fR? -Because many features in this package may be added as -commands to future tcl cores, or be provided in binary -form by packages, I need a declaritive way of saying -\fICreate this command if there isn't one already\fR\&. -The \fIninja\fR argument is a script to execute if the -command is created by this mechanism\&. -.TP -proc \fBclay::_ancestors\fR \fIresultvar\fR \fIclass\fR -.TP -proc \fBclay::ancestors\fR ?\fIargs\fR? -.TP -proc \fBclay::args_to_dict\fR ?\fIargs\fR? -.TP -proc \fBclay::args_to_options\fR ?\fIargs\fR? -.TP -proc \fBclay::dynamic_arguments\fR \fIensemble\fR \fImethod\fR \fIarglist\fR ?\fIargs\fR? -.TP -proc \fBclay::dynamic_wrongargs_message\fR \fIarglist\fR -.TP -proc \fBclay::is_dict\fR \fId\fR -.TP -proc \fBclay::is_null\fR \fIvalue\fR -.TP -proc \fBclay::leaf\fR ?\fIargs\fR? -.TP -proc \fBclay::K\fR \fIa\fR \fIb\fR -.TP -proc \fBclay::noop\fR ?\fIargs\fR? -Perform a noop\&. Useful in prototyping for commenting out blocks -of code without actually having to comment them out\&. It also makes -a handy default for method delegation if a delegate has not been -assigned yet\&. -.TP -proc \fBclay::cleanup\fR -Process the queue of objects to be destroyed -.TP -proc \fBclay::object_create\fR \fIobjname\fR ?\fIclass\fR \fB\fR? -.TP -proc \fBclay::object_rename\fR \fIobject\fR \fInewname\fR -.TP -proc \fBclay::object_destroy\fR ?\fIargs\fR? -Mark an objects for destruction on the next cleanup -.TP -proc \fBclay::path\fR ?\fIargs\fR? -.TP -proc \fBclay::putb\fR ?\fImap\fR? \fItext\fR -Append a line of text to a variable\&. Optionally apply a string mapping\&. -.TP -proc \fBclay::script_path\fR -.TP -proc \fBclay::NSNormalize\fR \fIqualname\fR -.TP -proc \fBclay::uuid_generate\fR ?\fIargs\fR? -.TP -proc \fBclay::uuid::generate_tcl_machinfo\fR -.TP -proc \fBclay::uuid::tostring\fR \fIuuid\fR -.TP -proc \fBclay::uuid::fromstring\fR \fIuuid\fR -Convert a string representation of a uuid into its binary format\&. -.TP -proc \fBclay::uuid::equal\fR \fIleft\fR \fIright\fR -Compare two uuids for equality\&. -.TP -proc \fBclay::uuid\fR \fIcmd\fR ?\fIargs\fR? -uuid generate -> string rep of a new uuid -uuid equal uuid1 uuid2 -.TP -proc \fBclay::tree::sanitize\fR \fIdict\fR -Output a dictionary removing any \&. entries added by \fBclay::tree::merge\fR -.TP -proc \fBclay::tree::_sanitizeb\fR \fIpath\fR \fIvarname\fR \fIdict\fR -Helper function for ::clay::tree::sanitize -Formats the string representation for a dictionary element within -a human readable stream of lines, and determines if it needs to call itself -with further indentation to express a sub-branch -.TP -proc \fBclay::tree::storage\fR \fIrawpath\fR -Return the path as a storage path for clay::tree -with all branch terminators removed\&. -This command will also break arguments up if they -contain /\&. -.sp -Example: -.CS - - > clay::tree::storage {foo bar baz bang} - foo bar baz bang - > clay::tree::storage {foo bar baz bang/} - foo bar baz bang - > clay::tree::storage {foo bar baz bang:} - foo bar baz bang: - > clay::tree::storage {foo/bar/baz bang:} - foo bar baz bang: - > clay::tree::storage {foo/bar/baz/bang} - foo bar baz bang - - - -.CE -.TP -proc \fBclay::tree::dictset\fR \fIvarname\fR ?\fIargs\fR? -Set an element with a recursive dictionary, -marking all branches on the way down to the -final element\&. -If the value does not exists in the nested dictionary -it is added as a leaf\&. If the value already exists as a branch -the value given is merged if the value is a valid dict\&. If the -incoming value is not a valid dict, the value overrides the value -stored, and the value is treated as a leaf from then on\&. -.sp -Example: -.CS - - > set r {} - > ::clay::tree::dictset r option color default Green - \&. {} option {\&. {} color {\&. {} default Green}} - > ::clay::tree::dictset r option {Something not dictlike} - \&. {} option {Something not dictlike} - # Note that if the value is not a dict, and you try to force it to be - # an error with be thrown on the merge - > ::clay::tree::dictset r option color default Blue - missing value to go with key - - - -.CE -.TP -proc \fBclay::tree::dictmerge\fR \fIvarname\fR ?\fIargs\fR? -A recursive form of dict merge, intended for modifying variables in place\&. -.sp -Example: -.CS - - > set mydict {sub/ {sub/ {description {a block of text}}}} - > ::clay::tree::dictmerge mydict {sub/ {sub/ {field {another block of text}}}}] - > clay::tree::print $mydict - sub/ { - sub/ { - description {a block of text} - field {another block of text} - } - } - - - -.CE -.TP -proc \fBclay::tree::merge\fR ?\fIargs\fR? -A recursive form of dict merge -.sp -A routine to recursively dig through dicts and merge -adapted from http://stevehavelka\&.com/tcl-dict-operation-nested-merge/ -.sp -Example: -.CS - - > set mydict {sub/ {sub/ {description {a block of text}}}} - > set odict [clay::tree::merge $mydict {sub/ {sub/ {field {another block of text}}}}] - > clay::tree::print $odict - sub/ { - sub/ { - description {a block of text} - field {another block of text} - } - } - - - -.CE -.TP -proc \fBdictargs::proc\fR \fIname\fR \fIargspec\fR \fIbody\fR -Named Procedures as new command -.TP -proc \fBdictargs::method\fR \fIname\fR \fIargspec\fR \fIbody\fR -.TP -proc \fBclay::dialect::Push\fR \fIclass\fR -.TP -proc \fBclay::dialect::Peek\fR -.TP -proc \fBclay::dialect::Pop\fR -.TP -proc \fBclay::dialect::create\fR \fIname\fR ?\fIparent\fR \fB\fR? -This proc will generate a namespace, a "mother of all classes", and a -rudimentary set of policies for this dialect\&. -.TP -proc \fBclay::dialect::NSNormalize\fR \fInamespace\fR \fIqualname\fR -Support commands; not intended to be called directly\&. -.TP -proc \fBclay::dialect::DefineThunk\fR \fItarget\fR ?\fIargs\fR? -.TP -proc \fBclay::dialect::Canonical\fR \fInamespace\fR \fINSpace\fR \fIclass\fR -.TP -proc \fBclay::dialect::Define\fR \fInamespace\fR \fIclass\fR ?\fIargs\fR? -Implementation of the languages' define command -.TP -proc \fBclay::dialect::Aliases\fR \fInamespace\fR ?\fIargs\fR? -.TP -proc \fBclay::dialect::SuperClass\fR \fInamespace\fR ?\fIargs\fR? -.TP -proc \fBclay::dynamic_methods\fR \fIclass\fR -.TP -proc \fBclay::dynamic_methods_class\fR \fIthisclass\fR -.TP -proc \fBclay::define::Array\fR \fIname\fR ?\fIvalues\fR \fB\fR? -New OO Keywords for clay -.TP -proc \fBclay::define::Delegate\fR \fIname\fR \fIinfo\fR -An annotation that objects of this class interact with delegated -methods\&. The annotation is intended to be a dictionary, and the -only reserved key is \fIdescription\fR, a human readable description\&. -.TP -proc \fBclay::define::constructor\fR \fIarglist\fR \fIrawbody\fR -.TP -proc \fBclay::define::Class_Method\fR \fIname\fR \fIarglist\fR \fIbody\fR -Specify the a method for the class object itself, instead of for objects of the class -.TP -proc \fBclay::define::class_method\fR \fIname\fR \fIarglist\fR \fIbody\fR -And alias to the new Class_Method keyword -.TP -proc \fBclay::define::clay\fR ?\fIargs\fR? -.TP -proc \fBclay::define::destructor\fR \fIrawbody\fR -.TP -proc \fBclay::define::Dict\fR \fIname\fR ?\fIvalues\fR \fB\fR? -.TP -proc \fBclay::define::Option\fR \fIname\fR ?\fIargs\fR? -Define an option for the class -.TP -proc \fBclay::define::Method\fR \fIname\fR \fIargstyle\fR \fIargspec\fR \fIbody\fR -.TP -proc \fBclay::define::Option_Class\fR \fIname\fR ?\fIargs\fR? -Define a class of options -All field / value pairs will be be inherited by an option that -specify \fIname\fR as it class field\&. -.TP -proc \fBclay::define::Variable\fR \fIname\fR ?\fIdefault\fR \fB\fR? -This keyword can also be expressed: -.CS - -property variable NAME {default DEFAULT} -.CE -.sp -Variables registered in the variable property are also initialized -(if missing) when the object changes class via the \fImorph\fR method\&. -.TP -proc \fBclay::ensemble_methodbody\fR \fIensemble\fR \fIeinfo\fR -Produce the body of an ensemble's public dispatch method -ensemble is the name of the the ensemble\&. -einfo is a dictionary of methods for the ensemble, and each value is a script -to execute on dispatch -.sp -Example: -.CS - - ::clay::ensemble_methodbody foo { - bar {tailcall my Foo_bar {*}$args} - baz {tailcall my Foo_baz {*}$args} - clock {return [clock seconds]} - default {puts "You gave me $method"} - } - - - -.CE -.TP -proc \fBclay::define::Ensemble\fR \fIrawmethod\fR ?\fIargs\fR? -.TP -proc \fBclay::event::cancel\fR \fIself\fR ?\fItask\fR \fB*\fR? -Cancel a scheduled event -.TP -proc \fBclay::event::generate\fR \fIself\fR \fIevent\fR ?\fIargs\fR? -Generate an event -Adds a subscription mechanism for objects -to see who has recieved this event and prevent -spamming or infinite recursion -.TP -proc \fBclay::event::nextid\fR -.TP -proc \fBclay::event::Notification_list\fR \fIself\fR \fIevent\fR ?\fIstackvar\fR \fB\fR? -Called recursively to produce a list of -who recieves notifications -.TP -proc \fBclay::event::notify\fR \fIrcpt\fR \fIsender\fR \fIevent\fR \fIeventinfo\fR -Final delivery to intended recipient object -.TP -proc \fBclay::event::process\fR \fIself\fR \fIhandle\fR \fIscript\fR -Evaluate an event script in the global namespace -.TP -proc \fBclay::event::schedule\fR \fIself\fR \fIhandle\fR \fIinterval\fR \fIscript\fR -Schedule an event to occur later -.TP -proc \fBclay::event::subscribe\fR \fIself\fR \fIwho\fR \fIevent\fR -Subscribe an object to an event pattern -.TP -proc \fBclay::event::unsubscribe\fR \fIself\fR ?\fIargs\fR? -Unsubscribe an object from an event pattern -.TP -proc \fBclay::singleton\fR \fIname\fR \fIscript\fR -An object which is intended to be it's own class\&. -.PP -.SH CLASSES -.SS "CLASS CLAY::CLASS" -.PP -\fBMethods\fR -.TP -method \fBclay ancestors\fR -Return this class and all ancestors in search order\&. -.TP -method \fBclay dump\fR -Return a complete dump of this object's clay data, but only this object's clay data\&. -.TP -method \fBclay find\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Pull a chunk of data from the clay system\&. If the last element of \fIpath\fR is a branch, -returns a recursive merge of all data from this object and it's constituent classes of the data in that branch\&. -If the last element is a leaf, search this object for a matching leaf, or search all constituent classes for a matching -leaf and return the first value found\&. -If no value is found, returns an empty string\&. -If a branch is returned the topmost \&. entry is omitted\&. -.TP -method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Pull a chunk of data from the class's clay system\&. -If no value is found, returns an empty string\&. -If a branch is returned the topmost \&. entry is omitted\&. -.TP -method \fBclay GET\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Pull a chunk of data from the class's clay system\&. -If no value is found, returns an empty string\&. -.TP -method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR? -Recursively merge the dictionaries given into the object's local clay storage\&. -.TP -method \fBclay replace\fR \fIdictionary\fR -Replace the contents of the internal clay storage with the dictionary given\&. -.TP -method \fBclay search\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Return the first matching value for the path in either this class's clay data or one of its ancestors -.TP -method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR -Merge the conents of \fBvalue\fR with the object's clay storage at \fBpath\fR\&. -.PP -.PP -.SS "CLASS CLAY::OBJECT" -clay::object -This class is inherited by all classes that have options\&. -.PP -\fBMethods\fR -.TP -method \fBclay ancestors\fR -Return the class this object belongs to, all classes mixed into this object, and all ancestors of those classes in search order\&. -.TP -method \fBclay cache\fR \fIpath\fR \fIvalue\fR -Store VALUE in such a way that request in SEARCH for PATH will always return it until the cache is flushed -.TP -method \fBclay cget\fR \fIfield\fR -Pull a value from either the object's clay structure or one of its constituent classes that matches the field name\&. -The order of search us: -.sp -1\&. The as a value in local dict variable config -.sp -2\&. The as a value in local dict variable clay -.sp -3\&. As a leaf in any ancestor as a root of the clay tree -.sp -4\&. As a leaf in any ancestor as \fBconst\fR \fIfield\fR -.sp -5\&. As a leaf in any ancestor as \fBoption\fR \fIfield\fR \fBdefault\fR -.TP -method \fBclay delegate\fR ?\fIstub\fR? ?\fIobject\fR? -Introspect or control method delegation\&. With no arguments, the method will return a -key/value list of stubs and objects\&. With just the \fIstub\fR argument, the method will -return the object (if any) attached to the stub\&. With a \fIstub\fR and an \fIobject\fR -this command will forward all calls to the method \fIstub\fR to the \fIobject\fR\&. -.TP -method \fBclay dump\fR -Return a complete dump of this object's clay data, as well as the data from all constituent classes recursively blended in\&. -.TP -method \fBclay ensemble_map\fR -Return a dictionary describing the method ensembles to be assembled for this object -.TP -method \fBclay eval\fR \fIscript\fR -Evaluated a script in the namespace of this object -.TP -method \fBclay evolve\fR -Trigger the \fBInitializePublic\fR private method -.TP -method \fBclay exists\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Returns 1 if \fIpath\fR exists in either the object's clay data\&. Values greater than one indicate the element exists in one of the object's constituent classes\&. A value of zero indicates the path could not be found\&. -.TP -method \fBclay flush\fR -Wipe any caches built by the clay implementation -.TP -method \fBclay forward\fR \fImethod\fR \fIobject\fR -A convenience wrapper for -.CS - -oo::objdefine [self] forward {*}$args -.CE -.TP -method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Pull a chunk of data from the clay system\&. If the last element of \fIpath\fR is a branch (ends in a slash /), -returns a recursive merge of all data from this object and it's constituent classes of the data in that branch\&. -If the last element is a leaf, search this object for a matching leaf, or search all constituent classes for a matching -leaf and return the first value found\&. -If no value is found, returns an empty string\&. -.TP -method \fBclay leaf\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -A modified get which is tailored to pull only leaf elements -.TP -method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR? -Recursively merge the dictionaries given into the object's local clay storage\&. -.TP -method \fBclay mixin\fR \fIclass\fR ?\fBclass\&.\&.\&.\fR? -Perform [oo::objdefine [self] mixin] on this object, with a few additional rules: -Prior to the call, for any class was previously mixed in, but not in the new result, execute the script registered to mixin/ unmap-script (if given\&.) -For all new classes, that were not present prior to this call, after the native TclOO mixin is invoked, execute the script registered to mixin/ map-script (if given\&.) -Fall all classes that are now present and “mixed inâ€, execute the script registered to mixin/ react-script (if given\&.) -.TP -method \fBclay mixinmap\fR ?\fIstub\fR? ?\fIclasses\fR? -With no arguments returns the map of stubs and classes mixed into the current object\&. When only stub is given, -returns the classes mixed in on that stub\&. When stub and classlist given, replace the classes currently on that stub with the given -classes and invoke clay mixin on the new matrix of mixed in classes\&. -.TP -method \fBclay provenance\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? -Return either \fBself\fR if that path exists in the current object, or return the first class (if any) along the clay search path which contains that element\&. -.TP -method \fBclay replace\fR \fIdictionary\fR -Replace the contents of the internal clay storage with the dictionary given\&. -.TP -method \fBclay search\fR \fIpath\fR \fIvaluevar\fR \fIisleafvar\fR -Return true, and set valuevar to the value and isleafar to true for false if PATH was found in the cache\&. -.TP -method \fBclay source\fR \fIfilename\fR -Source the given filename within the object's namespace -.TP -method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR -Merge the conents of \fBvalue\fR with the object's clay storage at \fBpath\fR\&. -.TP -method \fBInitializePublic\fR -Instantiate variables\&. Called on object creation and during clay mixin\&. -.PP -.PP -.SH AUTHORS -Sean Woods \fImailto:\fR -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIoo\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -TclOO, oo -.SH CATEGORY -Programming tools -.SH COPYRIGHT -.nf -Copyright (c) 2018 Sean Woods - -.fi Index: idoc/man/files/modules/clock/iso8601.n ================================================================== --- idoc/man/files/modules/clock/iso8601.n +++ idoc/man/files/modules/clock/iso8601.n @@ -307,81 +307,14 @@ \fB-gmt\fR, \fB-locale\fR, and \fB-timezone\fR of the builtin command \fBclock scan\fR\&. .PP -.SH "DATE FORMATS" -The commands accept the following 23 date formats: -.CS - - -(year)-(month)-(day) -(year)(month)(day) -(year)-(day in year) -(year)(day in year) -(year in century)-(month)-(day) -(year)-(month) Day defaults to the 1st of the month -(year in century)(month)(day) -(year in century)-(day in year) -(year in century)(day in year) ---(month)-(day) Year defaults to the current year ---(month)(day) Year defaults to the current year ---(day in year) Year defaults to the current year ----(day) Year defaults to the current year, month to current month -(fiscal year)-W(week)-(wday) -(fiscal year)W(week)-(wday) -(fiscal year in century)-W(week)-(wday) -(fiscal year in century)W(week)(wday) -(fiscal year)-W(week) Weekday defaults to monday -(fiscal year)W(week) Weekday defaults to monday --W(week)-(wday) Year defaults to current fiscal year --W(week)(wday) Year defaults to current fiscal year -(wday) Year defaults to current fiscal year, week to current week -(year) Month defaults to january, day to 1st of the month - -.CE -The possible parts/fields in the above, and their meanings, are: -.TP -year -Year with century, 4 digits -.TP -month -Month in year, 2 digits -.TP -day -Day in month, 2 digits\&. -.TP -year in century -Year without century, 2 digits -.TP -day in year -Day in year, 3 digits -.TP -fiscal year -ISO 8601 fiscal year with century, 4 digits -.TP -fiscal year in century -ISO 8601 fiscal year without century, 2 digits -.TP -week -ISO 8601 week number -.TP -wday -Week day, 1 digit, Monday (1) to Sunday (7,0) -.PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIclock::iso8601\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH CATEGORY Text processing Index: idoc/man/files/modules/clock/rfc2822.n ================================================================== --- idoc/man/files/modules/clock/rfc2822.n +++ idoc/man/files/modules/clock/rfc2822.n @@ -269,11 +269,11 @@ .de MT .QW "" .. .BS .SH NAME -clock_rfc2822 \- Parsing RFC 2822 dates/times +clock_rfc2822 \- Parsing ISO 8601 dates/times .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp package require \fBclock::rfc2822 ?0\&.1?\fR .sp @@ -295,15 +295,7 @@ bugs and other problems\&. Please report such in the category \fIclock::rfc2822\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH CATEGORY Text processing Index: idoc/man/files/modules/cmdline/cmdline.n ================================================================== --- idoc/man/files/modules/cmdline/cmdline.n +++ idoc/man/files/modules/cmdline/cmdline.n @@ -341,14 +341,10 @@ specified\&. This also generates an error message that lists the allowed flags if an incorrect flag is specified\&. The optional \fIusage\fR-argument contains a string to include in front of the generated message\&. If not present it defaults to "options:"\&. .sp -\fIargvVar\fR contains the name of the list of arguments to process\&. -If options are found the list is modified and the processed arguments -are removed from the start of the list\&. -.sp \fIoptlist\fR contains a list of lists where each element specifies an option in the form: \fIflag\fR \fIdefault\fR \fIcomment\fR\&. .sp If \fIflag\fR ends in "\&.arg" then the value is taken from the command line\&. Otherwise it is a boolean and appears in the result if present @@ -422,13 +418,10 @@ } set usage ": MyCommandName \\[options] filename \&.\&.\&.\\noptions:" try { array set params [::cmdline::getoptions argv $options $usage] - - # Note: argv is modified now\&. The recognized options are - # removed from it, leaving the non-option arguments behind\&. } trap {CMDLINE USAGE} {msg o} { # Trap the usage signal, print the message, and exit the application\&. # Note: Other errors are not caught and passed through to higher levels! puts $msg exit 1 @@ -455,17 +448,9 @@ bugs and other problems\&. Please report such in the category \fIcmdline\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS argument processing, argv, argv0, cmdline processing, command line processing .SH CATEGORY Programming tools Index: idoc/man/files/modules/comm/comm.n ================================================================== --- idoc/man/files/modules/comm/comm.n +++ idoc/man/files/modules/comm/comm.n @@ -1245,13 +1245,12 @@ 2\&.0 \fBcomm\fR has been rewritten from scratch (but is fully compatible with Comm 1\&.0, without the requirement to use obTcl)\&. .PP .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -1344,12 +1343,10 @@ compiled Tcl extension\&. See \fIhttp://www\&.cs\&.cornell\&.edu/Info/Projects/zeno/Projects/Tcl-DP\&.html\fR\&. .PP Michael Doyle has code that implements the Tcl-DP RPC interface using standard Tcl sockets, much like \fBcomm\fR\&. -The DpTcl package is available at -\fIhttp://chiselapp\&.com/user/gwlester/repository/DpTcl\fR\&. .PP Andreas Kupries uses \fBcomm\fR and has built a simple nameserver as part of his Pool library\&. See \fIhttp://www\&.purl\&.org/net/akupries/soft/pool/index\&.htm\fR\&. .SH "BUGS, IDEAS, FEEDBACK" @@ -1357,18 +1354,10 @@ bugs and other problems\&. Please report such in the category \fIcomm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" send(n) .SH KEYWORDS comm, communication, ipc, message, remote communication, remote execution, rpc, secure, send, socket, ssl, tls .SH CATEGORY Index: idoc/man/files/modules/comm/comm_wire.n ================================================================== --- idoc/man/files/modules/comm/comm_wire.n +++ idoc/man/files/modules/comm/comm_wire.n @@ -425,18 +425,10 @@ bugs and other problems\&. Please report such in the category \fIcomm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" comm .SH KEYWORDS comm, communication, ipc, message, remote communication, remote execution, rpc, socket .SH CATEGORY Index: idoc/man/files/modules/control/control.n ================================================================== --- idoc/man/files/modules/control/control.n +++ idoc/man/files/modules/control/control.n @@ -407,19 +407,11 @@ bugs and other problems\&. Please report such in the category \fIcontrol\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" break, continue, expr, if, join, namespace, return, string, while .SH KEYWORDS assert, control, do, flow, no-op, structure .SH CATEGORY Programming tools Index: idoc/man/files/modules/coroutine/coro_auto.n ================================================================== --- idoc/man/files/modules/coroutine/coro_auto.n +++ idoc/man/files/modules/coroutine/coro_auto.n @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIcoroutine\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait .SH CATEGORY Coroutine .SH COPYRIGHT .nf Copyright (c) 2010-2014 Andreas Kupries .fi Index: idoc/man/files/modules/coroutine/tcllib_coroutine.n ================================================================== --- idoc/man/files/modules/coroutine/tcllib_coroutine.n +++ idoc/man/files/modules/coroutine/tcllib_coroutine.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'tcllib_coroutine\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2010-2015 Andreas Kupries '\" -.TH "coroutine" n 1\&.2 tcllib "Coroutine utilities" +.TH "coroutine" n 1\&.1\&.3 tcllib "Coroutine utilities" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME coroutine \- Coroutine based event and IO handling .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp -package require \fBcoroutine 1\&.2\fR +package require \fBcoroutine 1\&.1\&.3\fR .sp \fBcoroutine::util after\fR \fIdelay\fR .sp \fBcoroutine::util await\fR \fIvarname\fR\&.\&.\&. .sp @@ -286,12 +286,10 @@ .sp \fBcoroutine::util exit\fR ?\fIstatus\fR? .sp \fBcoroutine::util gets\fR \fIchan\fR ?\fIvarname\fR? .sp -\fBcoroutine::util gets_safety\fR \fIchan\fR \fIlimit\fR \fIvarname\fR -.sp \fBcoroutine::util global\fR \fIvarname\fR\&.\&.\&. .sp \fBcoroutine::util read\fR \fB-nonewline\fR \fIchan\fR ?\fIn\fR? .sp \fBcoroutine::util update\fR ?\fBidletasks\fR? @@ -343,16 +341,10 @@ \fBcoroutine::util gets\fR \fIchan\fR ?\fIvarname\fR? This command reads a line from the channel \fIchan\fR and returns it either as its result, or, if a \fIvarname\fR was specified, writes it to the named variable and returns the number of characters read\&. .TP -\fBcoroutine::util gets_safety\fR \fIchan\fR \fIlimit\fR \fIvarname\fR -This command reads a line from the channel \fIchan\fR up to size \fIlimit\fR -and stores the result in \fIvarname\fR\&. Of \fIlimit\fR is reached before the -set first newline, an error is thrown\&. The command returns the number of -characters read\&. -.TP \fBcoroutine::util global\fR \fIvarname\fR\&.\&.\&. This command imports the named global variables of the coroutine into the current scope\&. From the technical point of view these variables reside in level \fB#1\fR of the Tcl stack\&. I\&.e\&. these are not the regular global variable in to the global namespace, and each coroutine @@ -376,22 +368,14 @@ bugs and other problems\&. Please report such in the category \fIcoroutine\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS after, channel, coroutine, events, exit, gets, global, green threads, read, threads, update, vwait .SH CATEGORY Coroutine .SH COPYRIGHT .nf Copyright (c) 2010-2015 Andreas Kupries .fi Index: idoc/man/files/modules/counter/counter.n ================================================================== --- idoc/man/files/modules/counter/counter.n +++ idoc/man/files/modules/counter/counter.n @@ -483,17 +483,9 @@ bugs and other problems\&. Please report such in the category \fIcounter\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS counting, histogram, statistics, tallying .SH CATEGORY Data structures Index: idoc/man/files/modules/crc/cksum.n ================================================================== --- idoc/man/files/modules/crc/cksum.n +++ idoc/man/files/modules/crc/cksum.n @@ -383,18 +383,10 @@ bugs and other problems\&. Please report such in the category \fIcrc\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" crc32(n), sum(n) .SH KEYWORDS checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security .SH CATEGORY Index: idoc/man/files/modules/crc/crc16.n ================================================================== --- idoc/man/files/modules/crc/crc16.n +++ idoc/man/files/modules/crc/crc16.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'crc16\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2002, 2017, Pat Thoyts +'\" Copyright (c) 2002, Pat Thoyts '\" -.TH "crc16" n 1\&.1\&.4 tcllib "Cyclic Redundancy Checks" +.TH "crc16" n 1\&.1\&.2 tcllib "Cyclic Redundancy Checks" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,21 +274,21 @@ .SH NAME crc16 \- Perform a 16bit Cyclic Redundancy Check .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBcrc16 ?1\&.1\&.4?\fR +package require \fBcrc16 ?1\&.1\&.2?\fR .sp -\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .sp \fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR .sp -\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .sp \fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR .sp -\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .sp \fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR .sp .BE .SH DESCRIPTION @@ -299,19 +299,19 @@ There are a number of permutations available for calculating CRC checksums and this package can handle all of them\&. Defaults are set up for the most common cases\&. .SH COMMANDS .TP -\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .TP \fB::crc::crc16\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR .TP -\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .TP \fB::crc::crc-ccitt\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR .TP -\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fB--\fR \fImessage\fR +\fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? \fImessage\fR .TP \fB::crc::xmodem\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? ?-implementation \fIprocname\fR? -filename \fIfile\fR The command takes either string data or a file name and returns a checksum value calculated using the CRC algorithm\&. The command used sets up the CRC polynomial, initial value and bit ordering for the desired @@ -357,39 +357,34 @@ for the XMODEM, CCITT and the usual CRC-16 checksum\&. For convenience, additional commands have been provided that make use of these implementations\&. .TP -- -Terminate option processing\&. Please note that using the option -termination flag is important when processing data from parameters\&. If -the binary data looks like one of the options given above then the -data will be read as an option if this marker is not included\&. -Always use the \fI--\fR option termination flag before giving the data -argument\&. +Terminate option processing\&. .PP .SH EXAMPLES .PP .CS -% crc::crc16 -- "Hello, World!" +% crc::crc16 "Hello, World!" 64077 .CE .PP .CS -% crc::crc-ccitt -- "Hello, World!" +% crc::crc-ccitt "Hello, World!" 26586 .CE .PP .CS -% crc::crc16 -format 0x%X -- "Hello, World!" +% crc::crc16 -format 0x%X "Hello, World!" 0xFA4D .CE .PP .CS @@ -406,24 +401,16 @@ bugs and other problems\&. Please report such in the category \fIcrc\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" cksum(n), crc32(n), sum(n) .SH KEYWORDS checksum, cksum, crc, crc16, crc32, cyclic redundancy check, data integrity, security .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf -Copyright (c) 2002, 2017, Pat Thoyts +Copyright (c) 2002, Pat Thoyts .fi Index: idoc/man/files/modules/crc/crc32.n ================================================================== --- idoc/man/files/modules/crc/crc32.n +++ idoc/man/files/modules/crc/crc32.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'crc32\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2002, Pat Thoyts '\" -.TH "crc32" n 1\&.3\&.3 tcllib "Cyclic Redundancy Checks" +.TH "crc32" n 1\&.3\&.2 tcllib "Cyclic Redundancy Checks" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME crc32 \- Perform a 32bit Cyclic Redundancy Check .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBcrc32 ?1\&.3\&.3?\fR +package require \fBcrc32 ?1\&.3\&.2?\fR .sp \fB::crc::crc32\fR ?-format \fIformat\fR? ?-seed \fIvalue\fR? [ \fI-channel chan\fR | \fI-filename file\fR | \fImessage\fR ] .sp \fB::crc::Crc32Init\fR ?\fIseed\fR? .sp @@ -399,18 +399,10 @@ bugs and other problems\&. Please report such in the category \fIcrc\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" cksum(n), crc16(n), sum(n) .SH KEYWORDS checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security .SH CATEGORY Index: idoc/man/files/modules/crc/sum.n ================================================================== --- idoc/man/files/modules/crc/sum.n +++ idoc/man/files/modules/crc/sum.n @@ -354,18 +354,10 @@ bugs and other problems\&. Please report such in the category \fIcrc\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" cksum(n), crc32(n), sum(1) .SH KEYWORDS checksum, cksum, crc, crc32, cyclic redundancy check, data integrity, security, sum .SH CATEGORY Index: idoc/man/files/modules/cron/cron.n ================================================================== --- idoc/man/files/modules/cron/cron.n +++ idoc/man/files/modules/cron/cron.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'cron\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2016-2018 Sean Woods +'\" Copyright (c) 2016 Sean Woods '\" -.TH "cron" n 2\&.1 tcllib "cron" +.TH "cron" n 2\&.0 tcllib "cron" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME cron \- Tool for automating the period callback of commands .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp -package require \fBcron ?2\&.1?\fR +package require \fBcron ?2\&.0?\fR .sp \fB::cron::at\fR \fI?processname?\fR \fItimecode\fR \fIcommand\fR .sp \fB::cron::cancel\fR \fIprocessname\fR .sp @@ -298,13 +298,13 @@ .sp \fB::cron::task set\fR \fIprocess\fR \fIfield\fR \fIvalue\fR \fI?field\&.\&.\&.?\fR \fI?value\&.\&.\&.?\fR .sp \fB::cron::wake\fR \fI?who?\fR .sp -\fB::cron::clock_step\fR \fImilliseconds\fR +\fB::cron::clock_step\fR \fImilleseconds\fR .sp -\fB::cron::clock_delay\fR \fImilliseconds\fR +\fB::cron::clock_delay\fR \fImilleseconds\fR .sp \fB::cron::clock_sleep\fR \fIseconds\fR \fI?offset?\fR .sp \fB::cron::clock_set\fR \fInewtime\fR .sp @@ -421,30 +421,24 @@ .TP \fB::cron::task set\fR \fIprocess\fR \fIfield\fR \fIvalue\fR \fI?field\&.\&.\&.?\fR \fI?value\&.\&.\&.?\fR .sp If \fIprocess\fR does not exist, it is created\&. Options Include: .RS -.TP \fBcommand\fR If \fBcoroutine\fR is black, a global command which implements this process\&. If \fBcoroutine\fR is not black, the command to invoke to create or recreate the coroutine\&. -.TP \fBcoroutine\fR The name of the coroutine (if any) which implements this process\&. -.TP \fBfrequency\fR If -1, this process is terminated after the next event\&. If 0 this process should be called during every -idle event\&. If positive, this process should generate events periodically\&. The frequency is an integer number -of milliseconds between events\&. -.TP +idle event\&. If positive, this process should generate events periodically\&. The frequency is an interger number +of milleseconds between events\&. \fBobject\fR The object associated with this process or coroutine\&. -.TP \fBscheduled\fR -If non-zero, the absolute time from the epoch (in milliseconds) that this process will trigger an event\&. +If non-zero, the absolute time from the epoch (in milleseconds) that this process will trigger an event\&. If zero, and the \fBfrequency\fR is also zero, this process is called every idle loop\&. -.TP \fBrunning\fR A boolean flag\&. If true it indicates the process never returned or yielded during the event loop, and will not be called again until it does so\&. .RE .TP @@ -459,19 +453,19 @@ .PP .PP Several utility commands are provided that are used internally within cron and for testing cron, but may or may not be useful in the general cases\&. .TP -\fB::cron::clock_step\fR \fImilliseconds\fR +\fB::cron::clock_step\fR \fImilleseconds\fR .sp Return a clock time absolute to the epoch which falls on the next -border between one second and the next for the value of \fImilliseconds\fR +border between one second and the next for the value of \fImilleseconds\fR .TP -\fB::cron::clock_delay\fR \fImilliseconds\fR +\fB::cron::clock_delay\fR \fImilleseconds\fR .sp Return a clock time absolute to the epoch which falls on the next -border between one second and the next \fImilliseconds\fR in the future\&. +border between one second and the next \fImilleseconds\fR in the future\&. .TP \fB::cron::clock_sleep\fR \fIseconds\fR \fI?offset?\fR .sp Return a clock time absolute to the epoch which falls exactly \fIseconds\fR in the future\&. If offset is given it may be positive or negative, and will shift @@ -480,32 +474,24 @@ \fB::cron::clock_set\fR \fInewtime\fR .sp Sets the internal clock for cron\&. This command will advance the time in 100ms increment, triggering events, until the internal time catches up with \fInewtime\fR\&. .sp -\fInewtime\fR is expressed in absolute milliseconds since the beginning of the epoch\&. +\fInewtime\fR is expressed in absolute milleseconds since the beginning of the epoch\&. .PP .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIodie\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS cron, odie .SH CATEGORY System .SH COPYRIGHT .nf -Copyright (c) 2016-2018 Sean Woods +Copyright (c) 2016 Sean Woods .fi Index: idoc/man/files/modules/csv/csv.n ================================================================== --- idoc/man/files/modules/csv/csv.n +++ idoc/man/files/modules/csv/csv.n @@ -491,18 +491,10 @@ bugs and other problems\&. Please report such in the category \fIcsv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" matrix, queue .SH KEYWORDS csv, matrix, package, queue, tcllib .SH CATEGORY Index: idoc/man/files/modules/debug/debug.n ================================================================== --- idoc/man/files/modules/debug/debug.n +++ idoc/man/files/modules/debug/debug.n @@ -505,18 +505,10 @@ bugs and other problems\&. Please report such in the category \fIdebug\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS debug, log, narrative, trace .SH CATEGORY debugging, tracing, and logging .SH COPYRIGHT Index: idoc/man/files/modules/debug/debug_caller.n ================================================================== --- idoc/man/files/modules/debug/debug_caller.n +++ idoc/man/files/modules/debug/debug_caller.n @@ -307,22 +307,14 @@ bugs and other problems\&. Please report such in the category \fIdebug\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS debug, log, narrative, trace .SH CATEGORY debugging, tracing, and logging .SH COPYRIGHT .nf Copyright (c) 2012-2015, Andreas Kupries .fi Index: idoc/man/files/modules/debug/debug_heartbeat.n ================================================================== --- idoc/man/files/modules/debug/debug_heartbeat.n +++ idoc/man/files/modules/debug/debug_heartbeat.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'debug_heartbeat\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 200?, Colin McCormack, Wub Server Utilities '\" Copyright (c) 2012, Andreas Kupries '\" -.TH "debug::heartbeat" n 1\&.0\&.1 tcllib "debug narrative" +.TH "debug::heartbeat" n 1 tcllib "debug narrative" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -275,11 +275,11 @@ .SH NAME debug::heartbeat \- debug narrative - heartbeat .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBdebug::heartbeat ?1\&.0\&.1?\fR +package require \fBdebug::heartbeat ?1?\fR .sp package require \fBdebug ?1?\fR .sp \fBdebug\fR \fBheartbeat\fR ?\fIdelta\fR? .sp @@ -307,18 +307,10 @@ bugs and other problems\&. Please report such in the category \fIdebug\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS debug, heartbeat, log, narrative, trace .SH CATEGORY debugging, tracing, and logging .SH COPYRIGHT Index: idoc/man/files/modules/debug/debug_timestamp.n ================================================================== --- idoc/man/files/modules/debug/debug_timestamp.n +++ idoc/man/files/modules/debug/debug_timestamp.n @@ -299,18 +299,10 @@ bugs and other problems\&. Please report such in the category \fIdebug\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS debug, log, narrative, timestamps, trace .SH CATEGORY debugging, tracing, and logging .SH COPYRIGHT DELETED idoc/man/files/modules/defer/defer.n Index: idoc/man/files/modules/defer/defer.n ================================================================== --- idoc/man/files/modules/defer/defer.n +++ idoc/man/files/modules/defer/defer.n @@ -1,373 +0,0 @@ -'\" -'\" Generated from file 'defer\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2017, Roy Keene -'\" -.TH "defer" n 1 tcllib "Defered execution ala Go" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -defer \- Defered execution -.SH SYNOPSIS -package require \fBTcl 8\&.6\fR -.sp -package require \fBdefer ?1?\fR -.sp -\fB::defer::defer\fR ?\fIcommand\fR? ?\fIarg1\fR? ?\fIarg2\fR? ?\fIargN\&.\&.\&.\fR? -.sp -\fB::defer::with\fR \fIvariableList\fR \fIscript\fR -.sp -\fB::defer::autowith\fR \fIscript\fR -.sp -\fB::defer::cancel\fR ?\fIid\&.\&.\&.\fR? -.sp -.BE -.SH DESCRIPTION -The \fBdefer\fR commands allow a developer to schedule actions to happen -as part of the current variable scope terminating\&. This is most useful -for dealing with cleanup activities\&. Since the defered actions always -execute, and always execute in the reverse order from which the defer -statements themselves execute, the programmer can schedule the cleanup -of a resource (for example, a channel) as soon as that resource is -acquired\&. Then, later if the procedure or lambda ends, either due to -an error, or an explicit return, the cleanup of that resource will -always occur\&. -.PP -.SH COMMANDS -.TP -\fB::defer::defer\fR ?\fIcommand\fR? ?\fIarg1\fR? ?\fIarg2\fR? ?\fIargN\&.\&.\&.\fR? -Defers execution of some code until the current variable scope -ends\&. Each argument is concatencated together to form the script -to execute at deferal time\&. -Multiple defer statements may be used, they are executed in the order -of last-in, first-out\&. -The return value is an identifier which can be used later with -\fBdefer::cancel\fR -.TP -\fB::defer::with\fR \fIvariableList\fR \fIscript\fR -Defers execution of a script while copying the current value of some -variables, whose names specified in \fIvariableList\fR, into the script\&. -The script acts like a lambda but executes at the same level as the -\fBdefer::with\fR -call\&. -The return value is the same as -\fB::defer::defer\fR -.TP -\fB::defer::autowith\fR \fIscript\fR -The same as -\fB::defer::with\fR but uses all local variables in the variable list\&. -.TP -\fB::defer::cancel\fR ?\fIid\&.\&.\&.\fR? -Cancels the execution of a defered action\&. The \fIid\fR argument is the -identifier returned by -\fB::defer::defer\fR, -\fB::defer::with\fR, or -\fB::defer::autowith\fR\&. -Any number of arguments may be supplied, and all of the IDs supplied -will be cancelled\&. -.PP -.SH EXAMPLES -.CS - - - package require defer 1 - apply {{} { - set fd [open /dev/null] - defer::defer close $fd - }} - -.CE -.SH REFERENCES -.IP [1] -.PP -.SH AUTHORS -Roy Keene -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIdefer\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -cleanup, golang -.SH CATEGORY -Utility -.SH COPYRIGHT -.nf -Copyright (c) 2017, Roy Keene - -.fi Index: idoc/man/files/modules/des/des.n ================================================================== --- idoc/man/files/modules/des/des.n +++ idoc/man/files/modules/des/des.n @@ -435,18 +435,10 @@ bugs and other problems\&. Please report such in the category \fIdes\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" aes(n), blowfish(n), md5(n), rc4(n), sha1(n) .SH KEYWORDS 3DES, DES, block cipher, data integrity, encryption, security .SH CATEGORY Index: idoc/man/files/modules/des/tcldes.n ================================================================== --- idoc/man/files/modules/des/tcldes.n +++ idoc/man/files/modules/des/tcldes.n @@ -289,18 +289,10 @@ bugs and other problems\&. Please report such in the category \fIdes\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" des(n) .SH KEYWORDS 3DES, DES, block cipher, data integrity, encryption, security .SH CATEGORY Index: idoc/man/files/modules/des/tcldesjr.n ================================================================== --- idoc/man/files/modules/des/tcldesjr.n +++ idoc/man/files/modules/des/tcldesjr.n @@ -289,18 +289,10 @@ bugs and other problems\&. Please report such in the category \fIdes\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" des(n) .SH KEYWORDS 3DES, DES, block cipher, data integrity, encryption, security .SH CATEGORY Index: idoc/man/files/modules/dicttool/dicttool.n ================================================================== --- idoc/man/files/modules/dicttool/dicttool.n +++ idoc/man/files/modules/dicttool/dicttool.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'dicttool\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2017 Sean Woods +'\" Copyright (c) 2015 Sean Woods '\" .TH "dicttool" n 1\&.0 tcllib "Extensions to the standard "dict" command" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -274,12 +274,10 @@ .SH NAME dicttool \- Dictionary Tools .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBdicttool ?1\&.0?\fR -.sp \fBladd\fR \fIvarname\fR \fIargs\fR .sp \fBldelete\fR \fIvarname\fR \fIargs\fR .sp \fBdict getnull\fR \fIargs\fR @@ -301,11 +299,11 @@ \fBladd\fR \fIvarname\fR \fIargs\fR This command will add a new instance of each element in \fIargs\fR to \fIvarname\fR, but only if that element is not already present\&. .TP \fBldelete\fR \fIvarname\fR \fIargs\fR -This command will delete all instances of each element in \fIargs\fR from \fIvarname\fR\&. +This command will add a delete all instances of each element in \fIargs\fR from \fIvarname\fR\&. .TP \fBdict getnull\fR \fIargs\fR Operates like \fBdict get\fR, however if the key \fIargs\fR does not exist, it returns an empty list instead of throwing an error\&. .TP @@ -357,22 +355,14 @@ bugs and other problems\&. Please report such in the category \fIdict\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS dict .SH CATEGORY -Utilities +Utilites .SH COPYRIGHT .nf -Copyright (c) 2017 Sean Woods +Copyright (c) 2015 Sean Woods .fi Index: idoc/man/files/modules/dns/tcllib_dns.n ================================================================== --- idoc/man/files/modules/dns/tcllib_dns.n +++ idoc/man/files/modules/dns/tcllib_dns.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'tcllib_dns\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2002, Pat Thoyts '\" -.TH "dns" n 1\&.5\&.0 tcllib "Domain Name Service" +.TH "dns" n 1\&.3\&.5 tcllib "Domain Name Service" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME dns \- Tcl Domain Name Service Client .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBdns ?1\&.5\&.0?\fR +package require \fBdns ?1\&.3\&.5?\fR .sp \fB::dns::resolve\fR \fIquery\fR ?\fIoptions\fR? .sp \fB::dns::configure\fR ?\fIoptions\fR? .sp @@ -323,16 +323,11 @@ \fINote:\fR The package defaults to using DNS over TCP connections\&. If you wish to use UDP you will need to have the \fBtcludp\fR package installed and have a version that correctly handles binary data (> 1\&.0\&.4)\&. This is available at \fIhttp://tcludp\&.sourceforge\&.net/\fR\&. -If the \fBudp\fR package is present then UDP will be used by -default\&. -.PP -\fINote:\fR The package supports DNS over TLS (RFC 7858) for -enhanced privacy of DNS queries\&. Using this feature requires -the TLS package\&. +If the \fBudp\fR package is present then UDP will be used by default\&. .SH COMMANDS .TP \fB::dns::resolve\fR \fIquery\fR ?\fIoptions\fR? Resolve a domain name using the \fIDNS\fR protocol\&. \fIquery\fR is the domain name to be lookup up\&. This should be either a fully @@ -371,29 +366,10 @@ act upon your request\&. Normally set to \fItrue\fR\&. .TP \fB-command\fR \fIprocname\fR Set a procedure to be called upon request completion\&. The procedure will be passed the token as its only argument\&. -.TP -\fB-usetls\fR \fIboolean\fR -Set the \fItrue\fR to use DNS over TLS\&. This will force the use of -TCP and change the default port to 853\&. Certificate validation is -required so a source of trusted certificate authority certificates -must be provided using \fI-cafile\fR or \fI-cadir\fR\&. -.TP -\fB-cafile\fR \fIfilepath\fR -Specify a file containing a collection of trusted certificate -authority certficates\&. See the \fBupdate-ca-certificates\fR command -manual page for details or the \fB-CAfile\fR option help from -\fBopenssl\fR\&. -.TP -\fB-cadir\fR \fIdirpath\fR -Specify a directory containing trusted certificate authority -certificates\&. This must be provided if \fB-cafile\fR is not -specified for certificate validation to work when \fB-usetls\fR is -enabled\&. See the \fBopenssl\fR documentation for the required -structure of this directory\&. .RE .sp .TP \fB::dns::configure\fR ?\fIoptions\fR? The \fB::dns::configure\fR command is used to setup the dns @@ -422,18 +398,10 @@ .TP \fB-loglevel\fR \fIlevel\fR Set the log level used for emitting diagnostic messages from this package\&. The default is \fIwarn\fR\&. See the \fBlog\fR package for details of the available levels\&. -.TP -\fB-cafile\fR \fIfilepath\fR -Set the default file path to be used for the \fB-cafile\fR -option to \fBdns::resolve\fR\&. -.TP -\fB-cadir\fR \fIdirpath\fR -Set the default directory path to be used for the \fB-cadir\fR -option to \fBdns::resolve\fR\&. .RE .sp .TP \fB::dns::name\fR \fItoken\fR Returns a list of all domain names returned as an answer to your query\&. @@ -516,23 +484,10 @@ ::dns::1 % dns::name $tok localhost % dns::cleanup $tok -.CE -.PP -Using DNS over TLS (RFC 7858): -.CS - - -% set tok [dns::resolve www\&.tcl\&.tk -nameserver dns-tls\&.bitwiseshift\&.net -usetls 1 -cafile /etc/ssl/certs/ca-certificates\&.crt] -::dns::12 -% dns::wait $tok -ok -% dns::address $tok -104\&.25\&.119\&.118 104\&.25\&.120\&.118 - .CE .SH REFERENCES .IP [1] Mockapetris, P\&., "Domain Names - Concepts and Facilities", RFC 1034, November 1987\&. @@ -556,15 +511,10 @@ (\fIhttp://www\&.ietf\&.org/rfc/rfc2782\&.txt\fR) .IP [6] Ohta, M\&. "Incremental Zone Transfer in DNS", RFC 1995, August 1996, (\fIhttp://www\&.ietf\&.org/rfc/rfc1995\&.txt\fR) -.IP [7] -Hu, Z\&., etc al\&. -"Specification for DNS over Transport Layer Security (TLS)", -RFC 7858, May 2016, -(\fIhttp://www\&.ietf\&.org/rfc/rfc7858\&.txt\fR) .PP .SH AUTHORS Pat Thoyts .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain @@ -571,24 +521,16 @@ bugs and other problems\&. Please report such in the category \fIdns\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" resolver(5) .SH KEYWORDS -DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886, rfc 7858 +DNS, domain name service, resolver, rfc 1034, rfc 1035, rfc 1886 .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002, Pat Thoyts .fi Index: idoc/man/files/modules/dns/tcllib_ip.n ================================================================== --- idoc/man/files/modules/dns/tcllib_ip.n +++ idoc/man/files/modules/dns/tcllib_ip.n @@ -342,19 +342,19 @@ and comparing internet addresses\&. The package can handle both IPv4 (1) and IPv6 (2) address types\&. .SH COMMANDS .TP \fB::ip::version\fR \fIaddress\fR -Returns the protocol version of the address (\fB4\fR or \fB6\fR), -or \fB-1\fR if the address is neither IPv4 or IPv6\&. +Returns the protocol version of the address (4 or 6) or 0 if the +address is neither IPv4 or IPv6\&. .TP \fB::ip::is\fR \fIclass\fR \fIaddress\fR Returns true if the address is a member of the given protocol -class\&. The class parameter may be either \fBipv4\fR or \fBipv6\fR +class\&. The class parameter may be either \fIipv4\fR or \fIipv6\fR This is effectively a boolean equivalent of the \fBversion\fR -command\&. The \fIclass\fR argument may be shortened to \fB4\fR or -\fB6\fR\&. +command\&. The \fIclass\fR argument may be shortened to \fI4\fR or +\fI6\fR\&. .TP \fB::ip::equal\fR \fIaddress\fR \fIaddress\fR Compare two address specifications for equivalence\&. The arguments are normalized and the address prefix determined (if a mask is supplied)\&. The normalized addresses are then compared bit-by-bit and @@ -736,18 +736,10 @@ bugs and other problems\&. Please report such in the category \fIdns\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" inet(3), ip(7), ipv6(7) .SH KEYWORDS internet address, ip, ipv4, ipv6, rfc 3513 .SH CATEGORY Index: idoc/man/files/modules/docstrip/docstrip.n ================================================================== --- idoc/man/files/modules/docstrip/docstrip.n +++ idoc/man/files/modules/docstrip/docstrip.n Index: idoc/man/files/modules/docstrip/docstrip_util.n ================================================================== --- idoc/man/files/modules/docstrip/docstrip_util.n +++ idoc/man/files/modules/docstrip/docstrip_util.n Index: idoc/man/files/modules/doctools/changelog.n ================================================================== --- idoc/man/files/modules/doctools/changelog.n +++ idoc/man/files/modules/doctools/changelog.n @@ -354,22 +354,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS changelog, doctools, emacs .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2003-2013 Andreas Kupries .fi Index: idoc/man/files/modules/doctools/cvs.n ================================================================== --- idoc/man/files/modules/doctools/cvs.n +++ idoc/man/files/modules/doctools/cvs.n @@ -334,10 +334,11 @@ The values are lists of the files the entry is touching\&. .RE .sp .TP \fB::doctools::cvs::toChangeLog\fR \fIevar\fR \fIcvar\fR \fIfvar\fR +] The three arguments for this command are the same as the last three arguments of the command \fB::doctools::cvs::scanLog\fR\&. This command however expects them to be filled with information about one or more logs\&. It takes this information and converts it into a text in the format of a ChangeLog as accepted and generated by \fBemacs\fR\&. The @@ -348,18 +349,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" [uri, http://wiki\&.tcl\&.tk/log2changelog .SH KEYWORDS changelog, cvs, cvs log, emacs, log .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx.n ================================================================== --- idoc/man/files/modules/doctools/docidx.n +++ idoc/man/files/modules/doctools/docidx.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'docidx\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2003-2019 Andreas Kupries +'\" Copyright (c) 2003-2014 Andreas Kupries '\" -.TH "doctools::idx" n 1\&.1 tcllib "Documentation tools" +.TH "doctools::idx" n 1\&.0\&.5 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME doctools::idx \- docidx - Processing indices .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBdoctools::idx ?1\&.1?\fR +package require \fBdoctools::idx ?1\&.0\&.5?\fR .sp \fB::doctools::idx::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR \&.\&.\&.? .sp \fB::doctools::idx::help\fR .sp @@ -559,13 +559,10 @@ list This engine retrieves version, section and title of the manpage from the document\&. As such it can be used to generate a directory listing for a set of manpages\&. .TP -markdown -This engine generates \fIMarkdown\fR markup\&. -.TP nroff This engine generates nroff output, for processing by \fBnroff\fR, or \fBgroff\fR\&. The result will be standard man pages as they are known in the unix world\&. .TP @@ -586,24 +583,16 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, docidx_lang_cmdref, docidx_lang_intro, docidx_lang_syntax, docidx_plugin_apiref .SH KEYWORDS -HTML, TMML, conversion, docidx, documentation, index, keyword index, latex, manpage, markdown, markup, nroff, wiki +HTML, TMML, conversion, docidx, documentation, index, keyword index, latex, manpage, markup, nroff, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2003-2019 Andreas Kupries +Copyright (c) 2003-2014 Andreas Kupries .fi Index: idoc/man/files/modules/doctools/docidx_intro.n ================================================================== --- idoc/man/files/modules/doctools/docidx_intro.n +++ idoc/man/files/modules/doctools/docidx_intro.n @@ -337,18 +337,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax, docidx_plugin_apiref, doctoc_intro, doctools::idx, doctools_intro .SH KEYWORDS index, keyword index, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx_lang_cmdref.n ================================================================== --- idoc/man/files/modules/doctools/docidx_lang_cmdref.n +++ idoc/man/files/modules/doctools/docidx_lang_cmdref.n @@ -378,18 +378,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax .SH KEYWORDS docidx commands, docidx language, docidx markup, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx_lang_faq.n ================================================================== --- idoc/man/files/modules/doctools/docidx_lang_faq.n +++ idoc/man/files/modules/doctools/docidx_lang_faq.n @@ -307,18 +307,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_lang_cmdref, docidx_lang_intro, docidx_lang_syntax .SH KEYWORDS docidx commands, docidx language, docidx markup, docidx syntax, examples, faq, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx_lang_intro.n ================================================================== --- idoc/man/files/modules/doctools/docidx_lang_intro.n +++ idoc/man/files/modules/doctools/docidx_lang_intro.n @@ -299,11 +299,11 @@ .CE .CS - \&.\&.\&. [manpage thefile \\ + \&.\&.\&. [manpage thefile \\\\ {file description}] \&.\&.\&. .CE .SS "BASIC STRUCTURE" The most simple document which can be written in docidx is @@ -452,18 +452,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, docidx_lang_cmdref, docidx_lang_syntax .SH KEYWORDS docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx_lang_syntax.n ================================================================== --- idoc/man/files/modules/doctools/docidx_lang_syntax.n +++ idoc/man/files/modules/doctools/docidx_lang_syntax.n @@ -356,18 +356,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro .SH KEYWORDS docidx commands, docidx language, docidx markup, docidx syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/docidx_plugin_apiref.n ================================================================== --- idoc/man/files/modules/doctools/docidx_plugin_apiref.n +++ idoc/man/files/modules/doctools/docidx_plugin_apiref.n @@ -634,18 +634,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, docidx_lang_cmdref, docidx_lang_faq, docidx_lang_intro, docidx_lang_syntax, doctools::idx .SH KEYWORDS formatting engine, index, index formatter, keywords, markup, plugin, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc.n ================================================================== --- idoc/man/files/modules/doctools/doctoc.n +++ idoc/man/files/modules/doctools/doctoc.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'doctoc\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2003-2019 Andreas Kupries +'\" Copyright (c) 2003-2014 Andreas Kupries '\" -.TH "doctools::toc" n 1\&.2 tcllib "Documentation tools" +.TH "doctools::toc" n 1\&.1\&.4 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME doctools::toc \- doctoc - Processing tables of contents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBdoctools::toc ?1\&.2?\fR +package require \fBdoctools::toc ?1\&.1\&.4?\fR .sp \fB::doctools::toc::new\fR \fIobjectName\fR ?\fB-option\fR \fIvalue\fR \&.\&.\&.? .sp \fB::doctools::toc::help\fR .sp @@ -559,13 +559,10 @@ list This engine retrieves version, section and title of the manpage from the document\&. As such it can be used to generate a directory listing for a set of manpages\&. .TP -markdown -This engine generates \fIMarkdown\fR markup\&. -.TP nroff This engine generates nroff output, for processing by \fBnroff\fR, or \fBgroff\fR\&. The result will be standard man pages as they are known in the unix world\&. .TP @@ -586,24 +583,16 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syntax, doctoc_plugin_apiref .SH KEYWORDS -HTML, TMML, conversion, doctoc, documentation, latex, manpage, markdown, markup, nroff, table of contents, toc, wiki +HTML, TMML, conversion, doctoc, documentation, latex, manpage, markup, nroff, table of contents, toc, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2003-2019 Andreas Kupries +Copyright (c) 2003-2014 Andreas Kupries .fi Index: idoc/man/files/modules/doctools/doctoc_intro.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_intro.n +++ idoc/man/files/modules/doctools/doctoc_intro.n @@ -336,18 +336,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax, doctoc_plugin_apiref, doctools::toc, doctools_intro .SH KEYWORDS markup, semantic markup, table of contents, toc .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc_lang_cmdref.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_lang_cmdref.n +++ idoc/man/files/modules/doctools/doctoc_lang_cmdref.n @@ -385,18 +385,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax .SH KEYWORDS doctoc commands, doctoc language, doctoc markup, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc_lang_faq.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_lang_faq.n +++ idoc/man/files/modules/doctools/doctoc_lang_faq.n @@ -307,18 +307,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_lang_cmdref, doctoc_lang_intro, doctoc_lang_syntax .SH KEYWORDS doctoc commands, doctoc language, doctoc markup, doctoc syntax, examples, faq, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc_lang_intro.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_lang_intro.n +++ idoc/man/files/modules/doctools/doctoc_lang_intro.n @@ -299,11 +299,11 @@ .CE .CS - \&.\&.\&. [item thefile \\ + \&.\&.\&. [item thefile \\\\ label {file description}] \&.\&.\&. .CE .SS "BASIC STRUCTURE" The most simple document which can be written in doctoc is @@ -523,18 +523,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctoc_lang_cmdref, doctoc_lang_syntax .SH KEYWORDS doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc_lang_syntax.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_lang_syntax.n +++ idoc/man/files/modules/doctools/doctoc_lang_syntax.n @@ -344,18 +344,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro .SH KEYWORDS doctoc commands, doctoc language, doctoc markup, doctoc syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctoc_plugin_apiref.n ================================================================== --- idoc/man/files/modules/doctools/doctoc_plugin_apiref.n +++ idoc/man/files/modules/doctools/doctoc_plugin_apiref.n @@ -634,18 +634,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro, doctoc_lang_syntax, doctools::toc .SH KEYWORDS formatting engine, markup, plugin, semantic markup, table of contents, toc, toc formatter .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools.n ================================================================== --- idoc/man/files/modules/doctools/doctools.n +++ idoc/man/files/modules/doctools/doctools.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'doctools\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2003-2019 Andreas Kupries +'\" Copyright (c) 2003-2014 Andreas Kupries '\" -.TH "doctools" n 1\&.5\&.6 tcllib "Documentation tools" +.TH "doctools" n 1\&.4\&.19 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME doctools \- doctools - Processing documents .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBdoctools ?1\&.5\&.6?\fR +package require \fBdoctools ?1\&.4\&.19?\fR .sp \fB::doctools::new\fR \fIobjectName\fR ?\fIoption value\fR\&.\&.\&.? .sp \fB::doctools::help\fR .sp @@ -608,11 +608,11 @@ xref The value for this parameter has to be a list of triples specifying cross-reference information\&. This information is used by the engine to create more hyperlinks\&. Each triple is a list containing a pattern, symbolic filename and fragment reference, in this order\&. If a pattern -is specified multiple times the last occurrence of the pattern will be +is specified multiple times the last occurence of the pattern will be used\&. .sp The engine will consult the xref database when encountering specific commands and will create a link if the relevant text matches one of the patterns\&. No link will be created if no match was found\&. The link @@ -671,33 +671,10 @@ .TP nroff This engine generates nroff output, for processing by \fBnroff\fR, or \fBgroff\fR\&. The result will be standard man pages as they are known in the unix world\&. -.TP -markdown -This engine generates \fIMarkdown\fR markup\&. This engine supports two -parameters: -.RS -.TP -header -The value for this parameter has to be valid selfcontained markdown -markup for the body section of a markdown document\&. The default value -is the empty string\&. The value is inserted into the generated output -just before the table of contents\&. -.sp -This can be used to insert boilerplate header markup into the -generated document\&. -.TP -xref -The value for this parameter has to be a list of triples specifying -cross-reference information\&. -.sp -The full details of expected syntax and engine-internal use are -explained above for the \fIhtml\fR engine\&. -.RE -.sp .TP null This engine generates no outout at all\&. This can be used if one just wants to validate some input\&. .TP @@ -714,24 +691,16 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools_intro, doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref .SH KEYWORDS -HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff +HTML, TMML, conversion, documentation, manpage, markup, nroff .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2003-2019 Andreas Kupries +Copyright (c) 2003-2014 Andreas Kupries .fi Index: idoc/man/files/modules/doctools/doctools_intro.n ================================================================== --- idoc/man/files/modules/doctools/doctools_intro.n +++ idoc/man/files/modules/doctools/doctools_intro.n @@ -335,18 +335,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, doctoc_intro, doctools, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref .SH KEYWORDS markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools_lang_cmdref.n ================================================================== --- idoc/man/files/modules/doctools/doctools_lang_cmdref.n +++ idoc/man/files/modules/doctools/doctools_lang_cmdref.n @@ -798,18 +798,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools_intro, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax .SH KEYWORDS doctools commands, doctools language, doctools markup, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools_lang_faq.n ================================================================== --- idoc/man/files/modules/doctools/doctools_lang_faq.n +++ idoc/man/files/modules/doctools/doctools_lang_faq.n @@ -307,18 +307,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools_lang_cmdref, doctools_lang_intro, doctools_lang_syntax .SH KEYWORDS doctools commands, doctools language, doctools markup, doctools syntax, examples, faq, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools_lang_intro.n ================================================================== --- idoc/man/files/modules/doctools/doctools_lang_intro.n +++ idoc/man/files/modules/doctools/doctools_lang_intro.n @@ -298,11 +298,11 @@ .CE .CS - \&.\&.\&. [call [cmd foo] \\ + \&.\&.\&. [call [cmd foo] \\\\ [arg bar]] \&.\&.\&. .CE .CS @@ -332,11 +332,11 @@ [keywords {doctools syntax}] [keywords markup] [keywords {semantic markup}] [description] [vset CATEGORY doctools] -[include \&.\&./common-text/feedback\&.inc] +[include \&.\&./doctools2base/include/feedback\&.inc] [manpage_end] .CE This also shows us that all doctools documents are split into two parts, the \fIheader\fR and the \fIbody\fR\&. Everything coming before @@ -374,10 +374,20 @@ Given the above a less minimal example of a document is .CS [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [\fBcopyright {YEAR AUTHOR}\fR] [\fBtitledesc TITLE\fR] [\fBmoddesc MODULE_TITLE\fR] [\fBrequire PACKAGE VERSION\fR] [\fBrequire PACKAGE\fR] @@ -388,14 +398,24 @@ Remember that the whitespace is optional\&. The document .CS [manpage_begin NAME SECTION VERSION] +[see_also doctools_intro] +[see_also doctools_lang_cmdref] +[see_also doctools_lang_faq] +[see_also doctools_lang_syntax] +[keywords {doctools commands}] +[keywords {doctools language}] +[keywords {doctools markup}] +[keywords {doctools syntax}] +[keywords markup] +[keywords {semantic markup}] [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] [require PACKAGE VERSION][require PACKAGE][description] [vset CATEGORY doctools] -[include \&.\&./common-text/feedback\&.inc] +[include \&.\&./doctools2base/include/feedback\&.inc] [manpage_end] .CE has the same meaning as the example before\&. .PP @@ -407,10 +427,20 @@ .CS [\fBcomment { \&.\&.\&. }\fR] [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [copyright {YEAR AUTHOR}] [titledesc TITLE] [moddesc MODULE_TITLE][\fBcomment { \&.\&.\&. }\fR] [require PACKAGE VERSION] [require PACKAGE] @@ -432,10 +462,20 @@ [\fBinclude FILE\fR] [\fBvset VAR VALUE\fR] [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [description] [manpage_end] .CE Even more important, these two commands are allowed anywhere where a @@ -443,10 +483,20 @@ structure\&. I\&.e\&. for example in the header as well\&. .CS [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [\fBinclude FILE\fR] [\fBvset VAR VALUE\fR] [description] [manpage_end] @@ -473,10 +523,20 @@ paragraph automatically ends at \fBmanpage_end\fR\&. .CS [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [description] \&.\&.\&. [\fBpara\fR] \&.\&.\&. [\fBpara\fR] @@ -499,10 +559,20 @@ paragraphs within sections\&. .CS [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [description] \&.\&.\&. [\fBsection {Section A}\fR] \&.\&.\&. [para] @@ -524,10 +594,20 @@ paragraphs within subsections\&. .CS [manpage_begin NAME SECTION VERSION] + + + + + + + + + + [description] \&.\&.\&. [section {Section A}] \&.\&.\&. [\fBsubsection {Sub 1}\fR] @@ -629,11 +709,11 @@ item command (\fBcall\fR), and our ability to nest them\&. .CS \&.\&.\&. - [call [\fBcmd arg_def\fR] [\fBarg type\fR] [\fBarg name\fR] [\fBopt\fR [\fBarg mode\fR]]] + [call [\fBcmd arg_def\fR] [\fBarg type\fR] [\fBarg name\fR]] [\fBopt\fR [\fBarg mode\fR]]] Text structure\&. List element\&. Argument list\&. Automatically closes the previous list element\&. Specifies the data-[\fBarg type\fR] of the described argument of a command, its [\fBarg name\fR] and its i/o-[\fBarg mode\fR]\&. The latter is optional\&. @@ -860,18 +940,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_syntax .SH KEYWORDS doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools_lang_syntax.n ================================================================== --- idoc/man/files/modules/doctools/doctools_lang_syntax.n +++ idoc/man/files/modules/doctools/doctools_lang_syntax.n @@ -381,18 +381,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro .SH KEYWORDS doctools commands, doctools language, doctools markup, doctools syntax, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/doctools_plugin_apiref.n ================================================================== --- idoc/man/files/modules/doctools/doctools_plugin_apiref.n +++ idoc/man/files/modules/doctools/doctools_plugin_apiref.n @@ -702,18 +702,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctools, doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax .SH KEYWORDS document, formatter, formatting engine, manpage, markup, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools/mpexpand.n ================================================================== --- idoc/man/files/modules/doctools/mpexpand.n +++ idoc/man/files/modules/doctools/mpexpand.n @@ -341,18 +341,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" expander(n), format(n), formatter(n) .SH KEYWORDS HTML, TMML, conversion, manpage, markup, nroff .SH CATEGORY Index: idoc/man/files/modules/doctools2base/html_cssdefaults.n ================================================================== --- idoc/man/files/modules/doctools2base/html_cssdefaults.n +++ idoc/man/files/modules/doctools2base/html_cssdefaults.n @@ -300,22 +300,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS CSS, HTML, doctools, export, plugin, style .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2base/nroff_manmacros.n ================================================================== --- idoc/man/files/modules/doctools2base/nroff_manmacros.n +++ idoc/man/files/modules/doctools2base/nroff_manmacros.n @@ -300,22 +300,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, macros, man_macros, nroff, plugin .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2base/tcl_parse.n ================================================================== --- idoc/man/files/modules/doctools2base/tcl_parse.n +++ idoc/man/files/modules/doctools2base/tcl_parse.n @@ -428,22 +428,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Tcl syntax, command, doctools, parser, subst, word .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2base/tcllib_msgcat.n ================================================================== --- idoc/man/files/modules/doctools2base/tcllib_msgcat.n +++ idoc/man/files/modules/doctools2base/tcllib_msgcat.n @@ -321,22 +321,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS catalog package, docidx, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/export_docidx.n ================================================================== --- idoc/man/files/modules/doctools2idx/export_docidx.n +++ idoc/man/files/modules/doctools2idx/export_docidx.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::idx::export::docidx" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::idx::export::docidx" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME doctools::idx::export::docidx \- docidx export plugin .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::idx::export::docidx ?0\&.2\&.1?\fR +package require \fBdoctools::idx::export::docidx ?0\&.1?\fR .sp \fBexport\fR \fIserial\fR \fIconfiguration\fR .sp .BE .SH DESCRIPTION @@ -421,14 +421,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -452,22 +452,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS docidx, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_container.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_container.n +++ idoc/man/files/modules/doctools2idx/idx_container.n @@ -613,14 +613,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -644,22 +644,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, TMML, conversion, docidx markup, documentation, formatting, generation, index, json, keyword index, latex, manpage, markup, nroff, parsing, plugin, reference, tcler's wiki, text, url, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export.n +++ idoc/man/files/modules/doctools2idx/idx_export.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'idx_export\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::idx::export" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::idx::export" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,15 +272,15 @@ .. .BS .SH NAME doctools::idx::export \- Exporting keyword indices .SH SYNOPSIS -package require \fBdoctools::idx::export ?0\&.2\&.1?\fR +package require \fBdoctools::idx::export ?0\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::map \fR +package require \fBdoctools::config \fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBsnit \fR .sp @@ -488,11 +488,11 @@ If no value is specified it simply returns the current value, without changing it\&. .sp Note that while the user can set the predefined configuration variables \fBuser\fR and \fBformat\fR doing so will have no -effect, these values will be internally overridden when invoking an +effect, these values will be internally overriden when invoking an import plugin\&. .TP \fIobjectName\fR \fBconfig unset\fR \fIpattern\fR\&.\&.\&. This method unsets all configuration variables matching the specified glob \fIpattern\fRs\&. If no pattern is specified it will unset all @@ -627,14 +627,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -658,22 +658,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, conversion, docidx, documentation, export, formatting, generation, index, json, keyword index, manpage, markup, nroff, plugin, reference, tcler's wiki, text, url, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export_html.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export_html.n +++ idoc/man/files/modules/doctools2idx/idx_export_html.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::idx::export::html" n 0\&.2 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -506,14 +506,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -537,22 +537,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export_json.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export_json.n +++ idoc/man/files/modules/doctools2idx/idx_export_json.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::idx::export::json" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -438,14 +438,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -469,22 +469,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS JSON, doctools, export, index, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export_nroff.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export_nroff.n +++ idoc/man/files/modules/doctools2idx/idx_export_nroff.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::idx::export::nroff" n 0\&.3 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -389,14 +389,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -420,22 +420,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, index, nroff, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export_text.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export_text.n +++ idoc/man/files/modules/doctools2idx/idx_export_text.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::idx::export::text" n 0\&.2 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -373,14 +373,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -404,22 +404,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, index, plain text, serialization .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_export_wiki.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_export_wiki.n +++ idoc/man/files/modules/doctools2idx/idx_export_wiki.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::idx::export::wiki" n 0\&.2 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -386,14 +386,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -417,22 +417,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, index, serialization, wiki .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_import.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_import.n +++ idoc/man/files/modules/doctools2idx/idx_import.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'idx_import\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::idx::import" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::idx::import" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,15 +272,15 @@ .. .BS .SH NAME doctools::idx::import \- Importing keyword indices .SH SYNOPSIS -package require \fBdoctools::idx::import ?0\&.2\&.1?\fR +package require \fBdoctools::idx::import ?0\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::map \fR +package require \fBdoctools::config \fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBsnit \fR .sp @@ -503,11 +503,11 @@ If no value is specified it simply returns the current value, without changing it\&. .sp Note that while the user can set the predefined configuration variables \fBuser\fR and \fBformat\fR doing so will have no -effect, these values will be internally overridden when invoking an +effect, these values will be internally overriden when invoking an import plugin\&. .TP \fIobjectName\fR \fBconfig unset\fR \fIpattern\fR\&.\&.\&. This method unsets all configuration variables matching the specified glob \fIpattern\fRs\&. If no pattern is specified it will unset all @@ -706,14 +706,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -737,22 +737,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS conversion, docidx, documentation, import, index, json, keyword index, manpage, markup, parsing, plugin, reference, url .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_import_json.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_import_json.n +++ idoc/man/files/modules/doctools2idx/idx_import_json.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::idx::import::json" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::idx::import::json" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,13 +272,13 @@ .. .BS .SH NAME doctools::idx::import::json \- JSON import plugin .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::idx::import::json ?0\&.2\&.1?\fR +package require \fBdoctools::idx::import::json ?0\&.1?\fR .sp package require \fBdoctools::idx::structure \fR .sp package require \fBjson \fR .sp @@ -415,14 +415,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -446,22 +446,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS JSON, deserialization, doctools, import, index .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_introduction.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_introduction.n +++ idoc/man/files/modules/doctools2idx/idx_introduction.n @@ -371,17 +371,17 @@ ~~ | ~~ doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -struct::map = | | | = doctools::include struct::map fileutil::paths +doctools::config = | | | = doctools::include doctools::config doctools::paths | | | | | doctools::idx::export::<*> | | | doctools::idx::import::<*> docidx | | | docidx, json - json | | | | \\ - html | | | doctools::idx::parse \\ - nroff | | | | \\ + json | | | | \\\\ + html | | | doctools::idx::parse \\\\ + nroff | | | | \\\\ wiki | | | +---------------+ json text | | | | | doctools::idx::structure | | +-------+---------------+ @@ -405,18 +405,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx_intro, doctoc_intro, doctools, doctools2doc_introduction, doctools2toc_introduction, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref .SH KEYWORDS conversion, formatting, index, keyword index, markup, parsing, plugin, semantic markup .SH CATEGORY Index: idoc/man/files/modules/doctools2idx/idx_msgcat_c.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_msgcat_c.n +++ idoc/man/files/modules/doctools2idx/idx_msgcat_c.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS C, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_msgcat_de.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_msgcat_de.n +++ idoc/man/files/modules/doctools2idx/idx_msgcat_de.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS DE, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_msgcat_en.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_msgcat_en.n +++ idoc/man/files/modules/doctools2idx/idx_msgcat_en.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EN, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_msgcat_fr.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_msgcat_fr.n +++ idoc/man/files/modules/doctools2idx/idx_msgcat_fr.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS FR, catalog package, docidx, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_parse.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_parse.n +++ idoc/man/files/modules/doctools2idx/idx_parse.n @@ -398,11 +398,11 @@ .IP [2] Each error element will be a list containing six strings describing an error in detail\&. The strings will be .RS .IP [1] -The path of the file the error occurred in\&. This may be empty\&. +The path of the file the error occured in\&. This may be empty\&. .IP [2] The range of the token the error was found at\&. This range is a two-element list containing the offset of the first and last character in the range, counted from the beginning of the input (file)\&. Offsets are counted from zero\&. @@ -494,14 +494,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -525,22 +525,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS docidx, doctools, lexer, parser .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/idx_structure.n ================================================================== --- idoc/man/files/modules/doctools2idx/idx_structure.n +++ idoc/man/files/modules/doctools2idx/idx_structure.n @@ -422,14 +422,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -453,22 +453,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS deserialization, docidx, doctools, serialization .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2idx/import_docidx.n ================================================================== --- idoc/man/files/modules/doctools2idx/import_docidx.n +++ idoc/man/files/modules/doctools2idx/import_docidx.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::idx::import::docidx" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::idx::import::docidx" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,13 +272,13 @@ .. .BS .SH NAME doctools::idx::import::docidx \- docidx import plugin .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::idx::import::docidx ?0\&.2\&.1?\fR +package require \fBdoctools::idx::import::docidx ?0\&.1?\fR .sp package require \fBdoctools::idx::parse \fR .sp package require \fBdoctools::idx::structure \fR .sp @@ -397,14 +397,14 @@ The \fItype\fR of a reference can be one of two values, .RS .TP \fBmanpage\fR The identifier of the reference is interpreted as symbolic file name, -referring to one of the documents the index was made for\&. +refering to one of the documents the index was made for\&. .TP \fBurl\fR -The identifier of the reference is interpreted as an url, referring to +The identifier of the reference is interpreted as an url, refering to some external location, like a website, etc\&. .RE .RE .TP canonical serialization @@ -428,22 +428,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS deserialization, docidx, doctools, import, index .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/export_doctoc.n ================================================================== --- idoc/man/files/modules/doctools2toc/export_doctoc.n +++ idoc/man/files/modules/doctools2toc/export_doctoc.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::toc::export::doctoc" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::toc::export::doctoc" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME doctools::toc::export::doctoc \- doctoc export plugin .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::toc::export::doctoc ?0\&.2\&.1?\fR +package require \fBdoctools::toc::export::doctoc ?0\&.1?\fR .sp \fBexport\fR \fIserial\fR \fIconfiguration\fR .sp .BE .SH DESCRIPTION @@ -479,22 +479,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctoc, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/import_doctoc.n ================================================================== --- idoc/man/files/modules/doctools2toc/import_doctoc.n +++ idoc/man/files/modules/doctools2toc/import_doctoc.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::toc::import::doctoc" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::toc::import::doctoc" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,13 +272,13 @@ .. .BS .SH NAME doctools::toc::import::doctoc \- doctoc import plugin .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::toc::import::doctoc ?0\&.2\&.1?\fR +package require \fBdoctools::toc::import::doctoc ?0\&.1?\fR .sp package require \fBdoctools::toc::parse \fR .sp package require \fBdoctools::toc::structure \fR .sp @@ -456,22 +456,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS deserialization, doctoc, doctools, import, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_container.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_container.n +++ idoc/man/files/modules/doctools2toc/toc_container.n @@ -459,22 +459,22 @@ The result of the method is the empty string\&. .TP \fIobjectName\fR \fBup\fR \fIid\fR This method returns the handle of the parent for the element identified by its handle \fIid\fR, or the empty string if \fIid\fR -referred to the root element\&. +refered to the root element\&. .TP \fIobjectName\fR \fBnext\fR \fIid\fR This method returns the handle of the right sibling for the element identified by its handle \fIid\fR, or the handle of the parent if the -element has no right sibling, or the empty string if \fIid\fR referred +element has no right sibling, or the empty string if \fIid\fR refered to the root element\&. .TP \fIobjectName\fR \fBprev\fR \fIid\fR This method returns the handle of the left sibling for the element identified by its handle \fIid\fR, or the handle of the parent if the -element has no left sibling, or the empty string if \fIid\fR referred +element has no left sibling, or the empty string if \fIid\fR refered to the root element\&. .TP \fIobjectName\fR \fBchild\fR \fIid\fR \fIlabel\fR ?\fI\&.\&.\&.\fR? This method returns the handle of a child of the element identified by its handle \fIid\fR\&. The child itself is identified by a series of @@ -727,22 +727,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, TMML, conversion, doctoc markup, documentation, formatting, generation, json, latex, markup, nroff, parsing, plugin, reference, table, table of contents, tcler's wiki, text, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export.n +++ idoc/man/files/modules/doctools2toc/toc_export.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'toc_export\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::toc::export" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::toc::export" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,15 +272,15 @@ .. .BS .SH NAME doctools::toc::export \- Exporting tables of contents .SH SYNOPSIS -package require \fBdoctools::toc::export ?0\&.2\&.1?\fR +package require \fBdoctools::toc::export ?0\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::map \fR +package require \fBdoctools::config \fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBsnit \fR .sp @@ -479,11 +479,11 @@ If no value is specified it simply returns the current value, without changing it\&. .sp Note that while the user can set the predefined configuration variables \fBuser\fR and \fBformat\fR doing so will have no -effect, these values will be internally overridden when invoking an +effect, these values will be internally overriden when invoking an import plugin\&. .TP \fIobjectName\fR \fBconfig unset\fR \fIpattern\fR\&.\&.\&. This method unsets all configuration variables matching the specified glob \fIpattern\fRs\&. If no pattern is specified it will unset all @@ -675,22 +675,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, conversion, doctoc, documentation, export, formatting, generation, json, manpage, markup, nroff, plugin, reference, table, table of contents, tcler's wiki, text, url, wiki .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export_html.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export_html.n +++ idoc/man/files/modules/doctools2toc/toc_export_html.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::toc::export::html" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -529,22 +529,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS HTML, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export_json.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export_json.n +++ idoc/man/files/modules/doctools2toc/toc_export_json.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::toc::export::json" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -517,22 +517,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS JSON, doctools, export, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export_nroff.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export_nroff.n +++ idoc/man/files/modules/doctools2toc/toc_export_nroff.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::toc::export::nroff" n 0\&.2 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -448,22 +448,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, nroff, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export_text.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export_text.n +++ idoc/man/files/modules/doctools2toc/toc_export_text.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::toc::export::text" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -431,22 +431,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, plain text, serialization, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_export_wiki.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_export_wiki.n +++ idoc/man/files/modules/doctools2toc/toc_export_wiki.n @@ -1,8 +1,8 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" .TH "doctools::toc::export::wiki" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" @@ -437,22 +437,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctools, export, serialization, table of contents, toc, wiki .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_import.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_import.n +++ idoc/man/files/modules/doctools2toc/toc_import.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'toc_import\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::toc::import" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::toc::import" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,15 +272,15 @@ .. .BS .SH NAME doctools::toc::import \- Importing keyword indices .SH SYNOPSIS -package require \fBdoctools::toc::import ?0\&.2\&.1?\fR +package require \fBdoctools::toc::import ?0\&.1?\fR .sp package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::map \fR +package require \fBdoctools::config \fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBsnit \fR .sp @@ -494,11 +494,11 @@ If no value is specified it simply returns the current value, without changing it\&. .sp Note that while the user can set the predefined configuration variables \fBuser\fR and \fBformat\fR doing so will have no -effect, these values will be internally overridden when invoking an +effect, these values will be internally overriden when invoking an import plugin\&. .TP \fIobjectName\fR \fBconfig unset\fR \fIpattern\fR\&.\&.\&. This method unsets all configuration variables matching the specified glob \fIpattern\fRs\&. If no pattern is specified it will unset all @@ -756,22 +756,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS conversion, doctoc, documentation, import, json, manpage, markup, parsing, plugin, reference, table, table of contents, url .SH CATEGORY Documentation tools .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_import_json.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_import_json.n +++ idoc/man/files/modules/doctools2toc/toc_import_json.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'plugin\&.inc' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "doctools::toc::import::json" n 0\&.2\&.1 tcllib "Documentation tools" +.TH "doctools::toc::import::json" n 0\&.1 tcllib "Documentation tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,13 +272,13 @@ .. .BS .SH NAME doctools::toc::import::json \- JSON import plugin .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBdoctools::toc::import::json ?0\&.2\&.1?\fR +package require \fBdoctools::toc::import::json ?0\&.1?\fR .sp package require \fBdoctools::toc::structure \fR .sp package require \fBjson \fR .sp @@ -494,22 +494,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS JSON, deserialization, doctools, import, table of contents, toc .SH CATEGORY Text formatter plugin .SH COPYRIGHT .nf -Copyright (c) 2009-2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_introduction.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_introduction.n +++ idoc/man/files/modules/doctools2toc/toc_introduction.n @@ -371,17 +371,17 @@ ~~ | ~~ doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -struct:map = | | | = doctools::include struct::map fileutil::paths +doctools::config = | | | = doctools::include doctools::config doctools::paths | | | | | doctools::toc::export::<*> | | | doctools::toc::import::<*> doctoc | | | doctoc, json - json | | | | \\ - html | | | doctools::toc::parse \\ - nroff | | | | \\ + json | | | | \\\\ + html | | | doctools::toc::parse \\\\ + nroff | | | | \\\\ wiki | | | +---------------+ json text | | | | | doctools::toc::structure | | +-------+---------------+ @@ -405,18 +405,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" doctoc_intro, doctools, doctools2doc_introduction, doctools2idx_introduction, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref .SH KEYWORDS contents, conversion, formatting, markup, parsing, plugin, semantic markup, table of contents .SH CATEGORY Index: idoc/man/files/modules/doctools2toc/toc_msgcat_c.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_msgcat_c.n +++ idoc/man/files/modules/doctools2toc/toc_msgcat_c.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS C, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_msgcat_de.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_msgcat_de.n +++ idoc/man/files/modules/doctools2toc/toc_msgcat_de.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS DE, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_msgcat_en.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_msgcat_en.n +++ idoc/man/files/modules/doctools2toc/toc_msgcat_en.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EN, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_msgcat_fr.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_msgcat_fr.n +++ idoc/man/files/modules/doctools2toc/toc_msgcat_fr.n @@ -309,22 +309,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS FR, catalog package, doctoc, doctools, i18n, internationalization, l10n, localization, message catalog, message package .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_parse.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_parse.n +++ idoc/man/files/modules/doctools2toc/toc_parse.n @@ -398,11 +398,11 @@ .IP [2] Each error element will be a list containing six strings describing an error in detail\&. The strings will be .RS .IP [1] -The path of the file the error occurred in\&. This may be empty\&. +The path of the file the error occured in\&. This may be empty\&. .IP [2] The range of the token the error was found at\&. This range is a two-element list containing the offset of the first and last character in the range, counted from the beginning of the input (file)\&. Offsets are counted from zero\&. @@ -553,22 +553,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS doctoc, doctools, lexer, parser .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/doctools2toc/toc_structure.n ================================================================== --- idoc/man/files/modules/doctools2toc/toc_structure.n +++ idoc/man/files/modules/doctools2toc/toc_structure.n @@ -498,22 +498,14 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS deserialization, doctoc, doctools, serialization .SH CATEGORY Documentation tools .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/dtplite/pkg_dtplite.n ================================================================== --- idoc/man/files/modules/dtplite/pkg_dtplite.n +++ idoc/man/files/modules/dtplite/pkg_dtplite.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pkg_dtplite\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004-2013 Andreas Kupries '\" -.TH "dtplite" n 1\&.3\&.1 tcllib "Documentation toolbox" +.TH "dtplite" n 1\&.3 tcllib "Documentation toolbox" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,11 +272,11 @@ .. .BS .SH NAME dtplite \- Lightweight DocTools Markup Processor .SH SYNOPSIS -package require \fBdtplite ?1\&.3\&.1?\fR +package require \fBdtplite ?1\&.3?\fR .sp \fBdtplite\fR \fB-o\fR \fIoutput\fR ?options? \fIformat\fR \fIinputfile\fR .sp \fBdtplite\fR \fBvalidate\fR \fIinputfile\fR .sp @@ -614,18 +614,10 @@ bugs and other problems\&. Please report such in the category \fIdoctools\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" docidx introduction, doctoc introduction, doctools introduction .SH KEYWORDS HTML, TMML, conversion, docidx, doctoc, doctools, manpage, markup, nroff .SH CATEGORY Index: idoc/man/files/modules/fileutil/fileutil.n ================================================================== --- idoc/man/files/modules/fileutil/fileutil.n +++ idoc/man/files/modules/fileutil/fileutil.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'fileutil\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "fileutil" n 1\&.16 tcllib "file utilities" +.TH "fileutil" n 1\&.15 tcllib "file utilities" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME fileutil \- Procedures implementing some file utilities .SH SYNOPSIS package require \fBTcl 8\fR .sp -package require \fBfileutil ?1\&.16?\fR +package require \fBfileutil ?1\&.15?\fR .sp \fB::fileutil::lexnormalize\fR \fIpath\fR .sp \fB::fileutil::fullnormalize\fR \fIpath\fR .sp @@ -784,17 +784,9 @@ bugs and other problems\&. Please report such in the category \fIfileutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS cat, file utilities, grep, temp file, test, touch, type .SH CATEGORY Programming tools Index: idoc/man/files/modules/fileutil/multi.n ================================================================== --- idoc/man/files/modules/fileutil/multi.n +++ idoc/man/files/modules/fileutil/multi.n @@ -315,17 +315,9 @@ bugs and other problems\&. Please report such in the category \fIfileutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS copy, file utilities, move, multi-file, remove .SH CATEGORY Programming tools Index: idoc/man/files/modules/fileutil/multiop.n ================================================================== --- idoc/man/files/modules/fileutil/multiop.n +++ idoc/man/files/modules/fileutil/multiop.n @@ -634,45 +634,45 @@ The following examples assume that the variable \fBF\fR contains a reference to a multi-file operation object\&. .CS - $F do copy \\ - the *\&.dll \\ - from c:/TDK/PrivateOpenSSL/bin \\ + $F do copy \\\\ + the *\&.dll \\\\ + from c:/TDK/PrivateOpenSSL/bin \\\\ to [installdir_of tls] .CE .CS - $F do move \\ - the * \\ - from /sources \\ - into /scratch \\ + $F do move \\\\ + the * \\\\ + from /sources \\\\ + into /scratch \\\\ but not *\&.html # Alternatively use 'except for *\&.html'\&. .CE .CS - $F do \\ - move \\ - the index \\ - from /sources \\ - into /scratch \\ + $F do \\\\ + move \\\\ + the index \\\\ + from /sources \\\\ + into /scratch \\\\ as pkgIndex\&.tcl .CE .CS - $F do \\ - remove \\ - the *\&.txt \\ + $F do \\\\ + remove \\\\ + the *\&.txt \\\\ in /scratch .CE Note that the fact that most commands just modify the object state allows us to use more off forms as specifications instead of just @@ -679,15 +679,15 @@ nearly-natural language sentences\&. For example the second example in this section can re-arranged into: .CS - $F do \\ - from /sources \\ - into /scratch \\ - but not *\&.html \\ - move \\ + $F do \\\\ + from /sources \\\\ + into /scratch \\\\ + but not *\&.html \\\\ + move \\\\ the * .CE and the result is not only still a valid specification, but even stays relatively readable\&. @@ -699,17 +699,17 @@ information\&. For example the second and third examples of this section can be merged and rewritten into the equivalent: .CS -$F do \\ - move \\ - the * \\ - from /sources \\ - into /scratch \\ - but not *\&.html not index \\ - the index \\ +$F do \\\\ + move \\\\ + the * \\\\ + from /sources \\\\ + into /scratch \\\\ + but not *\&.html not index \\\\ + the index \\\\ as pkgIndex\&.tcl .CE .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain @@ -716,17 +716,9 @@ bugs and other problems\&. Please report such in the category \fIfileutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS copy, file utilities, move, multi-file, remove .SH CATEGORY Programming tools DELETED idoc/man/files/modules/fileutil/paths.n Index: idoc/man/files/modules/fileutil/paths.n ================================================================== --- idoc/man/files/modules/fileutil/paths.n +++ idoc/man/files/modules/fileutil/paths.n @@ -1,350 +0,0 @@ -'\" -'\" Generated from file 'paths\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "fileutil::paths" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -fileutil::paths \- Manage search path pools -.SH SYNOPSIS -package require \fBTcl 8\&.4\fR -.sp -package require \fBfileutil::paths ?1?\fR -.sp -\fB::fileutil::paths\fR \fIpoolName\fR -.sp -\fBpoolName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? -.sp -\fIpoolName\fR \fBadd\fR \fIpath\fR -.sp -\fIpoolName\fR \fBclear\fR -.sp -\fIpoolName\fR \fBpaths\fR -.sp -\fIpoolName\fR \fBremove\fR \fIpath\fR -.sp -.BE -.SH DESCRIPTION -Provides a snit class whose instances manage a pool of (search) paths\&. -.SH API -The main command provides construction of search path pools: -.TP -\fB::fileutil::paths\fR \fIpoolName\fR -Creates a new, empty pool of search paths with an associated global -Tcl command whose name is \fIpoolName\fR\&. -It may be used to invoke various operations on the pool\&. -It has the following general form: -.RS -.TP -\fBpoolName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? -\fBmethod\fR and \fIarg\fRuments determine the exact behavior of -the command\&. -.RE -.IP -If \fIpoolName\fR is specified as \fB%AUTO%\fR a unique name will be -generated by the package itself\&. -The result of the command is the fully-qualified name of the instance -command\&. -.PP -.PP -The following commands are possible for pool objects: -.TP -\fIpoolName\fR \fBadd\fR \fIpath\fR -Adds the \fIpath\fR to the pool\&. -Nothing is done if the \fIpath\fR is already known to the pool\&. -The result of the command is the empty string\&. -.TP -\fIpoolName\fR \fBclear\fR -Clears the entire pool\&. In other words, removes all paths from it\&. -The result of the command is the empty string\&. -.TP -\fIpoolName\fR \fBpaths\fR -Returns the list of all paths known to the pool, in the order they -were added\&. -.TP -\fIpoolName\fR \fBremove\fR \fIpath\fR -Removes the \fIpath\fR from the pool, if it is known to the pool\&. -Unknown paths are ignored without error\&. -The result of the command is the empty string\&. -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIfileutil\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. Index: idoc/man/files/modules/fileutil/traverse.n ================================================================== --- idoc/man/files/modules/fileutil/traverse.n +++ idoc/man/files/modules/fileutil/traverse.n @@ -445,17 +445,9 @@ bugs and other problems\&. Please report such in the category \fIfileutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS directory traversal, traversal .SH CATEGORY Programming tools Index: idoc/man/files/modules/ftp/ftp.n ================================================================== --- idoc/man/files/modules/ftp/ftp.n +++ idoc/man/files/modules/ftp/ftp.n @@ -646,19 +646,11 @@ bugs and other problems\&. Please report such in the category \fIftp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" ftpd, mime, pop3, smtp .SH KEYWORDS ftp, internet, net, rfc 959 .SH CATEGORY Networking Index: idoc/man/files/modules/ftp/ftp_geturl.n ================================================================== --- idoc/man/files/modules/ftp/ftp_geturl.n +++ idoc/man/files/modules/ftp/ftp_geturl.n @@ -311,19 +311,11 @@ bugs and other problems\&. Please report such in the category \fIftp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" ftpd, mime, pop3, smtp .SH KEYWORDS ftp, internet, net, rfc 959 .SH CATEGORY Networking Index: idoc/man/files/modules/ftpd/ftpd.n ================================================================== --- idoc/man/files/modules/ftpd/ftpd.n +++ idoc/man/files/modules/ftpd/ftpd.n @@ -519,17 +519,9 @@ bugs and other problems\&. Please report such in the category \fIftpd\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ftp, ftpd, ftpserver, rfc 959, services .SH CATEGORY Networking Index: idoc/man/files/modules/fumagic/cfront.n ================================================================== --- idoc/man/files/modules/fumagic/cfront.n +++ idoc/man/files/modules/fumagic/cfront.n @@ -331,19 +331,11 @@ bugs and other problems\&. Please report such in the category \fIfileutil :: magic\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" file(1), fileutil, magic(5) .SH KEYWORDS file recognition, file type, file utilities, mime, type .SH CATEGORY Programming tools Index: idoc/man/files/modules/fumagic/cgen.n ================================================================== --- idoc/man/files/modules/fumagic/cgen.n +++ idoc/man/files/modules/fumagic/cgen.n @@ -324,19 +324,11 @@ bugs and other problems\&. Please report such in the category \fIfileutil :: magic\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" file(1), fileutil, magic(5) .SH KEYWORDS file recognition, file type, file utilities, mime, type .SH CATEGORY Programming tools Index: idoc/man/files/modules/fumagic/filetypes.n ================================================================== --- idoc/man/files/modules/fumagic/filetypes.n +++ idoc/man/files/modules/fumagic/filetypes.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'filetypes\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "fileutil::magic::filetype" n 2\&.0 tcllib "file utilities" +.TH "fileutil::magic::filetype" n 1\&.2\&.0 tcllib "file utilities" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME fileutil::magic::filetype \- Procedures implementing file-type recognition .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp -package require \fBfileutil::magic::filetype ?2\&.0?\fR +package require \fBfileutil::magic::filetype ?1\&.2\&.0?\fR .sp \fB::fileutil::magic::filetype\fR \fIfilename\fR .sp .BE .SH DESCRIPTION @@ -311,19 +311,11 @@ bugs and other problems\&. Please report such in the category \fIfileutil :: magic\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" file(1), fileutil, magic(5) .SH KEYWORDS file recognition, file type, file utilities, type .SH CATEGORY Programming tools Index: idoc/man/files/modules/fumagic/rtcore.n ================================================================== --- idoc/man/files/modules/fumagic/rtcore.n +++ idoc/man/files/modules/fumagic/rtcore.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'rtcore\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "fileutil::magic::rt" n 2\&.0 tcllib "file utilities" +.TH "fileutil::magic::rt" n 1\&.2\&.0 tcllib "file utilities" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME fileutil::magic::rt \- Runtime core for file type recognition engines written in pure Tcl .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBfileutil::magic::rt ?2\&.0?\fR +package require \fBfileutil::magic::rt ?1\&.2\&.0?\fR .sp \fB::fileutil::magic::rt::>\fR .sp \fB::fileutil::magic::rt::<\fR .sp @@ -533,19 +533,11 @@ bugs and other problems\&. Please report such in the category \fIfileutil :: magic\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" file(1), fileutil, magic(5) .SH KEYWORDS file recognition, file type, file utilities, mime, type .SH CATEGORY Programming tools Index: idoc/man/files/modules/generator/generator.n ================================================================== --- idoc/man/files/modules/generator/generator.n +++ idoc/man/files/modules/generator/generator.n Index: idoc/man/files/modules/gpx/gpx.n ================================================================== --- idoc/man/files/modules/gpx/gpx.n +++ idoc/man/files/modules/gpx/gpx.n @@ -422,22 +422,14 @@ bugs and other problems\&. Please report such in the category \fIgpx\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS gps, gpx .SH CATEGORY File formats .SH COPYRIGHT .nf Copyright (c) 2010, Keith Vetter .fi Index: idoc/man/files/modules/grammar_aycock/aycock.n ================================================================== --- idoc/man/files/modules/grammar_aycock/aycock.n +++ idoc/man/files/modules/grammar_aycock/aycock.n Index: idoc/man/files/modules/grammar_fa/dacceptor.n ================================================================== --- idoc/man/files/modules/grammar_fa/dacceptor.n +++ idoc/man/files/modules/grammar_fa/dacceptor.n @@ -349,22 +349,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_fa\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS acceptance, acceptor, automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_fa/dexec.n ================================================================== --- idoc/man/files/modules/grammar_fa/dexec.n +++ idoc/man/files/modules/grammar_fa/dexec.n @@ -419,18 +419,10 @@ bugs and other problems\&. Please report such in the category \fIgrammar_fa\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS automaton, execution, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, running, state, transducer .SH CATEGORY Grammars and finite automata .SH COPYRIGHT Index: idoc/man/files/modules/grammar_fa/fa.n ================================================================== --- idoc/man/files/modules/grammar_fa/fa.n +++ idoc/man/files/modules/grammar_fa/fa.n @@ -547,15 +547,15 @@ a possible serialization is .sp .CS - grammar::fa \\ - {yellow red green red/yellow} \\ - {Drive {0 0 {yellow Brake}} \\ - Brake {0 0 {red Stop}} \\ - Stop {1 0 {red/yellow Attention}} \\ + grammar::fa \\\\ + {yellow red green red/yellow} \\\\ + {Drive {0 0 {yellow Brake}} \\\\ + Brake {0 0 {red Stop}} \\\\ + Stop {1 0 {red/yellow Attention}} \\\\ Attention {0 0 {green Drive}}} .CE .sp A possible one, because I did not care about creation order here @@ -915,22 +915,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_fa\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004-2009 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_fa/faop.n ================================================================== --- idoc/man/files/modules/grammar_fa/faop.n +++ idoc/man/files/modules/grammar_fa/faop.n @@ -678,22 +678,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_fa\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS automaton, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, state, transducer .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/gasm.n ================================================================== --- idoc/man/files/modules/grammar_me/gasm.n +++ idoc/man/files/modules/grammar_me/gasm.n @@ -662,22 +662,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS assembler, grammar, graph, parsing, tree, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_ast.n ================================================================== --- idoc/man/files/modules/grammar_me/me_ast.n +++ idoc/man/files/modules/grammar_me/me_ast.n @@ -362,22 +362,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS AST, abstract syntax tree .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_cpu.n ================================================================== --- idoc/man/files/modules/grammar_me/me_cpu.n +++ idoc/man/files/modules/grammar_me/me_cpu.n @@ -548,22 +548,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS grammar, parsing, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2006 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_cpucore.n ================================================================== --- idoc/man/files/modules/grammar_me/me_cpucore.n +++ idoc/man/files/modules/grammar_me/me_cpucore.n @@ -661,22 +661,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS grammar, parsing, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2006 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_intro.n ================================================================== --- idoc/man/files/modules/grammar_me/me_intro.n +++ idoc/man/files/modules/grammar_me/me_intro.n @@ -327,22 +327,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS CFG, CFL, LL(k), PEG, TPDL, context-free grammar, context-free languages, expression, grammar, matching, parsing, parsing expression grammar, push down automaton, recursive descent, top-down parsing languages, transducer, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_tcl.n ================================================================== --- idoc/man/files/modules/grammar_me/me_tcl.n +++ idoc/man/files/modules/grammar_me/me_tcl.n @@ -615,22 +615,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS grammar, parsing, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_util.n ================================================================== --- idoc/man/files/modules/grammar_me/me_util.n +++ idoc/man/files/modules/grammar_me/me_util.n @@ -344,22 +344,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS abstract syntax tree, syntax tree, tree .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_me/me_vm.n ================================================================== --- idoc/man/files/modules/grammar_me/me_vm.n +++ idoc/man/files/modules/grammar_me/me_vm.n @@ -744,22 +744,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_me\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS grammar, parsing, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_peg/peg.n ================================================================== --- idoc/man/files/modules/grammar_peg/peg.n +++ idoc/man/files/modules/grammar_peg/peg.n @@ -556,24 +556,24 @@ a possible serialization is .sp .CS - grammar::peg \\ - {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\ - Factor {x Term {* {x AddOp Term}}} \\ - Term Number \\ - MulOp {/ * /} \\ - AddOp {/ + -} \\ - Number {x {? Sign} {+ Digit}} \\ - Sign {/ + -} \\ - Digit {/ 0 1 2 3 4 5 6 7 8 9} \\ - } \\ - {Expression value Factor value \\ - Term value MulOp value \\ - AddOp value Number value \\ - Sign value Digit value \\ + grammar::peg \\\\ + {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\\\ + Factor {x Term {* {x AddOp Term}}} \\\\ + Term Number \\\\ + MulOp {/ * /} \\\\ + AddOp {/ + -} \\\\ + Number {x {? Sign} {+ Digit}} \\\\ + Sign {/ + -} \\\\ + Digit {/ 0 1 2 3 4 5 6 7 8 9} \\\\ + } \\\\ + {Expression value Factor value \\\\ + Term value MulOp value \\\\ + AddOp value Number value \\\\ + Sign value Digit value \\\\ } Expression .CE .sp @@ -837,22 +837,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_peg\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS LL(k), TDPL, context-free languages, expression, grammar, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/grammar_peg/peg_interp.n ================================================================== --- idoc/man/files/modules/grammar_peg/peg_interp.n +++ idoc/man/files/modules/grammar_peg/peg_interp.n @@ -357,22 +357,14 @@ bugs and other problems\&. Please report such in the category \fIgrammar_peg\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS LL(k), TDPL, context-free languages, expression, grammar, matching, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine .SH CATEGORY Grammars and finite automata .SH COPYRIGHT .nf Copyright (c) 2005-2011 Andreas Kupries .fi Index: idoc/man/files/modules/hook/hook.n ================================================================== --- idoc/man/files/modules/hook/hook.n +++ idoc/man/files/modules/hook/hook.n @@ -609,18 +609,10 @@ bugs and other problems\&. Please report such in the category \fIhook\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" uevent(n) .SH KEYWORDS callback, event, hook, observer, producer, publisher, subject, subscriber, uevent .SH CATEGORY Index: idoc/man/files/modules/html/html.n ================================================================== --- idoc/man/files/modules/html/html.n +++ idoc/man/files/modules/html/html.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'html\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "html" n 1\&.5 tcllib "HTML Generation" +.TH "html" n 1\&.4\&.4 tcllib "HTML Generation" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME html \- Procedures to generate HTML structures .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBhtml ?1\&.5?\fR +package require \fBhtml ?1\&.4\&.4?\fR .sp \fB::html::author\fR \fIauthor\fR .sp \fB::html::bodyTag\fR \fIargs\fR .sp @@ -343,16 +343,10 @@ .sp \fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR? .sp \fB::html::meta\fR \fIargs\fR .sp -\fB::html::meta_name\fR \fIargs\fR -.sp -\fB::html::meta_equiv\fR \fIargs\fR -.sp -\fB::html::meta_charset\fR \fIcharset\fR -.sp \fB::html::css\fR \fIhref\fR .sp \fB::html::css-clear\fR .sp \fB::html::js\fR \fIhref\fR @@ -387,11 +381,11 @@ .sp \fB::html::selectPlain\fR \fIname param choices\fR ?\fIcurrent\fR? .sp \fB::html::set\fR \fIvar val\fR .sp -\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? ?\fItitle\fR? +\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? .sp \fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR? .sp \fB::html::tableFromList\fR \fIquerylist\fR ?\fIparam\fR? .sp @@ -405,12 +399,10 @@ .sp \fB::html::while\fR \fItest body\fR .sp \fB::html::doctype\fR \fIid\fR .sp -\fB::html::wrapTag\fR \fItag\fR ?\fItext\fR? ?\fIargs\fR? -.sp .BE .SH DESCRIPTION .PP The package \fBhtml\fR provides commands that generate HTML\&. These commands typically return an HTML string as their result\&. In @@ -595,35 +587,13 @@ .TP \fB::html::mailto\fR \fIemail\fR ?\fIsubject\fR? Generate a hypertext link to a mailto: URL\&. .TP \fB::html::meta\fR \fIargs\fR -Compatibility name for \fBhtml::meta_name\fR\&. -.TP -\fB::html::meta_name\fR \fIargs\fR -\fISide effect only\fR\&. -Call this before \fB::html::head\fR to define a \fImeta\fR tag for -the page\&. -The arguments (\fIargs\fR) are a Tcl-style name, value list that is -used for the \fBname=\fR and \fBcontent=\fR attributes of the -\fImeta\fR tag\&. The \fImeta\fR tag is included in the result of -\fB::html::head\fR\&. -.TP -\fB::html::meta_equiv\fR \fIargs\fR -\fISide effect only\fR\&. -Call this before \fB::html::head\fR to define a \fImeta\fR tag for -the page\&. -The arguments (\fIargs\fR) are a Tcl-style name, value list that is -used for the \fBhttp-equiv=\fR and \fBcontent=\fR attributes of -the \fImeta\fR tag\&. The \fImeta\fR tag is included in the result of -\fB::html::head\fR\&. -.TP -\fB::html::meta_charset\fR \fIcharset\fR -\fISide effect only\fR\&. -Call this before \fB::html::head\fR to -define a \fImeta\fR tag for the page\&. -The \fIcharset\fR is used with the \fBcharset=\fR attribute of the +\fISide effect only\fR\&. Call this before \fB::html::head\fR to +define a \fImeta\fR tag for the page\&. The \fIargs\fR is a Tcl-style name, +value list that is used for the name= and value= parameters for the \fImeta\fR tag\&. The \fImeta\fR tag is included in the result of \fB::html::head\fR\&. .TP \fB::html::css\fR \fIhref\fR \fISide effect only\fR\&. Call this before \fB::html::head\fR to @@ -737,15 +707,12 @@ This procedure is similar to the built-in Tcl \fBset\fR command\&. The main difference is that it returns "" so it can be called from an HTML template file without appending unwanted results\&. The other difference is that it must take two arguments\&. .TP -\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? ?\fItitle\fR? -Generate an \fIinput\fR tag of type \fIsubmit\fR\&. -The \fIname\fR defaults to "submit"\&. -When a non-empty \fItitle\fR string is specified the button gains a -\fBtitle=\fR attribute with that value\&. +\fB::html::submit\fR \fIlabel\fR ?\fIname\fR? +Generate an \fIinput\fR tag of type \fIsubmit\fR\&. \fIname\fR defaults to "submit"\&. .TP \fB::html::tableFromArray\fR \fIarrname\fR ?\fIparam\fR? ?\fIpat\fR? Generate a two-column \fItable\fR and nested rows to display a Tcl array\&. The table gets a heading that matches the array name, and each generated row contains a name, value pair\&. The array names are sorted (\fBlsort\fR without @@ -813,34 +780,19 @@ .IP [11] XHTML11 .IP [12] XHTMLB .RE -.TP -\fB::html::wrapTag\fR \fItag\fR ?\fItext\fR? ?\fIargs\fR? -A helper to wrap a \fItext\fR in a pair of open/close \fItag\fRs\&. -The arguments (\fIargs\fR) are a Tcl-style name, value list that is -used to provide attributes and associated values to the opening tag\&. -The result is a string with the open \fItag\fR along with the optional -attributes, the optional text, and the closed tag\&. .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIhtml\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" htmlparse, ncgi .SH KEYWORDS checkbox, checkbutton, form, html, radiobutton, table .SH CATEGORY CGI programming Index: idoc/man/files/modules/htmlparse/htmlparse.n ================================================================== --- idoc/man/files/modules/htmlparse/htmlparse.n +++ idoc/man/files/modules/htmlparse/htmlparse.n @@ -389,10 +389,11 @@ error if it sees incomplete HTML and has no place to store it to\&. This makes sense for the normal mode\&. Only incomplete tags are detected, not missing tags\&. Optional, defaults to 'no variable'\&. .RE .RS +.sp .TP \fIInterface to the command prefix\fR In normal mode the parser will invoke the command prefix with four arguments appended\&. See \fB::htmlparse::debugCallback\fR for a description\&. @@ -490,19 +491,11 @@ bugs and other problems\&. Please report such in the category \fIhtmlparse\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" struct::tree .SH KEYWORDS html, parsing, queue, tree .SH CATEGORY Text processing Index: idoc/man/files/modules/http/autoproxy.n ================================================================== --- idoc/man/files/modules/http/autoproxy.n +++ idoc/man/files/modules/http/autoproxy.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'autoproxy\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "autoproxy" n 1\&.7 tcllib "HTTP protocol helper modules" +.TH "autoproxy" n 1\&.5\&.3 tcllib "HTTP protocol helper modules" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -271,15 +271,15 @@ .. .BS .SH NAME autoproxy \- Automatic HTTP proxy usage and authentication .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.2\fR .sp package require \fBhttp ?2\&.0?\fR .sp -package require \fBautoproxy ?1\&.7?\fR +package require \fBautoproxy ?1\&.5\&.3?\fR .sp \fB::autoproxy::init\fR .sp \fB::autoproxy::cget\fR \fI-option\fR .sp @@ -313,19 +313,12 @@ these may be requested from the user or provided via http_proxy_user and http_proxy_pass\&. This package attempts to deal with all these schemes\&. It will do it's best to get the required parameters from the environment or registry and if it fails can be reconfigured\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -\fINote\fR This section only applies if TLS support is provided -by the \fBTLS\fR package\&. -It does not apply when \fBautoproxy\fR was configured to use some -other package which can provide the same (i\&.e \fBtwapi\fR), via -the \fB-tls_package\fR configuration option\&. -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -368,21 +361,19 @@ Connect to a secure socket through a proxy\&. HTTP proxy servers permit the use of the CONNECT HTTP command to open a link through the proxy to the target machine\&. This function hides the details\&. For use with the http package see \fBtls_socket\fR\&. .sp -The \fIargs\fR list may contain any of the options -supported by the specific TLS package that is in use but +The \fIargs\fR list may contain any of the \fBtls\fR package options but must end with the host and port as the last two items\&. .TP \fB::autoproxy::tunnel_connect\fR \fIargs\fR Connect to a target host throught a proxy\&. This uses the same CONNECT HTTP command as the \fBtls_connect\fR but does not promote the link security once the connection is established\&. .sp -The \fIargs\fR list may contain any of the options -supported by the specific TLS package that is in use but +The \fIargs\fR list may contain any of the \fBtls\fR package options but must end with the host and port as the last two items\&. .sp Note that many proxy servers will permit CONNECT calls to a limited set of ports - typically only port 443 (the secure HTTP port)\&. .TP @@ -422,18 +413,10 @@ dialog to the user to request the additional information\&. .TP \fB-basic\fR Following options are for configuring the Basic authentication scheme parameters\&. See \fBBasic Authentication\fR\&. -To unset the proxy authentication information retained from a previous -call of this function either "--" or no additional parameters can be -supplied\&. This will remove the existing authentication information\&. -.TP -\fB-tls_package\fR packagename -This option may be used to configure the Tcl package to use for -TLS support\&. Valid package names are \fBtls\fR (default) -and \fBtwapi\fR\&. .PP .SH "BASIC AUTHENTICATION" Basic is the simplest and most commonly use HTTP proxy authentication scheme\&. It is described in (1 section 11) and also in (2)\&. It offers no privacy whatsoever and its use should be discouraged in favour of @@ -449,16 +432,11 @@ .TP \fB-password\fR password The password required for the username specified\&. .TP \fB-realm\fR realm -This option is not used by this package but may be used in requesting -authentication details from the user\&. -.TP -\fB--\fR -The end-of-options indicator may be used alone to unset any -authentication details currently enabled\&. +This option is not used\&. .PP .SH EXAMPLES .PP .CS @@ -503,19 +481,11 @@ bugs and other problems\&. Please report such in the category \fIhttp :: autoproxy\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" http(n) .SH KEYWORDS authentication, http, proxy .SH CATEGORY Networking DELETED idoc/man/files/modules/httpd/httpd.n Index: idoc/man/files/modules/httpd/httpd.n ================================================================== --- idoc/man/files/modules/httpd/httpd.n +++ idoc/man/files/modules/httpd/httpd.n @@ -1,1137 +0,0 @@ -'\" -'\" Generated from file 'httpd\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2018 Sean Woods -'\" -.TH "httpd" n 4\&.3\&.5 tcllib "Tcl Web Server" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -httpd \- A TclOO and coroutine based web server -.SH SYNOPSIS -package require \fBTcl 8\&.6\fR -.sp -package require \fBuuid \fR -.sp -package require \fBclay \fR -.sp -package require \fBcoroutine \fR -.sp -package require \fBfileutil \fR -.sp -package require \fBfileutil::magic::filetype \fR -.sp -package require \fBwebsocket \fR -.sp -package require \fBmime \fR -.sp -package require \fBcron \fR -.sp -package require \fBuri \fR -.sp -package require \fBMarkdown \fR -.sp -method \fBChannelCopy\fR \fIin\fR \fIout\fR ?\fIargs\fR? -.sp -method \fBhtml_header\fR ?\fItitle\fR \fB\fR? ?\fIargs\fR? -.sp -method \fBhtml_footer\fR ?\fIargs\fR? -.sp -method \fBhttp_code_string\fR \fIcode\fR -.sp -method \fBHttpHeaders\fR \fIsock\fR ?\fIdebug\fR \fB\fR? -.sp -method \fBHttpHeaders_Default\fR -.sp -method \fBHttpServerHeaders\fR -.sp -method \fBMimeParse\fR \fImimetext\fR -.sp -method \fBUrl_Decode\fR \fIdata\fR -.sp -method \fBUrl_PathCheck\fR \fIurlsuffix\fR -.sp -method \fBwait\fR \fImode\fR \fIsock\fR -.sp -variable \fBChannelRegister\fR -.sp -variable \fBreply\fR -.sp -variable \fBrequest\fR -.sp -delegate \fB\fR -.sp -method \fBconstructor\fR \fIServerObj\fR ?\fIargs\fR? -.sp -method \fBdestructor\fR ?\fIdictargs\fR? -.sp -method \fBChannelRegister\fR ?\fIargs\fR? -.sp -method \fBclose\fR -.sp -method \fBLog_Dispatched\fR -.sp -method \fBdispatch\fR \fInewsock\fR \fIdatastate\fR -.sp -method \fBDispatch\fR -.sp -method \fBhtml_header\fR \fItitle\fR ?\fIargs\fR? -.sp -method \fBhtml_footer\fR ?\fIargs\fR? -.sp -method \fBerror\fR \fIcode\fR ?\fImsg\fR \fB\fR? ?\fIerrorInfo\fR \fB\fR? -.sp -method \fBcontent\fR -.sp -method \fBEncodeStatus\fR \fIstatus\fR -.sp -method \fBlog\fR \fItype\fR ?\fIinfo\fR \fB\fR? -.sp -method \fBCoroName\fR -.sp -method \fBDoOutput\fR -.sp -method \fBFormData\fR -.sp -method \fBPostData\fR \fIlength\fR -.sp -method \fBSession_Load\fR -.sp -method \fBputs\fR \fIline\fR -.sp -method \fBRequestFind\fR \fIfield\fR -.sp -method \fBrequest\fR \fIsubcommand\fR ?\fIargs\fR? -.sp -method \fBreply\fR \fIsubcommand\fR ?\fIargs\fR? -.sp -method \fBreset\fR -.sp -method \fBtimeOutCheck\fR -.sp -method \fBtimestamp\fR -.sp -variable \fBtemplate\fR -.sp -variable \fBurl_patterns\fR -.sp -method \fBconstructor\fR \fIargs\fR ?\fIport\fR \fBauto\fR? ?\fImyaddr\fR \fB127\&.0\&.0\&.1\fR? ?\fIstring\fR \fBauto\fR? ?\fIname\fR \fBauto\fR? ?\fIdoc_root\fR \fB\fR? ?\fIreverse_dns\fR \fB0\fR? ?\fIconfiguration_file\fR \fB\fR? ?\fIprotocol\fR \fBHTTP/1\&.1\fR? -.sp -method \fBdestructor\fR ?\fIdictargs\fR? -.sp -method \fBconnect\fR \fIsock\fR \fIip\fR \fIport\fR -.sp -method \fBServerHeaders\fR \fIip\fR \fIhttp_request\fR \fImimetxt\fR -.sp -method \fBConnect\fR \fIuuid\fR \fIsock\fR \fIip\fR -.sp -method \fBcounter\fR \fIwhich\fR -.sp -method \fBCheckTimeout\fR -.sp -method \fBdebug\fR ?\fIargs\fR? -.sp -method \fBdispatch\fR \fIdata\fR -.sp -method \fBDispatch_Default\fR \fIreply\fR -.sp -method \fBDispatch_Local\fR \fIdata\fR -.sp -method \fBHeaders_Local\fR \fIvarname\fR -.sp -method \fBHeaders_Process\fR \fIvarname\fR -.sp -method \fBHostName\fR \fIipaddr\fR -.sp -method \fBlog\fR ?\fIargs\fR? -.sp -method \fBplugin\fR \fIslot\fR ?\fIclass\fR \fB\fR? -.sp -method \fBport_listening\fR -.sp -method \fBPrefixNormalize\fR \fIprefix\fR -.sp -method \fBsource\fR \fIfilename\fR -.sp -method \fBstart\fR -.sp -method \fBstop\fR -.sp -method \fBSubObject {} db\fR -.sp -method \fBSubObject {} default\fR -.sp -method \fBtemplate\fR \fIpage\fR -.sp -method \fBTemplateSearch\fR \fIpage\fR -.sp -method \fBThread_start\fR -.sp -method \fBUuid_Generate\fR -.sp -method \fBValidate_Connection\fR \fIsock\fR \fIip\fR -.sp -method \fBreset\fR -.sp -method \fBcontent\fR -.sp -method \fBDispatch\fR -.sp -method \fBcontent\fR -.sp -method \fBFileName\fR -.sp -method \fBDirectoryListing\fR \fIlocal_file\fR -.sp -method \fBcontent\fR -.sp -method \fBDispatch\fR -.sp -variable \fBexename\fR -.sp -method \fBCgiExec\fR \fIexecname\fR \fIscript\fR \fIarglist\fR -.sp -method \fBCgi_Executable\fR \fIscript\fR -.sp -method \fBproxy_channel\fR -.sp -method \fBproxy_path\fR -.sp -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.sp -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.sp -method \fBDispatch\fR -.sp -method \fBFileName\fR -.sp -method \fBproxy_channel\fR -.sp -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.sp -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.sp -method \fBDirectoryListing\fR \fIlocal_file\fR -.sp -method \fBEncodeStatus\fR \fIstatus\fR -.sp -method \fBscgi_info\fR -.sp -method \fBproxy_channel\fR -.sp -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.sp -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.sp -method \fBdebug\fR ?\fIargs\fR? -.sp -method \fBConnect\fR \fIuuid\fR \fIsock\fR \fIip\fR -.sp -method \fBDispatch_Dict\fR \fIdata\fR -.sp -method \fBuri {} add\fR \fIvhosts\fR \fIpatterns\fR \fIinfo\fR -.sp -method \fBuri {} direct\fR \fIvhosts\fR \fIpatterns\fR \fIinfo\fR \fIbody\fR -.sp -method \fBoutput\fR -.sp -method \fBDoOutput\fR -.sp -method \fBclose\fR -.sp -method \fBlocal_memchan\fR \fIcommand\fR ?\fIargs\fR? -.sp -method \fBConnect_Local\fR \fIuuid\fR \fIsock\fR ?\fIargs\fR? -.sp -.BE -.SH DESCRIPTION -.PP -This module implements a web server, suitable for embedding in an -application\&. The server is object oriented, and contains all of the -fundamentals needed for a full service website\&. -.PP -.SH "MINIMAL EXAMPLE" -Starting a web service requires starting a class of type -\fBhttpd::server\fR, and providing that server with one or more URIs -to service, and \fBhttpd::reply\fR derived classes to generate them\&. -.CS - - -oo::class create ::reply\&.hello { - method content {} { - my puts "IRM Dispatch Server" - my puts "

Hello World!

" - my puts - } -} -::httpd::server create HTTPD port 8015 myaddr 127\&.0\&.0\&.1 doc_root ~/htdocs -HTTPD plugin dispatch httpd::server::dispatch -HTTPD uri add * /hello [list mixin reply\&.hello] - -.CE -The bare module does have facilities to hose a files from a file system\&. Files that end in a \&.tml will be substituted in the style of Tclhttpd: -.CS - - - -[my html_header {Hello World!}] -Your Server is running\&. -

-The time is now [clock format [clock seconds]] -[my html_footer] - -.CE -A complete example of an httpd server is in the /examples directory of Tcllib\&. It also show how to dispatch URIs to other processes via SCGI and HTTP proxies\&. -.CS - - -cd ~/tcl/sandbox/tcllib -tclsh examples/httpd\&.tcl - -.CE -.SH CLASSES -.SS "CLASS HTTPD::MIME" -A metaclass for MIME handling behavior across a live socket -.PP -\fBMethods\fR -.TP -method \fBChannelCopy\fR \fIin\fR \fIout\fR ?\fIargs\fR? -.TP -method \fBhtml_header\fR ?\fItitle\fR \fB\fR? ?\fIargs\fR? -Returns a block of HTML -.TP -method \fBhtml_footer\fR ?\fIargs\fR? -.TP -method \fBhttp_code_string\fR \fIcode\fR -.TP -method \fBHttpHeaders\fR \fIsock\fR ?\fIdebug\fR \fB\fR? -.TP -method \fBHttpHeaders_Default\fR -.TP -method \fBHttpServerHeaders\fR -.TP -method \fBMimeParse\fR \fImimetext\fR -Converts a block of mime encoded text to a key/value list\&. If an exception is encountered, -the method will generate its own call to the \fBerror\fR method, and immediately invoke -the \fBoutput\fR method to produce an error code and close the connection\&. -.TP -method \fBUrl_Decode\fR \fIdata\fR -De-httpizes a string\&. -.TP -method \fBUrl_PathCheck\fR \fIurlsuffix\fR -.TP -method \fBwait\fR \fImode\fR \fIsock\fR -.PP -.PP -.SS "CLASS HTTPD::REPLY" -\fIancestors\fR: \fBhttpd::mime\fR -.PP -A class which shephards a request through the process of generating a -reply\&. -The socket associated with the reply is available at all times as the \fIchan\fR -variable\&. -The process of generating a reply begins with an \fBhttpd::server\fR generating a -\fBhttp::class\fR object, mixing in a set of behaviors and then invoking the reply -object's \fBdispatch\fR method\&. -In normal operations the \fBdispatch\fR method: -.IP [1] -Invokes the \fBreset\fR method for the object to populate default headers\&. -.IP [2] -Invokes the \fBHttpHeaders\fR method to stream the MIME headers out of the socket -.IP [3] -Invokes the \fBrequest parse\fR method to convert the stream of MIME headers into a -dict that can be read via the \fBrequest\fR method\&. -.IP [4] -Stores the raw stream of MIME headers in the \fIrawrequest\fR variable of the object\&. -.IP [5] -Invokes the \fBcontent\fR method for the object, generating an call to the \fBerror\fR -method if an exception is raised\&. -.IP [6] -Invokes the \fBoutput\fR method for the object -.PP -.PP -Developers have the option of streaming output to a buffer via the \fBputs\fR method of the -reply, or simply populating the \fIreply_body\fR variable of the object\&. -The information returned by the \fBcontent\fR method is not interpreted in any way\&. -If an exception is thrown (via the \fBerror\fR command in Tcl, for example) the caller will -auto-generate a 500 {Internal Error} message\&. -A typical implementation of \fBcontent\fR look like: -.CS - - - - clay::define ::test::content\&.file { - superclass ::httpd::content\&.file - # Return a file - # Note: this is using the content\&.file mixin which looks for the reply_file variable - # and will auto-compute the Content-Type - method content {} { - my reset - set doc_root [my request get DOCUMENT_ROOT] - my variable reply_file - set reply_file [file join $doc_root index\&.html] - } - } - clay::define ::test::content\&.time { - # return the current system time - method content {} { - my variable reply_body - my reply set Content-Type text/plain - set reply_body [clock seconds] - } - } - clay::define ::test::content\&.echo { - method content {} { - my variable reply_body - my reply set Content-Type [my request get CONTENT_TYPE] - set reply_body [my PostData [my request get CONTENT_LENGTH]] - } - } - clay::define ::test::content\&.form_handler { - method content {} { - set form [my FormData] - my reply set Content-Type {text/html; charset=UTF-8} - my puts [my html_header {My Dynamic Page}] - my puts "" - my puts "You Sent

" - my puts "" - foreach {f v} $form { - my puts "" - } - my puts "
$f$v

" - my puts "Send some info:

" - my puts "

" - my puts "" - foreach field {name rank serial_number} { - set line "" - my puts $line - } - my puts "
$field
" - my puts [my html footer] - } - } - - -.CE -.PP -\fBVariable\fR -.TP -variable \fBChannelRegister\fR -.TP -variable \fBreply\fR -A dictionary which will converted into the MIME headers of the reply -.TP -variable \fBrequest\fR -A dictionary containing the SCGI transformed HTTP headers for the request -.PP -.PP -\fBDelegate\fR -.TP -delegate \fB\fR -The server object which spawned this reply -.PP -.PP -\fBMethods\fR -.TP -method \fBconstructor\fR \fIServerObj\fR ?\fIargs\fR? -.TP -method \fBdestructor\fR ?\fIdictargs\fR? -clean up on exit -.TP -method \fBChannelRegister\fR ?\fIargs\fR? -Registers a channel to be closed by the close method -.TP -method \fBclose\fR -Close channels opened by this object -.TP -method \fBLog_Dispatched\fR -Record a dispatch event -.TP -method \fBdispatch\fR \fInewsock\fR \fIdatastate\fR -Accept the handoff from the server object of the socket -\fInewsock\fR and feed it the state \fIdatastate\fR\&. -Fields the \fIdatastate\fR are looking for in particular are: -.sp -* \fBmixin\fR - A key/value list of slots and classes to be mixed into the -object prior to invoking \fBDispatch\fR\&. -.sp -* \fBhttp\fR - A key/value list of values to populate the object's \fIrequest\fR -ensemble -.sp -All other fields are passed along to the \fBclay\fR structure of the object\&. -.TP -method \fBDispatch\fR -.TP -method \fBhtml_header\fR \fItitle\fR ?\fIargs\fR? -.TP -method \fBhtml_footer\fR ?\fIargs\fR? -.TP -method \fBerror\fR \fIcode\fR ?\fImsg\fR \fB\fR? ?\fIerrorInfo\fR \fB\fR? -.TP -method \fBcontent\fR -REPLACE ME: -This method is the "meat" of your application\&. -It writes to the result buffer via the "puts" method -and can tweak the headers via "clay put header_reply" -.TP -method \fBEncodeStatus\fR \fIstatus\fR -Formulate a standard HTTP status header from he string provided\&. -.TP -method \fBlog\fR \fItype\fR ?\fIinfo\fR \fB\fR? -.TP -method \fBCoroName\fR -.TP -method \fBDoOutput\fR -Generates the the HTTP reply, streams that reply back across \fIchan\fR, -and destroys the object\&. -.TP -method \fBFormData\fR -For GET requests, converts the QUERY_DATA header into a key/value list\&. -For POST requests, reads the Post data and converts that information to -a key/value list for application/x-www-form-urlencoded posts\&. For multipart -posts, it composites all of the MIME headers of the post to a singular key/value -list, and provides MIME_* information as computed by the \fBmime\fR package, including -the MIME_TOKEN, which can be fed back into the mime package to read out the contents\&. -.TP -method \fBPostData\fR \fIlength\fR -Stream \fIlength\fR bytes from the \fIchan\fR socket, but only of the request is a -POST or PUSH\&. Returns an empty string otherwise\&. -.TP -method \fBSession_Load\fR -Manage session data -.TP -method \fBputs\fR \fIline\fR -Appends the value of \fIstring\fR to the end of \fIreply_body\fR, as well as a trailing newline -character\&. -.TP -method \fBRequestFind\fR \fIfield\fR -.TP -method \fBrequest\fR \fIsubcommand\fR ?\fIargs\fR? -.TP -method \fBreply\fR \fIsubcommand\fR ?\fIargs\fR? -.TP -method \fBreset\fR -Clear the contents of the \fIreply_body\fR variable, and reset all headers in the \fBreply\fR -structure back to the defaults for this object\&. -.TP -method \fBtimeOutCheck\fR -Called from the \fBhttp::server\fR object which spawned this reply\&. Checks to see -if too much time has elapsed while waiting for data or generating a reply, and issues -a timeout error to the request if it has, as well as destroy the object and close the -\fIchan\fR socket\&. -.TP -method \fBtimestamp\fR -Return the current system time in the format: -.CS - -%a, %d %b %Y %T %Z -.CE -.PP -.PP -.SS "CLASS HTTPD::SERVER" -\fIancestors\fR: \fBhttpd::mime\fR -.PP -.PP -\fBVariable\fR -.TP -variable \fBtemplate\fR -.TP -variable \fBurl_patterns\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBconstructor\fR \fIargs\fR ?\fIport\fR \fBauto\fR? ?\fImyaddr\fR \fB127\&.0\&.0\&.1\fR? ?\fIstring\fR \fBauto\fR? ?\fIname\fR \fBauto\fR? ?\fIdoc_root\fR \fB\fR? ?\fIreverse_dns\fR \fB0\fR? ?\fIconfiguration_file\fR \fB\fR? ?\fIprotocol\fR \fBHTTP/1\&.1\fR? -.TP -method \fBdestructor\fR ?\fIdictargs\fR? -.TP -method \fBconnect\fR \fIsock\fR \fIip\fR \fIport\fR -Reply to an open socket\&. This method builds a coroutine to manage the remainder -of the connection\&. The coroutine's operations are driven by the \fBConnect\fR method\&. -.TP -method \fBServerHeaders\fR \fIip\fR \fIhttp_request\fR \fImimetxt\fR -.TP -method \fBConnect\fR \fIuuid\fR \fIsock\fR \fIip\fR -This method reads HTTP headers, and then consults the \fBdispatch\fR method to -determine if the request is valid, and/or what kind of reply to generate\&. Under -normal cases, an object of class \fB::http::reply\fR is created, and that class's -\fBdispatch\fR method\&. -This action passes control of the socket to -the reply object\&. The reply object manages the rest of the transaction, including -closing the socket\&. -.TP -method \fBcounter\fR \fIwhich\fR -Increment an internal counter\&. -.TP -method \fBCheckTimeout\fR -Check open connections for a time out event\&. -.TP -method \fBdebug\fR ?\fIargs\fR? -.TP -method \fBdispatch\fR \fIdata\fR -Given a key/value list of information, return a data structure describing how -the server should reply\&. -.TP -method \fBDispatch_Default\fR \fIreply\fR -Method dispatch method of last resort before returning a 404 NOT FOUND error\&. -The default behavior is to look for a file in \fIDOCUMENT_ROOT\fR which -matches the query\&. -.TP -method \fBDispatch_Local\fR \fIdata\fR -Method dispatch method invoked prior to invoking methods implemented by plugins\&. -If this method returns a non-empty dictionary, that structure will be passed to -the reply\&. The default is an empty implementation\&. -.TP -method \fBHeaders_Local\fR \fIvarname\fR -Introspect and possibly modify a data structure destined for a reply\&. This -method is invoked before invoking Header methods implemented by plugins\&. -The default implementation is empty\&. -.TP -method \fBHeaders_Process\fR \fIvarname\fR -Introspect and possibly modify a data structure destined for a reply\&. This -method is built dynamically by the \fBplugin\fR method\&. -.TP -method \fBHostName\fR \fIipaddr\fR -Convert an ip address to a host name\&. If the server/ reverse_dns flag -is false, this method simply returns the IP address back\&. -Internally, this method uses the \fIdns\fR module from tcllib\&. -.TP -method \fBlog\fR ?\fIargs\fR? -Log an event\&. The input for args is free form\&. This method is intended -to be replaced by the user, and is a noop for a stock http::server object\&. -.TP -method \fBplugin\fR \fIslot\fR ?\fIclass\fR \fB\fR? -Incorporate behaviors from a plugin\&. -This method dynamically rebuilds the \fBDispatch\fR and \fBHeaders\fR -method\&. For every plugin, the server looks for the following entries in -\fIclay plugin/\fR: -.sp -\fIload\fR - A script to invoke in the server's namespace during the \fBplugin\fR method invokation\&. -.sp -\fIdispatch\fR - A script to stitch into the server's \fBDispatch\fR method\&. -.sp -\fIheaders\fR - A script to stitch into the server's \fBHeaders\fR method\&. -.sp -\fIthread\fR - A script to stitch into the server's \fBThread_start\fR method\&. -.TP -method \fBport_listening\fR -Return the actual port that httpd is listening on\&. -.TP -method \fBPrefixNormalize\fR \fIprefix\fR -For the stock version, trim trailing /'s and *'s from a prefix\&. This -method can be replaced by the end user to perform any other transformations -needed for the application\&. -.TP -method \fBsource\fR \fIfilename\fR -.TP -method \fBstart\fR -Open the socket listener\&. -.TP -method \fBstop\fR -Shut off the socket listener, and destroy any pending replies\&. -.TP -method \fBSubObject {} db\fR -.TP -method \fBSubObject {} default\fR -.TP -method \fBtemplate\fR \fIpage\fR -Return a template for the string \fIpage\fR -.TP -method \fBTemplateSearch\fR \fIpage\fR -Perform a search for the template that best matches \fIpage\fR\&. This -can include local file searches, in-memory structures, or even -database lookups\&. The stock implementation simply looks for files -with a \&.tml or \&.html extension in the ?doc_root? directory\&. -.TP -method \fBThread_start\fR -Built by the \fBplugin\fR method\&. Called by the \fBstart\fR method\&. Intended -to allow plugins to spawn worker threads\&. -.TP -method \fBUuid_Generate\fR -Generate a GUUID\&. Used to ensure every request has a unique ID\&. -The default implementation is: -.CS - - - return [::clay::uuid generate] - -.CE -.TP -method \fBValidate_Connection\fR \fIsock\fR \fIip\fR -Given a socket and an ip address, return true if this connection should -be terminated, or false if it should be allowed to continue\&. The stock -implementation always returns 0\&. This is intended for applications to -be able to implement black lists and/or provide security based on IP -address\&. -.PP -.PP -.SS "CLASS HTTPD::SERVER::DISPATCH" -\fIancestors\fR: \fBhttpd::server\fR -.PP -Provide a backward compadible alias -.PP -.SS "CLASS HTTPD::CONTENT\&.REDIRECT" -.PP -\fBMethods\fR -.TP -method \fBreset\fR -.TP -method \fBcontent\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.CACHE" -.PP -\fBMethods\fR -.TP -method \fBDispatch\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.TEMPLATE" -.PP -\fBMethods\fR -.TP -method \fBcontent\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.FILE" -Class to deliver Static content -When utilized, this class is fed a local filename -by the dispatcher -.PP -\fBMethods\fR -.TP -method \fBFileName\fR -.TP -method \fBDirectoryListing\fR \fIlocal_file\fR -.TP -method \fBcontent\fR -.TP -method \fBDispatch\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.EXEC" -.PP -\fBVariable\fR -.TP -variable \fBexename\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBCgiExec\fR \fIexecname\fR \fIscript\fR \fIarglist\fR -.TP -method \fBCgi_Executable\fR \fIscript\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.PROXY" -\fIancestors\fR: \fBhttpd::content\&.exec\fR -.PP -Return data from an proxy process -.PP -\fBMethods\fR -.TP -method \fBproxy_channel\fR -.TP -method \fBproxy_path\fR -.TP -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.TP -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.TP -method \fBDispatch\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.CGI" -\fIancestors\fR: \fBhttpd::content\&.proxy\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBFileName\fR -.TP -method \fBproxy_channel\fR -.TP -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.TP -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.TP -method \fBDirectoryListing\fR \fIlocal_file\fR -For most CGI applications a directory list is vorboten -.PP -.PP -.SS "CLASS HTTPD::PROTOCOL\&.SCGI" -Return data from an SCGI process -.PP -\fBMethods\fR -.TP -method \fBEncodeStatus\fR \fIstatus\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.SCGI" -\fIancestors\fR: \fBhttpd::content\&.proxy\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBscgi_info\fR -.TP -method \fBproxy_channel\fR -.TP -method \fBProxyRequest\fR \fIchana\fR \fIchanb\fR -.TP -method \fBProxyReply\fR \fIchana\fR \fIchanb\fR ?\fIargs\fR? -.PP -.PP -.SS "CLASS HTTPD::SERVER\&.SCGI" -\fIancestors\fR: \fBhttpd::server\fR -.PP -Act as an SCGI Server -.PP -\fBMethods\fR -.TP -method \fBdebug\fR ?\fIargs\fR? -.TP -method \fBConnect\fR \fIuuid\fR \fIsock\fR \fIip\fR -.PP -.PP -.SS "CLASS HTTPD::CONTENT\&.WEBSOCKET" -Upgrade a connection to a websocket -.PP -.SS "CLASS HTTPD::PLUGIN" -httpd plugin template -.PP -.SS "CLASS HTTPD::PLUGIN\&.DICT_DISPATCH" -A rudimentary plugin that dispatches URLs from a dict -data structure -.PP -\fBMethods\fR -.TP -method \fBDispatch_Dict\fR \fIdata\fR -Implementation of the dispatcher -.TP -method \fBuri {} add\fR \fIvhosts\fR \fIpatterns\fR \fIinfo\fR -.TP -method \fBuri {} direct\fR \fIvhosts\fR \fIpatterns\fR \fIinfo\fR \fIbody\fR -.PP -.PP -.SS "CLASS HTTPD::REPLY\&.MEMCHAN" -\fIancestors\fR: \fBhttpd::reply\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBoutput\fR -.TP -method \fBDoOutput\fR -.TP -method \fBclose\fR -.PP -.PP -.SS "CLASS HTTPD::PLUGIN\&.LOCAL_MEMCHAN" -.PP -\fBMethods\fR -.TP -method \fBlocal_memchan\fR \fIcommand\fR ?\fIargs\fR? -.TP -method \fBConnect_Local\fR \fIuuid\fR \fIsock\fR ?\fIargs\fR? -A modified connection method that passes simple GET request to an object -and pulls data directly from the reply_body data variable in the object -Needed because memchan is bidirectional, and we can't seem to communicate that -the server is one side of the link and the reply is another -.PP -.PP -.SH AUTHORS -Sean Woods -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fInetwork\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -TclOO, WWW, http, httpd, httpserver, services -.SH CATEGORY -Networking -.SH COPYRIGHT -.nf -Copyright (c) 2018 Sean Woods - -.fi Index: idoc/man/files/modules/ident/ident.n ================================================================== --- idoc/man/files/modules/ident/ident.n +++ idoc/man/files/modules/ident/ident.n @@ -316,22 +316,14 @@ bugs and other problems\&. Please report such in the category \fIident\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ident, identification, rfc 1413 .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2004 Reinhard Max .fi Index: idoc/man/files/modules/imap4/imap4.n ================================================================== --- idoc/man/files/modules/imap4/imap4.n +++ idoc/man/files/modules/imap4/imap4.n @@ -273,11 +273,11 @@ .SH NAME imap4 \- imap client-side tcl implementation of imap protocol .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBimap4 ?0\&.5\&.3?\fR +package require \fBimap4 ?0\&.5\&.2?\fR .sp \fB::imap4::open\fR \fIhostname\fR ?\fIport\fR? .sp \fB::imap4::starttls\fR \fIchan\fR .sp @@ -759,13 +759,12 @@ # Cleanup ::imap4::cleanup $imap .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -798,20 +797,10 @@ bugs and other problems\&. Please report such in the category \fIimap4\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. Only a small part of rfc3501 implemented\&. .SH "SEE ALSO" ftp, http, imap, mime, pop3, tls .SH KEYWORDS email, imap, internet, mail, net, rfc3501, ssl, tls -.SH CATEGORY -Networking Index: idoc/man/files/modules/inifile/ini.n ================================================================== --- idoc/man/files/modules/inifile/ini.n +++ idoc/man/files/modules/inifile/ini.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'ini\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "inifile" n 0\&.3\&.2 tcllib "Parsing of Windows INI files" +.TH "inifile" n 0\&.3 tcllib "Parsing of Windows INI files" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME inifile \- Parsing of Windows INI files .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBinifile ?0\&.3\&.2?\fR +package require \fBinifile ?0\&.3?\fR .sp \fB::ini::open\fR \fIfile\fR ?\fB-encoding\fR \fIencoding\fR? ?\fIaccess\fR? .sp \fB::ini::close\fR \fIini\fR .sp @@ -379,15 +379,7 @@ bugs and other problems\&. Please report such in the category \fIinifile\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH CATEGORY Text processing Index: idoc/man/files/modules/interp/deleg_method.n ================================================================== --- idoc/man/files/modules/interp/deleg_method.n +++ idoc/man/files/modules/interp/deleg_method.n @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIinterp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS comm, delegation, interpreter, method, snit .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/interp/deleg_proc.n ================================================================== --- idoc/man/files/modules/interp/deleg_proc.n +++ idoc/man/files/modules/interp/deleg_proc.n @@ -308,22 +308,14 @@ bugs and other problems\&. Please report such in the category \fIinterp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS comm, delegation, interpreter, procedure .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/interp/tcllib_interp.n ================================================================== --- idoc/man/files/modules/interp/tcllib_interp.n +++ idoc/man/files/modules/interp/tcllib_interp.n @@ -329,22 +329,14 @@ bugs and other problems\&. Please report such in the category \fIinterp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS alias, empty interpreter, interpreter, method, snit .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/irc/irc.n ================================================================== --- idoc/man/files/modules/irc/irc.n +++ idoc/man/files/modules/irc/irc.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'irc\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "irc" n 0\&.7\&.0 tcllib "Low Level Tcl IRC Interface" +.TH "irc" n 0\&.6\&.1 tcllib "Low Level Tcl IRC Interface" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -271,13 +271,13 @@ .. .BS .SH NAME irc \- Create IRC connection and interface\&. .SH SYNOPSIS -package require \fBTcl 8\&.6\fR +package require \fBTcl \fR .sp -package require \fBirc ?0\&.7\&.0?\fR +package require \fBirc ?0\&.6\&.1?\fR .sp \fB::irc::config\fR ?key? ?value? .sp \fB::irc::connection\fR .sp @@ -524,19 +524,11 @@ bugs and other problems\&. Please report such in the category \fIirc\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" rfc 1459 .SH KEYWORDS chat, irc .SH CATEGORY Networking Index: idoc/man/files/modules/irc/picoirc.n ================================================================== --- idoc/man/files/modules/irc/picoirc.n +++ idoc/man/files/modules/irc/picoirc.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'picoirc\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "picoirc" n 0\&.7\&.0 tcllib "Simple embeddable IRC interface" +.TH "picoirc" n 0\&.5\&.2 tcllib "Simple embeddable IRC interface" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -271,15 +271,15 @@ .. .BS .SH NAME picoirc \- Small and simple embeddable IRC client\&. .SH SYNOPSIS -package require \fBTcl 8\&.6\fR +package require \fBTcl \fR .sp -package require \fBpicoirc ?0\&.7\&.0?\fR +package require \fBpicoirc ?0\&.5\&.2?\fR .sp -\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR ?\fIpassword\fR? \fIurl\fR +\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR \fIurl\fR .sp \fB::picoirc::post\fR \fIcontext\fR \fIchannel\fR \fImessage\fR .sp \fB::picoirc::splituri\fR \fIuri\fR .sp @@ -301,50 +301,26 @@ This package is a fairly simple IRC client\&. If you need something with more capability investigate the \fBirc\fR package\&. .PP .SH COMMANDS .TP -\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR ?\fIpassword\fR? \fIurl\fR -Creates a new irc connection to the server specified by \fIurl\fR and -login using the \fInick\fR as the username and optionally \fIpassword\fR\&. -If the \fIurl\fR starts with \fIircs://\fR then a TLS connection is -created\&. The \fIcallback\fR must be as specified in \fBCALLBACK\fR\&. -Returns a package-specific variable that is used when calling other -commands in this package\&. -.sp -\fINote:\fR -For connecting via TLS the Tcl module \fItls\fR must be already -loaded, otherwise an error is raised\&. -.CS - - -# must be loaded for TLS -package require tls -# default arguments -tls::init -autoservername true -command workaround \\ - -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1\&.1 0 -# avoid annoying bgerror, errors are already catched internally -proc workaround {state args} { - if {$state == "verify"} { - return [lindex $args 3] - } -} - -.CE +\fB::picoirc::connect\fR \fIcallback\fR \fInick\fR \fIurl\fR +Create a new irc connection to the server specified by \fIurl\fR and +login using the \fInick\fR as the username\&. The \fIcallback\fR must be +as specified in \fBCALLBACK\fR\&. Returns a package-specific variable +that is used when calling other commands in this package\&. .TP \fB::picoirc::post\fR \fIcontext\fR \fIchannel\fR \fImessage\fR This should be called to process user input and send it to the server\&. A number of commands are recognised when prefixed with a forward-slash (/)\&. Such commands are converted to IRC command sequences and then sent\&. .TP \fB::picoirc::splituri\fR \fIuri\fR Splits an IRC scheme uniform resource indicator into its component -parts\&. Returns a list of server, port, channel and secure where -secure is a boolean flag which is \fBtrue\fR if a TLS connection was -requested via the \fIircs://\fR schema\&. The default port is 6667 (or -6697 if secured) and there is no default channel\&. +parts\&. Returns a list of server, port and channel\&. The default port is +6667 and there is no default channel\&. .TP \fB::picoirc::send\fR \fIcontext\fR \fIline\fR This command is where all raw output to the server is handled\&. The default action is to write the \fIline\fR to the irc socket\&. However, before this happens the callback is called with "debug write"\&. This Index: idoc/man/files/modules/javascript/javascript.n ================================================================== --- idoc/man/files/modules/javascript/javascript.n +++ idoc/man/files/modules/javascript/javascript.n @@ -360,19 +360,11 @@ bugs and other problems\&. Please report such in the category \fIjavascript\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" html, ncgi .SH KEYWORDS checkbox, html, javascript, selectionbox, submitbutton .SH CATEGORY CGI programming Index: idoc/man/files/modules/jpeg/jpeg.n ================================================================== --- idoc/man/files/modules/jpeg/jpeg.n +++ idoc/man/files/modules/jpeg/jpeg.n @@ -471,18 +471,10 @@ bugs and other problems\&. Please report such in the category \fIjpeg\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS comment, exif, image, jfif, jpeg, thumbnail .SH CATEGORY File formats .SH COPYRIGHT Index: idoc/man/files/modules/json/json.n ================================================================== --- idoc/man/files/modules/json/json.n +++ idoc/man/files/modules/json/json.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'json\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2006 ActiveState Software Inc\&. '\" Copyright (c) 2009 Thomas Maeder, Glue Software Engineering AG '\" -.TH "json" n 1\&.3\&.4 tcllib "JSON" +.TH "json" n 1\&.3\&.3 tcllib "JSON" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -275,11 +275,11 @@ .SH NAME json \- JSON parser .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBjson ?1\&.3\&.4?\fR +package require \fBjson ?1\&.3\&.3?\fR .sp \fB::json::json2dict\fR \fItxt\fR .sp \fB::json::many-json2dict\fR \fItxt\fR ?\fImax\fR? .sp @@ -366,27 +366,17 @@ } => Image {IDs {116 943 234 38793} Thumbnail {Width 100 Height 125 Url http://www\&.example\&.com/image/481989943} Width 800 Height 600 Title {View from 15th Floor}} .CE -.SH RELATED -To write json, instead of parsing it, see package \fBjson::write\fR\&. .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIjson\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS data exchange, exchange format, javascript, json .SH CATEGORY CGI programming .SH COPYRIGHT Index: idoc/man/files/modules/json/json_write.n ================================================================== --- idoc/man/files/modules/json/json_write.n +++ idoc/man/files/modules/json/json_write.n @@ -342,31 +342,21 @@ This method takes a series of key/value arguments, the values already formatted for JSON, and returns them as a properly formatted JSON object as its result, with the keys formatted as JSON strings\&. .PP .PP -.SH RELATED -To parse json, instead of writing it, see package \fBjson\fR\&. .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIjson\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS data exchange, exchange format, javascript, json .SH CATEGORY CGI programming .SH COPYRIGHT .nf Copyright (c) 2009-2013 Andreas Kupries .fi Index: idoc/man/files/modules/lambda/lambda.n ================================================================== --- idoc/man/files/modules/lambda/lambda.n +++ idoc/man/files/modules/lambda/lambda.n @@ -352,18 +352,10 @@ bugs and other problems\&. Please report such in the category \fIlambda\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" apply(n), proc(n) .SH KEYWORDS anonymous procedure, callback, command prefix, currying, lambda, partial application, proc .SH CATEGORY DELETED idoc/man/files/modules/lazyset/lazyset.n Index: idoc/man/files/modules/lazyset/lazyset.n ================================================================== --- idoc/man/files/modules/lazyset/lazyset.n +++ idoc/man/files/modules/lazyset/lazyset.n @@ -1,369 +0,0 @@ -'\" -'\" Generated from file 'lazyset\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2018 Roy Keene -'\" -.TH "lazyset" n 1 tcllib "Lazy evaluation for variables and arrays" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -lazyset \- Lazy evaluation -.SH SYNOPSIS -package require \fBTcl 8\&.5\fR -.sp -package require \fBlazyset ?1?\fR -.sp -\fB::lazyset::variable\fR ?\fI-array boolean\fR? ?\fI-appendArgs boolean\fR? \fIvariableName\fR \fIcommandPrefix\fR -.sp -.BE -.SH DESCRIPTION -.PP -The \fBlazyset\fR package provides a mechanism for deferring execution -of code until a specific variable or any index of an array is referenced\&. -.SH COMMANDS -.TP -\fB::lazyset::variable\fR ?\fI-array boolean\fR? ?\fI-appendArgs boolean\fR? \fIvariableName\fR \fIcommandPrefix\fR -Arrange for the code specified as \fIcommandPrefix\fR to be executed when -the variable whose name is specified by \fIvariableName\fR is read for -the first time\&. -If the optional argument \fI-array boolean\fR is specified as true, -then the variable specified as \fIvariableName\fR is treated as an -array and attempting to read any index of the array causes that -index to be set by the \fIcommandPrefix\fR as they are read\&. -If the optional argument \fI-appendArgs boolean\fR is specified as -false, then the variable name and subnames are not appended to the -\fIcommandPrefix\fR before it is evaluated\&. If the argument -\fI-appendArgs boolean\fR is not specified or is specified as true -then 1 or 2 additional arguments are appended to the \fIcommandPrefix\fR\&. -If \fI-array boolean\fR is specified as true, then 2 arguments are -appended corresponding to the name of the variable and the index, -otherwise 1 argument is appended containing the name of variable\&. -The \fIcommandPrefix\fR code is run in the same scope as the variable -is read\&. -.PP -.SH EXAMPLES -.CS - - - ::lazyset::variable page {apply {{name} { - package require http - set token [http::geturl http://www\&.tcl\&.tk/] - set data [http::data $token] - return $data - }}} - - puts $page - -.CE -.CS - - - ::lazyset::variable -array true page {apply {{name index} { - package require http - set token [http::geturl $index] - set data [http::data $token] - return $data - }}} - - puts $page(http://www\&.tcl\&.tk/) - -.CE -.CS - - - ::lazyset::variable -appendArgs false simple { - return -level 0 42 - } - - puts $simple - -.CE -.SH AUTHORS -Roy Keene -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIutility\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH CATEGORY -Utility -.SH COPYRIGHT -.nf -Copyright (c) 2018 Roy Keene - -.fi Index: idoc/man/files/modules/ldap/ldap.n ================================================================== --- idoc/man/files/modules/ldap/ldap.n +++ idoc/man/files/modules/ldap/ldap.n @@ -2,11 +2,11 @@ '\" Generated from file 'ldap\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004 Andreas Kupries '\" Copyright (c) 2004 Jochen Loewer '\" Copyright (c) 2006 Michael Schlenker '\" -.TH "ldap" n 1\&.10 tcllib "LDAP client" +.TH "ldap" n 1\&.6\&.9 tcllib "LDAP client" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,29 +274,21 @@ .. .BS .SH NAME ldap \- LDAP client .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBldap ?1\&.10?\fR +package require \fBldap ?1\&.8?\fR .sp \fB::ldap::connect\fR \fIhost\fR ?\fIport\fR? .sp -\fB::ldap::tlsoptions\fR \fBreset\fR -.sp -\fB::ldap::tlsoptions\fR ?\fIopt1\fR \fIval1\fR? ?\fIopt2\fR \fIval2\fR? \&.\&.\&. -.sp \fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? .sp -\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR? -.sp \fB::ldap::disconnect\fR \fIhandle\fR .sp -\fB::ldap::starttls\fR \fIhandle\fR -.sp -\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR? +\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? .sp \fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? .sp \fB::ldap::bindSASL\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? .sp @@ -330,12 +322,10 @@ .sp \fB::ldap::info\fR \fBconnections\fR .sp \fB::ldap::info\fR \fBtls\fR \fIhandle\fR .sp -\fB::ldap::info\fR \fBtlsstatus\fR \fIhandle\fR -.sp \fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR .sp \fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR .sp \fB::ldap::info\fR \fBextensions\fR \fIextensions\fR @@ -351,13 +341,12 @@ It works by opening the standard (or secure) LDAP socket on the server, and then providing a Tcl API to access the LDAP protocol commands\&. All server errors are returned as Tcl errors (thrown) which must be caught with the Tcl \fBcatch\fR command\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBLDAPS\fR connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -372,11 +361,12 @@ Such a patch may be as simple as generally activating \fBtls1\fR support, as shown in the example below\&. .CS - ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol + package require tls + tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol \&.\&.\&. your own application code \&.\&.\&. .CE .SH COMMANDS @@ -388,137 +378,29 @@ specified it will default to \fB389\fR\&. .sp The command blocks until the connection has been established, or establishment definitely failed\&. .TP -\fB::ldap::tlsoptions\fR \fBreset\fR -This command resets TLS options to default values\&. It returns the -set of options\&. -Using this command is incompatible with the obsolete -form of \fB::ldap::secure_connect\fR and \fB::ldap_starttls\fR\&. -.TP -\fB::ldap::tlsoptions\fR ?\fIopt1\fR \fIval1\fR? ?\fIopt2\fR \fIval2\fR? \&.\&.\&. -This commands adds one or more options to some value, and may be used -more than one time in order to add options in several steps\&. A complete -description of options may be found in the \fBtls\fR package -documentation\&. Valid options and values are: -.RS -.TP -\fB-cadir\fR directory -Provide the directory containing the CA certificates\&. -No default\&. -.TP -\fB-cafile\fR file -Provide the CA file\&. -No default\&. -.TP -\fB-cipher\fR string -Provide the cipher suites to use\&. -No default\&. -.TP -\fB-dhparams\fR file -Provide a Diffie-Hellman parameters file\&. -No default\&. -.TP -\fB-request\fR boolean -Request a certificate from peer during SSL handshake\&. -Default: true\&. -.TP -\fB-require\fR boolean -Require a valid certificate from peer during SSL handshake\&. If this is -set to true then -request must also be set to true\&. -Default: false -.TP -\fB-servername\fR host -Only available if the OpenSSL library the TLS package is linked against -supports the TLS hostname extension for 'Server Name Indication' -(SNI)\&. Use to name the logical host we are talking to and expecting a -certificate for\&. -No default\&. -.TP -\fB-ssl2\fR bool -Enable use of SSL v2\&. -Default: false -.TP -\fB-ssl3\fR bool -Enable use of SSL v3\&. -Default: false -.TP -\fB-tls1\fR bool -Enable use of TLS v1 -Default: true -.TP -\fB-tls1\&.1\fR bool -Enable use of TLS v1\&.1 -Default: true -.TP -\fB-tls1\&.2\fR bool -Enable use of TLS v1\&.2 -Default: true -.RE -.sp -This command returns the current set of TLS options and values\&. -In particular, one may use this command without any arguments to get -the current set of options\&. -.sp -Using this command is incompatible with the obsolete -form of \fB::ldap::secure_connect\fR and \fB::ldap_starttls\fR -(see below)\&. -.TP \fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? Like \fB::ldap::connect\fR, except that the created connection is secured by SSL\&. The port defaults to \fB636\fR\&. This command depends on the availability of the package \fBTLS\fR, which is a SSL binding for Tcl\&. If \fBTLS\fR is not available, then this command will fail\&. .sp -TLS options are specified with \fB::ldap::tlsoptions\fR\&. -.sp The command blocks until the connection has been established, or establishment definitely failed\&. .TP -\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR? -Note: this form of the command is deprecated, since TLS options had -to be specified with a combination of parameters to this command -(\fIverify_cert\fR and \fIsni_servername\fR) and arguments to \fB::tls::init\fR -(from package \fBtls\fR) for example to setup defaults for trusted -certificates\&. Prefer the above form (without the \fIverify_cert\fR and -\fIsni_servername\fR parameters) and set TLS options with -\fB::ldap::tlsoptions\fR\&. -.sp -If \fIverify_cert\fR is set to 1, the default, this checks the server certificate against -the known hosts\&. If \fIsni_servername\fR is set, the given hostname is used as the -hostname for Server Name Indication in the TLS handshake\&. -.sp -Use \fB::tls::init\fR to setup defaults for trusted certificates\&. -.sp -TLS supports different protocol levels\&. In common use are the versions 1\&.0, 1\&.1 and 1\&.2\&. -By default all those versions are offered\&. If you need to modify the acceptable -protocols, you can change the ::ldap::tlsProtocols list (deprecated)\&. -.TP \fB::ldap::disconnect\fR \fIhandle\fR Closes the ldap connection refered to by the token \fIhandle\fR\&. Returns the empty string as its result\&. .TP -\fB::ldap::starttls\fR \fIhandle\fR -Start TLS negotiation on the connection denoted by \fIhandle\fR, -with TLS parameters set with \fB::ldap::tlsoptions\fR\&. -.TP -\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR? -Note: this form of the command is deprecated, since TLS options had -to be specified with a combination of parameters to this command -(\fIcafile\fR, \fIcertfile\fR, \fIkeyfile\fR, \fIverify_cert\fR -and \fIsni_servername\fR) and arguments to \fB::tls::init\fR -(from package \fBtls\fR)\&. -Prefer the above form (without specific TLS arguments) -and set TLS options with \fB::ldap::tlsoptions\fR\&. -.sp +\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? Start TLS negotiation on the connection denoted by \fIhandle\fR\&. -You need to set at least the \fIcafile\fR argument to a file with trusted certificates, if \fIverify_cert\fR is 1, which is the default\&. -The \fIsni_servername\fR can be used to signal a different hostname during the TLS handshake\&. -The announced protocols are determined in the same way as \fB::ldap::secure_connect\fR\&. -You can specify a TLS client certificate with the \fIcertfile\fR and \fIkeyfile\fR options\&. +This is currently experimental and subject to change, more control over the TLS details +will probably be exposed later, to allow users to fine tune the negotiation according +to their security needs\&. .TP \fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR? This command authenticates the ldap connection refered to by the token in \fIhandle\fR, with a user name and associated password\&. It blocks until a response from the ldap server arrives\&. Its result is the empty @@ -744,10 +626,11 @@ attributes from the server\&. The command blocks until the operation has completed\&. Its result is the empty string\&. .TP \fB::ldap::modifyDN\fR \fIhandle\fR \fIdn\fR \fInewrdn\fR ?\fIdeleteOld\fR? ?\fInewSuperior\fR? +] This command moves or copies the object specified by \fIdn\fR to a new location in the tree of object\&. This location is specified by \fInewrdn\fR, a \fIrelative\fR designation, or by \fInewrdn\fR and \fInewSuperior\fR, a \fIabsolute\fR designation\&. The optional argument \fIdeleteOld\fR defaults to \fBtrue\fR, @@ -776,16 +659,10 @@ .TP \fB::ldap::info\fR \fBtls\fR \fIhandle\fR This command returns 1 if the ldap connection \fIhandle\fR used TLS/SSL for connection via \fBldap::secure_connect\fR or completed \fBldap::starttls\fR, 0 otherwise\&. .TP -\fB::ldap::info\fR \fBtlsstatus\fR \fIhandle\fR -This command returns the current security status of an TLS secured -channel\&. The result is a list of key-value pairs describing the connected -peer (see the \fBTLS\fR package documentation for the returned values)\&. -If the connection is not secured with TLS, an empty list is returned\&. -.TP \fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR Return the supported SASL mechanisms advertised by the server\&. Only valid in a bound state (anonymous or other)\&. .TP \fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR @@ -862,11 +739,11 @@ ldap::unbind $handle ldap::disconnect $handle .CE .PP -And another example, a simple query, and processing the +And a another example, a simple query, and processing the results\&. .PP .CS @@ -911,18 +788,10 @@ bugs and other problems\&. Please report such in the category \fIldap\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc 4511, x\&.500 .SH CATEGORY Networking .SH COPYRIGHT Index: idoc/man/files/modules/ldap/ldapx.n ================================================================== --- idoc/man/files/modules/ldap/ldapx.n +++ idoc/man/files/modules/ldap/ldapx.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'ldapx\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2006-2018 Pierre David +'\" Copyright (c) 2006 Pierre David '\" -.TH "ldapx" n 1\&.2 tcllib "LDAP extended object interface" +.TH "ldapx" n 0\&.2\&.5 tcllib "LDAP extended object interface" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,13 +272,13 @@ .. .BS .SH NAME ldapx \- LDAP extended object interface .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBldapx ?1\&.2?\fR +package require \fBldapx ?1\&.0?\fR .sp \fIe\fR \fBreset\fR .sp \fIe\fR \fBdn\fR ?\fInewdn\fR? .sp @@ -324,11 +324,11 @@ .sp \fIce\fR \fBdiff\fR \fInew\fR ?\fIold\fR? .sp \fIla\fR \fBerror\fR ?\fInewmsg\fR? .sp -\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? ?\fIstarttls\fR? +\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? .sp \fIla\fR \fBdisconnect\fR .sp \fIla\fR \fBtraverse\fR \fIbase\fR \fIfilter\fR \fIattrs\fR \fIentry\fR \fIbody\fR .sp @@ -658,30 +658,11 @@ the last method of the \fBldap\fR class (this string is modified in nearly all methods)\&. The \fBerror\fR method may be used to fetch this message\&. .PP .SS "LDAP OPTIONS" -Options are configured on \fBldap\fR instances using the \fBconfigure\fR -method\&. -.PP -The first option is used for TLS parameters: -.TP -\fB-tlsoptions\fR \fIlist\fR -Specify the set of TLS options to use when connecting to the -LDAP server (see the \fBconnect\fR method)\&. For the list of -valid options, see the \fBLDAP\fR package documentation\&. -.sp -The default is \fB-request 1 -require 1 -ssl2 no -ssl3 no -tls1 yes -tls1\&.1 yes -tls1\&.2 yes\fR\&. -.sp -Example: -.sp -.CS - -$l configure -tlsoptions {-request yes -require yes} -.CE -.PP -A set of options of the \fBldap\fR class is used during +A first set of options of the \fBldap\fR class is used during search operations (methods \fBtraverse\fR, \fBsearch\fR and \fBread\fR, see below)\&. .TP \fB-scope\fR \fBbase\fR|\fBone\fR|\fBsub\fR Specify the scope of the LDAP search to be one of @@ -744,26 +725,17 @@ This method returns the error message that occurred in the last call to a \fBldap\fR class method\&. If the optional argument \fInewmsg\fR is supplied, it becomes the last error message\&. .TP -\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? ?\fIstarttls\fR? +\fIla\fR \fBconnect\fR \fIurl\fR ?\fIbinddn\fR? ?\fIbindpw\fR? This method connects to the LDAP server using given URL (which can be of the form \fIldap://host:port\fR or \fIldaps://host:port\fR)\&. If an optional \fIbinddn\fR argument is given together with the \fIbindpw\fR argument, the \fBconnect\fR binds to the LDAP server using the specified DN and password\&. -.sp -If the \fIstarttls\fR argument is given a true value (\fB1\fR, -\fByes\fR, etc\&.) and the URL uses the \fIldap://\fR scheme, -a TLS negotiation is initiated with the newly created connection, -before LDAP binding\&. -Default value: \fBno\fR\&. -.sp -This method returns 1 if connection was successful, or 0 if an -error occurred (use the \fBerror\fR method to get the message)\&. .TP \fIla\fR \fBdisconnect\fR This method disconnects (and unbinds, if necessary) from the LDAP server\&. .TP @@ -812,17 +784,16 @@ package require ldapx # - # Connects to the LDAP directory using StartTLS + # Connects to the LDAP directory # ::ldapx::ldap create l - l configure -tlsoptions {-cadir /etc/ssl/certs -request yes -require yes} set url "ldap://server\&.mycomp\&.com" - if {! [l connect $url "cn=admin,o=mycomp" "mypasswd" yes]} then { + if {! [l connect $url "cn=admin,o=mycomp" "mypasswd"]} then { puts stderr "error: [l error]" exit 1 } # @@ -856,11 +827,10 @@ puts stderr "error: [l error]" exit 1 } $e destroy } - c destroy l disconnect l destroy .CE @@ -1000,22 +970,14 @@ bugs and other problems\&. Please report such in the category \fIldap\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS directory access, internet, ldap, ldap client, ldif, protocol, rfc 2251, rfc 2849 .SH CATEGORY Networking .SH COPYRIGHT .nf -Copyright (c) 2006-2018 Pierre David +Copyright (c) 2006 Pierre David .fi Index: idoc/man/files/modules/log/log.n ================================================================== --- idoc/man/files/modules/log/log.n +++ idoc/man/files/modules/log/log.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'log\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2001-2009 Andreas Kupries '\" -.TH "log" n 1\&.4 tcllib "Logging facility" +.TH "log" n 1\&.3 tcllib "Logging facility" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME log \- Procedures to log messages of libraries and applications\&. .SH SYNOPSIS package require \fBTcl 8\fR .sp -package require \fBlog ?1\&.4?\fR +package require \fBlog ?1\&.3?\fR .sp \fB::log::levels\fR .sp \fB::log::lv2longform\fR \fIlevel\fR .sp @@ -314,12 +314,10 @@ .sp \fB::log::logarray\fR \fIlevel\fR \fIarrayvar\fR ?\fIpattern\fR? .sp \fB::log::loghex\fR \fIlevel\fR \fItext\fR \fIdata\fR .sp -\fB::log::logsubst\fR \fIlevel\fR \fImsg\fR -.sp \fB::log::logMsg\fR \fItext\fR .sp \fB::log::logError\fR \fItext\fR .sp \fB::log::Puts\fR \fIlevel\fR \fItext\fR @@ -431,14 +429,16 @@ signals that level1 is of less priority than level2\&. 0 signals that both levels have the same priority\&. 1 signals that level1 has higher priority than level2\&. .TP \fB::log::lvSuppress\fR \fIlevel\fR {\fIsuppress\fR 1} +] (Un)suppresses the output of messages having the specified level\&. Unique abbreviations for the level are allowed here too\&. .TP \fB::log::lvSuppressLE\fR \fIlevel\fR {\fIsuppress\fR 1} +] (Un)suppresses the output of messages having the specified level or one of lesser priority\&. Unique abbreviations for the level are allowed here too\&. .TP \fB::log::lvIsSuppressed\fR \fIlevel\fR @@ -505,22 +505,10 @@ .TP \fB::log::loghex\fR \fIlevel\fR \fItext\fR \fIdata\fR Like \fB::log::log\fR, but assumes that \fIdata\fR contains binary data\&. It converts this into a mixed hex/ascii representation before writing them to the log\&. -.TP -\fB::log::logsubst\fR \fIlevel\fR \fImsg\fR -Like \fB::log::log\fR, but \fImsg\fR may contain substitutions and variable references, which are evaluated in the caller scope first\&. -The purpose of this command is to avoid overhead in the non-logging case, if the log message building is expensive\&. -Any substitution errors raise an error in the command execution\&. -The following example shows an xml text representation, which is only generated in debug mode: -.CS - - - log::logsubst debug {XML of node $node is '[$node toXml]'} - -.CE .TP \fB::log::logMsg\fR \fItext\fR Convenience wrapper around \fB::log::log\fR\&. Equivalent to \fB::log::log info text\fR\&. .TP @@ -563,22 +551,14 @@ bugs and other problems\&. Please report such in the category \fIlog\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS log, log level, message, message level .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2001-2009 Andreas Kupries .fi Index: idoc/man/files/modules/log/logger.n ================================================================== --- idoc/man/files/modules/log/logger.n +++ idoc/man/files/modules/log/logger.n @@ -710,17 +710,9 @@ bugs and other problems\&. Please report such in the category \fIlogger\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS log, log level, logger, service .SH CATEGORY Programming tools Index: idoc/man/files/modules/log/loggerAppender.n ================================================================== --- idoc/man/files/modules/log/loggerAppender.n +++ idoc/man/files/modules/log/loggerAppender.n @@ -319,22 +319,14 @@ bugs and other problems\&. Please report such in the category \fIlogger\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS appender, logger .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Aamer Akhter .fi Index: idoc/man/files/modules/log/loggerUtils.n ================================================================== --- idoc/man/files/modules/log/loggerUtils.n +++ idoc/man/files/modules/log/loggerUtils.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'loggerUtils\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2005 Aamer Akhter '\" -.TH "logger::utils" n 1\&.3\&.1 tcllib "Object Oriented logging facility" +.TH "logger::utils" n 1\&.3 tcllib "Object Oriented logging facility" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME logger::utils \- Utilities for logger .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBlogger::utils ?1\&.3\&.1?\fR +package require \fBlogger::utils ?1\&.3?\fR .sp \fB::logger::utils::createFormatCmd\fR \fIformatString\fR .sp \fB::logger::utils::createLogProc\fR \fB-procName\fR \fIprocName\fR ?\fIoptions\fR\&.\&.\&.? .sp @@ -417,22 +417,14 @@ bugs and other problems\&. Please report such in the category \fIlogger\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS appender, logger .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Aamer Akhter .fi Index: idoc/man/files/modules/map/map_geocode_nominatim.n ================================================================== --- idoc/man/files/modules/map/map_geocode_nominatim.n +++ idoc/man/files/modules/map/map_geocode_nominatim.n Index: idoc/man/files/modules/map/map_slippy.n ================================================================== --- idoc/man/files/modules/map/map_slippy.n +++ idoc/man/files/modules/map/map_slippy.n Index: idoc/man/files/modules/map/map_slippy_cache.n ================================================================== --- idoc/man/files/modules/map/map_slippy_cache.n +++ idoc/man/files/modules/map/map_slippy_cache.n Index: idoc/man/files/modules/map/map_slippy_fetcher.n ================================================================== --- idoc/man/files/modules/map/map_slippy_fetcher.n +++ idoc/man/files/modules/map/map_slippy_fetcher.n Index: idoc/man/files/modules/mapproj/mapproj.n ================================================================== --- idoc/man/files/modules/mapproj/mapproj.n +++ idoc/man/files/modules/mapproj/mapproj.n Index: idoc/man/files/modules/markdown/markdown.n ================================================================== --- idoc/man/files/modules/markdown/markdown.n +++ idoc/man/files/modules/markdown/markdown.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'markdown\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "markdown" n 1\&.2 tcllib "Markdown to HTML Converter" +.TH "markdown" n 1\&.0 tcllib "Markdown to HTML Converter" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,68 +273,27 @@ .SH NAME markdown \- Converts Markdown text to HTML .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBMarkdown 1\&.2\fR -.sp package require \fBtextutil ?0\&.8?\fR .sp \fB::Markdown::convert\fR \fImarkdown\fR .sp -\fB::Markdown::register\fR \fIlangspec\fR \fIconverter\fR -.sp -\fB::Markdown::get_lang_counter\fR -.sp -\fB::Markdown::reset_lang_counter\fR -.sp .BE .SH DESCRIPTION The package \fBMarkdown\fR provides a command to convert Markdown annotated text into HMTL\&. .TP \fB::Markdown::convert\fR \fImarkdown\fR This command takes in a block of Markdown text, and returns a block of HTML\&. -.sp -The converter supports two types of syntax highlighting for -fenced code blocks: highlighting via a registered converter -(see \fB::Markdown::register\fR), or pure JavaScript highlighting, -e\&.g\&. via "highlight\&.js", where the language specifier used in the -markup is set as CSS class of the "code" element in the returned markup\&. -.TP -\fB::Markdown::register\fR \fIlangspec\fR \fIconverter\fR -Register a language specific converter for prettifying a code block -(e\&.g\&. syntax highlighting)\&. Markdown supports fenced code blocks with -an optional language specifier (e\&.g\&. "tcl")\&. When the markdown parser -processes such a code block and a converter for the specified langspec -is registered, the converter is called with the raw code block as -argument\&. The converter is supposed to return the markup of the code -block as result\&. The specified converter can be an arbitrary Tcl -command, the raw text block is added as last argument upon invocation\&. -.TP -\fB::Markdown::get_lang_counter\fR -Return a dict of language specifier and number of occurrences in -fenced code blocks\&. This function can be used e\&.g\&. to detect, whether -some CSS or JavaScript headers should be included for rendering -without the need of postprocessing the rendered result\&. -.TP -\fB::Markdown::reset_lang_counter\fR -Reset the language counters\&. .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH CATEGORY Text processing Index: idoc/man/files/modules/math/bigfloat.n ================================================================== --- idoc/man/files/modules/math/bigfloat.n +++ idoc/man/files/modules/math/bigfloat.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'bigfloat\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004-2008, by Stephane Arnold '\" -.TH "math::bigfloat" n 2\&.0\&.3 tcllib "Tcl Math Library" +.TH "math::bigfloat" n 2\&.0\&.1 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME math::bigfloat \- Arbitrary precision floating-point numbers .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBmath::bigfloat ?2\&.0\&.3?\fR +package require \fBmath::bigfloat ?2\&.0\&.1?\fR .sp \fBfromstr\fR \fInumber\fR ?\fItrailingZeros\fR? .sp \fBtostr\fR ?\fB-nosci\fR? \fInumber\fR .sp @@ -807,22 +807,14 @@ bugs and other problems\&. Please report such in the category \fImath :: bignum :: float\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS computations, floating-point, interval, math, multiprecision, tcl .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004-2008, by Stephane Arnold .fi Index: idoc/man/files/modules/math/bignum.n ================================================================== --- idoc/man/files/modules/math/bignum.n +++ idoc/man/files/modules/math/bignum.n @@ -557,18 +557,10 @@ bugs and other problems\&. Please report such in the category \fImath :: bignum\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS bignums, math, multiprecision, tcl .SH CATEGORY Mathematics .SH COPYRIGHT Index: idoc/man/files/modules/math/calculus.n ================================================================== --- idoc/man/files/modules/math/calculus.n +++ idoc/man/files/modules/math/calculus.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'calculus\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2002,2003,2004 Arjen Markus '\" -.TH "math::calculus" n 0\&.8\&.2 tcllib "Tcl Math Library" +.TH "math::calculus" n 0\&.8\&.1 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME math::calculus \- Integration and ordinary differential equations .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBmath::calculus 0\&.8\&.2\fR +package require \fBmath::calculus 0\&.8\&.1\fR .sp \fB::math::calculus::integral\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIfunc\fR .sp \fB::math::calculus::integralExpr\fR \fIbegin\fR \fIend\fR \fInosteps\fR \fIexpression\fR .sp @@ -779,18 +779,10 @@ bugs and other problems\&. Please report such in the category \fImath :: calculus\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" romberg .SH KEYWORDS calculus, differential equations, integration, math, roots .SH CATEGORY DELETED idoc/man/files/modules/math/changepoint.n Index: idoc/man/files/modules/math/changepoint.n ================================================================== --- idoc/man/files/modules/math/changepoint.n +++ idoc/man/files/modules/math/changepoint.n @@ -1,414 +0,0 @@ -'\" -'\" Generated from file 'changepoint\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2020 by Arjen Markus -'\" -.TH "math::changepoint" n 0\&.1 tcllib "Tcl Math Library" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::changepoint \- Change point detection methods -.SH SYNOPSIS -package require \fBTcl ?8\&.5?\fR -.sp -package require \fBmath::statistics \fR -.sp -package require \fBmath::changepoint ?0\&.1?\fR -.sp -\fB::math::changepoint::cusum-detect\fR \fIdata\fR ?args? -.sp -\fB::math::changepoint::cusum-online\fR ?args? -.sp -\fB$cusumObj\fR examine \fIvalue\fR -.sp -\fB$cusumObj\fR reset -.sp -\fB::math::changepoint::binary-segmentation\fR \fIdata\fR ?args? -.sp -.BE -.SH DESCRIPTION -.PP -The \fBmath::changepoint\fR package implements a number of well-known methods -to determine if a series of data contains a shift in the mean or not\&. Note that -these methods only indicate if a shift in the mean is probably\&. Due to the stochastic -nature of the data that will be analysed, false positives are possible\&. -The CUSUM method is implemented in both an "offline" and an "online" version, so that -it can be used either for a complete data series or for detecting changes in data that -come in one by one\&. The implementation has been based on these websites mostly: -.IP \(bu -\fIhttps://www\&.itl\&.nist\&.gov/div898/handbook/pmc/section3/pmc323\&.htm\fR -.IP \(bu -\fIhttps://en\&.wikipedia\&.org/wiki/CUSUM\fR -.PP -Basically, the deviation of the data from a given target value is accumulated and when -the total deviation becomes too large, a change point is reported\&. -A second method, binary segmentation, is implemented only as an "offline" method, as it -needs to examine the data series as a whole\&. In the variant contained here the following -ideas have been used: -.IP \(bu -The segments in which the data series may be separated shold not be too short, otherwise -the ultimate result could be segments of only one data point long\&. So a minimum length is -used\&. -.IP \(bu -To make the segmentation worthwhile there should be a minimum gain in reducing the cost -function (the sum of the squared deviations from the mean for each segment)\&. -.PP -This may not be in agreement with the descriptions of the method found in various -publications, but it is simple to understand and intuitive\&. -One publication that provides more information on the method in general is -"Selective review of offline change point detection methods" by Truong et al\&. \fIhttps://arxiv\&.org/abs/1801\&.00718\fR\&. -.SH PROCEDURES -The package defines the following public procedures: -.TP -\fB::math::changepoint::cusum-detect\fR \fIdata\fR ?args? -Examine a given data series and return the location of the first change (if any) -.RS -.TP -double \fIdata\fR -Series of data to be examined -.TP -list \fIargs\fR -Optional list of key-value pairs: -.RS -.TP -\fB-target\fR \fIvalue\fR -The target (or mean) for the time series -.TP -\fB-tolerance\fR \fIvalue\fR -The tolerated standard deviation -.TP -\fB-kfactor\fR \fIvalue\fR -The factor by which to multiply the standard deviation (defaults to 0\&.5, typically between 0\&.5 and 1\&.0) -.TP -\fB-hfactor\fR \fIvalue\fR -The factor determining the limits betweem which the "cusum" statistic is accepted (typicaly 3\&.0-5\&.0, default 4\&.0) -.RE -.RE -.TP -\fB::math::changepoint::cusum-online\fR ?args? -Class to examine data passed in against expected properties\&. At least the keywords \fI-target\fR and \fI-tolerance\fR must be given\&. -.RS -.TP -list \fIargs\fR -List of key-value pairs: -.RS -.TP -\fB-target\fR \fIvalue\fR -The target (or mean) for the time series -.TP -\fB-tolerance\fR \fIvalue\fR -The tolerated standard deviation -.TP -\fB-kfactor\fR \fIvalue\fR -The factor by which to multiply the standard deviation (defaults to 0\&.5, typically between 0\&.5 and 1\&.0) -.TP -\fB-hfactor\fR \fIvalue\fR -The factor determining the limits betweem which the "cusum" statistic is accepted (typicaly 3\&.0-5\&.0, default 4\&.0) -.RE -.RE -.TP -\fB$cusumObj\fR examine \fIvalue\fR -Pass a value to the \fIcusum-online\fR object and examine it\&. If, with this new value, the cumulative sum remains within the bounds, -zero (0) is returned, otherwise one (1) is returned\&. -.RS -.TP -double \fIvalue\fR -The new value -.RE -.TP -\fB$cusumObj\fR reset -Reset the cumulative sum, so that the examination can start afresh\&. -.TP -\fB::math::changepoint::binary-segmentation\fR \fIdata\fR ?args? -Apply the binary segmentation method recursively to find change points\&. Returns a list of indices of potential change points -.RS -.TP -list \fIdata\fR -Data to be examined -.TP -list \fIargs\fR -Optional key-value pairs: -.RS -.TP -\fB-minlength\fR \fInumber\fR -Minimum number of points in each segment (default: 5) -.TP -\fB-threshold\fR \fIvalue\fR -Factor applied to the standard deviation functioning as a threshold for accepting the change in cost function as an improvement (default: 1\&.0) -.RE -.RE -.PP -.SH KEYWORDS -control, statistics -.SH CATEGORY -Mathematics -.SH COPYRIGHT -.nf -Copyright (c) 2020 by Arjen Markus - -.fi Index: idoc/man/files/modules/math/combinatorics.n ================================================================== --- idoc/man/files/modules/math/combinatorics.n +++ idoc/man/files/modules/math/combinatorics.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'combinatorics\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "math::combinatorics" n 2\&.0 tcllib "Tcl Math Library" +.TH "math::combinatorics" n 1\&.2\&.3 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -275,76 +275,23 @@ .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp package require \fBmath ?1\&.2\&.3?\fR .sp -package require \fBTcl 8\&.6\fR -.sp -package require \fBmath::combinatorics ?2\&.0?\fR -.sp \fB::math::ln_Gamma\fR \fIz\fR .sp \fB::math::factorial\fR \fIx\fR .sp \fB::math::choose\fR \fIn k\fR .sp \fB::math::Beta\fR \fIz w\fR .sp -\fB::math::combinatorics::permutations\fR \fIn\fR -.sp -\fB::math::combinatorics::variations\fR \fIn\fR \fIk\fR -.sp -\fB::math::combinatorics::combinations\fR \fIn\fR \fIk\fR -.sp -\fB::math::combinatorics::derangements\fR \fIn\fR -.sp -\fB::math::combinatorics::catalan\fR \fIn\fR -.sp -\fB::math::combinatorics::firstStirling\fR \fIn\fR \fIm\fR -.sp -\fB::math::combinatorics::secondStirling\fR \fIn\fR \fIm\fR -.sp -\fB::math::combinatorics::partitionP\fR \fIn\fR -.sp -\fB::math::combinatorics::list-permutations\fR \fIn\fR -.sp -\fB::math::combinatorics::list-variations\fR \fIn\fR \fIk\fR -.sp -\fB::math::combinatorics::list-combinations\fR \fIn\fR \fIk\fR -.sp -\fB::math::combinatorics::list-derangements\fR \fIn\fR -.sp -\fB::math::combinatorics::list-powerset\fR \fIn\fR -.sp -\fB::math::combinatorics::permutationObj\fR new/create NAME \fIn\fR -.sp -\fB$perm\fR next -.sp -\fB$perm\fR reset -.sp -\fB$perm\fR setElements \fIelements\fR -.sp -\fB$perm\fR setElements -.sp -\fB::math::combinatorics::combinationObj\fR new/create NAME \fIn\fR \fIk\fR -.sp -\fB$combin\fR next -.sp -\fB$combin\fR reset -.sp -\fB$combin\fR setElements \fIelements\fR -.sp -\fB$combin\fR setElements -.sp .BE .SH DESCRIPTION .PP The \fBmath\fR package contains implementations of several -functions useful in combinatorial problems\&. The \fBmath::combinatorics\fR -extends the collections based on features in Tcl 8\&.6\&. -Note: the meaning of the partitionP function, Catalan and Stirling numbers is explained on the -\fIMathWorld website\fR [http://mathworld\&.wolfram\&.com] +functions useful in combinatorial problems\&. .SH COMMANDS .TP \fB::math::ln_Gamma\fR \fIz\fR Returns the natural logarithm of the Gamma function for the argument \fIz\fR\&. @@ -417,207 +364,15 @@ .CE .IP Results are returned as a floating point number precise to better than nine significant digits provided that \fIw\fR and \fIz\fR are both at least 1\&. -.TP -\fB::math::combinatorics::permutations\fR \fIn\fR -Return the number of permutations of n items\&. The returned number -is always an integer, it is not limited by the range of 32-or 64-bits -integers using the arbitrary precision integers available in Tcl 8\&.5 and later\&. -.RS -.TP -int \fIn\fR -The number of items to be permuted\&. -.RE -.TP -\fB::math::combinatorics::variations\fR \fIn\fR \fIk\fR -Return the number of variations k items selected from the total of n items\&. -The order of the items is taken into account\&. -.RS -.TP -int \fIn\fR -The number of items to be selected from\&. -.TP -int \fIk\fR -The number of items to be selected in each variation\&. -.RE -.TP -\fB::math::combinatorics::combinations\fR \fIn\fR \fIk\fR -Return the number of combinations of k items selected from the total of n items\&. -The order of the items is not important\&. -.RS -.TP -int \fIn\fR -The number of items to be selected from\&. -.TP -int \fIk\fR -The number of items to be selected in each combination\&. -.RE -.TP -\fB::math::combinatorics::derangements\fR \fIn\fR -Return the number of derangements of n items\&. A derangement is a permutation -where each item is displaced from the original position\&. -.RS -.TP -int \fIn\fR -The number of items to be rearranged\&. -.RE -.TP -\fB::math::combinatorics::catalan\fR \fIn\fR -Return the n'th Catalan number\&. The number n is expected to be 1 or larger\&. -These numbers occur in various combinatorial problems\&. -.RS -.TP -int \fIn\fR -The index of the Catalan number -.RE -.TP -\fB::math::combinatorics::firstStirling\fR \fIn\fR \fIm\fR -Calculate a Stirling number of the first kind -(signed version, m cycles in a permutation of n items) -.RS -.TP -int \fIn\fR -Number of items -.TP -int \fIm\fR -Number of cycles -.RE -.TP -\fB::math::combinatorics::secondStirling\fR \fIn\fR \fIm\fR -Calculate a Stirling number of the second kind -(m non-empty subsets from n items) -.RS -.TP -int \fIn\fR -Number of items -.TP -int \fIm\fR -Number of subsets -.RE -.TP -\fB::math::combinatorics::partitionP\fR \fIn\fR -Calculate the number of ways an integer n can be written as the sum of positive integers\&. -.RS -.TP -int \fIn\fR -Number in question -.RE -.TP -\fB::math::combinatorics::list-permutations\fR \fIn\fR -Return the list of permutations of the numbers 0, \&.\&.\&., n-1\&. -.RS -.TP -int \fIn\fR -The number of items to be permuted\&. -.RE -.TP -\fB::math::combinatorics::list-variations\fR \fIn\fR \fIk\fR -Return the list of variations of k numbers selected from the numbers 0, \&.\&.\&., n-1\&. -The order of the items is taken into account\&. -.RS -.TP -int \fIn\fR -The number of items to be selected from\&. -.TP -int \fIk\fR -The number of items to be selected in each variation\&. -.RE -.TP -\fB::math::combinatorics::list-combinations\fR \fIn\fR \fIk\fR -Return the list of combinations of k numbers selected from the numbers 0, \&.\&.\&., n-1\&. -The order of the items is ignored\&. -.RS -.TP -int \fIn\fR -The number of items to be selected from\&. -.TP -int \fIk\fR -The number of items to be selected in each combination\&. -.RE -.TP -\fB::math::combinatorics::list-derangements\fR \fIn\fR -Return the list of derangements of the numbers 0, \&.\&.\&., n-1\&. -.RS -.TP -int \fIn\fR -The number of items to be rearranged\&. -.RE -.TP -\fB::math::combinatorics::list-powerset\fR \fIn\fR -Return the list of all subsets of the numbers 0, \&.\&.\&., n-1\&. -.RS -.TP -int \fIn\fR -The number of items to be rearranged\&. -.RE -.TP -\fB::math::combinatorics::permutationObj\fR new/create NAME \fIn\fR -Create a TclOO object for returning permutations one by one\&. If the last permutation -has been reached an empty list is returned\&. -.RS -.TP -int \fIn\fR -The number of items to be rearranged\&. -.RE -.TP -\fB$perm\fR next -Return the next permutation of n objects\&. -.TP -\fB$perm\fR reset -Reset the object, so that the command \fInext\fR returns the complete list again\&. -.TP -\fB$perm\fR setElements \fIelements\fR -Register a list of items to be permuted, using the \fInextElements\fR command\&. -.RS -.TP -list \fIelements\fR -The list of n items that will be permuted\&. -.RE -.TP -\fB$perm\fR setElements -Return the next permulation of the registered items\&. -.TP -\fB::math::combinatorics::combinationObj\fR new/create NAME \fIn\fR \fIk\fR -Create a TclOO object for returning combinations one by one\&. If the last combination -has been reached an empty list is returned\&. -.RS -.TP -int \fIn\fR -The number of items to be rearranged\&. -.RE -.TP -\fB$combin\fR next -Return the next combination of n objects\&. -.TP -\fB$combin\fR reset -Reset the object, so that the command \fInext\fR returns the complete list again\&. -.TP -\fB$combin\fR setElements \fIelements\fR -Register a list of items to be permuted, using the \fInextElements\fR command\&. -.RS -.TP -list \fIelements\fR -The list of n items that will be permuted\&. -.RE -.TP -\fB$combin\fR setElements -Return the next combination of the registered items\&. .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fImath\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH CATEGORY Mathematics Index: idoc/man/files/modules/math/constants.n ================================================================== --- idoc/man/files/modules/math/constants.n +++ idoc/man/files/modules/math/constants.n @@ -417,22 +417,14 @@ bugs and other problems\&. Please report such in the category \fImath :: constants\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS constants, degrees, e, math, pi, radians .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus .fi Index: idoc/man/files/modules/math/decimal.n ================================================================== --- idoc/man/files/modules/math/decimal.n +++ idoc/man/files/modules/math/decimal.n @@ -383,19 +383,19 @@ this man page for information about individual procedures\&. .PP .CS - package require math::decimal + package require decimal # Various operations on two numbers\&. # We first convert them to decimal format\&. set a [::math::decimal::fromstr 8\&.2] set b [::math::decimal::fromstr \&.2] - # Then we perform our operations\&. Here we add - set c [::math::decimal::+ $a $b] + # Then we perform our operations\&. Here we multiply + set c [::math::decimal::* $a $b] # Finally we convert back to string format for presentation to the user\&. puts [::math::decimal::tostr $c] ; # => will output 8\&.4 # Other examples @@ -403,12 +403,12 @@ # Subtraction set c [::math::decimal::- $a $b] puts [::math::decimal::tostr $c] ; # => will output 8\&.0 # Why bother using this instead of simply expr? - puts [expr {8\&.2 + \&.2}] ; # => will output 8\&.399999999999999 - puts [expr {8\&.2 - \&.2}] ; # => will output 7\&.999999999999999 + puts 8\&.399999999999999 ; # => will output 8\&.399999999999999 + puts 7\&.999999999999999 ; # => will output 7\&.999999999999999 # See http://speleotrove\&.com/decimal to learn more about why this happens\&. .CE .SH API .TP @@ -545,22 +545,14 @@ bugs and other problems\&. Please report such in the category \fIdecimal\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS decimal, math, tcl .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2011 Mark Alston .fi Index: idoc/man/files/modules/math/exact.n ================================================================== --- idoc/man/files/modules/math/exact.n +++ idoc/man/files/modules/math/exact.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'exact\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2015 Kevin B\&. Kenny '\" Redistribution permitted under the terms of the Open Publication License '\" -.TH "math::exact" n 1\&.0\&.1 tcllib "Tcl Math Library" +.TH "math::exact" n 1\&.0 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -277,11 +277,11 @@ .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp package require \fBgrammar::aycock 1\&.0\fR .sp -package require \fBmath::exact 1\&.0\&.1\fR +package require \fBmath::exact 1\&.0\fR .sp \fB::math::exact::exactexpr\fR \fIexpr\fR .sp \fInumber\fR \fBref\fR .sp DELETED idoc/man/files/modules/math/filtergen.n Index: idoc/man/files/modules/math/filtergen.n ================================================================== --- idoc/man/files/modules/math/filtergen.n +++ idoc/man/files/modules/math/filtergen.n @@ -1,369 +0,0 @@ -'\" -'\" Generated from file 'filtergen\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2020 by Arjen Markus -'\" -.TH "math::filters" n 0\&.1 tcllib "Tcl Math Library" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::filters \- Digital filters -.SH SYNOPSIS -package require \fBTcl ?8\&.5?\fR -.sp -package require \fBmath::filters ?0\&.1?\fR -.sp -\fB::math::filters::filterButterworth\fR \fIlowpass\fR \fIorder\fR \fIsamplefreq\fR \fIcutofffreq\fR -.sp -\fB::math::filters::filter\fR \fIcoeffs\fR \fIdata\fR -.sp -\fB::math::filters::filterObj\fR new \fIcoeffs\fR \fIyinit\fR -.sp -\fB$filterObj\fR filter \fIx\fR -.sp -\fB$filterObj\fR reset -.sp -.BE -.SH DESCRIPTION -.PP -The \fBmath::filters\fR package implements digital filters, -notably Butterworth low-pass and high-pass filters\&. The procedures -allow to filter an entire data series as well as filter data one -by one\&. -.SH PROCEDURES -The package defines the following public procedures: -.TP -\fB::math::filters::filterButterworth\fR \fIlowpass\fR \fIorder\fR \fIsamplefreq\fR \fIcutofffreq\fR -Determine the coefficients for a Butterworth filter of given order\&. The coefficients are returned as -a list of the x-coefficients, the y-coefficients and the scale\&. The formula is (n is the filter order): -.CS - - - n n - scale * y_k = sum x_(k-i) + sum y_(k-i) - i=0 i=1 - -.CE -.RS -.TP -bool \fIlowpass\fR -Generate a low-pass filter (1) or a high-pass filter (0) -.TP -integer \fIlowpass\fR -The order of the filter to be generated -.TP -double \fIsamplefreq\fR -Sampling frequency of the data series -.TP -double \fIcutofffreq\fR -Cut-off frequency for the filter -.RE -.TP -\fB::math::filters::filter\fR \fIcoeffs\fR \fIdata\fR -Filter the entire data series based on the filter coefficients\&. -.RS -.TP -list \fIcoeffs\fR -List of coefficients as generated by \fIfilterButterworth\fR (or in fact any similar list of coefficients) -.TP -list \fIdata\fR -Data to be filtered -.RE -.TP -\fB::math::filters::filterObj\fR new \fIcoeffs\fR \fIyinit\fR -Create a filter object\&. The initial x data are taken as zero\&. The initial y data can be prescribed\&. If they are not given, -they are taken as zero as well\&. -.RS -.TP -list \fIcoeffs\fR -List of coefficients as generated by \fIfilterButterworth\fR (or in fact any similar list of coefficients) -.TP -list \fIyinit\fR -(Optional) initial data for the filter result\&. -.RE -.TP -\fB$filterObj\fR filter \fIx\fR -Filter a single value and return the result\&. -.RS -.TP -double \fIx\fR -The value to be filtered -.RE -.TP -\fB$filterObj\fR reset -Reset the filter object (start anew) -.PP -.SH KEYWORDS -digital, filtering -.SH CATEGORY -Mathematics -.SH COPYRIGHT -.nf -Copyright (c) 2020 by Arjen Markus - -.fi Index: idoc/man/files/modules/math/fourier.n ================================================================== --- idoc/man/files/modules/math/fourier.n +++ idoc/man/files/modules/math/fourier.n @@ -409,17 +409,9 @@ bugs and other problems\&. Please report such in the category \fImath :: fourier\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS FFT, Fourier transform, complex numbers, mathematics .SH CATEGORY Mathematics Index: idoc/man/files/modules/math/fuzzy.n ================================================================== --- idoc/man/files/modules/math/fuzzy.n +++ idoc/man/files/modules/math/fuzzy.n @@ -411,17 +411,9 @@ bugs and other problems\&. Please report such in the category \fImath :: fuzzy\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS floating-point, math, rounding .SH CATEGORY Mathematics Index: idoc/man/files/modules/math/interpolate.n ================================================================== --- idoc/man/files/modules/math/interpolate.n +++ idoc/man/files/modules/math/interpolate.n @@ -575,18 +575,10 @@ bugs and other problems\&. Please report such in the category \fImath :: interpolate\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS interpolation, math, spatial interpolation .SH CATEGORY Mathematics .SH COPYRIGHT Index: idoc/man/files/modules/math/linalg.n ================================================================== --- idoc/man/files/modules/math/linalg.n +++ idoc/man/files/modules/math/linalg.n @@ -1470,18 +1470,10 @@ bugs and other problems\&. Please report such in the category \fImath :: linearalgebra\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS least squares, linear algebra, linear equations, math, matrices, matrix, vectors .SH CATEGORY Mathematics .SH COPYRIGHT Index: idoc/man/files/modules/math/machineparameters.n ================================================================== --- idoc/man/files/modules/math/machineparameters.n +++ idoc/man/files/modules/math/machineparameters.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'machineparameters\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2008 Michael Baudin '\" -.TH "math::machineparameters" n 1\&.0 tcllib "tclrep" +.TH "tclrep/machineparameters" n 1\&.0 tcllib "tclrep" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -270,14 +270,12 @@ .de MT .QW "" .. .BS .SH NAME -math::machineparameters \- Compute double precision machine parameters\&. +tclrep/machineparameters \- Compute double precision machine parameters\&. .SH SYNOPSIS -package require \fBTcl 8\&.4\fR -.sp package require \fBsnit \fR .sp package require \fBmath::machineparameters 0\&.1\fR .sp \fBmachineparameters\fR create \fIobjectname\fR ?\fIoptions\fR\&.\&.\&.? @@ -475,18 +473,10 @@ bugs and other problems\&. Please report such in the category \fImath\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH COPYRIGHT .nf Copyright (c) 2008 Michael Baudin .fi Index: idoc/man/files/modules/math/math.n ================================================================== --- idoc/man/files/modules/math/math.n +++ idoc/man/files/modules/math/math.n @@ -399,17 +399,9 @@ bugs and other problems\&. Please report such in the category \fImath\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS math, statistics .SH CATEGORY Mathematics Index: idoc/man/files/modules/math/math_geometry.n ================================================================== --- idoc/man/files/modules/math/math_geometry.n +++ idoc/man/files/modules/math/math_geometry.n @@ -1,14 +1,13 @@ '\" '\" Generated from file 'math_geometry\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2001 by Ideogramic ApS and other parties +'\" Copyright (c) 2004 by Arjen Markus '\" Copyright (c) 2010 by Andreas Kupries '\" Copyright (c) 2010 by Kevin Kenny -'\" Copyright (c) 2018 by Arjen Markus -'\" Copyright (c) 2020 by Manfred Rosenberger '\" -.TH "math::geometry" n 1\&.4\&.1 tcllib "Tcl Math Library" +.TH "math::geometry" n 1\&.2\&.2 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +277,11 @@ .SH NAME math::geometry \- Geometrical computations .SH SYNOPSIS package require \fBTcl ?8\&.5?\fR .sp -package require \fBmath::geometry ?1\&.4\&.1?\fR +package require \fBmath::geometry ?1\&.2\&.2?\fR .sp \fB::math::geometry::+\fR \fIpoint1\fR \fIpoint2\fR .sp \fB::math::geometry::-\fR \fIpoint1\fR \fIpoint2\fR .sp @@ -308,16 +307,10 @@ .sp \fB::math::geometry::nwse\fR \fIrect\fR .sp \fB::math::geometry::angle\fR \fIline\fR .sp -\fB::math::geometry::angleBetween\fR \fIvector1\fR \fIvector2\fR -.sp -\fB::math::geometry::inproduct\fR \fIvector1\fR \fIvector2\fR -.sp -\fB::math::geometry::areaParallellogram\fR \fIvector1\fR \fIvector2\fR -.sp \fB::math::geometry::calculateDistanceToLine\fR \fIP\fR \fIline\fR .sp \fB::math::geometry::calculateDistanceToLineSegment\fR \fIP\fR \fIlinesegment\fR .sp \fB::math::geometry::calculateDistanceToPolyline\fR \fIP\fR \fIpolyline\fR @@ -348,20 +341,10 @@ .sp \fB::math::geometry::rectanglesOverlap\fR \fIP1\fR \fIP2\fR \fIQ1\fR \fIQ2\fR \fIstrict\fR .sp \fB::math::geometry::bbox\fR \fIpolyline\fR .sp -\fB::math::geometry::overlapBBox\fR \fIpolyline1\fR \fIpolyline2\fR ?strict? -.sp -\fB::math::geometry::pointInsideBBox\fR \fIbbox\fR \fIpoint\fR -.sp -\fB::math::geometry::cathetusPoint\fR \fIpa\fR \fIpb\fR \fIcathetusLength\fR ?location? -.sp -\fB::math::geometry::parallel\fR \fIline\fR \fIoffset\fR ?orient? -.sp -\fB::math::geometry::unitVector\fR \fIline\fR -.sp \fB::math::geometry::pointInsidePolygon\fR \fIP\fR \fIpolyline\fR .sp \fB::math::geometry::pointInsidePolygonAlt\fR \fIP\fR \fIpolyline\fR .sp \fB::math::geometry::rectangleInsidePolygon\fR \fIP1\fR \fIP2\fR \fIpolyline\fR @@ -370,48 +353,16 @@ .sp \fB::math::geometry::translate\fR \fIvector\fR \fIpolyline\fR .sp \fB::math::geometry::rotate\fR \fIangle\fR \fIpolyline\fR .sp -\fB::math::geometry::rotateAbout\fR \fIp\fR \fIangle\fR \fIpolyline\fR -.sp \fB::math::geometry::reflect\fR \fIangle\fR \fIpolyline\fR .sp \fB::math::geometry::degToRad\fR \fIangle\fR .sp \fB::math::geometry::radToDeg\fR \fIangle\fR .sp -\fB::math::geometry::circle\fR \fIcentre\fR \fIradius\fR -.sp -\fB::math::geometry::circleTwoPoints\fR \fIpoint1\fR \fIpoint2\fR -.sp -\fB::math::geometry::pointInsideCircle\fR \fIpoint\fR \fIcircle\fR -.sp -\fB::math::geometry::lineIntersectsCircle\fR \fIline\fR \fIcircle\fR -.sp -\fB::math::geometry::lineSegmentIntersectsCircle\fR \fIsegment\fR \fIcircle\fR -.sp -\fB::math::geometry::intersectionLineWithCircle\fR \fIline\fR \fIcircle\fR -.sp -\fB::math::geometry::intersectionCircleWithCircle\fR \fIcircle1\fR \fIcircle2\fR -.sp -\fB::math::geometry::tangentLinesToCircle\fR \fIpoint\fR \fIcircle\fR -.sp -\fB::math::geometry::intersectionPolylines\fR \fIpolyline1\fR \fIpolyline2\fR ?mode? ?granularity? -.sp -\fB::math::geometry::intersectionPolylineCircle\fR \fIpolyline\fR \fIcircle\fR ?mode? ?granularity? -.sp -\fB::math::geometry::polylineCutOrigin\fR \fIpolyline1\fR \fIpolyline2\fR ?granularity? -.sp -\fB::math::geometry::polylineCutEnd\fR \fIpolyline1\fR \fIpolyline2\fR ?granularity? -.sp -\fB::math::geometry::splitPolyline\fR \fIpolyline\fR \fInumberVertex\fR -.sp -\fB::math::geometry::enrichPolyline\fR \fIpolyline\fR \fIaccuracy\fR -.sp -\fB::math::geometry::cleanupPolyline\fR \fIpolyline\fR -.sp .BE .SH DESCRIPTION .PP The \fBmath::geometry\fR package is a collection of functions for computations and manipulations on two-dimensional geometrical objects, @@ -420,13 +371,10 @@ The geometrical objects are implemented as plain lists of coordinates\&. For instance a line is defined by a list of four numbers, the x- and y-coordinate of a first point and the x- and y-coordinates of a second point on the line\&. .PP -\fINote:\fR In version 1\&.4\&.0 an inconsistency was repaired - see \fIhttps://core\&.tcl-lang\&.org/tcllib/tktview?name=fb4812f82b\fR\&. -More in \fBCOORDINATE SYSTEM\fR -.PP The various types of object are recognised by the number of coordinate pairs and the context in which they are used: a list of four elements can be regarded as an infinite line, a finite line segment but also as a polyline of one segment and a point set of two points\&. .PP @@ -449,13 +397,10 @@ the polyline is closed (if the first and last points do not coincide, the missing segment is automatically added)\&. .IP \(bu \fIpoint set\fR - again a list of an even number of coordinates, but the points are regarded without any ordering\&. -.IP \(bu -\fIcircle\fR - a list of three numbers, the first two are the coordinates of the -centre and the third is the radius\&. .PP .SH PROCEDURES The package defines the following public procedures: .TP \fB::math::geometry::+\fR \fIpoint1\fR \fIpoint2\fR @@ -489,11 +434,11 @@ result of the command\&. This is a vector as well\&. .TP \fB::math::geometry::direction\fR \fIangle\fR Given the angle in degrees this command computes and returns the unit vector pointing into this direction\&. The vector for -angle == 0 points to the right (east), and for angle == 90 up (north)\&. +angle == 0 points to the right (up), and for angle == 90 up (north)\&. .TP \fB::math::geometry::h\fR \fIlength\fR Returns a horizontal vector on the X-axis of the specified length\&. Positive lengths point to the right (east)\&. .TP @@ -547,43 +492,11 @@ .RS .TP list \fIline\fR Coordinates of the line .RE -.TP -\fB::math::geometry::angleBetween\fR \fIvector1\fR \fIvector2\fR -Calculate the angle between two vectors (in degrees) -.RS -.TP -list \fIvector1\fR -First vector -.TP -list \fIvector2\fR -Second vector -.RE -.TP -\fB::math::geometry::inproduct\fR \fIvector1\fR \fIvector2\fR -Calculate the inner product of two vectors -.RS -.TP -list \fIvector1\fR -First vector -.TP -list \fIvector2\fR -Second vector -.RE -.TP -\fB::math::geometry::areaParallellogram\fR \fIvector1\fR \fIvector2\fR -Calculate the area of the parallellogram with the two vectors as its sides -.RS -.TP -list \fIvector1\fR -First vector -.TP -list \fIvector2\fR -Second vector -.RE +.sp .TP \fB::math::geometry::calculateDistanceToLine\fR \fIP\fR \fIline\fR Calculate the distance of point P to the (infinite) line and return the result .RS @@ -593,10 +506,11 @@ .TP list \fIline\fR List of four numbers, the coordinates of two points on the line .RE +.sp .TP \fB::math::geometry::calculateDistanceToLineSegment\fR \fIP\fR \fIlinesegment\fR Calculate the distance of point P to the (finite) line segment and return the result\&. .RS @@ -606,10 +520,12 @@ .TP list \fIlinesegment\fR List of four numbers, the coordinates of the first and last points of the line segment .RE +.sp +.sp .TP \fB::math::geometry::calculateDistanceToPolyline\fR \fIP\fR \fIpolyline\fR Calculate the distance of point P to the polyline and return the result\&. Note that a polyline needs not to be closed\&. .RS @@ -619,10 +535,11 @@ .TP list \fIpolyline\fR List of numbers, the coordinates of the vertices of the polyline .RE +.sp .TP \fB::math::geometry::calculateDistanceToPolygon\fR \fIP\fR \fIpolygon\fR Calculate the distance of point P to the polygon and return the result\&. If the list of coordinates is not closed (first and last points differ), it is automatically closed\&. @@ -633,10 +550,11 @@ .TP list \fIpolygon\fR List of numbers, the coordinates of the vertices of the polygon .RE +.sp .TP \fB::math::geometry::findClosestPointOnLine\fR \fIP\fR \fIline\fR Return the point on a line which is closest to a given point\&. .RS .TP @@ -645,10 +563,11 @@ .TP list \fIline\fR List of four numbers, the coordinates of two points on the line .RE +.sp .TP \fB::math::geometry::findClosestPointOnLineSegment\fR \fIP\fR \fIlinesegment\fR Return the point on a \fIline segment\fR which is closest to a given point\&. .RS @@ -658,10 +577,11 @@ .TP list \fIlinesegment\fR List of four numbers, the first and last points on the line segment .RE +.sp .TP \fB::math::geometry::findClosestPointOnPolyline\fR \fIP\fR \fIpolyline\fR Return the point on a \fIpolyline\fR which is closest to a given point\&. .RS @@ -670,19 +590,21 @@ List of two numbers, the coordinates of the point .TP list \fIpolyline\fR List of numbers, the vertices of the polyline .RE +.sp .TP \fB::math::geometry::lengthOfPolyline\fR \fIpolyline\fR Return the length of the \fIpolyline\fR (note: it not regarded as a polygon) .RS .TP list \fIpolyline\fR List of numbers, the vertices of the polyline .RE +.sp .TP \fB::math::geometry::movePointInDirection\fR \fIP\fR \fIdirection\fR \fIdist\fR Move a point over a given distance in a given direction and return the new coordinates (in two dimensions only)\&. .RS @@ -695,10 +617,11 @@ upwards) .TP list \fIdist\fR Distance over which to move the point .RE +.sp .TP \fB::math::geometry::lineSegmentsIntersect\fR \fIlinesegment1\fR \fIlinesegment2\fR Check if two line segments intersect or coincide\&. Returns 1 if that is the case, 0 otherwise (in two dimensions only)\&. If an endpoint of one segment lies on the other segment (or is very close to the segment), they are considered to intersect @@ -708,10 +631,11 @@ First line segment .TP list \fIlinesegment2\fR Second line segment .RE +.sp .TP \fB::math::geometry::findLineSegmentIntersection\fR \fIlinesegment1\fR \fIlinesegment2\fR Find the intersection point of two line segments\&. Return the coordinates or the keywords "coincident" or "none" if the line segments coincide or have no points in common (in two dimensions only)\&. @@ -721,10 +645,11 @@ First line segment .TP list \fIlinesegment2\fR Second line segment .RE +.sp .TP \fB::math::geometry::findLineIntersection\fR \fIline1\fR \fIline2\fR Find the intersection point of two (infinite) lines\&. Return the coordinates or the keywords "coincident" or "none" if the lines coincide or have no points in common (in two dimensions only)\&. @@ -736,10 +661,11 @@ list \fIline2\fR Second line .RE .IP See section \fBReferences\fR for details on the algorithm and math behind it\&. +.sp .TP \fB::math::geometry::polylinesIntersect\fR \fIpolyline1\fR \fIpolyline2\fR Check if two polylines intersect or not (in two dimensions only)\&. .RS .TP @@ -747,10 +673,11 @@ First polyline .TP list \fIpolyline2\fR Second polyline .RE +.sp .TP \fB::math::geometry::polylinesBoundingIntersect\fR \fIpolyline1\fR \fIpolyline2\fR \fIgranularity\fR Check whether two polylines intersect, but reduce the correctness of the result to the given granularity\&. Use this for faster, but weaker, intersection checking\&. @@ -771,10 +698,11 @@ .TP int \fIgranularity\fR Number of points in each part (<=1 means check every edge) .RE +.sp .TP \fB::math::geometry::intervalsOverlap\fR \fIy1\fR \fIy2\fR \fIy3\fR \fIy4\fR \fIstrict\fR Check if two intervals overlap\&. .RS .TP @@ -785,10 +713,11 @@ Begin and end of second interval .TP logical \fIstrict\fR Check for strict or non-strict overlap .RE +.sp .TP \fB::math::geometry::rectanglesOverlap\fR \fIP1\fR \fIP2\fR \fIQ1\fR \fIQ2\fR \fIstrict\fR Check if two rectangles overlap\&. .RS .TP @@ -805,99 +734,21 @@ lower-right corner of the second rectangle .TP list \fIstrict\fR choosing strict or non-strict interpretation .RE +.sp .TP \fB::math::geometry::bbox\fR \fIpolyline\fR Calculate the bounding box of a polyline\&. Returns a list of four coordinates: the upper-left and the lower-right corner of the box\&. .RS .TP list \fIpolyline\fR The polyline to be examined .RE -.TP -\fB::math::geometry::overlapBBox\fR \fIpolyline1\fR \fIpolyline2\fR ?strict? -Check if the bounding boxes of two polylines overlap or not\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline1\fR -The first polyline -.TP -list \fIpolyline1\fR -The second polyline -.TP -int \fIstrict\fR -Whether strict overlap is to checked (1) or if the bounding boxes may touch (0, default) -.RE -.TP -\fB::math::geometry::pointInsideBBox\fR \fIbbox\fR \fIpoint\fR -.sp -Check if the point is inside or on the bounding box or not\&. -Arguments: -.RS -.TP -list \fIbbox\fR -The bounding box given as a list of x/y coordinates -.TP -list \fIpoint\fR -The point to be checked -.RE -.TP -\fB::math::geometry::cathetusPoint\fR \fIpa\fR \fIpb\fR \fIcathetusLength\fR ?location? -Return the third point of the rectangular triangle defined by the two given end points of the hypothenusa\&. -The triangle's side from point A (or B, if the location is given as "b") to the third point is the cathetus length\&. -If the cathetus' length is lower than the length of the hypothenusa, an empty list is returned\&. -.sp -Arguments: -.RS -.TP -list \fIpa\fR -The starting point on hypotenuse -.TP -list \fIpb\fR -The ending point on hypotenuse -.TP -float \fIcathetusLength\fR -The length of the cathetus of the triangle -.TP -string \fIlocation\fR -The location of the given cathetus, -"a" means given cathetus shares point pa (default) -"b" means given cathetus shares point pb -.RE -.TP -\fB::math::geometry::parallel\fR \fIline\fR \fIoffset\fR ?orient? -Return a line parallel to the given line, with a distance "offset"\&. The orientation is determined by the -two points defining the line\&. -.sp -Arguments: -.RS -.TP -list \fIline\fR -The given line -.TP -float \fIoffset\fR -The distance to the given line -.TP -string \fIorient\fR -Orientation of the new line with respect to the given line (defaults to "right") -.RE -.sp -.TP -\fB::math::geometry::unitVector\fR \fIline\fR -Return a unit vector from the given line or direction, if the \fIline\fR argument is -a single point (then a line through the origin is assumed) -Arguments: -.RS -.TP -list \fIline\fR -The line in question (or a single point, implying a line through the origin) -.RE +.sp .TP \fB::math::geometry::pointInsidePolygon\fR \fIP\fR \fIpolyline\fR Determine if a point is completely inside a polygon\&. If the point touches the polygon, then the point is not completely inside the polygon\&. @@ -907,10 +758,11 @@ Coordinates of the point .TP list \fIpolyline\fR The polyline to be examined .RE +.sp .TP \fB::math::geometry::pointInsidePolygonAlt\fR \fIP\fR \fIpolyline\fR Determine if a point is completely inside a polygon\&. If the point touches the polygon, then the point is not completely inside the polygon\&. \fINote:\fR this alternative procedure uses the so-called @@ -922,10 +774,11 @@ Coordinates of the point .TP list \fIpolyline\fR The polyline to be examined .RE +.sp .TP \fB::math::geometry::rectangleInsidePolygon\fR \fIP1\fR \fIP2\fR \fIpolyline\fR Determine if a rectangle is completely inside a polygon\&. If polygon touches the rectangle, then the rectangle is not complete inside the polygon\&. @@ -939,56 +792,44 @@ .sp .TP list \fIpolygon\fR The polygon in question .RE +.sp .TP \fB::math::geometry::areaPolygon\fR \fIpolygon\fR Calculate the area of a polygon\&. .RS .TP list \fIpolygon\fR The polygon in question .RE +.sp .TP \fB::math::geometry::translate\fR \fIvector\fR \fIpolyline\fR Translate a polyline over a given vector .RS .TP list \fIvector\fR Translation vector .TP list \fIpolyline\fR -The polyline to be translated +The polyline to be rotated .RE +.sp .TP \fB::math::geometry::rotate\fR \fIangle\fR \fIpolyline\fR Rotate a polyline over a given angle (degrees) around the origin .RS .TP list \fIangle\fR Angle over which to rotate the polyline (degrees) .TP list \fIpolyline\fR -The polyline to be rotated -.RE -.TP -\fB::math::geometry::rotateAbout\fR \fIp\fR \fIangle\fR \fIpolyline\fR -Rotate a polyline around a given point p and return the new polyline\&. -.sp -Arguments: -.RS -.TP -list \fIp\fR -The point of rotation -.TP -float \fIangle\fR -The angle over which to rotate the polyline (degrees) -.TP -list \fIpolyline\fR -The polyline to be rotated -.RE +The polyline to be translated +.RE +.sp .TP \fB::math::geometry::reflect\fR \fIangle\fR \fIpolyline\fR Reflect a polyline in a line through the origin at a given angle (degrees) to the x-axis .RS .TP @@ -996,247 +837,29 @@ Angle of the line of reflection (degrees) .TP list \fIpolyline\fR The polyline to be reflected .RE +.sp .TP \fB::math::geometry::degToRad\fR \fIangle\fR Convert from degrees to radians .RS .TP list \fIangle\fR Angle in degrees .RE +.sp .TP \fB::math::geometry::radToDeg\fR \fIangle\fR Convert from radians to degrees .RS .TP list \fIangle\fR Angle in radians .RE -.TP -\fB::math::geometry::circle\fR \fIcentre\fR \fIradius\fR -Convenience procedure to create a circle from a point and a radius\&. -.RS -.TP -list \fIcentre\fR -Coordinates of the circle centre -.TP -list \fIradius\fR -Radius of the circle -.RE -.TP -\fB::math::geometry::circleTwoPoints\fR \fIpoint1\fR \fIpoint2\fR -Convenience procedure to create a circle from two points on its circumference -The centre is the point between the two given points, the radius is half the -distance between them\&. -.RS -.TP -list \fIpoint1\fR -First point -.TP -list \fIpoint2\fR -Second point -.RE -.TP -\fB::math::geometry::pointInsideCircle\fR \fIpoint\fR \fIcircle\fR -Determine if the given point is inside the circle or on the circumference (1) -or outside (0)\&. -.RS -.TP -list \fIpoint\fR -Point to be checked -.TP -list \fIcircle\fR -Circle that may or may not contain the point -.RE -.TP -\fB::math::geometry::lineIntersectsCircle\fR \fIline\fR \fIcircle\fR -Determine if the given line intersects the circle or touches it (1) -or does not (0)\&. -.RS -.TP -list \fIline\fR -Line to be checked -.TP -list \fIcircle\fR -Circle that may or may not be intersected -.RE -.TP -\fB::math::geometry::lineSegmentIntersectsCircle\fR \fIsegment\fR \fIcircle\fR -Determine if the given line segment intersects the circle or touches it (1) -or does not (0)\&. -.RS -.TP -list \fIsegment\fR -Line segment to be checked -.TP -list \fIcircle\fR -Circle that may or may not be intersected -.RE -.TP -\fB::math::geometry::intersectionLineWithCircle\fR \fIline\fR \fIcircle\fR -Determine the points at which the given line intersects the circle\&. There can -be zero, one or two points\&. (If the line touches the circle or is close to it, -then one point is returned\&. An arbitrary margin of 1\&.0e-10 times the radius -is used to determine this situation\&.) -.RS -.TP -list \fIline\fR -Line to be checked -.TP -list \fIcircle\fR -Circle that may or may not be intersected -.RE -.TP -\fB::math::geometry::intersectionCircleWithCircle\fR \fIcircle1\fR \fIcircle2\fR -Determine the points at which the given two circles intersect\&. There can -be zero, one or two points\&. (If the two circles touch the circle or are very close, -then one point is returned\&. An arbitrary margin of 1\&.0e-10 times the mean of the radii of -the two circles is used to determine this situation\&.) -.RS -.TP -list \fIcircle1\fR -First circle -.TP -list \fIcircle2\fR -Second circle -.RE -.TP -\fB::math::geometry::tangentLinesToCircle\fR \fIpoint\fR \fIcircle\fR -Determine the tangent lines from the given point to the circle\&. There can -be zero, one or two lines\&. (If the point is on the cirucmference or very close to -the circle, then one line is returned\&. An arbitrary margin of 1\&.0e-10 times the -radius of the circle is used to determine this situation\&.) -.RS -.TP -list \fIpoint\fR -Point in question -.TP -list \fIcircle\fR -Circle to which the tangent lines are to be determined -.RE -.TP -\fB::math::geometry::intersectionPolylines\fR \fIpolyline1\fR \fIpolyline2\fR ?mode? ?granularity? -Return the first point or all points where the two polylines intersect\&. If the number of points in the polylines is large, -you can use the granularity to get an approximate answer faster\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline1\fR -The first polyline -.TP -list \fIpolyline2\fR -The second polyline -.TP -string \fImode\fR -Whether to return only the first (default) or to return all intersection points ("all") -.TP -int \fIgranularity\fR -The number of points that will be skipped plus 1 in the search for intersection points (1 or smaller means an exact answer is returned) -.RE -.TP -\fB::math::geometry::intersectionPolylineCircle\fR \fIpolyline\fR \fIcircle\fR ?mode? ?granularity? -Return the first point or all points where the polyline intersects the circle\&. If the number of points in the polyline is large, -you can use the granularity to get an approximate answer faster\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline\fR -The polyline that may intersect the circle -.TP -list \fIcircle\fR -The circle in question -.TP -string \fImode\fR -Whether to return only the first (default) or to return all intersection points ("all") -.TP -int \fIgranularity\fR -The number of points that will be skipped plus 1 in the search for intersection points (1 or smaller means an exact answer is returned) -.RE -.TP -\fB::math::geometry::polylineCutOrigin\fR \fIpolyline1\fR \fIpolyline2\fR ?granularity? -Return the part of the first polyline from the origin up to the first intersection with the second\&. If the number of points in the polyline is large, -you can use the granularity to get an approximate answer faster\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline1\fR -The first polyline (from which a part is to be returned) -.TP -list \fIpolyline2\fR -The second polyline -.TP -int \fIgranularity\fR -The number of points that will be skipped plus 1 in the search for intersection points (1 or smaller means an exact answer is returned) -.RE -.TP -\fB::math::geometry::polylineCutEnd\fR \fIpolyline1\fR \fIpolyline2\fR ?granularity? -Return the part of the first polyline from the last intersection point with the second to the end\&. If the number of points in the polyline is large, -you can use the granularity to get an approximate answer faster\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline1\fR -The first polyline (from which a part is to be returned) -.TP -list \fIpolyline2\fR -The second polyline -.TP -int \fIgranularity\fR -The number of points that will be skipped plus 1 in the search for intersection points (1 or smaller means an exact answer is returned) -.RE -.TP -\fB::math::geometry::splitPolyline\fR \fIpolyline\fR \fInumberVertex\fR -Split the poyline into a set of polylines where each separate polyline holds "numberVertex" vertices between the two end points\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline\fR -The polyline to be split up -.TP -int \fInumberVertex\fR -The number of "internal" vertices -.RE -.TP -\fB::math::geometry::enrichPolyline\fR \fIpolyline\fR \fIaccuracy\fR -Split up each segment of a polyline into a number of smaller segments and return the result\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline\fR -The polyline to be refined -.TP -int \fIaccuracy\fR -The number of subsegments to be created -.RE -.TP -\fB::math::geometry::cleanupPolyline\fR \fIpolyline\fR -Remove duplicate neighbouring vertices and return the result\&. -.sp -Arguments: -.RS -.TP -list \fIpolyline\fR -The polyline to be cleaned up -.RE .PP -.SH "COORDINATE SYSTEM" -The coordinate system used by the package is the ordinary cartesian system, where the -positive x-axis is directed to the right and the positive y-axis is directed upwards\&. -Angles and directions are defined with respect to the positive x-axis in a counter-clockwise -direction, so that an angle of 90 degrees is the direction of the positive y-axis\&. -Note that the Tk canvas coordinates differ from this, as there the origin is located in the -upper left corner of the window\&. Up to and including version 1\&.3, the direction and octant -procedures of this package used this convention inconsistently\&. .SH REFERENCES .IP [1] \fIPolygon Intersection\fR [http:/wiki\&.tcl\&.tk/12070] .IP [2] \fIhttp://en\&.wikipedia\&.org/wiki/Line-line_intersection\fR @@ -1248,26 +871,17 @@ bugs and other problems\&. Please report such in the category \fImath :: geometry\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS angle, distance, line, math, plane geometry, point .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2001 by Ideogramic ApS and other parties +Copyright (c) 2004 by Arjen Markus Copyright (c) 2010 by Andreas Kupries Copyright (c) 2010 by Kevin Kenny -Copyright (c) 2018 by Arjen Markus -Copyright (c) 2020 by Manfred Rosenberger .fi Index: idoc/man/files/modules/math/numtheory.n ================================================================== --- idoc/man/files/modules/math/numtheory.n +++ idoc/man/files/modules/math/numtheory.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'numtheory\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2010 Lars Hellström '\" -.TH "math::numtheory" n 1\&.1\&.1 tcllib "Tcl Math Library" +.TH "math::numtheory" n 1\&.0 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,53 +274,20 @@ .SH NAME math::numtheory \- Number Theory .SH SYNOPSIS package require \fBTcl ?8\&.5?\fR .sp -package require \fBmath::numtheory ?1\&.1\&.1?\fR +package require \fBmath::numtheory ?1\&.0?\fR .sp \fBmath::numtheory::isprime\fR \fIN\fR ?\fIoption\fR \fIvalue\fR \&.\&.\&.? .sp -\fBmath::numtheory::firstNprimes\fR \fIN\fR -.sp -\fBmath::numtheory::primesLowerThan\fR \fIN\fR -.sp -\fBmath::numtheory::primeFactors\fR \fIN\fR -.sp -\fBmath::numtheory::primesLowerThan\fR \fIN\fR -.sp -\fBmath::numtheory::primeFactors\fR \fIN\fR -.sp -\fBmath::numtheory::uniquePrimeFactors\fR \fIN\fR -.sp -\fBmath::numtheory::factors\fR \fIN\fR -.sp -\fBmath::numtheory::totient\fR \fIN\fR -.sp -\fBmath::numtheory::moebius\fR \fIN\fR -.sp -\fBmath::numtheory::legendre\fR \fIa\fR \fIp\fR -.sp -\fBmath::numtheory::jacobi\fR \fIa\fR \fIb\fR -.sp -\fBmath::numtheory::gcd\fR \fIm\fR \fIn\fR -.sp -\fBmath::numtheory::lcm\fR \fIm\fR \fIn\fR -.sp -\fBmath::numtheory::numberPrimesGauss\fR \fIN\fR -.sp -\fBmath::numtheory::numberPrimesLegendre\fR \fIN\fR -.sp -\fBmath::numtheory::numberPrimesLegendreModified\fR \fIN\fR -.sp -\fBmath::numtheory::differenceNumberPrimesLegendreModified\fR \fIlower\fR \fIupper\fR -.sp .BE .SH DESCRIPTION .PP -This package is for collecting various number-theoretic operations, with -a slight bias to prime numbers\&. +This package is for collecting various number-theoretic operations, +though at the moment it only provides that of testing whether an +integer is a prime\&. .TP \fBmath::numtheory::isprime\fR \fIN\fR ?\fIoption\fR \fIvalue\fR \&.\&.\&.? The \fBisprime\fR command tests whether the integer \fIN\fR is a prime, returning a boolean true value for prime \fIN\fR and a boolean false value for non-prime \fIN\fR\&. The formal definition of @@ -348,182 +315,22 @@ probability of a false positive by a factor at least 4\&. The default for \fIrepetitions\fR is 4\&. .RE .IP Unknown options are silently ignored\&. -.TP -\fBmath::numtheory::firstNprimes\fR \fIN\fR -Return the first N primes -.RS -.TP -integer \fIN\fR (in) -Number of primes to return -.RE -.TP -\fBmath::numtheory::primesLowerThan\fR \fIN\fR -Return the prime numbers lower/equal to N -.RS -.TP -integer \fIN\fR (in) -Maximum number to consider -.RE -.TP -\fBmath::numtheory::primeFactors\fR \fIN\fR -Return a list of the prime numbers in the number N -.RS -.TP -integer \fIN\fR (in) -Number to be factorised -.RE -.TP -\fBmath::numtheory::primesLowerThan\fR \fIN\fR -Return the prime numbers lower/equal to N -.RS -.TP -integer \fIN\fR (in) -Maximum number to consider -.RE -.TP -\fBmath::numtheory::primeFactors\fR \fIN\fR -Return a list of the prime numbers in the number N -.RS -.TP -integer \fIN\fR (in) -Number to be factorised -.RE -.TP -\fBmath::numtheory::uniquePrimeFactors\fR \fIN\fR -Return a list of the \fIunique\fR prime numbers in the number N -.RS -.TP -integer \fIN\fR (in) -Number to be factorised -.RE -.TP -\fBmath::numtheory::factors\fR \fIN\fR -Return a list of all \fIunique\fR factors in the number N, including 1 and N itself -.RS -.TP -integer \fIN\fR (in) -Number to be factorised -.RE -.TP -\fBmath::numtheory::totient\fR \fIN\fR -Evaluate the Euler totient function for the number N (number of numbers -relatively prime to N) -.RS -.TP -integer \fIN\fR (in) -Number in question -.RE -.TP -\fBmath::numtheory::moebius\fR \fIN\fR -Evaluate the Moebius function for the number N -.RS -.TP -integer \fIN\fR (in) -Number in question -.RE -.TP -\fBmath::numtheory::legendre\fR \fIa\fR \fIp\fR -Evaluate the Legendre symbol (a/p) -.RS -.TP -integer \fIa\fR (in) -Upper number in the symbol -.TP -integer \fIp\fR (in) -Lower number in the symbol (must be non-zero) -.RE -.TP -\fBmath::numtheory::jacobi\fR \fIa\fR \fIb\fR -Evaluate the Jacobi symbol (a/b) -.RS -.TP -integer \fIa\fR (in) -Upper number in the symbol -.TP -integer \fIb\fR (in) -Lower number in the symbol (must be odd) -.RE -.TP -\fBmath::numtheory::gcd\fR \fIm\fR \fIn\fR -Return the greatest common divisor of \fIm\fR and \fIn\fR -.RS -.TP -integer \fIm\fR (in) -First number -.TP -integer \fIn\fR (in) -Second number -.RE -.TP -\fBmath::numtheory::lcm\fR \fIm\fR \fIn\fR -Return the lowest common multiple of \fIm\fR and \fIn\fR -.RS -.TP -integer \fIm\fR (in) -First number -.TP -integer \fIn\fR (in) -Second number -.RE -.TP -\fBmath::numtheory::numberPrimesGauss\fR \fIN\fR -Estimate the number of primes according the formula by Gauss\&. -.RS -.TP -integer \fIN\fR (in) -Number in question, should be larger than 0 -.RE -.TP -\fBmath::numtheory::numberPrimesLegendre\fR \fIN\fR -Estimate the number of primes according the formula by Legendre\&. -.RS -.TP -integer \fIN\fR (in) -Number in question, should be larger than 0 -.RE -.TP -\fBmath::numtheory::numberPrimesLegendreModified\fR \fIN\fR -Estimate the number of primes according the modified formula by Legendre\&. -.RS -.TP -integer \fIN\fR (in) -Number in question, should be larger than 0 -.RE -.TP -\fBmath::numtheory::differenceNumberPrimesLegendreModified\fR \fIlower\fR \fIupper\fR -Estimate the number of primes between tow limits according the modified formula by Legendre\&. -.RS -.TP -integer \fIlower\fR (in) -Lower limit for the primes, should be larger than 0 -.TP -integer \fIupper\fR (in) -Upper limit for the primes, should be larger than 0 -.RE .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fImath :: numtheory\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS number theory, prime .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2010 Lars Hellström .fi Index: idoc/man/files/modules/math/optimize.n ================================================================== --- idoc/man/files/modules/math/optimize.n +++ idoc/man/files/modules/math/optimize.n @@ -606,18 +606,10 @@ bugs and other problems\&. Please report such in the category \fImath :: optimize\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS linear program, math, maximum, minimum, optimization .SH CATEGORY Mathematics .SH COPYRIGHT DELETED idoc/man/files/modules/math/pca.n Index: idoc/man/files/modules/math/pca.n ================================================================== --- idoc/man/files/modules/math/pca.n +++ idoc/man/files/modules/math/pca.n @@ -1,434 +0,0 @@ -'\" -'\" Generated from file 'pca\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "math::PCA" n 1\&.0 tcllib "Principal Components Analysis" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::PCA \- Package for Principal Component Analysis -.SH SYNOPSIS -package require \fBTcl ?8\&.6?\fR -.sp -package require \fBmath::linearalgebra 1\&.0\fR -.sp -\fB::math::PCA::createPCA\fR \fIdata\fR ?args? -.sp -\fB$pca using\fR ?number?|?-minproportion value? -.sp -\fB$pca eigenvectors\fR ?option? -.sp -\fB$pca eigenvalues\fR ?option? -.sp -\fB$pca proportions\fR ?option? -.sp -\fB$pca approximate\fR \fIobservation\fR -.sp -\fB$pca approximatOriginal\fR -.sp -\fB$pca scores\fR \fIobservation\fR -.sp -\fB$pca distance\fR \fIobservation\fR -.sp -\fB$pca qstatistic\fR \fIobservation\fR ?option? -.sp -.BE -.SH DESCRIPTION -.PP -The PCA package provides a means to perform principal components analysis -in Tcl, using an object-oriented technique as facilitated by TclOO\&. It -actually defines a single public method, \fI::math::PCA::createPCA\fR, -which constructs an object based on the data that are passed to perform -the actual analysis\&. -.PP -The methods of the PCA objects that are created with this command allow one -to examine the principal components, to approximate (new) observations -using all or a selected number of components only and to examine the -properties of the components and the statistics of the approximations\&. -.PP -The package has been modelled after the PCA example provided by the -original linear algebra package by Ed Hume\&. -.SH COMMANDS -The \fImath::PCA\fR package provides one public command: -.TP -\fB::math::PCA::createPCA\fR \fIdata\fR ?args? -Create a new object, based on the data that are passed via the \fIdata\fR argument\&. -The principal components may be based on either correlations or covariances\&. -All observations will be normalised according to the mean and standard deviation -of the original data\&. -.RS -.TP -list \fIdata\fR -- A list of observations (see the example below)\&. -.TP -list \fIargs\fR -- A list of key-value pairs defining the options\&. Currently there is -only one key: \fI-covariances\fR\&. This indicates if covariances are to be used -(if the value is 1) or instead correlations (value is 0)\&. The default is to use -correlations\&. -.RE -.PP -The PCA object that is created has the following methods: -.TP -\fB$pca using\fR ?number?|?-minproportion value? -Set the number of components to be used in the analysis (the number of retained components)\&. -Returns the number of components, also if no argument is given\&. -.RS -.TP -int \fInumber\fR -- The number of components to be retained -.TP -double \fIvalue\fR -- Select the number of components based on the minimum proportion -of variation that is retained by them\&. Should be a value between 0 and 1\&. -.RE -.TP -\fB$pca eigenvectors\fR ?option? -Return the eigenvectors as a list of lists\&. -.RS -.TP -string \fIoption\fR -- By default only the \fIretained\fR components are returned\&. -If all eigenvectors are required, use the option \fI-all\fR\&. -.RE -.TP -\fB$pca eigenvalues\fR ?option? -Return the eigenvalues as a list of lists\&. -.RS -.TP -string \fIoption\fR -- By default only the eigenvalues of the \fIretained\fR components are returned\&. -If all eigenvalues are required, use the option \fI-all\fR\&. -.RE -.TP -\fB$pca proportions\fR ?option? -Return the proportions for all components, that is, the amount of variations that each -components can explain\&. -.TP -\fB$pca approximate\fR \fIobservation\fR -Return an approximation of the observation based on the retained components -.RS -.TP -list \fIobservation\fR -- The values for the observation\&. -.RE -.TP -\fB$pca approximatOriginal\fR -Return an approximation of the original data, using the retained components\&. It is -a convenience method that works on the complete set of original data\&. -.TP -\fB$pca scores\fR \fIobservation\fR -Return the scores per retained component for the given observation\&. -.RS -.TP -list \fIobservation\fR -- The values for the observation\&. -.RE -.TP -\fB$pca distance\fR \fIobservation\fR -Return the distance between the given observation and its approximation\&. (Note: -this distance is based on the normalised vectors\&.) -.RS -.TP -list \fIobservation\fR -- The values for the observation\&. -.RE -.TP -\fB$pca qstatistic\fR \fIobservation\fR ?option? -Return the Q statistic, basically the square of the distance, for the given observation\&. -.RS -.TP -list \fIobservation\fR -- The values for the observation\&. -.TP -string \fIoption\fR -- If the observation is part of the original data, you may want -to use the corrected Q statistic\&. This is achieved with the option "-original"\&. -.RE -.PP -.SH EXAMPLE -TODO: NIST example -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIPCA\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -PCA, math, statistics, tcl -.SH CATEGORY -Mathematics Index: idoc/man/files/modules/math/polynomials.n ================================================================== --- idoc/man/files/modules/math/polynomials.n +++ idoc/man/files/modules/math/polynomials.n @@ -496,22 +496,14 @@ bugs and other problems\&. Please report such in the category \fImath :: polynomials\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS math, polynomial functions .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus .fi DELETED idoc/man/files/modules/math/probopt.n Index: idoc/man/files/modules/math/probopt.n ================================================================== --- idoc/man/files/modules/math/probopt.n +++ idoc/man/files/modules/math/probopt.n @@ -1,500 +0,0 @@ -'\" -'\" Generated from file 'probopt\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "math::probopt" n 1 tcllib "Tcl Math Library" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::probopt \- Probabilistic optimisation methods -.SH SYNOPSIS -package require \fBTcl 8\&.5\fR -.sp -package require \fBmath::probopt 1\fR -.sp -\fB::math::probopt::pso\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -.sp -\fB::math::probopt::sce\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -.sp -\fB::math::probopt::diffev\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -.sp -\fB::math::probopt::lipoMax\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -.sp -\fB::math::probopt::adaLipoMax\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -.sp -.BE -.SH DESCRIPTION -.PP -The purpose of the \fBmath::probopt\fR package is to provide various optimisation -algorithms that are based on probabilistic techniques\&. The results of these algorithms -may therefore vary from one run to the next\&. The algorithms are all well-known and -well described and proponents generally claim they are efficient and reliable\&. -.PP -As most of these algorithms have one or more tunable parameters or even variations, -the interface to each accepts options to set these parameters or the select -the variation\&. These take the form of key-value pairs, for instance, \fI-iterations 100\fR\&. -.PP -This manual does not offer any recommendations with regards to these algorithms, nor -does it provide much in the way of guidelines for the parameters\&. For this we refer to -online articles on the algorithms in question\&. -.PP -A few notes, however: -.IP \(bu -With the exception of LIPO, the algorithms are capable of dealing with irregular (non-smooth) and even discontinuous -functions\&. -.IP \(bu -The results depend on the random number seeding and are likely not to be very accurate, especially if the function -varies slowly in the vicinty of the optimum\&. They do give a good starting point for a deterministic algorithm\&. -.PP -.PP -The collection consists of the following algorithms: -.IP \(bu -PSO - particle swarm optimisation -.IP \(bu -SCE - shuffled complexes evolution -.IP \(bu -DE - differential evolution -.IP \(bu -LIPO - Lipschitz optimisation -.PP -The various procedures have a uniform interface: -.CS - - - set result [::math::probopt::algorithm function bounds args] - -.CE -The arguments have the following meaning: -.IP \(bu -The argument \fIfunction\fR is the name of the procedure that evaluates the function\&. -Its interface is: -.CS - - - set value [function coords] - -.CE -.IP -where \fIcoords\fR is a list of coordinates at which to evaluate the function\&. It is -supposed to return the function value\&. -.IP \(bu -The argument \fIbounds\fR is a list of pairs of minimum and maximum for each coordinate\&. -This list implicitly determines the dimension of the coordinate space in which the optimum -is to be sought, for instance for a function like \fIx**2 + (y-1)**4\fR, you may specify -the bounds as \fI{{-1 1} {-1 1}}\fR, that is, two pairs for the two coordinates\&. -.IP \(bu -The rest (\fIargs\fR) consists of zero or more key-value pairs to specify the options\&. Which -options are supported by which algorithm, is documented below\&. -.PP -The result of the various optimisation procedures is a dictionary containing at least the -following elements: -.IP \(bu -\fIoptimum-coordinates\fR is a list containing the coordinates of the optimum that was found\&. -.IP \(bu -\fIoptimum-value\fR is the function value at those coordinates\&. -.IP \(bu -\fIevaluations\fR is the number of function evaluations\&. -.IP \(bu -\fIbest-values\fR is a list of successive best values, obtained as -part of the iterations\&. -.PP -.SH "DETAILS ON THE ALGORITHMS" -The algorithms in the package are the following: -.TP -\fB::math::probopt::pso\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -The "particle swarm optimisation" algorithm uses the idea that the candidate -optimum points should swarm around the best point found so far, with -variations to allow for improvements\&. -.sp -It recognises the following options: -.RS -.IP \(bu -\fI-swarmsize number\fR: Number of particles to consider (default: 50) -.IP \(bu -\fI-vweight value\fR: Weight for the current "velocity" (0-1, default: 0\&.5) -.IP \(bu -\fI-pweight value\fR: Weight for the individual particle's best position (0-1, default: 0\&.3) -.IP \(bu -\fI-gweight value\fR: Weight for the "best" overall position as per particle (0-1, default: 0\&.3) -.IP \(bu -\fI-type local/global\fR: Type of optimisation -.IP \(bu -\fI-neighbours number\fR: Size of the neighbourhood (default: 5, used if "local") -.IP \(bu -\fI-iterations number\fR: Maximum number of iterations -.IP \(bu -\fI-tolerance value\fR: Absolute minimal improvement for minimum value -.RE -.TP -\fB::math::probopt::sce\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -The "shuffled complex evolution" algorithm is an extension of the Nelder-Mead algorithm that -uses multiple complexes and reorganises these complexes to find the "global" optimum\&. -.sp -It recognises the following options: -.RS -.IP \(bu -\fI-complexes number\fR: Number of particles to consider (default: 2) -.IP \(bu -\fI-mincomplexes number\fR: Minimum number of complexes (default: 2; not currently used) -.IP \(bu -\fI-newpoints number\fR: Number of new points to be generated (default: 1) -.IP \(bu -\fI-shuffle number\fR: Number of iterations after which to reshuffle the complexes (if set to 0, the default, a number will be calculated from the number of dimensions) -.IP \(bu -\fI-pointspercomplex number\fR: Number of points per complex (if set to 0, the default, a number will be calculated from the number of dimensions) -.IP \(bu -\fI-pointspersubcomplex number\fR: Number of points per subcomplex (used to select the best points in each complex; if set to 0, the default, a number will be calculated from the number of dimensions) -.IP \(bu -\fI-iterations number\fR: Maximum number of iterations (default: 100) -.IP \(bu -\fI-maxevaluations number\fR: Maximum number of function evaluations (when this number is reached the iteration is broken off\&. Default: 1000 million) -.IP \(bu -\fI-abstolerance value\fR: Absolute minimal improvement for minimum value (default: 0\&.0) -.IP \(bu -\fI-reltolerance value\fR: Relative minimal improvement for minimum value (default: 0\&.001) -.RE -.TP -\fB::math::probopt::diffev\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -The "differential evolution" algorithm uses a number of initial points that are then updated using randomly selected points\&. It is more or less akin -to genetic algorithms\&. It is controlled by two parameters, factor and lambda, where the first determines the update via random points and the second -the update with the best point found sofar\&. -.sp -It recognises the following options: -.RS -.IP \(bu -\fI-iterations number\fR: Maximum number of iterations (default: 100) -.IP \(bu -\fI-number number\fR: Number of point to work with (if set to 0, the default, it is calculated from the number of dimensions) -.IP \(bu -\fI-factor value\fR: Weight of randomly selected points in the updating (0-1, default: 0\&.6) -.IP \(bu -\fI-lambda value\fR: Weight of the best point found so far in the updating (0-1, default: 0\&.0) -.IP \(bu -\fI-crossover value\fR: Fraction of new points to be considered for replacing the old ones (0-1, default: 0\&.5) -.IP \(bu -\fI-maxevaluations number\fR: Maximum number of function evaluations (when this number is reached the iteration is broken off\&. Default: 1000 million) -.IP \(bu -\fI-abstolerance value\fR: Absolute minimal improvement for minimum value (default: 0\&.0) -.IP \(bu -\fI-reltolerance value\fR: Relative minimal improvement for minimum value (default: 0\&.001) -.RE -.TP -\fB::math::probopt::lipoMax\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -The "Lipschitz optimisation" algorithm uses the "Lipschitz" property of the given function to find a \fImaximum\fR in the given bounding box\&. There are -two variants, \fIlipoMax\fR assumes a fixed estimate for the Lipschitz parameter\&. -.sp -It recognises the following options: -.RS -.IP \(bu -\fI-iterations number\fR: Number of iterations (equals the actual number of function evaluations, default: 100) -.IP \(bu -\fI-lipschitz value\fR: Estimate of the Lipschitz parameter (default: 10\&.0) -.RE -.TP -\fB::math::probopt::adaLipoMax\fR \fIfunction\fR \fIbounds\fR \fIargs\fR -The "adaptive Lipschitz optimisation" algorithm uses the "Lipschitz" property of the given function to find a \fImaximum\fR in the given bounding box\&. The adaptive -variant actually uses two phases to find a suitable estimate for the Lipschitz parameter\&. This is controlled by the "Bernoulli" parameter\&. -.sp -When you specify a large number of iterations, the algorithm may take a very long time to complete as it is trying to improve on the Lipschitz parameter and -the chances of hitting a better estimate diminish fast\&. -.sp -It recognises the following options: -.RS -.IP \(bu -\fI-iterations number\fR: Number of iterations (equals the actual number of function evaluations, default: 100) -.IP \(bu -\fI-bernoulli value\fR: Parameter for random decisions (exploration versus exploitation, default: 0\&.1) -.RE -.PP -.SH REFERENCES -The various algorithms have been described in on-line publications\&. Here are a few: -.IP \(bu -\fIPSO\fR: Maurice Clerc, Standard Particle Swarm Optimisation (2012) -\fIhttps://hal\&.archives-ouvertes\&.fr/file/index/docid/764996/filename/SPSO_descriptions\&.pdf\fR -.sp -Alternatively: \fIhttps://en\&.wikipedia\&.org/wiki/Particle_swarm_optimization\fR -.IP \(bu -\fISCE\fR: Qingyuan Duan, Soroosh Sorooshian, Vijai K\&. Gupta, Optimal use offo the SCE-UA global optimization method for calibrating watershed models -(1994), Journal of Hydrology 158, pp 265-284 -.sp -\fIhttps://www\&.researchgate\&.net/publication/223408756_Optimal_Use_of_the_SCE-UA_Global_Optimization_Method_for_Calibrating_Watershed_Models\fR -.IP \(bu -\fIDE\fR: Rainer Storn and Kenneth Price, Differential Evolution - A simple and efficient adaptivescheme for globaloptimization over continuous spaces -(1996) -.sp -\fIhttp://www1\&.icsi\&.berkeley\&.edu/~storn/TR-95-012\&.pdf\fR -.IP \(bu -\fILIPO\fR: Cedric Malherbe and Nicolas Vayatis, Global optimization of Lipschitz functions, -(june 2017) -.sp -\fIhttps://arxiv\&.org/pdf/1703\&.02628\&.pdf\fR -.PP -.SH KEYWORDS -mathematics, optimisation, probabilistic calculations -.SH CATEGORY -Mathematics Index: idoc/man/files/modules/math/qcomplex.n ================================================================== --- idoc/man/files/modules/math/qcomplex.n +++ idoc/man/files/modules/math/qcomplex.n @@ -555,22 +555,14 @@ bugs and other problems\&. Please report such in the category \fImath :: complexnumbers\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS complex numbers, math .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus .fi DELETED idoc/man/files/modules/math/quasirandom.n Index: idoc/man/files/modules/math/quasirandom.n ================================================================== --- idoc/man/files/modules/math/quasirandom.n +++ idoc/man/files/modules/math/quasirandom.n @@ -1,394 +0,0 @@ -'\" -'\" Generated from file 'quasirandom\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "math::quasirandom" n 1 tcllib "Tcl Math Library" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::quasirandom \- Quasi-random points for integration and Monte Carlo type methods -.SH SYNOPSIS -package require \fBTcl 8\&.5\fR -.sp -package require \fBTclOO \fR -.sp -package require \fBmath::quasirandom 1\fR -.sp -\fB::math::quasirandom::qrpoint create\fR \fINAME\fR \fIDIM\fR ?ARGS? -.sp -\fBgen next\fR -.sp -\fBgen set-start\fR \fIindex\fR -.sp -\fBgen set-evaluations\fR \fInumber\fR -.sp -\fBgen integral\fR \fIfunc\fR \fIminmax\fR \fIargs\fR -.sp -.BE -.SH DESCRIPTION -.PP -In many applications pseudo-random numbers and pseudo-random points in a (limited) -sample space play an important role\&. For instance in any type of Monte Carlo simulation\&. -Pseudo-random numbers, however, may be too random and as a consequence a large -number of data points is required to reduce the error or fluctuation in the results -to the desired value\&. -.PP -Quasi-random numbers can be used as an alternative: instead of "completely" arbitrary -points, points are generated that are diverse enough to cover the entire sample space -in a more or less uniform way\&. As a consequence convergence to the limit can be -much faster, when such quasi-random numbers are well-chosen\&. -.PP -The package defines a \fIclass\fR "qrpoint" that creates a command to generate -quasi-random points in 1, 2 or more dimensions\&. The command can either generate -separate points, so that they can be used in a user-defined algorithm or use these -points to calculate integrals of functions defined over 1, 2 or more dimensions\&. -It also holds several other common algorithms\&. (NOTE: these are not implemented yet) -.PP -One particular characteristic of the generators is that there are no tuning parameters -involved, which makes the use particularly simple\&. -.SH COMMANDS -A quasi-random point generator is created using the \fIqrpoint\fR class: -.TP -\fB::math::quasirandom::qrpoint create\fR \fINAME\fR \fIDIM\fR ?ARGS? -This command takes the following arguments: -.RS -.TP -string \fINAME\fR -The name of the command to be created (alternatively: the \fInew\fR subcommand -will generate a unique name) -.TP -integer/string \fIDIM\fR -The number of dimensions or one of: "circle", "disk", "sphere" or "ball" -.TP -strings \fIARGS\fR -Zero or more key-value pairs\&. The supported options are: -.RS -.IP \(bu -\fI-start index\fR: The index for the next point to be generated (default: 1) -.IP \(bu -\fI-evaluations number\fR: The number of evaluations to be used by default (default: 100) -.RE -.RE -.PP -The points that are returned lie in the hyperblock [0,1[^n (n the number of dimensions) -or on the unit circle, within the unit disk, on the unit sphere or within the unit ball\&. -.PP -Each generator supports the following subcommands: -.TP -\fBgen next\fR -Return the coordinates of the next quasi-random point -.sp -.TP -\fBgen set-start\fR \fIindex\fR -Reset the index for the next quasi-random point\&. This is useful to control which list of points is returned\&. -Returns the new or the current value, if no value is given\&. -.sp -.TP -\fBgen set-evaluations\fR \fInumber\fR -Reset the default number of evaluations in compound algorithms\&. Note that the actual number is the -smallest 4-fold larger or equal to the given number\&. (The 4-fold plays a role in the detailed integration -routine\&.) -.sp -.TP -\fBgen integral\fR \fIfunc\fR \fIminmax\fR \fIargs\fR -Calculate the integral of the given function over the block (or the circle, sphere etc\&.) -.RS -.TP -string \fIfunc\fR -The name of the function to be integrated -.TP -list \fIminmax\fR -List of pairs of minimum and maximum coordinates\&. This can be used to -map the quasi-random coordinates to the desired hyper-block\&. -.sp -If the space is a circle, disk etc\&. then this argument should be a single value, the radius\&. -The circle, disk, etc\&. is centred at the origin\&. If this is not what is required, then a coordinate -transformation should be made within the function\&. -.TP -strings \fIargs\fR -Zero or more key-value pairs\&. The following options are supported: -.RS -.IP \(bu -\fI-evaluations number\fR: The number of evaluations to be used\&. If not specified use the -default of the generator object\&. -.RE -.RE -.PP -.SH TODO -Implement other algorithms and variants -.PP -Implement more unit tests\&. -.PP -Comparison to pseudo-random numbers for integration\&. -.SH REFERENCES -Various algorithms exist for generating quasi-random numbers\&. The generators created in this package are based on: -\fIhttp://extremelearning\&.com\&.au/unreasonable-effectiveness-of-quasirandom-sequences/\fR -.SH KEYWORDS -mathematics, quasi-random -.SH CATEGORY -Mathematics Index: idoc/man/files/modules/math/rational_funcs.n ================================================================== --- idoc/man/files/modules/math/rational_funcs.n +++ idoc/man/files/modules/math/rational_funcs.n @@ -465,22 +465,14 @@ bugs and other problems\&. Please report such in the category \fImath :: rationalfunctions\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS math, rational functions .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2005 Arjen Markus .fi Index: idoc/man/files/modules/math/roman.n ================================================================== --- idoc/man/files/modules/math/roman.n +++ idoc/man/files/modules/math/roman.n @@ -324,22 +324,14 @@ bugs and other problems\&. Please report such in the category \fImath :: roman\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS conversion, integer, roman numeral .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2005 Kenneth Green .fi Index: idoc/man/files/modules/math/romberg.n ================================================================== --- idoc/man/files/modules/math/romberg.n +++ idoc/man/files/modules/math/romberg.n @@ -570,22 +570,14 @@ bugs and other problems\&. Please report such in the category \fImath :: calculus\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" math::calculus, math::interpolate .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Kevin B\&. Kenny \&. All rights reserved\&. Redistribution permitted under the terms of the Open Publication License .fi Index: idoc/man/files/modules/math/special.n ================================================================== --- idoc/man/files/modules/math/special.n +++ idoc/man/files/modules/math/special.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'special\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004 Arjen Markus '\" -.TH "math::special" n 0\&.4 tcllib "Tcl Math Library" +.TH "math::special" n 0\&.3 tcllib "Tcl Math Library" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -272,28 +272,18 @@ .. .BS .SH NAME math::special \- Special mathematical functions .SH SYNOPSIS -package require \fBTcl ?8\&.5?\fR +package require \fBTcl ?8\&.3?\fR .sp -package require \fBmath::special ?0\&.5?\fR -.sp -\fB::math::special::eulerNumber\fR \fIindex\fR -.sp -\fB::math::special::bernoulliNumber\fR \fIindex\fR +package require \fBmath::special ?0\&.3?\fR .sp \fB::math::special::Beta\fR \fIx\fR \fIy\fR .sp -\fB::math::special::incBeta\fR \fIa\fR \fIb\fR \fIx\fR -.sp -\fB::math::special::regIncBeta\fR \fIa\fR \fIb\fR \fIx\fR -.sp \fB::math::special::Gamma\fR \fIx\fR .sp -\fB::math::special::digamma\fR \fIx\fR -.sp \fB::math::special::erf\fR \fIx\fR .sp \fB::math::special::erfc\fR \fIx\fR .sp \fB::math::special::invnorm\fR \fIp\fR @@ -420,15 +410,10 @@ integrals | S | all of R | -- | < 2\&.0e-3 | | | | general | Beta | (see Gamma) | -- | < 1\&.0e-9 | Gamma | x != 0,-1, | -- | < 1\&.0e-9 | | -2, \&.\&.\&. | | - | incBeta | | a, b > 0 | < 1\&.0e-9 - | regIncBeta | | a, b > 0 | < 1\&.0e-9 - | digamma | x != 0,-1 | | < 1\&.0e-9 - | | -2, \&.\&.\&. | | - | | | | | sinc | all of R | -- | exact | | | | orthogonal | Legendre | all of R | n = 0,1,\&.\&.\&. | exact polynomials | Chebyshev | all of R | n = 0,1,\&.\&.\&. | exact | Laguerre | all of R | n = 0,1,\&.\&.\&. | exact @@ -447,34 +432,16 @@ .IP \(bu Bessel functions of arbitrary order (and hence the Airy functions) .IP \(bu Chebyshev polynomials of the second kind (U_n) .IP \(bu -The incomplete gamma function +The digamma function (psi) +.IP \(bu +The incomplete gamma and beta functions .PP .SH PROCEDURES The package defines the following public procedures: -.TP -\fB::math::special::eulerNumber\fR \fIindex\fR -Return the index'th Euler number (note: these are integer values)\&. As the -size of these numbers grows very fast, only a limited number are available\&. -.RS -.TP -int \fIindex\fR -Index of the number to be returned (should be between 0 and 54) -.RE -.sp -.TP -\fB::math::special::bernoulliNumber\fR \fIindex\fR -Return the index'th Bernoulli number\&. As the size of the numbers grows very fast, -only a limited number are available\&. -.RS -.TP -int \fIindex\fR -Index of the number to be returned (should be between 0 and 52) -.RE -.sp .TP \fB::math::special::Beta\fR \fIx\fR \fIy\fR Compute the Beta function for arguments "x" and "y" .RS .TP @@ -483,57 +450,18 @@ .TP float \fIy\fR Second argument for the Beta function .RE .sp -.TP -\fB::math::special::incBeta\fR \fIa\fR \fIb\fR \fIx\fR -Compute the incomplete Beta function for argument "x" with parameters "a" and "b" -.RS -.TP -float \fIa\fR -First parameter for the incomplete Beta function, a > 0 -.TP -float \fIb\fR -Second parameter for the incomplete Beta function, b > 0 -.TP -float \fIx\fR -Argument for the incomplete Beta function -.RE -.sp -.TP -\fB::math::special::regIncBeta\fR \fIa\fR \fIb\fR \fIx\fR -Compute the regularized incomplete Beta function for argument "x" with parameters "a" and "b" -.RS -.TP -float \fIa\fR -First parameter for the incomplete Beta function, a > 0 -.TP -float \fIb\fR -Second parameter for the incomplete Beta function, b > 0 -.TP -float \fIx\fR -Argument for the regularized incomplete Beta function -.RE -.sp .TP \fB::math::special::Gamma\fR \fIx\fR Compute the Gamma function for argument "x" .RS .TP float \fIx\fR Argument for the Gamma function .RE -.sp -.TP -\fB::math::special::digamma\fR \fIx\fR -Compute the digamma function (psi) for argument "x" -.RS -.TP -float \fIx\fR -Argument for the digamma function -.RE .sp .TP \fB::math::special::erf\fR \fIx\fR Compute the error function for argument "x" .RS @@ -847,22 +775,14 @@ bugs and other problems\&. Please report such in the category \fImath :: special\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Bessel functions, error function, math, special functions .SH CATEGORY Mathematics .SH COPYRIGHT .nf Copyright (c) 2004 Arjen Markus .fi Index: idoc/man/files/modules/math/statistics.n ================================================================== --- idoc/man/files/modules/math/statistics.n +++ idoc/man/files/modules/math/statistics.n @@ -271,11 +271,11 @@ .. .BS .SH NAME math::statistics \- Basic statistical functions and procedures .SH SYNOPSIS -package require \fBTcl 8\&.5\fR +package require \fBTcl 8\&.4\fR .sp package require \fBmath::statistics 1\fR .sp \fB::math::statistics::mean\fR \fIdata\fR .sp @@ -313,14 +313,10 @@ .sp \fB::math::statistics::test-Duckworth\fR \fIlist1\fR \fIlist2\fR \fIsignificance\fR .sp \fB::math::statistics::test-anova-F\fR \fIalpha\fR \fIargs\fR .sp -\fB::math::statistics::test-Tukey-range\fR \fIalpha\fR \fIargs\fR -.sp -\fB::math::statistics::test-Dunnett\fR \fIalpha\fR \fIcontrol\fR \fIargs\fR -.sp \fB::math::statistics::quantiles\fR \fIdata\fR \fIconfidence\fR .sp \fB::math::statistics::quantiles\fR \fIlimits\fR \fIcounts\fR \fIconfidence\fR .sp \fB::math::statistics::autocorr\fR \fIdata\fR @@ -349,14 +345,10 @@ .sp \fB::math::statistics::test-Kruskal-Wallis\fR \fIconfidence\fR \fIargs\fR .sp \fB::math::statistics::analyse-Kruskal-Wallis\fR \fIargs\fR .sp -\fB::math::statistics::test-Levene\fR \fIgroups\fR -.sp -\fB::math::statistics::test-Brown-Forsythe\fR \fIgroups\fR -.sp \fB::math::statistics::group-rank\fR \fIargs\fR .sp \fB::math::statistics::test-Wilcoxon\fR \fIsample_a\fR \fIsample_b\fR .sp \fB::math::statistics::spearman-rank\fR \fIsample_a\fR \fIsample_b\fR @@ -363,20 +355,10 @@ .sp \fB::math::statistics::spearman-rank-extended\fR \fIsample_a\fR \fIsample_b\fR .sp \fB::math::statistics::kernel-density\fR \fIdata\fR opt \fI-option value\fR \&.\&.\&. .sp -\fB::math::statistics::bootstrap\fR \fIdata\fR \fIsampleSize\fR ?numberSamples? -.sp -\fB::math::statistics::wasserstein-distance\fR \fIprob1\fR \fIprob2\fR -.sp -\fB::math::statistics::kl-divergence\fR \fIprob1\fR \fIprob2\fR -.sp -\fB::math::statistics::logistic-model\fR \fIxdata\fR \fIydata\fR -.sp -\fB::math::statistics::logistic-probability\fR \fIcoeffs\fR \fIx\fR -.sp \fB::math::statistics::tstat\fR \fIdof\fR ?alpha? .sp \fB::math::statistics::mv-wls\fR \fIwt1\fR \fIweights_and_values\fR .sp \fB::math::statistics::mv-ols\fR \fIvalues\fR @@ -387,14 +369,10 @@ .sp \fB::math::statistics::pdf-exponential\fR \fImean\fR \fIvalue\fR .sp \fB::math::statistics::pdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR .sp -\fB::math::statistics::pdf-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -.sp -\fB::math::statistics::pdf-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -.sp \fB::math::statistics::pdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR .sp \fB::math::statistics::pdf-poisson\fR \fImu\fR \fIk\fR .sp \fB::math::statistics::pdf-chisquare\fR \fIdf\fR \fIvalue\fR @@ -411,28 +389,18 @@ .sp \fB::math::statistics::pdf-pareto\fR \fIscale\fR \fIshape\fR \fIvalue\fR .sp \fB::math::statistics::pdf-cauchy\fR \fIlocation\fR \fIscale\fR \fIvalue\fR .sp -\fB::math::statistics::pdf-laplace\fR \fIlocation\fR \fIscale\fR \fIvalue\fR -.sp -\fB::math::statistics::pdf-kumaraswamy\fR \fIa\fR \fIb\fR \fIvalue\fR -.sp -\fB::math::statistics::pdf-negative-binomial\fR \fIr\fR \fIp\fR \fIvalue\fR -.sp \fB::math::statistics::cdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR .sp \fB::math::statistics::cdf-lognormal\fR \fImean\fR \fIstdev\fR \fIvalue\fR .sp \fB::math::statistics::cdf-exponential\fR \fImean\fR \fIvalue\fR .sp \fB::math::statistics::cdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR .sp -\fB::math::statistics::cdf-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -.sp -\fB::math::statistics::cdf-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -.sp \fB::math::statistics::cdf-students-t\fR \fIdegrees\fR \fIvalue\fR .sp \fB::math::statistics::cdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR .sp \fB::math::statistics::cdf-poisson\fR \fImu\fR \fIk\fR @@ -447,16 +415,10 @@ .sp \fB::math::statistics::cdf-cauchy\fR \fIlocation\fR \fIscale\fR \fIvalue\fR .sp \fB::math::statistics::cdf-F\fR \fInf1\fR \fInf2\fR \fIvalue\fR .sp -\fB::math::statistics::cdf-laplace\fR \fIlocation\fR \fIscale\fR \fIvalue\fR -.sp -\fB::math::statistics::cdf-kumaraswamy\fR \fIa\fR \fIb\fR \fIvalue\fR -.sp -\fB::math::statistics::cdf-negative-binomial\fR \fIr\fR \fIp\fR \fIvalue\fR -.sp \fB::math::statistics::empirical-distribution\fR \fIvalues\fR .sp \fB::math::statistics::random-normal\fR \fImean\fR \fIstdev\fR \fInumber\fR .sp \fB::math::statistics::random-lognormal\fR \fImean\fR \fIstdev\fR \fInumber\fR @@ -463,14 +425,10 @@ .sp \fB::math::statistics::random-exponential\fR \fImean\fR \fInumber\fR .sp \fB::math::statistics::random-uniform\fR \fIxmin\fR \fIxmax\fR \fInumber\fR .sp -\fB::math::statistics::random-triangular\fR \fIxmin\fR \fIxmax\fR \fInumber\fR -.sp -\fB::math::statistics::random-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fInumber\fR -.sp \fB::math::statistics::random-gamma\fR \fIalpha\fR \fIbeta\fR \fInumber\fR .sp \fB::math::statistics::random-poisson\fR \fImu\fR \fInumber\fR .sp \fB::math::statistics::random-chisquare\fR \fIdf\fR \fInumber\fR @@ -485,30 +443,18 @@ .sp \fB::math::statistics::random-pareto\fR \fIscale\fR \fIshape\fR \fInumber\fR .sp \fB::math::statistics::random-cauchy\fR \fIlocation\fR \fIscale\fR \fInumber\fR .sp -\fB::math::statistics::random-laplace\fR \fIlocation\fR \fIscale\fR \fInumber\fR -.sp -\fB::math::statistics::random-kumaraswamy\fR \fIa\fR \fIb\fR \fInumber\fR -.sp -\fB::math::statistics::random-negative-binomial\fR \fIr\fR \fIp\fR \fInumber\fR -.sp \fB::math::statistics::histogram-uniform\fR \fIxmin\fR \fIxmax\fR \fIlimits\fR \fInumber\fR .sp \fB::math::statistics::incompleteGamma\fR \fIx\fR \fIp\fR ?tol? .sp \fB::math::statistics::incompleteBeta\fR \fIa\fR \fIb\fR \fIx\fR ?tol? .sp \fB::math::statistics::estimate-pareto\fR \fIvalues\fR .sp -\fB::math::statistics::estimate-exponential\fR \fIvalues\fR -.sp -\fB::math::statistics::estimate-laplace\fR \fIvalues\fR -.sp -\fB::math::statistics::estimante-negative-binomial\fR \fIr\fR \fIvalues\fR -.sp \fB::math::statistics::filter\fR \fIvarname\fR \fIdata\fR \fIexpression\fR .sp \fB::math::statistics::map\fR \fIvarname\fR \fIdata\fR \fIexpression\fR .sp \fB::math::statistics::samplescount\fR \fIvarname\fR \fIlist\fR \fIexpression\fR @@ -811,17 +757,13 @@ - Significance level (either 0\&.05, 0\&.01 or 0\&.001) .RE .sp .TP \fB::math::statistics::test-anova-F\fR \fIalpha\fR \fIargs\fR -Determine if two or more groups with normally distributed data have the same means\&. -The procedure returns 0 if the means are likely unequal, 1 if they are\&. This is +Determine if two or more groups with normally distributed data have the same variances\&. +The procedure returns 0 if the variances are likely unequal, 1 if they are\&. This is a one-way ANOVA test\&. The groups may also be stored in a nested list: -The procedure returns a list of the comparison results for each pair of groups\&. Each -element of this list contains: the index of the first group and that of the second group, -whether the means are likely to be different (1) or not (0) and the confidence interval -the conclusion is based on\&. The groups may also be stored in a nested list: .CS test-anova-F 0\&.05 $A $B $C # @@ -837,59 +779,15 @@ .TP list \fIargs\fR - Two or more groups of data to be checked .RE .sp -.TP -\fB::math::statistics::test-Tukey-range\fR \fIalpha\fR \fIargs\fR -Determine if two or more groups with normally distributed data have the same means, -using Tukey's range test\&. It is complementary to the ANOVA test\&. -The procedure returns a list of the comparison results for each pair of groups\&. Each -element of this list contains: the index of the first group and that of the second group, -whether the means are likely to be different (1) or not (0) and the confidence interval -the conclusion is based on\&. The groups may also be stored in a nested list, just as with -the ANOVA test\&. -.RS -.TP -float \fIalpha\fR -- Significance level - either 0\&.05 or 0\&.01 -.TP -list \fIargs\fR -- Two or more groups of data to be checked -.RE -.sp -.TP -\fB::math::statistics::test-Dunnett\fR \fIalpha\fR \fIcontrol\fR \fIargs\fR -Determine if one or more groups with normally distributed data have the same means as -the group of control data, using Dunnett's test\&. It is complementary to the ANOVA test\&. -The procedure returns a list of the comparison results for each group with the control group\&. Each -element of this list contains: whether the means are likely to be different (1) or not (0) -and the confidence interval the conclusion is based on\&. The groups may also be stored in a -nested list, just as with the ANOVA test\&. -.sp -Note: some care is required if there is only one group to compare the control with: -.CS - - - test-Dunnett-F 0\&.05 $control [list $A] - -.CE -.IP -Otherwise the group A is split up into groups of one element - this is due to an ambiguity\&. -.RS -.TP -float \fIalpha\fR -- Significance level - either 0\&.05 or 0\&.01 -.TP -list \fIargs\fR -- One or more groups of data to be checked -.RE -.sp .TP \fB::math::statistics::quantiles\fR \fIdata\fR \fIconfidence\fR Return the quantiles for a given set of data .RS +.sp .TP list \fIdata\fR - List of raw data values .sp .TP @@ -1168,35 +1066,10 @@ .TP list \fIargs\fR - Two or more lists of data .RE .sp -.TP -\fB::math::statistics::test-Levene\fR \fIgroups\fR -Compute the Levene statistic to determine if groups of data have the -same variance (are homoscadastic) or not\&. The data are organised -in groups\&. This version uses the mean of the data as the measure -to determine the deviations\&. The statistic is equivalent to an -F statistic with degrees of freedom k-1 and N-k, k being the -number of groups and N the total number of data\&. -.RS -.TP -list \fIgroups\fR -- List of groups of data -.RE -.sp -.TP -\fB::math::statistics::test-Brown-Forsythe\fR \fIgroups\fR -Compute the Brown-Forsythe statistic to determine if groups of data have the -same variance (are homoscadastic) or not\&. Like the Levene test, but this -version uses the median of the data\&. -.RS -.TP -list \fIgroups\fR -- List of groups of data -.RE -.sp .TP \fB::math::statistics::group-rank\fR \fIargs\fR Rank the groups of data with respect to the complete set\&. Returns a list consisting of the group ID, the value and the rank (possibly a rational number, in case of ties) for each data item\&. @@ -1208,11 +1081,11 @@ .sp .TP \fB::math::statistics::test-Wilcoxon\fR \fIsample_a\fR \fIsample_b\fR Compute the Wilcoxon test statistic to determine if two samples have the same median or not\&. (The statistic can be regarded as standard normal, if the -sample sizes are both larger than 10\&.) Returns the value of this statistic\&. +sample sizes are both larger than 10\&. Returns the value of this statistic\&. .RS .TP list \fIsample_a\fR - List of data comprising the first sample .TP @@ -1247,10 +1120,11 @@ list \fIsample_b\fR - Second list of data .RE .TP \fB::math::statistics::kernel-density\fR \fIdata\fR opt \fI-option value\fR \&.\&.\&. +] Return the density function based on kernel density estimation\&. The procedure is controlled by a small set of options, each of which is given a reasonable default\&. .sp The return value consists of three lists: the centres of the bins, the associated probability density and a list of computational parameters (begin and end of the interval, mean and standard @@ -1280,86 +1154,10 @@ \fB-kernel\fR \fIfunction\fR Kernel to be used (One of: gaussian, cosine, epanechnikov, uniform, triangular, biweight, logistic; default: gaussian) .RE .RE -.TP -\fB::math::statistics::bootstrap\fR \fIdata\fR \fIsampleSize\fR ?numberSamples? -Create a subsample or subsamples from a given list of data\&. The data in the samples are chosen -from this list - multiples may occur\&. If there is only one subsample, the sample itself -is returned (as a list of "sampleSize" values), otherwise a list of samples is returned\&. -.RS -.TP -list \fIdata\fR -List of values to chose from -.TP -int \fIsampleSize\fR -Number of values per sample -.TP -int \fInumberSamples\fR -Number of samples (default: 1) -.RE -.TP -\fB::math::statistics::wasserstein-distance\fR \fIprob1\fR \fIprob2\fR -Compute the Wasserstein distance or earth mover's distance for two equidstantly spaced histograms -or probability densities\&. The histograms need not to be normalised to sum to one, -but they must have the same number of entries\&. -.sp -Note: the histograms are assumed to be based on the same equidistant intervals\&. -As the bounds are not passed, the value is expressed in the length of the intervals\&. -.RS -.TP -list \fIprob1\fR -List of values for the first histogram/probability density -.TP -list \fIprob2\fR -List of values for the second histogram/probability density -.RE -.TP -\fB::math::statistics::kl-divergence\fR \fIprob1\fR \fIprob2\fR -Compute the Kullback-Leibler (KL) divergence for two equidstantly spaced histograms -or probability densities\&. The histograms need not to be normalised to sum to one, -but they must have the same number of entries\&. -.sp -Note: the histograms are assumed to be based on the same equidistant intervals\&. -As the bounds are not passed, the value is expressed in the length of the intervals\&. -.sp -Note also that the KL divergence is not symmetric and that the second histogram -should not contain zeroes in places where the first histogram has non-zero values\&. -.RS -.TP -list \fIprob1\fR -List of values for the first histogram/probability density -.TP -list \fIprob2\fR -List of values for the second histogram/probability density -.RE -.TP -\fB::math::statistics::logistic-model\fR \fIxdata\fR \fIydata\fR -Estimate the coefficients of the logistic model that fits the data best\&. The data consist -of independent x-values and the outcome 0 or 1 for each of the x-values\&. The result -can be used to estimate the probability that a certain x-value gives 1\&. -.RS -.TP -list \fIxdata\fR -List of values for which the success (1) or failure (0) is known -.TP -list \fIydata\fR -List of successes or failures corresponding to each value in \fIxdata\fR\&. -.RE -.TP -\fB::math::statistics::logistic-probability\fR \fIcoeffs\fR \fIx\fR -Calculate the probability of success for the value \fIx\fR given the coefficients of the -logistic model\&. -.RS -.TP -list \fIcoeffs\fR -List of coefficients as determine by the \fBlogistic-model\fR command -.TP -float \fIx\fR -X-value for which the probability needs to be determined -.RE .PP .SH "MULTIVARIATE LINEAR REGRESSION" Besides the linear regression with a single independent variable, the statistics package provides two procedures for doing ordinary least squares (OLS) and weighted least squares (WLS) linear regression @@ -1605,44 +1403,10 @@ .TP float \fIvalue\fR - Value for which the probability is required .RE .sp -.TP -\fB::math::statistics::pdf-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -Return the probability of a given value for a triangular -distribution with given extremes\&. If the argument min is lower than the argument max, then smaller -values have higher probability and vice versa\&. In the first case the probability -density function is of the form \fIf(x) = 2(1-x)\fR and the other case it is of the form \fIf(x) = 2x\fR\&. -.RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmin\fR -- Maximum value of the distribution -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::pdf-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -Return the probability of a given value for a symmetric triangular -distribution with given extremes\&. -.RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmin\fR -- Maximum value of the distribution -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp .TP \fB::math::statistics::pdf-gamma\fR \fIalpha\fR \fIbeta\fR \fIvalue\fR Return the probability of a given value for a Gamma distribution with given shape and rate parameters .RS @@ -1791,61 +1555,10 @@ .TP float \fIvalue\fR - Value for which the probability is required .RE .sp -.TP -\fB::math::statistics::pdf-laplace\fR \fIlocation\fR \fIscale\fR \fIvalue\fR -Return the probability of a given value for a Laplace -distribution with given location and shape parameters\&. The Laplace distribution -consists of two exponential functions, is peaked and has heavier tails than the -normal distribution\&. -.RS -.TP -float \fIlocation\fR -- Location parameter (mean) -.TP -float \fIscale\fR -- Shape parameter -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::pdf-kumaraswamy\fR \fIa\fR \fIb\fR \fIvalue\fR -Return the probability of a given value for a Kumaraswamy -distribution with given parameters a and b\&. The Kumaraswamy distribution -is related to the Beta distribution, but has a tractable cumulative distribution function\&. -.RS -.TP -float \fIa\fR -- Parameter a -.TP -float \fIb\fR -- Parameter b -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::pdf-negative-binomial\fR \fIr\fR \fIp\fR \fIvalue\fR -Return the probability of a given value for a negative binomial -distribution with an allowed number of failures and the probability of success\&. -.RS -.TP -int \fIr\fR -- Allowed number of failures (at least 1) -.TP -float \fIp\fR -- Probability of success -.TP -int \fIvalue\fR -- Number of successes for which the probability is to be returned -.RE -.sp .TP \fB::math::statistics::cdf-normal\fR \fImean\fR \fIstdev\fR \fIvalue\fR Return the cumulative probability of a given value for a normal distribution with given mean and standard deviation, that is the probability for values up to the given one\&. @@ -1894,43 +1607,10 @@ .TP \fB::math::statistics::cdf-uniform\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR Return the cumulative probability of a given value for a uniform distribution with given extremes\&. .RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmin\fR -- Maximum value of the distribution -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::cdf-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -Return the cumulative probability of a given value for a triangular -distribution with given extremes\&. If xmin < xmax, then lower values have -a higher probability and vice versa, see also \fIpdf-triangular\fR -.RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmin\fR -- Maximum value of the distribution -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::cdf-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fIvalue\fR -Return the cumulative probability of a given value for a symmetric triangular -distribution with given extremes\&. -.RS .TP float \fIxmin\fR - Minimum value of the distribution .TP float \fIxmin\fR @@ -2076,61 +1756,10 @@ .TP float \fIvalue\fR - Value for which the probability is required .RE .sp -.TP -\fB::math::statistics::cdf-laplace\fR \fIlocation\fR \fIscale\fR \fIvalue\fR -Return the cumulative probability of a given value for a Laplace -distribution with given location and shape parameters\&. The Laplace distribution -consists of two exponential functions, is peaked and has heavier tails than the -normal distribution\&. -.RS -.TP -float \fIlocation\fR -- Location parameter (mean) -.TP -float \fIscale\fR -- Shape parameter -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::cdf-kumaraswamy\fR \fIa\fR \fIb\fR \fIvalue\fR -Return the cumulative probability of a given value for a Kumaraswamy -distribution with given parameters a and b\&. The Kumaraswamy distribution -is related to the Beta distribution, but has a tractable cumulative distribution function\&. -.RS -.TP -float \fIa\fR -- Parameter a -.TP -float \fIb\fR -- Parameter b -.TP -float \fIvalue\fR -- Value for which the probability is required -.RE -.sp -.TP -\fB::math::statistics::cdf-negative-binomial\fR \fIr\fR \fIp\fR \fIvalue\fR -Return the cumulative probability of a given value for a negative binomial -distribution with an allowed number of failures and the probability of success\&. -.RS -.TP -int \fIr\fR -- Allowed number of failures (at least 1) -.TP -float \fIp\fR -- Probability of success -.TP -int \fIvalue\fR -- Greatest number of successes -.RE -.sp .TP \fB::math::statistics::empirical-distribution\fR \fIvalues\fR Return a list of values and their empirical probability\&. The values are sorted in increasing order\&. (The implementation follows the description at the corresponding Wikipedia page) .RS @@ -2187,43 +1816,10 @@ .TP \fB::math::statistics::random-uniform\fR \fIxmin\fR \fIxmax\fR \fInumber\fR Return a list of "number" random values satisfying a uniform distribution with given extremes\&. .RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmax\fR -- Maximum value of the distribution -.TP -int \fInumber\fR -- Number of values to be returned -.RE -.sp -.TP -\fB::math::statistics::random-triangular\fR \fIxmin\fR \fIxmax\fR \fInumber\fR -Return a list of "number" random values satisfying a triangular -distribution with given extremes\&. If xmin < xmax, then lower values have a higher probability -and vice versa (see also \fIpdf-triangular\fR\&. -.RS -.TP -float \fIxmin\fR -- Minimum value of the distribution -.TP -float \fIxmax\fR -- Maximum value of the distribution -.TP -int \fInumber\fR -- Number of values to be returned -.RE -.sp -.TP -\fB::math::statistics::random-symmetric-triangular\fR \fIxmin\fR \fIxmax\fR \fInumber\fR -Return a list of "number" random values satisfying a symmetric triangular -distribution with given extremes\&. -.RS .TP float \fIxmin\fR - Minimum value of the distribution .TP float \fIxmax\fR @@ -2366,60 +1962,10 @@ .TP int \fInumber\fR - Number of values to be returned .RE .sp -.TP -\fB::math::statistics::random-laplace\fR \fIlocation\fR \fIscale\fR \fInumber\fR -Return a list of "number" random values satisfying a Laplace -distribution with given location and shape parameters\&. The Laplace distribution -consists of two exponential functions, is peaked and has heavier tails than the -normal distribution\&. -.RS -.TP -float \fIlocation\fR -- Location parameter (mean) -.TP -float \fIscale\fR -- Shape parameter -.TP -int \fInumber\fR -- Number of values to be returned -.RE -.sp -.TP -\fB::math::statistics::random-kumaraswamy\fR \fIa\fR \fIb\fR \fInumber\fR -Return a list of "number" random values satisying a Kumaraswamy -distribution with given parameters a and b\&. The Kumaraswamy distribution -is related to the Beta distribution, but has a tractable cumulative distribution function\&. -.RS -.TP -float \fIa\fR -- Parameter a -.TP -float \fIb\fR -- Parameter b -.TP -int \fInumber\fR -- Number of values to be returned -.RE -.sp -.TP -\fB::math::statistics::random-negative-binomial\fR \fIr\fR \fIp\fR \fInumber\fR -Return a list of "number" random values satisying a negative binomial distribution\&. -.RS -.TP -int \fIr\fR -- Allowed number of failures (at least 1) -.TP -float \fIp\fR -- Probability of success -.TP -int \fInumber\fR -- Number of values to be returned -.RE -.sp .TP \fB::math::statistics::histogram-uniform\fR \fIxmin\fR \fIxmax\fR \fIlimits\fR \fInumber\fR Return the expected histogram for a uniform distribution\&. .RS .TP @@ -2484,43 +2030,10 @@ .RS .TP list \fIvalues\fR - List of values, assumed to be distributed according to a Pareto distribution .RE -.sp -.TP -\fB::math::statistics::estimate-exponential\fR \fIvalues\fR -Estimate the parameter for the exponential distribution that comes closest to the given values\&. -Returns an estimate of the one parameter and of the standard error\&. -.RS -.TP -list \fIvalues\fR -- List of values, assumed to be distributed according to an exponential distribution -.RE -.sp -.TP -\fB::math::statistics::estimate-laplace\fR \fIvalues\fR -Estimate the parameters for the Laplace distribution that comes closest to the given values\&. -Returns an estimate of respectively the location and scale parameters, based on maximum likelihood\&. -.RS -.TP -list \fIvalues\fR -- List of values, assumed to be distributed according to an exponential distribution -.RE -.sp -.TP -\fB::math::statistics::estimante-negative-binomial\fR \fIr\fR \fIvalues\fR -Estimate the probability of success for the negative binomial distribution that comes closest to the given values\&. -The allowed number of failures must be given\&. -.RS -.TP -int \fIr\fR -- Allowed number of failures (at least 1) -.TP -int \fInumber\fR -- List of values, assumed to be distributed according to a negative binomial distribution\&. -.RE .sp .PP TO DO: more function descriptions to be added .SH "DATA MANIPULATION" The data manipulation procedures act on lists or lists of lists: @@ -2859,17 +2372,9 @@ bugs and other problems\&. Please report such in the category \fImath :: statistics\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS data analysis, mathematics, statistics .SH CATEGORY Mathematics Index: idoc/man/files/modules/math/symdiff.n ================================================================== --- idoc/man/files/modules/math/symdiff.n +++ idoc/man/files/modules/math/symdiff.n @@ -355,21 +355,13 @@ bugs and other problems\&. Please report such in the category \fImath :: calculus\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" math::calculus, math::interpolate .SH COPYRIGHT .nf Copyright (c) 2010 by Kevin B\&. Kenny Redistribution permitted under the terms of the Open Publication License .fi DELETED idoc/man/files/modules/math/trig.n Index: idoc/man/files/modules/math/trig.n ================================================================== --- idoc/man/files/modules/math/trig.n +++ idoc/man/files/modules/math/trig.n @@ -1,557 +0,0 @@ -'\" -'\" Generated from file 'trig\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2018 Arjen Markus -'\" -.TH "math::trig" n 1\&.0\&.0 tcllib "Tcl Math Library" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -math::trig \- Trigonometric anf hyperbolic functions -.SH SYNOPSIS -package require \fBTcl 8\&.5\fR -.sp -package require \fBmath::trig 1\&.0\&.0\fR -.sp -\fB::math::trig::radian_reduced\fR \fIangle\fR -.sp -\fB::math::trig::degree_reduced\fR \fIangle\fR -.sp -\fB::math::trig::cosec\fR \fIangle\fR -.sp -\fB::math::trig::sec\fR \fIangle\fR -.sp -\fB::math::trig::cotan\fR \fIangle\fR -.sp -\fB::math::trig::acosec\fR \fIvalue\fR -.sp -\fB::math::trig::asec\fR \fIvalue\fR -.sp -\fB::math::trig::acotan\fR \fIvalue\fR -.sp -\fB::math::trig::cosech\fR \fIvalue\fR -.sp -\fB::math::trig::sech\fR \fIvalue\fR -.sp -\fB::math::trig::cotanh\fR \fIvalue\fR -.sp -\fB::math::trig::asinh\fR \fIvalue\fR -.sp -\fB::math::trig::acosh\fR \fIvalue\fR -.sp -\fB::math::trig::atanh\fR \fIvalue\fR -.sp -\fB::math::trig::acosech\fR \fIvalue\fR -.sp -\fB::math::trig::asech\fR \fIvalue\fR -.sp -\fB::math::trig::acotanh\fR \fIvalue\fR -.sp -\fB::math::trig::sind\fR \fIangle\fR -.sp -\fB::math::trig::cosd\fR \fIangle\fR -.sp -\fB::math::trig::tand\fR \fIangle\fR -.sp -\fB::math::trig::cosecd\fR \fIangle\fR -.sp -\fB::math::trig::secd\fR \fIangle\fR -.sp -\fB::math::trig::cotand\fR \fIangle\fR -.sp -.BE -.SH DESCRIPTION -.PP -The \fImath::trig\fR package defines a set of trigonomic and hyperbolic functions -and their inverses\&. In addition it defines versions of the trigonomic functions -that take arguments in degrees instead of radians\&. -.PP -For easy use these functions may be imported into the \fItcl::mathfunc\fR namespace, -so that they can be used directly in the \fIexpr\fR command\&. -.SH FUNCTIONS -The functions \fIradian_reduced\fR and \fIdegree_reduced\fR return a reduced angle, in -respectively radians and degrees, in the intervals [0, 2pi) and [0, 360): -.TP -\fB::math::trig::radian_reduced\fR \fIangle\fR -Return the equivalent angle in the interval [0, 2pi)\&. -.RS -.TP -float \fIangle\fR -Angle (in radians) -.RE -.TP -\fB::math::trig::degree_reduced\fR \fIangle\fR -Return the equivalent angle in the interval [0, 360)\&. -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.PP -The following trigonomic functions are defined in addition to the ones defined -in the \fIexpr\fR command: -.TP -\fB::math::trig::cosec\fR \fIangle\fR -Calculate the cosecant of the angle (1/cos(angle)) -.RS -.TP -float \fIangle\fR -Angle (in radians) -.RE -.TP -\fB::math::trig::sec\fR \fIangle\fR -Calculate the secant of the angle (1/sin(angle)) -.RS -.TP -float \fIangle\fR -Angle (in radians) -.RE -.TP -\fB::math::trig::cotan\fR \fIangle\fR -Calculate the cotangent of the angle (1/tan(angle)) -.RS -.TP -float \fIangle\fR -Angle (in radians) -.RE -.PP -For these functions also the inverses are defined: -.TP -\fB::math::trig::acosec\fR \fIvalue\fR -Calculate the arc cosecant of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::asec\fR \fIvalue\fR -Calculate the arc secant of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::acotan\fR \fIvalue\fR -Calculate the arc cotangent of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.PP -The following hyperbolic and inverse hyperbolic functions are defined: -.TP -\fB::math::trig::cosech\fR \fIvalue\fR -Calculate the hyperbolic cosecant of the value (1/sinh(value)) -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::sech\fR \fIvalue\fR -Calculate the hyperbolic secant of the value (1/cosh(value)) -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::cotanh\fR \fIvalue\fR -Calculate the hyperbolic cotangent of the value (1/tanh(value)) -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::asinh\fR \fIvalue\fR -Calculate the arc hyperbolic sine of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::acosh\fR \fIvalue\fR -Calculate the arc hyperbolic cosine of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::atanh\fR \fIvalue\fR -Calculate the arc hyperbolic tangent of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::acosech\fR \fIvalue\fR -Calculate the arc hyperbolic cosecant of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::asech\fR \fIvalue\fR -Calculate the arc hyperbolic secant of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.TP -\fB::math::trig::acotanh\fR \fIvalue\fR -Calculate the arc hyperbolic cotangent of the value -.RS -.TP -float \fIvalue\fR -Value of the argument -.RE -.PP -The following versions of the common trigonometric functions and their -inverses are defined: -.TP -\fB::math::trig::sind\fR \fIangle\fR -Calculate the sine of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.TP -\fB::math::trig::cosd\fR \fIangle\fR -Calculate the cosine of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in radians) -.RE -.TP -\fB::math::trig::tand\fR \fIangle\fR -Calculate the cotangent of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.TP -\fB::math::trig::cosecd\fR \fIangle\fR -Calculate the cosecant of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.TP -\fB::math::trig::secd\fR \fIangle\fR -Calculate the secant of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.TP -\fB::math::trig::cotand\fR \fIangle\fR -Calculate the cotangent of the angle (in degrees) -.RS -.TP -float \fIangle\fR -Angle (in degrees) -.RE -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fImath :: trig\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -math, trigonometry -.SH CATEGORY -Mathematics -.SH COPYRIGHT -.nf -Copyright (c) 2018 Arjen Markus - -.fi Index: idoc/man/files/modules/md4/md4.n ================================================================== --- idoc/man/files/modules/md4/md4.n +++ idoc/man/files/modules/md4/md4.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'md4\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003, Pat Thoyts '\" -.TH "md4" n 1\&.0\&.7 tcllib "MD4 Message-Digest Algorithm" +.TH "md4" n 1\&.0\&.6 tcllib "MD4 Message-Digest Algorithm" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME md4 \- MD4 Message-Digest Algorithm .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBmd4 ?1\&.0\&.7?\fR +package require \fBmd4 ?1\&.0\&.6?\fR .sp \fB::md4::md4\fR ?\fI-hex\fR? [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] .sp \fB::md4::hmac\fR ?\fI-hex\fR? \fI-key key\fR [ \fI-channel channel\fR | \fI-file filename\fR | \fIstring\fR ] .sp @@ -415,18 +415,10 @@ bugs and other problems\&. Please report such in the category \fImd4\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md5, sha1 .SH KEYWORDS hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security .SH CATEGORY Index: idoc/man/files/modules/md5/md5.n ================================================================== --- idoc/man/files/modules/md5/md5.n +++ idoc/man/files/modules/md5/md5.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'md5\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003, Pat Thoyts '\" -.TH "md5" n 2\&.0\&.8 tcllib "MD5 Message-Digest Algorithm" +.TH "md5" n 2\&.0\&.7 tcllib "MD5 Message-Digest Algorithm" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -421,18 +421,10 @@ bugs and other problems\&. Please report such in the category \fImd5\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md4, sha1 .SH KEYWORDS hashing, md5, message-digest, rfc 1320, rfc 1321, rfc 2104, security .SH CATEGORY Index: idoc/man/files/modules/md5crypt/md5crypt.n ================================================================== --- idoc/man/files/modules/md5crypt/md5crypt.n +++ idoc/man/files/modules/md5crypt/md5crypt.n @@ -349,18 +349,10 @@ bugs and other problems\&. Please report such in the category \fImd5crypt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md5 .SH KEYWORDS hashing, md5, md5crypt, message-digest, security .SH CATEGORY Index: idoc/man/files/modules/mime/mime.n ================================================================== --- idoc/man/files/modules/mime/mime.n +++ idoc/man/files/modules/mime/mime.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'mime\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 1999-2000 Marshall T\&. Rose '\" -.TH "mime" n 1\&.6\&.3 tcllib "Mime" +.TH "mime" n 1\&.6 tcllib "Mime" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME mime \- Manipulation of MIME body parts .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBmime ?1\&.6\&.3?\fR +package require \fBmime ?1\&.6?\fR .sp \fB::mime::initialize\fR ?\fB-canonical\fR \fItype/subtype\fR ?\fB-param\fR {\fIkey value\fR}\&.\&.\&.? ?\fB-encoding\fR \fIvalue\fR? ?\fB-header\fR {\fIkey value\fR}\&.\&.\&.?? (\fB-file\fR \fIname\fR | \fB-string\fR \fIvalue\fR | \fB-parts\fR {\fItoken1\fR \&.\&.\&. \fItokenN\fR}) .sp \fB::mime::finalize\fR \fItoken\fR ?\fB-subordinates\fR \fBall\fR | \fBdynamic\fR | \fBnone\fR? .sp @@ -584,18 +584,10 @@ bugs and other problems\&. Please report such in the category \fImime\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" ftp, http, pop3, smtp .SH KEYWORDS email, internet, mail, mime, net, rfc 2045, rfc 2046, rfc 2049, rfc 821, rfc 822, smtp .SH CATEGORY Index: idoc/man/files/modules/mime/smtp.n ================================================================== --- idoc/man/files/modules/mime/smtp.n +++ idoc/man/files/modules/mime/smtp.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'smtp\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 1999-2000 Marshall T\&. Rose and others '\" -.TH "smtp" n 1\&.5 tcllib "smtp client" +.TH "smtp" n 1\&.4\&.5 tcllib "smtp client" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -276,11 +276,11 @@ .SH SYNOPSIS package require \fBTcl \fR .sp package require \fBmime ?1\&.5\&.4?\fR .sp -package require \fBsmtp ?1\&.5?\fR +package require \fBsmtp ?1\&.4\&.5?\fR .sp \fB::smtp::sendmessage\fR \fItoken\fR \fIoption\fR\&.\&.\&. .sp .BE .SH DESCRIPTION @@ -294,22 +294,13 @@ of options and their associated values\&. The recognized options are: .RS .TP \fB-servers\fR A list of SMTP servers\&. The default is \fBlocalhost\fR\&. -.sp -If multiple servers are specified they are tried in sequence\&. -Note that the \fB-ports\fR are iterated over in tandem with the -servers\&. If there are not enough ports for the number of servers the -default port (see below) is used\&. If there are more ports than servers -the superfluous ports are ignored\&. .TP \fB-ports\fR A list of SMTP ports\&. The default is \fB25\fR\&. -.sp -See option \fB-servers\fR above regardig the behaviour for -then multiple servers and ports are specified\&. .TP \fB-client\fR The name to use as our hostname when connecting to the server\&. By default this is either localhost if one of the servers is localhost, or is set to the string returned by \fBinfo hostname\fR\&. @@ -338,17 +329,10 @@ .TP \fB-usetls\fR This package supports the RFC 3207 TLS extension (3) by default provided the tls package is available\&. You can turn this off with this boolean option\&. .TP -\fB-tlsimport\fR -This boolean flag is \fBfalse\fR by default\&. -When this flag is set the package will import TLS on a sucessfully -opened channel\&. This is needed for connections using native TLS -negotiation instead of \fBSTARTTLS\fR\&. The \fBtls\fR package -is automatically required when needed\&. -.TP \fB-tlspolicy\fR This option lets you specify a command to be called if an error occurs during TLS setup\&. The command is called with the SMTP code and diagnostic message appended\&. The command should return 'secure' or 'insecure' where insecure will cause the package to continue on the unencrypted channel\&. @@ -405,26 +389,25 @@ proc send_simple_message {recipient email_server subject body} { package require smtp package require mime - set token [mime::initialize -canonical text/plain \\ + set token [mime::initialize -canonical text/plain \\\\ -string $body] mime::setheader $token Subject $subject - smtp::sendmessage $token \\ + smtp::sendmessage $token \\\\ -recipients $recipient -servers $email_server mime::finalize $token } -send_simple_message someone@somewhere\&.com localhost \\ +send_simple_message someone@somewhere\&.com localhost \\\\ "This is the subject\&." "This is the message\&." .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -468,18 +451,10 @@ bugs and other problems\&. Please report such in the category \fIsmtp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" ftp, http, mime, pop3 .SH KEYWORDS email, internet, mail, mime, net, rfc 2554, rfc 2821, rfc 3207, rfc 821, rfc 822, smtp, tls .SH CATEGORY Index: idoc/man/files/modules/multiplexer/multiplexer.n ================================================================== --- idoc/man/files/modules/multiplexer/multiplexer.n +++ idoc/man/files/modules/multiplexer/multiplexer.n @@ -397,17 +397,9 @@ bugs and other problems\&. Please report such in the category \fImultiplexer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS chat, multiplexer .SH CATEGORY Programming tools Index: idoc/man/files/modules/namespacex/namespacex.n ================================================================== --- idoc/man/files/modules/namespacex/namespacex.n +++ idoc/man/files/modules/namespacex/namespacex.n @@ -2,11 +2,11 @@ '\" Generated from file 'namespacex\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 200? Neil Madden (http://wiki\&.tcl\&.tk/12790) '\" Copyright (c) 200? Various (http://wiki\&.tcl\&.tk/1489) '\" Copyright (c) 2010 Documentation, Andreas Kupries '\" -.TH "namespacex" n 0\&.2 tcllib "Namespace utility commands" +.TH "namespacex" n 0\&.1 tcllib "Namespace utility commands" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -276,179 +276,82 @@ .SH NAME namespacex \- Namespace utility commands .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBnamespacex ?0\&.2?\fR +package require \fBnamespacex ?0\&.1?\fR .sp \fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR .sp \fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR .sp \fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR .sp \fB::namespacex hook next\fR \fIarg\fR\&.\&.\&. .sp -\fB::namespacex import fromns\fR \fIcmdname ?\fInewname\fR \&.\&.\&.?\fR -.sp \fB::namespacex info allchildren\fR \fInamespace\fR .sp \fB::namespacex info allvars\fR \fInamespace\fR .sp -\fB::namespacex normalize\fR \fInamespace\fR -.sp \fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR? .sp \fB::namespacex state get\fR \fInamespace\fR .sp \fB::namespacex state set\fR \fInamespace\fR \fIdict\fR .sp \fB::namespacex state drop\fR \fInamespace\fR .sp -\fB::namespacex strip\fR \fIprefix\fR \fInamespaces\fR -.sp .BE .SH DESCRIPTION This package provides a number of utility commands for working with namespaces\&. -The commands fall into four categories: -.IP [1] -Hook commands provide and manipulate a chain of commands which -replaces the single regular \fBnamespace unknown\fR handler\&. -.IP [2] -An import command provides the ability to import any command -from another namespace\&. -.IP [3] -Information commands allow querying of variables and child -namespaces\&. -.IP [4] -State commands provide a means to serialize variable values in -a namespace\&. -.PP -.SH COMMANDS +.SH API .TP \fB::namespacex hook add\fR ?\fInamespace\fR? \fIcmdprefix\fR -Adds the \fIcmdprefix\fR to the chain of unknown command handlers that -are invoked when the \fInamespace\fR would otherwise invoke its -unknown handler\&. -If \fInamespace\fR is not specified, then \fIcmdprefix\fR is added to -the chain of handlers for the namespace of the caller\&. -.sp -The chain of \fIcmdprefix\fR are executed in reverse order of -addition, \fIi\&.e\&.\fR the most recently added \fIcmdprefix\fR is -executed first\&. -When executed, \fIcmdprefix\fR has additional arguments appended to it -as would any namespace unknown handler\&. .TP \fB::namespacex hook proc\fR ?\fInamespace\fR? \fIarguments\fR \fIbody\fR -Adds an anonymous procedure to the chain of namespace unknown handlers -for the \fInamespace\fR\&. -.sp -If \fInamespace\fR is not specified, then the handler is added -to the chain of handlers for the namespace of the caller\&. -.sp -The \fIarguments\fR and \fIbody\fR are specified as for the -core \fBproc\fR command\&. .TP \fB::namespacex hook on\fR ?\fInamespace\fR? \fIguardcmdprefix\fR \fIactioncmdprefix\fR -Adds a guarded action to the chain of namespace unknown handlers for -the \fInamespace\fR\&. -.sp -If \fInamespace\fR is not specified, then the handler is added -to the chain of handlers for the namespace of the caller\&. -.sp -The \fIguardcmdprefix\fR is executed first\&. If it returns a -value that can be interpreted as false, then the next unknown hander -in the chain is executed\&. Otherwise, \fIactioncmdprefix\fR is executed -and the return value of the handler is the value returned by -\fIactioncmdprefix\fR\&. -.sp -When executed, both \fIguardcmdprefix\fR and -\fIactioncmdprefix\fR have the same additional arguments appended as -for any namespace unknown handler\&. .TP \fB::namespacex hook next\fR \fIarg\fR\&.\&.\&. -This command is available to namespace hooks to execute the next hook -in the chain of handlers for the namespace\&. -.TP -\fB::namespacex import fromns\fR \fIcmdname ?\fInewname\fR \&.\&.\&.?\fR -Imports the command \fIcmdname\fR from the \fIfromns\fR namespace into -the namespace of the caller\&. -The \fIcmdname\fR command is imported even if the \fIfromns\fR did not -originally export the command\&. -.sp -If \fInewname\fR is specified, then the imported command will -be known by that name\&. Otherwise, the command retains is original name -as given by \fIcmdname\fR\&. -.sp -Additional pairs of \fIcmdname\fR / \fInewname\fR arguments may -also be specified\&. .TP \fB::namespacex info allchildren\fR \fInamespace\fR -Returns a list containing the names of all child namespaces in the -specified \fInamespace\fR and its children\&. The names are all fully -qualified\&. +This command returns a list containing the names of all child +namespaces in the specified \fInamespace\fR and its children\&. The +names are all fully qualified\&. .TP \fB::namespacex info allvars\fR \fInamespace\fR -Returns a list containing the names of all variables in the specified -\fInamespace\fR and its children\&. The names are all given relative to -\fInamespace\fR, and \fInot\fR fully qualified\&. -.TP -\fB::namespacex normalize\fR \fInamespace\fR -Returns the absolute name of \fInamespace\fR, which is resolved -relative to the namespace of the caller, with all unneeded colon -characters removed\&. +This command returns a list containing the names of all variables in +the specified \fInamespace\fR and its children\&. The names are all +relative to \fInamespace\fR, and \fInot\fR fully qualified\&. .TP \fB::namespacex info vars\fR \fInamespace\fR ?\fIpattern\fR? -Returns a list containing the names of all variables in +This command returns a list containing the names of all variables in the specified \fInamespace\fR\&. -If the \fIpattern\fR argument is specified, then only variables -matching \fIpattern\fR are returned\&. Matching is determined using the -same rules as for \fBstring match\fR\&. .TP \fB::namespacex state get\fR \fInamespace\fR -Returns a dictionary holding the names and values of all variables in -the specified \fInamespace\fR and its child namespaces\&. +This command returns a dictionary holding the names and values of all +variables in the specified \fInamespace\fR and its child namespaces\&. .sp -Note that the names are all relative to \fInamespace\fR, and -\fInot\fR fully qualified\&. +Note that the names are all relative to \fInamespace\fR, +and \fInot\fR fully qualified\&. .TP \fB::namespacex state set\fR \fInamespace\fR \fIdict\fR -Takes a dictionary holding the names and values for a set of variables -and replaces the current state of the specified \fInamespace\fR and -its child namespaces with this state\&. +This command takes a dictionary holding the names and values for a set +of variables and replaces the current state of the specified +\fInamespace\fR and its child namespaces with this state\&. The result of the command is the empty string\&. .TP \fB::namespacex state drop\fR \fInamespace\fR -Unsets all variables in the specified \fInamespace\fR and its child -namespaces\&. +This command unsets all variables in the specified \fInamespace\fR and +its child namespaces\&. The result of the command is the empty string\&. -.TP -\fB::namespacex strip\fR \fIprefix\fR \fInamespaces\fR -Each item in \fInamespaces\fR must be the absolute normalized name of -a child namespace of namespace \fIprefix\fR\&. -Returns the corresponding list of relative names of child namespaces\&. -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fInamespacex\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. +.PP .SH KEYWORDS extended namespace, info, namespace unknown, namespace utilities, state (de)serialization, unknown hooking, utilities .SH COPYRIGHT .nf Copyright (c) 200? Neil Madden (http://wiki\&.tcl\&.tk/12790) Copyright (c) 200? Various (http://wiki\&.tcl\&.tk/1489) Copyright (c) 2010 Documentation, Andreas Kupries .fi Index: idoc/man/files/modules/ncgi/ncgi.n ================================================================== --- idoc/man/files/modules/ncgi/ncgi.n +++ idoc/man/files/modules/ncgi/ncgi.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'ncgi\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "ncgi" n 1\&.4\&.4 tcllib "CGI Support" +.TH "ncgi" n 1\&.4\&.3 tcllib "CGI Support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME ncgi \- Procedures to manipulate CGI values\&. .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBncgi ?1\&.4\&.4?\fR +package require \fBncgi ?1\&.4\&.3?\fR .sp \fB::ncgi::cookie\fR \fIcookie\fR .sp \fB::ncgi::decode\fR \fIstr\fR .sp @@ -580,19 +580,11 @@ bugs and other problems\&. Please report such in the category \fIncgi\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" html .SH KEYWORDS CGI, cookie, form, html .SH CATEGORY CGI programming Index: idoc/man/files/modules/nettool/nettool.n ================================================================== --- idoc/man/files/modules/nettool/nettool.n +++ idoc/man/files/modules/nettool/nettool.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'nettool\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2015-2018 Sean Woods +'\" Copyright (c) 2015 Sean Woods '\" -.TH "nettool" n 0\&.5\&.2 tcllib "nettool" +.TH "nettool" n 0\&.5\&.1 tcllib "nettool" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME nettool \- Tools for networked applications .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBnettool ?0\&.5\&.2?\fR +package require \fBnettool ?0\&.5\&.1?\fR .sp package require \fBtwapi 3\&.1\fR .sp package require \fBip 0\&.1\fR .sp @@ -439,22 +439,14 @@ bugs and other problems\&. Please report such in the category \fIodie\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS nettool, odie .SH CATEGORY System .SH COPYRIGHT .nf -Copyright (c) 2015-2018 Sean Woods +Copyright (c) 2015 Sean Woods .fi Index: idoc/man/files/modules/nmea/nmea.n ================================================================== --- idoc/man/files/modules/nmea/nmea.n +++ idoc/man/files/modules/nmea/nmea.n @@ -397,22 +397,14 @@ bugs and other problems\&. Please report such in the category \fInmea\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS gps, nmea .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2006-2009, Aaron Faupell .fi Index: idoc/man/files/modules/nns/nns_auto.n ================================================================== --- idoc/man/files/modules/nns/nns_auto.n +++ idoc/man/files/modules/nns/nns_auto.n @@ -357,18 +357,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv(n) .SH KEYWORDS automatic, client, name service, reconnect, restore .SH CATEGORY Index: idoc/man/files/modules/nns/nns_client.n ================================================================== --- idoc/man/files/modules/nns/nns_client.n +++ idoc/man/files/modules/nns/nns_client.n @@ -404,11 +404,11 @@ options, and their current values\&. The list of supported options and their meaning can be found in section \fBOPTIONS\fR\&. .TP \fB::nameserv::configure\fR \fB-option\fR In this form the command is an alias for -"\fB::nameserv::cget\fR \fB-option\fR"\&. +"\fB::nameserv::cget\fR \fB-option\fR]"\&. The list of supported options and their meaning can be found in section \fBOPTIONS\fR\&. .TP \fB::nameserv::configure\fR \fB-option\fR \fIvalue\fR\&.\&.\&. In this form the command is used to configure one or more of the @@ -572,18 +572,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv::common(n), nameserv::server(n) .SH KEYWORDS client, name service .SH CATEGORY Index: idoc/man/files/modules/nns/nns_common.n ================================================================== --- idoc/man/files/modules/nns/nns_common.n +++ idoc/man/files/modules/nns/nns_common.n @@ -306,18 +306,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv::client(n), nameserv::server(n) .SH KEYWORDS client, name service, server .SH CATEGORY Index: idoc/man/files/modules/nns/nns_intro.n ================================================================== --- idoc/man/files/modules/nns/nns_intro.n +++ idoc/man/files/modules/nns/nns_intro.n @@ -353,18 +353,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv(n), nameserv::auto(n), nameserv::common(n), nameserv::protocol(n), nameserv::server(n), nnsd(n), nss(n) .SH KEYWORDS client, name service, server .SH CATEGORY Index: idoc/man/files/modules/nns/nns_protocol.n ================================================================== --- idoc/man/files/modules/nns/nns_protocol.n +++ idoc/man/files/modules/nns/nns_protocol.n @@ -413,18 +413,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" comm_wire(n), nameserv(n), nameserv::server(n) .SH KEYWORDS comm, name service, protocol .SH CATEGORY Index: idoc/man/files/modules/nns/nns_server.n ================================================================== --- idoc/man/files/modules/nns/nns_server.n +++ idoc/man/files/modules/nns/nns_server.n @@ -346,11 +346,11 @@ options, and their current values\&. The list of supported options and their meaning can be found in section \fBOPTIONS\fR\&. .TP \fB::nameserv::server::configure\fR \fB-option\fR In this form the command is an alias for -"\fB::nameserv::server::cget\fR \fB-option\fR"\&. +"\fB::nameserv::server::cget\fR \fB-option\fR]"\&. The list of supported options and their meaning can be found in section \fBOPTIONS\fR\&. .TP \fB::nameserv::server::configure\fR \fB-option\fR \fIvalue\fR\&.\&.\&. In this form the command is used to configure one or more of the @@ -398,18 +398,10 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" nameserv::client(n), nameserv::common(n) .SH KEYWORDS name service, server .SH CATEGORY Index: idoc/man/files/modules/nntp/nntp.n ================================================================== --- idoc/man/files/modules/nntp/nntp.n +++ idoc/man/files/modules/nntp/nntp.n @@ -635,17 +635,9 @@ bugs and other problems\&. Please report such in the category \fInntp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS news, nntp, nntpclient, rfc 1036, rfc 977 .SH CATEGORY Networking Index: idoc/man/files/modules/ntp/ntp_time.n ================================================================== --- idoc/man/files/modules/ntp/ntp_time.n +++ idoc/man/files/modules/ntp/ntp_time.n @@ -417,18 +417,10 @@ bugs and other problems\&. Please report such in the category \fIntp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" ntp .SH KEYWORDS NTP, SNTP, rfc 2030, rfc 868, time .SH CATEGORY Index: idoc/man/files/modules/oauth/oauth.n ================================================================== --- idoc/man/files/modules/oauth/oauth.n +++ idoc/man/files/modules/oauth/oauth.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'oauth\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2014 Javi P\&. '\" -.TH "oauth" n 1\&.0\&.3 tcllib "oauth" +.TH "oauth" n 1\&.0 tcllib "oauth" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME oauth \- oauth API base signature .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBoauth ?1\&.0\&.3?\fR +package require \fBoauth ?1\&.0?\fR .sp \fB::oauth::config\fR .sp \fB::oauth::config\fR ?\fIoptions\fR\&.\&.\&.? .sp @@ -292,13 +292,12 @@ The \fBoauth\fR package provides a simple Tcl-only library for communication with \fIoauth\fR [http://oauth\&.net] APIs\&. This current version of the package supports the Oauth 1\&.0 Protocol, as specified in \fIRFC 5849\fR [http://tools\&.ietf\&.org/rfc/rfc5849\&.txt]\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -480,22 +479,14 @@ bugs and other problems\&. Please report such in the category \fIoauth\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS RFC 2718, RFC 5849, oauth, twitter .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2014 Javi P\&. .fi DELETED idoc/man/files/modules/oometa/oometa.n Index: idoc/man/files/modules/oometa/oometa.n ================================================================== --- idoc/man/files/modules/oometa/oometa.n +++ idoc/man/files/modules/oometa/oometa.n @@ -1,454 +0,0 @@ -'\" -'\" Generated from file 'oometa\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2015 Sean Woods -'\" -.TH "oometa" n 0\&.7\&.1 tcllib "Data registry for TclOO frameworks" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -oometa \- oo::meta A data registry for classess -.SH SYNOPSIS -\fBoo::meta::info\fR -.sp -\fBoo::meta::info branchget\fR ?\fIkey\fR? ?\&.\&.\&.? -.sp -\fBoo::meta::info branchset\fR ?\fIkey\&.\&.\&.\fR? \fIkey\fR \fIvalue\fR -.sp -\fBoo::meta::info dump\fR \fIclass\fR -.sp -\fBoo::meta::info\fR \fIclass\fR \fBis\fR \fItype\fR ?\fIargs\fR? -.sp -\fBoo::meta::info\fR \fIclass\fR \fBmerge\fR ?\fIdict\fR? ?\fIdict\fR? ?\fI\&.\&.\&.\fR? -.sp -\fBoo::meta::info\fR \fIclass\fR \fBrebuild\fR -.sp -\fBoo::meta::metadata\fR \fIclass\fR -.sp -\fBoo::define meta\fR -.sp -\fBoo::class method meta\fR -.sp -\fBoo::object method meta\fR -.sp -\fBoo::object method meta cget\fR ?\fIfield\fR? ?\fI\&.\&.\&.\fR? \fIfield\fR -.sp -.BE -.SH DESCRIPTION -The \fBoo::meta\fR package provides a data registry service for TclOO classes\&. -.SH USAGE -.CS - - -oo::class create animal { - meta set biodata animal: 1 -} -oo::class create mammal { - superclass animal - meta set biodata mammal: 1 -} -oo::class create cat { - superclass mammal - meta set biodata diet: carnivore -} - -cat create felix -puts [felix meta dump biodata] -> animal: 1 mammal: 1 diet: carnivore - -felix meta set biodata likes: {birds mice} -puts [felix meta get biodata] -> animal: 1 mammal: 1 diet: carnivore likes: {bird mice} - -# Modify a class -mammal meta set biodata metabolism: warm-blooded -puts [felix meta get biodata] -> animal: 1 mammal: 1 metabolism: warm-blooded diet: carnivore likes: {birds mice} - -# Overwrite class info -felix meta set biodata mammal: yes -puts [felix meta get biodata] -> animal: 1 mammal: yes metabolism: warm-blooded diet: carnivore likes: {birds mice} - -.CE -.SH CONCEPT -The concept behind \fBoo::meta\fR is that each class contributes a snippet of \fIlocal\fR data\&. -When \fBoo::meta::metadata\fR is called, the system walks through the linear ancestry produced by -\fBoo::meta::ancestors\fR, and recursively combines all of that local data for all of a class' -ancestors into a single dict\&. -Instances of oo::object can also combine class data with a local dict stored in the \fImeta\fR variable\&. -.SH COMMANDS -.TP -\fBoo::meta::info\fR -\fBoo::meta::info\fR is intended to work on the metadata of a class in a manner similar to if the aggregate -pieces where assembled into a single dict\&. The system mimics all of the standard dict commands, and addes -the following: -.TP -\fBoo::meta::info branchget\fR ?\fIkey\fR? ?\&.\&.\&.? -Returns a dict representation of the element at \fIargs\fR, but with any trailing : removed from field names\&. -.CS - - -::oo::meta::info $myclass set option color {default: green widget: colorselect} -puts [::oo::meta::info $myclass get option color] -> {default: green widget: color} -puts [::oo::meta::info $myclass branchget option color] -> {default green widget color} - -.CE -.TP -\fBoo::meta::info branchset\fR ?\fIkey\&.\&.\&.\fR? \fIkey\fR \fIvalue\fR -Merges \fIdict\fR with any other information contaned at node ?\fIkey\&.\&.\&.\fR?, and adding a trailing : -to all field names\&. -.CS - - -::oo::meta::info $myclass branchset option color {default green widget colorselect} -puts [::oo::meta::info $myclass get option color] -> {default: green widget: color} - -.CE -.TP -\fBoo::meta::info dump\fR \fIclass\fR -Returns the complete snapshot of a class metadata, as producted by \fBoo::meta::metadata\fR -.TP -\fBoo::meta::info\fR \fIclass\fR \fBis\fR \fItype\fR ?\fIargs\fR? -Returns a boolean true or false if the element ?\fIargs\fR? would match \fBstring is\fR \fItype\fR \fIvalue\fR -.CS - - -::oo::meta::info $myclass set constant mammal 1 -puts [::oo::meta::info $myclass is true constant mammal] -> 1 - -.CE -.TP -\fBoo::meta::info\fR \fIclass\fR \fBmerge\fR ?\fIdict\fR? ?\fIdict\fR? ?\fI\&.\&.\&.\fR? -Combines all of the arguments into a single dict, which is then stored as the new -local representation for this class\&. -.TP -\fBoo::meta::info\fR \fIclass\fR \fBrebuild\fR -Forces the meta system to destroy any cached representation of a class' metadata before -the next access to \fBoo::meta::metadata\fR -.TP -\fBoo::meta::metadata\fR \fIclass\fR -Returns an aggregate picture of the metadata for \fIclass\fR, combining its \fIlocal\fR data -with the \fIlocal\fR data from its ancestors\&. -.TP -\fBoo::define meta\fR -The package injects a command \fBoo::define::meta\fR which works to provide a class in the -process of definition access to \fBoo::meta::info\fR, but without having to look the name up\&. -.CS - - -oo::define myclass { - meta set foo bar: baz -} - -.CE -.TP -\fBoo::class method meta\fR -The package injects a new method \fBmeta\fR into \fBoo::class\fR which works to provide a class -instance access to \fBoo::meta::info\fR\&. -.TP -\fBoo::object method meta\fR -The package injects a new method \fBmeta\fR into \fBoo::object\fR\&. \fBoo::object\fR combines the data -for its class (as provided by \fBoo::meta::metadata\fR), with a local variable \fImeta\fR to -produce a local picture of metadata\&. -This method provides the following additional commands: -.TP -\fBoo::object method meta cget\fR ?\fIfield\fR? ?\fI\&.\&.\&.\fR? \fIfield\fR -Attempts to locate a singlar leaf, and return its value\&. For single option lookups, this -is faster than \fBmy meta getnull\fR ?\fIfield\fR? ?\fI\&.\&.\&.\fR? \fIfield\fR], because -it performs a search instead directly instead of producing the recursive merge product -between the class metadata, the local \fImeta\fR variable, and THEN performing the search\&. -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fItcloo\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -TOOL, TclOO -.SH CATEGORY -TclOO -.SH COPYRIGHT -.nf -Copyright (c) 2015 Sean Woods - -.fi Index: idoc/man/files/modules/ooutil/ooutil.n ================================================================== --- idoc/man/files/modules/ooutil/ooutil.n +++ idoc/man/files/modules/ooutil/ooutil.n @@ -437,18 +437,10 @@ bugs and other problems\&. Please report such in the category \fIoo::util\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" snit(n) .SH KEYWORDS TclOO, callback, class methods, class variables, command prefix, currying, method reference, my method, singleton .SH CATEGORY Index: idoc/man/files/modules/otp/otp.n ================================================================== --- idoc/man/files/modules/otp/otp.n +++ idoc/man/files/modules/otp/otp.n @@ -347,18 +347,10 @@ bugs and other problems\&. Please report such in the category \fIotp\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" SASL, md4, md5, ripemd160, sha1 .SH KEYWORDS hashing, message-digest, password, rfc 2289, security .SH CATEGORY Index: idoc/man/files/modules/page/page_intro.n ================================================================== --- idoc/man/files/modules/page/page_intro.n +++ idoc/man/files/modules/page/page_intro.n @@ -295,22 +295,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS page, parser generator, text processing .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_pluginmgr.n ================================================================== --- idoc/man/files/modules/page/page_pluginmgr.n +++ idoc/man/files/modules/page/page_pluginmgr.n @@ -1035,22 +1035,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS page, parser generator, text processing .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_util_flow.n ================================================================== --- idoc/man/files/modules/page/page_util_flow.n +++ idoc/man/files/modules/page/page_util_flow.n @@ -347,22 +347,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS dataflow, graph walking, page, parser generator, text processing, tree walking .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_util_norm_lemon.n ================================================================== --- idoc/man/files/modules/page/page_util_norm_lemon.n +++ idoc/man/files/modules/page/page_util_norm_lemon.n @@ -303,22 +303,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS graph walking, lemon, normalization, page, parser generator, text processing, tree walking .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_util_norm_peg.n ================================================================== --- idoc/man/files/modules/page/page_util_norm_peg.n +++ idoc/man/files/modules/page/page_util_norm_peg.n @@ -352,22 +352,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS PEG, graph walking, normalization, page, parser generator, text processing, tree walking .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_util_peg.n ================================================================== --- idoc/man/files/modules/page/page_util_peg.n +++ idoc/man/files/modules/page/page_util_peg.n @@ -374,22 +374,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS PEG, page, parser generator, parsing expression grammar, text processing, transformation .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/page/page_util_quote.n ================================================================== --- idoc/man/files/modules/page/page_util_quote.n +++ idoc/man/files/modules/page/page_util_quote.n @@ -328,22 +328,14 @@ bugs and other problems\&. Please report such in the category \fIpage\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS page, parser generator, quoting, text processing .SH CATEGORY Page Parser Generator .SH COPYRIGHT .nf Copyright (c) 2007 Andreas Kupries .fi Index: idoc/man/files/modules/pki/pki.n ================================================================== --- idoc/man/files/modules/pki/pki.n +++ idoc/man/files/modules/pki/pki.n @@ -347,39 +347,20 @@ .IP [2] "openssl rsautl -verify" == "::pki::decrypt -binary -pub" .RE .TP \fB::pki::sign\fR \fIinput\fR \fIkey\fR ?\fIalgo\fR? -Digitally sign message \fIinput\fR using the private \fIkey\fR\&. -.sp -If \fIalgo\fR is ommited "sha1" is assumed\&. Possible values for -\fIalgo\fR include "\fBmd5\fR", "\fBsha1\fR", "\fBsha256\fR", -and "\fBraw\fR"\&. -.sp -Specifying "\fBraw\fR" for \fIalgo\fR will inhibit the -building of an ASN\&.1 structure to encode which hashing algorithm was -chosen\&. -\fIAttention\fR: In this case the corresponding \fBpkgi::verify\fR -must be called \fBwith\fR algorithm information\&. -Conversely, specifying a non-"\fBraw\fR" algorithm here means that -the corresponding \fBpkgi::verify\fR invokation has to be made -\fIwithout\fR algorithm information\&. -.sp -The \fIinput\fR should be the plain text, hashing will be -performed on it\&. -.sp +Digitally sign message \fIinput\fR using the private \fIkey\fR\&. If \fIalgo\fR +is ommited "sha1" is assumed\&. Possible values for \fIalgo\fR include +"md5", "sha1", "sha256", and "raw"\&. Specifyin "raw" for \fIalgo\fR will +inhibit the building of an ASN\&.1 structure to encode which hashing +algorithm was chosen\&. +The \fIinput\fR should be the plain text, hashing will be performed on it\&. The \fIkey\fR should include the private key\&. .TP \fB::pki::verify\fR \fIsignedmessage\fR \fIplaintext\fR \fIkey\fR ?\fIalgo\fR? Verify a digital signature using a public \fIkey\fR\&. Returns true or false\&. -.sp -\fIAttention\fR: The algorithm information \fIalgo\fR has to -be specified if and only if the \fBpki::sign\fR which generated the -\fIsignedmessage\fR was called with algorithm "\fBraw\fR"\&. This -inhibited the building of the ASN\&.1 structure encoding the chosen -hashing algorithm\&. Conversely, if a proper algorithm was specified -during signing then you \fImust not\fR specify an algorithm here\&. .TP \fB::pki::key\fR \fIkey\fR ?\fIpassword\fR? ?\fIencodePem\fR? Convert a key structure into a serialized PEM (default) or DER encoded private key suitable for other applications\&. For RSA keys this means PKCS#1\&. .TP \fB::pki::pkcs::parse_key\fR \fIkey\fR ?\fIpassword\fR? @@ -501,18 +482,10 @@ bugs and other problems\&. Please report such in the category \fIrsa\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" aes(n), blowfish(n), des(n), md5(n), sha1(n) .SH KEYWORDS cipher, data integrity, encryption, public key cipher, rsa, security .SH CATEGORY Index: idoc/man/files/modules/pluginmgr/pluginmgr.n ================================================================== --- idoc/man/files/modules/pluginmgr/pluginmgr.n +++ idoc/man/files/modules/pluginmgr/pluginmgr.n @@ -617,22 +617,14 @@ bugs and other problems\&. Please report such in the category \fIpluginmgr\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS plugin management, plugin search .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2005 Andreas Kupries .fi Index: idoc/man/files/modules/png/png.n ================================================================== --- idoc/man/files/modules/png/png.n +++ idoc/man/files/modules/png/png.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'png\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004, Code: Aaron Faupell '\" Copyright (c) 2004, Doc: Andreas Kupries '\" -.TH "png" n 0\&.3 tcllib "Image manipulation" +.TH "png" n 0\&.1\&.2 tcllib "Image manipulation" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -277,11 +277,11 @@ .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp package require \fBcrc32 \fR .sp -package require \fBpng ?0\&.3?\fR +package require \fBpng ?0\&.1\&.2?\fR .sp \fB::png::validate\fR \fIfile\fR .sp \fB::png::isPNG\fR \fIfile\fR .sp @@ -297,12 +297,10 @@ .sp \fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fItext\fR .sp \fB::png::addComment\fR \fIfile\fR \fIkeyword\fR \fIlang\fR \fIkeyword2\fR \fItext\fR .sp -\fB::png::getPixelDimension\fR \fIfile\fR -.sp \fB::png::image\fR \fIfile\fR .sp \fB::png::write\fR \fIfile\fR \fIdata\fR .sp .BE @@ -406,22 +404,10 @@ is found\&. \fIkeyword\fR has to be less than 80 characters long to conform to the PNG specification\&. \fIkeyword2\fR is the translated \fIkeyword\fR, in the language specified by the language identifier \fIlang\fR\&. .TP -\fB::png::getPixelDimension\fR \fIfile\fR -Returns a dictionary with keys \fBppux\fR, \fBppuy\fR and -\fBunit\fR if the information is present\&. Otherwise, it returns the empty -string\&. -.sp -The values of \fBppux\fR and \fBppuy\fR return the pixel -per unit value in X or Y direction\&. -.sp -The allowed values for key \fBunit\fR are \fBmeter\fR and -\fBunknown\fR\&. In the case of meter, the dpi value can be calculated -by multiplying with the conversion factor \fB0\&.0254\fR\&. -.TP \fB::png::image\fR \fIfile\fR Given a PNG file returns the image in the list of scanlines format used by Tk_GetColor\&. .TP \fB::png::write\fR \fIfile\fR \fIdata\fR Takes a list of scanlines in the Tk_GetColor format and writes the represented image @@ -432,18 +418,10 @@ bugs and other problems\&. Please report such in the category \fIpng\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS comment, image, png, timestamp .SH CATEGORY File formats .SH COPYRIGHT Index: idoc/man/files/modules/pop3/pop3.n ================================================================== --- idoc/man/files/modules/pop3/pop3.n +++ idoc/man/files/modules/pop3/pop3.n @@ -308,13 +308,12 @@ transmitting the username and password, then providing a Tcl API to access the POP3 protocol commands\&. All server errors are returned as Tcl errors (thrown) which must be caught with the Tcl \fBcatch\fR command\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -501,11 +500,11 @@ package require tls tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&. # Create secured pop3 channel - pop3::open -socketcmd tls::socket \\ + pop3::open -socketcmd tls::socket \\\\ $thehost $theuser $thepassword \&.\&.\&. .CE @@ -519,11 +518,11 @@ package require tls tls::init -cafile /path/to/ca/cert -keyfile \&.\&.\&. # Create secured pop3 channel - pop3::open -stls 1 \\ + pop3::open -stls 1 \\\\ $thehost $theuser $thepassword \&.\&.\&. .CE @@ -532,17 +531,9 @@ bugs and other problems\&. Please report such in the category \fIpop3\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS email, mail, pop, pop3, rfc 1939, secure, ssl, tls .SH CATEGORY Networking Index: idoc/man/files/modules/pop3d/pop3d.n ================================================================== --- idoc/man/files/modules/pop3d/pop3d.n +++ idoc/man/files/modules/pop3d/pop3d.n @@ -452,10 +452,11 @@ are able to use it\&. The \fImbox\fR argument is the storage reference as returned by the \fBlookup\fR method of the authentication command, see section \fBAuthentication\fR\&. .TP \fIstorageCmd\fR \fBdele\fR \fImbox\fR \fImsgList\fR +] Deletes the messages whose numeric ids are contained in the \fImsgList\fR from the mailbox specified via \fImbox\fR\&. .TP \fIstorageCmd\fR \fBlock\fR \fImbox\fR This method locks the specified mailbox for use by a single connection @@ -491,11 +492,11 @@ command, see package \fBtls\fR, to secure the communication\&. .CS package require tls - tls::init \\ + tls::init \\\\ \&.\&.\&. pop3d::new S -socket tls::socket \&.\&.\&. @@ -511,18 +512,10 @@ bugs and other problems\&. Please report such in the category \fIpop3d\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS internet, network, pop3, protocol, rfc 1939, secure, ssl, tls .SH CATEGORY Networking .SH COPYRIGHT Index: idoc/man/files/modules/pop3d/pop3d_dbox.n ================================================================== --- idoc/man/files/modules/pop3d/pop3d_dbox.n +++ idoc/man/files/modules/pop3d/pop3d_dbox.n @@ -426,22 +426,14 @@ bugs and other problems\&. Please report such in the category \fIpop3d\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS internet, network, pop3, protocol, rfc 822 .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries .fi Index: idoc/man/files/modules/pop3d/pop3d_udb.n ================================================================== --- idoc/man/files/modules/pop3d/pop3d_udb.n +++ idoc/man/files/modules/pop3d/pop3d_udb.n @@ -375,22 +375,14 @@ bugs and other problems\&. Please report such in the category \fIpop3d\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS internet, network, pop3, protocol .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries .fi Index: idoc/man/files/modules/practcl/practcl.n ================================================================== --- idoc/man/files/modules/practcl/practcl.n +++ idoc/man/files/modules/practcl/practcl.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'practcl\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2016-2018 Sean Woods +'\" Copyright (c) 2016 Sean Woods '\" -.TH "practcl" n 0\&.16\&.4 tcllib "The The Proper Rational API for C to Tool Command Language Module" +.TH "practcl" n 0\&.1 tcllib "The The Proper Rational API for C to Tool Command Language Module" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,1902 +274,81 @@ .SH NAME practcl \- The Practcl Module .SH SYNOPSIS package require \fBTclOO 1\&.0\fR .sp -proc \fBpractcl::cat\fR \fIfname\fR -.sp -proc \fBpractcl::docstrip\fR \fItext\fR -.sp -proc \fBputb\fR ?\fImap\fR? \fItext\fR -.sp -proc \fBProc\fR \fIname\fR \fIarglist\fR \fIbody\fR -.sp -proc \fBnoop\fR ?\fIargs\fR? -.sp -proc \fBpractcl::debug\fR ?\fIargs\fR? -.sp -proc \fBpractcl::doexec\fR ?\fIargs\fR? -.sp -proc \fBpractcl::doexec_in\fR \fIpath\fR ?\fIargs\fR? -.sp -proc \fBpractcl::dotclexec\fR ?\fIargs\fR? -.sp -proc \fBpractcl::domake\fR \fIpath\fR ?\fIargs\fR? -.sp -proc \fBpractcl::domake\&.tcl\fR \fIpath\fR ?\fIargs\fR? -.sp -proc \fBpractcl::fossil\fR \fIpath\fR ?\fIargs\fR? -.sp -proc \fBpractcl::fossil_status\fR \fIdir\fR -.sp -proc \fBpractcl::os\fR -.sp -proc \fBpractcl::mkzip\fR \fIexename\fR \fIbarekit\fR \fIvfspath\fR -.sp -proc \fBpractcl::sort_dict\fR \fIlist\fR -.sp -proc \fBpractcl::local_os\fR -.sp -proc \fBpractcl::config\&.tcl\fR \fIpath\fR -.sp -proc \fBpractcl::read_configuration\fR \fIpath\fR -.sp -proc \fBpractcl::tcllib_require\fR \fIpkg\fR ?\fIargs\fR? -.sp -proc \fBpractcl::platform::tcl_core_options\fR \fIos\fR -.sp -proc \fBpractcl::platform::tk_core_options\fR \fIos\fR -.sp -proc \fBpractcl::read_rc_file\fR \fIfilename\fR ?\fIlocaldat\fR \fB\fR? -.sp -proc \fBpractcl::read_sh_subst\fR \fIline\fR \fIinfo\fR -.sp -proc \fBpractcl::read_sh_file\fR \fIfilename\fR ?\fIlocaldat\fR \fB\fR? -.sp -proc \fBpractcl::read_Config\&.sh\fR \fIfilename\fR -.sp -proc \fBpractcl::read_Makefile\fR \fIfilename\fR -.sp -proc \fBpractcl::cputs\fR \fIvarname\fR ?\fIargs\fR? -.sp -proc \fBpractcl::tcl_to_c\fR \fIbody\fR -.sp -proc \fBpractcl::_tagblock\fR \fItext\fR ?\fIstyle\fR \fBtcl\fR? ?\fInote\fR \fB\fR? -.sp -proc \fBpractcl::de_shell\fR \fIdata\fR -.sp -proc \fBpractcl::grep\fR \fIpattern\fR ?\fIfiles\fR \fB\fR? -.sp -proc \fBpractcl::file_lexnormalize\fR \fIsp\fR -.sp -proc \fBpractcl::file_relative\fR \fIbase\fR \fIdst\fR -.sp -proc \fBpractcl::findByPattern\fR \fIbasedir\fR \fIpatterns\fR -.sp -proc \fBpractcl::log\fR \fIfname\fR \fIcomment\fR -.sp -proc \fBpractcl::_pkgindex_simpleIndex\fR \fIpath\fR -.sp -proc \fBpractcl::_pkgindex_directory\fR \fIpath\fR -.sp -proc \fBpractcl::_pkgindex_path_subdir\fR \fIpath\fR -.sp -proc \fBpractcl::pkgindex_path\fR ?\fIargs\fR? -.sp -proc \fBpractcl::installDir\fR \fId1\fR \fId2\fR -.sp -proc \fBpractcl::copyDir\fR \fId1\fR \fId2\fR ?\fItoplevel\fR \fB1\fR? -.sp -proc \fBpractcl::buildModule\fR \fImodpath\fR -.sp -proc \fBpractcl::installModule\fR \fImodpath\fR \fIDEST\fR -.sp -proc \fBpractcl::trigger\fR ?\fIargs\fR? -.sp -proc \fBpractcl::depends\fR ?\fIargs\fR? -.sp -proc \fBpractcl::target\fR \fIname\fR \fIinfo\fR ?\fIaction\fR \fB\fR? -.sp -method \fBconstructor\fR -.sp -method \fBargspec\fR \fIargspec\fR -.sp -method \fBcomment\fR \fIblock\fR -.sp -method \fBkeyword\&.Annotation\fR \fIresultvar\fR \fIcommentblock\fR \fItype\fR \fIname\fR \fIbody\fR -.sp -method \fBkeyword\&.Class\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR \fIbody\fR -.sp -method \fBkeyword\&.class\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR \fIbody\fR -.sp -method \fBkeyword\&.Class_Method\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR ?\fIargs\fR? -.sp -method \fBkeyword\&.method\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR ?\fIargs\fR? -.sp -method \fBkeyword\&.proc\fR \fIcommentblock\fR \fIname\fR \fIargspec\fR -.sp -method \fBreset\fR -.sp -method \fBMain\fR -.sp -method \fBsection\&.method\fR \fIkeyword\fR \fImethod\fR \fIminfo\fR -.sp -method \fBsection\&.annotation\fR \fItype\fR \fIname\fR \fIiinfo\fR -.sp -method \fBsection\&.class\fR \fIclass_name\fR \fIclass_info\fR -.sp -method \fBsection\&.command\fR \fIprocinfo\fR -.sp -method \fBmanpage\fR ?\fBheader \fIvalue\fR\fR? ?\fBfooter \fIvalue\fR\fR? ?\fBauthors \fIlist\fR\fR? -.sp -method \fBscan_text\fR \fItext\fR -.sp -method \fBscan_file\fR \fIfilename\fR -.sp -method \fB_MorphPatterns\fR -.sp -method \fBdefine\fR \fIsubmethod\fR ?\fIargs\fR? -.sp -method \fBgraft\fR ?\fIargs\fR? -.sp -method \fBinitialize\fR -.sp -method \fBlink\fR \fIcommand\fR ?\fIargs\fR? -.sp -method \fBmorph\fR \fIclassname\fR -.sp -method \fBscript\fR \fIscript\fR -.sp -method \fBselect\fR -.sp -method \fBsource\fR \fIfilename\fR -.sp -classmethod \fBselect\fR \fIobject\fR -.sp -method \fBconfig\&.sh\fR -.sp -method \fBBuildDir\fR \fIPWD\fR -.sp -method \fBMakeDir\fR \fIsrcdir\fR -.sp -method \fBread_configuration\fR -.sp -method \fBbuild-cflags\fR \fIPROJECT\fR \fIDEFS\fR \fInamevar\fR \fIversionvar\fR \fIdefsvar\fR -.sp -method \fBcritcl\fR ?\fIargs\fR? -.sp -method \fBAutoconf\fR -.sp -method \fBBuildDir\fR \fIPWD\fR -.sp -method \fBConfigureOpts\fR -.sp -method \fBMakeDir\fR \fIsrcdir\fR -.sp -method \fBmake {} autodetect\fR -.sp -method \fBmake {} clean\fR -.sp -method \fBmake {} compile\fR -.sp -method \fBmake {} install\fR \fIDEST\fR -.sp -method \fBbuild-compile-sources\fR \fIPROJECT\fR \fICOMPILE\fR \fICPPCOMPILE\fR \fIINCLUDES\fR -.sp -method \fBbuild-Makefile\fR \fIpath\fR \fIPROJECT\fR -.sp -method \fBbuild-library\fR \fIoutfile\fR \fIPROJECT\fR -.sp -method \fBbuild-tclsh\fR \fIoutfile\fR \fIPROJECT\fR ?\fIpath\fR \fBauto\fR? -.sp -method \fBBuildDir\fR \fIPWD\fR -.sp -method \fBmake {} autodetect\fR -.sp -method \fBmake {} clean\fR -.sp -method \fBmake {} compile\fR -.sp -method \fBmake {} install\fR \fIDEST\fR -.sp -method \fBMakeDir\fR \fIsrcdir\fR -.sp -method \fBNmakeOpts\fR -.sp -method \fBconstructor\fR \fImodule_object\fR \fIname\fR \fIinfo\fR ?\fIaction_body\fR \fB\fR? -.sp -method \fBdo\fR -.sp -method \fBcheck\fR -.sp -method \fBoutput\fR -.sp -method \fBreset\fR -.sp -method \fBtriggers\fR -.sp -method \fBconstructor\fR \fIparent\fR ?\fIargs\fR? -.sp -method \fBchild\fR \fImethod\fR -.sp -method \fBgo\fR -.sp -method \fBcstructure\fR \fIname\fR \fIdefinition\fR ?\fIargdat\fR \fB\fR? -.sp -method \fBinclude\fR \fIheader\fR -.sp -method \fBinclude_dir\fR ?\fIargs\fR? -.sp -method \fBinclude_directory\fR ?\fIargs\fR? -.sp -method \fBc_header\fR \fIbody\fR -.sp -method \fBc_code\fR \fIbody\fR -.sp -method \fBc_function\fR \fIheader\fR \fIbody\fR ?\fIinfo\fR \fB\fR? -.sp -method \fBc_tcloomethod\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.sp -method \fBcmethod\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.sp -method \fBc_tclproc_nspace\fR \fInspace\fR -.sp -method \fBc_tclcmd\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.sp -method \fBc_tclproc_raw\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.sp -method \fBtcltype\fR \fIname\fR \fIargdat\fR -.sp -method \fBproject-compile-products\fR -.sp -method \fBimplement\fR \fIpath\fR -.sp -method \fBinitialize\fR -.sp -method \fBlinktype\fR -.sp -method \fBgenerate-cfile-constant\fR -.sp -method \fBgenerate-cfile-header\fR -.sp -method \fBgenerate-cfile-tclapi\fR -.sp -method \fBgenerate-loader-module\fR -.sp -method \fBCollate_Source\fR \fICWD\fR -.sp -method \fBselect\fR -.sp -classmethod \fBselect\fR \fIobject\fR -.sp -method \fBcode\fR \fIsection\fR \fIbody\fR -.sp -method \fBCollate_Source\fR \fICWD\fR -.sp -method \fBproject-compile-products\fR -.sp -method \fBgenerate-debug\fR ?\fIspaces\fR \fB\fR? -.sp -method \fBgenerate-cfile-constant\fR -.sp -method \fBgenerate-cfile-public-structure\fR -.sp -method \fBgenerate-cfile-header\fR -.sp -method \fBgenerate-cfile-global\fR -.sp -method \fBgenerate-cfile-private-typedef\fR -.sp -method \fBgenerate-cfile-private-structure\fR -.sp -method \fBgenerate-cfile-functions\fR -.sp -method \fBgenerate-cfile-tclapi\fR -.sp -method \fBgenerate-hfile-public-define\fR -.sp -method \fBgenerate-hfile-public-macro\fR -.sp -method \fBgenerate-hfile-public-typedef\fR -.sp -method \fBgenerate-hfile-public-structure\fR -.sp -method \fBgenerate-hfile-public-headers\fR -.sp -method \fBgenerate-hfile-public-function\fR -.sp -method \fBgenerate-hfile-public-includes\fR -.sp -method \fBgenerate-hfile-public-verbatim\fR -.sp -method \fBgenerate-loader-external\fR -.sp -method \fBgenerate-loader-module\fR -.sp -method \fBgenerate-stub-function\fR -.sp -method \fBIncludeAdd\fR \fIheadervar\fR ?\fIargs\fR? -.sp -method \fBgenerate-tcl-loader\fR -.sp -method \fBgenerate-tcl-pre\fR -.sp -method \fBgenerate-tcl-post\fR -.sp -method \fBlinktype\fR -.sp -method \fBOfile\fR \fIfilename\fR -.sp -method \fBproject-static-packages\fR -.sp -method \fBtoolset-include-directory\fR -.sp -method \fBtarget\fR \fImethod\fR ?\fIargs\fR? -.sp -method \fBproject-compile-products\fR -.sp -method \fBgenerate-loader-module\fR -.sp -method \fBproject-compile-products\fR -.sp -method \fBlinker-products\fR \fIconfigdict\fR -.sp -method \fBinitialize\fR -.sp -variable \fBmake_object\fR -.sp -method \fB_MorphPatterns\fR -.sp -method \fBadd\fR ?\fIargs\fR? -.sp -method \fBinstall-headers\fR ?\fIargs\fR? -.sp -method \fBmake {} _preamble\fR -.sp -method \fBmake {} pkginfo\fR -.sp -method \fBmake {} objects\fR -.sp -method \fBmake {} object\fR \fIname\fR -.sp -method \fBmake {} reset\fR -.sp -method \fBmake {} trigger\fR ?\fIargs\fR? -.sp -method \fBmake {} depends\fR ?\fIargs\fR? -.sp -method \fBmake {} filename\fR \fIname\fR -.sp -method \fBmake {} target\fR \fIname\fR \fIInfo\fR \fIbody\fR -.sp -method \fBmake {} todo\fR -.sp -method \fBmake {} do\fR -.sp -method \fBchild\fR \fIwhich\fR -.sp -method \fBgenerate-c\fR -.sp -method \fBgenerate-h\fR -.sp -method \fBgenerate-loader\fR -.sp -method \fBinitialize\fR -.sp -method \fBimplement\fR \fIpath\fR -.sp -method \fBlinktype\fR -.sp -method \fB_MorphPatterns\fR -.sp -method \fBconstructor\fR ?\fIargs\fR? -.sp -method \fBadd_object\fR \fIobject\fR -.sp -method \fBadd_project\fR \fIpkg\fR \fIinfo\fR ?\fIoodefine\fR \fB\fR? -.sp -method \fBadd_tool\fR \fIpkg\fR \fIinfo\fR ?\fIoodefine\fR \fB\fR? -.sp -method \fBbuild-tclcore\fR -.sp -method \fBchild\fR \fIwhich\fR -.sp -method \fBlinktype\fR -.sp -method \fBproject\fR \fIpkg\fR ?\fIargs\fR? -.sp -method \fBtclcore\fR -.sp -method \fBtkcore\fR -.sp -method \fBtool\fR \fIpkg\fR ?\fIargs\fR? -.sp -method \fBclean\fR \fIPATH\fR -.sp -method \fBproject-compile-products\fR -.sp -method \fBgo\fR -.sp -method \fBgenerate-decls\fR \fIpkgname\fR \fIpath\fR -.sp -method \fBimplement\fR \fIpath\fR -.sp -method \fBgenerate-make\fR \fIpath\fR -.sp -method \fBlinktype\fR -.sp -method \fBpackage-ifneeded\fR ?\fIargs\fR? -.sp -method \fBshared_library\fR ?\fIfilename\fR \fB\fR? -.sp -method \fBstatic_library\fR ?\fIfilename\fR \fB\fR? -.sp -method \fBbuild-tclkit_main\fR \fIPROJECT\fR \fIPKG_OBJS\fR -.sp -method \fBCollate_Source\fR \fICWD\fR -.sp -method \fBwrap\fR \fIPWD\fR \fIexename\fR \fIvfspath\fR ?\fIargs\fR? -.sp -classmethod \fBSandbox\fR \fIobject\fR -.sp -classmethod \fBselect\fR \fIobject\fR -.sp -classmethod \fBclaim_option\fR -.sp -classmethod \fBclaim_object\fR \fIobject\fR -.sp -classmethod \fBclaim_path\fR \fIpath\fR -.sp -method \fBscm_info\fR -.sp -method \fBDistroMixIn\fR -.sp -method \fBSandbox\fR -.sp -method \fBSrcDir\fR -.sp -method \fBScmTag\fR -.sp -method \fBScmClone\fR -.sp -method \fBScmUnpack\fR -.sp -method \fBScmUpdate\fR -.sp -method \fBUnpack\fR -.sp -classmethod \fBclaim_object\fR \fIobject\fR -.sp -classmethod \fBclaim_option\fR -.sp -classmethod \fBclaim_path\fR \fIpath\fR -.sp -method \fBScmUnpack\fR -.sp -classmethod \fBclaim_object\fR \fIobj\fR -.sp -classmethod \fBclaim_option\fR -.sp -classmethod \fBclaim_path\fR \fIpath\fR -.sp -method \fBscm_info\fR -.sp -method \fBScmClone\fR -.sp -method \fBScmTag\fR -.sp -method \fBScmUnpack\fR -.sp -method \fBScmUpdate\fR -.sp -classmethod \fBclaim_object\fR \fIobj\fR -.sp -classmethod \fBclaim_option\fR -.sp -classmethod \fBclaim_path\fR \fIpath\fR -.sp -method \fBScmTag\fR -.sp -method \fBScmUnpack\fR -.sp -method \fBScmUpdate\fR -.sp -method \fB_MorphPatterns\fR -.sp -method \fBBuildDir\fR \fIPWD\fR -.sp -method \fBchild\fR \fIwhich\fR -.sp -method \fBcompile\fR -.sp -method \fBgo\fR -.sp -method \fBinstall\fR ?\fIargs\fR? -.sp -method \fBlinktype\fR -.sp -method \fBlinker-products\fR \fIconfigdict\fR -.sp -method \fBlinker-external\fR \fIconfigdict\fR -.sp -method \fBlinker-extra\fR \fIconfigdict\fR -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-exec\fR -.sp -method \fBenv-install\fR -.sp -method \fBenv-load\fR -.sp -method \fBenv-present\fR -.sp -method \fBsources\fR -.sp -method \fBupdate\fR -.sp -method \fBunpack\fR -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-present\fR -.sp -method \fBlinktype\fR -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-install\fR -.sp -method \fBenv-present\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBkettle\fR \fIpath\fR ?\fIargs\fR? -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-install\fR -.sp -method \fBenv-present\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBinstall-module\fR \fIDEST\fR ?\fIargs\fR? -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-install\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBinstall-module\fR \fIDEST\fR ?\fIargs\fR? -.sp -method \fBclean\fR -.sp -method \fBenv-install\fR -.sp -method \fBproject-compile-products\fR -.sp -method \fBComputeInstall\fR -.sp -method \fBgo\fR -.sp -method \fBlinker-products\fR \fIconfigdict\fR -.sp -method \fBproject-static-packages\fR -.sp -method \fBBuildDir\fR \fIPWD\fR -.sp -method \fBcompile\fR -.sp -method \fBConfigure\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBinstall\fR \fIDEST\fR -.sp -method \fBenv-bootstrap\fR -.sp -method \fBenv-present\fR -.sp -method \fBenv-install\fR -.sp -method \fBgo\fR -.sp -method \fBlinktype\fR +package require \fBpractcl 0\&.1\fR +.sp +\fBCPUTS\fR \fIvarname\fR \fIbody\fR ?\fIbody\fR\&.\&.\&.? +.sp +\fBpractcl::_isdirectory\fR \fIpath\fR +.sp +\fBpractcl::object\fR \fIparent\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::library\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::exe\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::product\fR \fIparent\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::cheader\fR \fIparent\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::csource\fR \fIparent\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::module\fR \fIparent\fR ?\fIkeyvaluelist\fR? +.sp +\fBpractcl::submodule\fR \fIparent\fR ?\fIkeyvaluelist\fR? .sp .BE .SH DESCRIPTION The Practcl module is a tool for integrating large modules for C API Tcl code that requires custom Tcl types and TclOO objects\&. -.PP -The concept with Practcl is that is a single file package that can -assist any tcl based project with distribution, compilation, linking, -VFS preparation, executable assembly, and installation\&. Practcl also -allows one project to invoke the build system from another project, -allowing complex projects such as a statically linked basekit to be -assembled with relative ease\&. -.PP -Practcl ships as a single file, and aside from a Tcl 8\&.6 interpreter, -has no external dependencies\&. -.PP -Making a practcl project .SH COMMANDS .TP -proc \fBpractcl::cat\fR \fIfname\fR -Concatenate a file -.TP -proc \fBpractcl::docstrip\fR \fItext\fR -Strip the global comments from tcl code\&. Used to -prevent the documentation markup comments from clogging -up files intended for distribution in machine readable format\&. -.TP -proc \fBputb\fR ?\fImap\fR? \fItext\fR -Append a line of text to a variable\&. Optionally apply a string mapping\&. -.TP -proc \fBProc\fR \fIname\fR \fIarglist\fR \fIbody\fR -Generate a proc if no command already exists by that name -.TP -proc \fBnoop\fR ?\fIargs\fR? -A command to do nothing\&. A handy way of -negating an instruction without -having to comment it completely out\&. -It's also a handy attachment point for -an object to be named later -.TP -proc \fBpractcl::debug\fR ?\fIargs\fR? -.TP -proc \fBpractcl::doexec\fR ?\fIargs\fR? -Drop in a static copy of Tcl -.TP -proc \fBpractcl::doexec_in\fR \fIpath\fR ?\fIargs\fR? -.TP -proc \fBpractcl::dotclexec\fR ?\fIargs\fR? -.TP -proc \fBpractcl::domake\fR \fIpath\fR ?\fIargs\fR? -.TP -proc \fBpractcl::domake\&.tcl\fR \fIpath\fR ?\fIargs\fR? -.TP -proc \fBpractcl::fossil\fR \fIpath\fR ?\fIargs\fR? -.TP -proc \fBpractcl::fossil_status\fR \fIdir\fR -.TP -proc \fBpractcl::os\fR -.TP -proc \fBpractcl::mkzip\fR \fIexename\fR \fIbarekit\fR \fIvfspath\fR -Build a zipfile\&. On tcl8\&.6 this invokes the native Zip implementation -on older interpreters this invokes zip via exec -.TP -proc \fBpractcl::sort_dict\fR \fIlist\fR -Dictionary sort a key/value list\&. Needed because pre tcl8\&.6 -does not have \fIlsort -stride 2\fR -.TP -proc \fBpractcl::local_os\fR -Returns a dictionary describing the local operating system\&. -Fields return include: -.RS -.IP \(bu -download - Filesystem path where fossil repositories and source tarballs are downloaded for the current user -.IP \(bu -EXEEXT - The extension to give to executables\&. (i\&.e\&. \&.exe on windows) -.IP \(bu -fossil_mirror - A URI for a local network web server who acts as a fossil repository mirror -.IP \(bu -local_install - Filesystem path where packages for local consumption by the current user are installed -.IP \(bu -prefix - The prefix as given to the Tcl core/TEA for installation to local_install in \&./configure -.IP \(bu -sandbox - The file location where this project unpacks external projects -.IP \(bu -TEACUP_PROFILE - The ActiveState/Teacup canonical name for this platform (i\&.e\&. win32-ix86 macosx10\&.5-i386-x86_84) -.IP \(bu -TEACUP_OS - The local operating system (windows, macosx, openbsd, etc)\&. Gives the same answer as tcl\&.m4, except that macosx is given as macosx instead of Darwin\&. -.IP \(bu -TEA_PLATFORM - The platform returned by uname -s-uname -r (on Unix), or "windows" on Windows -.IP \(bu -TEACUP_ARCH - The processor architecture for the local os (i\&.e\&. ix86, x86_64) -.IP \(bu -TEACUP_ARCH - The processor architecture for the local os (i\&.e\&. ix86, x86_64) -.IP \(bu -teapot - Filesystem path where teapot package files are downloaded for the current user -.IP \(bu -userhome - File path to store localized preferences, cache download files, etc for the current user -.RE -.IP -This command uses a combination of local checks with Exec, any tclConfig\&.sh file that is -resident, autoconf data where already computed, and data gleaned from a file named -practcl\&.rc in userhome\&. The location for userhome varies by platform and operating system: -.RS -.IP \(bu -Windows: ::env(LOCALAPPDATA)/Tcl -.IP \(bu -Macos: ~/Library/Application Support/Tcl -.IP \(bu -Other: ~/tcl -.RE -.TP -proc \fBpractcl::config\&.tcl\fR \fIpath\fR -A transparent call to ::practcl::read_configuration to preserve backward compadibility -with older copies of Practcl -.TP -proc \fBpractcl::read_configuration\fR \fIpath\fR -Detect local platform\&. This command looks for data gleaned by autoconf or autosetup -in the path specified, or perform its own logic tests if neither has been run\&. -A file named config\&.site present in the location indicates that this project is -cross compiling, and the data stored in that file is used for the compiler and linker\&. -.sp -This command looks for information from the following files, in the following order: -.RS -.IP \(bu -config\&.tcl - A file generated by autoconf/configure in newer editions of TEA, encoded as a Tcl script\&. -.IP \(bu -config\&.site - A file containing cross compiler information, encoded as a SH script -.IP \(bu -::env(VisualStudioVersion) - On Windows, and environmental value that indicates MS Visual Studio is installed -.RE -.sp -This command returns a dictionary containing all of the data cleaned from the sources above\&. -In the absence of any guidance this command returns the same output as ::practcl::local_os\&. -In this mode, if the environmental variable VisualStudioVersion exists, this command -will provide a template of fields that are appropriate for compiling on Windows under -Microsoft Visual Studio\&. The USEMSVC flag in the dictionary is a boolean flag to indicate -if this is indeed the case\&. -.TP -proc \fBpractcl::tcllib_require\fR \fIpkg\fR ?\fIargs\fR? -Try to load a package, and failing that -retrieve tcllib -.TP -proc \fBpractcl::platform::tcl_core_options\fR \fIos\fR -Return the string to pass to \&./configure to compile the Tcl core for the given OS\&. -.RS -.IP \(bu -windows: --with-tzdata --with-encoding utf-8 -.IP \(bu -macosx: --enable-corefoundation=yes --enable-framework=no --with-tzdata --with-encoding utf-8 -.IP \(bu -other: --with-tzdata --with-encoding utf-8 -.RE -.TP -proc \fBpractcl::platform::tk_core_options\fR \fIos\fR -.TP -proc \fBpractcl::read_rc_file\fR \fIfilename\fR ?\fIlocaldat\fR \fB\fR? -Read a stylized key/value list stored in a file -.TP -proc \fBpractcl::read_sh_subst\fR \fIline\fR \fIinfo\fR -Converts a XXX\&.sh file into a series of Tcl variables -.TP -proc \fBpractcl::read_sh_file\fR \fIfilename\fR ?\fIlocaldat\fR \fB\fR? -.TP -proc \fBpractcl::read_Config\&.sh\fR \fIfilename\fR -A simpler form of read_sh_file tailored -to pulling data from (tcl|tk)Config\&.sh -.TP -proc \fBpractcl::read_Makefile\fR \fIfilename\fR -A simpler form of read_sh_file tailored -to pulling data from a Makefile -.TP -proc \fBpractcl::cputs\fR \fIvarname\fR ?\fIargs\fR? -Append arguments to a buffer -The command works like puts in that each call will also insert -a line feed\&. Unlike puts, blank links in the interstitial are -suppressed -.TP -proc \fBpractcl::tcl_to_c\fR \fIbody\fR -.TP -proc \fBpractcl::_tagblock\fR \fItext\fR ?\fIstyle\fR \fBtcl\fR? ?\fInote\fR \fB\fR? -.TP -proc \fBpractcl::de_shell\fR \fIdata\fR -.TP -proc \fBpractcl::grep\fR \fIpattern\fR ?\fIfiles\fR \fB\fR? -Search for the pattern \fIpattern\fR amongst $files -.TP -proc \fBpractcl::file_lexnormalize\fR \fIsp\fR -.TP -proc \fBpractcl::file_relative\fR \fIbase\fR \fIdst\fR -Calculate a relative path between base and dst -.sp -Example: -.CS - - ::practcl::file_relative ~/build/tcl/unix ~/build/tcl/library - > \&.\&./library - - - -.CE -.TP -proc \fBpractcl::findByPattern\fR \fIbasedir\fR \fIpatterns\fR -.TP -proc \fBpractcl::log\fR \fIfname\fR \fIcomment\fR -Record an event in the practcl log -.TP -proc \fBpractcl::_pkgindex_simpleIndex\fR \fIpath\fR -.TP -proc \fBpractcl::_pkgindex_directory\fR \fIpath\fR -Return true if the pkgindex file contains -any statement other than "package ifneeded" -and/or if any package ifneeded loads a DLL -.TP -proc \fBpractcl::_pkgindex_path_subdir\fR \fIpath\fR -Helper function for ::practcl::pkgindex_path -.TP -proc \fBpractcl::pkgindex_path\fR ?\fIargs\fR? -Index all paths given as though they will end up in the same -virtual file system -.TP -proc \fBpractcl::installDir\fR \fId1\fR \fId2\fR -Delete the contents of \fId2\fR, and then -recusively Ccopy the contents of \fId1\fR to \fId2\fR\&. -.TP -proc \fBpractcl::copyDir\fR \fId1\fR \fId2\fR ?\fItoplevel\fR \fB1\fR? -Recursively copy the contents of \fId1\fR to \fId2\fR -.TP -proc \fBpractcl::buildModule\fR \fImodpath\fR -.TP -proc \fBpractcl::installModule\fR \fImodpath\fR \fIDEST\fR -Install a module from MODPATH to the directory specified\&. -\fIdpath\fR is assumed to be the fully qualified path where module is to be placed\&. -Any existing files will be deleted at that path\&. -If the path is symlink the process will return with no error and no action\&. -If the module has contents in the build/ directory that are newer than the -\&.tcl files in the module source directory, and a build/build\&.tcl file exists, -the build/build\&.tcl file is run\&. -If the source directory includes a file named index\&.tcl, the directory is assumed -to be in the tao style of modules, and the entire directory (and all subdirectories) -are copied verbatim\&. -If no index\&.tcl file is present, all \&.tcl files are copied from the module source -directory, and a pkgIndex\&.tcl file is generated if non yet exists\&. -I a folder named htdocs exists in the source directory, that directory is copied -verbatim to the destination\&. -.TP -proc \fBpractcl::trigger\fR ?\fIargs\fR? -Trigger build targets, and recompute dependencies -.sp -Internals: -.CS - - - ::practcl::LOCAL make trigger {*}$args - foreach {name obj} [::practcl::LOCAL make objects] { - set ::make($name) [$obj do] - } - -.CE -.TP -proc \fBpractcl::depends\fR ?\fIargs\fR? -Calculate if a dependency for any of the arguments needs to -be fulfilled or rebuilt\&. -.sp -Internals: -.CS - - - ::practcl::LOCAL make depends {*}$args - -.CE -.TP -proc \fBpractcl::target\fR \fIname\fR \fIinfo\fR ?\fIaction\fR \fB\fR? -Declare a build product\&. This proc is just a shorthand for -\fI::practcl::LOCAL make task $name $info $action\fR -.sp -Registering a build product with this command will create -an entry in the global array, and populate -a value in the global array\&. -.sp -Internals: -.CS - - - set obj [::practcl::LOCAL make task $name $info $action] - set ::make($name) 0 - set filename [$obj define get filename] - if {$filename ne {}} { - set ::target($name) $filename - } - -.CE -.PP -.SH CLASSES -.SS "CLASS PRACTCL::DOCTOOL" -.CS - -{ set authors { - {John Doe} {jdoe@illustrious\&.edu} - {Tom RichardHarry} {tomdickharry@illustrius\&.edu} - } - # Create the object - ::practcl::doctool create AutoDoc - set fout [open [file join $moddir module\&.tcl] w] - foreach file [glob [file join $srcdir *\&.tcl]] { - set content [::practcl::cat [file join $srcdir $file]] - # Scan the file - AutoDoc scan_text $content - # Strip the comments from the distribution - puts $fout [::practcl::docstrip $content] - } - # Write out the manual page - set manout [open [file join $moddir module\&.man] w] - dict set args header [string map $modmap [::practcl::cat [file join $srcdir manual\&.txt]]] - dict set args footer [string map $modmap [::practcl::cat [file join $srcdir footer\&.txt]]] - dict set args authors $authors - puts $manout [AutoDoc manpage {*}$args] - close $manout - - -} -.CE -.PP -Tool for build scripts to dynamically generate manual files from comments -in source code files -.PP -\fBMethods\fR -.TP -method \fBconstructor\fR -.TP -method \fBargspec\fR \fIargspec\fR -Process an argument list into an informational dict\&. -This method also understands non-positional -arguments expressed in the notation of Tip 471 -\fIhttps://core\&.tcl-lang\&.org/tips/doc/trunk/tip/479\&.md\fR\&. -.sp -The output will be a dictionary of all of the fields and whether the fields -are \fBpositional\fR, \fBmandatory\fR, and whether they have a -\fBdefault\fR value\&. -.sp -.sp -Example: -.CS - - my argspec {a b {c 10}} - - > a {positional 1 mandatory 1} b {positional 1 mandatory 1} c {positional 1 mandatory 0 default 10} - - - -.CE -.TP -method \fBcomment\fR \fIblock\fR -Convert a block of comments into an informational dictionary\&. -If lines in the comment start with a single word ending in a colon, -all subsequent lines are appended to a dictionary field of that name\&. -If no fields are given, all of the text is appended to the \fBdescription\fR -field\&. -.sp -Example: -.CS - - my comment {Does something cool} - > description {Does something cool} - - my comment { - title : Something really cool - author : Sean Woods - author : John Doe - description : - This does something really cool! - } - > description {This does something really cool!} - title {Something really cool} - author {Sean Woods - John Doe} - - - -.CE -.TP -method \fBkeyword\&.Annotation\fR \fIresultvar\fR \fIcommentblock\fR \fItype\fR \fIname\fR \fIbody\fR -.TP -method \fBkeyword\&.Class\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR \fIbody\fR -Process an oo::objdefine call that modifies the class object -itself -.TP -method \fBkeyword\&.class\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR \fIbody\fR -Process an oo::define, clay::define, etc statement\&. -.TP -method \fBkeyword\&.Class_Method\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR ?\fIargs\fR? -Process a statement for a clay style class method -.TP -method \fBkeyword\&.method\fR \fIresultvar\fR \fIcommentblock\fR \fIname\fR ?\fIargs\fR? -Process a statement for a tcloo style object method -.TP -method \fBkeyword\&.proc\fR \fIcommentblock\fR \fIname\fR \fIargspec\fR -Process a proc statement -.TP -method \fBreset\fR -Reset the state of the object and its embedded coroutine -.TP -method \fBMain\fR -Main body of the embedded coroutine for the object -.TP -method \fBsection\&.method\fR \fIkeyword\fR \fImethod\fR \fIminfo\fR -Generate the manual page text for a method or proc -.TP -method \fBsection\&.annotation\fR \fItype\fR \fIname\fR \fIiinfo\fR -.TP -method \fBsection\&.class\fR \fIclass_name\fR \fIclass_info\fR -Generate the manual page text for a class -.TP -method \fBsection\&.command\fR \fIprocinfo\fR -Generate the manual page text for the commands section -.TP -method \fBmanpage\fR ?\fBheader \fIvalue\fR\fR? ?\fBfooter \fIvalue\fR\fR? ?\fBauthors \fIlist\fR\fR? -Generate the manual page\&. Returns the completed text suitable for saving in \&.man file\&. -The header argument is a block of doctools text to go in before the machine generated -section\&. footer is a block of doctools text to go in after the machine generated -section\&. authors is a list of individual authors and emails in the form of AUTHOR EMAIL ?AUTHOR EMAIL?\&.\&.\&. -.TP -method \fBscan_text\fR \fItext\fR -Scan a block of text -.TP -method \fBscan_file\fR \fIfilename\fR -Scan a file of text -.PP -.PP -.SS "CLASS PRACTCL::METACLASS" -The metaclass for all practcl objects -.PP -\fBMethods\fR -.TP -method \fB_MorphPatterns\fR -.TP -method \fBdefine\fR \fIsubmethod\fR ?\fIargs\fR? -.TP -method \fBgraft\fR ?\fIargs\fR? -.TP -method \fBinitialize\fR -.TP -method \fBlink\fR \fIcommand\fR ?\fIargs\fR? -.TP -method \fBmorph\fR \fIclassname\fR -.TP -method \fBscript\fR \fIscript\fR -.TP -method \fBselect\fR -.TP -method \fBsource\fR \fIfilename\fR -.PP -.PP -.SS "CLASS PRACTCL::TOOLSET" -Ancestor-less class intended to be a mixin -which defines a family of build related behaviors -that are modified when targetting either gcc or msvc -.PP -\fBClass Methods\fR -.TP -classmethod \fBselect\fR \fIobject\fR -Perform the selection for the toolset mixin -.PP -.PP -\fBMethods\fR -.TP -method \fBconfig\&.sh\fR -find or fake a key/value list describing this project -.TP -method \fBBuildDir\fR \fIPWD\fR -Compute the location where the product will be built -.TP -method \fBMakeDir\fR \fIsrcdir\fR -Return where the Makefile is located relative to \fIsrcdir\fR\&. -For this implementation the MakeDir is always srcdir\&. -.TP -method \fBread_configuration\fR -Read information about the build process for this package\&. -For this implementation, data is sought in the following locations -in the following order: -config\&.tcl (generated by practcl\&.) PKGConfig\&.sh\&. The Makefile -.sp -If the Makefile needs to be consulted, but does not exist, the -Configure method is invoked -.TP -method \fBbuild-cflags\fR \fIPROJECT\fR \fIDEFS\fR \fInamevar\fR \fIversionvar\fR \fIdefsvar\fR -method DEFS -This method populates 4 variables: -name - The name of the package -version - The version of the package -defs - C flags passed to the compiler -includedir - A list of paths to feed to the compiler for finding headers -.TP -method \fBcritcl\fR ?\fIargs\fR? -Invoke critcl in an external process -.PP -.PP -.SS "CLASS PRACTCL::TOOLSET\&.GCC" -\fIancestors\fR: \fBpractcl::toolset\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBAutoconf\fR -.TP -method \fBBuildDir\fR \fIPWD\fR -.TP -method \fBConfigureOpts\fR -.TP -method \fBMakeDir\fR \fIsrcdir\fR -Detect what directory contains the Makefile template -.TP -method \fBmake {} autodetect\fR -.TP -method \fBmake {} clean\fR -.TP -method \fBmake {} compile\fR -.TP -method \fBmake {} install\fR \fIDEST\fR -.TP -method \fBbuild-compile-sources\fR \fIPROJECT\fR \fICOMPILE\fR \fICPPCOMPILE\fR \fIINCLUDES\fR -.TP -method \fBbuild-Makefile\fR \fIpath\fR \fIPROJECT\fR -.TP -method \fBbuild-library\fR \fIoutfile\fR \fIPROJECT\fR -Produce a static or dynamic library -.TP -method \fBbuild-tclsh\fR \fIoutfile\fR \fIPROJECT\fR ?\fIpath\fR \fBauto\fR? -Produce a static executable -.PP -.PP -.SS "CLASS PRACTCL::TOOLSET\&.MSVC" -\fIancestors\fR: \fBpractcl::toolset\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBBuildDir\fR \fIPWD\fR -MSVC always builds in the source directory -.TP -method \fBmake {} autodetect\fR -Do nothing -.TP -method \fBmake {} clean\fR -.TP -method \fBmake {} compile\fR -.TP -method \fBmake {} install\fR \fIDEST\fR -.TP -method \fBMakeDir\fR \fIsrcdir\fR -Detect what directory contains the Makefile template -.TP -method \fBNmakeOpts\fR -.PP -.PP -.SS "CLASS PRACTCL::MAKE_OBJ" -\fIancestors\fR: \fBpractcl::metaclass\fR -.PP -A build deliverable object\&. Normally an object file, header, or tcl script -which must be compiled or generated in some way -.PP -\fBMethods\fR -.TP -method \fBconstructor\fR \fImodule_object\fR \fIname\fR \fIinfo\fR ?\fIaction_body\fR \fB\fR? -.TP -method \fBdo\fR -.TP -method \fBcheck\fR -.TP -method \fBoutput\fR -.TP -method \fBreset\fR -.TP -method \fBtriggers\fR -.PP -.PP -.SS "CLASS PRACTCL::OBJECT" -\fIancestors\fR: \fBpractcl::metaclass\fR -.PP -A generic Practcl object -.PP -\fBMethods\fR -.TP -method \fBconstructor\fR \fIparent\fR ?\fIargs\fR? -.TP -method \fBchild\fR \fImethod\fR -.TP -method \fBgo\fR -.PP -.PP -.SS "CLASS PRACTCL::DYNAMIC" -Dynamic blocks do not generate their own \&.c files, -instead the contribute to the amalgamation -of the main library file -.PP -\fBMethods\fR -.TP -method \fBcstructure\fR \fIname\fR \fIdefinition\fR ?\fIargdat\fR \fB\fR? -Parser functions -.TP -method \fBinclude\fR \fIheader\fR -.TP -method \fBinclude_dir\fR ?\fIargs\fR? -.TP -method \fBinclude_directory\fR ?\fIargs\fR? -.TP -method \fBc_header\fR \fIbody\fR -.TP -method \fBc_code\fR \fIbody\fR -.TP -method \fBc_function\fR \fIheader\fR \fIbody\fR ?\fIinfo\fR \fB\fR? -.TP -method \fBc_tcloomethod\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.TP -method \fBcmethod\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -Alias to classic name -.TP -method \fBc_tclproc_nspace\fR \fInspace\fR -.TP -method \fBc_tclcmd\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -.TP -method \fBc_tclproc_raw\fR \fIname\fR \fIbody\fR ?\fIarginfo\fR \fB\fR? -Alias to classic name -.TP -method \fBtcltype\fR \fIname\fR \fIargdat\fR -.TP -method \fBproject-compile-products\fR -Module interactions -.TP -method \fBimplement\fR \fIpath\fR -.TP -method \fBinitialize\fR -Practcl internals -.TP -method \fBlinktype\fR -.TP -method \fBgenerate-cfile-constant\fR -.TP -method \fBgenerate-cfile-header\fR -.TP -method \fBgenerate-cfile-tclapi\fR -Generate code that provides implements Tcl API -calls -.TP -method \fBgenerate-loader-module\fR -Generate code that runs when the package/module is -initialized into the interpreter -.TP -method \fBCollate_Source\fR \fICWD\fR -.TP -method \fBselect\fR -Once an object marks itself as some -flavor of dynamic, stop trying to morph -it into something else -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT" -A deliverable for the build system -.PP -\fBClass Methods\fR -.TP -classmethod \fBselect\fR \fIobject\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBcode\fR \fIsection\fR \fIbody\fR -.TP -method \fBCollate_Source\fR \fICWD\fR -.TP -method \fBproject-compile-products\fR -.TP -method \fBgenerate-debug\fR ?\fIspaces\fR \fB\fR? -.TP -method \fBgenerate-cfile-constant\fR -.TP -method \fBgenerate-cfile-public-structure\fR -Populate const static data structures -.TP -method \fBgenerate-cfile-header\fR -.TP -method \fBgenerate-cfile-global\fR -.TP -method \fBgenerate-cfile-private-typedef\fR -.TP -method \fBgenerate-cfile-private-structure\fR -.TP -method \fBgenerate-cfile-functions\fR -Generate code that provides subroutines called by -Tcl API methods -.TP -method \fBgenerate-cfile-tclapi\fR -Generate code that provides implements Tcl API -calls -.TP -method \fBgenerate-hfile-public-define\fR -.TP -method \fBgenerate-hfile-public-macro\fR -.TP -method \fBgenerate-hfile-public-typedef\fR -.TP -method \fBgenerate-hfile-public-structure\fR -.TP -method \fBgenerate-hfile-public-headers\fR -.TP -method \fBgenerate-hfile-public-function\fR -.TP -method \fBgenerate-hfile-public-includes\fR -.TP -method \fBgenerate-hfile-public-verbatim\fR -.TP -method \fBgenerate-loader-external\fR -.TP -method \fBgenerate-loader-module\fR -.TP -method \fBgenerate-stub-function\fR -.TP -method \fBIncludeAdd\fR \fIheadervar\fR ?\fIargs\fR? -.TP -method \fBgenerate-tcl-loader\fR -.TP -method \fBgenerate-tcl-pre\fR -This methods generates any Tcl script file -which is required to pre-initialize the C library -.TP -method \fBgenerate-tcl-post\fR -.TP -method \fBlinktype\fR -.TP -method \fBOfile\fR \fIfilename\fR -.TP -method \fBproject-static-packages\fR -Methods called by the master project -.TP -method \fBtoolset-include-directory\fR -Methods called by the toolset -.TP -method \fBtarget\fR \fImethod\fR ?\fIargs\fR? -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT\&.CHEADER" -\fIancestors\fR: \fBpractcl::product\fR -.PP -A product which generated from a C header file\&. Which is to say, nothing\&. -.PP -\fBMethods\fR -.TP -method \fBproject-compile-products\fR -.TP -method \fBgenerate-loader-module\fR -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT\&.CSOURCE" -\fIancestors\fR: \fBpractcl::product\fR -.PP -A product which generated from a C source file\&. Normally an object (\&.o) file\&. -.PP -\fBMethods\fR -.TP -method \fBproject-compile-products\fR -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT\&.CLIBRARY" -\fIancestors\fR: \fBpractcl::product\fR -.PP -A product which is generated from a compiled C library\&. -Usually a \&.a or a \&.dylib file, but in complex cases may -actually just be a conduit for one project to integrate the -source code of another -.PP -\fBMethods\fR -.TP -method \fBlinker-products\fR \fIconfigdict\fR -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT\&.DYNAMIC" -\fIancestors\fR: \fBpractcl::dynamic\fR \fBpractcl::product\fR -.PP -A product which is generated from C code that itself is generated -by practcl or some other means\&. This C file may or may not produce -its own \&.o file, depending on whether it is eligible to become part -of an amalgamation -.PP -\fBMethods\fR -.TP -method \fBinitialize\fR -.PP -.PP -.SS "CLASS PRACTCL::PRODUCT\&.CRITCL" -\fIancestors\fR: \fBpractcl::dynamic\fR \fBpractcl::product\fR -.PP -A binary product produced by critcl\&. Note: The implementation is not -written yet, this class does nothing\&. -.PP -.SS "CLASS PRACTCL::MODULE" -\fIancestors\fR: \fBpractcl::object\fR \fBpractcl::product\&.dynamic\fR -.PP -In the end, all C code must be loaded into a module -This will either be a dynamically loaded library implementing -a tcl extension, or a compiled in segment of a custom shell/app -.PP -\fBVariable\fR -.TP -variable \fBmake_object\fR -.PP -.PP -\fBMethods\fR -.TP -method \fB_MorphPatterns\fR -.TP -method \fBadd\fR ?\fIargs\fR? -.TP -method \fBinstall-headers\fR ?\fIargs\fR? -.TP -method \fBmake {} _preamble\fR -.TP -method \fBmake {} pkginfo\fR -.TP -method \fBmake {} objects\fR -Return a dictionary of all handles and associated objects -.TP -method \fBmake {} object\fR \fIname\fR -Return the object associated with handle \fIname\fR -.TP -method \fBmake {} reset\fR -Reset all deputy objects -.TP -method \fBmake {} trigger\fR ?\fIargs\fR? -Exercise the triggers method for all handles listed -.TP -method \fBmake {} depends\fR ?\fIargs\fR? -Exercise the check method for all handles listed -.TP -method \fBmake {} filename\fR \fIname\fR -Return the file name of the build product for the listed -handle -.TP -method \fBmake {} target\fR \fIname\fR \fIInfo\fR \fIbody\fR -.TP -method \fBmake {} todo\fR -Return a list of handles for object which return true for the -do method -.TP -method \fBmake {} do\fR -For each target exercise the action specified in the \fIaction\fR -definition if the \fIdo\fR method returns true -.TP -method \fBchild\fR \fIwhich\fR -.TP -method \fBgenerate-c\fR -This methods generates the contents of an amalgamated \&.c file -which implements the loader for a batch of tools -.TP -method \fBgenerate-h\fR -This methods generates the contents of an amalgamated \&.h file -which describes the public API of this module -.TP -method \fBgenerate-loader\fR -.TP -method \fBinitialize\fR -.TP -method \fBimplement\fR \fIpath\fR -.TP -method \fBlinktype\fR -.PP -.PP -.SS "CLASS PRACTCL::PROJECT" -\fIancestors\fR: \fBpractcl::module\fR -.PP -A toplevel project that is a collection of other projects -.PP -\fBMethods\fR -.TP -method \fB_MorphPatterns\fR -.TP -method \fBconstructor\fR ?\fIargs\fR? -.TP -method \fBadd_object\fR \fIobject\fR -.TP -method \fBadd_project\fR \fIpkg\fR \fIinfo\fR ?\fIoodefine\fR \fB\fR? -.TP -method \fBadd_tool\fR \fIpkg\fR \fIinfo\fR ?\fIoodefine\fR \fB\fR? -.TP -method \fBbuild-tclcore\fR -Compile the Tcl core\&. If the define \fItk\fR is true, compile the -Tk core as well -.TP -method \fBchild\fR \fIwhich\fR -.TP -method \fBlinktype\fR -.TP -method \fBproject\fR \fIpkg\fR ?\fIargs\fR? -Exercise the methods of a sub-object -.TP -method \fBtclcore\fR -.TP -method \fBtkcore\fR -.TP -method \fBtool\fR \fIpkg\fR ?\fIargs\fR? -.PP -.PP -.SS "CLASS PRACTCL::LIBRARY" -\fIancestors\fR: \fBpractcl::project\fR -.PP -A toplevel project that produces a library -.PP -\fBMethods\fR -.TP -method \fBclean\fR \fIPATH\fR -.TP -method \fBproject-compile-products\fR -.TP -method \fBgo\fR -.TP -method \fBgenerate-decls\fR \fIpkgname\fR \fIpath\fR -.TP -method \fBimplement\fR \fIpath\fR -.TP -method \fBgenerate-make\fR \fIpath\fR -Backward compadible call -.TP -method \fBlinktype\fR -.TP -method \fBpackage-ifneeded\fR ?\fIargs\fR? -Create a "package ifneeded" -Args are a list of aliases for which this package will answer to -.TP -method \fBshared_library\fR ?\fIfilename\fR \fB\fR? -.TP -method \fBstatic_library\fR ?\fIfilename\fR \fB\fR? -.PP -.PP -.SS "CLASS PRACTCL::TCLKIT" -\fIancestors\fR: \fBpractcl::library\fR -.PP -A toplevel project that produces a self-contained executable -.PP -\fBMethods\fR -.TP -method \fBbuild-tclkit_main\fR \fIPROJECT\fR \fIPKG_OBJS\fR -.TP -method \fBCollate_Source\fR \fICWD\fR -.TP -method \fBwrap\fR \fIPWD\fR \fIexename\fR \fIvfspath\fR ?\fIargs\fR? -Wrap an executable -.PP -.PP -.SS "CLASS PRACTCL::DISTRIBUTION" -Standalone class to manage code distribution -This class is intended to be mixed into another class -(Thus the lack of ancestors) -.PP -\fBClass Methods\fR -.TP -classmethod \fBSandbox\fR \fIobject\fR -.TP -classmethod \fBselect\fR \fIobject\fR -.TP -classmethod \fBclaim_option\fR -.TP -classmethod \fBclaim_object\fR \fIobject\fR -.TP -classmethod \fBclaim_path\fR \fIpath\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBscm_info\fR -.TP -method \fBDistroMixIn\fR -.TP -method \fBSandbox\fR -.TP -method \fBSrcDir\fR -.TP -method \fBScmTag\fR -.TP -method \fBScmClone\fR -.TP -method \fBScmUnpack\fR -.TP -method \fBScmUpdate\fR -.TP -method \fBUnpack\fR -.PP -.PP -.SS "CLASS PRACTCL::DISTRIBUTION\&.SNAPSHOT" -\fIancestors\fR: \fBpractcl::distribution\fR -.PP -A file distribution from zip, tarball, or other non-scm archive format -.PP -\fBClass Methods\fR -.TP -classmethod \fBclaim_object\fR \fIobject\fR -.TP -classmethod \fBclaim_option\fR -.TP -classmethod \fBclaim_path\fR \fIpath\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBScmUnpack\fR -.PP -.PP -.SS "CLASS PRACTCL::DISTRIBUTION\&.FOSSIL" -\fIancestors\fR: \fBpractcl::distribution\fR -.PP -A file distribution based on fossil -.PP -\fBClass Methods\fR -.TP -classmethod \fBclaim_object\fR \fIobj\fR -Check for markers in the metadata -.TP -classmethod \fBclaim_option\fR -.TP -classmethod \fBclaim_path\fR \fIpath\fR -Check for markers in the source root -.PP -.PP -\fBMethods\fR -.TP -method \fBscm_info\fR -.TP -method \fBScmClone\fR -Clone the source -.TP -method \fBScmTag\fR -.TP -method \fBScmUnpack\fR -.TP -method \fBScmUpdate\fR -.PP -.PP -.SS "CLASS PRACTCL::DISTRIBUTION\&.GIT" -\fIancestors\fR: \fBpractcl::distribution\fR -.PP -A file distribution based on git -.PP -\fBClass Methods\fR -.TP -classmethod \fBclaim_object\fR \fIobj\fR -.TP -classmethod \fBclaim_option\fR -.TP -classmethod \fBclaim_path\fR \fIpath\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBScmTag\fR -.TP -method \fBScmUnpack\fR -.TP -method \fBScmUpdate\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT" -\fIancestors\fR: \fBpractcl::module\fR -.PP -A subordinate project -.PP -\fBMethods\fR -.TP -method \fB_MorphPatterns\fR -.TP -method \fBBuildDir\fR \fIPWD\fR -.TP -method \fBchild\fR \fIwhich\fR -.TP -method \fBcompile\fR -.TP -method \fBgo\fR -.TP -method \fBinstall\fR ?\fIargs\fR? -Install project into the local build system -.TP -method \fBlinktype\fR -.TP -method \fBlinker-products\fR \fIconfigdict\fR -.TP -method \fBlinker-external\fR \fIconfigdict\fR -.TP -method \fBlinker-extra\fR \fIconfigdict\fR -.TP -method \fBenv-bootstrap\fR -Methods for packages/tools that can be downloaded -possibly built and used internally by this Practcl -process -Load the facility into the interpreter -.TP -method \fBenv-exec\fR -Return a file path that exec can call -.TP -method \fBenv-install\fR -Install the tool into the local environment -.TP -method \fBenv-load\fR -Do whatever is necessary to get the tool -into the local environment -.TP -method \fBenv-present\fR -Check if tool is available for load/already loaded -.TP -method \fBsources\fR -.TP -method \fBupdate\fR -.TP -method \fBunpack\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.SOURCE" -\fIancestors\fR: \fBpractcl::subproject\fR \fBpractcl::library\fR -.PP -A project which the kit compiles and integrates -the source for itself -.PP -\fBMethods\fR -.TP -method \fBenv-bootstrap\fR -.TP -method \fBenv-present\fR -.TP -method \fBlinktype\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.TEAPOT" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -a copy from the teapot -.PP -\fBMethods\fR -.TP -method \fBenv-bootstrap\fR -.TP -method \fBenv-install\fR -.TP -method \fBenv-present\fR -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.KETTLE" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBkettle\fR \fIpath\fR ?\fIargs\fR? -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.CRITCL" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.SAK" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBenv-bootstrap\fR -.TP -method \fBenv-install\fR -.TP -method \fBenv-present\fR -.TP -method \fBinstall\fR \fIDEST\fR -.TP -method \fBinstall-module\fR \fIDEST\fR ?\fIargs\fR? -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.PRACTCL" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBenv-bootstrap\fR -.TP -method \fBenv-install\fR -.TP -method \fBinstall\fR \fIDEST\fR -.TP -method \fBinstall-module\fR \fIDEST\fR ?\fIargs\fR? -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.BINARY" -\fIancestors\fR: \fBpractcl::subproject\fR -.PP -A subordinate binary package -.PP -\fBMethods\fR -.TP -method \fBclean\fR -.TP -method \fBenv-install\fR -.TP -method \fBproject-compile-products\fR -.TP -method \fBComputeInstall\fR -.TP -method \fBgo\fR -.TP -method \fBlinker-products\fR \fIconfigdict\fR -.TP -method \fBproject-static-packages\fR -.TP -method \fBBuildDir\fR \fIPWD\fR -.TP -method \fBcompile\fR -.TP -method \fBConfigure\fR -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.TEA" -\fIancestors\fR: \fBpractcl::subproject\&.binary\fR -.PP -A subordinate TEA based binary package -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.LIBRARY" -\fIancestors\fR: \fBpractcl::subproject\&.binary\fR \fBpractcl::library\fR -.PP -A subordinate C library built by this project -.PP -\fBMethods\fR -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.EXTERNAL" -\fIancestors\fR: \fBpractcl::subproject\&.binary\fR -.PP -A subordinate external C library -.PP -\fBMethods\fR -.TP -method \fBinstall\fR \fIDEST\fR -.PP -.PP -.SS "CLASS PRACTCL::SUBPROJECT\&.CORE" -\fIancestors\fR: \fBpractcl::subproject\&.binary\fR -.PP -.PP -\fBMethods\fR -.TP -method \fBenv-bootstrap\fR -.TP -method \fBenv-present\fR -.TP -method \fBenv-install\fR -.TP -method \fBgo\fR -.TP -method \fBlinktype\fR -.PP +\fBCPUTS\fR \fIvarname\fR \fIbody\fR ?\fIbody\fR\&.\&.\&.? +Appends blocks of text to a buffer\&. This command tries to reduce the number +of line breaks between bodies\&. +.TP +\fBpractcl::_isdirectory\fR \fIpath\fR +Returns true if \fIpath\fR is a directory, using the test +.PP +.TP +\fBpractcl::object\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A generic Practcl object +.TP +\fBpractcl::library\fR ?\fIkeyvaluelist\fR? +A Practcl object representing a library container +.TP +\fBpractcl::exe\fR ?\fIkeyvaluelist\fR? +A Practcl object representing a wrapped executable +.TP +\fBpractcl::product\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A Practcl object representing a compiled product +.TP +\fBpractcl::cheader\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A Practcl object representing an externally generated c header +.TP +\fBpractcl::csource\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A Practcl object representing an externally generated c source file +.TP +\fBpractcl::module\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A Practcl object representing a dynamically generated C/H/Tcl suite +.TP +\fBpractcl::submodule\fR \fIparent\fR ?\fIkeyvaluelist\fR? +A Practcl object representing a dynamically generated C/H/Tcl suite, subordinate to a module .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIpractcl\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS practcl .SH CATEGORY TclOO .SH COPYRIGHT .nf -Copyright (c) 2016-2018 Sean Woods +Copyright (c) 2016 Sean Woods .fi Index: idoc/man/files/modules/processman/processman.n ================================================================== --- idoc/man/files/modules/processman/processman.n +++ idoc/man/files/modules/processman/processman.n @@ -350,22 +350,14 @@ bugs and other problems\&. Please report such in the category \fIodie\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS odie, processman .SH CATEGORY System .SH COPYRIGHT .nf Copyright (c) 2015 Sean Woods .fi Index: idoc/man/files/modules/profiler/profiler.n ================================================================== --- idoc/man/files/modules/profiler/profiler.n +++ idoc/man/files/modules/profiler/profiler.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'profiler\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "profiler" n 0\&.5 tcllib "Tcl Profiler" +.TH "profiler" n 0\&.3 tcllib "Tcl Profiler" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME profiler \- Tcl source code profiler .SH SYNOPSIS package require \fBTcl 8\&.3\fR .sp -package require \fBprofiler ?0\&.5?\fR +package require \fBprofiler ?0\&.3?\fR .sp \fB::profiler::init\fR .sp \fB::profiler::dump\fR \fIpattern\fR .sp @@ -287,14 +287,10 @@ .sp \fB::profiler::suspend\fR ?\fIpattern\fR? .sp \fB::profiler::resume\fR ?\fIpattern\fR? .sp -\fB::profiler::new-disabled\fR -.sp -\fB::profiler::new-enabled\fR -.sp \fB::profiler::sortFunctions\fR \fIkey\fR .sp .BE .SH DESCRIPTION .PP @@ -367,22 +363,10 @@ Resume profiling for all functions matching \fIpattern\fR\&. If no pattern is specified, profiling will be resumed for all functions\&. This command should be invoked after suspending the profiler in the code\&. .TP -\fB::profiler::new-disabled\fR -Change the initial profiling state for new procedures\&. Invoking this -command disables profiling for all procedures created after this -command until \fBnew-enabled\fR is invoked\&. Activate profiling of -specific procedures via \fBresume\fR\&. -.TP -\fB::profiler::new-enabled\fR -Change the initial profiling state for new procedures\&. Invoking this -command enables profiling for all procedures created after this -command until \fBnew-disabled\fR is invoked\&. Prevent profiling of -specific procedures via \fBsuspend\fR\&. -.TP \fB::profiler::sortFunctions\fR \fIkey\fR Return a list of functions sorted by a particular profiling statistic\&. Supported values for \fIkey\fR are: \fBcalls\fR, \fBexclusiveTime\fR, \fBcompileTime\fR, \fBnonCompileTime\fR, \fBtotalRuntime\fR, \fBavgExclusiveTime\fR, and @@ -395,17 +379,9 @@ bugs and other problems\&. Please report such in the category \fIprofiler\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS performance, profile, speed .SH CATEGORY Programming tools Index: idoc/man/files/modules/pt/pt_astree.n ================================================================== --- idoc/man/files/modules/pt/pt_astree.n +++ idoc/man/files/modules/pt/pt_astree.n @@ -548,22 +548,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_cparam_config_critcl.n ================================================================== --- idoc/man/files/modules/pt/pt_cparam_config_critcl.n +++ idoc/man/files/modules/pt/pt_cparam_config_critcl.n @@ -320,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_cparam_config_tea.n ================================================================== --- idoc/man/files/modules/pt/pt_cparam_config_tea.n +++ idoc/man/files/modules/pt/pt_cparam_config_tea.n @@ -320,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_from_api.n ================================================================== --- idoc/man/files/modules/pt/pt_from_api.n +++ idoc/man/files/modules/pt/pt_from_api.n @@ -757,22 +757,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_introduction.n ================================================================== --- idoc/man/files/modules/pt/pt_introduction.n +++ idoc/man/files/modules/pt/pt_introduction.n @@ -429,22 +429,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_json_language.n ================================================================== --- idoc/man/files/modules/pt/pt_json_language.n +++ idoc/man/files/modules/pt/pt_json_language.n @@ -750,22 +750,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_param.n ================================================================== --- idoc/man/files/modules/pt/pt_param.n +++ idoc/man/files/modules/pt/pt_param.n @@ -775,22 +775,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_parse_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_parse_peg.n +++ idoc/man/files/modules/pt/pt_parse_peg.n @@ -375,22 +375,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_parser_api.n ================================================================== --- idoc/man/files/modules/pt/pt_parser_api.n +++ idoc/man/files/modules/pt/pt_parser_api.n @@ -705,22 +705,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_container.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_container.n +++ idoc/man/files/modules/pt/pt_peg_container.n @@ -938,22 +938,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_container_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_container_peg.n +++ idoc/man/files/modules/pt/pt_peg_container_peg.n @@ -303,22 +303,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_export.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_export.n +++ idoc/man/files/modules/pt/pt_peg_export.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pt_peg_export\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "pt::peg::export" n 1\&.0\&.1 tcllib "Parser Tools" +.TH "pt::peg::export" n 1 tcllib "Parser Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -276,17 +276,17 @@ .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp package require \fBsnit \fR .sp -package require \fBstruct::map \fR +package require \fBconfiguration \fR .sp package require \fBpt::peg \fR .sp package require \fBpluginmgr \fR .sp -package require \fBpt::peg::export ?1\&.0\&.1?\fR +package require \fBpt::peg::export ?1?\fR .sp \fB::pt::peg::export\fR \fIobjectName\fR .sp \fBobjectName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? .sp @@ -759,22 +759,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_export_container.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_export_container.n +++ idoc/man/files/modules/pt/pt_peg_export_container.n @@ -759,22 +759,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS CONTAINER, EBNF, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_export_json.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_export_json.n +++ idoc/man/files/modules/pt/pt_peg_export_json.n @@ -818,22 +818,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, JSON, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_export_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_export_peg.n +++ idoc/man/files/modules/pt/pt_peg_export_peg.n @@ -810,22 +810,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, export, expression, grammar, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_from_container.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_from_container.n +++ idoc/man/files/modules/pt/pt_peg_from_container.n @@ -297,22 +297,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_from_json.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_from_json.n +++ idoc/man/files/modules/pt/pt_peg_from_json.n @@ -784,22 +784,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, JSON, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_from_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_from_peg.n +++ idoc/man/files/modules/pt/pt_peg_from_peg.n @@ -760,22 +760,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_import.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_import.n +++ idoc/man/files/modules/pt/pt_peg_import.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pt_peg_import\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "pt::peg::import" n 1\&.0\&.1 tcllib "Parser Tools" +.TH "pt::peg::import" n 1 tcllib "Parser Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,21 +274,19 @@ .SH NAME pt::peg::import \- PEG Import .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBTcl 8\&.5\fR -.sp package require \fBsnit \fR .sp -package require \fBfileutil::paths \fR +package require \fBconfiguration \fR .sp package require \fBpt::peg \fR .sp package require \fBpluginmgr \fR .sp -package require \fBpt::peg::import ?1\&.0\&.1?\fR +package require \fBpt::peg::import ?1?\fR .sp \fB::pt::peg::import\fR \fIobjectName\fR .sp \fBobjectName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? .sp @@ -781,22 +779,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_import_container.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_import_container.n +++ idoc/man/files/modules/pt/pt_peg_import_container.n @@ -297,22 +297,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_import_json.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_import_json.n +++ idoc/man/files/modules/pt/pt_peg_import_json.n @@ -793,22 +793,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, JSON, LL(k), PEG, TDPL, context-free languages, expression, grammar, import, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_import_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_import_peg.n +++ idoc/man/files/modules/pt/pt_peg_import_peg.n @@ -773,22 +773,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, import, matching, parser, parsing expression, parsing expression grammar, plugin, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_interp.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_interp.n +++ idoc/man/files/modules/pt/pt_peg_interp.n @@ -697,22 +697,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_introduction.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_introduction.n +++ idoc/man/files/modules/pt/pt_peg_introduction.n @@ -427,22 +427,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_language.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_language.n +++ idoc/man/files/modules/pt/pt_peg_language.n @@ -741,22 +741,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_op.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_op.n +++ idoc/man/files/modules/pt/pt_peg_op.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pt_peg_op\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "pt_peg_op" i 1\&.1\&.0 tcllib "Parser Tools" +.TH "pt_peg_op" i 1\&.0\&.1 tcllib "Parser Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME pt_peg_op \- Parser Tools PE Grammar Utility Operations .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBpt::peg::op ?1\&.1\&.0?\fR +package require \fBpt::peg::op 1\&.0\&.1\fR .sp \fB::peg::peg::op\fR \fBcalled\fR \fIcontainer\fR .sp \fB::peg::peg::op\fR \fBdechain\fR \fIcontainer\fR .sp @@ -460,22 +460,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_container.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_container.n +++ idoc/man/files/modules/pt/pt_peg_to_container.n @@ -782,22 +782,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS CONTAINER, EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_cparam.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_cparam.n +++ idoc/man/files/modules/pt/pt_peg_to_cparam.n @@ -814,22 +814,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS CPARAM, EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_json.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_json.n +++ idoc/man/files/modules/pt/pt_peg_to_json.n @@ -846,22 +846,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, JSON, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_param.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_param.n +++ idoc/man/files/modules/pt/pt_peg_to_param.n @@ -1480,22 +1480,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PARAM, PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_peg.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_peg.n +++ idoc/man/files/modules/pt/pt_peg_to_peg.n @@ -832,22 +832,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_peg_to_tclparam.n ================================================================== --- idoc/man/files/modules/pt/pt_peg_to_tclparam.n +++ idoc/man/files/modules/pt/pt_peg_to_tclparam.n @@ -786,22 +786,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TCLPARAM, TDPL, context-free languages, conversion, expression, format conversion, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, serialization, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_pegrammar.n ================================================================== --- idoc/man/files/modules/pt/pt_pegrammar.n +++ idoc/man/files/modules/pt/pt_pegrammar.n @@ -696,22 +696,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_pexpr_op.n ================================================================== --- idoc/man/files/modules/pt/pt_pexpr_op.n +++ idoc/man/files/modules/pt/pt_pexpr_op.n @@ -527,22 +527,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_pexpression.n ================================================================== --- idoc/man/files/modules/pt/pt_pexpression.n +++ idoc/man/files/modules/pt/pt_pexpression.n @@ -722,22 +722,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_pgen.n ================================================================== --- idoc/man/files/modules/pt/pt_pgen.n +++ idoc/man/files/modules/pt/pt_pgen.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pt_pgen\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "pt::pgen" n 1\&.1 tcllib "Parser Tools" +.TH "pt::pgen" n 1\&.0\&.2 tcllib "Parser Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME pt::pgen \- Parser Generator .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBpt::pgen ?1\&.1?\fR +package require \fBpt::pgen ?1\&.0\&.2?\fR .sp \fB::pt::pgen\fR \fIinputformat\fR \fItext\fR \fIresultformat\fR ?\fIoptions\&.\&.\&.\fR? .sp .BE .SH DESCRIPTION @@ -488,22 +488,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_rdengine.n ================================================================== --- idoc/man/files/modules/pt/pt_rdengine.n +++ idoc/man/files/modules/pt/pt_rdengine.n @@ -1287,22 +1287,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_tclparam_config_nx.n ================================================================== --- idoc/man/files/modules/pt/pt_tclparam_config_nx.n +++ idoc/man/files/modules/pt/pt_tclparam_config_nx.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'pt_tclparam_config_nx\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "pt::tclparam::configuration::nx" n 1\&.0\&.1 tcllib "Parser Tools" +.TH "pt::tclparam::configuration::nx" n 1\&.0\&.0 tcllib "Parser Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME pt::tclparam::configuration::nx \- Tcl/PARAM, Canned configuration, NX .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBpt::tclparam::configuration::nx ?1\&.0\&.1?\fR +package require \fBpt::tclparam::configuration::nx ?1\&.0\&.0?\fR .sp \fB::pt::tclparam::configuration::nx\fR \fBdef\fR \fIname\fR \fIpkg\fR \fIversion\fR \fIcmdprefix\fR .sp .BE .SH DESCRIPTION @@ -320,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_tclparam_config_snit.n ================================================================== --- idoc/man/files/modules/pt/pt_tclparam_config_snit.n +++ idoc/man/files/modules/pt/pt_tclparam_config_snit.n @@ -320,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_tclparam_config_tcloo.n ================================================================== --- idoc/man/files/modules/pt/pt_tclparam_config_tcloo.n +++ idoc/man/files/modules/pt/pt_tclparam_config_tcloo.n @@ -320,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_to_api.n ================================================================== --- idoc/man/files/modules/pt/pt_to_api.n +++ idoc/man/files/modules/pt/pt_to_api.n @@ -773,22 +773,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/pt/pt_util.n ================================================================== --- idoc/man/files/modules/pt/pt_util.n +++ idoc/man/files/modules/pt/pt_util.n @@ -328,22 +328,14 @@ bugs and other problems\&. Please report such in the category \fIpt\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS EBNF, LL(k), PEG, TDPL, context-free languages, expression, grammar, matching, parser, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer .SH CATEGORY Parsing and Grammars .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/rc4/rc4.n ================================================================== --- idoc/man/files/modules/rc4/rc4.n +++ idoc/man/files/modules/rc4/rc4.n @@ -370,18 +370,10 @@ bugs and other problems\&. Please report such in the category \fIrc4\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" aes(n), blowfish(n), des(n) .SH KEYWORDS arcfour, data integrity, encryption, rc4, security, stream cipher .SH CATEGORY Index: idoc/man/files/modules/rcs/rcs.n ================================================================== --- idoc/man/files/modules/rcs/rcs.n +++ idoc/man/files/modules/rcs/rcs.n @@ -535,18 +535,10 @@ bugs and other problems\&. Please report such in the category \fIrcs\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" struct, textutil .SH KEYWORDS CVS, RCS, RCS patch, SCCS, diff -n format, patching, text conversion, text differences .SH CATEGORY Index: idoc/man/files/modules/report/report.n ================================================================== --- idoc/man/files/modules/report/report.n +++ idoc/man/files/modules/report/report.n @@ -686,22 +686,14 @@ bugs and other problems\&. Please report such in the category \fIreport\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS matrix, report, table .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002-2014 Andreas Kupries .fi Index: idoc/man/files/modules/rest/rest.n ================================================================== --- idoc/man/files/modules/rest/rest.n +++ idoc/man/files/modules/rest/rest.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'rest\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "rest" n 1\&.3\&.1 tcllib "A framework for RESTful web services" +.TH "rest" n 1\&.2 tcllib "A framework for RESTful web services" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,20 +273,18 @@ .SH NAME rest \- define REST web APIs and call them inline or asychronously .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBrest ?1\&.3\&.1?\fR +package require \fBrest ?1\&.2?\fR .sp \fB::rest::simple\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .sp \fB::rest::get\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .sp \fB::rest::post\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .sp -\fB::rest::patch\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? -.sp \fB::rest::head\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .sp \fB::rest::put\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .sp \fB::rest::delete\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? @@ -324,12 +322,10 @@ .TP \fB::rest::get\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .TP \fB::rest::post\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .TP -\fB::rest::patch\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? -.TP \fB::rest::head\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .TP \fB::rest::put\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? .TP \fB::rest::delete\fR \fIurl\fR \fIquery\fR ?\fIconfig\fR? ?\fIbody\fR? @@ -795,13 +791,12 @@ package require tls http::register https 443 ::tls::socket .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -829,13 +824,5 @@ bugs and other problems\&. Please report such in the category \fIrest\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. Index: idoc/man/files/modules/ripemd/ripemd128.n ================================================================== --- idoc/man/files/modules/ripemd/ripemd128.n +++ idoc/man/files/modules/ripemd/ripemd128.n @@ -431,18 +431,10 @@ bugs and other problems\&. Please report such in the category \fIripemd\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md4, md5, ripemd160, sha1 .SH KEYWORDS RIPEMD, hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security .SH CATEGORY Index: idoc/man/files/modules/ripemd/ripemd160.n ================================================================== --- idoc/man/files/modules/ripemd/ripemd160.n +++ idoc/man/files/modules/ripemd/ripemd160.n @@ -418,18 +418,10 @@ bugs and other problems\&. Please report such in the category \fIripemd\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md4, md5, ripemd128, sha1 .SH KEYWORDS RIPEMD, hashing, md4, message-digest, rfc 1320, rfc 1321, rfc 2104, security .SH CATEGORY Index: idoc/man/files/modules/sasl/gtoken.n ================================================================== --- idoc/man/files/modules/sasl/gtoken.n +++ idoc/man/files/modules/sasl/gtoken.n @@ -285,13 +285,12 @@ the Simple Authentication and Security Layer (SASL)\&. .PP Please read the documentation for package \fBsasl\fR for details\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -321,22 +320,14 @@ bugs and other problems\&. Please report such in the category \fIsasl\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS SASL, XGoogleToken, authentication .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2006, Pat Thoyts .fi Index: idoc/man/files/modules/sasl/ntlm.n ================================================================== --- idoc/man/files/modules/sasl/ntlm.n +++ idoc/man/files/modules/sasl/ntlm.n @@ -299,22 +299,14 @@ bugs and other problems\&. Please report such in the category \fIsasl\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS NTLM, SASL, authentication .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2005-2006, Pat Thoyts .fi Index: idoc/man/files/modules/sasl/sasl.n ================================================================== --- idoc/man/files/modules/sasl/sasl.n +++ idoc/man/files/modules/sasl/sasl.n @@ -565,22 +565,14 @@ bugs and other problems\&. Please report such in the category \fIsasl\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS SASL, authentication .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2005-2006, Pat Thoyts .fi Index: idoc/man/files/modules/sasl/scram.n ================================================================== --- idoc/man/files/modules/sasl/scram.n +++ idoc/man/files/modules/sasl/scram.n @@ -299,22 +299,14 @@ bugs and other problems\&. Please report such in the category \fIsasl\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS SASL, SCRAM, authentication .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) 2013 Sergei Golovan .fi Index: idoc/man/files/modules/sha1/sha1.n ================================================================== --- idoc/man/files/modules/sha1/sha1.n +++ idoc/man/files/modules/sha1/sha1.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'sha1\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2005, Pat Thoyts '\" -.TH "sha1" n 2\&.0\&.4 tcllib "SHA-x Message-Digest Algorithm" +.TH "sha1" n 2\&.0\&.3 tcllib "SHA-x Message-Digest Algorithm" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME sha1 \- SHA1 Message-Digest Algorithm .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBsha1 ?2\&.0\&.4?\fR +package require \fBsha1 ?2\&.0\&.3?\fR .sp \fB::sha1::sha1\fR ?\fB-hex|-bin\fR? [ \fB-channel channel\fR | \fB-file filename\fR | ?\fB--\fR? \fIstring\fR ] .sp \fB::sha1::hmac\fR \fIkey\fR \fIstring\fR .sp @@ -431,18 +431,10 @@ bugs and other problems\&. Please report such in the category \fIsha1\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md4, md5, ripemd128, ripemd160 .SH KEYWORDS FIPS 180-1, hashing, message-digest, rfc 2104, security, sha1 .SH CATEGORY Index: idoc/man/files/modules/sha1/sha256.n ================================================================== --- idoc/man/files/modules/sha1/sha256.n +++ idoc/man/files/modules/sha1/sha256.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'sha256\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2008, Andreas Kupries '\" -.TH "sha256" n 1\&.0\&.4 tcllib "SHA-x Message-Digest Algorithm" +.TH "sha256" n 1\&.0\&.3 tcllib "SHA-x Message-Digest Algorithm" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME sha256 \- SHA256 Message-Digest Algorithm .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBsha256 ?1\&.0\&.4?\fR +package require \fBsha256 ?1\&.0\&.3?\fR .sp \fB::sha2::sha256\fR ?\fB-hex|-bin\fR? [ \fB-channel channel\fR | \fB-file filename\fR | ?\fB--\fR? \fIstring\fR ] .sp \fB::sha2::sha224\fR ?\fB-hex|-bin\fR? [ \fB-channel channel\fR | \fB-file filename\fR | ?\fB--\fR? \fIstring\fR ] .sp @@ -444,18 +444,10 @@ bugs and other problems\&. Please report such in the category \fIsha1\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" md4, md5, ripemd128, ripemd160, sha1 .SH KEYWORDS FIPS 180-1, hashing, message-digest, rfc 2104, security, sha256 .SH CATEGORY Index: idoc/man/files/modules/simulation/annealing.n ================================================================== --- idoc/man/files/modules/simulation/annealing.n +++ idoc/man/files/modules/simulation/annealing.n Index: idoc/man/files/modules/simulation/montecarlo.n ================================================================== --- idoc/man/files/modules/simulation/montecarlo.n +++ idoc/man/files/modules/simulation/montecarlo.n Index: idoc/man/files/modules/simulation/simulation_random.n ================================================================== --- idoc/man/files/modules/simulation/simulation_random.n +++ idoc/man/files/modules/simulation/simulation_random.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'simulation_random\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004 Arjen Markus '\" -.TH "simulation::random" n 0\&.4 tcllib "Tcl Simulation Tools" +.TH "simulation::random" n 0\&.1 tcllib "Tcl Simulation Tools" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,24 +274,20 @@ .SH NAME simulation::random \- Pseudo-random number generators .SH SYNOPSIS package require \fBTcl ?8\&.4?\fR .sp -package require \fBsimulation::random 0\&.4\fR +package require \fBsimulation::random 0\&.1\fR .sp \fB::simulation::random::prng_Bernoulli\fR \fIp\fR .sp \fB::simulation::random::prng_Discrete\fR \fIn\fR .sp \fB::simulation::random::prng_Poisson\fR \fIlambda\fR .sp \fB::simulation::random::prng_Uniform\fR \fImin\fR \fImax\fR .sp -\fB::simulation::random::prng_Triangular\fR \fImin\fR \fImax\fR -.sp -\fB::simulation::random::prng_SymmTriangular\fR \fImin\fR \fImax\fR -.sp \fB::simulation::random::prng_Exponential\fR \fImin\fR \fImean\fR .sp \fB::simulation::random::prng_Normal\fR \fImean\fR \fIstdev\fR .sp \fB::simulation::random::prng_Pareto\fR \fImin\fR \fIsteep\fR @@ -368,38 +364,10 @@ .TP \fB::simulation::random::prng_Uniform\fR \fImin\fR \fImax\fR Create a command (PRNG) that generates uniformly distributed numbers between "min" and "max"\&. .RS -.TP -float \fImin\fR -Minimum number that will be generated -.TP -float \fImax\fR -Maximum number that will be generated -.RE -.sp -.TP -\fB::simulation::random::prng_Triangular\fR \fImin\fR \fImax\fR -Create a command (PRNG) that generates triangularly distributed numbers -between "min" and "max"\&. If the argument min is lower than the argument max, then smaller -values have higher probability and vice versa\&. In the first case the probability -density function is of the form \fIf(x) = 2(1-x)\fR and the other case it is of the form \fIf(x) = 2x\fR\&. -.RS -.TP -float \fImin\fR -Minimum number that will be generated -.TP -float \fImax\fR -Maximum number that will be generated -.RE -.sp -.TP -\fB::simulation::random::prng_SymmTriangular\fR \fImin\fR \fImax\fR -Create a command (PRNG) that generates numbers distributed according to a symmetric triangle -around the mean of "min" and "max"\&. -.RS .TP float \fImin\fR Minimum number that will be generated .TP float \fImax\fR Index: idoc/man/files/modules/smtpd/smtpd.n ================================================================== --- idoc/man/files/modules/smtpd/smtpd.n +++ idoc/man/files/modules/smtpd/smtpd.n @@ -312,13 +312,12 @@ running Mail Transfer Agent on an Internet connected server, even though we are careful not to evaluate remote user input\&. There are many other well tested and security audited programs that can be used as mail servers for internet connected hosts\&. .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -482,10 +481,11 @@ callback and permits you to verify a local mailbox and accept mail for a local user address during RCPT command handling\&. To reject mail, throw an error as above\&. The error message is ignored\&. .TP \fBdeliverMIME\fR callback +] The deliverMIME callback is called once a mail message has been successfully passed to the server\&. A mime token is constructed from the sender, recipients and data and the users procedure it called with this single argument\&. When the call returns, the mime token is cleaned up so if the user wishes to preserve the data she must make a copy\&. @@ -541,22 +541,14 @@ bugs and other problems\&. Please report such in the category \fIsmtpd\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS rfc 2821, rfc 821, services, smtp, smtpd, socket, vwait .SH CATEGORY Networking .SH COPYRIGHT .nf Copyright (c) Pat Thoyts .fi Index: idoc/man/files/modules/snit/snit.n ================================================================== --- idoc/man/files/modules/snit/snit.n +++ idoc/man/files/modules/snit/snit.n @@ -2863,22 +2863,14 @@ bugs and other problems\&. Please report such in the category \fIsnit\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS BWidget, C++, Incr Tcl, Snit, adaptors, class, mega widget, object, object oriented, type, widget, widget adaptors .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2003-2009, by William H\&. Duquette .fi Index: idoc/man/files/modules/snit/snitfaq.n ================================================================== --- idoc/man/files/modules/snit/snitfaq.n +++ idoc/man/files/modules/snit/snitfaq.n @@ -3802,22 +3802,14 @@ bugs and other problems\&. Please report such in the category \fIsnit\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS BWidget, C++, Incr Tcl, adaptors, class, mega widget, object, object oriented, widget, widget adaptors .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2003-2006, by William H\&. Duquette .fi Index: idoc/man/files/modules/soundex/soundex.n ================================================================== --- idoc/man/files/modules/soundex/soundex.n +++ idoc/man/files/modules/soundex/soundex.n @@ -309,18 +309,10 @@ bugs and other problems\&. Please report such in the category \fIsoundex\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS knuth, soundex, text comparison, text likeness .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT Index: idoc/man/files/modules/stooop/stooop.n ================================================================== --- idoc/man/files/modules/stooop/stooop.n +++ idoc/man/files/modules/stooop/stooop.n @@ -470,17 +470,9 @@ bugs and other problems\&. Please report such in the category \fIstooop\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS C++, class, object, object oriented .SH CATEGORY Programming tools Index: idoc/man/files/modules/stooop/switched.n ================================================================== --- idoc/man/files/modules/stooop/switched.n +++ idoc/man/files/modules/stooop/switched.n @@ -504,16 +504,15 @@ error command) if the value is invalid\&. .sp The switched layer also keeps track of the options current values, so that a \fBset-\fBoption\fR\fR procedure is called only when the corresponding option value passed as parameter is -different from the current value (see \fB-option\fR data members +different from the current value (see data members description)\&. .TP -\fB-option\fR .sp -The \fB-option\fR data member is an options current value\&. +The data member is an options current value\&. There is one for each option listed in the options procedure\&. It is a read-only value which the switched layer checks against when an option is changed\&. It is rarely used at the layer derived from switched, except in the few cases, such as in the following example: @@ -541,14 +540,13 @@ .sp In this case, the manufacturer's name is stored at the switched layer level (this is why the set-manufacturer procedure has nothing to do) and later retrieved in the printData procedure\&. .TP -\fBcomplete\fR .sp -The \fBcomplete\fR data member (not to be confused with the -\fBcomplete\fR procedure) is a boolean\&. +The data member (not to be confused with +the \fBcomplete\fR procedure) is a boolean\&. Its initial value is \fBfalse\fR and it is set to \fBtrue\fR at the very end of the switched \fBcomplete\fR procedure\&. It becomes useful when some options should be set at construction time only and not dynamically, as the following example shows: .sp @@ -569,17 +567,9 @@ bugs and other problems\&. Please report such in the category \fIstooop\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS C++, class, object, object oriented .SH CATEGORY Programming tools Index: idoc/man/files/modules/string/token.n ================================================================== --- idoc/man/files/modules/string/token.n +++ idoc/man/files/modules/string/token.n @@ -366,17 +366,9 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS lexing, regex, string, tokenization .SH CATEGORY Text processing Index: idoc/man/files/modules/string/token_shell.n ================================================================== --- idoc/man/files/modules/string/token_shell.n +++ idoc/man/files/modules/string/token_shell.n @@ -390,17 +390,9 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS bash, lexing, parsing, shell, string, tokenization .SH CATEGORY Text processing Index: idoc/man/files/modules/stringprep/stringprep.n ================================================================== --- idoc/man/files/modules/stringprep/stringprep.n +++ idoc/man/files/modules/stringprep/stringprep.n @@ -376,22 +376,14 @@ bugs and other problems\&. Please report such in the category \fIstringprep\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" unicode(n) .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007-2009, Sergei Golovan .fi Index: idoc/man/files/modules/stringprep/stringprep_data.n ================================================================== --- idoc/man/files/modules/stringprep/stringprep_data.n +++ idoc/man/files/modules/stringprep/stringprep_data.n @@ -291,20 +291,12 @@ bugs and other problems\&. Please report such in the category \fIstringprep\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007-2009, Sergei Golovan .fi Index: idoc/man/files/modules/stringprep/unicode.n ================================================================== --- idoc/man/files/modules/stringprep/unicode.n +++ idoc/man/files/modules/stringprep/unicode.n @@ -344,22 +344,14 @@ bugs and other problems\&. Please report such in the category \fIstringprep\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" stringprep(n) .SH KEYWORDS normalization, unicode .SH COPYRIGHT .nf Copyright (c) 2007, Sergei Golovan .fi Index: idoc/man/files/modules/stringprep/unicode_data.n ================================================================== --- idoc/man/files/modules/stringprep/unicode_data.n +++ idoc/man/files/modules/stringprep/unicode_data.n @@ -291,20 +291,12 @@ bugs and other problems\&. Please report such in the category \fIstringprep\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS stringprep, unicode .SH COPYRIGHT .nf Copyright (c) 2007, Sergei Golovan .fi Index: idoc/man/files/modules/struct/disjointset.n ================================================================== --- idoc/man/files/modules/struct/disjointset.n +++ idoc/man/files/modules/struct/disjointset.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'disjointset\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "struct::disjointset" n 1\&.1 tcllib "Tcl Data Structures" +.TH "struct::disjointset" n 1\&.0 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -271,20 +271,18 @@ .. .BS .SH NAME struct::disjointset \- Disjoint set data structure .SH SYNOPSIS -package require \fBTcl 8\&.6\fR +package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::disjointset ?1\&.1?\fR +package require \fBstruct::disjointset ?1\&.0?\fR .sp \fB::struct::disjointset\fR \fIdisjointsetName\fR .sp \fIdisjointsetName\fR \fIoption\fR ?\fIarg arg \&.\&.\&.\fR? .sp -\fIdisjointsetName\fR \fBadd-element\fR \fIitem\fR -.sp \fIdisjointsetName\fR \fBadd-partition\fR \fIelements\fR .sp \fIdisjointsetName\fR \fBpartitions\fR .sp \fIdisjointsetName\fR \fBnum-partitions\fR @@ -293,14 +291,10 @@ .sp \fIdisjointsetName\fR \fBmerge\fR \fIa\fR \fIb\fR .sp \fIdisjointsetName\fR \fBfind\fR \fIe\fR .sp -\fIdisjointsetName\fR \fBexemplars\fR -.sp -\fIdisjointsetName\fR \fBfind-exemplar\fR \fIe\fR -.sp \fIdisjointsetName\fR \fBdestroy\fR .sp .BE .SH DESCRIPTION .PP @@ -372,98 +366,47 @@ The \fBoption\fR and the \fIarg\fRs determine the exact behavior of the command\&. The following commands are possible for disjointset objects: .RE .TP -\fIdisjointsetName\fR \fBadd-element\fR \fIitem\fR -Creates a new partition in the specified disjoint set, and fills it -with the single item \fIitem\fR\&. The command maintains -the integrity of the disjoint set, i\&.e\&. it verifies that none of the -\fIelements\fR are already part of the disjoint set and throws an -error otherwise\&. -.sp -The result of this method is the empty string\&. -.sp -This method runs in constant time\&. -.TP \fIdisjointsetName\fR \fBadd-partition\fR \fIelements\fR Creates a new partition in specified disjoint set, and fills it with the values found in the set of \fIelements\fR\&. The command maintains the integrity of the disjoint set, i\&.e\&. it verifies that none of the \fIelements\fR are already part of the disjoint set and throws an error otherwise\&. .sp The result of the command is the empty string\&. -.sp -This method runs in time proportional to the size of \fIelements\fR]\&. .TP \fIdisjointsetName\fR \fBpartitions\fR Returns the set of partitions the named disjoint set currently -consists of\&. The form of the result is a list of lists; the inner -lists contain the elements of the partitions\&. -.sp -This method runs in time O(N*alpha(N)), -where N is the number of elements in the disjoint set and alpha -is the inverse Ackermann function\&. +consists of\&. .TP \fIdisjointsetName\fR \fBnum-partitions\fR Returns the number of partitions the named disjoint set currently consists of\&. -.sp -This method runs in constant time\&. .TP \fIdisjointsetName\fR \fBequal\fR \fIa\fR \fIb\fR Determines if the two elements \fIa\fR and \fIb\fR of the disjoint set belong to the same partition\&. The result of the method is a boolean value, \fBTrue\fR if the two elements are contained in the same partition, and \fBFalse\fR otherwise\&. .sp An error will be thrown if either \fIa\fR or \fIb\fR are not elements of the disjoint set\&. -.sp -This method runs in amortized time O(alpha(N)), where N is the number of -elements in the larger partition and alpha is the inverse Ackermann function\&. .TP \fIdisjointsetName\fR \fBmerge\fR \fIa\fR \fIb\fR Determines the partitions the elements \fIa\fR and \fIb\fR are contained in and merges them into a single partition\&. If the two elements were already contained in the same partition nothing will change\&. .sp The result of the method is the empty string\&. -.sp -This method runs in amortized time O(alpha(N)), where N is the number of -items in the larger of the partitions being merged\&. The worst case time -is O(N)\&. .TP \fIdisjointsetName\fR \fBfind\fR \fIe\fR -Returns a list of the members of the partition of the disjoint set -which contains the element +Returns the partition of the disjoint set which contains the element \fIe\fR\&. -.sp -This method runs in O(N*alpha(N)) time, where N is the total number of -items in the disjoint set and alpha is the inverse Ackermann function, -See \fBfind-exemplar\fR for a faster method, if all that is needed -is a unique identifier for the partition, rather than an enumeration -of all its elements\&. -.TP -\fIdisjointsetName\fR \fBexemplars\fR -Returns a list containing an exemplar of each partition in the disjoint -set\&. The exemplar is a member of the partition, chosen arbitrarily\&. -.sp -This method runs in O(N*alpha(N)) time, where N is the total number of items -in the disjoint set and alpha is the inverse Ackermann function\&. -.TP -\fIdisjointsetName\fR \fBfind-exemplar\fR \fIe\fR -Returns the exemplar of the partition of the disjoint set containing -the element \fIe\fR\&. Throws an error if \fIe\fR is not found in the -disjoint set\&. The exemplar is an arbitrarily chosen member of the partition\&. -The only operation that will change the exemplar of any partition is -\fBmerge\fR\&. -.sp -This method runs in O(alpha(N)) time, where N is the number of items in -the partition containing E, and alpha is the inverse Ackermann function\&. .TP \fIdisjointsetName\fR \fBdestroy\fR Destroys the disjoint set object and all associated memory\&. .PP .SH "BUGS, IDEAS, FEEDBACK" @@ -471,17 +414,9 @@ bugs and other problems\&. Please report such in the category \fIstruct :: disjointset\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS disjoint set, equivalence class, find, merge find, partition, partitioned set, union .SH CATEGORY Data structures Index: idoc/man/files/modules/struct/graph.n ================================================================== --- idoc/man/files/modules/struct/graph.n +++ idoc/man/files/modules/struct/graph.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'graph\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2002-2009,2019 Andreas Kupries +'\" Copyright (c) 2002-2009 Andreas Kupries '\" -.TH "struct::graph" n 2\&.4\&.3 tcllib "Tcl Data Structures" +.TH "struct::graph" n 2\&.4 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME struct::graph \- Create and manipulate directed graph objects .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::graph ?2\&.4\&.3?\fR +package require \fBstruct::graph ?2\&.4?\fR .sp package require \fBstruct::list ?1\&.5?\fR .sp package require \fBstruct::set ?2\&.2\&.3?\fR .sp @@ -725,11 +725,11 @@ command can be used as well\&. The restrictions that involve connected nodes take a variable number of nodes as argument, specified after the name of the restriction itself\&. .sp The restrictions imposed by either \fB-in\fR, \fB-out\fR, -\fB-adj\fR, \fB-inner\fR, or \fB-embedding\fR are applied +\fB-adj\fR, \fB-inner\fR, or \fB-embedded\fR are applied first\&. Specifying more than one of them is illegal\&. .sp After that the restrictions set via \fB-key\fR (and \fB-value\fR) are applied\&. Specifying more than one \fB-key\fR (and \fB-value\fR) is illegal\&. Specifying \fB-value\fR alone, @@ -764,21 +764,10 @@ .TP \fB-embedding\fR Return a list of all arcs adjacent to exactly one of the nodes in the set\&. This is the set of arcs connecting the subgraph spawned by the specified nodes to the rest of the graph\&. -.RE -.IP -\fIAttention\fR: After the above options any word with a leading dash -which is not a valid option is treated as a node name instead of an -invalid option to error out on\&. This condition holds until either a -valid option terminates the list of nodes, or the end of the command -is reached, whichever comes first\&. -.sp -The remaining filter options are: -.sp -.RS .TP \fB-key\fR \fIkey\fR Limit the list of arcs that are returned to those arcs that have an associated key \fIkey\fR\&. .TP @@ -905,17 +894,13 @@ of returned nodes based on neighboring nodes, or based on the keyed values associated with the node\&. The restrictions that involve neighboring nodes have a list of nodes as argument, specified after the name of the restriction itself\&. .sp -The possible restrictions are the same as for method \fBarcs\fR\&. -Note that while the exact meanings change slightly, as they operate on -nodes instead of arcs, the general behaviour is the same, especially -when it comes to the handling of words with a leading dash in node -lists\&. -.sp -The command recognizes: +The possible restrictions are the same as for method +\fBarcs\fR\&. The exact meanings change slightly, as they operate on +nodes instead of arcs\&. The command recognizes: .RS .TP \fB-in\fR Return a list of all nodes with at least one outgoing arc ending in a node found in the specified set of nodes\&. Alternatively specified as @@ -1048,14 +1033,14 @@ # A possible serialization for the graph structure # # d -----> %2 - # / ^ \\ - # / / \\ - # / b \\ - # / / \\ + # / ^ \\\\ + # / / \\\\ + # / b \\\\ + # / / \\\\ # %1 <- a - %0 e # ^ \\\\ / # \\\\ c / # \\\\ \\\\ / # \\\\ v v @@ -1163,22 +1148,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: graph\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS adjacent, arc, cgraph, degree, edge, graph, loop, neighbour, node, serialization, subgraph, vertex .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002-2009,2019 Andreas Kupries +Copyright (c) 2002-2009 Andreas Kupries .fi Index: idoc/man/files/modules/struct/graph1.n ================================================================== --- idoc/man/files/modules/struct/graph1.n +++ idoc/man/files/modules/struct/graph1.n @@ -638,22 +638,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: graph\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS cgraph, graph .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries .fi Index: idoc/man/files/modules/struct/graphops.n ================================================================== --- idoc/man/files/modules/struct/graphops.n +++ idoc/man/files/modules/struct/graphops.n @@ -274,11 +274,11 @@ .. .BS .SH NAME struct::graph::op \- Operation for (un)directed graph objects .SH SYNOPSIS -package require \fBTcl 8\&.6\fR +package require \fBTcl 8\&.4\fR .sp package require \fBstruct::graph::op ?0\&.11\&.3?\fR .sp \fBstruct::graph::op::toAdjacencyMatrix\fR \fIg\fR .sp @@ -1493,18 +1493,10 @@ bugs and other problems\&. Please report such in the category \fIstruct :: graph\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS adjacency list, adjacency matrix, adjacent, approximation algorithm, arc, articulation point, augmenting network, augmenting path, bfs, bipartite, blocking flow, bridge, complete graph, connected component, cut edge, cut vertex, degree, degree constrained spanning tree, diameter, dijkstra, distance, eccentricity, edge, flow network, graph, heuristic, independent set, isthmus, level graph, local searching, loop, matching, max cut, maximum flow, minimal spanning tree, minimum cost flow, minimum degree spanning tree, minimum diameter spanning tree, neighbour, node, radius, residual graph, shortest path, squared graph, strongly connected component, subgraph, travelling salesman, vertex, vertex cover .SH CATEGORY Data structures .SH COPYRIGHT Index: idoc/man/files/modules/struct/matrix.n ================================================================== --- idoc/man/files/modules/struct/matrix.n +++ idoc/man/files/modules/struct/matrix.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'matrix\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2002-2013,2019 Andreas Kupries +'\" Copyright (c) 2002-2013 Andreas Kupries '\" -.TH "struct::matrix" n 2\&.0\&.4 tcllib "Tcl Data Structures" +.TH "struct::matrix" n 2\&.0\&.3 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME struct::matrix \- Create and manipulate matrix objects .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBstruct::matrix ?2\&.0\&.4?\fR +package require \fBstruct::matrix ?2\&.0\&.3?\fR .sp \fB::struct::matrix\fR ?\fImatrixName\fR? ?\fB=\fR|\fB:=\fR|\fBas\fR|\fBdeserialize\fR \fIsource\fR? .sp \fBmatrixName\fR \fIoption\fR ?\fIarg arg \&.\&.\&.\fR? .sp @@ -834,22 +834,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: matrix\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS matrix .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002-2013,2019 Andreas Kupries +Copyright (c) 2002-2013 Andreas Kupries .fi Index: idoc/man/files/modules/struct/matrix1.n ================================================================== --- idoc/man/files/modules/struct/matrix1.n +++ idoc/man/files/modules/struct/matrix1.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'matrix1\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2002,2019 Andreas Kupries +'\" Copyright (c) 2002 Andreas Kupries '\" -.TH "struct::matrix_v1" n 1\&.2\&.2 tcllib "Tcl Data Structures" +.TH "struct::matrix_v1" n 1\&.2\&.1 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME struct::matrix_v1 \- Create and manipulate matrix objects .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBstruct::matrix ?1\&.2\&.2?\fR +package require \fBstruct::matrix ?1\&.2\&.1?\fR .sp \fBmatrixName\fR \fIoption\fR ?\fIarg arg \&.\&.\&.\fR? .sp \fImatrixName\fR \fBadd column\fR ?\fIvalues\fR? .sp @@ -670,22 +670,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: matrix\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS matrix .SH CATEGORY Data structures .SH COPYRIGHT .nf -Copyright (c) 2002,2019 Andreas Kupries +Copyright (c) 2002 Andreas Kupries .fi Index: idoc/man/files/modules/struct/pool.n ================================================================== --- idoc/man/files/modules/struct/pool.n +++ idoc/man/files/modules/struct/pool.n @@ -659,22 +659,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: pool\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS discrete items, finite, pool, struct .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002, Erik Leunissen .fi Index: idoc/man/files/modules/struct/prioqueue.n ================================================================== --- idoc/man/files/modules/struct/prioqueue.n +++ idoc/man/files/modules/struct/prioqueue.n @@ -377,22 +377,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: prioqueue\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ordered list, prioqueue, priority queue .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2003 Michael Schlenker .fi Index: idoc/man/files/modules/struct/queue.n ================================================================== --- idoc/man/files/modules/struct/queue.n +++ idoc/man/files/modules/struct/queue.n @@ -354,17 +354,9 @@ bugs and other problems\&. Please report such in the category \fIstruct :: queue\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS graph, list, matrix, pool, prioqueue, record, set, skiplist, stack, tree .SH CATEGORY Data structures Index: idoc/man/files/modules/struct/record.n ================================================================== --- idoc/man/files/modules/struct/record.n +++ idoc/man/files/modules/struct/record.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'record\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2002, Brett Schwarz '\" -.TH "struct::record" n 1\&.2\&.2 tcllib "Tcl Data Structures" +.TH "struct::record" n 1\&.2\&.1 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME struct::record \- Define and create records (similar to 'C' structures) .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBstruct::record ?1\&.2\&.2?\fR +package require \fBstruct::record ?1\&.2\&.1?\fR .sp \fBrecord define\fR \fIrecordName\fR \fIrecordMembers\fR ?\fIinstanceName1 instanceName2 \&.\&.\&.\fR? .sp \fBrecord show\fR \fIrecord\fR .sp @@ -294,67 +294,50 @@ .sp \fBrecord delete\fR \fIrecord\fR \fIrecordName\fR .sp \fBrecord delete\fR \fIinstance\fR \fIinstanceName\fR .sp -\fIinstanceName\fR \fBcget\fR -\fImember\fR -.sp -\fIinstanceName\fR \fBcget\fR -\fImember1\fR -\fImember2\fR -.sp -\fIinstanceName\fR \fBcget\fR -.sp -\fIinstanceName\fR \fBconfigure\fR -.sp -\fIinstanceName\fR -.sp -\fIinstanceName\fR \fBconfigure\fR -\fImember\fR \fIvalue\fR -.sp -\fIinstanceName\fR \fBconfigure\fR -\fImember1\fR \fIvalue1\fR -\fImember2\fR \fIvalue2\fR -.sp -\fIrecordName\fR \fIinstanceName\fR|\fB#auto\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? +\fIrecordName\fR \fB\fIinstanceName|#auto\fR\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? .sp \fIinstanceName\fR \fBcget\fR ?\fI-member1 -member2 \&.\&.\&.\fR? .sp \fIinstanceName\fR \fBconfigure\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? .sp .BE .SH DESCRIPTION -The \fB::struct::record\fR package provides a mechanism to group -variables together as one data structure, similar to a \fIC\fR -structure\&. The members of a record can be variables or other -records\&. However, a record can not contain circular records, -i\&.e\&. records that contain the same record as a member\&. -.PP -This package was structured so that it is very similar to how -Tk objects work\&. Each record definition creates a record object that -encompasses that definition\&. Subsequently, that record object can -create instances of that record\&. These instances can then be -manipulated with the \fBcget\fR and \fBconfigure\fR methods\&. -.PP -The package only contains one top level command, but several -sub commands (see below)\&. It also obeys the namespace in which the -record was defined, hence the objects returned are fully qualified\&. +The \fB::struct::record\fR package provides a mechanism to group variables together +as one data structure, similar to a 'C' structure\&. The members of a +record can be variables or other records\&. However, a record can not contain circular +record, i\&.e\&. records that contain the same record as a +member\&. +.PP +This package was structured so that it is very similar to how Tk objects work\&. Each record +definition creates a record object that encompasses that definition\&. Subsequently, that +record object can create instances of that record\&. These instances can then +be manipulated with the \fBcget\fR and \fBconfigure\fR methods\&. +.PP +The package only contains one top level command, but several sub commands (see below)\&. It also obeys the namespace in which the record was define, hence the objects returned are fully qualified\&. .TP \fBrecord define\fR \fIrecordName\fR \fIrecordMembers\fR ?\fIinstanceName1 instanceName2 \&.\&.\&.\fR? -Defines a record\&. \fIrecordName\fR is the name of the record, and is -also used as an object command\&. This object command is used to create -instances of the record definition\&. The \fIrecordMembers\fR are the -members of the record that make up the record definition\&. These are -variables and other records\&. If optional \fIinstanceName\fR args are -specified, then an instance is generated after the definition is -created for each \fIinstanceName\fR\&. +Defines a record\&. \fIrecordName\fR is the name of the record, and is also +used as an object command\&. This object command is used to create instances of the +record definition\&. \fIrecordMembers\fR are the members of +the record that make up the record definition\&. These are variables +and other record\&. If optional \fIinstanceName\fR args are given, then an instance +is generated after the definition is created for each \fIinstanceName\fR\&. .TP \fBrecord show\fR \fIrecord\fR Returns a list of records that have been defined\&. .TP \fBrecord show\fR \fIinstances\fR \fIrecordName\fR Returns the instances that have been instantiated by \fIrecordName\fR\&. .TP \fBrecord show\fR \fImembers\fR \fIrecordName\fR -Returns the members that are defined for record \fIrecordName\fR\&. -It returns the same format as how the records were defined\&. +Returns the members that are defined for +record \fIrecordName\fR\&. It returns the same format as how the +records were defined\&. .TP \fBrecord show\fR \fIvalues\fR \fIinstanceName\fR Returns a list of values that are set for the instance \fIinstanceName\fR\&. The output is a list of key/value pairs\&. If there are nested records, then the values of the nested records will @@ -367,25 +350,24 @@ \fBrecord exists\fR \fIinstance\fR \fIinstanceName\fR Tests for the existence of a \fIinstance\fR with the name \fIinstanceName\fR\&. .TP \fBrecord delete\fR \fIrecord\fR \fIrecordName\fR -Deletes \fIrecordName\fR, and all instances of \fIrecordName\fR\&. -It will return an error if the record does not exist\&. +Deletes \fIrecordName\fR, and all instances of \fIrecordName\fR\&. It will return +an error if the record does not exist\&. .TP \fBrecord delete\fR \fIinstance\fR \fIinstanceName\fR -Deletes \fIinstance\fR with the name of \fIinstanceName\fR\&. It will -return an error if the instance does not exist\&. Note that this -recursively deletes any nested instances as well\&. +Deletes \fIinstance\fR with the name of \fIinstanceName\fR\&. It +will return an error if the instance does not exist\&. +.PP .PP .SH "RECORD MEMBERS" Record members can either be variables, or other records, However, the same record can not be nested witin itself (circular)\&. To define a nested record, you need to specify the \fBrecord\fR keyword, along the with name of the record, and the name of the instance of that -nested record (within the container)\&. For example, it would look like -this: +nested record\&. For example, it would look like this: .PP .CS # this is the nested record @@ -398,183 +380,168 @@ record define myrecord { mem1 mem2 {record mynestedrecord mem3} } + .CE -You can also assign default or initial values to the members of a -record, by enclosing the member entry in braces: +You can also assign default or initial values to the members of a record, +by enclosing the member entry in braces: .PP .CS + record define myrecord { mem1 {mem2 5} } -.CE -All instances created from this record definition will initially have -\fB5\fR as the value for member \fImem2\fR\&. If no default is given, -then the value will be the empty string\&. -.SS "GETTING VALUES" -To get a value of a member, there are several ways to do this\&. -.TP -\fIinstanceName\fR \fBcget\fR -\fImember\fR -In this form the built-in \fBcget\fR instance method returns the -value of the specified \fImember\fR\&. Note the leading dash\&. -.sp -To reach a nested member use \fIdot notation\fR: -.CS - - -\fIinstanceName\fR \fBcget\fR -mem3\&.nest1 - -.CE -.TP -\fIinstanceName\fR \fBcget\fR -\fImember1\fR -\fImember2\fR -In this form the built-in \fBcget\fR instance method returns a list -containing the values of both specified members, in the order of specification\&. -.TP -\fIinstanceName\fR \fBcget\fR -.TP -\fIinstanceName\fR \fBconfigure\fR -.TP -\fIinstanceName\fR -These forms are all equivalent\&. They return a dictionary of all -members and the associated values\&. -.PP -.SS "SETTING VALUES" -To set a value of a member, there are several ways to do this\&. -.TP -\fIinstanceName\fR \fBconfigure\fR -\fImember\fR \fIvalue\fR -In this form the built-in \fBconfigure\fR instance method sets the -specified \fImember\fR to the given \fIvalue\fR\&. Note the leading -dash\&. -.sp -To reach a nested member use \fIdot notation\fR: -.CS - - -\fIinstanceName\fR \fBconfigure\fR -mem3\&.nest1 value - -.CE -.TP -\fIinstanceName\fR \fBconfigure\fR -\fImember1\fR \fIvalue1\fR -\fImember2\fR \fIvalue2\fR -In this form the built-in \fBconfigure\fR instance method sets all -specified members to the associated values\&. -.PP -.SS "ALIAS ACCESS" -In the original implementation, access was done by using dot notation -similar to how \fIC\fR structures are accessed\&. However, there was a -concensus to make the interface more Tcl like, which made sense\&. -However, the original alias access still exists\&. It might prove to be -helpful to some\&. -.PP -Basically, for every member of every instance, an alias is -created\&. This alias is used to get and set values for that member\&. -An example will illustrate the point, using the above defined records: -.PP -.CS - - -% # Create an instance first -% myrecord inst1 -::inst1 - -% # To get a member of an instance, just use the alias\&. It behaves -% # like a Tcl command: -% inst1\&.mem1 - -% # To set a member via the alias, just include a value\&. And optionally -% # the equal sign - syntactic sugar\&. -% inst1\&.mem1 = 5 -5 - -% inst1\&.mem1 -5 - -% # For nested records, just continue with the dot notation\&. -% # note, no equal sign\&. -% inst1\&.mem3\&.nest1 10 -10 - -% inst1\&.mem3\&.nest1 -10 - -% # just the instance by itself gives all member/values pairs for that -% # instance -% inst1 --mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} - -% # and to get all members within the nested record -% inst1\&.mem3 --nest1 10 -nest2 {} - - -.CE -.SH "RECORD COMMAND" -The following subcommands and corresponding arguments are available to -any record command: -.TP -\fIrecordName\fR \fIinstanceName\fR|\fB#auto\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? -Using the \fIrecordName\fR object command that was created from the -record definition, instances of the record definition can be -created\&. -Once an instance is created, it inherits the members of the record -definition, very similar to how objects work\&. -During instance generation, an object command for the instance is -created as well, using \fIinstanceName\fR\&. -.sp -This object command is used to access the data members of the -instance\&. -During the instantiation, while values for that instance may be given, -when done, \fIall\fR values must be given, and be given as -key/value pairs, like for method \fBconfigure\fR\&. Nested records -have to be in list format\&. -.sp -Optionally, \fB#auto\fR can be used in place of -\fIinstanceName\fR\&. When \fB#auto\fR is used, the instance name will -be automatically generated, and of the form -\fBrecordName\fBN\fR\fR, where \fBN\fR is a unique integer (starting -at 0) that is generated\&. + +.CE +All instances created from this record definition, will initially have 5 as +the value for \fImem2\fR\&. If no default is given, then the value will be the empty string\&. +.PP +\fIGetting Values\fR +.PP +To get a value of a member, there are several ways to do this\&. +.IP [1] +To get a member value, then use the instance built-in \fBcget\fR method: +.sp +\fIinstanceName\fR \fBcget\fR -mem1 +.IP [2] +To get multiple member values, you can specify them all in one command: +.sp +\fIinstanceName\fR \fBcget\fR -mem1 -mem2 +.IP [3] +To get a list of the key/value of all of the members, there are 3 ways: +.sp +- \fIinstanceName\fR \fBcget\fR +.sp +- \fIinstanceName\fR \fBconfigure\fR +.sp +- \fIinstanceName\fR +.IP [4] +To get a value of a nested member, then use the dot notation: +.sp +\fIinstanceName\fR \fBcget\fR -mem3\&.nest1 +.PP +.PP +\fISetting Values\fR +.PP +To set a value of a member, there are several ways to do this\&. +.IP [1] +To set a member value, then use the instance built-in \fBconfigure\fR method: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem1 val1 +.IP [2] +To set multiple member values, you can specify them all in one command: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem1 va1 -mem2 val2 +.IP [3] +To set a value of a nested member, then use the dot notation: +.sp +\fIinstanceName\fR \fBconfigure\fR -mem3\&.nest1 value +.PP +.PP +\fIAlias access\fR +.PP +In the original implementation, access was done by using dot notation similar to how 'C' structures are accessed\&. However, +there was a concensus to make the interface more Tcl like, which made sense\&. However, the original alias access still +exists\&. It might prove to be helpful to some\&. +.PP +Basically, for every member of every instance, an alias is created\&. This alias is used to get and set values for that +member\&. An example will illustrate the point, using the above defined records: +.PP +.CS + + +# Create an instance first +% myrecord inst1 +::inst1 +% # To get a member of an instance, just use the +% # alias (it behaves like a Tcl command): +% inst1\&.mem1 +% +% # To set a member via the alias, just include +% # a value (optionally the equal sign - syntactic sugar) +% inst1\&.mem1 = 5 +5 +% inst1\&.mem1 +5 +% # For nested records, just continue with the +% # dot notation (note no equal sign) +% inst1\&.mem3\&.nest1 10 +10 +% inst1\&.mem3\&.nest1 +10 +% # just the instance by itself gives all +% # member/values pairs for that instance +% inst1 +-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}} +% # and to get all members within the nested record +% inst1\&.mem3 +-nest1 10 -nest2 {} +% + + +.CE +.SH "RECORD COMMAND" +The following subcommands and corresponding arguments are available to any +record command: +.TP +\fIrecordName\fR \fB\fIinstanceName|#auto\fR\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? +Using the \fIrecordName\fR object command that was created from the record definition, +instances of the record definition can be created\&. Once a instance is +created, then it inherits the members of the record definition, very +similar to how objects work\&. During instance generation, an object command for the instance +is created as well, using \fIinstanceName\fR\&. This object command is used +to access the data members of the instance\&. During the instantiation, values for +that instance can be given, \fIbut\fR all values must be given, and be given +in key/value pairs\&. Nested records, need to be in list format\&. +.sp +Optionally, \fI#auto\fR can be used in place of \fIinstanceName\fR\&. When #auto is used, +then a instance name will automatically be generated, of the form recordName, where + is a unique integer (starting at 0) that is generated\&. .PP .PP .SH "INSTANCE COMMAND" The following subcommands and corresponding arguments are available to any record instance command: .TP \fIinstanceName\fR \fBcget\fR ?\fI-member1 -member2 \&.\&.\&.\fR? -Each instance has the method \fBcget\fR\&. This is very similar to -how Tk widget's \fBcget\fR command works\&. It queries the values of -the members for that particular instance\&. If no arguments are given, -then a dictionary is returned\&. +Each instance has the sub command \fBcget\fR associated with it\&. This +is very similar to how Tk widget's cget command works\&. It queries +the values of the member for that particular instance\&. If +no arguments are given, then a key/value list is returned\&. .TP \fIinstanceName\fR \fBconfigure\fR ?\fI-member1 value1 -member2 value2 \&.\&.\&.\fR? -Each instance has the method \fBconfigure\fR\&. This is very similar -to how Tk widget's \fBconfigure\fR command works\&. It sets the -values of the particular members for that particular instance\&. If no -arguments are given, then a dictionary list is returned\&. +Each instance has the sub command \fBconfigure\fR associated with it\&. This +is very similar to how Tk widget's configure command works\&. It sets +the values of the particular member for that particular instance\&. If +no arguments are given, then a key/value list is returned\&. .PP .SH EXAMPLES -Two examples are provided to give a good illustration on how to use +Two examples are provided to give an good illustration on how to use this package\&. -.SS "EXAMPLE 1 - CONTACT INFORMATION" -Probably the most obvious example would be to hold contact -information, such as addresses, phone numbers, comments, etc\&. Since a -person can have multiple phone numbers, multiple email addresses, etc, -we will use nested records to define these\&. So, the first thing we do -is define the nested records: +.PP +\fIExample 1\fR +.PP +Probably the most obvious example would be to hold contact information, +such as addresses, phone numbers, comments, etc\&. Since a person can have +multiple phone numbers, multiple email addresses, etc, we will use nested +records to define these\&. So, the first thing we do is define the nested +records: .PP .CS ## -## This is an interactive example, to see what is returned by -## each command as well\&. +## This is an interactive example, to see what is +## returned by each command as well\&. ## % namespace import ::struct::record::* % # define a nested record\&. Notice that country has default 'USA'\&. @@ -623,64 +590,61 @@ % record show members contacts first middle last {record locations home} {record locations work} % .CE -.SS "EXAMPLE 2 - LINKED LIST" +.PP +\fIExample 1\fR +.PP This next example just illustrates a simple linked list .PP .CS + % # define a very simple record for linked list -% record define linkedlist { +% record define llist { value next } -::linkedlist -% linkedlist lstart +::llist +% llist lstart ::lstart -% lstart config -value 1 -next [linkedlist #auto] -% [lstart cget -next] config -value 2 -next [linkedlist #auto] +% lstart config -value 1 -next [llist #auto] +% [lstart cget -next] config -value 2 -next [llist #auto] % [[lstart cget -next] cget -next] config -value 3 -next "end" % set next lstart lstart % while 1 { - lappend values [$next cget -value] - set next [$next cget -next] - if {[string match "end" $next]} break +lappend values [$next cget -value] +set next [$next cget -next] +if {[string match "end" $next]} {break} } % puts "$values" 1 2 3 % # cleanup linked list -% # We could just use delete record linkedlist also -% foreach I [record show instances linkedlist] { - record delete instance $I +% # We could just use delete record llist also +% foreach I [record show instances llist] { +record delete instance $I } -% record show instances linkedlist +% record show instances llist % + .CE +.PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIstruct :: record\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS data structures, record, struct .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002, Brett Schwarz .fi Index: idoc/man/files/modules/struct/skiplist.n ================================================================== --- idoc/man/files/modules/struct/skiplist.n +++ idoc/man/files/modules/struct/skiplist.n @@ -348,22 +348,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: skiplist\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS skiplist .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2000 Keith Vetter .fi Index: idoc/man/files/modules/struct/stack.n ================================================================== --- idoc/man/files/modules/struct/stack.n +++ idoc/man/files/modules/struct/stack.n @@ -377,17 +377,9 @@ bugs and other problems\&. Please report such in the category \fIstruct :: stack\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS graph, matrix, queue, tree .SH CATEGORY Data structures Index: idoc/man/files/modules/struct/struct_list.n ================================================================== --- idoc/man/files/modules/struct/struct_list.n +++ idoc/man/files/modules/struct/struct_list.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'struct_list\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2003-2005 by Kevin B\&. Kenny\&. All rights reserved '\" Copyright (c) 2003-2012 Andreas Kupries '\" -.TH "struct::list" n 1\&.8\&.4 tcllib "Tcl Data Structures" +.TH "struct::list" n 1\&.8\&.3 tcllib "Tcl Data Structures" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -275,11 +275,11 @@ .SH NAME struct::list \- Procedures for manipulating lists .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBstruct::list ?1\&.8\&.4?\fR +package require \fBstruct::list ?1\&.8\&.3?\fR .sp \fB::struct::list\fR \fBlongestCommonSubsequence\fR \fIsequence1\fR \fIsequence2\fR ?\fImaxOccurs\fR? .sp \fB::struct::list\fR \fBlongestCommonSubsequence2\fR \fIsequence1 sequence2\fR ?\fImaxOccurs\fR? .sp @@ -990,18 +990,10 @@ bugs and other problems\&. Please report such in the category \fIstruct :: list\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Fisher-Yates, assign, common, comparison, diff, differential, equal, equality, filter, first permutation, flatten, folding, full outer join, generate permutations, inner join, join, left outer join, list, longest common subsequence, map, next permutation, outer join, permutation, reduce, repeating, repetition, reshuffle, reverse, right outer join, shuffle, subsequence, swapping .SH CATEGORY Data structures .SH COPYRIGHT DELETED idoc/man/files/modules/struct/struct_map.n Index: idoc/man/files/modules/struct/struct_map.n ================================================================== --- idoc/man/files/modules/struct/struct_map.n +++ idoc/man/files/modules/struct/struct_map.n @@ -1,349 +0,0 @@ -'\" -'\" Generated from file 'struct_map\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "struct::map" n 1 tcllib "" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -struct::map \- Manage key/value maps -.SH SYNOPSIS -package require \fBstruct::map ?1?\fR -.sp -\fB::struct::map\fR \fImapName\fR -.sp -\fBmapName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? -.sp -\fImapName\fR \fBget\fR -.sp -\fImapName\fR \fBnames\fR -.sp -\fImapName\fR \fBset\fR \fIname\fR ?\fIvalue\fR? -.sp -\fImapName\fR \fBunset\fR ?\fIpattern\fR\&.\&.\&.? -.sp -.BE -.SH DESCRIPTION -Provides a snit class whose instances manage a key/value map\&. -In other words, an object wrapper around Tcl arrays\&. -.SH API -The main command provides construction of maps: -.TP -\fB::struct::map\fR \fImapName\fR -Creates a new, empty map with an associated global Tcl command whose -name is \fImapName\fR\&. -It may be used to invoke various operations on the map\&. -It has the following general form: -.RS -.TP -\fBmapName\fR \fBmethod\fR ?\fIarg arg \&.\&.\&.\fR? -\fBmethod\fR and \fIarg\fRuments determine the exact behavior of -the command\&. -.RE -.IP -If \fImapName\fR is specified as \fB%AUTO%\fR a unique name will be -generated by the package itself\&. -The result of the command is the fully-qualified name of the instance -command\&. -.PP -.PP -The following commands are possible for map objects: -.TP -\fImapName\fR \fBget\fR -Returns the entire map as a Tcl dictionary\&. -.TP -\fImapName\fR \fBnames\fR -Returns the list of all keys known to the map, in arbitrary order\&. -.TP -\fImapName\fR \fBset\fR \fIname\fR ?\fIvalue\fR? -Sets key \fIname\fR to the specified \fIvalue\fR, if the value specified\&. -Returns the value for the key\&. -Throws an error if the key is not known\&. -.TP -\fImapName\fR \fBunset\fR ?\fIpattern\fR\&.\&.\&.? -Removes all keys matching at least one of the glob \fIpattern\fRs from -the map\&. -If no pattern is specified all keys are removed\&. -In other words, the default pattern is \fB*\fR\&. -The result of the command is the empty string\&. -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fIstruct :: list\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. Index: idoc/man/files/modules/struct/struct_set.n ================================================================== --- idoc/man/files/modules/struct/struct_set.n +++ idoc/man/files/modules/struct/struct_set.n @@ -400,22 +400,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: set\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS cardinality, difference, emptiness, exclusion, inclusion, intersection, membership, set, symmetric difference, union .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries .fi Index: idoc/man/files/modules/struct/struct_tree.n ================================================================== --- idoc/man/files/modules/struct/struct_tree.n +++ idoc/man/files/modules/struct/struct_tree.n @@ -996,22 +996,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: tree\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS breadth-first, depth-first, in-order, node, post-order, pre-order, serialization, tree .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002-2004,2012 Andreas Kupries .fi Index: idoc/man/files/modules/struct/struct_tree1.n ================================================================== --- idoc/man/files/modules/struct/struct_tree1.n +++ idoc/man/files/modules/struct/struct_tree1.n @@ -552,22 +552,14 @@ bugs and other problems\&. Please report such in the category \fIstruct :: tree\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS tree .SH CATEGORY Data structures .SH COPYRIGHT .nf Copyright (c) 2002 Andreas Kupries .fi Index: idoc/man/files/modules/tar/tar.n ================================================================== --- idoc/man/files/modules/tar/tar.n +++ idoc/man/files/modules/tar/tar.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'tar\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "tar" n 0\&.11 tcllib "Tar file handling" +.TH "tar" n 0\&.10 tcllib "Tar file handling" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME tar \- Tar file creation, extraction & manipulation .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBtar ?0\&.11?\fR +package require \fBtar ?0\&.10?\fR .sp \fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR? .sp \fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR? .sp @@ -366,11 +366,11 @@ } .CE .TP \fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR? -Returns the contents of \fIfileName\fR from the \fItarball\fR\&. +Returns the contents of \fIfileName\fR from the \fItarball\fR .sp .CS % set readme [::tar::get tarball\&.tar doc/README] { @@ -377,17 +377,13 @@ % puts $readme } .CE .sp -If the option \fB-chan\fR is present \fItarball\fR is -interpreted as an open channel\&. It is assumed that the channel was -opened for reading, and configured for binary input\&. The command will -\fInot\fR close the channel\&. -.sp -An error is thrown when \fIfileName\fR is not found in the tar -archive\&. +If the option \fB-chan\fR is present \fItarball\fR is interpreted as an open channel\&. +It is assumed that the channel was opened for reading, and configured for binary input\&. +The command will \fInot\fR close the channel\&. .TP \fB::tar::create\fR \fItarball\fR \fIfiles\fR \fIargs\fR Creates a new tar file containing the \fIfiles\fR\&. \fIfiles\fR must be specified as a single argument which is a proper list of filenames\&. .RS @@ -454,17 +450,9 @@ bugs and other problems\&. Please report such in the category \fItar\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS archive, tape archive, tar .SH CATEGORY File formats Index: idoc/man/files/modules/tepam/tepam_argument_dialogbox.n ================================================================== --- idoc/man/files/modules/tepam/tepam_argument_dialogbox.n +++ idoc/man/files/modules/tepam/tepam_argument_dialogbox.n Index: idoc/man/files/modules/tepam/tepam_doc_gen.n ================================================================== --- idoc/man/files/modules/tepam/tepam_doc_gen.n +++ idoc/man/files/modules/tepam/tepam_doc_gen.n @@ -511,11 +511,11 @@ .TP \fIName\fR Name of the argument .TP \fIIsOptional\fR -If true (=\fB1\fR) the argument is optional which should be indicated by the generated string (for example by putting the argument into brackets {[]} or into question marks '?'): +If true (=\fB1\fR) the argument is optional which should be indicated by the generated string (for example by putting the argument into brackets {} or into question marks '?'): .CS gen(TXT,ArgumentString) mtype 1 0 string -> \fI"[mtype]"\fR .CE .TP Index: idoc/man/files/modules/tepam/tepam_introduction.n ================================================================== --- idoc/man/files/modules/tepam/tepam_introduction.n +++ idoc/man/files/modules/tepam/tepam_introduction.n Index: idoc/man/files/modules/tepam/tepam_procedure.n ================================================================== --- idoc/man/files/modules/tepam/tepam_procedure.n +++ idoc/man/files/modules/tepam/tepam_procedure.n @@ -1122,11 +1122,11 @@ my_proc \fB-n1 N1 -n2 N2 "->" "<-"\fR \fI-> my_proc: Argument '->' not known\fR set U1 "->" -my_proc \fB-n1 N1 -n2 N2 $U1 U2\fR +my_proc -n1 N1 -n2 N2 $U1 U2}] my_proc: Argument '->' not known .CE The '--' flag allows separating unambiguously the unnamed arguments from the named arguments\&. All data after the '--' flag will be considered as unnamed argument: .CS Index: idoc/man/files/modules/term/ansi_cattr.n ================================================================== --- idoc/man/files/modules/term/ansi_cattr.n +++ idoc/man/files/modules/term/ansi_cattr.n @@ -483,22 +483,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ansi, attribute control, color control, control, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/ansi_cctrl.n ================================================================== --- idoc/man/files/modules/term/ansi_cctrl.n +++ idoc/man/files/modules/term/ansi_cctrl.n @@ -774,22 +774,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ansi, attribute control, color control, control, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006-2008 Andreas Kupries .fi Index: idoc/man/files/modules/term/ansi_cmacros.n ================================================================== --- idoc/man/files/modules/term/ansi_cmacros.n +++ idoc/man/files/modules/term/ansi_cmacros.n @@ -330,22 +330,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ansi, control, frame, menu, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/ansi_code.n ================================================================== --- idoc/man/files/modules/term/ansi_code.n +++ idoc/man/files/modules/term/ansi_code.n @@ -314,22 +314,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS control, declare, define, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/ansi_ctrlu.n ================================================================== --- idoc/man/files/modules/term/ansi_ctrlu.n +++ idoc/man/files/modules/term/ansi_ctrlu.n @@ -338,22 +338,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS ansi, columns, control, cooked, input mode, lines, raw, rows, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006-2011 Andreas Kupries .fi Index: idoc/man/files/modules/term/ansi_send.n ================================================================== --- idoc/man/files/modules/term/ansi_send.n +++ idoc/man/files/modules/term/ansi_send.n @@ -766,22 +766,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS character output, control, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/imenu.n ================================================================== --- idoc/man/files/modules/term/imenu.n +++ idoc/man/files/modules/term/imenu.n @@ -405,22 +405,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS control, menu, terminal, text display .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/ipager.n ================================================================== --- idoc/man/files/modules/term/ipager.n +++ idoc/man/files/modules/term/ipager.n @@ -406,22 +406,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS control, pager, terminal, text display .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/receive.n ================================================================== --- idoc/man/files/modules/term/receive.n +++ idoc/man/files/modules/term/receive.n @@ -334,22 +334,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS character input, control, get character, listener, receiver, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/term.n ================================================================== --- idoc/man/files/modules/term/term.n +++ idoc/man/files/modules/term/term.n @@ -289,22 +289,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS control, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/term_bind.n ================================================================== --- idoc/man/files/modules/term/term_bind.n +++ idoc/man/files/modules/term/term_bind.n @@ -378,22 +378,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS character input, control, dispatcher, listener, receiver, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/term/term_send.n ================================================================== --- idoc/man/files/modules/term/term_send.n +++ idoc/man/files/modules/term/term_send.n @@ -304,22 +304,14 @@ bugs and other problems\&. Please report such in the category \fIterm\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS character output, control, terminal .SH CATEGORY Terminal control .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/textutil/adjust.n ================================================================== --- idoc/man/files/modules/textutil/adjust.n +++ idoc/man/files/modules/textutil/adjust.n @@ -374,11 +374,12 @@ \fB-length\fR \fIinteger\fR Set the length of the \fIlogical\fR line in the string to \fIinteger\fR\&. \fIinteger\fR must be a positive integer value\&. Defaults to \fB72\fR\&. .TP -\fB-strictlength\fR \fIboolean\fR +\fB-strictlength\fR +\fIboolean\fR] If set to \fBfalse\fR (default), a line can exceed the specified \fB-length\fR if a single word is longer than \fB-length\fR\&. If set to \fBtrue\fR, words that are longer than \fB-length\fR are split so that no line exceeds the specified \fB-length\fR\&. .RE @@ -435,19 +436,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS TeX, adjusting, formatting, hyphenation, indenting, justification, paragraph, string, undenting .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/expander.n ================================================================== --- idoc/man/files/modules/textutil/expander.n +++ idoc/man/files/modules/textutil/expander.n @@ -743,18 +743,10 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" [uri, http://www\&.wjduquette\&.com/expand, regexp, split, string .SH KEYWORDS string, template processing, text expansion .SH CATEGORY DELETED idoc/man/files/modules/textutil/patch.n Index: idoc/man/files/modules/textutil/patch.n ================================================================== --- idoc/man/files/modules/textutil/patch.n +++ idoc/man/files/modules/textutil/patch.n @@ -1,345 +0,0 @@ -'\" -'\" Generated from file 'patch\&.man' by tcllib/doctools with format 'nroff' -'\" -.TH "textutil::patch" n 0\&.1 tcllib "Text and string utilities" -.\" The -*- nroff -*- definitions below are for supplemental macros used -.\" in Tcl/Tk manual entries. -.\" -.\" .AP type name in/out ?indent? -.\" Start paragraph describing an argument to a library procedure. -.\" type is type of argument (int, etc.), in/out is either "in", "out", -.\" or "in/out" to describe whether procedure reads or modifies arg, -.\" and indent is equivalent to second arg of .IP (shouldn't ever be -.\" needed; use .AS below instead) -.\" -.\" .AS ?type? ?name? -.\" Give maximum sizes of arguments for setting tab stops. Type and -.\" name are examples of largest possible arguments that will be passed -.\" to .AP later. If args are omitted, default tab stops are used. -.\" -.\" .BS -.\" Start box enclosure. From here until next .BE, everything will be -.\" enclosed in one large box. -.\" -.\" .BE -.\" End of box enclosure. -.\" -.\" .CS -.\" Begin code excerpt. -.\" -.\" .CE -.\" End code excerpt. -.\" -.\" .VS ?version? ?br? -.\" Begin vertical sidebar, for use in marking newly-changed parts -.\" of man pages. The first argument is ignored and used for recording -.\" the version when the .VS was added, so that the sidebars can be -.\" found and removed when they reach a certain age. If another argument -.\" is present, then a line break is forced before starting the sidebar. -.\" -.\" .VE -.\" End of vertical sidebar. -.\" -.\" .DS -.\" Begin an indented unfilled display. -.\" -.\" .DE -.\" End of indented unfilled display. -.\" -.\" .SO ?manpage? -.\" Start of list of standard options for a Tk widget. The manpage -.\" argument defines where to look up the standard options; if -.\" omitted, defaults to "options". The options follow on successive -.\" lines, in three columns separated by tabs. -.\" -.\" .SE -.\" End of list of standard options for a Tk widget. -.\" -.\" .OP cmdName dbName dbClass -.\" Start of description of a specific option. cmdName gives the -.\" option's name as specified in the class command, dbName gives -.\" the option's name in the option database, and dbClass gives -.\" the option's class in the option database. -.\" -.\" .UL arg1 arg2 -.\" Print arg1 underlined, then print arg2 normally. -.\" -.\" .QW arg1 ?arg2? -.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). -.\" -.\" .PQ arg1 ?arg2? -.\" Print an open parenthesis, arg1 in quotes, then arg2 normally -.\" (for trailing punctuation) and then a closing parenthesis. -.\" -.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. -.if t .wh -1.3i ^B -.nr ^l \n(.l -.ad b -.\" # Start an argument description -.de AP -.ie !"\\$4"" .TP \\$4 -.el \{\ -. ie !"\\$2"" .TP \\n()Cu -. el .TP 15 -.\} -.ta \\n()Au \\n()Bu -.ie !"\\$3"" \{\ -\&\\$1 \\fI\\$2\\fP (\\$3) -.\".b -.\} -.el \{\ -.br -.ie !"\\$2"" \{\ -\&\\$1 \\fI\\$2\\fP -.\} -.el \{\ -\&\\fI\\$1\\fP -.\} -.\} -.. -.\" # define tabbing values for .AP -.de AS -.nr )A 10n -.if !"\\$1"" .nr )A \\w'\\$1'u+3n -.nr )B \\n()Au+15n -.\" -.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n -.nr )C \\n()Bu+\\w'(in/out)'u+2n -.. -.AS Tcl_Interp Tcl_CreateInterp in/out -.\" # BS - start boxed text -.\" # ^y = starting y location -.\" # ^b = 1 -.de BS -.br -.mk ^y -.nr ^b 1u -.if n .nf -.if n .ti 0 -.if n \l'\\n(.lu\(ul' -.if n .fi -.. -.\" # BE - end boxed text (draw box now) -.de BE -.nf -.ti 0 -.mk ^t -.ie n \l'\\n(^lu\(ul' -.el \{\ -.\" Draw four-sided box normally, but don't draw top of -.\" box if the box started on an earlier page. -.ie !\\n(^b-1 \{\ -\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.el \}\ -\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' -.\} -.\} -.fi -.br -.nr ^b 0 -.. -.\" # VS - start vertical sidebar -.\" # ^Y = starting y location -.\" # ^v = 1 (for troff; for nroff this doesn't matter) -.de VS -.if !"\\$2"" .br -.mk ^Y -.ie n 'mc \s12\(br\s0 -.el .nr ^v 1u -.. -.\" # VE - end of vertical sidebar -.de VE -.ie n 'mc -.el \{\ -.ev 2 -.nf -.ti 0 -.mk ^t -\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' -.sp -1 -.fi -.ev -.\} -.nr ^v 0 -.. -.\" # Special macro to handle page bottom: finish off current -.\" # box/sidebar if in box/sidebar mode, then invoked standard -.\" # page bottom macro. -.de ^B -.ev 2 -'ti 0 -'nf -.mk ^t -.if \\n(^b \{\ -.\" Draw three-sided box if this is the box's first page, -.\" draw two sides but no top otherwise. -.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c -.\} -.if \\n(^v \{\ -.nr ^x \\n(^tu+1v-\\n(^Yu -\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c -.\} -.bp -'fi -.ev -.if \\n(^b \{\ -.mk ^y -.nr ^b 2 -.\} -.if \\n(^v \{\ -.mk ^Y -.\} -.. -.\" # DS - begin display -.de DS -.RS -.nf -.sp -.. -.\" # DE - end display -.de DE -.fi -.RE -.sp -.. -.\" # SO - start of list of standard options -.de SO -'ie '\\$1'' .ds So \\fBoptions\\fR -'el .ds So \\fB\\$1\\fR -.SH "STANDARD OPTIONS" -.LP -.nf -.ta 5.5c 11c -.ft B -.. -.\" # SE - end of list of standard options -.de SE -.fi -.ft R -.LP -See the \\*(So manual entry for details on the standard options. -.. -.\" # OP - start of full description for a single option -.de OP -.LP -.nf -.ta 4c -Command-Line Name: \\fB\\$1\\fR -Database Name: \\fB\\$2\\fR -Database Class: \\fB\\$3\\fR -.fi -.IP -.. -.\" # CS - begin code excerpt -.de CS -.RS -.nf -.ta .25i .5i .75i 1i -.. -.\" # CE - end code excerpt -.de CE -.fi -.RE -.. -.\" # UL - underline word -.de UL -\\$1\l'|0\(ul'\\$2 -.. -.\" # QW - apply quotation marks to word -.de QW -.ie '\\*(lq'"' ``\\$1''\\$2 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\$2 -.. -.\" # PQ - apply parens and quotation marks to word -.de PQ -.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 -.\"" fix emacs highlighting -.el (\\*(lq\\$1\\*(rq\\$2)\\$3 -.. -.\" # QR - quoted range -.de QR -.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 -.\"" fix emacs highlighting -.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 -.. -.\" # MT - "empty" string -.de MT -.QW "" -.. -.BS -.SH NAME -textutil::patch \- Application of uni-diff patches to directory trees -.SH SYNOPSIS -package require \fBTcl 8\&.2\fR -.sp -package require \fBtextutil::patch ?0\&.1?\fR -.sp -\fB::textutil::patch::apply\fR \fIbasedirectory\fR \fIstriplevel\fR \fIpatch\fR \fIreportcmd\fR -.sp -\fB{*}reportcmd\fR \fBapply\fR \fIfilename\fR -.sp -\fB{*}reportcmd\fR \fBfail\fR \fIfilename\fR \fIhunk\fR \fIexpected\fR \fIseen\fR -.sp -\fB{*}reportcmd\fR \fBfail-already\fR \fIfilename\fR \fIhunk\fR -.sp -.BE -.SH DESCRIPTION -This package provides a single command which applies a patch in -\fIunified format\fR [https://www\&.gnu\&.org/software/diffutils/manual/html_node/Detailed-Unified\&.html] -to a directory tree\&. -.TP -\fB::textutil::patch::apply\fR \fIbasedirectory\fR \fIstriplevel\fR \fIpatch\fR \fIreportcmd\fR -Applies the \fIpatch\fR (text of the path, not file) to the files in -the \fIbasedirectory\fR using the specified \fIstriplevel\fR\&. -The result of the command is the empty string\&. -.sp -The \fIstriplevel\fR argument is equivalent to option -\fB-p\fR of the \fBpatch\fR command\&. -.sp -Errors are thrown when the \fIpatch\fR does not parse, and -nothing is done to the files in \fIbasedirectory\fR\&. -.sp -All activities during the application of the patch, including -the inability to apply a hunk are reported through the command prefix -\fIreportcmd\fR instead\&. Files with problems are left unchanged\&. Note -however that this does \fInot prevent\fR changes to files with no -problems, before and after the problematic file(s)\&. -.sp -The command prefix is called in 3 possible forms: -.RS -.TP -\fB{*}reportcmd\fR \fBapply\fR \fIfilename\fR -The caller begins operation on file \fIfname\fR, applying all hunks -collected for said file\&. -.TP -\fB{*}reportcmd\fR \fBfail\fR \fIfilename\fR \fIhunk\fR \fIexpected\fR \fIseen\fR -Application of hunk number \fIhunk\fR of file \fIfilename\fR has failed\&. -The command expected to find the text \fIexpected\fR, and saw \fIseen\fR instead\&. -.TP -\fB{*}reportcmd\fR \fBfail-already\fR \fIfilename\fR \fIhunk\fR -Application of hunk number \fIhunk\fR of file \fIfilename\fR has failed\&. -The command believes that this hunk has already been applied to the file\&. -.RE -.PP -.SH "BUGS, IDEAS, FEEDBACK" -This document, and the package it describes, will undoubtedly contain -bugs and other problems\&. -Please report such in the category \fItextutil\fR of the -\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. -Please also report any ideas for enhancements you may have for either -package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. -.SH KEYWORDS -diff -ruN, diff, unified format, fossil, git, patch, unified format diff -.SH CATEGORY -Text processing Index: idoc/man/files/modules/textutil/repeat.n ================================================================== --- idoc/man/files/modules/textutil/repeat.n +++ idoc/man/files/modules/textutil/repeat.n @@ -307,19 +307,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS blanks, repetition, string .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/tabify.n ================================================================== --- idoc/man/files/modules/textutil/tabify.n +++ idoc/man/files/modules/textutil/tabify.n @@ -332,19 +332,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS formatting, string, tabstops .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/textutil.n ================================================================== --- idoc/man/files/modules/textutil/textutil.n +++ idoc/man/files/modules/textutil/textutil.n @@ -623,19 +623,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS TeX, formatting, hyphenation, indenting, paragraph, regular expression, string, trimming .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/textutil_split.n ================================================================== --- idoc/man/files/modules/textutil/textutil_split.n +++ idoc/man/files/modules/textutil/textutil_split.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'textutil_split\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "textutil::split" n 0\&.8 tcllib "Text and string utilities, macro processing" +.TH "textutil::split" n 0\&.7 tcllib "Text and string utilities, macro processing" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,11 +273,11 @@ .SH NAME textutil::split \- Procedures to split texts .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBtextutil::split ?0\&.8?\fR +package require \fBtextutil::split ?0\&.7?\fR .sp \fB::textutil::split::splitn\fR \fIstring\fR ?\fIlen\fR? .sp \fB::textutil::split::splitx\fR \fIstring\fR ?\fIregexp\fR? .sp @@ -300,34 +300,25 @@ .TP \fB::textutil::split::splitx\fR \fIstring\fR ?\fIregexp\fR? This command splits the \fIstring\fR and return a list\&. The string is split according to the regular expression \fIregexp\fR instead of a simple list of chars\&. -\fINote\fR: When parentheses are used in the \fIregexp\fR, i\&.e\&. regex -capture groups, then these groups will be added into the result list -as additional elements\&. If the \fIstring\fR is empty the result is the -empty list, like for \fBsplit\fR\&. -If \fIregexp\fR is empty the \fIstring\fR is split at every character, -like \fBsplit\fR does\&. +Note that if you parentheses are added into the \fIregexp\fR, the +parentheses part of separator will be added into the result list as +additional element\&. If the \fIstring\fR is empty the result is the +empty list, like for \fBsplit\fR\&. If \fIregexp\fR is empty the +\fIstring\fR is split at every character, like \fBsplit\fR does\&. The regular expression \fIregexp\fR defaults to "[\\\\t \\\\r\\\\n]+"\&. .PP .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS regular expression, split, string .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/textutil_string.n ================================================================== --- idoc/man/files/modules/textutil/textutil_string.n +++ idoc/man/files/modules/textutil/textutil_string.n @@ -336,19 +336,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS capitalize, chop, common prefix, formatting, prefix, string, uncapitalize .SH CATEGORY Text processing Index: idoc/man/files/modules/textutil/trim.n ================================================================== --- idoc/man/files/modules/textutil/trim.n +++ idoc/man/files/modules/textutil/trim.n @@ -337,19 +337,11 @@ bugs and other problems\&. Please report such in the category \fItextutil\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" regexp(n), split(n), string(n) .SH KEYWORDS prefix, regular expression, string, trimming .SH CATEGORY Text processing Index: idoc/man/files/modules/tie/tie.n ================================================================== --- idoc/man/files/modules/tie/tie.n +++ idoc/man/files/modules/tie/tie.n @@ -700,22 +700,14 @@ bugs and other problems\&. Please report such in the category \fItie\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS array, database, file, metakit, persistence, tie, untie .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2004-2008 Andreas Kupries .fi Index: idoc/man/files/modules/tie/tie_std.n ================================================================== --- idoc/man/files/modules/tie/tie_std.n +++ idoc/man/files/modules/tie/tie_std.n @@ -303,22 +303,14 @@ bugs and other problems\&. Please report such in the category \fItie\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS array, database, file, metakit, persistence, tie, untie .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2008-2015 Andreas Kupries .fi Index: idoc/man/files/modules/tiff/tiff.n ================================================================== --- idoc/man/files/modules/tiff/tiff.n +++ idoc/man/files/modules/tiff/tiff.n @@ -476,22 +476,14 @@ bugs and other problems\&. Please report such in the category \fItiff\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS image, tif, tiff .SH CATEGORY File formats .SH COPYRIGHT .nf Copyright (c) 2005-2006, Aaron Faupell .fi Index: idoc/man/files/modules/tool/meta.n ================================================================== --- idoc/man/files/modules/tool/meta.n +++ idoc/man/files/modules/tool/meta.n @@ -437,18 +437,10 @@ bugs and other problems\&. Please report such in the category \fIoo::util\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" snit(n) .SH KEYWORDS TclOO, callback, class methods, class variables, command prefix, currying, method reference, my method, singleton .SH CATEGORY Index: idoc/man/files/modules/tool/tool.n ================================================================== --- idoc/man/files/modules/tool/tool.n +++ idoc/man/files/modules/tool/tool.n @@ -270,11 +270,11 @@ .de MT .QW "" .. .BS .SH NAME -tool \- TclOO Library (TOOL) Framework +tool \- Dictionary Tools .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp package require \fBsha1 \fR .sp @@ -522,26 +522,18 @@ .SH AUTHORS Sean Woods .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. -Please report such in the category \fItcloo\fR of the +Please report such in the category \fItool\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS -TOOL, TclOO, framework +TOOL, TclOO .SH CATEGORY -TclOO +Utility .SH COPYRIGHT .nf Copyright (c) 2015 Sean Woods .fi Index: idoc/man/files/modules/tool/tool_dict_ensemble.n ================================================================== --- idoc/man/files/modules/tool/tool_dict_ensemble.n +++ idoc/man/files/modules/tool/tool_dict_ensemble.n @@ -299,22 +299,14 @@ bugs and other problems\&. Please report such in the category \fItool\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS TOOL, TclOO .SH CATEGORY Utility .SH COPYRIGHT .nf Copyright (c) 2015 Sean Woods .fi Index: idoc/man/files/modules/transfer/connect.n ================================================================== --- idoc/man/files/modules/transfer/connect.n +++ idoc/man/files/modules/transfer/connect.n @@ -453,13 +453,12 @@ transfer::connect C -socketcmd tls::socket \&.\&.\&. \&.\&.\&. .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -487,22 +486,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS active, channel, connection, passive, secure, ssl, tls, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/copyops.n ================================================================== --- idoc/man/files/modules/transfer/copyops.n +++ idoc/man/files/modules/transfer/copyops.n @@ -410,22 +410,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/ddest.n ================================================================== --- idoc/man/files/modules/transfer/ddest.n +++ idoc/man/files/modules/transfer/ddest.n @@ -393,22 +393,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, data destination, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/dsource.n ================================================================== --- idoc/man/files/modules/transfer/dsource.n +++ idoc/man/files/modules/transfer/dsource.n @@ -431,22 +431,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, data source, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/receiver.n ================================================================== --- idoc/man/files/modules/transfer/receiver.n +++ idoc/man/files/modules/transfer/receiver.n @@ -502,13 +502,12 @@ transfer::receiver R -socketcmd tls::socket \&.\&.\&. \&.\&.\&. .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -536,22 +535,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, data destination, receiver, secure, ssl, tls, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/tqueue.n ================================================================== --- idoc/man/files/modules/transfer/tqueue.n +++ idoc/man/files/modules/transfer/tqueue.n @@ -416,22 +416,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, queue, transfer .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006 Andreas Kupries .fi Index: idoc/man/files/modules/transfer/transmitter.n ================================================================== --- idoc/man/files/modules/transfer/transmitter.n +++ idoc/man/files/modules/transfer/transmitter.n @@ -512,13 +512,12 @@ transfer::transmitter T -socketcmd tls::socket \&.\&.\&. \&.\&.\&. .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -546,22 +545,14 @@ bugs and other problems\&. Please report such in the category \fItransfer\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel, copy, data source, secure, ssl, tls, transfer, transmitter .SH CATEGORY Transfer module .SH COPYRIGHT .nf Copyright (c) 2006-2009 Andreas Kupries .fi Index: idoc/man/files/modules/treeql/treeql.n ================================================================== --- idoc/man/files/modules/treeql/treeql.n +++ idoc/man/files/modules/treeql/treeql.n @@ -406,13 +406,13 @@ # Below we can see the same query, but rewritten # to show the structure as it is seen by the query # interpreter\&. - q query \\ - root \\ - children \\ + q query \\\\ + root \\\\ + children \\\\ get data .CE .sp The operators of the TreeQL language available for this are explained @@ -868,18 +868,10 @@ bugs and other problems\&. Please report such in the category \fItreeql\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Cost, DOM, TreeQL, XPath, XSLT, structured queries, tree, tree query language .SH CATEGORY Data structures .SH COPYRIGHT Index: idoc/man/files/modules/try/tcllib_throw.n ================================================================== --- idoc/man/files/modules/try/tcllib_throw.n +++ idoc/man/files/modules/try/tcllib_throw.n @@ -305,18 +305,10 @@ bugs and other problems\&. Please report such in the category \fItry\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" error(n) .SH KEYWORDS error, return, throw .SH CATEGORY Index: idoc/man/files/modules/try/tcllib_try.n ================================================================== --- idoc/man/files/modules/try/tcllib_try.n +++ idoc/man/files/modules/try/tcllib_try.n @@ -382,18 +382,10 @@ bugs and other problems\&. Please report such in the category \fItry\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" catch(n), error(n), return(n), throw(n) .SH KEYWORDS cleanup, error, exception, final, resource management .SH CATEGORY Index: idoc/man/files/modules/udpcluster/udpcluster.n ================================================================== --- idoc/man/files/modules/udpcluster/udpcluster.n +++ idoc/man/files/modules/udpcluster/udpcluster.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'udpcluster\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2016-2018 Sean Woods +'\" Copyright (c) 2016 Sean Woods '\" -.TH "udpcluster" n 0\&.3\&.3 tcllib "Lightweight UDP based tool for cluster node discovery" +.TH "udpcluster" n 0\&.3 tcllib "Lightweight UDP based tool for cluster node discovery" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,12 +274,10 @@ .SH NAME udpcluster \- UDP Peer-to-Peer cluster .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBudpcluster ?0\&.3\&.3?\fR -.sp package require \fBip \fR .sp package require \fBnettool \fR .sp package require \fBcomm \fR @@ -340,22 +338,14 @@ bugs and other problems\&. Please report such in the category \fInameserv\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS name service, server .SH CATEGORY Networking .SH COPYRIGHT .nf -Copyright (c) 2016-2018 Sean Woods +Copyright (c) 2016 Sean Woods .fi Index: idoc/man/files/modules/uev/uevent.n ================================================================== --- idoc/man/files/modules/uev/uevent.n +++ idoc/man/files/modules/uev/uevent.n @@ -452,18 +452,10 @@ bugs and other problems\&. Please report such in the category \fIuevent\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" hook(n) .SH KEYWORDS bind, event, generate event, hook, unbind .SH CATEGORY Index: idoc/man/files/modules/uev/uevent_onidle.n ================================================================== --- idoc/man/files/modules/uev/uevent_onidle.n +++ idoc/man/files/modules/uev/uevent_onidle.n @@ -321,20 +321,12 @@ bugs and other problems\&. Please report such in the category \fIuevent\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS callback, deferal, event, idle, merge, on-idle .SH COPYRIGHT .nf Copyright (c) 2008 Andreas Kupries .fi Index: idoc/man/files/modules/units/units.n ================================================================== --- idoc/man/files/modules/units/units.n +++ idoc/man/files/modules/units/units.n @@ -628,20 +628,12 @@ bugs and other problems\&. Please report such in the category \fIunits\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS angle, constants, conversion, distance, radians, unit .SH COPYRIGHT .nf Copyright (c) 2000-2005 Mayo Foundation .fi Index: idoc/man/files/modules/uri/uri.n ================================================================== --- idoc/man/files/modules/uri/uri.n +++ idoc/man/files/modules/uri/uri.n @@ -1,9 +1,9 @@ '\" '\" Generated from file 'uri\&.man' by tcllib/doctools with format 'nroff' '\" -.TH "uri" n 1\&.2\&.7 tcllib "Tcl Uniform Resource Identifier Management" +.TH "uri" n 1\&.2\&.6 tcllib "Tcl Uniform Resource Identifier Management" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -273,13 +273,11 @@ .SH NAME uri \- URI utilities .SH SYNOPSIS package require \fBTcl 8\&.2\fR .sp -package require \fBuri ?1\&.2\&.7?\fR -.sp -\fBuri::setQuirkOption\fR \fIoption\fR ?\fIvalue\fR? +package require \fBuri ?1\&.2\&.6?\fR .sp \fBuri::split\fR \fIurl\fR ?\fIdefaultscheme\fR? .sp \fBuri::join\fR ?\fIkey\fR \fIvalue\fR?\&.\&.\&. .sp @@ -293,294 +291,145 @@ .sp \fBuri::register\fR \fIschemeList\fR \fIscript\fR .sp .BE .SH DESCRIPTION -This package does two things\&. -.PP -First, it provides a number of -commands for manipulating URLs/URIs and fetching data specified by -them\&. For fetching data this package analyses the requested URL/URI and -then dispatches it to the appropriate package (\fBhttp\fR, \fBftp\fR, \&.\&.\&.) for -actual retrieval\&. Currently these commands are defined for the schemes -\fIhttp\fR, \fIhttps\fR, \fIftp\fR, \fImailto\fR, \fInews\fR, -\fIldap\fR, \fIldaps\fR and \fIfile\fR\&. The package \fBuri::urn\fR adds scheme \fIurn\fR\&. -.PP -Second, it provides regular expressions -for a number of \fBregistered\fR URL/URI schemes\&. Registered -schemes are currently \fIftp\fR, \fIldap\fR, \fIldaps\fR, \fIfile\fR, -\fIhttp\fR, \fIhttps\fR, \fIgopher\fR, \fImailto\fR, \fInews\fR, -\fIwais\fR and \fIprospero\fR\&. The package \fBuri::urn\fR adds scheme -\fIurn\fR\&. -.PP -The commands of the package conform to -RFC 3986 (\fIhttps://www\&.rfc-editor\&.org/rfc/rfc3986\&.txt\fR), -with the exception of a loophole arising from RFC 1630 and described -in RFC 3986 Sections 5\&.2\&.2 and 5\&.4\&.2\&. The loophole allows a relative -URI to include a scheme if it is the same as the scheme of the base -URI against which it is resolved\&. RFC 3986 recommends avoiding this usage\&. +This package contains two parts\&. First it provides regular expressions +for a number of url/uri schemes\&. Second it provides a number of +commands for manipulating urls/uris and fetching data specified by +them\&. For the latter this package analyses the requested url/uri and +then dispatches it to the appropriate package (http, ftp, \&.\&.\&.) for +actual fetching\&. +.PP +The package currently does not conform to +RFC 2396 (\fIhttp://www\&.rfc-editor\&.org/rfc/rfc2396\&.txt\fR), +but quite likely should be\&. Patches and other help are welcome\&. .SH COMMANDS .TP -\fBuri::setQuirkOption\fR \fIoption\fR ?\fIvalue\fR? -\fBuri::setQuirkOption\fR is an accessor command for a number of "quirk options"\&. -The command has the same semantics as the command \fBset\fR: when called with one argument it reads an existing value; with two arguments it writes a new value\&. The value of a "quirk option" is boolean: the value \fBfalse\fR requests conformance with RFC 3986, while \fBtrue\fR requests use of the quirk\&. See section \fBQUIRK OPTIONS\fR for discussion of the different options and their purpose\&. -.TP \fBuri::split\fR \fIurl\fR ?\fIdefaultscheme\fR? -\fBuri::split\fR takes a \fIurl\fR, decodes it and then returns a +\fBuri::split\fR takes an \fIurl\fR, decodes it and then returns a list of key/value pairs suitable for \fBarray set\fR containing the -constituents of the \fIurl\fR\&. If the scheme is missing from the \fIurl\fR +constituents of the \fIurl\fR\&. If the scheme is missing from the url it defaults to the value of \fIdefaultscheme\fR if it was specified, -or \fIhttp\fR else\&. Currently the schemes \fIhttp\fR, -\fIhttps\fR, \fIftp\fR, \fImailto\fR, \fInews\fR, \fIldap\fR, \fIldaps\fR and +or \fIhttp\fR else\&. Currently only the schemes \fIhttp\fR, +\fIftp\fR, \fImailto\fR, \fIurn\fR, \fInews\fR, \fIldap\fR and \fIfile\fR are supported by the package itself\&. See section \fBEXTENDING\fR on how to expand that range\&. .sp -The set of constituents of a URL (= the set of keys in the returned -dictionary) is dependent on the scheme of the URL\&. The only key which +The set of constituents of an url (= the set of keys in the returned +dictionary) is dependent on the scheme of the url\&. The only key which is therefore always present is \fBscheme\fR\&. For the following schemes the constituents and their keys are known: .RS .TP ftp \fBuser\fR, \fBpwd\fR, \fBhost\fR, \fBport\fR, -\fBpath\fR, \fBtype\fR, \fBpbare\fR\&. The pbare is optional\&. +\fBpath\fR, \fBtype\fR .TP http(s) \fBuser\fR, \fBpwd\fR, \fBhost\fR, \fBport\fR, -\fBpath\fR, \fBquery\fR, \fBfragment\fR, \fBpbare\fR\&. The pbare is optional\&. +\fBpath\fR, \fBquery\fR, \fBfragment\fR\&. The fragment +is optional\&. .TP file \fBpath\fR, \fBhost\fR\&. The host is optional\&. .TP mailto \fBuser\fR, \fBhost\fR\&. The host is optional\&. .TP -ldap(s) -\fBhost\fR, \fBport\fR, \fBdn\fR, \fBattrs\fR, \fBscope\fR, \fBfilter\fR, \fBextensions\fR -.TP news Either \fBmessage-id\fR or \fBnewsgroup-name\fR\&. .RE -.IP -For discussion of the boolean \fBpbare\fR see options \fINoInitialSlash\fR and \fINoExtraKeys\fR in \fBQUIRK OPTIONS\fR\&. -.sp -The constituents are returned as slices of the argument \fIurl\fR, without removal of percent-encoding ("url-encoding") or other adaptations\&. Notably, on Windows® the \fBpath\fR in scheme \fIfile\fR is not a valid local filename\&. See \fBEXAMPLES\fR for more information\&. .sp .TP \fBuri::join\fR ?\fIkey\fR \fIvalue\fR?\&.\&.\&. \fBuri::join\fR takes a list of key/value pairs (generated by -\fBuri::split\fR, for example) and returns the canonical URL they -represent\&. Currently the schemes \fIhttp\fR, \fIhttps\fR, -\fIftp\fR, \fImailto\fR, \fInews\fR, \fIldap\fR, \fIldaps\fR and \fIfile\fR -are supported by the package itself\&. See section \fBEXTENDING\fR on how to expand that range\&. -.sp -The arguments are expected to be slices of a valid URL, with percent-encoding ("url-encoding") and any other necessary adaptations\&. Notably, on Windows the \fBpath\fR in scheme \fIfile\fR is not a valid local filename\&. See \fBEXAMPLES\fR for more information\&. +\fBuri::split\fR, for example) and returns the canonical url they +represent\&. Currently only the schemes \fIhttp\fR, \fIftp\fR, +\fImailto\fR, \fIurn\fR, \fInews\fR, \fIldap\fR and \fIfile\fR +are supported\&. See section \fBEXTENDING\fR on how to expand that +range\&. .TP \fBuri::resolve\fR \fIbase\fR \fIurl\fR \fBuri::resolve\fR resolves the specified \fIurl\fR relative to -\fIbase\fR, in conformance with RFC 3986\&. In other words: a -non-relative \fIurl\fR is returned +\fIbase\fR\&. In other words: A non-relative \fIurl\fR is returned unchanged, whereas for a relative \fIurl\fR the missing parts are taken from \fIbase\fR and prepended to it\&. The result of this operation is returned\&. For an empty \fIurl\fR the result is -\fIbase\fR, without its URI fragment (if any)\&. The command is available for schemes \fIhttp\fR, \fIhttps\fR, \fIftp\fR, and \fIfile\fR\&. +\fIbase\fR\&. .TP \fBuri::isrelative\fR \fIurl\fR \fBuri::isrelative\fR determines whether the specified \fIurl\fR is -absolute or relative\&. The command is available for a \fIurl\fR of any scheme\&. +absolute or relative\&. .TP \fBuri::geturl\fR \fIurl\fR ?\fIoptions\fR\&.\&.\&.? \fBuri::geturl\fR decodes the specified \fIurl\fR and then dispatches the request to the package appropriate for the scheme found in the -URL\&. The command assumes that the package to handle the given scheme +url\&. The command assumes that the package to handle the given scheme either has the same name as the scheme itself (including possible capitalization) followed by \fB::geturl\fR, or, in case of this failing, has the same name as the scheme itself (including possible capitalization)\&. It further assumes that whatever package was loaded provides a \fBgeturl\fR-command in the namespace of the same name as the package itself\&. This command is called with the given \fIurl\fR and all given \fIoptions\fR\&. Currently \fBgeturl\fR does not handle any options itself\&. .sp -\fINote:\fR \fIfile\fR-URLs are an exception to the rule +\fINote:\fR \fIfile\fR-urls are an exception to the rule described above\&. They are handled internally\&. .sp It is not possible to specify results of the command\&. They depend on the \fBgeturl\fR-command for the scheme the request was dispatched to\&. .TP \fBuri::canonicalize\fR \fIuri\fR \fBuri::canonicalize\fR returns the canonical form of a URI\&. The canonical form of a URI is one where relative path specifications, -i\&.e\&. "\&." and "\&.\&.", have been resolved\&. The command is available for all -URI schemes that have \fBuri::split\fR and \fBuri::join\fR commands\&. The command -returns a canonicalized URI if the URI scheme has a \fBpath\fR component (i\&.e\&. \fIhttp\fR, \fIhttps\fR, \fIftp\fR, and \fIfile\fR)\&. For schemes that have \fBuri::split\fR and \fBuri::join\fR commands but no \fBpath\fR component (i\&.e\&. \fImailto\fR, \fInews\fR, \fIldap\fR, and \fIldaps\fR), the command returns the \fIuri\fR unchanged\&. +ie\&. \&. and \&.\&., have been resolved\&. .TP \fBuri::register\fR \fIschemeList\fR \fIscript\fR \fBuri::register\fR registers the first element of \fIschemeList\fR as a new scheme and the remaining elements as aliases for this scheme\&. It creates the namespace for the scheme and executes the \fIscript\fR in -the new namespace\&. The script has to declare variables containing +the new namespace\&. The script has to declare variables containing the regular expressions relevant to the scheme\&. At least the variable \fBschemepart\fR has to be declared as that one is used to extend the variables keeping track of the registered schemes\&. .PP .SH SCHEMES In addition to the commands mentioned above this package provides -regular expression to recognize URLs for a number of URL schemes\&. +regular expression to recognize urls for a number of url schemes\&. .PP For each supported scheme a namespace of the same name as the scheme itself is provided inside of the namespace \fIuri\fR containing the variable \fBurl\fR whose contents are a regular expression to -recognize URLs of that scheme\&. Additional variables may contain -regular expressions for parts of URLs for that scheme\&. +recognize urls of that scheme\&. Additional variables may contain +regular expressions for parts of urls for that scheme\&. .PP -The variable \fBuri::schemes\fR contains a list of all registered -schemes\&. Currently these are \fIftp\fR, \fIldap\fR, \fIldaps\fR, \fIfile\fR, -\fIhttp\fR, \fIhttps\fR, \fIgopher\fR, \fImailto\fR, \fInews\fR, +The variable \fBuri::schemes\fR contains a list of all supported +schemes\&. Currently these are \fIftp\fR, \fIldap\fR, \fIfile\fR, +\fIhttp\fR, \fIgopher\fR, \fImailto\fR, \fInews\fR, \fIwais\fR and \fIprospero\fR\&. .SH EXTENDING Extending the range of schemes supported by \fBuri::split\fR and \fBuri::join\fR is easy because both commands do not handle the request by themselves but dispatch it to another command in the -\fIuri\fR namespace using the scheme of the URL as criterion\&. +\fIuri\fR namespace using the scheme of the url as criterion\&. .PP \fBuri::split\fR and \fBuri::join\fR call \fBSplit[string totitle ]\fR and \fBJoin[string totitle ]\fR respectively\&. -.PP -The provision of split and join commands is sufficient to extend the commands \fBuri::canonicalize\fR and \fBuri::geturl\fR -(the latter subject to the availability of a suitable package with a \fBgeturl\fR command)\&. In contrast, to extend the command \fBuri::resolve\fR to a new scheme, the command itself must be modified\&. -.PP -To extend the range of schemes for which pattern information is -available, use the command \fBuri::register\fR\&. -.PP -An example of a package that provides both commands and pattern information for a new scheme is \fBuri::urn\fR, which adds scheme \fIurn\fR\&. -.SH "QUIRK OPTIONS" -The value of a "quirk option" is boolean: the value \fBfalse\fR requests conformance with RFC 3986, while \fBtrue\fR requests use of the quirk\&. Use command \fBuri::setQuirkOption\fR to access the values of quirk options\&. -.PP -Quirk options are useful both for allowing backwards compatibility when a command -specification changes, and for adding useful features that are not included -in RFC specifications\&. The following quirk options are currently defined: -.TP -\fINoInitialSlash\fR -This quirk option concerns the leading character of \fBpath\fR (if non-empty) in the schemes \fIhttp\fR, \fIhttps\fR, and \fIftp\fR\&. -.sp -RFC 3986 defines \fBpath\fR in an absolute URI to have an initial "/", unless the value of \fBpath\fR is the empty string\&. For the scheme \fIfile\fR, all versions of package \fBuri\fR follow this rule\&. The quirk option \fINoInitialSlash\fR does not apply to scheme \fIfile\fR\&. -.sp -For the schemes \fIhttp\fR, \fIhttps\fR, and \fIftp\fR, versions of \fBuri\fR before 1\&.2\&.7 define the \fBpath\fR \fINOT\fR to include an initial "/"\&. When the quirk option \fINoInitialSlash\fR is \fBtrue\fR (the default), this behavior is also used in version 1\&.2\&.7\&. To use instead values of \fBpath\fR as defined by RFC 3986, set this quirk option to \fBfalse\fR\&. -.sp -This setting does not affect RFC 3986 conformance\&. If \fINoInitialSlash\fR is \fBtrue\fR, then the value of \fBpath\fR in the schemes \fIhttp\fR, \fIhttps\fR, or \fIftp\fR, cannot distinguish between URIs in which the full "RFC 3986 path" is the empty string "" or a single slash "/" respectively\&. The missing information is recorded in an additional \fBuri::split\fR key \fBpbare\fR\&. -.sp -The boolean \fBpbare\fR is defined when quirk options \fINoInitialSlash\fR and \fINoExtraKeys\fR have values \fBtrue\fR and \fBfalse\fR respectively\&. In this case, if the value of \fBpath\fR is the empty string "", \fBpbare\fR is \fBtrue\fR if the full "RFC 3986 path" is "", and \fBpbare\fR is \fBfalse\fR if the full "RFC 3986 path" is "/"\&. -.sp -Using this quirk option \fINoInitialSlash\fR is a matter of preference\&. -.TP -\fINoExtraKeys\fR -This quirk option permits full backward compatibility with versions of \fBuri\fR before 1\&.2\&.7, by omitting the \fBuri::split\fR key \fBpbare\fR described above (see quirk option \fINoInitialSlash\fR)\&. The outcome is greater backward compatibility of the \fBuri::split\fR command, but an inability to distinguish between URIs in which the full "RFC 3986 path" is the empty string "" or a single slash "/" respectively - i\&.e\&. a minor non-conformance with RFC 3986\&. -.sp -If the quirk option \fINoExtraKeys\fR is \fBfalse\fR (the default), command \fBuri::split\fR returns an additional key \fBpbare\fR, and the commands comply with RFC 3986\&. If the quirk option \fINoExtraKeys\fR is \fBtrue\fR, the key \fBpbare\fR is not defined and there is not full conformance with RFC 3986\&. -.sp -Using the quirk option \fINoExtraKeys\fR is \fINOT\fR recommended, because if set to \fBtrue\fR it will reduce conformance with RFC 3986\&. The option is included only for compatibility with code, written for earlier versions of \fBuri\fR, that needs values of \fBpath\fR without a leading "/", \fIAND ALSO\fR cannot tolerate unexpected keys in the results of \fBuri::split\fR\&. -.TP -\fIHostAsDriveLetter\fR -When handling the scheme \fIfile\fR on the -Windows platform, versions of \fBuri\fR before 1\&.2\&.7 -use the \fBhost\fR field to represent a Windows drive letter and the colon that follows it, and the \fBpath\fR field to represent the filename path after the colon\&. Such URIs are invalid, and are not recognized by any RFC\&. When the quirk option \fIHostAsDriveLetter\fR is \fBtrue\fR, this behavior is also used in version 1\&.2\&.7\&. To use \fIfile\fR URIs on Windows that conform to RFC 3986, set this quirk option to \fBfalse\fR (the default)\&. -.sp -Using this quirk is \fINOT\fR recommended, because if set to \fBtrue\fR it will cause the \fBuri\fR commands to expect and produce invalid URIs\&. The option is included only for compatibility with legacy code\&. -.TP -\fIRemoveDoubleSlashes\fR -When a URI is canonicalized by \fBuri::canonicalize\fR, its \fBpath\fR is normalized by removal of segments "\&." and "\&.\&."\&. RFC 3986 does not mandate -the removal of empty segments "" (i\&.e\&. the merger of double slashes, which is a feature of filename normalization but not of URI \fBpath\fR normalization): it treats URIs with excess slashes as referring to different resources\&. When the quirk option \fIRemoveDoubleSlashes\fR is \fBtrue\fR (the default), empty segments will be removed from \fBpath\fR\&. To prevent removal, and thereby conform to RFC 3986, set this quirk option to \fBfalse\fR\&. -.sp -Using this quirk is a matter of preference\&. A URI with double slashes in its path was most likely generated by error, certainly so if it has a straightforward mapping to a file on a server\&. In some cases it may be better to sanitize the URI; in others, to keep the URI and let the server handle the possible error\&. -.PP -.PP -.SS "BACKWARD COMPATIBILITY" -To behave as similarly as possible to versions of \fBuri\fR earlier than 1\&.2\&.7, set the following quirk options: -.IP \(bu -\fBuri::setQuirkOption\fR \fINoInitialSlash\fR 1 -.IP \(bu -\fBuri::setQuirkOption\fR \fINoExtraKeys\fR 1 -.IP \(bu -\fBuri::setQuirkOption\fR \fIHostAsDriveLetter\fR 1 -.IP \(bu -\fBuri::setQuirkOption\fR \fIRemoveDoubleSlashes\fR 0 -.PP -In code that can tolerate the return by \fBuri::split\fR of an additional key \fBpbare\fR, set -.IP \(bu -\fBuri::setQuirkOption\fR \fINoExtraKeys\fR 0 -.PP -in order to achieve greater compliance with RFC 3986\&. -.SS "NEW DESIGNS" -For new projects, the following settings are recommended: -.IP \(bu -\fBuri::setQuirkOption\fR \fINoInitialSlash\fR 0 -.IP \(bu -\fBuri::setQuirkOption\fR \fINoExtraKeys\fR 0 -.IP \(bu -\fBuri::setQuirkOption\fR \fIHostAsDriveLetter\fR 0 -.IP \(bu -\fBuri::setQuirkOption\fR \fIRemoveDoubleSlashes\fR 0|1 -.PP -.SS "DEFAULT VALUES" -The default values for package \fBuri\fR version 1\&.2\&.7 are intended to be a compromise between backwards compatibility and improved features\&. Different default values may be chosen in future versions of package \fBuri\fR\&. -.IP \(bu -\fBuri::setQuirkOption\fR \fINoInitialSlash\fR 1 -.IP \(bu -\fBuri::setQuirkOption\fR \fINoExtraKeys\fR 0 -.IP \(bu -\fBuri::setQuirkOption\fR \fIHostAsDriveLetter\fR 0 -.IP \(bu -\fBuri::setQuirkOption\fR \fIRemoveDoubleSlashes\fR 1 -.PP -.SH EXAMPLES -A Windows® local filename such as "\fBC:\\Other Files\\startup\&.txt\fR" is not suitable for use as the \fBpath\fR element of a URI in the scheme \fIfile\fR\&. -.PP -The Tcl command \fBfile normalize\fR will convert the backslashes to forward slashes\&. To generate a valid \fBpath\fR for the scheme \fIfile\fR, the normalized filename must be prepended with "\fB/\fR", and then any characters that do not match the \fBregexp\fR bracket expression -.CS - - - [a-zA-Z0-9$_\&.+!*'(,)?:@&=-] - -.CE -must be percent-encoded\&. -.PP -The result in this example is "\fB/C:/Other%20Files/startup\&.txt\fR" which is a valid value for \fBpath\fR\&. -.CS - - -% uri::join path /C:/Other%20Files/startup\&.txt scheme file - -file:///C:/Other%20Files/startup\&.txt - -% uri::split file:///C:/Other%20Files/startup\&.txt - -path /C:/Other%20Files/startup\&.txt scheme file - - -.CE -On UNIX® systems filenames begin with "\fB/\fR" which is also used as the directory separator\&. The only action needed to convert a filename to a valid \fBpath\fR is percent-encoding\&. .SH CREDITS .PP Original code (regular expressions) by Andreas Kupries\&. Modularisation by Steve Ball, also the split/join/resolve -functionality\&. RFC 3986 conformance by Keith Nash\&. +functionality\&. .SH "BUGS, IDEAS, FEEDBACK" This document, and the package it describes, will undoubtedly contain bugs and other problems\&. Please report such in the category \fIuri\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS -fetching information, file, ftp, gopher, http, https, ldap, mailto, news, prospero, rfc 1630, rfc 2255, rfc 2396, rfc 3986, uri, url, wais, www +fetching information, file, ftp, gopher, http, ldap, mailto, news, prospero, rfc 2255, rfc 2396, uri, url, wais, www .SH CATEGORY Networking Index: idoc/man/files/modules/uri/urn-scheme.n ================================================================== --- idoc/man/files/modules/uri/urn-scheme.n +++ idoc/man/files/modules/uri/urn-scheme.n @@ -306,17 +306,9 @@ bugs and other problems\&. Please report such in the category \fIuri\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS rfc 2141, uri, url, urn .SH CATEGORY Networking Index: idoc/man/files/modules/uuid/uuid.n ================================================================== --- idoc/man/files/modules/uuid/uuid.n +++ idoc/man/files/modules/uuid/uuid.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'uuid\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2004, Pat Thoyts '\" -.TH "uuid" n 1\&.0\&.6 tcllib "uuid" +.TH "uuid" n 1\&.0\&.4 tcllib "uuid" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME uuid \- UUID generation and comparison .SH SYNOPSIS package require \fBTcl 8\&.5\fR .sp -package require \fBuuid ?1\&.0\&.6?\fR +package require \fBuuid ?1\&.0\&.4?\fR .sp \fB::uuid::uuid generate\fR .sp \fB::uuid::uuid equal\fR \fIid1\fR \fIid2\fR .sp @@ -317,22 +317,14 @@ bugs and other problems\&. Please report such in the category \fIuuid\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS GUID, UUID .SH CATEGORY Hashes, checksums, and encryption .SH COPYRIGHT .nf Copyright (c) 2004, Pat Thoyts .fi Index: idoc/man/files/modules/valtype/cc_amex.n ================================================================== --- idoc/man/files/modules/valtype/cc_amex.n +++ idoc/man/files/modules/valtype/cc_amex.n @@ -362,22 +362,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS AMEX, American Express, Checking, Testing, Type checking, Validation, Value checking, bank, card for credit, credit card, finance, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/cc_discover.n ================================================================== --- idoc/man/files/modules/valtype/cc_discover.n +++ idoc/man/files/modules/valtype/cc_discover.n @@ -362,22 +362,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Discover, Testing, Type checking, Validation, Value checking, bank, card for credit, credit card, finance, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/cc_mastercard.n ================================================================== --- idoc/man/files/modules/valtype/cc_mastercard.n +++ idoc/man/files/modules/valtype/cc_mastercard.n @@ -362,22 +362,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, MasterCard, Testing, Type checking, Validation, Value checking, bank, card for credit, credit card, finance, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/cc_visa.n ================================================================== --- idoc/man/files/modules/valtype/cc_visa.n +++ idoc/man/files/modules/valtype/cc_visa.n @@ -362,22 +362,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Testing, Type checking, VISA, Validation, Value checking, bank, card for credit, credit card, finance, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/ean13.n ================================================================== --- idoc/man/files/modules/valtype/ean13.n +++ idoc/man/files/modules/valtype/ean13.n @@ -356,22 +356,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, EAN, EAN13, European Article Number, International Article Number, Testing, Type checking, Validation, Value checking, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/iban.n ================================================================== --- idoc/man/files/modules/valtype/iban.n +++ idoc/man/files/modules/valtype/iban.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'vtype\&.inc' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2011 Andreas Kupries '\" -.TH "valtype::iban" n 1\&.7 tcllib "Validation types" +.TH "valtype::iban" n 1\&.6 tcllib "Validation types" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,11 @@ .sp package require \fBsnit 2\fR .sp package require \fBvaltype::common \fR .sp -package require \fBvaltype::iban ?1\&.7?\fR +package require \fBvaltype::iban ?1\&.6?\fR .sp \fBvaltype::iban\fR \fBvalidate\fR \fIvalue\fR .sp \fBvaltype::iban\fR \fBcheckdigit\fR \fIvalue\fR .sp @@ -353,22 +353,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, IBAN, International Bank Account Number, Testing, Type checking, Validation, Value checking, bank, finance, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/imei.n ================================================================== --- idoc/man/files/modules/valtype/imei.n +++ idoc/man/files/modules/valtype/imei.n @@ -358,22 +358,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, IMEI, International Mobile Equipment Identity, Testing, Type checking, Validation, Value checking, cell-phone, isA, mobile phone, phone .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/isbn.n ================================================================== --- idoc/man/files/modules/valtype/isbn.n +++ idoc/man/files/modules/valtype/isbn.n @@ -365,22 +365,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Book Number, Checking, EAN, EAN13, European Article Number, ISBN, International Article Number, International Standard Book Number, Testing, Type checking, Validation, Value checking, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/luhn.n ================================================================== --- idoc/man/files/modules/valtype/luhn.n +++ idoc/man/files/modules/valtype/luhn.n @@ -353,22 +353,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Testing, Type checking, Validation, Value checking, isA, luhn .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/luhn5.n ================================================================== --- idoc/man/files/modules/valtype/luhn5.n +++ idoc/man/files/modules/valtype/luhn5.n @@ -353,22 +353,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Testing, Type checking, Validation, Value checking, isA, luhn, luhn-5 .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/usnpi.n ================================================================== --- idoc/man/files/modules/valtype/usnpi.n +++ idoc/man/files/modules/valtype/usnpi.n @@ -358,22 +358,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, NPI, National Provider Identifier, Testing, Type checking, US-NPI, Validation, Value checking, isA, medicare .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/valtype_common.n ================================================================== --- idoc/man/files/modules/valtype/valtype_common.n +++ idoc/man/files/modules/valtype/valtype_common.n @@ -366,22 +366,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Testing, Type checking, Validation, Value checking, isA .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/valtype/verhoeff.n ================================================================== --- idoc/man/files/modules/valtype/verhoeff.n +++ idoc/man/files/modules/valtype/verhoeff.n @@ -353,22 +353,14 @@ bugs and other problems\&. Please report such in the category \fIvaltype\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Checking, Testing, Type checking, Validation, Value checking, isA, verhoeff .SH CATEGORY Validation, Type checking .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/cat.n ================================================================== --- idoc/man/files/modules/virtchannel_base/cat.n +++ idoc/man/files/modules/virtchannel_base/cat.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'cat\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2011 Andreas Kupries '\" -.TH "tcl::chan::cat" n 1\&.0\&.3 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::cat" n 1 tcllib "Reflected/virtual channel support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,11 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::core ?1?\fR .sp -package require \fBtcl::chan::cat ?1\&.0\&.3?\fR +package require \fBtcl::chan::cat ?1?\fR .sp \fB::tcl::chan::cat\fR \fIchan\fR\&.\&.\&. .sp .BE .SH DESCRIPTION @@ -313,22 +313,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS concatenation channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/facade.n ================================================================== --- idoc/man/files/modules/virtchannel_base/facade.n +++ idoc/man/files/modules/virtchannel_base/facade.n @@ -337,22 +337,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS concatenation channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/halfpipe.n ================================================================== --- idoc/man/files/modules/virtchannel_base/halfpipe.n +++ idoc/man/files/modules/virtchannel_base/halfpipe.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'halfpipe\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009, 2019 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "tcl::chan::halfpipe" n 1\&.0\&.1 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::halfpipe" n 1 tcllib "Reflected/virtual channel support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,13 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::events ?1?\fR .sp -package require \fBtcl::chan::halfpipe ?1\&.0\&.1?\fR +package require \fBtcl::chan::halfpipe ?1?\fR +.sp +package require \fBtcl::chan::halfpipe ?1?\fR .sp \fB::tcl::chan::halfpipe\fR ?\fB-option\fR \fIvalue\fR\&.\&.\&.? .sp \fIobjectCmd\fR \fBput\fR \fIbytes\fR .sp @@ -337,22 +339,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS callbacks, fifo, in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf -Copyright (c) 2009, 2019 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/nullzero.n ================================================================== --- idoc/man/files/modules/virtchannel_base/nullzero.n +++ idoc/man/files/modules/virtchannel_base/nullzero.n @@ -307,22 +307,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS /dev/null, /dev/zero, null, reflected channel, tip 219, virtual channel, zero .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/randseed.n ================================================================== --- idoc/man/files/modules/virtchannel_base/randseed.n +++ idoc/man/files/modules/virtchannel_base/randseed.n @@ -306,22 +306,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS /dev/random, merge, random, reflected channel, seed, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/std.n ================================================================== --- idoc/man/files/modules/virtchannel_base/std.n +++ idoc/man/files/modules/virtchannel_base/std.n @@ -307,22 +307,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS reflected channel, standard io, stdin, stdout, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2011 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_fifo.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_fifo.n +++ idoc/man/files/modules/virtchannel_base/tcllib_fifo.n @@ -289,11 +289,11 @@ .PP The \fBtcl::chan::fifo\fR package provides a command creating channels which live purely in memory\&. Access is fifo-like, i\&.e\&. things are read out of the channel in the order they were written to it\&. This is equivalent to the fifo channels provided by the package -\fBMemchan\fR, except that this is written in pure Tcl, not C\&. On +\fBMmechan\fR, except that this is written in pure Tcl, not C\&. On the other hand, \fBMemchan\fR is usable with Tcl 8\&.4 and before, whereas this package requires Tcl 8\&.5 or higher, and \fBTclOO\fR\&. .PP The internal \fBTclOO\fR class implementing the channel handler is a sub-class of the \fBtcl::chan::events\fR framework\&. @@ -307,22 +307,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS fifo, in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_fifo2.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_fifo2.n +++ idoc/man/files/modules/virtchannel_base/tcllib_fifo2.n @@ -294,11 +294,11 @@ each other in a fifo manner\&. What is written to one half of the pair can be read from the other half, in the same order\&. One particular application for this is communication between threads, with one half of the pair moved to the thread to talk to\&. This is equivalent to the fifo2 channels provided by the package -\fBMemchan\fR, except that this is written in pure Tcl, not C\&. On +\fBMmechan\fR, except that this is written in pure Tcl, not C\&. On the other hand, \fBMemchan\fR is usable with Tcl 8\&.4 and before, whereas this package requires Tcl 8\&.5 or higher, and \fBTclOO\fR\&. .PP The internal \fBTclOO\fR class implementing the channel handler is a sub-class of the \fBtcl::chan::events\fR framework\&. @@ -313,22 +313,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS connected fifos, fifo, in-memory channel, inter-thread communication, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_memchan.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_memchan.n +++ idoc/man/files/modules/virtchannel_base/tcllib_memchan.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'tcllib_memchan\&.man' by tcllib/doctools with format 'nroff' -'\" Copyright (c) 2009-2017 Andreas Kupries +'\" Copyright (c) 2009 Andreas Kupries '\" -.TH "tcl::chan::memchan" n 1\&.0\&.4 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::memchan" n 1 tcllib "Reflected/virtual channel support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,11 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::events ?1?\fR .sp -package require \fBtcl::chan::memchan ?1\&.0\&.4?\fR +package require \fBtcl::chan::memchan ?1?\fR .sp \fB::tcl::chan::memchan\fR .sp .BE .SH DESCRIPTION @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf -Copyright (c) 2009-2017 Andreas Kupries +Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_null.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_null.n +++ idoc/man/files/modules/virtchannel_base/tcllib_null.n @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS /dev/null, null, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_random.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_random.n +++ idoc/man/files/modules/virtchannel_base/tcllib_random.n @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS /dev/random, random, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_string.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_string.n +++ idoc/man/files/modules/virtchannel_base/tcllib_string.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'tcllib_string\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "tcl::chan::string" n 1\&.0\&.3 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::string" n 1 tcllib "Reflected/virtual channel support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,11 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::events ?1?\fR .sp -package require \fBtcl::chan::string ?1\&.0\&.3?\fR +package require \fBtcl::chan::string ?1?\fR .sp \fB::tcl::chan::string\fR \fIcontent\fR .sp .BE .SH DESCRIPTION @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_variable.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_variable.n +++ idoc/man/files/modules/virtchannel_base/tcllib_variable.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'tcllib_variable\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Andreas Kupries '\" -.TH "tcl::chan::variable" n 1\&.0\&.4 tcllib "Reflected/virtual channel support" +.TH "tcl::chan::variable" n 1 tcllib "Reflected/virtual channel support" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -278,11 +278,11 @@ .sp package require \fBTclOO \fR .sp package require \fBtcl::chan::events ?1?\fR .sp -package require \fBtcl::chan::variable ?1\&.0\&.4?\fR +package require \fBtcl::chan::variable ?1?\fR .sp \fB::tcl::chan::variable\fR \fIvarname\fR .sp .BE .SH DESCRIPTION @@ -311,22 +311,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS in-memory channel, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/tcllib_zero.n ================================================================== --- idoc/man/files/modules/virtchannel_base/tcllib_zero.n +++ idoc/man/files/modules/virtchannel_base/tcllib_zero.n @@ -310,22 +310,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS /dev/zero, reflected channel, tip 219, virtual channel, zero .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_base/textwindow.n ================================================================== --- idoc/man/files/modules/virtchannel_base/textwindow.n +++ idoc/man/files/modules/virtchannel_base/textwindow.n @@ -304,22 +304,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS Tk, reflected channel, text widget, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_core/core.n ================================================================== --- idoc/man/files/modules/virtchannel_core/core.n +++ idoc/man/files/modules/virtchannel_core/core.n @@ -336,22 +336,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_core/events.n ================================================================== --- idoc/man/files/modules/virtchannel_core/events.n +++ idoc/man/files/modules/virtchannel_core/events.n @@ -345,22 +345,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS event management, reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_core/transformcore.n ================================================================== --- idoc/man/files/modules/virtchannel_core/transformcore.n +++ idoc/man/files/modules/virtchannel_core/transformcore.n @@ -336,22 +336,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS reflected channel, tip 219, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/adler32.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/adler32.n +++ idoc/man/files/modules/virtchannel_transform/adler32.n @@ -330,22 +330,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS adler32, channel transformation, checksum, reflected channel, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/hex.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/hex.n +++ idoc/man/files/modules/virtchannel_transform/hex.n @@ -306,22 +306,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, hexadecimal, reflected channel, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/identity.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/identity.n +++ idoc/man/files/modules/virtchannel_transform/identity.n @@ -313,22 +313,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, identity, reflected channel, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/limitsize.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/limitsize.n +++ idoc/man/files/modules/virtchannel_transform/limitsize.n @@ -308,22 +308,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, limitsize, reflected channel, size limit, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/observe.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/observe.n +++ idoc/man/files/modules/virtchannel_transform/observe.n @@ -312,22 +312,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, observer, reflected channel, stream copy, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/rot.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/rot.n +++ idoc/man/files/modules/virtchannel_transform/rot.n @@ -315,22 +315,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS caesar cipher, channel transformation, cipher, decryption, encryption, reflected channel, rot, rot13, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/spacer.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/spacer.n +++ idoc/man/files/modules/virtchannel_transform/spacer.n @@ -308,22 +308,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, reflected channel, spacing, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/tcllib_zlib.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/tcllib_zlib.n +++ idoc/man/files/modules/virtchannel_transform/tcllib_zlib.n @@ -306,22 +306,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, compression, decompression, reflected channel, tip 230, tip 234, transformation, virtual channel, zlib .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/vt_base64.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/vt_base64.n +++ idoc/man/files/modules/virtchannel_transform/vt_base64.n @@ -306,22 +306,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS base64, channel transformation, reflected channel, tip 230, tip 317, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/vt_counter.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/vt_counter.n +++ idoc/man/files/modules/virtchannel_transform/vt_counter.n @@ -329,22 +329,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, counter, reflected channel, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/vt_crc32.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/vt_crc32.n +++ idoc/man/files/modules/virtchannel_transform/vt_crc32.n @@ -330,22 +330,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, checksum, crc32, reflected channel, tip 230, transformation, virtual channel .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/virtchannel_transform/vt_otp.n ================================================================== --- idoc/man/files/modules/virtchannel_transform/vt_otp.n +++ idoc/man/files/modules/virtchannel_transform/vt_otp.n @@ -311,22 +311,14 @@ bugs and other problems\&. Please report such in the category \fIvirtchannel\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS channel transformation, cipher, decryption, encryption, one time pad, otp, reflected channel, tip 230, transformation, virtual channel, xor .SH CATEGORY Channels .SH COPYRIGHT .nf Copyright (c) 2009 Andreas Kupries .fi Index: idoc/man/files/modules/websocket/websocket.n ================================================================== --- idoc/man/files/modules/websocket/websocket.n +++ idoc/man/files/modules/websocket/websocket.n @@ -472,11 +472,11 @@ Paths onto which this server will listen for incoming connections should be declared using \fB::websocket::live\fR\&. .TP \fB::websocket::live\fR \fIsock\fR \fIpath\fR \fIcb\fR ?\fIproto\fR? This procedure registers callbacks that will be performed on a -WebSocket compliant server registered with \fB::websocket::server\fR +WebSocket compliant server registered with \fB::websocket::server\fR] whenever a client connects to a matching path and protocol\&. \fIsock\fR is the listening socket of the websocket compliant server declared using \fB::websocket::server\fR\&. \fIpath\fR is a glob-style path to match in client request, whenever this will occur\&. \fIcb\fR is the command to callback (see Callbacks)\&. \fIproto\fR is a @@ -677,13 +677,12 @@ after 400 test $sock vwait forever .CE .SH "TLS SECURITY CONSIDERATIONS" -.PP -This package uses the \fBTLS\fR package to handle the -security for \fBhttps\fR urls and other socket connections\&. +This package uses the \fBTLS\fR package to handle the security +for \fBhttps\fR urls and other socket connections\&. .PP Policy decisions like the set of protocols to support and what ciphers to use are not the responsibility of \fBTLS\fR, nor of this package itself however\&. Such decisions are the responsibility of whichever application is @@ -711,19 +710,11 @@ bugs and other problems\&. Please report such in the category \fIwebsocket\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" http .SH KEYWORDS http, internet, net, rfc 6455 .SH CATEGORY Networking Index: idoc/man/files/modules/wip/wip.n ================================================================== --- idoc/man/files/modules/wip/wip.n +++ idoc/man/files/modules/wip/wip.n @@ -626,22 +626,14 @@ bugs and other problems\&. Please report such in the category \fIwip\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS interpreter, list, word .SH CATEGORY Programming tools .SH COPYRIGHT .nf Copyright (c) 2007-2010 Andreas Kupries .fi Index: idoc/man/files/modules/yaml/huddle.n ================================================================== --- idoc/man/files/modules/yaml/huddle.n +++ idoc/man/files/modules/yaml/huddle.n @@ -1,11 +1,11 @@ '\" '\" Generated from file 'huddle\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2008-2011 KATO Kanryu '\" Copyright (c) 2015 Miguel Martínez López '\" -.TH "huddle" n 0\&.3 tcllib "HUDDLE" +.TH "huddle" n 0\&.2 tcllib "HUDDLE" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -275,11 +275,11 @@ .SH NAME huddle \- Create and manipulate huddle object .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fBhuddle ?0\&.3?\fR +package require \fBhuddle ?0\&.2?\fR .sp \fBhuddle create\fR \fIkey\fR \fIvalue\fR ?\fIkey value \&.\&.\&.\fR? .sp \fBhuddle list\fR ?\fIvalue value \&.\&.\&.\fR? .sp @@ -886,18 +886,10 @@ bugs and other problems\&. Please report such in the category \fIhuddle\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" yaml .SH KEYWORDS data exchange, exchange format, huddle, json, parsing, text processing, yaml .SH COPYRIGHT Index: idoc/man/files/modules/yaml/yaml.n ================================================================== --- idoc/man/files/modules/yaml/yaml.n +++ idoc/man/files/modules/yaml/yaml.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'yaml\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2008 KATO Kanryu '\" -.TH "yaml" n 0\&.4\&.1 tcllib "YAML processing" +.TH "yaml" n 0\&.3\&.9 tcllib "YAML processing" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME yaml \- YAML Format Encoder/Decoder .SH SYNOPSIS package require \fBTcl 8\&.4\fR .sp -package require \fByaml ?0\&.4\&.1?\fR +package require \fByaml ?0\&.3\&.9?\fR .sp \fB::yaml::yaml2dict\fR ?\fIoptions\fR? \fItxt\fR .sp \fB::yaml::yaml2huddle\fR ?\fIoptions\fR? \fItxt\fR .sp @@ -458,22 +458,14 @@ bugs and other problems\&. Please report such in the category \fIyaml\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH "SEE ALSO" base64, huddle, json .SH KEYWORDS data exchange, huddle, parsing, text processing, yaml .SH COPYRIGHT .nf Copyright (c) 2008 KATO Kanryu .fi Index: idoc/man/files/modules/zip/decode.n ================================================================== --- idoc/man/files/modules/zip/decode.n +++ idoc/man/files/modules/zip/decode.n @@ -273,10 +273,12 @@ .BS .SH NAME zipfile::decode \- Access to zip archives .SH SYNOPSIS package require \fBTcl 8\&.4\fR +.sp +package require \fBfileutil::magic::mimetype \fR .sp package require \fBfileutil::decode 0\&.2\&.1\fR .sp package require \fBTrf \fR .sp @@ -309,11 +311,10 @@ \fB::zipfile::decode::unzipfile\fR \fIarchive\fR \fIdstdir\fR .sp .BE .SH DESCRIPTION .PP -Note: packages Trf and zlibtcl are not required if TCL 8\&.6 is available\&. This package provides commands to decompress and access the contents of zip archives\&. .SH API .TP \fB::zipfile::decode::archive\fR @@ -394,22 +395,14 @@ bugs and other problems\&. Please report such in the category \fIzipfile\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS decompression, zip .SH CATEGORY File .SH COPYRIGHT .nf Copyright (c) 2008-2016 Andreas Kupries .fi Index: idoc/man/files/modules/zip/encode.n ================================================================== --- idoc/man/files/modules/zip/encode.n +++ idoc/man/files/modules/zip/encode.n @@ -350,22 +350,14 @@ bugs and other problems\&. Please report such in the category \fIzipfile\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS compression, zip .SH CATEGORY File .SH COPYRIGHT .nf Copyright (c) 2008-2009 Andreas Kupries .fi Index: idoc/man/files/modules/zip/mkzip.n ================================================================== --- idoc/man/files/modules/zip/mkzip.n +++ idoc/man/files/modules/zip/mkzip.n @@ -1,10 +1,10 @@ '\" '\" Generated from file 'mkzip\&.man' by tcllib/doctools with format 'nroff' '\" Copyright (c) 2009 Pat Thoyts '\" -.TH "zipfile::mkzip" n 1\&.2\&.1 tcllib "Zip archive creation" +.TH "zipfile::mkzip" n 1\&.2 tcllib "Zip archive creation" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. @@ -274,11 +274,11 @@ .SH NAME zipfile::mkzip \- Build a zip archive .SH SYNOPSIS package require \fBTcl 8\&.6\fR .sp -package require \fBzipfile::mkzip ?1\&.2\&.1?\fR +package require \fBzipfile::mkzip ?1\&.2?\fR .sp \fB::zipfile::mkzip::mkzip\fR \fIzipfile\fR ?\fB-zipkit\fR? ?\fB-runtime\fR \fIprefix\fR? ?\fB-comment\fR \fIstring\fR? ?\fB-directory\fR \fIrootpath\fR? ?\fB-exclude\fR \fIexclude\fR? ?\fB--\fR? ?\fIpath\fR\&.\&.\&.? .sp .BE .SH DESCRIPTION @@ -374,22 +374,14 @@ bugs and other problems\&. Please report such in the category \fIzipfile\fR of the \fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&. Please also report any ideas for enhancements you may have for either package and/or documentation\&. -.PP -When proposing code changes, please provide \fIunified diffs\fR, -i\&.e the output of \fBdiff -u\fR\&. -.PP -Note further that \fIattachments\fR are strongly preferred over -inlined patches\&. Attachments can be made by going to the \fBEdit\fR -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar\&. .SH KEYWORDS decompression, zip .SH CATEGORY File .SH COPYRIGHT .nf Copyright (c) 2009 Pat Thoyts .fi Index: idoc/man/index.n ================================================================== --- idoc/man/index.n +++ idoc/man/index.n @@ -327,1408 +327,10 @@ tclDES .TP \fBfiles/modules/des/tcldesjr\&.n\fR tclDESjr .RE -AMEX -.RS -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.RE -AST -.RS -.TP -\fBfiles/modules/grammar_me/me_ast\&.n\fR -grammar::me_ast -.RE -American Express -.RS -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.RE -BWidget -.RS -.TP -\fBfiles/modules/snit/snit\&.n\fR -snit -.TP -\fBfiles/modules/snit/snitfaq\&.n\fR -snitfaq -.RE -Bessel functions -.RS -.TP -\fBfiles/modules/math/special\&.n\fR -math::special -.RE -BitTorrent -.RS -.TP -\fBfiles/modules/bee/bee\&.n\fR -bee -.RE -Book Number -.RS -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -C -.RS -.TP -\fBfiles/modules/doctools2idx/idx_msgcat_c\&.n\fR -doctools::msgcat::idx::c -.TP -\fBfiles/modules/doctools2toc/toc_msgcat_c\&.n\fR -doctools::msgcat::toc::c -.RE -C++ -.RS -.TP -\fBfiles/modules/snit/snit\&.n\fR -snit -.TP -\fBfiles/modules/snit/snitfaq\&.n\fR -snitfaq -.TP -\fBfiles/modules/stooop/stooop\&.n\fR -stooop -.TP -\fBfiles/modules/stooop/switched\&.n\fR -switched -.RE -CFG -.RS -.TP -\fBfiles/modules/grammar_me/me_intro\&.n\fR -grammar::me_intro -.RE -CFL -.RS -.TP -\fBfiles/modules/grammar_me/me_intro\&.n\fR -grammar::me_intro -.RE -CGI -.RS -.TP -\fBfiles/modules/ncgi/ncgi\&.n\fR -ncgi -.RE -CONTAINER -.RS -.TP -\fBfiles/modules/pt/pt_peg_export_container\&.n\fR -pt::peg::export::container -.TP -\fBfiles/modules/pt/pt_peg_to_container\&.n\fR -pt::peg::to::container -.RE -CPARAM -.RS -.TP -\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR -pt::peg::to::cparam -.RE -CSS -.RS -.TP -\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR -doctools::html::cssdefaults -.RE -CVS -.RS -.TP -\fBfiles/modules/rcs/rcs\&.n\fR -rcs -.RE -Checking -.RS -.TP -\fBfiles/modules/valtype/valtype_common\&.n\fR -valtype::common -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.TP -\fBfiles/modules/valtype/luhn\&.n\fR -valtype::luhn -.TP -\fBfiles/modules/valtype/luhn5\&.n\fR -valtype::luhn5 -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.TP -\fBfiles/modules/valtype/verhoeff\&.n\fR -valtype::verhoeff -.RE -Cost -.RS -.TP -\fBfiles/modules/treeql/treeql\&.n\fR -treeql -.RE -DE -.RS -.TP -\fBfiles/modules/doctools2idx/idx_msgcat_de\&.n\fR -doctools::msgcat::idx::de -.TP -\fBfiles/modules/doctools2toc/toc_msgcat_de\&.n\fR -doctools::msgcat::toc::de -.RE -DES -.RS -.TP -\fBfiles/modules/des/des\&.n\fR -des -.TP -\fBfiles/modules/des/tcldes\&.n\fR -tclDES -.TP -\fBfiles/modules/des/tcldesjr\&.n\fR -tclDESjr -.RE -DNS -.RS -.TP -\fBfiles/modules/dns/tcllib_dns\&.n\fR -dns -.RE -DOM -.RS -.TP -\fBfiles/modules/treeql/treeql\&.n\fR -treeql -.RE -Discover -.RS -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.RE -EAN -.RS -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -EAN13 -.RS -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -EBNF -.RS -.TP -\fBfiles/apps/pt\&.n\fR -pt -.TP -\fBfiles/modules/pt/pt_astree\&.n\fR -pt::ast -.TP -\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR -pt::cparam::configuration::critcl -.TP -\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR -pt::cparam::configuration::tea -.TP -\fBfiles/modules/pt/pt_json_language\&.n\fR -pt::json_language -.TP -\fBfiles/modules/pt/pt_param\&.n\fR -pt::param -.TP -\fBfiles/modules/pt/pt_pexpression\&.n\fR -pt::pe -.TP -\fBfiles/modules/pt/pt_pexpr_op\&.n\fR -pt::pe::op -.TP -\fBfiles/modules/pt/pt_pegrammar\&.n\fR -pt::peg -.TP -\fBfiles/modules/pt/pt_peg_container\&.n\fR -pt::peg::container -.TP -\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR -pt::peg::container::peg -.TP -\fBfiles/modules/pt/pt_peg_export\&.n\fR -pt::peg::export -.TP -\fBfiles/modules/pt/pt_peg_export_container\&.n\fR -pt::peg::export::container -.TP -\fBfiles/modules/pt/pt_peg_export_json\&.n\fR -pt::peg::export::json -.TP -\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR -pt::peg::export::peg -.TP -\fBfiles/modules/pt/pt_peg_from_container\&.n\fR -pt::peg::from::container -.TP -\fBfiles/modules/pt/pt_peg_from_json\&.n\fR -pt::peg::from::json -.TP -\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR -pt::peg::from::peg -.TP -\fBfiles/modules/pt/pt_peg_import\&.n\fR -pt::peg::import -.TP -\fBfiles/modules/pt/pt_peg_import_container\&.n\fR -pt::peg::import::container -.TP -\fBfiles/modules/pt/pt_peg_import_json\&.n\fR -pt::peg::import::json -.TP -\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR -pt::peg::import::peg -.TP -\fBfiles/modules/pt/pt_peg_interp\&.n\fR -pt::peg::interp -.TP -\fBfiles/modules/pt/pt_peg_to_container\&.n\fR -pt::peg::to::container -.TP -\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR -pt::peg::to::cparam -.TP -\fBfiles/modules/pt/pt_peg_to_json\&.n\fR -pt::peg::to::json -.TP -\fBfiles/modules/pt/pt_peg_to_param\&.n\fR -pt::peg::to::param -.TP -\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR -pt::peg::to::peg -.TP -\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR -pt::peg::to::tclparam -.TP -\fBfiles/modules/pt/pt_peg_language\&.n\fR -pt::peg_language -.TP -\fBfiles/modules/pt/pt_peg_introduction\&.n\fR -pt::pegrammar -.TP -\fBfiles/modules/pt/pt_pgen\&.n\fR -pt::pgen -.TP -\fBfiles/modules/pt/pt_rdengine\&.n\fR -pt::rde -.TP -\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR -pt::tclparam::configuration::nx -.TP -\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR -pt::tclparam::configuration::snit -.TP -\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR -pt::tclparam::configuration::tcloo -.TP -\fBfiles/modules/pt/pt_util\&.n\fR -pt::util -.TP -\fBfiles/modules/pt/pt_to_api\&.n\fR -pt_export_api -.TP -\fBfiles/modules/pt/pt_from_api\&.n\fR -pt_import_api -.TP -\fBfiles/modules/pt/pt_introduction\&.n\fR -pt_introduction -.TP -\fBfiles/modules/pt/pt_parse_peg\&.n\fR -pt_parse_peg -.TP -\fBfiles/modules/pt/pt_parser_api\&.n\fR -pt_parser_api -.TP -\fBfiles/modules/pt/pt_peg_op\&.n\fR -pt_peg_op -.RE -EN -.RS -.TP -\fBfiles/modules/doctools2idx/idx_msgcat_en\&.n\fR -doctools::msgcat::idx::en -.TP -\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR -doctools::msgcat::toc::en -.RE -European Article Number -.RS -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -FFT -.RS -.TP -\fBfiles/modules/math/fourier\&.n\fR -math::fourier -.RE -FIPS 180-1 -.RS -.TP -\fBfiles/modules/sha1/sha1\&.n\fR -sha1 -.TP -\fBfiles/modules/sha1/sha256\&.n\fR -sha256 -.RE -FR -.RS -.TP -\fBfiles/modules/doctools2idx/idx_msgcat_fr\&.n\fR -doctools::msgcat::idx::fr -.TP -\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR -doctools::msgcat::toc::fr -.RE -Fisher-Yates -.RS -.TP -\fBfiles/modules/struct/struct_list\&.n\fR -struct::list -.RE -Fourier transform -.RS -.TP -\fBfiles/modules/math/fourier\&.n\fR -math::fourier -.RE -GUID -.RS -.TP -\fBfiles/modules/uuid/uuid\&.n\fR -uuid -.RE -HTML -.RS -.TP -\fBfiles/modules/doctools/doctools\&.n\fR -doctools -.TP -\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR -doctools::html::cssdefaults -.TP -\fBfiles/modules/doctools2idx/idx_container\&.n\fR -doctools::idx -.TP -\fBfiles/modules/doctools/docidx\&.n\fR -doctools::idx -.TP -\fBfiles/modules/doctools2idx/idx_export\&.n\fR -doctools::idx::export -.TP -\fBfiles/modules/doctools2idx/idx_export_html\&.n\fR -doctools::idx::export::html -.TP -\fBfiles/modules/doctools/doctoc\&.n\fR -doctools::toc -.TP -\fBfiles/modules/doctools2toc/toc_container\&.n\fR -doctools::toc -.TP -\fBfiles/modules/doctools2toc/toc_export\&.n\fR -doctools::toc::export -.TP -\fBfiles/modules/doctools2toc/toc_export_html\&.n\fR -doctools::toc::export::html -.TP -\fBfiles/apps/dtplite\&.n\fR -dtplite -.TP -\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR -dtplite -.TP -\fBfiles/modules/doctools/mpexpand\&.n\fR -mpexpand -.RE -IBAN -.RS -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.RE -IMEI -.RS -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.RE -ISBN -.RS -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -Incr Tcl -.RS -.TP -\fBfiles/modules/snit/snit\&.n\fR -snit -.TP -\fBfiles/modules/snit/snitfaq\&.n\fR -snitfaq -.RE -International Article Number -.RS -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -International Bank Account Number -.RS -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.RE -International Mobile Equipment Identity -.RS -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.RE -International Standard Book Number -.RS -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.RE -JSON -.RS -.TP -\fBfiles/modules/doctools2idx/idx_export_json\&.n\fR -doctools::idx::export::json -.TP -\fBfiles/modules/doctools2idx/idx_import_json\&.n\fR -doctools::idx::import::json -.TP -\fBfiles/modules/doctools2toc/toc_export_json\&.n\fR -doctools::toc::export::json -.TP -\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR -doctools::toc::import::json -.TP -\fBfiles/modules/pt/pt_peg_export_json\&.n\fR -pt::peg::export::json -.TP -\fBfiles/modules/pt/pt_peg_from_json\&.n\fR -pt::peg::from::json -.TP -\fBfiles/modules/pt/pt_peg_import_json\&.n\fR -pt::peg::import::json -.TP -\fBfiles/modules/pt/pt_peg_to_json\&.n\fR -pt::peg::to::json -.RE -LL(k) -.RS -.TP -\fBfiles/modules/grammar_me/me_intro\&.n\fR -grammar::me_intro -.TP -\fBfiles/modules/grammar_peg/peg\&.n\fR -grammar::peg -.TP -\fBfiles/modules/grammar_peg/peg_interp\&.n\fR -grammar::peg::interp -.TP -\fBfiles/apps/pt\&.n\fR -pt -.TP -\fBfiles/modules/pt/pt_astree\&.n\fR -pt::ast -.TP -\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR -pt::cparam::configuration::critcl -.TP -\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR -pt::cparam::configuration::tea -.TP -\fBfiles/modules/pt/pt_json_language\&.n\fR -pt::json_language -.TP -\fBfiles/modules/pt/pt_param\&.n\fR -pt::param -.TP -\fBfiles/modules/pt/pt_pexpression\&.n\fR -pt::pe -.TP -\fBfiles/modules/pt/pt_pexpr_op\&.n\fR -pt::pe::op -.TP -\fBfiles/modules/pt/pt_pegrammar\&.n\fR -pt::peg -.TP -\fBfiles/modules/pt/pt_peg_container\&.n\fR -pt::peg::container -.TP -\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR -pt::peg::container::peg -.TP -\fBfiles/modules/pt/pt_peg_export\&.n\fR -pt::peg::export -.TP -\fBfiles/modules/pt/pt_peg_export_container\&.n\fR -pt::peg::export::container -.TP -\fBfiles/modules/pt/pt_peg_export_json\&.n\fR -pt::peg::export::json -.TP -\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR -pt::peg::export::peg -.TP -\fBfiles/modules/pt/pt_peg_from_container\&.n\fR -pt::peg::from::container -.TP -\fBfiles/modules/pt/pt_peg_from_json\&.n\fR -pt::peg::from::json -.TP -\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR -pt::peg::from::peg -.TP -\fBfiles/modules/pt/pt_peg_import\&.n\fR -pt::peg::import -.TP -\fBfiles/modules/pt/pt_peg_import_container\&.n\fR -pt::peg::import::container -.TP -\fBfiles/modules/pt/pt_peg_import_json\&.n\fR -pt::peg::import::json -.TP -\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR -pt::peg::import::peg -.TP -\fBfiles/modules/pt/pt_peg_interp\&.n\fR -pt::peg::interp -.TP -\fBfiles/modules/pt/pt_peg_to_container\&.n\fR -pt::peg::to::container -.TP -\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR -pt::peg::to::cparam -.TP -\fBfiles/modules/pt/pt_peg_to_json\&.n\fR -pt::peg::to::json -.TP -\fBfiles/modules/pt/pt_peg_to_param\&.n\fR -pt::peg::to::param -.TP -\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR -pt::peg::to::peg -.TP -\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR -pt::peg::to::tclparam -.TP -\fBfiles/modules/pt/pt_peg_language\&.n\fR -pt::peg_language -.TP -\fBfiles/modules/pt/pt_peg_introduction\&.n\fR -pt::pegrammar -.TP -\fBfiles/modules/pt/pt_pgen\&.n\fR -pt::pgen -.TP -\fBfiles/modules/pt/pt_rdengine\&.n\fR -pt::rde -.TP -\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR -pt::tclparam::configuration::nx -.TP -\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR -pt::tclparam::configuration::snit -.TP -\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR -pt::tclparam::configuration::tcloo -.TP -\fBfiles/modules/pt/pt_util\&.n\fR -pt::util -.TP -\fBfiles/modules/pt/pt_to_api\&.n\fR -pt_export_api -.TP -\fBfiles/modules/pt/pt_from_api\&.n\fR -pt_import_api -.TP -\fBfiles/modules/pt/pt_introduction\&.n\fR -pt_introduction -.TP -\fBfiles/modules/pt/pt_parse_peg\&.n\fR -pt_parse_peg -.TP -\fBfiles/modules/pt/pt_parser_api\&.n\fR -pt_parser_api -.TP -\fBfiles/modules/pt/pt_peg_op\&.n\fR -pt_peg_op -.RE -LaTeX -.RS -.TP -\fBfiles/modules/docstrip/docstrip\&.n\fR -docstrip -.TP -\fBfiles/modules/docstrip/docstrip_util\&.n\fR -docstrip_util -.TP -\fBfiles/apps/tcldocstrip\&.n\fR -tcldocstrip -.RE -MasterCard -.RS -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.RE -NPI -.RS -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.RE -NTLM -.RS -.TP -\fBfiles/modules/sasl/ntlm\&.n\fR -SASL::NTLM -.RE -NTP -.RS -.TP -\fBfiles/modules/ntp/ntp_time\&.n\fR -ntp_time -.RE -National Provider Identifier -.RS -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.RE -PARAM -.RS -.TP -\fBfiles/modules/pt/pt_peg_to_param\&.n\fR -pt::peg::to::param -.RE -PCA -.RS -.TP -\fBfiles/modules/math/pca\&.n\fR -math::PCA -.RE -PEG -.RS -.TP -\fBfiles/modules/grammar_me/me_intro\&.n\fR -grammar::me_intro -.TP -\fBfiles/modules/page/page_util_norm_peg\&.n\fR -page_util_norm_peg -.TP -\fBfiles/modules/page/page_util_peg\&.n\fR -page_util_peg -.TP -\fBfiles/apps/pt\&.n\fR -pt -.TP -\fBfiles/modules/pt/pt_astree\&.n\fR -pt::ast -.TP -\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR -pt::cparam::configuration::critcl -.TP -\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR -pt::cparam::configuration::tea -.TP -\fBfiles/modules/pt/pt_json_language\&.n\fR -pt::json_language -.TP -\fBfiles/modules/pt/pt_param\&.n\fR -pt::param -.TP -\fBfiles/modules/pt/pt_pexpression\&.n\fR -pt::pe -.TP -\fBfiles/modules/pt/pt_pexpr_op\&.n\fR -pt::pe::op -.TP -\fBfiles/modules/pt/pt_pegrammar\&.n\fR -pt::peg -.TP -\fBfiles/modules/pt/pt_peg_container\&.n\fR -pt::peg::container -.TP -\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR -pt::peg::container::peg -.TP -\fBfiles/modules/pt/pt_peg_export\&.n\fR -pt::peg::export -.TP -\fBfiles/modules/pt/pt_peg_export_container\&.n\fR -pt::peg::export::container -.TP -\fBfiles/modules/pt/pt_peg_export_json\&.n\fR -pt::peg::export::json -.TP -\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR -pt::peg::export::peg -.TP -\fBfiles/modules/pt/pt_peg_from_container\&.n\fR -pt::peg::from::container -.TP -\fBfiles/modules/pt/pt_peg_from_json\&.n\fR -pt::peg::from::json -.TP -\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR -pt::peg::from::peg -.TP -\fBfiles/modules/pt/pt_peg_import\&.n\fR -pt::peg::import -.TP -\fBfiles/modules/pt/pt_peg_import_container\&.n\fR -pt::peg::import::container -.TP -\fBfiles/modules/pt/pt_peg_import_json\&.n\fR -pt::peg::import::json -.TP -\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR -pt::peg::import::peg -.TP -\fBfiles/modules/pt/pt_peg_interp\&.n\fR -pt::peg::interp -.TP -\fBfiles/modules/pt/pt_peg_to_container\&.n\fR -pt::peg::to::container -.TP -\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR -pt::peg::to::cparam -.TP -\fBfiles/modules/pt/pt_peg_to_json\&.n\fR -pt::peg::to::json -.TP -\fBfiles/modules/pt/pt_peg_to_param\&.n\fR -pt::peg::to::param -.TP -\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR -pt::peg::to::peg -.TP -\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR -pt::peg::to::tclparam -.TP -\fBfiles/modules/pt/pt_peg_language\&.n\fR -pt::peg_language -.TP -\fBfiles/modules/pt/pt_peg_introduction\&.n\fR -pt::pegrammar -.TP -\fBfiles/modules/pt/pt_pgen\&.n\fR -pt::pgen -.TP -\fBfiles/modules/pt/pt_rdengine\&.n\fR -pt::rde -.TP -\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR -pt::tclparam::configuration::nx -.TP -\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR -pt::tclparam::configuration::snit -.TP -\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR -pt::tclparam::configuration::tcloo -.TP -\fBfiles/modules/pt/pt_util\&.n\fR -pt::util -.TP -\fBfiles/modules/pt/pt_to_api\&.n\fR -pt_export_api -.TP -\fBfiles/modules/pt/pt_from_api\&.n\fR -pt_import_api -.TP -\fBfiles/modules/pt/pt_introduction\&.n\fR -pt_introduction -.TP -\fBfiles/modules/pt/pt_parse_peg\&.n\fR -pt_parse_peg -.TP -\fBfiles/modules/pt/pt_parser_api\&.n\fR -pt_parser_api -.TP -\fBfiles/modules/pt/pt_peg_op\&.n\fR -pt_peg_op -.RE -RCS -.RS -.TP -\fBfiles/modules/rcs/rcs\&.n\fR -rcs -.RE -RCS patch -.RS -.TP -\fBfiles/modules/rcs/rcs\&.n\fR -rcs -.RE -RFC 2718 -.RS -.TP -\fBfiles/modules/oauth/oauth\&.n\fR -oauth -.RE -RFC 5849 -.RS -.TP -\fBfiles/modules/oauth/oauth\&.n\fR -oauth -.RE -RIPEMD -.RS -.TP -\fBfiles/modules/ripemd/ripemd128\&.n\fR -ripemd128 -.TP -\fBfiles/modules/ripemd/ripemd160\&.n\fR -ripemd160 -.RE -SASL -.RS -.TP -\fBfiles/modules/sasl/sasl\&.n\fR -SASL -.TP -\fBfiles/modules/sasl/ntlm\&.n\fR -SASL::NTLM -.TP -\fBfiles/modules/sasl/scram\&.n\fR -SASL::SCRAM -.TP -\fBfiles/modules/sasl/gtoken\&.n\fR -SASL::XGoogleToken -.RE -SCCS -.RS -.TP -\fBfiles/modules/rcs/rcs\&.n\fR -rcs -.RE -SCRAM -.RS -.TP -\fBfiles/modules/sasl/scram\&.n\fR -SASL::SCRAM -.RE -SNTP -.RS -.TP -\fBfiles/modules/ntp/ntp_time\&.n\fR -ntp_time -.RE -Snit -.RS -.TP -\fBfiles/modules/snit/snit\&.n\fR -snit -.RE -TCLPARAM -.RS -.TP -\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR -pt::peg::to::tclparam -.RE -TDPL -.RS -.TP -\fBfiles/modules/grammar_peg/peg\&.n\fR -grammar::peg -.TP -\fBfiles/modules/grammar_peg/peg_interp\&.n\fR -grammar::peg::interp -.TP -\fBfiles/apps/pt\&.n\fR -pt -.TP -\fBfiles/modules/pt/pt_astree\&.n\fR -pt::ast -.TP -\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR -pt::cparam::configuration::critcl -.TP -\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR -pt::cparam::configuration::tea -.TP -\fBfiles/modules/pt/pt_json_language\&.n\fR -pt::json_language -.TP -\fBfiles/modules/pt/pt_param\&.n\fR -pt::param -.TP -\fBfiles/modules/pt/pt_pexpression\&.n\fR -pt::pe -.TP -\fBfiles/modules/pt/pt_pexpr_op\&.n\fR -pt::pe::op -.TP -\fBfiles/modules/pt/pt_pegrammar\&.n\fR -pt::peg -.TP -\fBfiles/modules/pt/pt_peg_container\&.n\fR -pt::peg::container -.TP -\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR -pt::peg::container::peg -.TP -\fBfiles/modules/pt/pt_peg_export\&.n\fR -pt::peg::export -.TP -\fBfiles/modules/pt/pt_peg_export_container\&.n\fR -pt::peg::export::container -.TP -\fBfiles/modules/pt/pt_peg_export_json\&.n\fR -pt::peg::export::json -.TP -\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR -pt::peg::export::peg -.TP -\fBfiles/modules/pt/pt_peg_from_container\&.n\fR -pt::peg::from::container -.TP -\fBfiles/modules/pt/pt_peg_from_json\&.n\fR -pt::peg::from::json -.TP -\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR -pt::peg::from::peg -.TP -\fBfiles/modules/pt/pt_peg_import\&.n\fR -pt::peg::import -.TP -\fBfiles/modules/pt/pt_peg_import_container\&.n\fR -pt::peg::import::container -.TP -\fBfiles/modules/pt/pt_peg_import_json\&.n\fR -pt::peg::import::json -.TP -\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR -pt::peg::import::peg -.TP -\fBfiles/modules/pt/pt_peg_interp\&.n\fR -pt::peg::interp -.TP -\fBfiles/modules/pt/pt_peg_to_container\&.n\fR -pt::peg::to::container -.TP -\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR -pt::peg::to::cparam -.TP -\fBfiles/modules/pt/pt_peg_to_json\&.n\fR -pt::peg::to::json -.TP -\fBfiles/modules/pt/pt_peg_to_param\&.n\fR -pt::peg::to::param -.TP -\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR -pt::peg::to::peg -.TP -\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR -pt::peg::to::tclparam -.TP -\fBfiles/modules/pt/pt_peg_language\&.n\fR -pt::peg_language -.TP -\fBfiles/modules/pt/pt_peg_introduction\&.n\fR -pt::pegrammar -.TP -\fBfiles/modules/pt/pt_pgen\&.n\fR -pt::pgen -.TP -\fBfiles/modules/pt/pt_rdengine\&.n\fR -pt::rde -.TP -\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR -pt::tclparam::configuration::nx -.TP -\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR -pt::tclparam::configuration::snit -.TP -\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR -pt::tclparam::configuration::tcloo -.TP -\fBfiles/modules/pt/pt_util\&.n\fR -pt::util -.TP -\fBfiles/modules/pt/pt_to_api\&.n\fR -pt_export_api -.TP -\fBfiles/modules/pt/pt_from_api\&.n\fR -pt_import_api -.TP -\fBfiles/modules/pt/pt_introduction\&.n\fR -pt_introduction -.TP -\fBfiles/modules/pt/pt_parse_peg\&.n\fR -pt_parse_peg -.TP -\fBfiles/modules/pt/pt_parser_api\&.n\fR -pt_parser_api -.TP -\fBfiles/modules/pt/pt_peg_op\&.n\fR -pt_peg_op -.RE -TMML -.RS -.TP -\fBfiles/modules/doctools/doctools\&.n\fR -doctools -.TP -\fBfiles/modules/doctools2idx/idx_container\&.n\fR -doctools::idx -.TP -\fBfiles/modules/doctools/docidx\&.n\fR -doctools::idx -.TP -\fBfiles/modules/doctools/doctoc\&.n\fR -doctools::toc -.TP -\fBfiles/modules/doctools2toc/toc_container\&.n\fR -doctools::toc -.TP -\fBfiles/apps/dtplite\&.n\fR -dtplite -.TP -\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR -dtplite -.TP -\fBfiles/modules/doctools/mpexpand\&.n\fR -mpexpand -.RE -TOOL -.RS -.TP -\fBfiles/modules/oometa/oometa\&.n\fR -oometa -.TP -\fBfiles/modules/tool/tool\&.n\fR -tool -.TP -\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR -tool::dict_ensemble -.RE -TPDL -.RS -.TP -\fBfiles/modules/grammar_me/me_intro\&.n\fR -grammar::me_intro -.RE -Tcl module -.RS -.TP -\fBfiles/modules/docstrip/docstrip_util\&.n\fR -docstrip_util -.RE -Tcl syntax -.RS -.TP -\fBfiles/modules/doctools2base/tcl_parse\&.n\fR -doctools::tcl::parse -.RE -TclOO -.RS -.TP -\fBfiles/modules/clay/clay\&.n\fR -clay -.TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.TP -\fBfiles/modules/tool/meta\&.n\fR -oo::util -.TP -\fBfiles/modules/ooutil/ooutil\&.n\fR -oo::util -.TP -\fBfiles/modules/oometa/oometa\&.n\fR -oometa -.TP -\fBfiles/modules/tool/tool\&.n\fR -tool -.TP -\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR -tool::dict_ensemble -.RE -TeX -.RS -.TP -\fBfiles/modules/textutil/textutil\&.n\fR -textutil -.TP -\fBfiles/modules/textutil/adjust\&.n\fR -textutil::adjust -.RE -Testing -.RS -.TP -\fBfiles/modules/valtype/valtype_common\&.n\fR -valtype::common -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.TP -\fBfiles/modules/valtype/luhn\&.n\fR -valtype::luhn -.TP -\fBfiles/modules/valtype/luhn5\&.n\fR -valtype::luhn5 -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.TP -\fBfiles/modules/valtype/verhoeff\&.n\fR -valtype::verhoeff -.RE -Tk -.RS -.TP -\fBfiles/modules/virtchannel_base/textwindow\&.n\fR -tcl::chan::textwindow -.RE -TreeQL -.RS -.TP -\fBfiles/modules/treeql/treeql\&.n\fR -treeql -.RE -Type checking -.RS -.TP -\fBfiles/modules/valtype/valtype_common\&.n\fR -valtype::common -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.TP -\fBfiles/modules/valtype/luhn\&.n\fR -valtype::luhn -.TP -\fBfiles/modules/valtype/luhn5\&.n\fR -valtype::luhn5 -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.TP -\fBfiles/modules/valtype/verhoeff\&.n\fR -valtype::verhoeff -.RE -US-NPI -.RS -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.RE -UUID -.RS -.TP -\fBfiles/modules/uuid/uuid\&.n\fR -uuid -.RE -VISA -.RS -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.RE -Validation -.RS -.TP -\fBfiles/modules/valtype/valtype_common\&.n\fR -valtype::common -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.TP -\fBfiles/modules/valtype/luhn\&.n\fR -valtype::luhn -.TP -\fBfiles/modules/valtype/luhn5\&.n\fR -valtype::luhn5 -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.TP -\fBfiles/modules/valtype/verhoeff\&.n\fR -valtype::verhoeff -.RE -Value checking -.RS -.TP -\fBfiles/modules/valtype/valtype_common\&.n\fR -valtype::common -.TP -\fBfiles/modules/valtype/cc_amex\&.n\fR -valtype::creditcard::amex -.TP -\fBfiles/modules/valtype/cc_discover\&.n\fR -valtype::creditcard::discover -.TP -\fBfiles/modules/valtype/cc_mastercard\&.n\fR -valtype::creditcard::mastercard -.TP -\fBfiles/modules/valtype/cc_visa\&.n\fR -valtype::creditcard::visa -.TP -\fBfiles/modules/valtype/ean13\&.n\fR -valtype::gs1::ean13 -.TP -\fBfiles/modules/valtype/iban\&.n\fR -valtype::iban -.TP -\fBfiles/modules/valtype/imei\&.n\fR -valtype::imei -.TP -\fBfiles/modules/valtype/isbn\&.n\fR -valtype::isbn -.TP -\fBfiles/modules/valtype/luhn\&.n\fR -valtype::luhn -.TP -\fBfiles/modules/valtype/luhn5\&.n\fR -valtype::luhn5 -.TP -\fBfiles/modules/valtype/usnpi\&.n\fR -valtype::usnpi -.TP -\fBfiles/modules/valtype/verhoeff\&.n\fR -valtype::verhoeff -.RE -WWW -.RS -.TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.RE -XGoogleToken -.RS -.TP -\fBfiles/modules/sasl/gtoken\&.n\fR -SASL::XGoogleToken -.RE -XPath -.RS -.TP -\fBfiles/modules/treeql/treeql\&.n\fR -treeql -.RE -XSLT -.RS -.TP -\fBfiles/modules/treeql/treeql\&.n\fR -treeql -.RE abstract syntax tree .RS .TP \fBfiles/modules/grammar_me/me_util\&.n\fR grammar::me::util @@ -1827,10 +429,22 @@ .RS .TP \fBfiles/modules/grammar_aycock/aycock\&.n\fR grammar::aycock .RE +American Express +.RS +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.RE +AMEX +.RS +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.RE angle .RS .TP \fBfiles/modules/math/math_geometry\&.n\fR math::geometry @@ -1995,10 +609,16 @@ .RS .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list .RE +AST +.RS +.TP +\fBfiles/modules/grammar_me/me_ast\&.n\fR +grammar::me_ast +.RE asynchronous .RS .TP \fBfiles/modules/cache/async\&.n\fR cache::async @@ -2166,10 +786,16 @@ .RS .TP \fBfiles/modules/asn/asn\&.n\fR asn .RE +Bessel functions +.RS +.TP +\fBfiles/modules/math/special\&.n\fR +math::special +.RE bfs .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op @@ -2201,10 +827,16 @@ bipartite .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op +.RE +BitTorrent +.RS +.TP +\fBfiles/modules/bee/bee\&.n\fR +bee .RE bittorrent .RS .TP \fBfiles/modules/bee/bee\&.n\fR @@ -2244,10 +876,16 @@ .RS .TP \fBfiles/modules/blowfish/blowfish\&.n\fR blowfish .RE +Book Number +.RS +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.RE breadth-first .RS .TP \fBfiles/modules/struct/struct_tree\&.n\fR struct::tree @@ -2256,10 +894,43 @@ .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op .RE +BWidget +.RS +.TP +\fBfiles/modules/snit/snit\&.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq\&.n\fR +snitfaq +.RE +C +.RS +.TP +\fBfiles/modules/doctools2idx/idx_msgcat_c\&.n\fR +doctools::msgcat::idx::c +.TP +\fBfiles/modules/doctools2toc/toc_msgcat_c\&.n\fR +doctools::msgcat::toc::c +.RE +C++ +.RS +.TP +\fBfiles/modules/snit/snit\&.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq\&.n\fR +snitfaq +.TP +\fBfiles/modules/stooop/stooop\&.n\fR +stooop +.TP +\fBfiles/modules/stooop/switched\&.n\fR +switched +.RE cache .RS .TP \fBfiles/modules/cache/async\&.n\fR cache::async @@ -2385,10 +1056,28 @@ .RS .TP \fBfiles/modules/asn/asn\&.n\fR asn .RE +CFG +.RS +.TP +\fBfiles/modules/grammar_me/me_intro\&.n\fR +grammar::me_intro +.RE +CFL +.RS +.TP +\fBfiles/modules/grammar_me/me_intro\&.n\fR +grammar::me_intro +.RE +CGI +.RS +.TP +\fBfiles/modules/ncgi/ncgi\&.n\fR +ncgi +.RE cgraph .RS .TP \fBfiles/modules/struct/graph\&.n\fR struct::graph @@ -2517,10 +1206,52 @@ .RS .TP \fBfiles/modules/html/html\&.n\fR html .RE +Checking +.RS +.TP +\fBfiles/modules/valtype/valtype_common\&.n\fR +valtype::common +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.TP +\fBfiles/modules/valtype/luhn\&.n\fR +valtype::luhn +.TP +\fBfiles/modules/valtype/luhn5\&.n\fR +valtype::luhn5 +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.TP +\fBfiles/modules/valtype/verhoeff\&.n\fR +valtype::verhoeff +.RE checksum .RS .TP \fBfiles/modules/crc/cksum\&.n\fR cksum @@ -2607,13 +1338,10 @@ oo::util .RE cleanup .RS .TP -\fBfiles/modules/defer/defer\&.n\fR -defer -.TP \fBfiles/modules/try/tcllib_try\&.n\fR try .RE client .RS @@ -2805,10 +1533,19 @@ math::constants .TP \fBfiles/modules/units/units\&.n\fR units .RE +CONTAINER +.RS +.TP +\fBfiles/modules/pt/pt_peg_export_container\&.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_to_container\&.n\fR +pt::peg::to::container +.RE contents .RS .TP \fBfiles/modules/doctools2toc/toc_introduction\&.n\fR doctools2toc_introduction @@ -2964,13 +1701,10 @@ .RS .TP \fBfiles/modules/control/control\&.n\fR control .TP -\fBfiles/modules/math/changepoint\&.n\fR -math::changepoint -.TP \fBfiles/modules/term/term\&.n\fR term .TP \fBfiles/modules/term/ansi_code\&.n\fR term::ansi::code @@ -3138,10 +1872,16 @@ coroutine::auto .TP \fBfiles/modules/generator/generator\&.n\fR generator .RE +Cost +.RS +.TP +\fBfiles/modules/treeql/treeql\&.n\fR +treeql +.RE counter .RS .TP \fBfiles/modules/virtchannel_transform/vt_counter\&.n\fR tcl::transform::counter @@ -3150,10 +1890,16 @@ .RS .TP \fBfiles/modules/counter/counter\&.n\fR counter .RE +CPARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR +pt::peg::to::cparam +.RE crc .RS .TP \fBfiles/modules/crc/cksum\&.n\fR cksum @@ -3216,10 +1962,16 @@ .RS .TP \fBfiles/modules/blowfish/blowfish\&.n\fR blowfish .RE +CSS +.RS +.TP +\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR +doctools::html::cssdefaults +.RE csv .RS .TP \fBfiles/modules/bench/bench_read\&.n\fR bench::in @@ -3251,10 +2003,16 @@ cut vertex .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op +.RE +CVS +.RS +.TP +\fBfiles/modules/rcs/rcs\&.n\fR +rcs .RE cvs .RS .TP \fBfiles/modules/doctools/cvs\&.n\fR @@ -3378,10 +2136,19 @@ .RS .TP \fBfiles/modules/page/page_util_flow\&.n\fR page_util_flow .RE +DE +.RS +.TP +\fBfiles/modules/doctools2idx/idx_msgcat_de\&.n\fR +doctools::msgcat::idx::de +.TP +\fBfiles/modules/doctools2toc/toc_msgcat_de\&.n\fR +doctools::msgcat::toc::de +.RE debug .RS .TP \fBfiles/modules/debug/debug\&.n\fR debug @@ -3480,10 +2247,22 @@ .RS .TP \fBfiles/modules/asn/asn\&.n\fR asn .RE +DES +.RS +.TP +\fBfiles/modules/des/des\&.n\fR +des +.TP +\fBfiles/modules/des/tcldes\&.n\fR +tclDES +.TP +\fBfiles/modules/des/tcldesjr\&.n\fR +tclDESjr +.RE deserialization .RS .TP \fBfiles/modules/doctools2idx/import_docidx\&.n\fR doctools::idx::import::docidx @@ -3528,22 +2307,10 @@ .RS .TP \fBfiles/modules/rcs/rcs\&.n\fR rcs .RE -diff -ruN -.RS -.TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch -.RE -diff, unified format -.RS -.TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch -.RE difference .RS .TP \fBfiles/modules/struct/struct_set\&.n\fR struct::set @@ -3558,16 +2325,10 @@ .RS .TP \fBfiles/modules/math/calculus\&.n\fR math::calculus .RE -digital -.RS -.TP -\fBfiles/modules/math/filtergen\&.n\fR -math::filters -.RE dijkstra .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op @@ -3585,10 +2346,16 @@ .RS .TP \fBfiles/modules/fileutil/traverse\&.n\fR fileutil_traverse .RE +Discover +.RS +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.RE discrete items .RS .TP \fBfiles/modules/struct/pool\&.n\fR struct::pool @@ -3614,10 +2381,16 @@ \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op .TP \fBfiles/modules/units/units\&.n\fR units +.RE +DNS +.RS +.TP +\fBfiles/modules/dns/tcllib_dns\&.n\fR +dns .RE do .RS .TP \fBfiles/modules/control/control\&.n\fR @@ -4059,10 +2832,16 @@ tcldocstrip .TP \fBfiles/modules/tepam/tepam_doc_gen\&.n\fR tepam::doc_gen .RE +DOM +.RS +.TP +\fBfiles/modules/treeql/treeql\&.n\fR +treeql +.RE dom .RS .TP \fBfiles/modules/amazon-s3/xsxp\&.n\fR xsxp @@ -4077,16 +2856,166 @@ .RS .TP \fBfiles/modules/math/constants\&.n\fR math::constants .RE +EAN +.RS +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.RE +EAN13 +.RS +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.RE earley .RS .TP \fBfiles/modules/grammar_aycock/aycock\&.n\fR grammar::aycock .RE +EBNF +.RS +.TP +\fBfiles/apps/pt\&.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree\&.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR +pt::cparam::configuration::tea +.TP +\fBfiles/modules/pt/pt_json_language\&.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param\&.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression\&.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op\&.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar\&.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container\&.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export\&.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container\&.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json\&.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container\&.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json\&.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import\&.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container\&.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json\&.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp\&.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container\&.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json\&.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param\&.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language\&.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction\&.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen\&.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine\&.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR +pt::tclparam::configuration::nx +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_util\&.n\fR +pt::util +.TP +\fBfiles/modules/pt/pt_to_api\&.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api\&.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction\&.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parse_peg\&.n\fR +pt_parse_peg +.TP +\fBfiles/modules/pt/pt_parser_api\&.n\fR +pt_parser_api +.TP +\fBfiles/modules/pt/pt_peg_op\&.n\fR +pt_peg_op +.RE eccentricity .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op @@ -4134,10 +3063,19 @@ .RS .TP \fBfiles/modules/interp/tcllib_interp\&.n\fR interp .RE +EN +.RS +.TP +\fBfiles/modules/doctools2idx/idx_msgcat_en\&.n\fR +doctools::msgcat::idx::en +.TP +\fBfiles/modules/doctools2toc/toc_msgcat_en\&.n\fR +doctools::msgcat::toc::en +.RE encoding .RS .TP \fBfiles/modules/base64/ascii85\&.n\fR ascii85 @@ -4217,10 +3155,19 @@ error function .RS .TP \fBfiles/modules/math/special\&.n\fR math::special +.RE +European Article Number +.RS +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn .RE event .RS .TP \fBfiles/modules/hook/hook\&.n\fR @@ -4530,10 +3477,16 @@ .RS .TP \fBfiles/modules/uri/uri\&.n\fR uri .RE +FFT +.RS +.TP +\fBfiles/modules/math/fourier\&.n\fR +math::fourier +.RE fifo .RS .TP \fBfiles/modules/virtchannel_base/tcllib_fifo\&.n\fR tcl::chan::fifo @@ -4623,16 +3576,10 @@ generator .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list .RE -filtering -.RS -.TP -\fBfiles/modules/math/filtergen\&.n\fR -math::filters -.RE final .RS .TP \fBfiles/modules/try/tcllib_try\&.n\fR try @@ -4679,13 +3626,28 @@ \fBfiles/modules/grammar_fa/dexec\&.n\fR grammar::fa::dexec .TP \fBfiles/modules/grammar_fa/faop\&.n\fR grammar::fa::op +.RE +FIPS 180-1 +.RS +.TP +\fBfiles/modules/sha1/sha1\&.n\fR +sha1 +.TP +\fBfiles/modules/sha1/sha256\&.n\fR +sha256 .RE first permutation .RS +.TP +\fBfiles/modules/struct/struct_list\&.n\fR +struct::list +.RE +Fisher-Yates +.RS .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list .RE flatten @@ -4833,28 +3795,31 @@ doctoc_plugin_apiref .TP \fBfiles/modules/doctools/doctools_plugin_apiref\&.n\fR doctools_plugin_apiref .RE -fossil +Fourier transform .RS .TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch +\fBfiles/modules/math/fourier\&.n\fR +math::fourier +.RE +FR +.RS +.TP +\fBfiles/modules/doctools2idx/idx_msgcat_fr\&.n\fR +doctools::msgcat::idx::fr +.TP +\fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR +doctools::msgcat::toc::fr .RE frame .RS .TP \fBfiles/modules/term/ansi_cmacros\&.n\fR term::ansi::code::macros .RE -framework -.RS -.TP -\fBfiles/modules/tool/tool\&.n\fR -tool -.RE ftp .RS .TP \fBfiles/modules/ftp/ftp\&.n\fR ftp @@ -4953,31 +3918,19 @@ coroutine .TP \fBfiles/modules/coroutine/coro_auto\&.n\fR coroutine::auto .RE -git -.RS -.TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch -.RE global .RS .TP \fBfiles/modules/coroutine/tcllib_coroutine\&.n\fR coroutine .TP \fBfiles/modules/coroutine/coro_auto\&.n\fR coroutine::auto .RE -golang -.RS -.TP -\fBfiles/modules/defer/defer\&.n\fR -defer -.RE gopher .RS .TP \fBfiles/modules/uri/uri\&.n\fR uri @@ -5213,10 +4166,16 @@ grep .RS .TP \fBfiles/modules/fileutil/fileutil\&.n\fR fileutil +.RE +GUID +.RS +.TP +\fBfiles/modules/uuid/uuid\&.n\fR +uuid .RE hashing .RS .TP \fBfiles/modules/md4/md4\&.n\fR @@ -5286,10 +4245,52 @@ .RS .TP \fBfiles/modules/grammar_aycock/aycock\&.n\fR grammar::aycock .RE +HTML +.RS +.TP +\fBfiles/modules/doctools/doctools\&.n\fR +doctools +.TP +\fBfiles/modules/doctools2base/html_cssdefaults\&.n\fR +doctools::html::cssdefaults +.TP +\fBfiles/modules/doctools2idx/idx_container\&.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx\&.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools2idx/idx_export\&.n\fR +doctools::idx::export +.TP +\fBfiles/modules/doctools2idx/idx_export_html\&.n\fR +doctools::idx::export::html +.TP +\fBfiles/modules/doctools/doctoc\&.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/toc_container\&.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/toc_export\&.n\fR +doctools::toc::export +.TP +\fBfiles/modules/doctools2toc/toc_export_html\&.n\fR +doctools::toc::export::html +.TP +\fBfiles/apps/dtplite\&.n\fR +dtplite +.TP +\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand\&.n\fR +mpexpand +.RE html .RS .TP \fBfiles/modules/html/html\&.n\fR html @@ -5307,13 +4308,10 @@ .RS .TP \fBfiles/modules/http/autoproxy\&.n\fR autoproxy .TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.TP \fBfiles/modules/map/map_geocode_nominatim\&.n\fR map::geocode::nominatim .TP \fBfiles/modules/map/map_slippy_fetcher\&.n\fR map::slippy::fetcher @@ -5322,28 +4320,10 @@ uri .TP \fBfiles/modules/websocket/websocket\&.n\fR websocket .RE -httpd -.RS -.TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.RE -https -.RS -.TP -\fBfiles/modules/uri/uri\&.n\fR -uri -.RE -httpserver -.RS -.TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.RE huddle .RS .TP \fBfiles/modules/yaml/huddle\&.n\fR huddle @@ -5397,10 +4377,16 @@ doctools::msgcat::toc::en .TP \fBfiles/modules/doctools2toc/toc_msgcat_fr\&.n\fR doctools::msgcat::toc::fr .RE +IBAN +.RS +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.RE ident .RS .TP \fBfiles/modules/ident/ident\&.n\fR ident @@ -5439,10 +4425,16 @@ .RS .TP \fBfiles/modules/imap4/imap4\&.n\fR imap4 .RE +IMEI +.RS +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.RE import .RS .TP \fBfiles/modules/doctools2idx/idx_import\&.n\fR doctools::idx::import @@ -5498,10 +4490,19 @@ inclusion .RS .TP \fBfiles/modules/struct/struct_set\&.n\fR struct::set +.RE +Incr Tcl +.RS +.TP +\fBfiles/modules/snit/snit\&.n\fR +snit +.TP +\fBfiles/modules/snit/snitfaq\&.n\fR +snitfaq .RE indenting .RS .TP \fBfiles/modules/textutil/textutil\&.n\fR @@ -5603,10 +4604,37 @@ inter-thread communication .RS .TP \fBfiles/modules/virtchannel_base/tcllib_fifo2\&.n\fR tcl::chan::fifo2 +.RE +International Article Number +.RS +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.RE +International Bank Account Number +.RS +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.RE +International Mobile Equipment Identity +.RS +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.RE +International Standard Book Number +.RS +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn .RE internationalization .RS .TP \fBfiles/modules/doctools2base/tcllib_msgcat\&.n\fR @@ -5790,10 +4818,16 @@ valtype::usnpi .TP \fBfiles/modules/valtype/verhoeff\&.n\fR valtype::verhoeff .RE +ISBN +.RS +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.RE isthmus .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op @@ -5832,10 +4866,37 @@ .RS .TP \fBfiles/modules/jpeg/jpeg\&.n\fR jpeg .RE +JSON +.RS +.TP +\fBfiles/modules/doctools2idx/idx_export_json\&.n\fR +doctools::idx::export::json +.TP +\fBfiles/modules/doctools2idx/idx_import_json\&.n\fR +doctools::idx::import::json +.TP +\fBfiles/modules/doctools2toc/toc_export_json\&.n\fR +doctools::toc::export::json +.TP +\fBfiles/modules/doctools2toc/toc_import_json\&.n\fR +doctools::toc::import::json +.TP +\fBfiles/modules/pt/pt_peg_export_json\&.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_from_json\&.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_import_json\&.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_to_json\&.n\fR +pt::peg::to::json +.RE json .RS .TP \fBfiles/modules/doctools2idx/idx_container\&.n\fR doctools::idx @@ -5937,10 +4998,22 @@ .RS .TP \fBfiles/modules/lambda/lambda\&.n\fR lambda .RE +LaTeX +.RS +.TP +\fBfiles/modules/docstrip/docstrip\&.n\fR +docstrip +.TP +\fBfiles/modules/docstrip/docstrip_util\&.n\fR +docstrip_util +.TP +\fBfiles/apps/tcldocstrip\&.n\fR +tcldocstrip +.RE latex .RS .TP \fBfiles/modules/doctools2idx/idx_container\&.n\fR doctools::idx @@ -6096,10 +5169,151 @@ docstrip_util .TP \fBfiles/apps/tcldocstrip\&.n\fR tcldocstrip .RE +LL(k) +.RS +.TP +\fBfiles/modules/grammar_me/me_intro\&.n\fR +grammar::me_intro +.TP +\fBfiles/modules/grammar_peg/peg\&.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp\&.n\fR +grammar::peg::interp +.TP +\fBfiles/apps/pt\&.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree\&.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR +pt::cparam::configuration::tea +.TP +\fBfiles/modules/pt/pt_json_language\&.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param\&.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression\&.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op\&.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar\&.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container\&.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export\&.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container\&.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json\&.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container\&.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json\&.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import\&.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container\&.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json\&.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp\&.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container\&.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json\&.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param\&.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language\&.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction\&.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen\&.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine\&.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR +pt::tclparam::configuration::nx +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_util\&.n\fR +pt::util +.TP +\fBfiles/modules/pt/pt_to_api\&.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api\&.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction\&.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parse_peg\&.n\fR +pt_parse_peg +.TP +\fBfiles/modules/pt/pt_parser_api\&.n\fR +pt_parser_api +.TP +\fBfiles/modules/pt/pt_peg_op\&.n\fR +pt_peg_op +.RE local searching .RS .TP \fBfiles/modules/struct/graphops\&.n\fR struct::graph::op @@ -6324,22 +5538,10 @@ mapproj .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list .RE -markdown -.RS -.TP -\fBfiles/modules/doctools/doctools\&.n\fR -doctools -.TP -\fBfiles/modules/doctools/docidx\&.n\fR -doctools::idx -.TP -\fBfiles/modules/doctools/doctoc\&.n\fR -doctools::toc -.RE markup .RS .TP \fBfiles/modules/doctools/docidx_intro\&.n\fR docidx_intro @@ -6438,10 +5640,16 @@ mpexpand .TP \fBfiles/apps/tcldocstrip\&.n\fR tcldocstrip .RE +MasterCard +.RS +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.RE matching .RS .TP \fBfiles/modules/grammar_me/me_intro\&.n\fR grammar::me_intro @@ -6618,25 +5826,19 @@ math::linearalgebra .TP \fBfiles/modules/math/optimize\&.n\fR math::optimize .TP -\fBfiles/modules/math/pca\&.n\fR -math::PCA -.TP \fBfiles/modules/math/polynomials\&.n\fR math::polynomials .TP \fBfiles/modules/math/rational_funcs\&.n\fR math::rationalfunctions .TP \fBfiles/modules/math/special\&.n\fR math::special .TP -\fBfiles/modules/math/trig\&.n\fR -math::trig -.TP \fBfiles/modules/simulation/annealing\&.n\fR simulation::annealing .TP \fBfiles/modules/simulation/montecarlo\&.n\fR simulation::montecarlo @@ -6648,16 +5850,10 @@ .RS .TP \fBfiles/modules/math/fourier\&.n\fR math::fourier .TP -\fBfiles/modules/math/probopt\&.n\fR -math::probopt -.TP -\fBfiles/modules/math/quasirandom\&.n\fR -math::quasirandom -.TP \fBfiles/modules/math/statistics\&.n\fR math::statistics .RE matrices .RS @@ -7083,10 +6279,16 @@ debug::heartbeat .TP \fBfiles/modules/debug/debug_timestamp\&.n\fR debug::timestamp .RE +National Provider Identifier +.RS +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.RE neighbour .RS .TP \fBfiles/modules/struct/graph\&.n\fR struct::graph @@ -7203,10 +6405,16 @@ page_util_norm_peg .TP \fBfiles/modules/stringprep/unicode\&.n\fR unicode .RE +NPI +.RS +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.RE nroff .RS .TP \fBfiles/modules/doctools/doctools\&.n\fR doctools @@ -7245,10 +6453,22 @@ dtplite .TP \fBfiles/modules/doctools/mpexpand\&.n\fR mpexpand .RE +NTLM +.RS +.TP +\fBfiles/modules/sasl/ntlm\&.n\fR +SASL::NTLM +.RE +NTP +.RS +.TP +\fBfiles/modules/ntp/ntp_time\&.n\fR +ntp_time +.RE null .RS .TP \fBfiles/modules/virtchannel_base/tcllib_null\&.n\fR tcl::chan::null @@ -7329,22 +6549,10 @@ .RS .TP \fBfiles/modules/virtchannel_transform/vt_otp\&.n\fR tcl::transform::otp .RE -oo -.RS -.TP -\fBfiles/modules/clay/clay\&.n\fR -clay -.RE -optimisation -.RS -.TP -\fBfiles/modules/math/probopt\&.n\fR -math::probopt -.RE optimization .RS .TP \fBfiles/modules/math/optimize\&.n\fR math::optimize @@ -7419,10 +6627,16 @@ textutil .TP \fBfiles/modules/textutil/adjust\&.n\fR textutil::adjust .RE +PARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_param\&.n\fR +pt::peg::to::param +.RE parameter entry form .RS .TP \fBfiles/modules/tepam/tepam_introduction\&.n\fR tepam @@ -7997,20 +7211,158 @@ patch .RS .TP \fBfiles/modules/docstrip/docstrip_util\&.n\fR docstrip_util -.TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch .RE patching .RS .TP \fBfiles/modules/rcs/rcs\&.n\fR rcs .RE +PEG +.RS +.TP +\fBfiles/modules/grammar_me/me_intro\&.n\fR +grammar::me_intro +.TP +\fBfiles/modules/page/page_util_norm_peg\&.n\fR +page_util_norm_peg +.TP +\fBfiles/modules/page/page_util_peg\&.n\fR +page_util_peg +.TP +\fBfiles/apps/pt\&.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree\&.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR +pt::cparam::configuration::tea +.TP +\fBfiles/modules/pt/pt_json_language\&.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param\&.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression\&.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op\&.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar\&.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container\&.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export\&.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container\&.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json\&.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container\&.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json\&.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import\&.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container\&.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json\&.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp\&.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container\&.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json\&.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param\&.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language\&.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction\&.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen\&.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine\&.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR +pt::tclparam::configuration::nx +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_util\&.n\fR +pt::util +.TP +\fBfiles/modules/pt/pt_to_api\&.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api\&.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction\&.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parse_peg\&.n\fR +pt_parse_peg +.TP +\fBfiles/modules/pt/pt_parser_api\&.n\fR +pt_parser_api +.TP +\fBfiles/modules/pt/pt_peg_op\&.n\fR +pt_peg_op +.RE performance .RS .TP \fBfiles/modules/bench/bench\&.n\fR bench @@ -8238,16 +7590,10 @@ .RS .TP \fBfiles/modules/struct/prioqueue\&.n\fR struct::prioqueue .RE -probabilistic calculations -.RS -.TP -\fBfiles/modules/math/probopt\&.n\fR -math::probopt -.RE proc .RS .TP \fBfiles/modules/lambda/lambda\&.n\fR lambda @@ -8481,16 +7827,10 @@ pt_parser_api .TP \fBfiles/modules/pt/pt_peg_op\&.n\fR pt_peg_op .RE -quasi-random -.RS -.TP -\fBfiles/modules/math/quasirandom\&.n\fR -math::quasirandom -.RE queue .RS .TP \fBfiles/modules/csv/csv\&.n\fR csv @@ -8561,10 +7901,22 @@ rc4 .RS .TP \fBfiles/modules/rc4/rc4\&.n\fR rc4 +.RE +RCS +.RS +.TP +\fBfiles/modules/rcs/rcs\&.n\fR +rcs +.RE +RCS patch +.RS +.TP +\fBfiles/modules/rcs/rcs\&.n\fR +rcs .RE read .RS .TP \fBfiles/modules/coroutine/tcllib_coroutine\&.n\fR @@ -9017,10 +8369,58 @@ reverse .RS .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list +.RE +rfc 821 +.RS +.TP +\fBfiles/modules/mime/mime\&.n\fR +mime +.TP +\fBfiles/modules/mime/smtp\&.n\fR +smtp +.TP +\fBfiles/modules/smtpd/smtpd\&.n\fR +smtpd +.RE +rfc 822 +.RS +.TP +\fBfiles/modules/mime/mime\&.n\fR +mime +.TP +\fBfiles/modules/pop3d/pop3d_dbox\&.n\fR +pop3d::dbox +.TP +\fBfiles/modules/mime/smtp\&.n\fR +smtp +.RE +rfc 868 +.RS +.TP +\fBfiles/modules/ntp/ntp_time\&.n\fR +ntp_time +.RE +rfc 959 +.RS +.TP +\fBfiles/modules/ftp/ftp\&.n\fR +ftp +.TP +\fBfiles/modules/ftp/ftp_geturl\&.n\fR +ftp::geturl +.TP +\fBfiles/modules/ftpd/ftpd\&.n\fR +ftpd +.RE +rfc 977 +.RS +.TP +\fBfiles/modules/nntp/nntp\&.n\fR +nntp .RE rfc 1034 .RS .TP \fBfiles/modules/dns/tcllib_dns\&.n\fR @@ -9071,16 +8471,10 @@ rfc 1413 .RS .TP \fBfiles/modules/ident/ident\&.n\fR ident -.RE -rfc 1630 -.RS -.TP -\fBfiles/modules/uri/uri\&.n\fR -uri .RE rfc 1886 .RS .TP \fBfiles/modules/dns/tcllib_dns\&.n\fR @@ -9176,10 +8570,16 @@ rfc 2554 .RS .TP \fBfiles/modules/mime/smtp\&.n\fR smtp +.RE +RFC 2718 +.RS +.TP +\fBfiles/modules/oauth/oauth\&.n\fR +oauth .RE rfc 2821 .RS .TP \fBfiles/modules/mime/smtp\&.n\fR @@ -9203,83 +8603,29 @@ rfc 3513 .RS .TP \fBfiles/modules/dns/tcllib_ip\&.n\fR tcllib_ip -.RE -rfc 3986 -.RS -.TP -\fBfiles/modules/uri/uri\&.n\fR -uri .RE rfc 4511 .RS .TP \fBfiles/modules/ldap/ldap\&.n\fR ldap +.RE +RFC 5849 +.RS +.TP +\fBfiles/modules/oauth/oauth\&.n\fR +oauth .RE rfc 6455 .RS .TP \fBfiles/modules/websocket/websocket\&.n\fR websocket .RE -rfc 7858 -.RS -.TP -\fBfiles/modules/dns/tcllib_dns\&.n\fR -dns -.RE -rfc 821 -.RS -.TP -\fBfiles/modules/mime/mime\&.n\fR -mime -.TP -\fBfiles/modules/mime/smtp\&.n\fR -smtp -.TP -\fBfiles/modules/smtpd/smtpd\&.n\fR -smtpd -.RE -rfc 822 -.RS -.TP -\fBfiles/modules/mime/mime\&.n\fR -mime -.TP -\fBfiles/modules/pop3d/pop3d_dbox\&.n\fR -pop3d::dbox -.TP -\fBfiles/modules/mime/smtp\&.n\fR -smtp -.RE -rfc 868 -.RS -.TP -\fBfiles/modules/ntp/ntp_time\&.n\fR -ntp_time -.RE -rfc 959 -.RS -.TP -\fBfiles/modules/ftp/ftp\&.n\fR -ftp -.TP -\fBfiles/modules/ftp/ftp_geturl\&.n\fR -ftp::geturl -.TP -\fBfiles/modules/ftpd/ftpd\&.n\fR -ftpd -.RE -rfc 977 -.RS -.TP -\fBfiles/modules/nntp/nntp\&.n\fR -nntp -.RE rfc3501 .RS .TP \fBfiles/modules/imap4/imap4\&.n\fR imap4 @@ -9297,10 +8643,19 @@ .RS .TP \fBfiles/modules/struct/struct_list\&.n\fR struct::list .RE +RIPEMD +.RS +.TP +\fBfiles/modules/ripemd/ripemd128\&.n\fR +ripemd128 +.TP +\fBfiles/modules/ripemd/ripemd160\&.n\fR +ripemd160 +.RE roman numeral .RS .TP \fBfiles/modules/math/roman\&.n\fR math::roman @@ -9360,16 +8715,43 @@ .RS .TP \fBfiles/modules/amazon-s3/S3\&.n\fR S3 .RE +SASL +.RS +.TP +\fBfiles/modules/sasl/sasl\&.n\fR +SASL +.TP +\fBfiles/modules/sasl/ntlm\&.n\fR +SASL::NTLM +.TP +\fBfiles/modules/sasl/scram\&.n\fR +SASL::SCRAM +.TP +\fBfiles/modules/sasl/gtoken\&.n\fR +SASL::XGoogleToken +.RE scanl .RS .TP \fBfiles/modules/generator/generator\&.n\fR generator .RE +SCCS +.RS +.TP +\fBfiles/modules/rcs/rcs\&.n\fR +rcs +.RE +SCRAM +.RS +.TP +\fBfiles/modules/sasl/scram\&.n\fR +SASL::SCRAM +.RE secure .RS .TP \fBfiles/modules/comm/comm\&.n\fR comm @@ -9657,13 +9039,10 @@ .RS .TP \fBfiles/modules/ftpd/ftpd\&.n\fR ftpd .TP -\fBfiles/modules/httpd/httpd\&.n\fR -httpd -.TP \fBfiles/modules/smtpd/smtpd\&.n\fR smtpd .RE set .RS @@ -9768,19 +9147,31 @@ .RS .TP \fBfiles/modules/smtpd/smtpd\&.n\fR smtpd .RE +Snit +.RS +.TP +\fBfiles/modules/snit/snit\&.n\fR +snit +.RE snit .RS .TP \fBfiles/modules/interp/deleg_method\&.n\fR deleg_method .TP \fBfiles/modules/interp/tcllib_interp\&.n\fR interp .RE +SNTP +.RS +.TP +\fBfiles/modules/ntp/ntp_time\&.n\fR +ntp_time +.RE socket .RS .TP \fBfiles/modules/comm/comm\&.n\fR comm @@ -10056,16 +9447,10 @@ counter .TP \fBfiles/modules/math/math\&.n\fR math .TP -\fBfiles/modules/math/changepoint\&.n\fR -math::changepoint -.TP -\fBfiles/modules/math/pca\&.n\fR -math::PCA -.TP \fBfiles/modules/math/statistics\&.n\fR math::statistics .RE stdin .RS @@ -10352,13 +9737,22 @@ \fBfiles/modules/math/bignum\&.n\fR math::bignum .TP \fBfiles/modules/math/decimal\&.n\fR math::decimal +.RE +Tcl module +.RS .TP -\fBfiles/modules/math/pca\&.n\fR -math::PCA +\fBfiles/modules/docstrip/docstrip_util\&.n\fR +docstrip_util +.RE +Tcl syntax +.RS +.TP +\fBfiles/modules/doctools2base/tcl_parse\&.n\fR +doctools::tcl::parse .RE tcler's wiki .RS .TP \fBfiles/modules/doctools2idx/idx_container\&.n\fR @@ -10377,10 +9771,169 @@ .RS .TP \fBfiles/modules/csv/csv\&.n\fR csv .RE +TclOO +.RS +.TP +\fBfiles/modules/tool/meta\&.n\fR +oo::util +.TP +\fBfiles/modules/ooutil/ooutil\&.n\fR +oo::util +.TP +\fBfiles/modules/tool/tool\&.n\fR +tool +.TP +\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR +tool::dict_ensemble +.RE +TCLPARAM +.RS +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR +pt::peg::to::tclparam +.RE +TDPL +.RS +.TP +\fBfiles/modules/grammar_peg/peg\&.n\fR +grammar::peg +.TP +\fBfiles/modules/grammar_peg/peg_interp\&.n\fR +grammar::peg::interp +.TP +\fBfiles/apps/pt\&.n\fR +pt +.TP +\fBfiles/modules/pt/pt_astree\&.n\fR +pt::ast +.TP +\fBfiles/modules/pt/pt_cparam_config_critcl\&.n\fR +pt::cparam::configuration::critcl +.TP +\fBfiles/modules/pt/pt_cparam_config_tea\&.n\fR +pt::cparam::configuration::tea +.TP +\fBfiles/modules/pt/pt_json_language\&.n\fR +pt::json_language +.TP +\fBfiles/modules/pt/pt_param\&.n\fR +pt::param +.TP +\fBfiles/modules/pt/pt_pexpression\&.n\fR +pt::pe +.TP +\fBfiles/modules/pt/pt_pexpr_op\&.n\fR +pt::pe::op +.TP +\fBfiles/modules/pt/pt_pegrammar\&.n\fR +pt::peg +.TP +\fBfiles/modules/pt/pt_peg_container\&.n\fR +pt::peg::container +.TP +\fBfiles/modules/pt/pt_peg_container_peg\&.n\fR +pt::peg::container::peg +.TP +\fBfiles/modules/pt/pt_peg_export\&.n\fR +pt::peg::export +.TP +\fBfiles/modules/pt/pt_peg_export_container\&.n\fR +pt::peg::export::container +.TP +\fBfiles/modules/pt/pt_peg_export_json\&.n\fR +pt::peg::export::json +.TP +\fBfiles/modules/pt/pt_peg_export_peg\&.n\fR +pt::peg::export::peg +.TP +\fBfiles/modules/pt/pt_peg_from_container\&.n\fR +pt::peg::from::container +.TP +\fBfiles/modules/pt/pt_peg_from_json\&.n\fR +pt::peg::from::json +.TP +\fBfiles/modules/pt/pt_peg_from_peg\&.n\fR +pt::peg::from::peg +.TP +\fBfiles/modules/pt/pt_peg_import\&.n\fR +pt::peg::import +.TP +\fBfiles/modules/pt/pt_peg_import_container\&.n\fR +pt::peg::import::container +.TP +\fBfiles/modules/pt/pt_peg_import_json\&.n\fR +pt::peg::import::json +.TP +\fBfiles/modules/pt/pt_peg_import_peg\&.n\fR +pt::peg::import::peg +.TP +\fBfiles/modules/pt/pt_peg_interp\&.n\fR +pt::peg::interp +.TP +\fBfiles/modules/pt/pt_peg_to_container\&.n\fR +pt::peg::to::container +.TP +\fBfiles/modules/pt/pt_peg_to_cparam\&.n\fR +pt::peg::to::cparam +.TP +\fBfiles/modules/pt/pt_peg_to_json\&.n\fR +pt::peg::to::json +.TP +\fBfiles/modules/pt/pt_peg_to_param\&.n\fR +pt::peg::to::param +.TP +\fBfiles/modules/pt/pt_peg_to_peg\&.n\fR +pt::peg::to::peg +.TP +\fBfiles/modules/pt/pt_peg_to_tclparam\&.n\fR +pt::peg::to::tclparam +.TP +\fBfiles/modules/pt/pt_peg_language\&.n\fR +pt::peg_language +.TP +\fBfiles/modules/pt/pt_peg_introduction\&.n\fR +pt::pegrammar +.TP +\fBfiles/modules/pt/pt_pgen\&.n\fR +pt::pgen +.TP +\fBfiles/modules/pt/pt_rdengine\&.n\fR +pt::rde +.TP +\fBfiles/modules/pt/pt_tclparam_config_nx\&.n\fR +pt::tclparam::configuration::nx +.TP +\fBfiles/modules/pt/pt_tclparam_config_snit\&.n\fR +pt::tclparam::configuration::snit +.TP +\fBfiles/modules/pt/pt_tclparam_config_tcloo\&.n\fR +pt::tclparam::configuration::tcloo +.TP +\fBfiles/modules/pt/pt_util\&.n\fR +pt::util +.TP +\fBfiles/modules/pt/pt_to_api\&.n\fR +pt_export_api +.TP +\fBfiles/modules/pt/pt_from_api\&.n\fR +pt_import_api +.TP +\fBfiles/modules/pt/pt_introduction\&.n\fR +pt_introduction +.TP +\fBfiles/modules/pt/pt_parse_peg\&.n\fR +pt_parse_peg +.TP +\fBfiles/modules/pt/pt_parser_api\&.n\fR +pt_parser_api +.TP +\fBfiles/modules/pt/pt_peg_op\&.n\fR +pt_peg_op +.RE temp file .RS .TP \fBfiles/modules/fileutil/fileutil\&.n\fR fileutil @@ -10434,10 +9987,52 @@ .RS .TP \fBfiles/modules/fileutil/fileutil\&.n\fR fileutil .RE +Testing +.RS +.TP +\fBfiles/modules/valtype/valtype_common\&.n\fR +valtype::common +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.TP +\fBfiles/modules/valtype/luhn\&.n\fR +valtype::luhn +.TP +\fBfiles/modules/valtype/luhn5\&.n\fR +valtype::luhn5 +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.TP +\fBfiles/modules/valtype/verhoeff\&.n\fR +valtype::verhoeff +.RE testing .RS .TP \fBfiles/modules/bench/bench\&.n\fR bench @@ -10458,10 +10053,19 @@ bench_lang_intro .TP \fBfiles/modules/bench/bench_lang_spec\&.n\fR bench_lang_spec .RE +TeX +.RS +.TP +\fBfiles/modules/textutil/textutil\&.n\fR +textutil +.TP +\fBfiles/modules/textutil/adjust\&.n\fR +textutil::adjust +.RE text .RS .TP \fBfiles/modules/bench/bench_read\&.n\fR bench::in @@ -10737,10 +10341,16 @@ .RS .TP \fBfiles/modules/virtchannel_transform/vt_base64\&.n\fR tcl::transform::base64 .RE +Tk +.RS +.TP +\fBfiles/modules/virtchannel_base/textwindow\&.n\fR +tcl::chan::textwindow +.RE tls .RS .TP \fBfiles/modules/comm/comm\&.n\fR comm @@ -10764,10 +10374,37 @@ transfer::receiver .TP \fBfiles/modules/transfer/transmitter\&.n\fR transfer::transmitter .RE +TMML +.RS +.TP +\fBfiles/modules/doctools/doctools\&.n\fR +doctools +.TP +\fBfiles/modules/doctools2idx/idx_container\&.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/docidx\&.n\fR +doctools::idx +.TP +\fBfiles/modules/doctools/doctoc\&.n\fR +doctools::toc +.TP +\fBfiles/modules/doctools2toc/toc_container\&.n\fR +doctools::toc +.TP +\fBfiles/apps/dtplite\&.n\fR +dtplite +.TP +\fBfiles/modules/dtplite/pkg_dtplite\&.n\fR +dtplite +.TP +\fBfiles/modules/doctools/mpexpand\&.n\fR +mpexpand +.RE toc .RS .TP \fBfiles/modules/doctools/doctoc_intro\&.n\fR doctoc_intro @@ -10815,10 +10452,19 @@ string::token .TP \fBfiles/modules/string/token_shell\&.n\fR string::token::shell .RE +TOOL +.RS +.TP +\fBfiles/modules/tool/tool\&.n\fR +tool +.TP +\fBfiles/modules/tool/tool_dict_ensemble\&.n\fR +tool::dict_ensemble +.RE top-down parsing languages .RS .TP \fBfiles/modules/grammar_me/me_intro\&.n\fR grammar::me_intro @@ -10968,10 +10614,16 @@ .RS .TP \fBfiles/modules/fileutil/fileutil\&.n\fR fileutil .RE +TPDL +.RS +.TP +\fBfiles/modules/grammar_me/me_intro\&.n\fR +grammar::me_intro +.RE trace .RS .TP \fBfiles/modules/debug/debug\&.n\fR debug @@ -11268,15 +10920,15 @@ page_util_norm_lemon .TP \fBfiles/modules/page/page_util_norm_peg\&.n\fR page_util_norm_peg .RE -trigonometry +TreeQL .RS .TP -\fBfiles/modules/math/trig\&.n\fR -math::trig +\fBfiles/modules/treeql/treeql\&.n\fR +treeql .RE trimming .RS .TP \fBfiles/modules/textutil/textutil\&.n\fR @@ -11310,10 +10962,52 @@ fileutil::magic::rt .TP \fBfiles/modules/snit/snit\&.n\fR snit .RE +Type checking +.RS +.TP +\fBfiles/modules/valtype/valtype_common\&.n\fR +valtype::common +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.TP +\fBfiles/modules/valtype/luhn\&.n\fR +valtype::luhn +.TP +\fBfiles/modules/valtype/luhn5\&.n\fR +valtype::luhn5 +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.TP +\fBfiles/modules/valtype/verhoeff\&.n\fR +valtype::verhoeff +.RE uevent .RS .TP \fBfiles/modules/hook/hook\&.n\fR hook @@ -11349,16 +11043,10 @@ unicode .TP \fBfiles/modules/stringprep/unicode_data\&.n\fR unicode::data .RE -unified format diff -.RS -.TP -\fBfiles/modules/textutil/patch\&.n\fR -textutil::patch -.RE union .RS .TP \fBfiles/modules/struct/disjointset\&.n\fR struct::disjointset @@ -11439,10 +11127,16 @@ .RS .TP \fBfiles/modules/uri/urn-scheme\&.n\fR uri_urn .RE +US-NPI +.RS +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.RE utilities .RS .TP \fBfiles/modules/namespacex/namespacex\&.n\fR namespacex @@ -11451,10 +11145,100 @@ .RS .TP \fBfiles/modules/base64/uuencode\&.n\fR uuencode .RE +UUID +.RS +.TP +\fBfiles/modules/uuid/uuid\&.n\fR +uuid +.RE +Validation +.RS +.TP +\fBfiles/modules/valtype/valtype_common\&.n\fR +valtype::common +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.TP +\fBfiles/modules/valtype/luhn\&.n\fR +valtype::luhn +.TP +\fBfiles/modules/valtype/luhn5\&.n\fR +valtype::luhn5 +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.TP +\fBfiles/modules/valtype/verhoeff\&.n\fR +valtype::verhoeff +.RE +Value checking +.RS +.TP +\fBfiles/modules/valtype/valtype_common\&.n\fR +valtype::common +.TP +\fBfiles/modules/valtype/cc_amex\&.n\fR +valtype::creditcard::amex +.TP +\fBfiles/modules/valtype/cc_discover\&.n\fR +valtype::creditcard::discover +.TP +\fBfiles/modules/valtype/cc_mastercard\&.n\fR +valtype::creditcard::mastercard +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.TP +\fBfiles/modules/valtype/ean13\&.n\fR +valtype::gs1::ean13 +.TP +\fBfiles/modules/valtype/iban\&.n\fR +valtype::iban +.TP +\fBfiles/modules/valtype/imei\&.n\fR +valtype::imei +.TP +\fBfiles/modules/valtype/isbn\&.n\fR +valtype::isbn +.TP +\fBfiles/modules/valtype/luhn\&.n\fR +valtype::luhn +.TP +\fBfiles/modules/valtype/luhn5\&.n\fR +valtype::luhn5 +.TP +\fBfiles/modules/valtype/usnpi\&.n\fR +valtype::usnpi +.TP +\fBfiles/modules/valtype/verhoeff\&.n\fR +valtype::verhoeff +.RE vectors .RS .TP \fBfiles/modules/math/linalg\&.n\fR math::linearalgebra @@ -11598,10 +11382,16 @@ grammar::peg::interp .TP \fBfiles/modules/pt/pt_param\&.n\fR pt::param .RE +VISA +.RS +.TP +\fBfiles/modules/valtype/cc_visa\&.n\fR +valtype::creditcard::visa +.RE vwait .RS .TP \fBfiles/modules/coroutine/tcllib_coroutine\&.n\fR coroutine @@ -11694,10 +11484,16 @@ .RS .TP \fBfiles/modules/ldap/ldap\&.n\fR ldap .RE +XGoogleToken +.RS +.TP +\fBfiles/modules/sasl/gtoken\&.n\fR +SASL::XGoogleToken +.RE xml .RS .TP \fBfiles/modules/amazon-s3/xsxp\&.n\fR xsxp @@ -11706,15 +11502,21 @@ .RS .TP \fBfiles/modules/virtchannel_transform/vt_otp\&.n\fR tcl::transform::otp .RE -yEnc +XPath +.RS +.TP +\fBfiles/modules/treeql/treeql\&.n\fR +treeql +.RE +XSLT .RS .TP -\fBfiles/modules/base64/yencode\&.n\fR -yencode +\fBfiles/modules/treeql/treeql\&.n\fR +treeql .RE yaml .RS .TP \fBfiles/modules/yaml/huddle\&.n\fR @@ -11723,10 +11525,16 @@ \fBfiles/modules/yaml/yaml\&.n\fR yaml .RE ydecode .RS +.TP +\fBfiles/modules/base64/yencode\&.n\fR +yencode +.RE +yEnc +.RS .TP \fBfiles/modules/base64/yencode\&.n\fR yencode .RE yencode @@ -11771,7 +11579,6 @@ \fBfiles/modules/map/map_slippy_cache\&.n\fR map::slippy::cache .TP \fBfiles/modules/map/map_slippy_fetcher\&.n\fR map::slippy::fetcher -.RE .RE Index: idoc/man/toc.n ================================================================== --- idoc/man/toc.n +++ idoc/man/toc.n @@ -331,18 +331,15 @@ \fIfiles/modules/cache/async\&.n\fR: Asynchronous in-memory cache .TP \fBcksum\fR \fIfiles/modules/crc/cksum\&.n\fR: Calculate a cksum(1) compatible checksum .TP -\fBclay\fR -\fIfiles/modules/clay/clay\&.n\fR: A minimalist framework for large scale OO Projects -.TP \fBclock_iso8601\fR \fIfiles/modules/clock/iso8601\&.n\fR: Parsing ISO 8601 dates/times .TP \fBclock_rfc2822\fR -\fIfiles/modules/clock/rfc2822\&.n\fR: Parsing RFC 2822 dates/times +\fIfiles/modules/clock/rfc2822\&.n\fR: Parsing ISO 8601 dates/times .TP \fBcmdline\fR \fIfiles/modules/cmdline/cmdline\&.n\fR: Procedures to process command lines and options\&. .TP \fBcomm\fR @@ -385,13 +382,10 @@ \fIfiles/modules/debug/debug_heartbeat\&.n\fR: debug narrative - heartbeat .TP \fBdebug::timestamp\fR \fIfiles/modules/debug/debug_timestamp\&.n\fR: debug narrative - timestamping .TP -\fBdefer\fR -\fIfiles/modules/defer/defer\&.n\fR: Defered execution -.TP \fBdeleg_method\fR \fIfiles/modules/interp/deleg_method\&.n\fR: Creation of comm delegates (snit methods) .TP \fBdeleg_proc\fR \fIfiles/modules/interp/deleg_proc\&.n\fR: Creation of comm delegates (procedures) @@ -625,13 +619,10 @@ \fIfiles/modules/fileutil/multi\&.n\fR: Multi-file operation, scatter/gather, standard object .TP \fBfileutil::multi::op\fR \fIfiles/modules/fileutil/multiop\&.n\fR: Multi-file operation, scatter/gather .TP -\fBfileutil::paths\fR -\fIfiles/modules/fileutil/paths\&.n\fR: Manage search path pools -.TP \fBfileutil_traverse\fR \fIfiles/modules/fileutil/traverse\&.n\fR: Iterative directory traversal .TP \fBftp\fR \fIfiles/modules/ftp/ftp\&.n\fR: Client-side tcl implementation of the ftp protocol @@ -700,13 +691,10 @@ \fIfiles/modules/html/html\&.n\fR: Procedures to generate HTML structures .TP \fBhtmlparse\fR \fIfiles/modules/htmlparse/htmlparse\&.n\fR: Procedures to parse HTML strings .TP -\fBhttpd\fR -\fIfiles/modules/httpd/httpd\&.n\fR: A TclOO and coroutine based web server -.TP \fBhuddle\fR \fIfiles/modules/yaml/huddle\&.n\fR: Create and manipulate huddle object .TP \fBident\fR \fIfiles/modules/ident/ident\&.n\fR: Ident protocol client @@ -736,13 +724,10 @@ \fIfiles/modules/json/json_write\&.n\fR: JSON generation .TP \fBlambda\fR \fIfiles/modules/lambda/lambda\&.n\fR: Utility commands for anonymous procedures .TP -\fBlazyset\fR -\fIfiles/modules/lazyset/lazyset\&.n\fR: Lazy evaluation -.TP \fBldap\fR \fIfiles/modules/ldap/ldap\&.n\fR: LDAP client .TP \fBldapx\fR \fIfiles/modules/ldap/ldapx\&.n\fR: LDAP extended object interface @@ -793,13 +778,10 @@ \fIfiles/modules/math/romberg\&.n\fR: Romberg integration .TP \fBmath::calculus::symdiff\fR \fIfiles/modules/math/symdiff\&.n\fR: Symbolic differentiation for Tcl .TP -\fBmath::changepoint\fR -\fIfiles/modules/math/changepoint\&.n\fR: Change point detection methods -.TP \fBmath::combinatorics\fR \fIfiles/modules/math/combinatorics\&.n\fR: Combinatorial functions in the Tcl Math Library .TP \fBmath::complexnumbers\fR \fIfiles/modules/math/qcomplex\&.n\fR: Straightforward complex number package @@ -811,13 +793,10 @@ \fIfiles/modules/math/decimal\&.n\fR: General decimal arithmetic .TP \fBmath::exact\fR \fIfiles/modules/math/exact\&.n\fR: Exact Real Arithmetic .TP -\fBmath::filters\fR -\fIfiles/modules/math/filtergen\&.n\fR: Digital filters -.TP \fBmath::fourier\fR \fIfiles/modules/math/fourier\&.n\fR: Discrete and fast fourier transforms .TP \fBmath::fuzzy\fR \fIfiles/modules/math/fuzzy\&.n\fR: Fuzzy comparison of floating-point numbers @@ -829,31 +808,19 @@ \fIfiles/modules/math/interpolate\&.n\fR: Interpolation routines .TP \fBmath::linearalgebra\fR \fIfiles/modules/math/linalg\&.n\fR: Linear Algebra .TP -\fBmath::machineparameters\fR -\fIfiles/modules/math/machineparameters\&.n\fR: Compute double precision machine parameters\&. -.TP \fBmath::numtheory\fR \fIfiles/modules/math/numtheory\&.n\fR: Number Theory .TP \fBmath::optimize\fR \fIfiles/modules/math/optimize\&.n\fR: Optimisation routines .TP -\fBmath::PCA\fR -\fIfiles/modules/math/pca\&.n\fR: Package for Principal Component Analysis -.TP \fBmath::polynomials\fR \fIfiles/modules/math/polynomials\&.n\fR: Polynomial functions .TP -\fBmath::probopt\fR -\fIfiles/modules/math/probopt\&.n\fR: Probabilistic optimisation methods -.TP -\fBmath::quasirandom\fR -\fIfiles/modules/math/quasirandom\&.n\fR: Quasi-random points for integration and Monte Carlo type methods -.TP \fBmath::rationalfunctions\fR \fIfiles/modules/math/rational_funcs\&.n\fR: Polynomial functions .TP \fBmath::roman\fR \fIfiles/modules/math/roman\&.n\fR: Tools for creating and manipulating roman numerals @@ -862,13 +829,10 @@ \fIfiles/modules/math/special\&.n\fR: Special mathematical functions .TP \fBmath::statistics\fR \fIfiles/modules/math/statistics\&.n\fR: Basic statistical functions and procedures .TP -\fBmath::trig\fR -\fIfiles/modules/math/trig\&.n\fR: Trigonometric anf hyperbolic functions -.TP \fBmd4\fR \fIfiles/modules/md4/md4\&.n\fR: MD4 Message-Digest Algorithm .TP \fBmd5\fR \fIfiles/modules/md5/md5\&.n\fR: MD5 Message-Digest Algorithm @@ -937,13 +901,10 @@ \fIfiles/modules/tool/meta\&.n\fR: Utility commands for TclOO .TP \fBoo::util\fR \fIfiles/modules/ooutil/ooutil\&.n\fR: Utility commands for TclOO .TP -\fBoometa\fR -\fIfiles/modules/oometa/oometa\&.n\fR: oo::meta A data registry for classess -.TP \fBotp\fR \fIfiles/modules/otp/otp\&.n\fR: One-Time Passwords .TP \fBpage\fR \fIfiles/apps/page\&.n\fR: Parser Generator @@ -1222,13 +1183,10 @@ \fIfiles/modules/struct/graph1\&.n\fR: Create and manipulate directed graph objects .TP \fBstruct::list\fR \fIfiles/modules/struct/struct_list\&.n\fR: Procedures for manipulating lists .TP -\fBstruct::map\fR -\fIfiles/modules/struct/struct_map\&.n\fR: Manage key/value maps -.TP \fBstruct::matrix\fR \fIfiles/modules/struct/matrix\&.n\fR: Create and manipulate matrix objects .TP \fBstruct::matrix_v1\fR \fIfiles/modules/struct/matrix1\&.n\fR: Create and manipulate matrix objects @@ -1357,39 +1315,24 @@ \fIfiles/modules/virtchannel_transform/spacer\&.n\fR: Space insertation and removal .TP \fBtcl::transform::zlib\fR \fIfiles/modules/virtchannel_transform/tcllib_zlib\&.n\fR: zlib (de)compression .TP -\fBtcl_community_communication\fR -\fIfiles/devdoc/tcl_community_communication\&.n\fR: Tcl Community - Kind Communication -.TP \fBtclDES\fR \fIfiles/modules/des/tcldes\&.n\fR: Implementation of the DES and triple-DES ciphers .TP \fBtclDESjr\fR \fIfiles/modules/des/tcldesjr\&.n\fR: Implementation of the DES and triple-DES ciphers .TP \fBtcldocstrip\fR \fIfiles/apps/tcldocstrip\&.n\fR: Tcl-based Docstrip Processor .TP -\fBtcllib_devguide\fR -\fIfiles/devdoc/tcllib_devguide\&.n\fR: Tcllib - The Developer's Guide -.TP -\fBtcllib_install_guide\fR -\fIfiles/devdoc/tcllib_installer\&.n\fR: Tcllib - The Installer's Guide -.TP \fBtcllib_ip\fR \fIfiles/modules/dns/tcllib_ip\&.n\fR: IPv4 and IPv6 address manipulation .TP -\fBtcllib_license\fR -\fIfiles/devdoc/tcllib_license\&.n\fR: Tcllib - License -.TP -\fBtcllib_releasemgr\fR -\fIfiles/devdoc/tcllib_releasemgr\&.n\fR: Tcllib - The Release Manager's Guide -.TP -\fBtcllib_sources\fR -\fIfiles/devdoc/tcllib_sources\&.n\fR: Tcllib - How To Get The Sources +\fBtclrep/machineparameters\fR +\fIfiles/modules/math/machineparameters\&.n\fR: Compute double precision machine parameters\&. .TP \fBtepam\fR \fIfiles/modules/tepam/tepam_introduction\&.n\fR: An introduction into TEPAM, Tcl's Enhanced Procedure and Argument Manager .TP \fBtepam::argument_dialogbox\fR @@ -1444,13 +1387,10 @@ \fIfiles/modules/textutil/adjust\&.n\fR: Procedures to adjust, indent, and undent paragraphs .TP \fBtextutil::expander\fR \fIfiles/modules/textutil/expander\&.n\fR: Procedures to process templates and expand text\&. .TP -\fBtextutil::patch\fR -\fIfiles/modules/textutil/patch\&.n\fR: Application of uni-diff patches to directory trees -.TP \fBtextutil::repeat\fR \fIfiles/modules/textutil/repeat\&.n\fR: Procedures to repeat strings\&. .TP \fBtextutil::split\fR \fIfiles/modules/textutil/textutil_split\&.n\fR: Procedures to split texts @@ -1475,11 +1415,11 @@ .TP \fBtiff\fR \fIfiles/modules/tiff/tiff\&.n\fR: TIFF reading, writing, and querying and manipulation of meta data .TP \fBtool\fR -\fIfiles/modules/tool/tool\&.n\fR: TclOO Library (TOOL) Framework +\fIfiles/modules/tool/tool\&.n\fR: Dictionary Tools .TP \fBtool::dict_ensemble\fR \fIfiles/modules/tool/tool_dict_ensemble\&.n\fR: Dictionary Tools .TP \fBtransfer::connect\fR Index: idoc/www/index.html ================================================================== --- idoc/www/index.html +++ idoc/www/index.html @@ -1,4420 +1,4310 @@ - - - Keyword Index
[ Tcllib Home -| Table Of Contents -| Categories -| Modules -| Applications - ]
-

Keyword Index

-
- 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +| Table Of Contents +| Categories +| Modules +| Applications + ]
+

Keyword Index

+
+ . · / · 3 · A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z +
+
-Keywords: 3 -
3DES - des · tclDES · tclDESjr -
-Keywords: A -
abstract syntax tree - grammar::me::util · grammar::me_ast -
acceptance - grammar::fa::dacceptor -
acceptor - grammar::fa::dacceptor -
active - transfer::connect -
adaptors - snit · snitfaq -
adjacency list - struct::graph::op -
adjacency matrix - struct::graph::op -
adjacent - struct::graph · struct::graph::op -
adjusting - textutil::adjust -
adler32 - tcl::transform::adler32 -
aes - aes -
after - coroutine · coroutine::auto -
alias - interp -
amazon - S3 -
ambiguous - grammar::aycock -
American Express - valtype::creditcard::amex -
AMEX - valtype::creditcard::amex -
angle - math::geometry · units -
anonymous procedure - lambda -
ansi - term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix -
appender - logger::appender · logger::utils -
application - nns · nnsd · nnslog -
approximation algorithm - struct::graph::op -
arc - struct::graph · struct::graph::op -
arcfour - rc4 -
archive - tar -
argument integrity - tepam · tepam::procedure -
argument processing - cmdline -
argument validation - tepam · tepam::procedure -
arguments - tepam · tepam::procedure -
argv - cmdline -
argv0 - cmdline -
array - tie · tie -
articulation point - struct::graph::op -
ascii85 - ascii85 -
asn - asn -
assembler - grammar::me::cpu::gasm -
assert - control -
assign - struct::list -
AST - grammar::me_ast -
asynchronous - cache::async -
attribute control - term::ansi::code::attr · term::ansi::code::ctrl -
augmenting network - struct::graph::op -
augmenting path - struct::graph::op -
authentication - autoproxy · SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken -
automatic - nameserv::auto -
automatic documentation - tepam::doc_gen -
automaton - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op -
aycock - grammar::aycock -
-Keywords: B -
bank - valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban -
base32 - base32 · base32::core · base32::hex -
base64 - base64 · tcl::transform::base64 -
bash - string::token::shell -
bee - bee -
bench language - bench_intro · bench_lang_intro · bench_lang_spec -
benchmark - bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec -
ber - asn -
Bessel functions - math::special -
bfs - struct::graph::op -
bibliography - bibtex -
bibtex - bibtex -
bignums - math::bignum -
bind - uevent -
bipartite - struct::graph::op -
BitTorrent - bee -
bittorrent - bee -
blanks - textutil::repeat -
block cipher - aes · blowfish · des · tclDES · tclDESjr -
blocking flow - struct::graph::op -
blowfish - blowfish -
Book Number - valtype::isbn -
breadth-first - struct::tree -
bridge - struct::graph::op -
BWidget - snit · snitfaq -
-Keywords: C -
C - doctools::msgcat::idx::c · doctools::msgcat::toc::c -
C++ - snit · snitfaq · stooop · switched -
cache - cache::async · map::slippy::cache -
caesar cipher - tcl::transform::rot -
calculus - math::calculus -
callback - cache::async · hook · lambda · oo::util · oo::util · uevent::onidle -
callbacks - tcl::chan::halfpipe -
capitalize - textutil::string -
card for credit - valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa -
cardinality - struct::set -
cat - fileutil -
catalog package - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
catalogue - docstrip_util -
cell-phone - valtype::imei -
cer - asn -
CFG - grammar::me_intro -
CFL - grammar::me_intro -
CGI - ncgi -
cgraph - struct::graph · struct::graph_v1 -
changelog - doctools::changelog · doctools::cvs -
channel - coroutine · coroutine::auto · transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter -
channel transformation - tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib -
character input - term::receive · term::receive::bind -
character output - term::ansi::send · term::send -
chat - irc · multiplexer · picoirc -
checkbox - html · javascript -
checkbutton - html -
Checking - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
checksum - cksum · crc16 · crc32 · sum · tcl::transform::adler32 · tcl::transform::crc32 -
chop - textutil::string -
cipher - pki · tcl::transform::otp · tcl::transform::rot -
cksum - cksum · crc16 · crc32 · sum -
class - snit · snitfaq · stooop · switched -
class methods - oo::util · oo::util -
class variables - oo::util · oo::util -
cleanup - defer · try -
client - nameserv · nameserv::auto · nameserv::common · nns · nns_intro · nnslog -
cloud - S3 -
cmdline processing - cmdline -
color control - term::ansi::code::attr · term::ansi::code::ctrl -
columns - term::ansi::ctrl::unix -
comm - comm · comm_wire · deleg_method · deleg_proc · nameserv::protocol -
command - doctools::tcl::parse -
command line processing - cmdline -
command prefix - lambda · oo::util · oo::util -
comment - jpeg · png -
common - struct::list -
common prefix - textutil::string -
communication - comm · comm_wire -
comparison - struct::list -
complete graph - struct::graph::op -
complex numbers - math::complexnumbers · math::fourier -
compression - tcl::transform::zlib · zipfile::encode -
computations - math::bigfloat -
concatenation channel - tcl::chan::cat · tcl::chan::facade -
connected component - struct::graph::op -
connected fifos - tcl::chan::fifo2 -
connection - transfer::connect -
constants - math::constants · units -
CONTAINER - pt::peg::export::container · pt::peg::to::container -
contents - doctools2toc_introduction -
context-free grammar - grammar::me_intro -
context-free languages - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
control - control · math::changepoint · term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send -
control structure - generator -
conversion - doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · dtplite · dtplite · math::roman · mpexpand · pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · tcldocstrip · units -
cooked - term::ansi::ctrl::unix -
cookie - ncgi -
copy - fileutil::multi · fileutil::multi::op · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter -
coroutine - coroutine · coroutine::auto · generator -
Cost - treeql -
counter - tcl::transform::counter -
counting - counter -
CPARAM - pt::peg::to::cparam -
crc - cksum · crc16 · crc32 · sum -
crc16 - crc16 -
crc32 - cksum · crc16 · crc32 · sum · tcl::transform::crc32 -
credit card - valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa -
cron - cron -
cryptography - blowfish -
CSS - doctools::html::cssdefaults -
csv - bench::in · bench::out::csv · csv -
currying - lambda · oo::util · oo::util -
cut edge - struct::graph::op -
cut vertex - struct::graph::op -
CVS - rcs -
cvs - doctools::cvs -
cvs log - doctools::cvs -
cyclic redundancy check - cksum · crc16 · crc32 · sum -
-Keywords: D -
data analysis - math::statistics -
data destination - transfer::data::destination · transfer::receiver -
data entry form - tepam::argument_dialogbox -
data exchange - huddle · json · json::write · yaml -
data integrity - aes · cksum · crc16 · crc32 · des · pki · rc4 · sum · tclDES · tclDESjr -
data source - transfer::data::source · transfer::transmitter -
data structures - struct::record -
database - tie · tie -
dataflow - page_util_flow -
.ddt - docstrip_util -
DE - doctools::msgcat::idx::de · doctools::msgcat::toc::de -
debug - debug · debug::caller · debug::heartbeat · debug::timestamp -
decimal - math::decimal -
declare - term::ansi::code -
decompression - tcl::transform::zlib · zipfile::decode · zipfile::mkzip -
decryption - tcl::transform::otp · tcl::transform::rot -
deferal - uevent::onidle -
define - term::ansi::code -
degree - struct::graph · struct::graph::op -
degree constrained spanning tree - struct::graph::op -
degrees - math::constants -
delegation - deleg_method · deleg_proc -
depth-first - struct::tree -
der - asn -
DES - des · tclDES · tclDESjr -
deserialization - doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::structure · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::structure -
/dev/null - tcl::chan::null · tcl::chan::nullzero -
/dev/random - tcl::chan::random · tcl::randomseed -
/dev/zero - tcl::chan::nullzero · tcl::chan::zero -
diameter - struct::graph::op -
dict - dicttool -
diff - docstrip_util · struct::list -
diff -n format - rcs -
diff -ruN - textutil::patch -
diff, unified format - textutil::patch -
difference - struct::set -
differential - struct::list -
differential equations - math::calculus -
digital - math::filters -
dijkstra - struct::graph::op -
directory access - ldap · ldapx -
directory traversal - fileutil_traverse -
Discover - valtype::creditcard::discover -
discrete items - struct::pool -
disjoint set - struct::disjointset -
dispatcher - term::receive::bind -
distance - math::geometry · struct::graph::op · units -
DNS - dns -
do - control -
docidx - doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · dtplite · dtplite -
docidx commands - docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax -
docidx language - docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax -
docidx markup - docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · doctools::idx -
docidx syntax - docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax -
docstrip - docstrip · docstrip_util · tcldocstrip -
doctoc - doctools::msgcat · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite -
doctoc commands - doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax -
doctoc language - doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax -
doctoc markup - doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctools::toc -
doctoc syntax - doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax -
doctools - docstrip_util · doctools::changelog · doctools::html::cssdefaults · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::nroff::man_macros · doctools::tcl::parse · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite -
doctools commands - doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax -
doctools language - doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax -
doctools markup - doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax -
doctools syntax - doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax -
document - doctools_plugin_apiref -
documentation - docstrip · docstrip_util · doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · tcldocstrip · tepam::doc_gen -
DOM - treeql -
dom - xsxp -
domain name service - dns -
.dtx - docstrip · docstrip_util · tcldocstrip -
-Keywords: E -
e - math::constants -
EAN - valtype::gs1::ean13 · valtype::isbn -
EAN13 - valtype::gs1::ean13 · valtype::isbn -
earley - grammar::aycock -
EBNF - pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
eccentricity - struct::graph::op -
edge - struct::graph · struct::graph::op -
emacs - doctools::changelog · doctools::cvs -
email - imap4 · mime · pop3 · smtp -
emptiness - struct::set -
empty interpreter - interp -
EN - doctools::msgcat::idx::en · doctools::msgcat::toc::en -
encoding - ascii85 · base64 · uuencode · yencode -
encryption - aes · blowfish · des · pki · rc4 · tcl::transform::otp · tcl::transform::rot · tclDES · tclDESjr -
entry mask - tepam -
equal - struct::list -
equality - struct::list -
equivalence class - struct::disjointset -
error - throw · try -
error function - math::special -
European Article Number - valtype::gs1::ean13 · valtype::isbn -
event - hook · uevent · uevent::onidle -
event management - tcl::chan::events -
events - coroutine · coroutine::auto -
examples - bench_lang_intro · docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq -
exception - try -
exchange format - huddle · json · json::write -
exclusion - struct::set -
execution - grammar::fa::dexec -
exif - jpeg -
exit - coroutine · coroutine::auto -
export - doctools::html::cssdefaults · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::nroff::man_macros · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg -
expression - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
extended namespace - namespacex -
-Keywords: F -
faq - docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq -
fetching information - uri -
FFT - math::fourier -
fifo - tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe -
file - tie · tie · uri -
file recognition - fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt -
file type - fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt -
file utilities - fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · fileutil::multi · fileutil::multi::op -
filesystem - map::slippy::cache -
filter - generator · struct::list -
filtering - math::filters -
final - try -
finance - valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban -
find - struct::disjointset -
finite - struct::pool -
finite automaton - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op -
FIPS 180-1 - sha1 · sha256 -
first permutation - struct::list -
Fisher-Yates - struct::list -
flatten - struct::list -
floating-point - math::bigfloat · math::fuzzy -
flow - control -
flow network - struct::graph::op -
folding - struct::list -
foldl - generator -
foldr - generator -
foreach - generator -
form - html · ncgi -
format conversion - pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam -
formatter - doctools_plugin_apiref -
formatting - bench::in · bench::out::csv · bench::out::text · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export · textutil · textutil::adjust · textutil::string · textutil::tabify -
formatting engine - docidx_plugin_apiref · doctoc_plugin_apiref · doctools_plugin_apiref -
fossil - textutil::patch -
Fourier transform - math::fourier -
FR - doctools::msgcat::idx::fr · doctools::msgcat::toc::fr -
frame - term::ansi::code::macros -
framework - tool -
ftp - ftp · ftp::geturl · ftpd · uri -
ftpd - ftpd -
ftpserver - ftpd -
full outer join - struct::list -
-Keywords: G -
generate event - uevent -
generate permutations - struct::list -
generation - doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export -
generator - generator -
geocoding - map::geocode::nominatim -
geodesy - map::slippy · mapproj -
geography - map::slippy -
get character - term::receive -
gets - coroutine · coroutine::auto -
git - textutil::patch -
global - coroutine · coroutine::auto -
golang - defer -
gopher - uri -
gps - gpx · nmea -
gpx - gpx -
grammar - grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
graph - grammar::me::cpu::gasm · struct::graph · struct::graph::op · struct::graph_v1 · struct::queue · struct::stack -
graph walking - page_util_flow · page_util_norm_lemon · page_util_norm_peg -
green threads - coroutine · coroutine::auto -
grep - fileutil -
GUID - uuid -
-Keywords: H -
hashing - md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 -
heartbeat - debug::heartbeat -
heuristic - struct::graph::op -
hex - base32::hex -
hexadecimal - tcl::transform::hex -
histogram - counter -
hook - hook · uevent -
horspool - grammar::aycock -
HTML - doctools · doctools::html::cssdefaults · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::html · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::html · dtplite · dtplite · mpexpand -
html - html · htmlparse · javascript · ncgi -
http - autoproxy · httpd · map::geocode::nominatim · map::slippy::fetcher · uri · websocket -
httpd - httpd -
https - uri -
httpserver - httpd -
huddle - huddle · yaml -
human readable - bench::in · bench::out::text -
hyphenation - textutil · textutil::adjust -
-Keywords: I -
i18n - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
IBAN - valtype::iban -
ident - ident -
identification - ident -
identity - tcl::transform::identity -
idle - uevent::onidle -
image - jpeg · png · tiff -
imap - imap4 -
IMEI - valtype::imei -
import - doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json · pt::peg::import::json · pt::peg::import::peg -
in-memory channel - tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::string · tcl::chan::variable -
in-order - struct::tree -
inclusion - struct::set -
Incr Tcl - snit · snitfaq -
indenting - textutil · textutil::adjust -
independent set - struct::graph::op -
index - docidx_intro · docidx_plugin_apiref · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json -
index formatter - docidx_plugin_apiref -
info - namespacex -
inner join - struct::list -
input mode - term::ansi::ctrl::unix -
integer - math::roman -
integration - math::calculus -
inter-thread communication - tcl::chan::fifo2 -
International Article Number - valtype::gs1::ean13 · valtype::isbn -
International Bank Account Number - valtype::iban -
International Mobile Equipment Identity - valtype::imei -
International Standard Book Number - valtype::isbn -
internationalization - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
internet - asn · ftp · ftp::geturl · imap4 · ldap · ldapx · mime · pop3d · pop3d::dbox · pop3d::udb · smtp · websocket -
internet address - tcllib_ip -
interpolation - math::interpolate -
interpreter - deleg_method · deleg_proc · interp · wip -
intersection - struct::set -
interval - math::bigfloat -
ip - tcllib_ip -
ipc - comm · comm_wire -
ipv4 - tcllib_ip -
ipv6 - tcllib_ip -
irc - irc · picoirc -
isA - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
ISBN - valtype::isbn -
isthmus - struct::graph::op -
iterator - generator -
-Keywords: J -
javascript - javascript · json · json::write -
jfif - jpeg -
join - struct::list -
jpeg - jpeg -
JSON - doctools::idx::export::json · doctools::idx::import::json · doctools::toc::export::json · doctools::toc::import::json · pt::peg::export::json · pt::peg::from::json · pt::peg::import::json · pt::peg::to::json -
json - doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · huddle · json · json::write -
justification - textutil::adjust -
-Keywords: K -
keyword index - docidx_intro · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import -
keywords - docidx_plugin_apiref -
knuth - soundex -
-Keywords: L -
l10n - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
lambda - lambda -
LaTeX - docstrip · docstrip_util · tcldocstrip -
latex - doctools::idx · doctools::idx · doctools::toc · doctools::toc -
latitute - map::slippy -
ldap - ldap · ldapx · uri -
ldap client - ldap · ldapx -
ldif - ldapx -
least squares - math::linearalgebra -
left outer join - struct::list -
lemon - page_util_norm_lemon -
level graph - struct::graph::op -
lexer - doctools::idx::parse · doctools::toc::parse -
lexing - string::token · string::token::shell -
limitsize - tcl::transform::limitsize -
line - math::geometry -
linear algebra - math::linearalgebra -
linear equations - math::linearalgebra -
linear program - math::optimize -
lines - term::ansi::ctrl::unix -
list - struct::list · struct::queue · wip -
listener - term::receive · term::receive::bind -
literate programming - docstrip · docstrip_util · tcldocstrip -
LL(k) - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
local searching - struct::graph::op -
localization - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
location - map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher -
log - debug · debug::caller · debug::heartbeat · debug::timestamp · doctools::cvs · log · logger -
log level - log · logger -
logger - logger · logger::appender · logger::utils -
longest common subsequence - struct::list -
longitude - map::slippy -
loop - struct::graph · struct::graph::op -
luhn - valtype::luhn · valtype::luhn5 -
luhn-5 - valtype::luhn5 -
-Keywords: M -
macros - doctools::nroff::man_macros -
mail - imap4 · mime · pop3 · smtp -
mailto - uri -
man_macros - doctools::nroff::man_macros -
manpage - doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_plugin_apiref · dtplite · dtplite · mpexpand -
map - generator · map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher · mapproj · struct::list -
markdown - doctools · doctools::idx · doctools::toc -
markup - docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref · dtplite · dtplite · mpexpand · tcldocstrip -
MasterCard - valtype::creditcard::mastercard -
matching - grammar::me_intro · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · struct::graph::op -
math - math · math::bigfloat · math::bignum · math::calculus · math::complexnumbers · math::constants · math::decimal · math::fuzzy · math::geometry · math::interpolate · math::linearalgebra · math::optimize · math::PCA · math::polynomials · math::rationalfunctions · math::special · math::trig · simulation::annealing · simulation::montecarlo · simulation::random -
mathematics - math::fourier · math::probopt · math::quasirandom · math::statistics -
matrices - math::linearalgebra -
matrix - csv · math::linearalgebra · report · struct::matrix · struct::matrix_v1 · struct::queue · struct::stack -
max cut - struct::graph::op -
maximum - math::optimize -
maximum flow - struct::graph::op -
md4 - md4 · ripemd128 · ripemd160 -
md5 - md5 · md5crypt -
md5crypt - md5crypt -
medicare - valtype::usnpi -
mega widget - snit · snitfaq -
membership - struct::set -
menu - term::ansi::code::macros · term::interact::menu -
merge - tcl::randomseed · uevent::onidle -
merge find - struct::disjointset -
merging - bench -
message - comm · comm_wire · log -
message catalog - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
message level - log -
message package - doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr -
message-digest - md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 -
metakit - tie · tie -
method - deleg_method · interp -
method reference - oo::util · oo::util -
mime - fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::rt · mime · smtp -
minimal spanning tree - struct::graph::op -
minimum - math::optimize -
minimum cost flow - struct::graph::op -
minimum degree spanning tree - struct::graph::op -
minimum diameter spanning tree - struct::graph::op -
mobile phone - valtype::imei -
module - docstrip_util -
montecarlo simulation - simulation::montecarlo -
move - fileutil::multi · fileutil::multi::op -
multi-file - fileutil::multi · fileutil::multi::op -
multiplexer - multiplexer -
multiprecision - math::bigfloat · math::bignum -
my method - oo::util · oo::util -
-Keywords: N -
name service - nameserv · nameserv::auto · nameserv::common · nameserv::protocol · nameserv::server · nns · nns_intro · nnsd · nnslog · udpcluster -
namespace unknown - namespacex -
namespace utilities - namespacex -
narrative - debug · debug::caller · debug::heartbeat · debug::timestamp -
National Provider Identifier - valtype::usnpi -
neighbour - struct::graph · struct::graph::op -
net - ftp · ftp::geturl · imap4 · mime · smtp · websocket -
nettool - nettool -
network - pop3d · pop3d::dbox · pop3d::udb -
news - nntp · uri -
next permutation - struct::list -
nmea - nmea -
nntp - nntp -
nntpclient - nntp -
no-op - control -
node - struct::graph · struct::graph::op · struct::tree -
nominatim - map::geocode::nominatim -
normalization - bench · page_util_norm_lemon · page_util_norm_peg · unicode -
NPI - valtype::usnpi -
nroff - doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::nroff · doctools::nroff::man_macros · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::nroff · dtplite · dtplite · mpexpand -
NTLM - SASL::NTLM -
NTP - ntp_time -
null - tcl::chan::null · tcl::chan::nullzero -
number theory - math::numtheory -
-Keywords: O -
oauth - oauth -
object - snit · snitfaq · stooop · switched -
object oriented - snit · snitfaq · stooop · switched -
observer - hook · tcl::transform::observe -
odie - cron · nettool · processman -
on-idle - uevent::onidle -
one time pad - tcl::transform::otp -
oo - clay -
optimisation - math::probopt -
optimization - math::optimize · simulation::annealing -
ordered list - struct::prioqueue -
otp - tcl::transform::otp -
outer join - struct::list -
-Keywords: P -
package - csv -
package indexing - docstrip_util -
page - page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote -
pager - term::interact::pager -
paragraph - textutil · textutil::adjust -
PARAM - pt::peg::to::param -
parameter entry form - tepam · tepam::argument_dialogbox -
parser - doctools::idx::parse · doctools::tcl::parse · doctools::toc::parse · grammar::aycock · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · xsxp -
parser generator - page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote -
parsing - bench::in · bibtex · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::import · doctools::toc · doctools::toc::import · grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · htmlparse · huddle · string::token::shell · yaml -
parsing expression - grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
parsing expression grammar - grammar::me_intro · grammar::peg · grammar::peg::interp · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
partial application - lambda -
partition - struct::disjointset -
partitioned set - struct::disjointset -
passive - transfer::connect -
password - otp -
patch - docstrip_util · textutil::patch -
patching - rcs -
PCA - math::PCA -
PEG - grammar::me_intro · page_util_norm_peg · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
performance - bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec · profiler -
permutation - struct::list -
persistence - tie · tie -
phone - valtype::imei -
pi - math::constants -
plain text - doctools::idx::export::text · doctools::toc::export::text -
plane geometry - math::geometry -
plugin - docidx_plugin_apiref · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools::html::cssdefaults · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::nroff::man_macros · doctools::toc · doctools::toc::export · doctools::toc::import · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::import::json · pt::peg::import::peg -
plugin management - pluginmgr -
plugin search - pluginmgr -
png - png -
point - math::geometry -
polynomial functions - math::polynomials -
pool - struct::pool · struct::queue -
pop - pop3 -
pop3 - pop3 · pop3d · pop3d::dbox · pop3d::udb -
post-order - struct::tree -
practcl - practcl -
pre-order - struct::tree -
prefix - textutil::string · textutil::trim -
prime - math::numtheory -
prioqueue - struct::prioqueue · struct::queue -
priority queue - struct::prioqueue -
probabilistic calculations - math::probopt -
proc - lambda -
procedure - deleg_proc · tepam · tepam::procedure -
procedure documentation - tepam::doc_gen -
processman - processman -
producer - hook -
profile - profiler -
projection - mapproj -
prospero - uri -
protocol - asn · ldap · ldapx · nameserv::protocol · pop3d · pop3d::dbox · pop3d::udb -
proxy - autoproxy -
public key cipher - pki -
publisher - hook -
push down automaton - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
-Keywords: Q -
quasi-random - math::quasirandom -
queue - csv · htmlparse · struct::stack · transfer::copy::queue -
quoting - page_util_quote -
-Keywords: R -
radians - math::constants · units -
radiobutton - html -
radius - struct::graph::op -
random - tcl::chan::random · tcl::randomseed -
random numbers - simulation::random -
rational functions - math::rationalfunctions -
raw - term::ansi::ctrl::unix -
rc4 - rc4 -
RCS - rcs -
RCS patch - rcs -
read - coroutine · coroutine::auto -
reading - bench::in -
receiver - term::receive · term::receive::bind · transfer::receiver -
reconnect - nameserv::auto -
record - struct::queue · struct::record -
recursive descent - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
reduce - generator · struct::list -
reference - doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import -
reflected channel - tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib -
regex - string::token -
regular expression - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · textutil · textutil::split · textutil::trim -
regular grammar - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op -
regular languages - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op -
remote communication - comm · comm_wire -
remote execution - comm · comm_wire -
remove - fileutil::multi · fileutil::multi::op -
repeating - struct::list -
repetition - struct::list · textutil::repeat -
report - report -
reshuffle - struct::list -
residual graph - struct::graph::op -
resolver - dns -
resource management - try -
restore - nameserv::auto -
return - throw -
reverse - struct::list -
rfc 821 - mime · smtp · smtpd -
rfc 822 - mime · pop3d::dbox · smtp -
rfc 868 - ntp_time -
rfc 959 - ftp · ftp::geturl · ftpd -
rfc 977 - nntp -
rfc 1034 - dns -
rfc 1035 - dns -
rfc 1036 - nntp -
rfc 1320 - md4 · md5 · ripemd128 · ripemd160 -
rfc 1321 - md4 · md5 · ripemd128 · ripemd160 -
rfc 1413 - ident -
rfc 1630 - uri -
rfc 1886 - dns -
rfc 1939 - pop3 · pop3d -
rfc 2030 - ntp_time -
rfc 2045 - mime -
rfc 2046 - mime -
rfc 2049 - mime -
rfc 2104 - md4 · md5 · ripemd128 · ripemd160 · sha1 · sha256 -
rfc 2141 - uri_urn -
rfc 2251 - ldap · ldapx -
rfc 2255 - uri -
rfc 2289 - otp -
rfc 2396 - uri -
rfc 2554 - smtp -
RFC 2718 - oauth -
rfc 2821 - smtp · smtpd -
rfc 2849 - ldapx -
rfc 3207 - smtp -
rfc 3513 - tcllib_ip -
rfc 3986 - uri -
rfc 4511 - ldap -
RFC 5849 - oauth -
rfc 6455 - websocket -
rfc 7858 - dns -
rfc3501 - imap4 -
rfc3548 - base32 · base32::hex -
right outer join - struct::list -
RIPEMD - ripemd128 · ripemd160 -
roman numeral - math::roman -
roots - math::calculus -
rot - tcl::transform::rot -
rot13 - tcl::transform::rot -
rounding - math::fuzzy -
rows - term::ansi::ctrl::unix -
rpc - comm · comm_wire -
rsa - pki -
running - grammar::fa::dexec -
-Keywords: S -
s3 - S3 -
SASL - SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken -
scanl - generator -
SCCS - rcs -
SCRAM - SASL::SCRAM -
secure - comm · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter -
security - aes · blowfish · cksum · crc16 · crc32 · des · md4 · md5 · md5crypt · otp · pki · rc4 · ripemd128 · ripemd160 · sha1 · sha256 · sum · tclDES · tclDESjr -
seed - tcl::randomseed -
selectionbox - javascript -
semantic markup - docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref -
send - comm -
serialization - bee · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::structure · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::structure · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::json · pt::peg::from::peg · pt::peg::import::json · pt::peg::import::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · struct::graph · struct::tree -
server - map::geocode::nominatim · map::slippy::fetcher · nameserv::common · nameserv::server · nns_intro · nnsd · udpcluster -
service - logger -
services - ftpd · httpd · smtpd -
set - struct::queue · struct::set -
sha1 - sha1 -
sha256 - sha256 -
shell - string::token::shell -
shortest path - struct::graph::op -
shuffle - struct::list -
simulated annealing - simulation::annealing -
simulation - simulation::random -
singleton - oo::util · oo::util -
size limit - tcl::transform::limitsize -
skiplist - struct::queue · struct::skiplist -
slippy - map::slippy · map::slippy::cache · map::slippy::fetcher -
smtp - mime · smtp · smtpd -
smtpd - smtpd -
Snit - snit -
snit - deleg_method · interp -
SNTP - ntp_time -
socket - comm · comm_wire · smtpd -
soundex - soundex -
source - docstrip · docstrip_util · tcldocstrip -
spacing - tcl::transform::spacer -
spatial interpolation - math::interpolate -
special functions - math::special -
specification - bench_lang_spec -
speed - profiler -
split - textutil::split -
squared graph - struct::graph::op -
ssl - comm · imap4 · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter -
stack - struct::queue -
standard io - tcl::chan::std -
state - grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
state (de)serialization - namespacex -
statistical distribution - simulation::random -
statistics - counter · math · math::changepoint · math::PCA · math::statistics -
stdin - tcl::chan::std -
stdout - tcl::chan::std -
stochastic modelling - simulation::montecarlo -
stream cipher - rc4 -
stream copy - tcl::transform::observe -
string - string::token · string::token::shell · textutil · textutil::adjust · textutil::expander · textutil::repeat · textutil::split · textutil::string · textutil::tabify · textutil::trim -
stringprep - stringprep · stringprep::data · unicode::data -
strongly connected component - struct::graph::op -
struct - struct::pool · struct::record -
structure - control -
structured queries - treeql -
style - doctools::html::cssdefaults -
subcommand - tepam · tepam::procedure -
subgraph - struct::graph · struct::graph::op -
subject - hook -
submitbutton - javascript -
subscriber - hook -
subsequence - struct::list -
subst - doctools::tcl::parse -
sum - sum -
swapping - struct::list -
symmetric difference - struct::set -
synchronous - cache::async -
syntax tree - grammar::me::util -
-Keywords: T -
table - doctools::toc · doctools::toc::export · doctools::toc::import · html · report -
table of contents - doctoc_intro · doctoc_plugin_apiref · doctools2toc_introduction · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json -
tabstops - textutil::tabify -
tallying - counter -
tape archive - tar -
tar - tar -
tcl - math::bigfloat · math::bignum · math::decimal · math::PCA -
Tcl module - docstrip_util -
Tcl syntax - doctools::tcl::parse -
tcler's wiki - doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export -
tcllib - csv -
TclOO - clay · httpd · oo::util · oo::util · oometa · tool · tool::dict_ensemble -
TCLPARAM - pt::peg::to::tclparam -
TDPL - grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
temp file - fileutil -
template processing - textutil::expander -
terminal - term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send -
test - fileutil -
Testing - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
testing - bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec -
TeX - textutil · textutil::adjust -
text - bench::in · bench::out::text · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export -
text comparison - soundex -
text conversion - rcs -
text differences - rcs -
text display - term::interact::menu · term::interact::pager -
text expansion - textutil::expander -
text likeness - soundex -
text processing - bibtex · huddle · page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote · yaml -
text widget - tcl::chan::textwindow -
threads - coroutine · coroutine::auto -
throw - throw -
thumbnail - jpeg -
tie - tie · tie -
tif - tiff -
tiff - tiff -
tile - map::slippy::cache · map::slippy::fetcher -
time - ntp_time -
timestamp - png -
timestamps - debug::timestamp -
tip 219 - tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::core -
tip 230 - tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib -
tip 234 - tcl::transform::zlib -
tip 317 - tcl::transform::base64 -
Tk - tcl::chan::textwindow -
tls - comm · imap4 · pop3 · pop3d · smtp · transfer::connect · transfer::receiver · transfer::transmitter -
TMML - doctools · doctools::idx · doctools::idx · doctools::toc · doctools::toc · dtplite · dtplite · mpexpand -
toc - doctoc_intro · doctoc_plugin_apiref · doctools::toc · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json -
toc formatter - doctoc_plugin_apiref -
tokenization - string::token · string::token::shell -
TOOL - oometa · tool · tool::dict_ensemble -
top-down parsing languages - grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
torrent - bee -
touch - fileutil -
TPDL - grammar::me_intro -
trace - debug · debug::caller · debug::heartbeat · debug::timestamp -
transducer - grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op -
transfer - transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter -
transformation - page_util_peg · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib -
transmitter - transfer::transmitter -
travelling salesman - struct::graph::op -
traversal - fileutil_traverse -
tree - grammar::me::cpu::gasm · grammar::me::util · htmlparse · struct::queue · struct::stack · struct::tree · struct::tree_v1 · treeql -
tree query language - treeql -
tree walking - page_util_flow · page_util_norm_lemon · page_util_norm_peg -
TreeQL - treeql -
trigonometry - math::trig -
trimming - textutil · textutil::trim -
twitter - oauth -
type - fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · snit -
Type checking - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
-Keywords: U -
uevent - hook -
unbind - uevent -
uncapitalize - textutil::string -
undenting - textutil::adjust -
unicode - stringprep · stringprep::data · unicode · unicode::data -
unified format diff - textutil::patch -
union - struct::disjointset · struct::set -
unit - units -
unknown hooking - namespacex -
untie - tie · tie -
update - coroutine · coroutine::auto -
uri - uri · uri_urn -
url - doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc::export · doctools::toc::import · map::geocode::nominatim · map::slippy::fetcher · uri · uri_urn -
urn - uri_urn -
US-NPI - valtype::usnpi -
utilities - namespacex -
uuencode - uuencode -
UUID - uuid -
-Keywords: V -
Validation - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
Value checking - valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff -
vectors - math::linearalgebra -
verhoeff - valtype::verhoeff -
vertex - struct::graph · struct::graph::op -
vertex cover - struct::graph::op -
virtual channel - tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib -
virtual machine - grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg::interp · pt::param -
VISA - valtype::creditcard::visa -
vwait - coroutine · coroutine::auto · smtpd -
-Keywords: W -
wais - uri -
widget - snit · snitfaq -
widget adaptors - snit · snitfaq -
wiki - doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::wiki · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::wiki -
word - doctools::tcl::parse · wip -
WWW - httpd -
www - uri -
-Keywords: X -
x.208 - asn -
x.209 - asn -
x.500 - ldap -
XGoogleToken - SASL::XGoogleToken -
xml - xsxp -
xor - tcl::transform::otp -
XPath - treeql -
XSLT - treeql -
-Keywords: Y -
yaml - huddle · yaml -
ydecode - yencode -
yEnc - yencode -
yencode - yencode -
-Keywords: Z -
zero - tcl::chan::nullzero · tcl::chan::zero -
zip - zipfile::decode · zipfile::encode · zipfile::mkzip -
zlib - tcl::transform::zlib -
zoom
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Keywords: . +
.ddt + docstrip_util +
.dtx + docstrip · docstrip_util · tcldocstrip +
+Keywords: / +
/dev/null + tcl::chan::null · tcl::chan::nullzero +
/dev/random + tcl::chan::random · tcl::randomseed +
/dev/zero + tcl::chan::nullzero · tcl::chan::zero +
+Keywords: 3 +
3DES + des · tclDES · tclDESjr +
+Keywords: A +
abstract syntax tree + grammar::me::util · grammar::me_ast +
acceptance + grammar::fa::dacceptor +
acceptor + grammar::fa::dacceptor +
active + transfer::connect +
adaptors + snit · snitfaq +
adjacency list + struct::graph::op +
adjacency matrix + struct::graph::op +
adjacent + struct::graph · struct::graph::op +
adjusting + textutil::adjust +
adler32 + tcl::transform::adler32 +
aes + aes +
after + coroutine · coroutine::auto +
alias + interp +
amazon + S3 +
ambiguous + grammar::aycock +
American Express + valtype::creditcard::amex +
AMEX + valtype::creditcard::amex +
angle + math::geometry · units +
anonymous procedure + lambda +
ansi + term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix +
appender + logger::appender · logger::utils +
application + nns · nnsd · nnslog +
approximation algorithm + struct::graph::op +
arc + struct::graph · struct::graph::op +
arcfour + rc4 +
archive + tar +
argument integrity + tepam · tepam::procedure +
argument processing + cmdline +
argument validation + tepam · tepam::procedure +
arguments + tepam · tepam::procedure +
argv + cmdline +
argv0 + cmdline +
array + tie · tie +
articulation point + struct::graph::op +
ascii85 + ascii85 +
asn + asn +
assembler + grammar::me::cpu::gasm +
assert + control +
assign + struct::list +
AST + grammar::me_ast +
asynchronous + cache::async +
attribute control + term::ansi::code::attr · term::ansi::code::ctrl +
augmenting network + struct::graph::op +
augmenting path + struct::graph::op +
authentication + autoproxy · SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken +
automatic + nameserv::auto +
automatic documentation + tepam::doc_gen +
automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
aycock + grammar::aycock +
+Keywords: B +
bank + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban +
base32 + base32 · base32::core · base32::hex +
base64 + base64 · tcl::transform::base64 +
bash + string::token::shell +
bee + bee +
bench language + bench_intro · bench_lang_intro · bench_lang_spec +
benchmark + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec +
ber + asn +
Bessel functions + math::special +
bfs + struct::graph::op +
bibliography + bibtex +
bibtex + bibtex +
bignums + math::bignum +
bind + uevent +
bipartite + struct::graph::op +
BitTorrent + bee +
bittorrent + bee +
blanks + textutil::repeat +
block cipher + aes · blowfish · des · tclDES · tclDESjr +
blocking flow + struct::graph::op +
blowfish + blowfish +
Book Number + valtype::isbn +
breadth-first + struct::tree +
bridge + struct::graph::op +
BWidget + snit · snitfaq +
+Keywords: C +
C + doctools::msgcat::idx::c · doctools::msgcat::toc::c +
C++ + snit · snitfaq · stooop · switched +
cache + cache::async · map::slippy::cache +
caesar cipher + tcl::transform::rot +
calculus + math::calculus +
callback + cache::async · hook · lambda · oo::util · oo::util · uevent::onidle +
callbacks + tcl::chan::halfpipe +
capitalize + textutil::string +
card for credit + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa +
cardinality + struct::set +
cat + fileutil +
catalog package + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
catalogue + docstrip_util +
cell-phone + valtype::imei +
cer + asn +
CFG + grammar::me_intro +
CFL + grammar::me_intro +
CGI + ncgi +
cgraph + struct::graph · struct::graph_v1 +
changelog + doctools::changelog · doctools::cvs +
channel + coroutine · coroutine::auto · transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
channel transformation + tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
character input + term::receive · term::receive::bind +
character output + term::ansi::send · term::send +
chat + irc · multiplexer · picoirc +
checkbox + html · javascript +
checkbutton + html +
Checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
checksum + cksum · crc16 · crc32 · sum · tcl::transform::adler32 · tcl::transform::crc32 +
chop + textutil::string +
cipher + pki · tcl::transform::otp · tcl::transform::rot +
cksum + cksum · crc16 · crc32 · sum +
class + snit · snitfaq · stooop · switched +
class methods + oo::util · oo::util +
class variables + oo::util · oo::util +
cleanup + try +
client + nameserv · nameserv::auto · nameserv::common · nns · nns_intro · nnslog +
cloud + S3 +
cmdline processing + cmdline +
color control + term::ansi::code::attr · term::ansi::code::ctrl +
columns + term::ansi::ctrl::unix +
comm + comm · comm_wire · deleg_method · deleg_proc · nameserv::protocol +
command + doctools::tcl::parse +
command line processing + cmdline +
command prefix + lambda · oo::util · oo::util +
comment + jpeg · png +
common + struct::list +
common prefix + textutil::string +
communication + comm · comm_wire +
comparison + struct::list +
complete graph + struct::graph::op +
complex numbers + math::complexnumbers · math::fourier +
compression + tcl::transform::zlib · zipfile::encode +
computations + math::bigfloat +
concatenation channel + tcl::chan::cat · tcl::chan::facade +
connected component + struct::graph::op +
connected fifos + tcl::chan::fifo2 +
connection + transfer::connect +
constants + math::constants · units +
CONTAINER + pt::peg::export::container · pt::peg::to::container +
contents + doctools2toc_introduction +
context-free grammar + grammar::me_intro +
context-free languages + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
control + control · term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send +
control structure + generator +
conversion + doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · dtplite · dtplite · math::roman · mpexpand · pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · tcldocstrip · units +
cooked + term::ansi::ctrl::unix +
cookie + ncgi +
copy + fileutil::multi · fileutil::multi::op · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
coroutine + coroutine · coroutine::auto · generator +
Cost + treeql +
counter + tcl::transform::counter +
counting + counter +
CPARAM + pt::peg::to::cparam +
crc + cksum · crc16 · crc32 · sum +
crc16 + crc16 +
crc32 + cksum · crc16 · crc32 · sum · tcl::transform::crc32 +
credit card + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa +
cron + cron +
cryptography + blowfish +
CSS + doctools::html::cssdefaults +
csv + bench::in · bench::out::csv · csv +
currying + lambda · oo::util · oo::util +
cut edge + struct::graph::op +
cut vertex + struct::graph::op +
CVS + rcs +
cvs + doctools::cvs +
cvs log + doctools::cvs +
cyclic redundancy check + cksum · crc16 · crc32 · sum +
+Keywords: D +
data analysis + math::statistics +
data destination + transfer::data::destination · transfer::receiver +
data entry form + tepam::argument_dialogbox +
data exchange + huddle · json · json::write · yaml +
data integrity + aes · cksum · crc16 · crc32 · des · pki · rc4 · sum · tclDES · tclDESjr +
data source + transfer::data::source · transfer::transmitter +
data structures + struct::record +
database + tie · tie +
dataflow + page_util_flow +
DE + doctools::msgcat::idx::de · doctools::msgcat::toc::de +
debug + debug · debug::caller · debug::heartbeat · debug::timestamp +
decimal + math::decimal +
declare + term::ansi::code +
decompression + tcl::transform::zlib · zipfile::decode · zipfile::mkzip +
decryption + tcl::transform::otp · tcl::transform::rot +
deferal + uevent::onidle +
define + term::ansi::code +
degree + struct::graph · struct::graph::op +
degree constrained spanning tree + struct::graph::op +
degrees + math::constants +
delegation + deleg_method · deleg_proc +
depth-first + struct::tree +
der + asn +
DES + des · tclDES · tclDESjr +
deserialization + doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::structure · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::structure +
diameter + struct::graph::op +
dict + dicttool +
diff + docstrip_util · struct::list +
diff -n format + rcs +
difference + struct::set +
differential + struct::list +
differential equations + math::calculus +
dijkstra + struct::graph::op +
directory access + ldap · ldapx +
directory traversal + fileutil_traverse +
Discover + valtype::creditcard::discover +
discrete items + struct::pool +
disjoint set + struct::disjointset +
dispatcher + term::receive::bind +
distance + math::geometry · struct::graph::op · units +
DNS + dns +
do + control +
docidx + doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · dtplite · dtplite +
docidx commands + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docidx language + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docidx markup + docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · doctools::idx +
docidx syntax + docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax +
docstrip + docstrip · docstrip_util · tcldocstrip +
doctoc + doctools::msgcat · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite +
doctoc commands + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctoc language + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctoc markup + doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctools::toc +
doctoc syntax + doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax +
doctools + docstrip_util · doctools::changelog · doctools::html::cssdefaults · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import::docidx · doctools::idx::import::json · doctools::idx::parse · doctools::idx::structure · doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr · doctools::nroff::man_macros · doctools::tcl::parse · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json · doctools::toc::parse · doctools::toc::structure · dtplite · dtplite +
doctools commands + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools language + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools markup + doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
doctools syntax + doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax +
document + doctools_plugin_apiref +
documentation + docstrip · docstrip_util · doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · tcldocstrip · tepam::doc_gen +
DOM + treeql +
dom + xsxp +
domain name service + dns +
+Keywords: E +
e + math::constants +
EAN + valtype::gs1::ean13 · valtype::isbn +
EAN13 + valtype::gs1::ean13 · valtype::isbn +
earley + grammar::aycock +
EBNF + pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
eccentricity + struct::graph::op +
edge + struct::graph · struct::graph::op +
emacs + doctools::changelog · doctools::cvs +
email + imap4 · mime · pop3 · smtp +
emptiness + struct::set +
empty interpreter + interp +
EN + doctools::msgcat::idx::en · doctools::msgcat::toc::en +
encoding + ascii85 · base64 · uuencode · yencode +
encryption + aes · blowfish · des · pki · rc4 · tcl::transform::otp · tcl::transform::rot · tclDES · tclDESjr +
entry mask + tepam +
equal + struct::list +
equality + struct::list +
equivalence class + struct::disjointset +
error + throw · try +
error function + math::special +
European Article Number + valtype::gs1::ean13 · valtype::isbn +
event + hook · uevent · uevent::onidle +
event management + tcl::chan::events +
events + coroutine · coroutine::auto +
examples + bench_lang_intro · docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq +
exception + try +
exchange format + huddle · json · json::write +
exclusion + struct::set +
execution + grammar::fa::dexec +
exif + jpeg +
exit + coroutine · coroutine::auto +
export + doctools::html::cssdefaults · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::nroff::man_macros · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg +
expression + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
extended namespace + namespacex +
+Keywords: F +
faq + docidx_lang_faq · doctoc_lang_faq · doctools_lang_faq +
fetching information + uri +
FFT + math::fourier +
fifo + tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe +
file + tie · tie · uri +
file recognition + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt +
file type + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt +
file utilities + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · fileutil::multi · fileutil::multi::op +
filesystem + map::slippy::cache +
filter + generator · struct::list +
final + try +
finance + valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::iban +
find + struct::disjointset +
finite + struct::pool +
finite automaton + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
FIPS 180-1 + sha1 · sha256 +
first permutation + struct::list +
Fisher-Yates + struct::list +
flatten + struct::list +
floating-point + math::bigfloat · math::fuzzy +
flow + control +
flow network + struct::graph::op +
folding + struct::list +
foldl + generator +
foldr + generator +
foreach + generator +
form + html · ncgi +
format conversion + pt::peg::from::json · pt::peg::from::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam +
formatter + doctools_plugin_apiref +
formatting + bench::in · bench::out::csv · bench::out::text · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export · textutil · textutil::adjust · textutil::string · textutil::tabify +
formatting engine + docidx_plugin_apiref · doctoc_plugin_apiref · doctools_plugin_apiref +
Fourier transform + math::fourier +
FR + doctools::msgcat::idx::fr · doctools::msgcat::toc::fr +
frame + term::ansi::code::macros +
ftp + ftp · ftp::geturl · ftpd · uri +
ftpd + ftpd +
ftpserver + ftpd +
full outer join + struct::list +
+Keywords: G +
generate event + uevent +
generate permutations + struct::list +
generation + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
generator + generator +
geocoding + map::geocode::nominatim +
geodesy + map::slippy · mapproj +
geography + map::slippy +
get character + term::receive +
gets + coroutine · coroutine::auto +
global + coroutine · coroutine::auto +
gopher + uri +
gps + gpx · nmea +
gpx + gpx +
grammar + grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
graph + grammar::me::cpu::gasm · struct::graph · struct::graph::op · struct::graph_v1 · struct::queue · struct::stack +
graph walking + page_util_flow · page_util_norm_lemon · page_util_norm_peg +
green threads + coroutine · coroutine::auto +
grep + fileutil +
GUID + uuid +
+Keywords: H +
hashing + md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 +
heartbeat + debug::heartbeat +
heuristic + struct::graph::op +
hex + base32::hex +
hexadecimal + tcl::transform::hex +
histogram + counter +
hook + hook · uevent +
horspool + grammar::aycock +
HTML + doctools · doctools::html::cssdefaults · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::html · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::html · dtplite · dtplite · mpexpand +
html + html · htmlparse · javascript · ncgi +
http + autoproxy · map::geocode::nominatim · map::slippy::fetcher · uri · websocket +
huddle + huddle · yaml +
human readable + bench::in · bench::out::text +
hyphenation + textutil · textutil::adjust +
+Keywords: I +
i18n + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
IBAN + valtype::iban +
ident + ident +
identification + ident +
identity + tcl::transform::identity +
idle + uevent::onidle +
image + jpeg · png · tiff +
imap + imap4 +
IMEI + valtype::imei +
import + doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json · pt::peg::import::json · pt::peg::import::peg +
in-memory channel + tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::string · tcl::chan::variable +
in-order + struct::tree +
inclusion + struct::set +
Incr Tcl + snit · snitfaq +
indenting + textutil · textutil::adjust +
independent set + struct::graph::op +
index + docidx_intro · docidx_plugin_apiref · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::import · doctools::idx::import::docidx · doctools::idx::import::json +
index formatter + docidx_plugin_apiref +
info + namespacex +
inner join + struct::list +
input mode + term::ansi::ctrl::unix +
integer + math::roman +
integration + math::calculus +
inter-thread communication + tcl::chan::fifo2 +
International Article Number + valtype::gs1::ean13 · valtype::isbn +
International Bank Account Number + valtype::iban +
International Mobile Equipment Identity + valtype::imei +
International Standard Book Number + valtype::isbn +
internationalization + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
internet + asn · ftp · ftp::geturl · imap4 · ldap · ldapx · mime · pop3d · pop3d::dbox · pop3d::udb · smtp · websocket +
internet address + tcllib_ip +
interpolation + math::interpolate +
interpreter + deleg_method · deleg_proc · interp · wip +
intersection + struct::set +
interval + math::bigfloat +
ip + tcllib_ip +
ipc + comm · comm_wire +
ipv4 + tcllib_ip +
ipv6 + tcllib_ip +
irc + irc · picoirc +
isA + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
ISBN + valtype::isbn +
isthmus + struct::graph::op +
iterator + generator +
+Keywords: J +
javascript + javascript · json · json::write +
jfif + jpeg +
join + struct::list +
jpeg + jpeg +
JSON + doctools::idx::export::json · doctools::idx::import::json · doctools::toc::export::json · doctools::toc::import::json · pt::peg::export::json · pt::peg::from::json · pt::peg::import::json · pt::peg::to::json +
json + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · huddle · json · json::write +
justification + textutil::adjust +
+Keywords: K +
keyword index + docidx_intro · doctools2idx_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import +
keywords + docidx_plugin_apiref +
knuth + soundex +
+Keywords: L +
l10n + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
lambda + lambda +
LaTeX + docstrip · docstrip_util · tcldocstrip +
latex + doctools::idx · doctools::idx · doctools::toc · doctools::toc +
latitute + map::slippy +
ldap + ldap · ldapx · uri +
ldap client + ldap · ldapx +
ldif + ldapx +
least squares + math::linearalgebra +
left outer join + struct::list +
lemon + page_util_norm_lemon +
level graph + struct::graph::op +
lexer + doctools::idx::parse · doctools::toc::parse +
lexing + string::token · string::token::shell +
limitsize + tcl::transform::limitsize +
line + math::geometry +
linear algebra + math::linearalgebra +
linear equations + math::linearalgebra +
linear program + math::optimize +
lines + term::ansi::ctrl::unix +
list + struct::list · struct::queue · wip +
listener + term::receive · term::receive::bind +
literate programming + docstrip · docstrip_util · tcldocstrip +
LL(k) + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
local searching + struct::graph::op +
localization + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
location + map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher +
log + debug · debug::caller · debug::heartbeat · debug::timestamp · doctools::cvs · log · logger +
log level + log · logger +
logger + logger · logger::appender · logger::utils +
longest common subsequence + struct::list +
longitude + map::slippy +
loop + struct::graph · struct::graph::op +
luhn + valtype::luhn · valtype::luhn5 +
luhn-5 + valtype::luhn5 +
+Keywords: M +
macros + doctools::nroff::man_macros +
mail + imap4 · mime · pop3 · smtp +
mailto + uri +
man_macros + doctools::nroff::man_macros +
manpage + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_plugin_apiref · dtplite · dtplite · mpexpand +
map + generator · map::geocode::nominatim · map::slippy · map::slippy::cache · map::slippy::fetcher · mapproj · struct::list +
markup + docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::import · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref · dtplite · dtplite · mpexpand · tcldocstrip +
MasterCard + valtype::creditcard::mastercard +
matching + grammar::me_intro · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · struct::graph::op +
math + math · math::bigfloat · math::bignum · math::calculus · math::complexnumbers · math::constants · math::decimal · math::fuzzy · math::geometry · math::interpolate · math::linearalgebra · math::optimize · math::polynomials · math::rationalfunctions · math::special · simulation::annealing · simulation::montecarlo · simulation::random +
mathematics + math::fourier · math::statistics +
matrices + math::linearalgebra +
matrix + csv · math::linearalgebra · report · struct::matrix · struct::matrix_v1 · struct::queue · struct::stack +
max cut + struct::graph::op +
maximum + math::optimize +
maximum flow + struct::graph::op +
md4 + md4 · ripemd128 · ripemd160 +
md5 + md5 · md5crypt +
md5crypt + md5crypt +
medicare + valtype::usnpi +
mega widget + snit · snitfaq +
membership + struct::set +
menu + term::ansi::code::macros · term::interact::menu +
merge + tcl::randomseed · uevent::onidle +
merge find + struct::disjointset +
merging + bench +
message + comm · comm_wire · log +
message catalog + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
message level + log +
message package + doctools::msgcat · doctools::msgcat::idx::c · doctools::msgcat::idx::de · doctools::msgcat::idx::en · doctools::msgcat::idx::fr · doctools::msgcat::toc::c · doctools::msgcat::toc::de · doctools::msgcat::toc::en · doctools::msgcat::toc::fr +
message-digest + md4 · md5 · md5crypt · otp · ripemd128 · ripemd160 · sha1 · sha256 +
metakit + tie · tie +
method + deleg_method · interp +
method reference + oo::util · oo::util +
mime + fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::rt · mime · smtp +
minimal spanning tree + struct::graph::op +
minimum + math::optimize +
minimum cost flow + struct::graph::op +
minimum degree spanning tree + struct::graph::op +
minimum diameter spanning tree + struct::graph::op +
mobile phone + valtype::imei +
module + docstrip_util +
montecarlo simulation + simulation::montecarlo +
move + fileutil::multi · fileutil::multi::op +
multi-file + fileutil::multi · fileutil::multi::op +
multiplexer + multiplexer +
multiprecision + math::bigfloat · math::bignum +
my method + oo::util · oo::util +
+Keywords: N +
name service + nameserv · nameserv::auto · nameserv::common · nameserv::protocol · nameserv::server · nns · nns_intro · nnsd · nnslog · udpcluster +
namespace unknown + namespacex +
namespace utilities + namespacex +
narrative + debug · debug::caller · debug::heartbeat · debug::timestamp +
National Provider Identifier + valtype::usnpi +
neighbour + struct::graph · struct::graph::op +
net + ftp · ftp::geturl · imap4 · mime · smtp · websocket +
nettool + nettool +
network + pop3d · pop3d::dbox · pop3d::udb +
news + nntp · uri +
next permutation + struct::list +
nmea + nmea +
nntp + nntp +
nntpclient + nntp +
no-op + control +
node + struct::graph · struct::graph::op · struct::tree +
nominatim + map::geocode::nominatim +
normalization + bench · page_util_norm_lemon · page_util_norm_peg · unicode +
NPI + valtype::usnpi +
nroff + doctools · doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::nroff · doctools::nroff::man_macros · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::nroff · dtplite · dtplite · mpexpand +
NTLM + SASL::NTLM +
NTP + ntp_time +
null + tcl::chan::null · tcl::chan::nullzero +
number theory + math::numtheory +
+Keywords: O +
oauth + oauth +
object + snit · snitfaq · stooop · switched +
object oriented + snit · snitfaq · stooop · switched +
observer + hook · tcl::transform::observe +
odie + cron · nettool · processman +
on-idle + uevent::onidle +
one time pad + tcl::transform::otp +
optimization + math::optimize · simulation::annealing +
ordered list + struct::prioqueue +
otp + tcl::transform::otp +
outer join + struct::list +
+Keywords: P +
package + csv +
package indexing + docstrip_util +
page + page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote +
pager + term::interact::pager +
paragraph + textutil · textutil::adjust +
PARAM + pt::peg::to::param +
parameter entry form + tepam · tepam::argument_dialogbox +
parser + doctools::idx::parse · doctools::tcl::parse · doctools::toc::parse · grammar::aycock · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op · xsxp +
parser generator + page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote +
parsing + bench::in · bibtex · doctools2idx_introduction · doctools2toc_introduction · doctools::idx · doctools::idx::import · doctools::toc · doctools::toc::import · grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg · grammar::peg::interp · htmlparse · huddle · string::token::shell · yaml +
parsing expression + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
parsing expression grammar + grammar::me_intro · grammar::peg · grammar::peg::interp · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
partial application + lambda +
partition + struct::disjointset +
partitioned set + struct::disjointset +
passive + transfer::connect +
password + otp +
patch + docstrip_util +
patching + rcs +
PEG + grammar::me_intro · page_util_norm_peg · page_util_peg · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
performance + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec · profiler +
permutation + struct::list +
persistence + tie · tie +
phone + valtype::imei +
pi + math::constants +
plain text + doctools::idx::export::text · doctools::toc::export::text +
plane geometry + math::geometry +
plugin + docidx_plugin_apiref · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools::html::cssdefaults · doctools::idx · doctools::idx::export · doctools::idx::import · doctools::nroff::man_macros · doctools::toc · doctools::toc::export · doctools::toc::import · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::import::json · pt::peg::import::peg +
plugin management + pluginmgr +
plugin search + pluginmgr +
png + png +
point + math::geometry +
polynomial functions + math::polynomials +
pool + struct::pool · struct::queue +
pop + pop3 +
pop3 + pop3 · pop3d · pop3d::dbox · pop3d::udb +
post-order + struct::tree +
practcl + practcl +
pre-order + struct::tree +
prefix + textutil::string · textutil::trim +
prime + math::numtheory +
prioqueue + struct::prioqueue · struct::queue +
priority queue + struct::prioqueue +
proc + lambda +
procedure + deleg_proc · tepam · tepam::procedure +
procedure documentation + tepam::doc_gen +
processman + processman +
producer + hook +
profile + profiler +
projection + mapproj +
prospero + uri +
protocol + asn · ldap · ldapx · nameserv::protocol · pop3d · pop3d::dbox · pop3d::udb +
proxy + autoproxy +
public key cipher + pki +
publisher + hook +
push down automaton + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
+Keywords: Q +
queue + csv · htmlparse · struct::stack · transfer::copy::queue +
quoting + page_util_quote +
+Keywords: R +
radians + math::constants · units +
radiobutton + html +
radius + struct::graph::op +
random + tcl::chan::random · tcl::randomseed +
random numbers + simulation::random +
rational functions + math::rationalfunctions +
raw + term::ansi::ctrl::unix +
rc4 + rc4 +
RCS + rcs +
RCS patch + rcs +
read + coroutine · coroutine::auto +
reading + bench::in +
receiver + term::receive · term::receive::bind · transfer::receiver +
reconnect + nameserv::auto +
record + struct::queue · struct::record +
recursive descent + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
reduce + generator · struct::list +
reference + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc · doctools::toc::export · doctools::toc::import +
reflected channel + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
regex + string::token +
regular expression + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · textutil · textutil::split · textutil::trim +
regular grammar + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
regular languages + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op +
remote communication + comm · comm_wire +
remote execution + comm · comm_wire +
remove + fileutil::multi · fileutil::multi::op +
repeating + struct::list +
repetition + struct::list · textutil::repeat +
report + report +
reshuffle + struct::list +
residual graph + struct::graph::op +
resolver + dns +
resource management + try +
restore + nameserv::auto +
return + throw +
reverse + struct::list +
rfc 821 + mime · smtp · smtpd +
rfc 822 + mime · pop3d::dbox · smtp +
rfc 868 + ntp_time +
rfc 959 + ftp · ftp::geturl · ftpd +
rfc 977 + nntp +
rfc 1034 + dns +
rfc 1035 + dns +
rfc 1036 + nntp +
rfc 1320 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1321 + md4 · md5 · ripemd128 · ripemd160 +
rfc 1413 + ident +
rfc 1886 + dns +
rfc 1939 + pop3 · pop3d +
rfc 2030 + ntp_time +
rfc 2045 + mime +
rfc 2046 + mime +
rfc 2049 + mime +
rfc 2104 + md4 · md5 · ripemd128 · ripemd160 · sha1 · sha256 +
rfc 2141 + uri_urn +
rfc 2251 + ldap · ldapx +
rfc 2255 + uri +
rfc 2289 + otp +
rfc 2396 + uri +
rfc 2554 + smtp +
RFC 2718 + oauth +
rfc 2821 + smtp · smtpd +
rfc 2849 + ldapx +
rfc 3207 + smtp +
rfc 3513 + tcllib_ip +
rfc 4511 + ldap +
RFC 5849 + oauth +
rfc 6455 + websocket +
rfc3501 + imap4 +
rfc3548 + base32 · base32::hex +
right outer join + struct::list +
RIPEMD + ripemd128 · ripemd160 +
roman numeral + math::roman +
roots + math::calculus +
rot + tcl::transform::rot +
rot13 + tcl::transform::rot +
rounding + math::fuzzy +
rows + term::ansi::ctrl::unix +
rpc + comm · comm_wire +
rsa + pki +
running + grammar::fa::dexec +
+Keywords: S +
s3 + S3 +
SASL + SASL · SASL::NTLM · SASL::SCRAM · SASL::XGoogleToken +
scanl + generator +
SCCS + rcs +
SCRAM + SASL::SCRAM +
secure + comm · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter +
security + aes · blowfish · cksum · crc16 · crc32 · des · md4 · md5 · md5crypt · otp · pki · rc4 · ripemd128 · ripemd160 · sha1 · sha256 · sum · tclDES · tclDESjr +
seed + tcl::randomseed +
selectionbox + javascript +
semantic markup + docidx_intro · docidx_lang_cmdref · docidx_lang_faq · docidx_lang_intro · docidx_lang_syntax · docidx_plugin_apiref · doctoc_intro · doctoc_lang_cmdref · doctoc_lang_faq · doctoc_lang_intro · doctoc_lang_syntax · doctoc_plugin_apiref · doctools2idx_introduction · doctools2toc_introduction · doctools_intro · doctools_lang_cmdref · doctools_lang_faq · doctools_lang_intro · doctools_lang_syntax · doctools_plugin_apiref +
send + comm +
serialization + bee · doctools::idx::export::docidx · doctools::idx::export::html · doctools::idx::export::json · doctools::idx::export::nroff · doctools::idx::export::text · doctools::idx::export::wiki · doctools::idx::structure · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::structure · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::json · pt::peg::from::peg · pt::peg::import::json · pt::peg::import::peg · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · struct::graph · struct::tree +
server + map::geocode::nominatim · map::slippy::fetcher · nameserv::common · nameserv::server · nns_intro · nnsd · udpcluster +
service + logger +
services + ftpd · smtpd +
set + struct::queue · struct::set +
sha1 + sha1 +
sha256 + sha256 +
shell + string::token::shell +
shortest path + struct::graph::op +
shuffle + struct::list +
simulated annealing + simulation::annealing +
simulation + simulation::random +
singleton + oo::util · oo::util +
size limit + tcl::transform::limitsize +
skiplist + struct::queue · struct::skiplist +
slippy + map::slippy · map::slippy::cache · map::slippy::fetcher +
smtp + mime · smtp · smtpd +
smtpd + smtpd +
Snit + snit +
snit + deleg_method · interp +
SNTP + ntp_time +
socket + comm · comm_wire · smtpd +
soundex + soundex +
source + docstrip · docstrip_util · tcldocstrip +
spacing + tcl::transform::spacer +
spatial interpolation + math::interpolate +
special functions + math::special +
specification + bench_lang_spec +
speed + profiler +
split + textutil::split +
squared graph + struct::graph::op +
ssl + comm · imap4 · pop3 · pop3d · transfer::connect · transfer::receiver · transfer::transmitter +
stack + struct::queue +
standard io + tcl::chan::std +
state + grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
state (de)serialization + namespacex +
statistical distribution + simulation::random +
statistics + counter · math · math::statistics +
stdin + tcl::chan::std +
stdout + tcl::chan::std +
stochastic modelling + simulation::montecarlo +
stream cipher + rc4 +
stream copy + tcl::transform::observe +
string + string::token · string::token::shell · textutil · textutil::adjust · textutil::expander · textutil::repeat · textutil::split · textutil::string · textutil::tabify · textutil::trim +
stringprep + stringprep · stringprep::data · unicode::data +
strongly connected component + struct::graph::op +
struct + struct::pool · struct::record +
structure + control +
structured queries + treeql +
style + doctools::html::cssdefaults +
subcommand + tepam · tepam::procedure +
subgraph + struct::graph · struct::graph::op +
subject + hook +
submitbutton + javascript +
subscriber + hook +
subsequence + struct::list +
subst + doctools::tcl::parse +
sum + sum +
swapping + struct::list +
symmetric difference + struct::set +
synchronous + cache::async +
syntax tree + grammar::me::util +
+Keywords: T +
table + doctools::toc · doctools::toc::export · doctools::toc::import · html · report +
table of contents + doctoc_intro · doctoc_plugin_apiref · doctools2toc_introduction · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import · doctools::toc::import::doctoc · doctools::toc::import::json +
tabstops + textutil::tabify +
tallying + counter +
tape archive + tar +
tar + tar +
tcl + math::bigfloat · math::bignum · math::decimal +
Tcl module + docstrip_util +
Tcl syntax + doctools::tcl::parse +
tcler's wiki + doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
tcllib + csv +
TclOO + oo::util · oo::util · tool · tool::dict_ensemble +
TCLPARAM + pt::peg::to::tclparam +
TDPL + grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
temp file + fileutil +
template processing + textutil::expander +
terminal + term · term::ansi::code · term::ansi::code::attr · term::ansi::code::ctrl · term::ansi::code::macros · term::ansi::ctrl::unix · term::ansi::send · term::interact::menu · term::interact::pager · term::receive · term::receive::bind · term::send +
test + fileutil +
Testing + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
testing + bench · bench::in · bench::out::csv · bench::out::text · bench_intro · bench_lang_intro · bench_lang_spec +
TeX + textutil · textutil::adjust +
text + bench::in · bench::out::text · doctools::idx · doctools::idx::export · doctools::toc · doctools::toc::export +
text comparison + soundex +
text conversion + rcs +
text differences + rcs +
text display + term::interact::menu · term::interact::pager +
text expansion + textutil::expander +
text likeness + soundex +
text processing + bibtex · huddle · page · page_intro · page_pluginmgr · page_util_flow · page_util_norm_lemon · page_util_norm_peg · page_util_peg · page_util_quote · yaml +
text widget + tcl::chan::textwindow +
threads + coroutine · coroutine::auto +
throw + throw +
thumbnail + jpeg +
tie + tie · tie +
tif + tiff +
tiff + tiff +
tile + map::slippy::cache · map::slippy::fetcher +
time + ntp_time +
timestamp + png +
timestamps + debug::timestamp +
tip 219 + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::core +
tip 230 + tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
tip 234 + tcl::transform::zlib +
tip 317 + tcl::transform::base64 +
Tk + tcl::chan::textwindow +
tls + comm · imap4 · pop3 · pop3d · smtp · transfer::connect · transfer::receiver · transfer::transmitter +
TMML + doctools · doctools::idx · doctools::idx · doctools::toc · doctools::toc · dtplite · dtplite · mpexpand +
toc + doctoc_intro · doctoc_plugin_apiref · doctools::toc · doctools::toc::export::doctoc · doctools::toc::export::html · doctools::toc::export::json · doctools::toc::export::nroff · doctools::toc::export::text · doctools::toc::export::wiki · doctools::toc::import::doctoc · doctools::toc::import::json +
toc formatter + doctoc_plugin_apiref +
tokenization + string::token · string::token::shell +
TOOL + tool · tool::dict_ensemble +
top-down parsing languages + grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
torrent + bee +
touch + fileutil +
TPDL + grammar::me_intro +
trace + debug · debug::caller · debug::heartbeat · debug::timestamp +
transducer + grammar::aycock · grammar::fa · grammar::fa::dacceptor · grammar::fa::dexec · grammar::fa::op · grammar::me_intro · grammar::peg · grammar::peg::interp · pt · pt::ast · pt::cparam::configuration::critcl · pt::cparam::configuration::tea · pt::json_language · pt::param · pt::pe · pt::pe::op · pt::peg · pt::peg::container · pt::peg::container::peg · pt::peg::export · pt::peg::export::container · pt::peg::export::json · pt::peg::export::peg · pt::peg::from::container · pt::peg::from::json · pt::peg::from::peg · pt::peg::import · pt::peg::import::container · pt::peg::import::json · pt::peg::import::peg · pt::peg::interp · pt::peg::to::container · pt::peg::to::cparam · pt::peg::to::json · pt::peg::to::param · pt::peg::to::peg · pt::peg::to::tclparam · pt::peg_language · pt::pegrammar · pt::pgen · pt::rde · pt::tclparam::configuration::nx · pt::tclparam::configuration::snit · pt::tclparam::configuration::tcloo · pt::util · pt_export_api · pt_import_api · pt_introduction · pt_parse_peg · pt_parser_api · pt_peg_op +
transfer + transfer::connect · transfer::copy · transfer::copy::queue · transfer::data::destination · transfer::data::source · transfer::receiver · transfer::transmitter +
transformation + page_util_peg · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
transmitter + transfer::transmitter +
travelling salesman + struct::graph::op +
traversal + fileutil_traverse +
tree + grammar::me::cpu::gasm · grammar::me::util · htmlparse · struct::queue · struct::stack · struct::tree · struct::tree_v1 · treeql +
tree query language + treeql +
tree walking + page_util_flow · page_util_norm_lemon · page_util_norm_peg +
TreeQL + treeql +
trimming + textutil · textutil::trim +
twitter + oauth +
type + fileutil · fileutil::magic::cfront · fileutil::magic::cgen · fileutil::magic::filetype · fileutil::magic::rt · snit +
Type checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
+Keywords: U +
uevent + hook +
unbind + uevent +
uncapitalize + textutil::string +
undenting + textutil::adjust +
unicode + stringprep · stringprep::data · unicode · unicode::data +
union + struct::disjointset · struct::set +
unit + units +
unknown hooking + namespacex +
untie + tie · tie +
update + coroutine · coroutine::auto +
uri + uri · uri_urn +
url + doctools::idx · doctools::idx::export · doctools::idx::import · doctools::toc::export · doctools::toc::import · map::geocode::nominatim · map::slippy::fetcher · uri · uri_urn +
urn + uri_urn +
US-NPI + valtype::usnpi +
utilities + namespacex +
uuencode + uuencode +
UUID + uuid +
+Keywords: V +
Validation + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
Value checking + valtype::common · valtype::creditcard::amex · valtype::creditcard::discover · valtype::creditcard::mastercard · valtype::creditcard::visa · valtype::gs1::ean13 · valtype::iban · valtype::imei · valtype::isbn · valtype::luhn · valtype::luhn5 · valtype::usnpi · valtype::verhoeff +
vectors + math::linearalgebra +
verhoeff + valtype::verhoeff +
vertex + struct::graph · struct::graph::op +
vertex cover + struct::graph::op +
virtual channel + tcl::chan::cat · tcl::chan::core · tcl::chan::events · tcl::chan::facade · tcl::chan::fifo · tcl::chan::fifo2 · tcl::chan::halfpipe · tcl::chan::memchan · tcl::chan::null · tcl::chan::nullzero · tcl::chan::random · tcl::chan::std · tcl::chan::string · tcl::chan::textwindow · tcl::chan::variable · tcl::chan::zero · tcl::randomseed · tcl::transform::adler32 · tcl::transform::base64 · tcl::transform::core · tcl::transform::counter · tcl::transform::crc32 · tcl::transform::hex · tcl::transform::identity · tcl::transform::limitsize · tcl::transform::observe · tcl::transform::otp · tcl::transform::rot · tcl::transform::spacer · tcl::transform::zlib +
virtual machine + grammar::me::cpu · grammar::me::cpu::core · grammar::me::cpu::gasm · grammar::me::tcl · grammar::me_intro · grammar::me_vm · grammar::peg::interp · pt::param +
VISA + valtype::creditcard::visa +
vwait + coroutine · coroutine::auto · smtpd +
+Keywords: W +
wais + uri +
widget + snit · snitfaq +
widget adaptors + snit · snitfaq +
wiki + doctools::idx · doctools::idx · doctools::idx::export · doctools::idx::export::wiki · doctools::toc · doctools::toc · doctools::toc::export · doctools::toc::export::wiki +
word + doctools::tcl::parse · wip +
www + uri +
+Keywords: X +
x.208 + asn +
x.209 + asn +
x.500 + ldap +
XGoogleToken + SASL::XGoogleToken +
xml + xsxp +
xor + tcl::transform::otp +
XPath + treeql +
XSLT + treeql +
+Keywords: Y +
yaml + huddle · yaml +
ydecode + yencode +
yEnc + yencode +
yencode + yencode +
+Keywords: Z +
zero + tcl::chan::nullzero · tcl::chan::zero +
zip + zipfile::decode · zipfile::encode · zipfile::mkzip +
zlib + tcl::transform::zlib +
zoom map::slippy · map::slippy::cache · map::slippy::fetcher
Index: idoc/www/tcllib/files/apps/dtplite.html ================================================================== --- idoc/www/tcllib/files/apps/dtplite.html +++ idoc/www/tcllib/files/apps/dtplite.html @@ -1,6 +1,7 @@ - + + dtplite - Documentation toolbox - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

dtplite(n) 1.0.5 tcllib "Documentation toolbox"

Name

dtplite - Lightweight DocTools Markup Processor

@@ -197,11 +198,11 @@

This argument specifies the formatting engine to use when processing the input, and thus the format of the generated document. See section FORMATS for the possibilities recognized by the application.

path inputfile (in)

This argument specifies the path to the file to process. It has to -exist, must be readable, and written in doctools format.

+exist, must be readable, and written in doctools format.

dtplite validate inputfile

This is a simpler form for use case [1]. The "validate" format generates no output at all, only syntax checks are performed. As such the specification of an output file or other options is not necessary @@ -212,11 +213,11 @@ directory instead of a file. The other arguments are identical, except for output, which now has to be the path to an existing and writable directory.

The input documents are all files in inputdirectory or any of its subdirectories which were recognized by fileutil::fileType -as containing text in doctools format.

+as containing text in doctools format.

dtplite -merge -o output ?options? format inputdirectory

This is the form for use case [3]. The only difference to the form for use case [2] is the additional option -merge.

Each such call will merge the generated documents coming from processing the input documents under inputdirectory or any of @@ -417,25 +418,19 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Documentation tools

Index: idoc/www/tcllib/files/apps/nns.html ================================================================== --- idoc/www/tcllib/files/apps/nns.html +++ idoc/www/tcllib/files/apps/nns.html @@ -1,6 +1,7 @@ - + + nns - Name service facility - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

nns(n) 1.1 tcllib "Name service facility"

Name

nns - Name service facility, Commandline Client Application

@@ -147,11 +148,11 @@ Beyond that the application's sources also serve as an example of how to use the client package nameserv. All abilities of a client are covered, from configuration to registration of names to searching.

This name service facility has nothing to do with the Internet's -Domain Name System, otherwise known as DNS. If the +Domain Name System, otherwise known as DNS. If the reader is looking for a package dealing with that please see either of the packages dns and resolv, both found in Tcllib too.

USE CASES

nns was written with the following two main use cases in @@ -219,25 +220,19 @@ bugs and other problems. Please report such in the category nameserv of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Networking

Index: idoc/www/tcllib/files/apps/nnsd.html ================================================================== --- idoc/www/tcllib/files/apps/nnsd.html +++ idoc/www/tcllib/files/apps/nnsd.html @@ -1,6 +1,7 @@ - + + nnsd - Name service facility - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

nnsd(n) 1.0.1 tcllib "Name service facility"

Name

nnsd - Name service facility, Commandline Server Application

@@ -142,11 +143,11 @@ command line server for the nano name service facility provided by the Tcllib packages nameserv, and nameserv::server. Beyond that the application's sources also serve as an example of how to use the server package nameserv::server.

This name service facility has nothing to do with the Internet's -Domain Name System, otherwise known as DNS. If the +Domain Name System, otherwise known as DNS. If the reader is looking for a package dealing with that please see either of the packages dns and resolv, both found in Tcllib too.

USE CASES

nnsd was written with the following main use case in @@ -187,25 +188,19 @@ bugs and other problems. Please report such in the category nameserv of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Networking

Index: idoc/www/tcllib/files/apps/nnslog.html ================================================================== --- idoc/www/tcllib/files/apps/nnslog.html +++ idoc/www/tcllib/files/apps/nnslog.html @@ -1,6 +1,7 @@ - + + nnslog - Name service facility - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

nnslog(n) 1.0 tcllib "Name service facility"

Name

nnslog - Name service facility, Commandline Logging Client Application

@@ -144,11 +145,11 @@

It essentially implements "nns search -continuous *", but uses a different output formatting. Instead of continuously showing the current contents of the server in the terminal it simply logs all received add/remove events to stdout.

This name service facility has nothing to do with the Internet's -Domain Name System, otherwise known as DNS. If the +Domain Name System, otherwise known as DNS. If the reader is looking for a package dealing with that please see either of the packages dns and resolv, both found in Tcllib too.

USE CASES

nnslog was written with the following main use case in mind.

@@ -190,25 +191,19 @@ bugs and other problems. Please report such in the category nameserv of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Networking

Index: idoc/www/tcllib/files/apps/page.html ================================================================== --- idoc/www/tcllib/files/apps/page.html +++ idoc/www/tcllib/files/apps/page.html @@ -1,6 +1,7 @@ - + + page - Development Tools - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

page(n) 1.0 tcllib "Development Tools"

Name

page - Parser Generator

@@ -336,11 +337,11 @@

Readers. The name of the package for the plugin name is "page::reader::name".

We have five predefined plugins:

peg
-

Interprets the input as a parsing expression grammar (PEG) and +

Interprets the input as a parsing expression grammar (PEG) and generates a tree representation for it. Both the syntax of PEGs and the structure of the tree representation are explained in their own manpages.

hb

Interprets the input as Tcl code as generated by the writer plugin @@ -349,11 +350,11 @@

Interprets the input as the serialization of a PEG, as generated by the writer plugin ser, using the package grammar::peg.

lemon

Interprets the input as a grammar specification as understood by -Richard Hipp's LEMON parser generator and generates a tree +Richard Hipp's LEMON parser generator and generates a tree representation for it. Both the input syntax and the structure of the tree representation are explained in their own manpages.

treeser

Interprets the input as the serialization of a struct::tree. It is validated as such, @@ -375,30 +376,30 @@

Assumes that the incoming data structure is a struct::tree and generates an indented textual representation of all nodes, their parental relationships, and their attribute information.

peg

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes it out as a PEG. The +PEG or other other grammar and writes it out as a PEG. The result is nicely formatted and partially simplified (strings as sequences of characters). A pretty printer in essence, but can also be used to obtain a canonical representation of the input grammar.

tpc

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes out Tcl code defining a +PEG or other other grammar and writes out Tcl code defining a package which defines a grammar::peg object containing the grammar when it is loaded into an interpreter.

hb

This is like the writer plugin tpc, but it writes only the statements which define stat expression and grammar rules. The code making the result a package is left out.

ser

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar, transforms it internally into a +PEG or other other grammar, transforms it internally into a grammar::peg object and writes out its serialization.

me

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar and writes out Tcl code defining a +PEG or other other grammar and writes out Tcl code defining a package which implements a memoizing recursive descent parser based on the match engine (ME) provided by the package grammar::mengine.

-t name

Transformers. The name of the package for the plugin name is @@ -405,16 +406,16 @@ "page::transform::name".

We have two predefined plugins:

reach

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar. It determines which nonterminal +PEG or other other grammar. It determines which nonterminal symbols and rules are reachable from start-symbol/expression. All nonterminal symbols which were not reached are removed.

use

Assumes that the incoming data structure is a tree representation of a -PEG or other other grammar. It determines which nonterminal +PEG or other other grammar. It determines which nonterminal symbols and rules are able to generate a finite sequences of terminal symbols (in the sense for a Context Free Grammar). All nonterminal symbols which were not deemed useful in this sense are removed.

@@ -457,25 +458,19 @@ bugs and other problems. Please report such in the category page of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

See Also

page::pluginmgr

Category

Page Parser Generator

Index: idoc/www/tcllib/files/apps/pt.html ================================================================== --- idoc/www/tcllib/files/apps/pt.html +++ idoc/www/tcllib/files/apps/pt.html @@ -1,6 +1,7 @@ - + + pt - Parser Tools - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

pt(n) 1 tcllib "Parser Tools"

Name

pt - Parser Tools Application

@@ -147,11 +148,11 @@ Do you have trouble understanding this document ? In that case please read the overview provided by the Introduction to Parser Tools. This document is the entrypoint to the whole system the current package is a part of.

This document describes pt, the main application of the module, -a parser generator. Its intended audience are people who wish +a parser generator. Its intended audience are people who wish to create a parser for some language of theirs. Should you wish to modify the application instead, please see the section about the application's Internals for the basic references.

It resides in the User Application Layer of Parser Tools.

arch_user_app

@@ -220,11 +221,11 @@ latter case it will be advantageous to lobby for the inclusion of the C-based runtime support (notes below) into the environment to reduce the impact of Tcl's on the speed of these parsers.

The relevant formats are snit and oo. Both place their result into a Tcl package containing a snit::type, or TclOO -class respectively.

+class respectively.

Of the supporting runtime, which is the package pt::rde, the user has to know nothing but that it does exist and that the parsers are dependent on it. Knowledge of the API exported by the runtime for the parsers' consumption is not required by the parsers' users.

Interpreted parsing implemented in Tcl
@@ -493,11 +494,11 @@ The default value is 1.

TclOO Parser

The oo format is executable code, a parser for the grammar. It -is a Tcl package holding a TclOO class, whose instances are +is a Tcl package holding a TclOO class, whose instances are parsers for the input grammar.

This result-format supports the following options:

-file string

The value of this option is the name of the file or other entity from @@ -673,22 +674,16 @@ bugs and other problems. Please report such in the category pt of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Parsing and Grammars

Index: idoc/www/tcllib/files/apps/tcldocstrip.html ================================================================== --- idoc/www/tcllib/files/apps/tcldocstrip.html +++ idoc/www/tcllib/files/apps/tcldocstrip.html @@ -1,6 +1,7 @@ - + + tcldocstrip - Textprocessing toolbox - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

tcldocstrip(n) 1.0 tcllib "Textprocessing toolbox"

Name

tcldocstrip - Tcl-based Docstrip Processor

@@ -177,11 +178,11 @@ documented to stdout.

If the output does not exist then [file dirname $output] has to exist and must be a writable directory.

path inputfile (in)

This argument specifies the path to the file to process. It has to -exist, must be readable, and written in docstrip format.

+exist, must be readable, and written in docstrip format.

tcldocstrip ?options? output (?options? input guards)...

This is the form for use case [2]. It differs from the form for use case [1] by the possibility of having options before the output file, which apply in general, and specifying more than one @@ -260,25 +261,19 @@ bugs and other problems. Please report such in the category docstrip of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Documentation tools

DELETED idoc/www/tcllib/files/devdoc/tcl_community_communication.html Index: idoc/www/tcllib/files/devdoc/tcl_community_communication.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcl_community_communication.html +++ idoc/www/tcllib/files/devdoc/tcl_community_communication.html @@ -1,251 +0,0 @@ - -tcl_community_communication - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcl_community_communication(n) 1 tcllib ""

-

Name

-

tcl_community_communication - Tcl Community - Kind Communication

-
- -

Description

-

The Tcl Community encourages contributions from anyone who wishes to -advance the development of:

-
    -

  • The Tcl Language

    • -

  • Tcl derived languages

    • -

  • Tcl related libraries

    • -

  • Tcl extensions

    • -

  • External Projects that Integrate Tcl

    • -
-

We welcome those contributions from anyone. We are blind to -gender, race, religion, cultural background, cybernetic nature, and -any other demographic characteristics, as well as personal political -views.

-

A community lives and dies by communications. And occasionally -our communications are peppered with patterns that are harsh, -unfriendly, unwelcoming and/or otherwise unkind. As a volunteer -community, we need all of the help we can get. Therefore, we ask all -contributors to make a conscious effort, in Tcl Community discussions, -to communicate in ways that are welcoming. Ways that are -friendly. Ways that are, in a word: kind.

-

These guidelines suggest specific ways to accomplish that goal.

-

Please note: for the balance of this document any reference to -"People", "Persons", "anybody" or "somebody" can refer to any sentient -being, not merely corporeal members of the species Homo Sapien.

-
-
We are a Sanctuary not a Clubhouse
-

The Tcl Community is a collective of amateurs and professionals who -code, test, and use tools. Our community is open to all. There is no -velvet rope. There is no bouncer at the door. There are no secret -handshakes. Any sentient being who enters our midst is welcome. If -someone is ever asked to leave, it is only because they are being -disruptive to the functioning of the community.

-
We Merit Ideas, Not People
-

A good idea can come from anyone, regardless of how little time they -have been with us. A bad idea can come from anyone, regardless of how -much time or how little time they have been with us. We judge a -concept by how it stands up to scrutiny of logic, implementation, and -regression testing. We don’t judge ideas based on who had the idea -first, who agrees with the idea, or who disagrees with it.

-
Treat Everyone with Respect
-

Everyone is deserving of respect and courtesy at all times.

-
Refer to people by the names they use.
-

If grammar requires you to state a gender for a person, honor their -preferences about their gender identity. If you are unsure as to the -gender of an individual, ask. If someone had to guess about your -gender and got it wrong, please correct them and do not take it -personally.

-
Do not take a harsh tone towards other participants.
-

Do not make personal attacks against anyone (participant or not.)

-

Criticize statements and actions, never people.

-
Don’t Take Things Personally
-

When in doubt, assume the best in people. A criticism of your -statements is not a personal attack on you.

-
Persons, not People
-

Stereotypes are an unhelpful tool on many accounts. They are generally -oversimplified. They are usually flat out wrong. And even if "right" -they are of absolutely no utility in determining the capabilities, -motivations, or fitness of an individual.

-

Don’t use them in Tcl Community communications.

-
Mistakes Happen
-

The human condition is a series of trials and errors. Progress is when -we get one more trial than error. Being wrong or making a mistake is -the default state of humanity. Accept the errors of your fellow -sentient beings, and be aware that you are also fallible.

-
Keep it Real
-

Please respond to what people actually say. We are all amazing -individuals, but none among us are mind readers. If you find yourself -responding to what you imagine someone is thinking, odds are you are -going to be wrong.

-

If you must criticize someone, stick to things they have -actually done. Never criticize for something you speculate they have -done. Or imagine they have done. Or something someone who shares some -attribute with them has done in the past.

-

Keep discussions about any non-Tcl subjects to what can be -stated factually and without emotion or judgement.

-
When Trouble Arises, Don’t Escalate
-

If you feel you are being personally attacked or offended, take the -high road. Punching back in a public forum will only makes things -worse. Address the matter in a private correspondence. Be -polite. Express your feelings, but note that you are expressing your -feelings. When writing, look for a way to calm matters down. And when -in doubt, sleep on your letter before pressing send. And when not in -doubt, sleep on it for another day after that.

-

If you are a spectator to a fight in progress, politely request -the two parties take the matter to a more private forum.

-
Always get the Last Word: I’m Sorry
-

If an personal argument does arise, be the first to apologize. An -apology does not concede a logical point. It merely acknowledges that -at some point the discussion left either logic, community decency, or -both. Return to the topic when cooler heads can prevail.

-
Nobody is Keeping Score
-

There is no prize for being right. There is no cost for being wrong. A -hard sell is not going to advance your idea along any more than a -logical argument. You aren’t running for office. This isn’t debate -club. If you find yourself continuing a discussion beyond where a -topic can be logically discussed, stop.

-
No Evangelizing
-

The Tcl Community is not the place to promote your chosen operating -system, political outlook, religion, marketing scheme, or economic -model. Period.

-

(And if you do bring it up, be prepared to have your chosen -topic discussed logically. And odds are, not favorably.)

-
Respect the Community
-

If the Community has come to a decision on a course of action, please -stop arguing.

-

If someone complains about how you are expressing your ideas, -listen.

-

If your words are hurting people, stop. There is no amount of -being "right" that makes up for someone leaving our midst because they -felt insulted, threatened, or ignored.

-
-

By following these guidelines, we will build our community, encourage -more contribution to our projects, and our discussions will be -friendlier and reach conclusions more easily.

-

Thank You.

-
-

Signatories

-
    -

  • Sean "the Hypnotoad" Woods

    • -

  • Andreas Kupries

    • -
-
-

Authors

-
-
Primary
-

Sean "the Hypnotoad" Woods

-
Light editing
-

Andreas Kupries

-
-
-
DELETED idoc/www/tcllib/files/devdoc/tcllib_devguide.html Index: idoc/www/tcllib/files/devdoc/tcllib_devguide.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_devguide.html +++ idoc/www/tcllib/files/devdoc/tcllib_devguide.html @@ -1,982 +0,0 @@ - -tcllib_devguide - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcllib_devguide(n) 1 tcllib ""

-

Name

-

tcllib_devguide - Tcllib - The Developer's Guide

-
- -

Synopsis

-
- -
-
-

Description

-

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl -packages that provide utility functions useful to a large collection -of Tcl programmers.

-

This document is a guide for developers working on Tcllib, -i.e. maintainers fixing bugs, extending the collection's -functionality, etc.

-

Please read

-
    -

  1. Tcllib - How To Get The Sources and

    2. -

  2. Tcllib - The Installer's Guide

    3. -
-

first, if that was not done already.

-

Here we assume that the sources are already available in a -directory of your choice, and that you not only know how to build and -install them, but also have all the necessary requisites to actually -do so. The guide to the sources in particular also explains which -source code management system is used, where to find it, how to set it -up, etc.

-
-

Commitments

-

Contributor

-

As a contributor to Tcllib you are committing yourself to:

-
    -

  1. keep the guidelines written down in - Tcl Community - Kind Communication in your mind. - The main point to take away from there is - to be kind to each other.

    2. -

  2. Your contributions getting distributed under a BSD/MIT license. - For the details see Tcllib - License

    3. -
-

Contributions are made by entering tickets into our tracker, providing -patches, bundles or branches of code for inclusion, or posting to the -Tcllib related mailing lists.

-
-

Maintainer

-

When contributing one or more packages for full inclusion into Tcllib -you are committing yourself to

-
    -

  1. Keep the guidelines written down in - Tcl Community - Kind Communication - (as any contributor) in your mind. The main point to take away - from there is to be kind to each other.

    2. -

  2. Your packages getting distributed under a BSD/MIT license. For - the details see Tcllib - License

    3. -

  3. Maintenance of the new packages for a period of two years under - the following rules, and responsibilities:

    -
      - -

    1. A maintainer may step down after the mandatory period as - they see fit.

      2. -

    2. A maintainer may step down before the end of the - mandatory period, under the condition that a replacement - maintainer is immediately available and has agreed to - serve the remainder of the period, plus their own - mandatory period (see below).

      3. -

    3. When stepping down without a replacement maintainer - taking over the relevant packages have to be flagged as - unmaintained.

      4. -

    4. When a replacement mantainer is brought in for a package - it is (kept) marked as maintained (again).

      -

      A replacement maintainer is bound by the same rules as - the original maintainer, except that the mandatory - period of maintenance is shortened to one year.

      5. -

    5. For any unmaintained package a contributor - interested in becoming its maintainer can become so by - flagging them as maintained with their name and - contact information, committing themselves to the rules - of a replacement maintainer (see previous point).

      6. -

    6. For any already maintained package a contributor - interested in becoming a co-maintainer can become so - with the agreement of the existing maintainer(s), - committing themselves to the rules of a replacement - maintainer (see two points previous).

      7. -
    -

    The responsibilities as a maintainer include:

    -
      - -

    1. Watching Tcllib's ticket tracker for bugs, bug fixes, - and feature requests related to the new packages.

      2. -

    2. Reviewing the aforementioned tickets, rejecting or - applying them

      3. -

    3. Coordination and discussion with ticket submitter during - the development and/or application of bug fixes.

      4. -
    -
    4. -

  4. Follow the Branching and Workflow of this guide.

    5. -
-
-
-

Branching and Workflow

-

Package Dependencies

-

Regarding packages and dependencies between them Tcllib occupies a -middle position between two extremes:

-
    -

  1. On one side a strongly interdependent set of packages, usually - by a single author, for a single project. Looking at my - (Andreas Kupries) own work examples of such are - Marpa, - CRIMP, - Kinetcl, etc.

    -

    For every change the author of the project handles all the - modifications cascading from any incompatibilities it - introduced to the system.

    2. -

  2. On the other side, the world of semi-independent projects by - many different authors where authors know what packages their - own creations depend on, yet usually do not know who else - depends on them.

    -

    The best thing an author making an (incompatible) change to - their project can do is to for one announce such changes in - some way, and for two use versioning to distinguish the code - before and after the change.

    -

    The world is then responsible for adapting, be it by updating - their own projects to the new version, or by sticking to the - old.

    3. -
-

As mentioned already, Tcllib lives in the middle of that.

-

While we as maintainers cannot be aware of all users of - Tcllib's packages, and thus have to rely on the mechanisms - touched on in point 2 above for that, the dependencies between - the packages contained in Tcllib are a different matter.

-

As we are collectively responsible for the usability of Tcllib - in toto to the outside world, it behooves us to be individually - mindful even of Tcllib packages we are not directly - maintaining, when they depend on packages under our - maintainership. - This may be as simple as coordinating with the maintainers of - the affected packages. - It may also require us to choose how to adapt affected packages - which do not have maintainers, i.e. modify them to use our - changed package properly, or modify them to properly depend on - the unchanged version of our package.

-

Note that the above is not only a chore but an opportunity as - well. - Additional insight can be had by forcing ourselves to look at - our package and the planned change(s) from an outside - perspective, to consider the ramifications of our actions on - others in general, and on dependent packages in particular.

-
-

Trunk

-

The management and use of branches is an important part of working -with a Distributed Version Control System (DVCS) like -fossil.

-

For Tcllib the main branch of the collection is - trunk. In git this branch would be called - master, and this is exactly the case in the - github mirror of - Tcllib.

-

To properly support debugging each commit on this - branch has to pass the entire testsuite of the - collection. Using bisection to determine when an issue appeared - is an example of an action made easier by this constraint.

-

This is part of our collective responsibility for the usability - of Tcllib in toto to the outside world. - As fossil has no mechanism to enforce this condition - this is handled on the honor system for developers and maintainers.

-

To make the task easier Tcllib comes with a tool - ("sak.tcl") providing a number of commands in - support. These commands are explained in the following sections - of this guide.

-

While it is possible and allowed to commit directly to trunk - remember the above constraint regarding the testsuite, and the - coming notes about other possible issues with a commit.

-
-

Branches

-

Given the constraints placed on the trunk branch of the -repository it is (strongly) recommended to perform any development -going beyond trivial changes on a non-trunk branch.

-

Outside of the trunk developers are allowed to commit - intermediate broken states of their work. - Only at the end of a development cycle, when the relevant - branch is considered ready for merging, will it be necessary to - perform full the set of validations ensuring that the merge to - come will create a good commit on trunk.

-

Note that while a review from a second developer is not a - required condition for merging a branch it is recommended to - seek out such an independent opinion as a means of - cross-checking the work.

-

It also recommended to give any new branch a name which aids in - determining additional details about it. Examples of good - things to stick into a branch name would be

-
    -

  • Developer (nick)name

    • -

  • Ticket hash/reference

    • -

  • One or two keywords applicable to the work

    • -

  • ...

    • -
-

Further, while most development branches are likely quite - short-lived, no prohibitions exist against making longer-lived - branches. - Creators should however be mindful that the longer such a - branch exists without merges the more divergent they will tend - to be, with an associated increase in the effort which will - have to be spent on either merging from and merging to trunk.

-
-

Working with Branches

-

In the hope of engendering good work practices now a few example -operations which will come up with branches, and their associated -fossil command (sequences).

-
-
Awareness
-

When developing we have to keep ourselves aware of the context of our -work. On what branch are we ? What files have we changed ? What new -files are not yet known to the repository ? What has happened remotely -since we used our checkout ? -The answers to these questions become especially important when using -a long-lived checkout and coming back to it after some time away.

-

Commands to answer questions like the above are:

-
-
fossil pull
-

Get all changes done on the remote since the last pull or sync - from it. This has to be done first, before any of the commands - below.

-

Even if the commit in our checkout refers to the branch we want - right now control operations committed to the remote may have - changed that from underneath us.

-
fossil info | grep tags
-
-
fossil branch list | grep '\*'
-

Two different ways of determining the branch our checkout is - on.

-
fossil timeline
-

What have we (and others) done recently ?

-

Attention, this information is very likely outdated, the - more the longer we did not use this checkout. - Run fossil pull first to get latest information from - the remote repository of the project.

-
fossil timeline current
-

Place the commit our checkout is based on at the top of the - timeline.

-
fossil changes
-

Lists the files we have changed compared to the commit the - checkout is based on.

-
fossil extra
-

Lists the files we have in the checkout the repository does not - know about. This may be leftover chaff from our work, or - something we have forgotten to fossil add to the - repository yet.

-
-
Clean checkouts
-

Be aware of where you are (see first definition).

-

For pretty much all the operation recipes below a clean - checkout is at least desired, often required. - To check that a checkout is clean invoke

-
-    fossil changes
-    fossil extra
-
-

How to clean up when uncommitted changes of all sorts are found is -context-specific and outside of the scope of this guide.

-
Starting a new branch
-

Be aware of where you are (see first definition).

-

Ensure that you have clean checkout (see second definition). - It is required.

-

In most situations you want to be on branch trunk, and - you want to be on the latest commit for it. To get there use

-
-    fossil pull
-    fossil update trunk
-
-

If some other branch is desired as the starting point for the coming -work replace trunk in the commands above with the name of that -branch.

-

With the base line established we now have two ways of creating - the new branch, with differing (dis)advantages. - The simpler way is to

-
-    fossil branch new NAME_OF_NEW_BRANCH
-
-

and start developing. The advantage here is that you cannot forget to -create the branch. The disadvantages are that we have a branch commit -unchanged from where we branched from, and that we have to use -high-handed techniques like hiding or shunning to get rid of the -commit should we decide to abandon the work before the first actual -commit on the branch.

-

The other way of creating the branch is to start developing, -and then on the first commit use the option --branch to tell -fossil that we are starting a branch now. I.e. run

-
-    fossil commit --branch NAME_OF_NEW_BRANCH ...
-
-

where ... are any other options used to supply the commit -message, files to commit, etc.

-

The (dis)advantages are now reversed.

-

We have no superflous commit, only what is actually - developed. The work is hidden until we commit to make our first - commit.

-

We may forget to use --branch NAME_OF_NEW_BRANCH and - then have to correct that oversight via the fossil web - interface (I am currently unaware of ways of doing such from - the command line, although some magic incantantion of - fossil tag create may work).

-

It helps to keep awareness, like checking before any commit - that we are on the desired branch.

-
Merging a branch into trunk
-

Be aware of where you are (see first definition).

-

Ensure that you have clean checkout (see second definition). - In the full-blown sequence (zig-zag) it is required, due - to the merging from trunk. In the shorter sequence it is only - desired. That said, keeping the checkout clean before - any major operations is a good habit to have, in my opinion.

-

The full-blown sequencing with checks all the way is to

-
    -

  1. Validate the checkout, i.e. last commit on your branch. Run the - full test suite and other validations, fix all the issues which - have cropped up.

    2. -

  2. Merge the latest state of the trunk (see next definition).

    3. -

  3. Validate the checkout again. The incoming trunk changes may - have broken something now. Do any required fixes.

    4. -

  4. Now merge to the trunk using

    -
    -    fossil update trunk
-    fossil merge --integrate YOUR_BRANCH
-
    -
    5. -

  5. At this point the checkout should be in the same state as at - the end of point (3) above, because we resolved any issues with - the trunk already. Thus a simple

    -
    -    fossil commit ...
-
    -

    should be sufficient now to commit the merge back and close the - branch (due to the --integrate we used on the merge).

    -

    The more paranoid may validate the checkout a third time before - commiting.

    6. -
-

I call this a zig-zag merge because of how the arrows - look in the timeline, from trunk to feature branch for the - first merge, and then back for the final merge.

-

A less paranoid can do what I call a simple merge, - which moves step (2) after step (4) and skips step (3) - entirely. The resulting shorter sequence is

-
    -

  1. Validate

    2. -

  2. Merge to trunk

    3. -

  3. Validate again

    4. -

  4. Commit to trunk

    5. -
-

The last step after either zig-zag or plain merge is to

-
-    fossil sync
-
-

This saves our work to the remote side, and further gives us any other -work done while we were doing our merge. It especially allows us to -check if we raced somebody else, resulting in a split trunk.

-

When that happens we should coordinate with the other developer - on who fixes the split, to ensure that we do not race each - other again.

-
Merging from trunk
-

Be aware of where you are (see first definition).

-

Ensure that you have clean checkout (see second definition). - It is required.

-

In most situations you want to import the latest commit of - branch trunk (or other origin). To get it use

-
-    fossil pull
-
-

With that done we can now import this commit into our current - branch with

-
-    fossil merge trunk
-
-

Even if fossil does not report any conflicts it is a - good idea to check that the operation has not broken the new - and/or changed functionality we are working on.

-

With the establishment of a good merge we then save the state - with

-
-    fossil commit ...
-
-

before continuing development.

-
-
-

Version numbers

-

In Tcllib all changes to a package have to come with an increment of -its version number. What part is incremented (patchlevel, minor, major -version) depends on the kind of change made. With multiple changes in -a commit the highest "wins".

-

When working in a development branch the version change can be - deferred until it is time to merge, and then has to cover all - the changes in the branch.

-

Below a list of the kinds of changes and their associated - version increments:

-
-
D - documentation
-

No increment

-
T - testsuite
-

No increment

-
B - bugfix
-

Patchlevel

-
I - implementation tweak
-

Patchlevel

-
P - performance tweak
-

Patchlevel

-
E - backward-compatible extension
-

Minor

-
API - incompatible change
-

Major

-
-

Note that a commit containing a version increment has to - mention the new version number in its commit message, as well - as the kind of change which caused it.

-

Note further that the version number of a package currently - exists in three places. An increment has to update all of them:

-
    -

  1. The package implementation.

    2. -

  2. The package index ("pkgIndex.tcl")

    3. -

  3. The package documentation.

    4. -
-

The "sak.tcl" command validate version helps - finding discrepancies between the first two. - All the other validate methods are also of interest to - any developer. Invoke it with

-
 sak.tcl help validate
-

to see their documentation.

-
-
-

Structural Overview

-

Main Directories

-

The main directories in the Tcllib toplevel directory and of interest -to a developer are:

-
-
"modules"
-

Each child directory represents one or more packages. -In the case of the latter the packages are usually related in some -way. Examples are "base64", "math", and "struct", with -loose (base64) to strong (math) relations between the packages in the -directory.

-
"apps"
-

This directory contains all the installable applications, with their -documentation. Note that this directory is currently not split -into sub-directories.

-
"examples"
-

Each child directory "foo" contains one or more example -application for the packages in "modules/foo". These examples are -generally not polished enough to be considered for installation.

-
-
-

More Directories

-
-
"config"
-

This directory contains files supporting the Unix build system, -i.e. "configure" and "Makefile.in".

-
"devdoc"
-

This directories contains the doctools sources for the global -documentation, like this document and its sibling guides.

-
"embedded"
-

This directory contains the entire documentation formatted for -HTML and styled to properly mix into the web site generated by -fossil for the repository.

-

This is the documentation accessible from the Tcllib home -directory, represented in the repository as "embedded/index.md".

-
"idoc"
-

This directory contains the entire documentation formatted for -nroff and HTML, the latter without any styling. -This is the documentation which will be installed.

-
"support"
-

This directory contains the sources of internal packages and utilities -used in the implementation of the "installer.tcl" and -"sak.tcl" scripts/tools.

-
-
-

Top Files

-
-
"aclocal.m4"
-
-
"configure"
-
-
"configure.in"
-
-
"Makefile.in"
-

These four files comprise the Unix build system layered on top of the -"installer.tcl" script.

-
"installer.tcl"
-

The Tcl-based installation script/tool.

-
"project.shed"
-

Configuration file for Sean Wood's PracTcl -buildsystem.

-
"sak.tcl"
-

This is the main tool for developers and release managers, the -Swiss Army Knife of management operations on the collection.

-
"ChangeLog"
-

The log of changes to the global support, when the sources were held -in CVS. Not relevant any longer with the switch to the -fossil SCM.

-
"license.terms"
-

The license in plain ASCII. See also Tcllib - License for the -nicely formatted form. The text is identical.

-
"README.md"
-
-
".github/CONTRIBUTING.md"
-
-
".github/ISSUE_TEMPLATE.md"
-
-
".github/PULL_REQUEST_TEMPLATE.md"
-

These markdown-formatted documents are used and shown by the github -mirror of these sources, pointing people back to the official location -and issue trackers.

-
"DESCRIPTION.txt"
-
-
"STATUS"
-
-
"tcllib.spec"
-
-
"tcllib.tap"
-
-
"tcllib.yml"
-

????

-
-
-

File Types

-

The most common file types, by file extension, are:

-
-
".tcl"
-

Tcl code for a package, application, or example.

-
".man"
-

Doctools-formatted documentation, usually for a package.

-
".test"
-

Test suite for a package, or part of. -Based on tcltest.

-
".bench"
-

Performance benchmarks for a package, or part of. -Based on "modules/bench".

-
".pcx"
-

Syntax rules for TclDevKit's tclchecker. Using these -rules allows the checker to validate the use of commands of a Tcllib -package foo without having to scan the ".tcl" files -implementing it.

-
-
-
-

Testsuite Tooling

-

Testsuites in Tcllib are based on Tcl's standard test package -tcltest, plus utilities found in the directory -"modules/devtools"

-

Tcllib developers invoke the suites through the -test run method of the "sak.tcl" tool, with other methods -of test providing management operations, for example setting a -list of standard Tcl shells to use.

-

Invoke the testsuites of a specific module

-

Invoke either

-
  ./sak.tcl test run foo
-

or

-
  ./sak.tcl test run modules/foo
-

to invoke the testsuites found in a specific module "foo".

-
-

Invoke the testsuites of all modules

-

Invoke the tool without a module name, i.e.

-
  ./sak.tcl test run
-

to invoke the testsuites of all modules.

-
-

Detailed Test Logs

-

In all the previous examples the test runner will write a combination -of progress display and testsuite log to the standard output, showing -for each module only the tests that passed or failed and how many of -each in a summary at the end.

-

To get a detailed log, it is necessary to invoke the test -runner with additional options.

-

For one:

-
-   ./sak.tcl test run --log LOG foo
-
-

While this shows the same short log on the terminal as before, it also -writes a detailed log to the file "LOG.log", and excerpts to -other files ("LOG.summary", "LOG.failures", etc.).

-

For two:

-
-  ./sak.tcl test run -v foo
-
-

This writes the detailed log to the standard output, instead of the -short log.

-

Regardless of form, the detailed log contains a list of all test -cases executed, which failed, and how they failed (expected versus -actual results).

-
-

Shell Selection

-

By default the test runner will use all the Tcl shells specified via -test add to invoke the specified testsuites, if any. If no -such are specified it will fall back to the Tcl shell used to run the -tool itself.

-

Use option --shell to explicitly specify the Tcl shell -to use, like

-
-  ./sak.tcl test run --shell /path/to/tclsh ...
-
-
-

Help

-

Invoke the tool as

-
  ./sak.tcl help test
-

to see the detailed help for all methods of test, and the -associated options.

-
-
-

Documentation Tooling

-

The standard format used for documentation of packages and other -things in Tcllib is doctools. -Its supporting packages are a part of Tcllib, see the directories -"modules/doctools" and "modules/dtplite". The latter is -an application package, with the actual application -"apps/dtplite" a light wrapper around it.

-

Tcllib developers gain access to these through the doc -method of the "sak.tcl" tool, another (internal) wrapper around -the "modules/dtplite" application package.

-

Generate documentation for a specific module

-

Invoke either

-
  ./sak.tcl doc html foo
-

or

-
  ./sak.tcl doc html modules/foo
-

to generate HTML for the documentation found in the module "foo". -Instead of html any other supported format can be used here, -of course.

-

The generated formatted documentation will be placed into a -directory "doc" in the current working directory.

-
-

Generate documentation for all modules

-

Invoke the tool without a module name, i.e.

-
  ./sak.tcl doc html
-

to generate HTML for the documentation found in all modules. -Instead of html any other supported format can be used here, -of course.

-

The generated formatted documentation will be placed into a -directory "doc" in the current working directory.

-
-

Available output formats, help

-

Invoke the tool as

-
  ./sak.tcl help doc
-

to see the entire set of supported output formats which can be -generated.

-
-

Validation without output

-

Note the special format validate.

-

Using this value as the name of the format to generate forces -the tool to simply check that the documentation is syntactically -correct, without generating actual output.

-

Invoke it as either

-
  ./sak.tcl doc validate (modules/)foo
-

or

-
  ./sak.tcl doc validate
-

to either check the packages of a specific module or check all of -them.

-
-
-

Notes On Writing A Testsuite

-

While previous sections talked about running the testsuites for a -module and the packages therein, this has no meaning if the module in -question has no testsuites at all.

-

This section gives a very basic overview on possible -methodologies for writing tests and testsuites.

-

First there are "drudgery" tests. Written to check absolutely -basic assumptions which should never fail.

-

For example for a command FOO taking two arguments, three tests -calling it with zero, one, and three arguments. The basic checks that -the command fails if it has not enough arguments, or too many.

-

After that come the tests checking things based on our -knowledge of the command, about its properties and assumptions. Some -examples based on the graph operations added during Google's Summer of -Code 2009 are:

-
    -

  • The BellmanFord command in struct::graph::ops takes a - startnode as argument, and this node should be a node of - the graph. This equals one test case checking the behavior when the - specified node is not a node of the graph.

    -

    This often gives rise to code in the implementation which - explicitly checks the assumption and throws an understandable error, - instead of letting the algorithm fail later in some weird - non-deterministic way.

    -

    It is not always possible to do such checks. The graph argument - for example is just a command in itself, and while we expect - it to exhibit a certain interface, i.e. a set of sub-commands - aka methods, we cannot check that it has them, except by - actually trying to use them. That is done by the algorithm - anyway, so an explicit check is just overhead we can get by - without.

    • -

  • IIRC one of the distinguishing characteristic of either - BellmanFord and/or Johnson is that they are able to handle - negative weights. Whereas Dijkstra requires positive weights.

    -

    This induces (at least) three testcases ... Graph with all - positive weights, all negative, and a mix of positive and - negative weights. - Thinking further does the algorithm handle the weight - 0 as well ? Another test case, or several, if we mix - zero with positive and negative weights.

    • -

  • The two algorithms we are currently thinking about are about - distances between nodes, and distance can be 'Inf'inity, - i.e. nodes may not be connected. This means that good test - cases are

    -
      - -

    1. Strongly connected graph

      2. -

    2. Connected graph

      3. -

    3. Disconnected graph.

      4. -
    -

    At the extremes of strongly connected and disconnected - we have the fully connected graphs and graphs without edges, - only nodes, i.e. completely disconnected.

    • -

  • IIRC both of the algorithms take weighted arcs, and fill in a - default if arcs are left unweighted in the input graph.

    -

    This also induces three test cases:

    -
      - -

    1. Graph will all arcs with explicit weights.

      2. -

    2. Graph without weights at all.

      3. -

    3. Graph with mixture of weighted and unweighted graphs.

      4. -
    -
    • -
-

What was described above via examples is called -black-box testing. Test cases are designed and written based on -the developer's knowledge of the properties of the algorithm and its -inputs, without referencing a particular implementation.

-

Going further, a complement to black-box testing is -white-box. For this we know the implementation of the -algorithm, we look at it and design our tests cases so that they force -the code through all possible paths in the implementation. Wherever a -decision is made we have a test case forcing a specific direction of -the decision, for all possible combinations and directions. It is easy -to get a combinatorial explosion in the number of needed test-cases.

-

In practice I often hope that the black-box tests I have made -are enough to cover all the paths, obviating the need for white-box -tests.

-

The above should be enough to make it clear that writing tests -for an algorithm takes at least as much time as coding the algorithm, -and often more time. Much more time. -See for example also http://sqlite.org/testing.html, a writeup -on how the Sqlite database engine is tested. Another article of -interest might be https://www.researchgate.net/publication/298896236. -While geared to a particular numerical algorithm it still shows that -even a simple-looking algorithm can lead to an incredible number of -test cases.

-

An interesting connection is to documentation. In one -direction, the properties checked with black-box testing are exactly -the properties which should be documented in the algorithm's man -page. And conversely, the documentation of the properties of an -algorithm makes a good reference to base the black-box tests on.

-

In practice test cases and documentation often get written -together, cross-influencing each other. And the actual writing of test -cases is a mix of black and white box, possibly influencing the -implementation while writing the tests. Like writing a test for a -condition like startnode not in input graph serving as -reminder to put a check for this condition into the code.

-
-

Installation Tooling

-

A last thing to consider when adding a new package to the collection -is installation.

-

How to use the "installer.tcl" script is documented -in Tcllib - The Installer's Guide.

-

Here we document how to extend said installer so that it may -install new package(s) and/or application(s).

-

In most cases only a single file has to be modified, the -"support/installation/modules.tcl" holding one command per module -and application to install.

-

The relevant commands are:

-
-
Module name code-action doc-action example-action
-

Install the packages of module name, found in -"modules/name".

-

The code-action is responsible for installing the -packages and their index. The system currently provides

-
-
_tcl
-

Copy all ".tcl" files found in -"modules/name" into the installation.

-
_tcr
-

As _tcl, copy the ".tcl" files found in -the subdirectories of "modules/name" as well.

-
_tci
-

As _tcl, and copy the "tclIndex.tcl" file -as well.

-
_msg
-

As _tcl, and copy the subdirectory "msgs" -as well.

-
_doc
-

As _tcl, and copy the subdirectory -"mpformats" as well.

-
_tex
-

As _tcl, and copy ".tex" files as well.

-
-

The doc-action is responsible for installing the package -documentation. The system currently provides

-
-
_null
-

No documentation available, do nothing.

-
_man
-

Process the ".man" files found in -"modules/name" and install the results (nroff and/or HTML) -in the proper location, as given to the installer.

-

This is actually a fallback, normally the installer uses the -pre-made formatted documentation found under "idoc".

-
-

The example-action is responsible for installing the -examples. The system currently provides

-
-
_null
-

No examples available, do nothing.

-
_exa
-

Copy the the directory "examples/name" -recursively to the install location for examples.

-
-
Application name
-

Install the application with name, found in "apps".

-
Exclude name
-

This command signals to the installer which of the listed modules to -not install. I.e. they name the deprecated modules of Tcllib.

-
-

If, and only if the above actions are not suitable for the new -module then a second file has to be modified, -"support/installation/actions.tcl".

-

This file contains the implementations of the available -actions, and is the place where any custom action needed to handle the -special circumstances of module has to be added.

-
-
DELETED idoc/www/tcllib/files/devdoc/tcllib_installer.html Index: idoc/www/tcllib/files/devdoc/tcllib_installer.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_installer.html +++ idoc/www/tcllib/files/devdoc/tcllib_installer.html @@ -1,393 +0,0 @@ - -tcllib_install_guide - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcllib_install_guide(n) 1 tcllib ""

-

Name

-

tcllib_install_guide - Tcllib - The Installer's Guide

-
- -

Description

-

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl -packages that provide utility functions useful to a large collection -of Tcl programmers.

-

The audience of this document is anyone wishing to build and install -the packages found in Tcllib, for either themselves, or others.

-

For developers intending to work on the packages themselves we -additionally provide

-
    -

  1. Tcllib - The Developer's Guide.

    2. -
-

Please read Tcllib - How To Get The Sources first, if that -was not done already. Here we assume that the sources are already -available in a directory of your choice.

-
-

Requisites

-

Before Tcllib can be build and used a number of requisites must be installed. -These are:

-
    -

  1. The scripting language Tcl. - For details see Tcl.

    2. -

  2. Optionally, the critcl package (C embedding) for Tcl. - For details see CriTcl.

    3. -
-

This list assumes that the machine where Tcllib is to be installed is -essentially clean. Of course, if parts of the dependencies listed -below are already installed the associated steps can be skipped. It is -still recommended to read their sections though, to validate that the -dependencies they talk about are indeed installed.

-

Tcl

-

As we are installing a number of Tcl packages and applications it -should be pretty much obvious that a working installation of Tcl -itself is needed, and I will not belabor the point.

-

Out of the many possibilities use whatever you are comfortable -with, as long as it provides at the very least Tcl 8.2, or higher. -This may be a Tcl installation provided by your operating system -distribution, from a distribution-independent vendor, or built by -yourself.

-

Note that the packages in Tcllib have begun to require -8.4, 8.5, and even 8.6. Older versions of Tcl will not be able to use -such packages. Trying to use them will result in -package not found errors, as their package index files will -not register them in versions of the core unable to use them.

-

Myself, I used (and still use) -ActiveState's -ActiveTcl 8.5 distribution during development, as I am most familiar -with it.

-

(Disclosure: I, Andreas Kupries, worked for ActiveState until 2016, maintaining ActiveTcl and TclDevKit for them).. -I am currently working for SUSE Software Canada ULC, although not in -Tcl-related areas.

-

This distribution can be found at -http://www.activestate.com/activetcl. Retrieve the archive of -ActiveTcl 8.5 (or higher) for your platform and install it as directed -by ActiveState.

-

For those wishing to build and install Tcl on their own, the -relevant sources can be found at

-
-
Tcl
-

http://core.tcl-lang.org/tcl/

-
-

together with the necessary instructions on how to build it.

-

If there are problems with building, installing, or using Tcl, -please file a ticket against Tcl, or the vendor of your -distribution, and not Tcllib.

-
-

Critcl

-

The critcl tool is an optional dependency.

-

It is only required when trying to build the C-based -accelerators for a number of packages, as explained in -Critcl & Accelerators

-

Tcllib's build system looks for it in the , -using the name critcl. This is for Unix. -On Windows on the other hand the search is more complex. First we look -for a proper application critcl.exe. When that is not found -we look for a combination of interpreter (tclkitsh.exe, -tclsh.exe) and starkit (critcl.kit, critcl) -instead. Note that the choice of starkit can be overriden via -the environment variable .

-

Tcllib requires Critcl version 2 or higher.

-

The github repository providing releases of version 2 and -higher, and the associated sources, can be found at -http://andreas-kupries.github.com/critcl.

-

Any branch of the repository can be used (if not using the -prebuild starkit or starpack), although the use of the stable branch -master is recommended.

-

At the above url is also an explanation on how to build and -install Critcl, including a list of its dependencies.

-

Its instructions will not be repeated here. If there are -problems with these directions please file a ticket against the -Critcl project, and not Tcllib.

-
-
-

Build & Installation Instructions

-

As Tcllib is mainly a bundle of packages written in pure Tcl building -it is the same as installing it. The exceptions to this have their own -subsection, Critcl & Accelerators, later on.

-

Before that however comes the standard case, differentiated by - the platforms with material differences in the instruction, i.e. - Unix-like, versus Windows.

-

Regarding the latter it should also be noted that it is - possible set up an Unix-like environment using projects - like MSYS, Cygwin, and others. In that case the - user has the choice of which instructions to follow.

-

Regardless of environment or platform, a suitable Tcl - has to be installed, and its tclsh should be placed on - the (Unix) or associated with - ".tcl" files (Windows).

-

Installing on Unix

-

For Unix-like environments Tcllib comes with the standard set -of files to make

-
-  ./configure
-  make install
-
-

a suitable way of installing it. -This is a standard non-interactive install automatically figuring out -where to place everything, i.e. packages, applications, and the -manpages.

-

To get a graphical installer invoke

-
-  ./installer.tcl
-
-

instead.

-
-

Installing on Windows

-

In a Windows environment we have the installer.tcl script to -perform installation.

-

If the desired tclsh is associated ".tcl" files - then double-clicking / opening the installer.tcl is - enough to invoke it in graphical mode. - This assumes that Tk is installed and available as well.

-

Without Tk the only way to invoke the installer are to - open a DOS window, i.e. cmd.exe, and then to invoke

-
-  ./installer.tcl
-
-

inside it.

-
-

Critcl & Accelerators

-

While the majority of Tcllib consists of packages written in pure Tcl -a number of packages also have accelerators associated with them. -These are critcl-based C packages whose use will boost the -performance of the packages using them. -These accelerators are optional, and they are not built by default. -If they are built according to the instructions below then they will -also be installed as well.

-

To build the accelerators the normally optional dependency on - critcl becomes required.

-

To build and install Tcllib with the accelerators in a - Unix-like environment invoke:

-
-  ./configure
-  make critcl  # Builds the shared library and package holding
-               # the accelerators, tcllibc
-  make install # Installs all packages, including the new tcllibc.
-
-

The underlying tool is "sak.tcl" in the toplevel directory -of Tcllib and the command make critcl is just a wrapper around

-
-  ./sak.tcl critcl
-
-

Therefore in a Windows environment instead invoke

-
-  ./sak.tcl critcl
-  ./installer.tcl
-
-

from within a DOS window, i.e. cmd.exe.

-
-

Tooling

-

The core of Tcllib's build system is the script "installer.tcl" -found in the toplevel directory of a checkout or release.

-

The

-
-         configure ; make install
-
-

setup available to - developers on Unix-like systems is just a wrapper around it. - To go beyond the standard embodied in the wrapper it is - necessary to directly invoke this script.

-

On Windows system using it directly is the only way to invoke - it.

-

For basic help invoke it as

-
-         ./installer.tcl -help
-
-

This will print a short list of all the available options to - the standard output channel.

-

The commands associated with the various install targets - in the Makefile.in for Unix can be used as additional - examples on how to use this tool as well.

-

The installer can operate in GUI and CLI modes. - By default it chooses the mode automatically, based on if the - Tcl package Tk can be used or not. - The option -no-gui can be used to force CLI mode.

-

Note that it is possible to specify options on the command line - even if the installer ultimatively selects GUI mode. In that - case the hardwired defaults and the options determine the data - presented to the user for editing.

-

The installer will select a number of defaults for the - locations of packages, examples, and documentation, and also - the format of the documentation. The user can overide these - defaults in the GUI, or by specifying additional options. - The defaults depend on the platform detected (Unix/Windows) and - on the tclsh executable used to run the installer.

-

Options

-
-
-help
-

Show the list of options explained here on the standard output channel -and exit.

-
+excluded
-

Include deprecated packages in the installation.

-
-no-gui
-

Force command line operation of the installer

-
-no-wait
-

In CLI mode the installer will by default ask the user to confirm that -the chosen configuration (destination paths, things to install) is -correct before performing any action. Using this option causes the -installer to skip this query and immediately jump to installation.

-
-app-path path
-
-
-example-path path
-
-
-html-path path
-
-
-nroff-path path
-
-
-pkg-path path
-

Declare the destination paths for the applications, examples, html -documentation, nroff manpages, and packages. The defaults are derived -from the location of the tclsh used to run the installer.

-
-dry-run
-
-
-simulate
-

Run the installer without modifying the destination directories.

-
-apps
-
-
-no-apps
-
-
-examples
-
-
-no-examples
-
-
-pkgs
-
-
-no-pkgs
-
-
-html
-
-
-no-html
-
-
-nroff
-
-
-no-nroff
-

(De)activate the installation of applications, examples, packages, -html documentation, and nroff manpages.

-

Applications, examples, and packages are installed by default.

-

On Windows the html documentation is installed by default.

-

On Unix the nroff manpages are installed by default.

-
-
-
-
DELETED idoc/www/tcllib/files/devdoc/tcllib_license.html Index: idoc/www/tcllib/files/devdoc/tcllib_license.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_license.html +++ idoc/www/tcllib/files/devdoc/tcllib_license.html @@ -1,162 +0,0 @@ - -tcllib_license - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcllib_license(n) 1 tcllib ""

-

Name

-

tcllib_license - Tcllib - License

-
- -

Description

-

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl -packages that provide utility functions useful to a large collection -of Tcl programmers.

-

The collection is under the BSD license.

-
-

License

-

This software is copyrighted by Ajuba Solutions and other parties. -The following terms apply to all files associated with the software -unless explicitly disclaimed in individual files.

-

The authors hereby grant permission to use, copy, modify, distribute, -and license this software and its documentation for any purpose, -provided that existing copyright notices are retained in all copies -and that this notice is included verbatim in any distributions. No -written agreement, license, or royalty fee is required for any of the -authorized uses. Modifications to this software may be copyrighted by -their authors and need not follow the licensing terms described here, -provided that the new terms are clearly indicated on the first page of -each file where they apply.

-

IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY -FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY -DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE.

-

THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND -NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND -THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE -MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

-

GOVERNMENT USE: If you are acquiring this software on behalf of the -U.S. government, the Government shall have only "Restricted Rights" in -the software and related documentation as defined in the Federal -Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you -are acquiring the software on behalf of the Department of Defense, the -software shall be classified as "Commercial Computer Software" and the -Government shall have only "Restricted Rights" as defined in Clause -252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the -authors grant the U.S. Government and others acting in its behalf -permission to use and distribute the software in accordance with the -terms specified in this license.

-
-
DELETED idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html Index: idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html +++ idoc/www/tcllib/files/devdoc/tcllib_releasemgr.html @@ -1,199 +0,0 @@ - -tcllib_releasemgr - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcllib_releasemgr(n) 1 tcllib ""

-

Name

-

tcllib_releasemgr - Tcllib - The Release Manager's Guide

-
- -

Description

-

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl -packages that provide utility functions useful to a large collection -of Tcl programmers.

-

The audience of this document is the release manager for Tcllib, their -deputies, and anybody else interested in the task of creating -an official release of Tcllib for distribution.

-

Please read Tcllib - How To Get The Sources first, if that -was not done already. Here we assume that the sources are already -available in a directory of your choice.

-
-

Tools

-

The "sak.tcl" script in the toplevel directory of a Tcllib -checkout is the one tool used by the release manager to perform its -Tasks.

-

The main commands to be used are

-
-    sak.tcl validate
-    sak.tcl test run
-    sak.tcl review
-    sak.tcl readme
-    sak.tcl localdoc
-    sak.tcl release
-
-

More detail will be provided in the explanations of the various -Tasks.

-
-

Tasks

-

Start a release candidate

-

todo: open a candidate for release

-
-

Ready the candidate

-

todo: test, validate and check that the candidate is worthy of release -fix testsuites, possibly fix packages, documentation -regenerate docs -coordinate with package maintainers wrt fixes -big thing: going over the packages, classify changes since last -release to generate a nice readme.

-
-

Make it official

-

todo: finalize release, make candidate official

-
-

Distribute the release

-

With the release made it has to be published and the world notified of -its existence.

-
    -

  1. Create a proper fossil event for the release, via - http://core.tcl-lang.org/tcllib/eventedit.

    -

    An existing event should be used as template.

    2. -

  2. Update a number of web locations:

    -
      -

    1. Home page

      2. -

    2. Downloads

      3. -

    3. Past Releases

      4. -

    4. http://www.tcl-lang.org/home/release.txt

      5. -

    5. http://www.tcl-lang.org/software/tcllib/*.tml

      6. -

    6. http://wiki.tcl-lang.org/page/Tcllib

      7. -
    -

    The first location maps to the file "embedded/index.md" in the -repository itself, as such it can edited as part of the release -process. This is where reference to the new fossil event is added, as -the new current release.

    -

    The next two locations are in the fossil tcllib wiki and -require admin or wiki write permissions for -http://core.tcl-lang.org/tcllib.

    -

    The last two locations require ssh access to -http://www.tcl-lang.org and permission to edit -files in the web area.

    3. -

  3. ***TODO*** mailing lists and other places to send notes to.

    4. -
-
-
-
DELETED idoc/www/tcllib/files/devdoc/tcllib_sources.html Index: idoc/www/tcllib/files/devdoc/tcllib_sources.html ================================================================== --- idoc/www/tcllib/files/devdoc/tcllib_sources.html +++ idoc/www/tcllib/files/devdoc/tcllib_sources.html @@ -1,169 +0,0 @@ - -tcllib_sources - - - - - -
[ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
-
-

tcllib_sources(n) 1 tcllib ""

-

Name

-

tcllib_sources - Tcllib - How To Get The Sources

-
- -

Description

-

Welcome to Tcllib, the Tcl Standard Library. Note that Tcllib is not a -package itself. It is a collection of (semi-independent) Tcl -packages that provide utility functions useful to a large collection -of Tcl programmers.

-

The audience of this document is anyone wishing to either have just a -look at Tcllib's source code, or build the packages, or to extend and -modify them.

-

For builders and developers we additionally provide

-
    -

  1. Tcllib - The Installer's Guide.

    2. -

  2. Tcllib - The Developer's Guide.

    3. -
-

respectively.

-
-

Source Location

-

The official repository for Tcllib can be found at -http://core.tcl-lang.org/tcllib

-
-

Retrieval

-

Assuming that you simply wish to look at the sources, or build a -specific revision, the easiest way of retrieving it is to:

-
    -

  1. Log into this site, as "anonymous", using the semi-random password in the captcha.

    2. -

  2. Go to the "Timeline".

    3. -

  3. Choose the revision you wish to have.

    4. -

  4. Follow its link to its detailed information page.

    5. -

  5. On that page, choose either the "ZIP" or "Tarball" link to get -a copy of this revision in the format of your choice.

    6. -
-
-

Source Code Management

-

For the curious (or a developer-to-be), the sources are managed by the -Fossil SCM. -Binaries for popular platforms can be found directly at its -download page.

-

With that tool available the full history can be retrieved via:

-
-    fossil clone  http://core.tcl-lang.org/tcllib  tcllib.fossil
-
-

followed by

-
-    mkdir tcllib
-    cd tcllib
-    fossil open ../tcllib.fossil
-
-

to get a checkout of the head of the trunk.

-
-
Index: idoc/www/tcllib/files/modules/aes/aes.html ================================================================== --- idoc/www/tcllib/files/modules/aes/aes.html +++ idoc/www/tcllib/files/modules/aes/aes.html @@ -1,6 +1,7 @@ - + + aes - Advanced Encryption Standard (AES) - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

aes(n) 1.2.1 tcllib "Advanced Encryption Standard (AES)"

Name

aes - Implementation of the AES block cipher

@@ -248,26 +249,20 @@ bugs and other problems. Please report such in the category aes of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Hashes, checksums, and encryption

Index: idoc/www/tcllib/files/modules/amazon-s3/S3.html ================================================================== --- idoc/www/tcllib/files/modules/amazon-s3/S3.html +++ idoc/www/tcllib/files/modules/amazon-s3/S3.html @@ -1,6 +1,7 @@ - + + S3 - Amazon S3 Web Service Utilities - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

S3(n) 1.0.3 tcllib "Amazon S3 Web Service Utilities"

Name

S3 - Amazon S3 Web Service Interface

@@ -447,11 +448,11 @@ if the call is not blocking, then a socket error (i.e., an error whose error code starts with "S3 socket" will be returned in the dictionary as error, errorInfo, and errorCode. If a foreground call is made (i.e., resultvar is not provided), and this option is not provided or is set to throw, then -error will be invoked instead.

+error will be invoked instead.

Once the call to S3::REST completes, a new dict is returned, either in the resultvar or as the result of execution. This dict is a copy of the original dict with the results added as new keys. The possible new keys are these:

@@ -1245,23 +1246,23 @@ each moving on to the next unstarted task as it finishes each. This is still being designed, and it is intended primarily to be run on Amazon's Elastic Compute Cloud.

TLS Security Considerations

-

This package uses the TLS package to handle the -security for https urls and other socket connections.

+

This package uses the TLS package to handle the security +for https urls and other socket connections.

Policy decisions like the set of protocols to support and what -ciphers to use are not the responsibility of TLS, nor of +ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and are likely influenced by the set of servers the application will talk to as well.

For example, in light of the recent POODLE attack discovered by Google many servers will disable support for the SSLv3 protocol. -To handle this change the applications using TLS must be -patched, and not this package, nor TLS itself. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below.

     package require tls
     tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
@@ -1273,22 +1274,16 @@
 bugs and other problems.
 Please report such in the category amazon-s3 of the
 Tcllib Trackers.
 Please also report any ideas for enhancements you may have for either
 package and/or documentation.

-
When proposing code changes, please provide unified diffs,
-i.e the output of diff -u.

-
Note further that attachments are strongly preferred over
-inlined patches. Attachments can be made by going to the Edit
-form of the ticket immediately after its creation, and then using the
-left-most button in the secondary navigation bar.

Category

Networking

Index: idoc/www/tcllib/files/modules/amazon-s3/xsxp.html ================================================================== --- idoc/www/tcllib/files/modules/amazon-s3/xsxp.html +++ idoc/www/tcllib/files/modules/amazon-s3/xsxp.html @@ -1,6 +1,6 @@ - + xsxp - Amazon S3 Web Service Utilities - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

xsxp(n) 1.0 tcllib "Amazon S3 Web Service Utilities"

Name

xsxp - eXtremely Simple Xml Parser

@@ -232,22 +232,16 @@ bugs and other problems. Please report such in the category amazon-s3 of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Text processing

Index: idoc/www/tcllib/files/modules/asn/asn.html ================================================================== --- idoc/www/tcllib/files/modules/asn/asn.html +++ idoc/www/tcllib/files/modules/asn/asn.html @@ -1,6 +1,7 @@ - + + asn - ASN.1 processing - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

asn(n) 0.8 tcllib "ASN.1 processing"

Name

asn - ASN.1 BER encoder/decoder

@@ -489,19 +490,13 @@ bugs and other problems. Please report such in the category asn of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

-

When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

-

Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

Category

Networking

Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export_text.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export_text.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export_text.html @@ -1,6 +1,7 @@ - + + doctools::toc::export::text - Documentation tools - - -
[ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

doctools::toc::export::text(n) 0.1 tcllib "Documentation tools"

Name

doctools::toc::export::text - plain text export plugin

@@ -131,11 +132,11 @@
  • package require Tcl 8.4
  • package require doctools::toc::export::text ?0.1?
  • package require doctools::text

    • Description

    This package implements the doctools table of contents export plugin @@ -150,11 +151,11 @@

    API

    The API provided by this package satisfies the specification of the doctoc export plugin API version 2.

    -
    export serial configuration
    +
    export serial configuration

    This command takes the canonical serialization of a table of contents, as specified in section ToC serialization format, and contained in serial, the configuration, a dictionary, and generates plain text markup encoding the table. The created string is then returned as the result of the command.

    @@ -267,22 +268,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_export_wiki.html @@ -1,6 +1,7 @@ - + + doctools::toc::export::wiki - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::toc::export::wiki(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::toc::export::wiki - wiki export plugin

    @@ -132,11 +133,11 @@
  • package require Tcl 8.4
  • package require doctools::toc::export::wiki ?0.1?
  • package require doctools::text

    • Description

    This package implements the doctools table of contents export plugin @@ -151,11 +152,11 @@

    API

    The API provided by this package satisfies the specification of the doctoc export plugin API version 2.

    -
    export serial configuration
    +
    export serial configuration

    This command takes the canonical serialization of a table of contents, as specified in section ToC serialization format, and contained in serial, the configuration, a dictionary, and generates wiki markup encoding the table. The created string is then returned as the result of the command.

    @@ -274,22 +275,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_import.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_import.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_import.html @@ -1,6 +1,7 @@ - + + doctools::toc::import - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    doctools::toc::import(n) 0.2.1 tcllib "Documentation tools"

    +

    doctools::toc::import(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::toc::import - Importing keyword indices

    Table Of Contents

      @@ -133,13 +134,13 @@

    Synopsis

      -
    • package require doctools::toc::import ?0.2.1?
      • +
    • package require doctools::toc::import ?0.1?
    • package require Tcl 8.4
      • -
    • package require struct::map
      • +
    • package require doctools::config
    • package require doctools::toc::structure
    • package require snit
    • package require pluginmgr

    Description

    This package provides a class to manage the plugins for the import of tables of contents from other formats, i.e. their conversion from, for -example doctoc, json, etc.

    +example doctoc, json, etc.

    This is one of the three public pillars the management of tables of contents resides on. The other two pillars are

    1. Exporting tables of contents, and

    2. Holding tables of contents

      3. @@ -210,14 +211,14 @@ absolute necessity, as it specifies the interaction between this package and its plugins in detail.

    Concepts

      -

    1. A table of contents consists of a (possibly empty) list of +

    2. A table of contents consists of a (possibly empty) list of elements.

    3. Each element in the list is identified by its label.

      4. -

    4. Each element is either a reference, or a division.

      5. +

    5. Each element is either a reference, or a division.

    6. Each reference has an associated document, identified by a symbolic id, and a textual description.

    7. Each division may have an associated document, identified by a symbolic id.

    8. Each division consists consists of a (possibly empty) list of @@ -238,11 +239,11 @@

      API

      Package commands

      ::doctools::toc::import objectName

      This command creates a new import manager object with an associated -Tcl command whose name is objectName. This object command +Tcl command whose name is objectName. This object command is explained in full detail in the sections Object command and Object methods. The object command will be created under the current namespace if the objectName is not fully qualified, and in the specified namespace otherwise.

      @@ -304,11 +305,11 @@ specified value and returns the new value of the variable.

      If no value is specified it simply returns the current value, without changing it.

      Note that while the user can set the predefined configuration variables user and format doing so will have no -effect, these values will be internally overridden when invoking an +effect, these values will be internally overriden when invoking an import plugin.

      objectName config unset pattern...

      This method unsets all configuration variables matching the specified glob patterns. If no pattern is specified it will unset all currently defined configuration variables.

      @@ -358,11 +359,11 @@ present, with the signature

      IncludeFile currentfile path

      This command has to be invoked by the plugin when it has to process an included file, if the format has the concept of such. An example of -such a format would be doctoc.

      +such a format would be doctoc.

      The plugin has to supply the following arguments

      string currentfile

      The path of the file it is currently processing. This may be the empty string if no such is known.

      @@ -397,11 +398,11 @@

    9. A plugin has to provide one command, with the signature shown below.

      -
      import text configuration
      +
      import text configuration

      Whenever an import manager of doctools::toc has to parse input for a table of contents it will invoke this command.

      string text

      This argument will contain the text encoding the table of contents per @@ -423,11 +424,11 @@

    10. A single usage cycle of a plugin consists of the invokations of - the command import. This call has to leave the plugin in + the command import. This call has to leave the plugin in a state where another usage cycle can be run without problems.

    ToC serialization format

    Here we specify the format used by the doctools v2 packages to @@ -523,22 +524,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_import_json.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_import_json.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_import_json.html @@ -1,6 +1,7 @@ - + + doctools::toc::import::json - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    doctools::toc::import::json(n) 0.2.1 tcllib "Documentation tools"

    +

    doctools::toc::import::json(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::toc::import::json - JSON import plugin

    Table Of Contents

      @@ -126,17 +127,17 @@

    Synopsis

      -
    • package require Tcl 8.5
      • -
    • package require doctools::toc::import::json ?0.2.1?
      • +
    • package require Tcl 8.4
      • +
    • package require doctools::toc::import::json ?0.1?
    • package require doctools::toc::structure
    • package require json

    Description

    This package implements the doctools table of contents import plugin @@ -151,11 +152,11 @@

    API

    The API provided by this package satisfies the specification of the doctoc import plugin API version 2.

    -
    import string configuration
    +
    import string configuration

    This command takes the string and parses it as JSON markup encoding a table of contents, in the context of the specified configuration (a dictionary). The result of the command is the canonical serialization of that table of contents, in the form specified in section ToC serialization format.

    @@ -324,22 +325,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Text formatter plugin

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_introduction.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_introduction.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_introduction.html @@ -1,6 +1,7 @@ - + + doctools2toc_introduction - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools2toc_introduction(n) 2.0 tcllib "Documentation tools"

    Name

    doctools2toc_introduction - DocTools - Tables of Contents

    @@ -123,11 +124,11 @@
  • Category
  • Copyright

    • Description

    -

    doctoc (short for documentation tables of contents) +

    doctoc (short for documentation tables of contents) stands for a set of related, yet different, entities which are working together for the easy creation and transformation of tables and contents for documentation.

    These are

      @@ -160,11 +161,11 @@ to validate it, and after completion it also performs the conversion into the chosen system of visual markup, be it *roff, HTML, plain text, wiki, etc. The simpler dtplite application makes internal use of doctoc when handling directories of documentation, automatically generating a proper table of contents for them.

      -

    1. A processor of documentation written in the doctoc +

    2. A processor of documentation written in the doctoc markup language has to know which tools are available for use.

      The main tool is the aforementioned dtp application provided by Tcllib. The simpler dtplite does not expose doctoc to the user. At the bottom level, common to both applications, however we find the three packages providing the basic facilities to handle @@ -193,11 +194,11 @@

    Related formats

    The doctoc format does not stand alone, it has two companion formats. -These are called docidx and doctools, and they are +These are called docidx and doctools, and they are intended for the markup of keyword indices, and of general documentation, respectively. They are described in their own sets of documents, starting at the DocTools - Keyword Indices and the DocTools - General, respectively.

    @@ -208,17 +209,17 @@ ~~ | ~~ doctools::toc::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::toc::import | | | +---------------+-------------------------+ | +------------------+---------------+-----------------------+---------------+ | | | | | | | | | -struct:map = | | | = doctools::include struct::map fileutil::paths +doctools::config = | | | = doctools::include doctools::config doctools::paths | | | | | doctools::toc::export::<*> | | | doctools::toc::import::<*> doctoc | | | doctoc, json - json | | | | \ - html | | | doctools::toc::parse \ - nroff | | | | \ + json | | | | \\ + html | | | doctools::toc::parse \\ + nroff | | | | \\ wiki | | | +---------------+ json text | | | | | doctools::toc::structure | | +-------+---------------+ @@ -241,25 +242,19 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_c.html @@ -1,6 +1,7 @@ - + + doctools::msgcat::toc::c - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::msgcat::toc::c(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::msgcat::toc::c - Message catalog for the doctoc parser (C)

    @@ -158,22 +159,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_de.html @@ -1,6 +1,7 @@ - + + doctools::msgcat::toc::de - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::msgcat::toc::de(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::msgcat::toc::de - Message catalog for the doctoc parser (DE)

    @@ -158,22 +159,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_en.html @@ -1,6 +1,7 @@ - + + doctools::msgcat::toc::en - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::msgcat::toc::en(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::msgcat::toc::en - Message catalog for the doctoc parser (EN)

    @@ -158,22 +159,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_msgcat_fr.html @@ -1,6 +1,7 @@ - + + doctools::msgcat::toc::fr - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::msgcat::toc::fr(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::msgcat::toc::fr - Message catalog for the doctoc parser (FR)

    @@ -158,22 +159,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_parse.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_parse.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_parse.html @@ -1,6 +1,7 @@ - + + doctools::toc::parse - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::toc::parse(n) 1 tcllib "Documentation tools"

    Name

    doctools::toc::parse - Parsing text in doctoc format

    @@ -154,23 +155,23 @@

    Description

    This package provides commands to parse text written in the -doctoc markup language and convert it into the canonical +doctoc markup language and convert it into the canonical serialization of the table of contents encoded in the text. See the section ToC serialization format for specification of their format.

    This is an internal package of doctools, for use by the higher level -packages handling doctoc documents.

    +packages handling doctoc documents.

    API

    ::doctools::toc::parse text text

    The command takes the string contained in text and parses it under the assumption that it contains a document written using the -doctoc markup language. An error is thrown if this assumption +doctoc markup language. An error is thrown if this assumption is found to be false. The format of these errors is described in section Parse errors.

    When successful the command returns the canonical serialization of the table of contents which was encoded in the text. See the section ToC serialization format for specification @@ -214,21 +215,21 @@ default pattern used when none is specified, is *.

    Parse errors

    The format of the parse error messages thrown when encountering -violations of the doctoc markup syntax is human readable and +violations of the doctoc markup syntax is human readable and not intended for processing by machines. As such it is not documented.

    However, the errorCode attached to the message is machine-readable and has the following format:

    1. The error code will be a list, each element describing a single error found in the input. The list has at least one element, possibly more.

    2. Each error element will be a list containing six strings describing an error in detail. The strings will be

        -

      1. The path of the file the error occurred in. This may be empty.

        2. +

      2. The path of the file the error occured in. This may be empty.

      3. The range of the token the error was found at. This range is a two-element list containing the offset of the first and last character in the range, counted from the beginning of the input (file). Offsets are counted from zero.

      4. The line the first character after the error is on. @@ -358,22 +359,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

        -

        When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

        -

        Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/doctools2toc/toc_structure.html ================================================================== --- idoc/www/tcllib/files/modules/doctools2toc/toc_structure.html +++ idoc/www/tcllib/files/modules/doctools2toc/toc_structure.html @@ -1,6 +1,7 @@ - + + doctools::toc::structure - Documentation tools - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    doctools::toc::structure(n) 0.1 tcllib "Documentation tools"

    Name

    doctools::toc::structure - Doctoc serialization utilities

    @@ -145,11 +146,11 @@

    This package provides commands to work with the serializations of tables of contents as managed by the doctools system v2, and specified in section ToC serialization format.

    This is an internal package of doctools, for use by the higher level packages handling tables of contents and their conversion into and out -of various other formats, like documents written using doctoc +of various other formats, like documents written using doctoc markup.

    API

    ::doctools::toc::structure verify serial ?canonvar?
    @@ -311,22 +312,16 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/dtplite/pkg_dtplite.html ================================================================== --- idoc/www/tcllib/files/modules/dtplite/pkg_dtplite.html +++ idoc/www/tcllib/files/modules/dtplite/pkg_dtplite.html @@ -1,6 +1,7 @@ - + + dtplite - Documentation toolbox - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    dtplite(n) 1.3.1 tcllib "Documentation toolbox"

    +

    dtplite(n) 1.3 tcllib "Documentation toolbox"

    Name

    dtplite - Lightweight DocTools Markup Processor

    Table Of Contents

      @@ -132,11 +133,11 @@

    Synopsis

      -
    • package require dtplite ?1.3.1?
      • +
    • package require dtplite ?1.3?
    • dtplite -o output ?options? format inputfile
    • dtplite validate inputfile
    • dtplite -o output ?options? format inputdirectory
      • @@ -200,11 +201,11 @@

      This argument specifies the formatting engine to use when processing the input, and thus the format of the generated document. See section FORMATS for the possibilities recognized by the application.

      path inputfile (in)

      This argument specifies the path to the file to process. It has to -exist, must be readable, and written in doctools format.

      +exist, must be readable, and written in doctools format.

      dtplite validate inputfile

      This is a simpler form for use case [1]. The "validate" format generates no output at all, only syntax checks are performed. As such the specification of an output file or other options is not necessary @@ -215,11 +216,11 @@ directory instead of a file. The other arguments are identical, except for output, which now has to be the path to an existing and writable directory.

      The input documents are all files in inputdirectory or any of its subdirectories which were recognized by fileutil::fileType -as containing text in doctools format.

      +as containing text in doctools format.

      dtplite -merge -o output ?options? format inputdirectory

      This is the form for use case [3]. The only difference to the form for use case [2] is the additional option -merge.

      Each such call will merge the generated documents coming from processing the input documents under inputdirectory or any of @@ -420,25 +421,19 @@ bugs and other problems. Please report such in the category doctools of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Documentation tools

    Index: idoc/www/tcllib/files/modules/fileutil/fileutil.html ================================================================== --- idoc/www/tcllib/files/modules/fileutil/fileutil.html +++ idoc/www/tcllib/files/modules/fileutil/fileutil.html @@ -1,6 +1,7 @@ - + + fileutil - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    fileutil(n) 1.16 tcllib "file utilities"

    +

    fileutil(n) 1.15 tcllib "file utilities"

    Name

    fileutil - Procedures implementing some file utilities

    Table Of Contents

      @@ -122,11 +123,11 @@

    Synopsis

    • package require Tcl 8
      • -
    • package require fileutil ?1.16?
      • +
    • package require fileutil ?1.15?
    • ::fileutil::lexnormalize path
    • ::fileutil::fullnormalize path
    • ::fileutil::test path codes ?msgvar? ?label?
      • @@ -205,11 +206,11 @@

      file isfile

      dir

      file isdirectory

      ::fileutil::cat (?options? file)...
      -

      A tcl implementation of the UNIX cat command. Returns the +

      A tcl implementation of the UNIX cat command. Returns the contents of the specified file(s). The arguments are files to read, with interspersed options configuring the process. If there are problems reading any of the files, an error will occur, and no data will be returned.

      The options accepted are -encoding, -translation, @@ -271,11 +272,11 @@ writes the result of that invokation back as the new contents of the file.

      If the executed command throws an error the file is not changed.

      The command accepts the same options as ::fileutil::cat.

      ::fileutil::fileType filename
      -

      An implementation of the UNIX file command, which uses +

      An implementation of the UNIX file command, which uses various heuristics to guess the type of a file. Returns a list specifying as much type information as can be determined about the file, from most general (eg, "binary" or "text") to most specific (eg, "gif"). For example, the return value for a GIF file would be "binary graphic gif". The command will detect the following types of files: @@ -286,11 +287,11 @@ gravity_wave_data_frame, compressed bzip, compressed gzip, compressed zip, compressed tar, audio wave, audio mpeg, and link. It further detects doctools, doctoc, and docidx documentation files, and tklib diagrams.

      ::fileutil::find ?basedir ?filtercmd??
      -

      An implementation of the unix command find. Adapted from the +

      An implementation of the unix command find. Adapted from the Tcler's Wiki. Takes at most two arguments, the path to the directory to start searching from and a command to use to evaluate interest in each file. The path defaults to ".", i.e. the current directory. The command defaults to the empty string, which means that all files are of interest. The command takes care not to @@ -331,11 +332,11 @@ script the variable var is set to the contents of the current line. The return value of this command is the result of the last invocation of the script cmd or the empty string if the file was empty.

      ::fileutil::grep pattern ?files?
      -

      Implementation of grep. Adapted from the Tcler's Wiki. The +

      Implementation of grep. Adapted from the Tcler's Wiki. The first argument defines the pattern to search for. This is followed by a list of files to search through. The list is optional and stdin will be used if it is missing. The result of the procedures is a list containing the matches. Each match is a single element of the list and contains filename, number and contents @@ -382,11 +383,11 @@ happens if path is relative, except that nothing is stripped of it. Before adding the jail prefix the path is lexically normalized to prevent the caller from using .. segments in path to escape the jail.

      ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
      -

      Implementation of touch. Alter the atime and mtime of the +

      Implementation of touch. Alter the atime and mtime of the specified files. If -c, do not create files if they do not already exist. If -r, use the atime and mtime from ref_file. If -t, use the integer clock value time. It is illegal to specify both -r and -t. If -a, only change the atime. If -m, @@ -525,19 +526,13 @@ bugs and other problems. Please report such in the category fileutil of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/fileutil/multi.html ================================================================== --- idoc/www/tcllib/files/modules/fileutil/multi.html +++ idoc/www/tcllib/files/modules/fileutil/multi.html @@ -1,6 +1,7 @@ - + + fileutil::multi - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    fileutil::multi(n) 0.1 tcllib "file utilities"

    Name

    fileutil::multi - Multi-file operation, scatter/gather, standard object

    @@ -163,19 +164,13 @@ bugs and other problems. Please report such in the category fileutil of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/fileutil/multiop.html ================================================================== --- idoc/www/tcllib/files/modules/fileutil/multiop.html +++ idoc/www/tcllib/files/modules/fileutil/multiop.html @@ -1,6 +1,7 @@ - + + fileutil::multi::op - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    fileutil::multi::op(n) 0.5.3 tcllib "file utilities"

    Name

    fileutil::multi::op - Multi-file operation, scatter/gather

    @@ -144,13 +145,13 @@
  • but
  • except
  • as name
  • recursive
  • recursively
    • -
  • copy
    • -
  • move
    • -
  • remove
    • +
  • copy
    • +
  • move
    • +
  • remove
  • expand
  • invoke cmdprefix
  • reset
  • (
  • )
    • @@ -260,19 +261,19 @@
    recursive

    Signals that file expansion should happen in the whole directory hierarchy and not just the directory itself.

    recursively

    An alias for recursive.

    -
    copy
    +
    copy

    Signals that the operation is the copying of files from source to destination directory per the specified inclusion and exclusion patterns.

    -
    move
    +
    move

    Signals that the operation is the moving of files from source to destination directory per the specified inclusion and exclusion patterns.

    -
    remove
    +
    remove

    Signals that the operation is the removal of files in the destination directory per the specified inclusion and exclusion patterns.

    expand

    Signals that there is no operation but the calculation of the set of files from the include and exclude patterns. This operation is not @@ -353,11 +354,11 @@

    from

    Current source directory, set by from.

    into

    Current destination directory, set by into (and aliases).

    operation
    -

    Current operation to perform, set by copy, move, remove, expand, or invoke.

    +

    Current operation to perform, set by copy, move, remove, expand, or invoke.

    recursive

    Current recursion status. Set/unset by recursive and !recursive.

    strict

    Current strictness. Set/unset by strict and !strict.

    type
    @@ -383,47 +384,47 @@

    EXAMPLES

    The following examples assume that the variable F contains a reference to a multi-file operation object.

    -    $F do copy                       \
-	the  *.dll                    \
-	from c:/TDK/PrivateOpenSSL/bin \
+    $F do copy                       \\
+	the  *.dll                    \\
+	from c:/TDK/PrivateOpenSSL/bin \\
 	to   [installdir_of tls]
 
    -    $F do move      \
-	the  *       \
-	from /sources \
-	into /scratch  \
+    $F do move      \\
+	the  *       \\
+	from /sources \\
+	into /scratch  \\
 	but not *.html
     # Alternatively use 'except for *.html'.
 
    -    $F do           \
-	move         \
-	the  index    \
-	from /sources  \
-	into /scratch   \
+    $F do           \\
+	move         \\
+	the  index    \\
+	from /sources  \\
+	into /scratch   \\
 	as   pkgIndex.tcl
 
    -    $F do         \
-	remove     \
-	the *.txt  \
+    $F do         \\
+	remove     \\
+	the *.txt  \\
 	in /scratch

    Note that the fact that most commands just modify the object state allows us to use more off forms as specifications instead of just nearly-natural language sentences. For example the second example in this section can re-arranged into:

    -    $F do            \
-	from /sources \
-	into /scratch  \
-	but not *.html \
-	move           \
+    $F do            \\
+	from /sources \\
+	into /scratch  \\
+	but not *.html \\
+	move           \\
 	the  *

    and the result is not only still a valid specification, but even stays relatively readable.

    Further note that the information collected by the commands but, @@ -431,17 +432,17 @@ the was executed. However no other state is reset in that manner, allowing the user to avoid repetitions of unchanging information. For example the second and third examples of this section can be merged and rewritten into the equivalent:

    -$F do                   \
-    move                 \
-    the  *                \
-    from /sources          \
-    into /scratch           \
-    but not *.html not index \
-    the  index               \
+$F do                   \\
+    move                 \\
+    the  *                \\
+    from /sources          \\
+    into /scratch           \\
+    but not *.html not index \\
+    the  index               \\
     as   pkgIndex.tcl

    Bugs, Ideas, Feedback

    This document, and the package it describes, will undoubtedly contain @@ -448,19 +449,13 @@ bugs and other problems. Please report such in the category fileutil of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    DELETED idoc/www/tcllib/files/modules/fileutil/paths.html Index: idoc/www/tcllib/files/modules/fileutil/paths.html ================================================================== --- idoc/www/tcllib/files/modules/fileutil/paths.html +++ idoc/www/tcllib/files/modules/fileutil/paths.html @@ -1,190 +0,0 @@ - -fileutil::paths - - - - - -
    [ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
    -
    -

    fileutil::paths(n) 1 tcllib ""

    -

    Name

    -

    fileutil::paths - Manage search path pools

    -
    - -

    Synopsis

    -
    -
      -
    • package require Tcl 8.4
      • -
    • package require fileutil::paths ?1?
      • -
    - -
    -
    -

    Description

    -

    Provides a snit class whose instances manage a pool of (search) paths.

    -
    -

    API

    -

    The main command provides construction of search path pools:

    -
    -
    ::fileutil::paths poolName
    -

    Creates a new, empty pool of search paths with an associated global -Tcl command whose name is poolName. -It may be used to invoke various operations on the pool. -It has the following general form:

    -
    -
    poolName method ?arg arg ...?
    -

    method and arguments determine the exact behavior of -the command.

    -
    -

    If poolName is specified as %AUTO% a unique name will be -generated by the package itself. -The result of the command is the fully-qualified name of the instance -command.

    -
    -

    The following commands are possible for pool objects:

    -
    -
    poolName add path
    -

    Adds the path to the pool. -Nothing is done if the path is already known to the pool. -The result of the command is the empty string.

    -
    poolName clear
    -

    Clears the entire pool. In other words, removes all paths from it. -The result of the command is the empty string.

    -
    poolName paths
    -

    Returns the list of all paths known to the pool, in the order they -were added.

    -
    poolName remove path
    -

    Removes the path from the pool, if it is known to the pool. -Unknown paths are ignored without error. -The result of the command is the empty string.

    -
    -
    -

    Bugs, Ideas, Feedback

    -

    This document, and the package it describes, will undoubtedly contain -bugs and other problems. -Please report such in the category fileutil of the -Tcllib Trackers. -Please also report any ideas for enhancements you may have for either -package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    -
    -
    Index: idoc/www/tcllib/files/modules/fileutil/traverse.html ================================================================== --- idoc/www/tcllib/files/modules/fileutil/traverse.html +++ idoc/www/tcllib/files/modules/fileutil/traverse.html @@ -1,6 +1,7 @@ - + + fileutil_traverse - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    fileutil_traverse(n) 0.6 tcllib "file utilities"

    Name

    fileutil_traverse - Iterative directory traversal

    @@ -273,19 +274,13 @@ bugs and other problems. Please report such in the category fileutil of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/ftp/ftp.html ================================================================== --- idoc/www/tcllib/files/modules/ftp/ftp.html +++ idoc/www/tcllib/files/modules/ftp/ftp.html @@ -1,6 +1,7 @@ - + + ftp - ftp client - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    ftp(n) 2.4.13 tcllib "ftp client"

    Name

    ftp - Client-side tcl implementation of the ftp protocol

    @@ -160,11 +161,11 @@ shutdown an existing ftp session use ::ftp::Close. All other commands are restricted to usage in an an open ftp session. They will generate errors if they are used out of context. The ftp package includes file and directory manipulating commands for remote sites. To perform the same operations on the local site use commands built into -the core, like cd or file.

    +the core, like cd or file.

    The output of the package is controlled by two state variables, ::ftp::VERBOSE and ::ftp::DEBUG. Setting ::ftp::VERBOSE to "1" forces the package to show all responses from a remote server. The default value is "0". Setting ::ftp::DEBUG to "1" enables debugging and forces the package to @@ -422,31 +423,25 @@

    BUGS

    The correct execution of many commands depends upon the proper behavior by the remote server, network and router configuration.

    An update command placed in the procedure ::ftp::DisplayMsg may run into persistent errors or infinite loops. The solution to this -problem is to use update idletasks instead of update.

    +problem is to use update idletasks instead of update.

    Bugs, Ideas, Feedback

    This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category ftp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/ftp/ftp_geturl.html ================================================================== --- idoc/www/tcllib/files/modules/ftp/ftp_geturl.html +++ idoc/www/tcllib/files/modules/ftp/ftp_geturl.html @@ -1,6 +1,7 @@ - + + ftp::geturl - ftp client - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    ftp::geturl(n) 0.2.2 tcllib "ftp client"

    Name

    ftp::geturl - Uri handler for ftp urls

    @@ -132,23 +133,23 @@

    Description

    This package provides a command which wraps around the client side of -the ftp protocol provided by package ftp to allow the -retrieval of urls using the ftp schema.

    +the ftp protocol provided by package ftp to allow the +retrieval of urls using the ftp schema.

    API

    ::ftp::geturl url

    This command can be used by the generic command ::uri::geturl (See package uri) to retrieve the contents of ftp urls. Internally it uses the commands of the package ftp to fulfill the request.

    -

    The contents of a ftp url are defined as follows:

    +

    The contents of a ftp url are defined as follows:

    -
    file
    +
    file

    The contents of the specified file itself.

    directory

    A listing of the contents of the directory in key value notation where the file name is the key and its attributes the associated value.

    link
    @@ -161,22 +162,16 @@ bugs and other problems. Please report such in the category ftp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/ftpd/ftpd.html ================================================================== --- idoc/www/tcllib/files/modules/ftpd/ftpd.html +++ idoc/www/tcllib/files/modules/ftpd/ftpd.html @@ -1,6 +1,7 @@ - + + ftpd - Tcl FTP Server Package - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    ftpd(n) 1.3 tcllib "Tcl FTP Server Package"

    Name

    ftpd - Tcl FTP server implementation

    @@ -332,19 +333,13 @@ bugs and other problems. Please report such in the category ftpd of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/fumagic/cfront.html ================================================================== --- idoc/www/tcllib/files/modules/fumagic/cfront.html +++ idoc/www/tcllib/files/modules/fumagic/cfront.html @@ -1,6 +1,7 @@ - + + fileutil::magic::cfront - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    fileutil::magic::cfront(n) 1.2.0 tcllib "file utilities"

    Name

    fileutil::magic::cfront - Generator core for compiler of magic(5) files

    @@ -173,22 +174,16 @@ bugs and other problems. Please report such in the category fileutil :: magic of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    See Also

    file(1), fileutil, magic(5)

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/fumagic/cgen.html ================================================================== --- idoc/www/tcllib/files/modules/fumagic/cgen.html +++ idoc/www/tcllib/files/modules/fumagic/cgen.html @@ -1,6 +1,7 @@ - + + fileutil::magic::cgen - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    fileutil::magic::cgen(n) 1.2.0 tcllib "file utilities"

    Name

    fileutil::magic::cgen - Generator core for compiler of magic(5) files

    @@ -169,22 +170,16 @@ bugs and other problems. Please report such in the category fileutil :: magic of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    See Also

    file(1), fileutil, magic(5)

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/fumagic/filetypes.html ================================================================== --- idoc/www/tcllib/files/modules/fumagic/filetypes.html +++ idoc/www/tcllib/files/modules/fumagic/filetypes.html @@ -1,6 +1,7 @@ - + + fileutil::magic::filetype - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    fileutil::magic::filetype(n) 2.0 tcllib "file utilities"

    +

    fileutil::magic::filetype(n) 1.2.0 tcllib "file utilities"

    Name

    fileutil::magic::filetype - Procedures implementing file-type recognition

    Table Of Contents

      @@ -123,11 +124,11 @@

    Synopsis

    • package require Tcl 8.6
      • -
    • package require fileutil::magic::filetype ?2.0?
      • +
    • package require fileutil::magic::filetype ?1.2.0?
    @@ -161,22 +162,16 @@ bugs and other problems. Please report such in the category fileutil :: magic of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    See Also

    file(1), fileutil, magic(5)

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/fumagic/rtcore.html ================================================================== --- idoc/www/tcllib/files/modules/fumagic/rtcore.html +++ idoc/www/tcllib/files/modules/fumagic/rtcore.html @@ -1,6 +1,7 @@ - + + fileutil::magic::rt - file utilities - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    fileutil::magic::rt(n) 2.0 tcllib "file utilities"

    +

    fileutil::magic::rt(n) 1.2.0 tcllib "file utilities"

    Name

    fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl

    Table Of Contents

      @@ -124,11 +125,11 @@

    Synopsis

    • package require Tcl 8.5
      • -
    • package require fileutil::magic::rt ?2.0?
      • +
    • package require fileutil::magic::rt ?1.2.0?
    • ::fileutil::magic::rt::>
    • ::fileutil::magic::rt::<
    • ::fileutil::magic::rt::open filename
      • @@ -318,22 +319,16 @@ bugs and other problems. Please report such in the category fileutil :: magic of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    See Also

    file(1), fileutil, magic(5)

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/generator/generator.html ================================================================== --- idoc/www/tcllib/files/modules/generator/generator.html +++ idoc/www/tcllib/files/modules/generator/generator.html @@ -1,6 +1,6 @@ - + generator - Tcl Generator Commands - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    generator(n) 0.1 tcllib "Tcl Generator Commands"

    Name

    generator - Procedures for creating and using generators.

    @@ -187,22 +187,22 @@ interface. The generator mechanism is built on top of the Tcl 8.6 coroutine mechanism.

    The package exports a single ensemble command, generator. All functionality is provided as subcommands of this command. The core subcommands of the package are define, yield, and foreach. The -define command works like Tcl's proc command, but creates a +define command works like Tcl's proc command, but creates a generator procedure; that is, a procedure that returns a generator when called. The generator itself is a command that can be called multiple times: each time it returns the next value in the generated series. When the series has been exhausted, the generator command returns an empty list and then destroys itself. Rather than manually call a generator, however, the package also provides a flexible foreach command that loops through the values of one or more generators. This loop construct mimicks the functionality of the -built-in Tcl foreach command, including handling multiple return values +built-in Tcl foreach command, including handling multiple return values and looping over multiple generators at once. Writing a generator is also a simple task, much like writing a normal procedure: simply use the define -command to define the generator, and then call yield instead of return. +command to define the generator, and then call yield instead of return. For example, we can define a generator for looping through the integers in a particular range:

         generator define range {n m} {
         for {set i $n} {$i <= $m} {incr i} { generator yield $i }
@@ -230,11 +230,11 @@

    COMMANDS

    generator define name params body

    Creates a new generator procedure. The arguments to the command are identical to -those for proc: a name, a list of parameters, and a body. The +those for proc: a name, a list of parameters, and a body. The parameter list format is identical to a procedure. In particular, default values and the ?args? syntax can be used as usual. Each time the resulting generator procedure is called it creates a new generator command (coroutine) that will yield a list of values on each call. Each result from a generator is guaranteed to be a non-empty list of values. When a generator is exhausted it @@ -249,14 +249,14 @@ yield command must be called with at least one argument, but can be called with multiple arguments, in which case this is equivalent to calling yield once for each argument.

    generator foreach varList generator varList generator ?...? body

    Loops through one or more generators, assigning the next values to variables and -then executing the loop body. Works much like the built-in foreach +then executing the loop body. Works much like the built-in foreach command, but working with generators rather than lists. Multiple generators can be iterated over in parallel, and multiple results can be retrieved from a -single generator at once. Like the built-in foreach, the loop will +single generator at once. Like the built-in foreach, the loop will continue until all of the generators have been exhausted: variables for generators that are exhausted early will be set to the empty string.

    The foreach command will automatically clean-up all of the generators at the end of the loop, regardless of whether the loop terminated early or not. This behaviour is provided as a convenience to avoid having to explicitly @@ -506,8 +506,8 @@

    BUGS, IDEAS, FEEDBACK

    Please report any errors in this document, or in the package it describes, to Neil Madden.

    Index: idoc/www/tcllib/files/modules/gpx/gpx.html ================================================================== --- idoc/www/tcllib/files/modules/gpx/gpx.html +++ idoc/www/tcllib/files/modules/gpx/gpx.html @@ -1,6 +1,7 @@ - + + gpx - GPS eXchange Format (GPX) - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    gpx(n) 0.9 tcllib "GPS eXchange Format (GPX)"

    Name

    gpx - Extracts waypoints, tracks and routes from GPX files

    @@ -258,22 +259,16 @@ bugs and other problems. Please report such in the category gpx of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    File formats

    Index: idoc/www/tcllib/files/modules/grammar_aycock/aycock.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_aycock/aycock.html +++ idoc/www/tcllib/files/modules/grammar_aycock/aycock.html @@ -1,6 +1,7 @@ - + + grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::aycock(n) 1.0 tcllib "Aycock-Horspool-Earley parser generator for Tcl"

    Name

    grammar::aycock - Aycock-Horspool-Earley parser generator for Tcl

    @@ -234,15 +235,15 @@

    KEYWORDS

    Aycock, Earley, Horspool, parser, compiler

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_fa/dacceptor.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_fa/dacceptor.html +++ idoc/www/tcllib/files/modules/grammar_fa/dacceptor.html @@ -1,6 +1,7 @@ - + + grammar::fa::dacceptor - Finite automaton operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::fa::dacceptor(n) 0.1.1 tcllib "Finite automaton operations and usage"

    Name

    grammar::fa::dacceptor - Create and use deterministic acceptors

    @@ -195,22 +196,16 @@ bugs and other problems. Please report such in the category grammar_fa of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_fa/dexec.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_fa/dexec.html +++ idoc/www/tcllib/files/modules/grammar_fa/dexec.html @@ -1,6 +1,7 @@ - + + grammar::fa::dexec - Finite automaton operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::fa::dexec(n) 0.2 tcllib "Finite automaton operations and usage"

    Name

    grammar::fa::dexec - Execute deterministic finite automatons

    @@ -251,23 +252,17 @@ bugs and other problems. Please report such in the category grammar_fa of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_fa/fa.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_fa/fa.html +++ idoc/www/tcllib/files/modules/grammar_fa/fa.html @@ -1,6 +1,7 @@ - + + grammar::fa - Finite automaton operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::fa(n) 0.4 tcllib "Finite automaton operations and usage"

    Name

    grammar::fa - Create and manipulate finite automatons

    @@ -311,15 +312,15 @@ Drive -- yellow --> Brake -- red --> (Stop) -- red/yellow --> Attention -- green --> Drive (...) is the start state.

    a possible serialization is

    -    grammar::fa \
-    {yellow red green red/yellow} \
-    {Drive     {0 0 {yellow     Brake}} \
-     Brake     {0 0 {red        Stop}} \
-     Stop      {1 0 {red/yellow Attention}} \
+    grammar::fa \\
+    {yellow red green red/yellow} \\
+    {Drive     {0 0 {yellow     Brake}} \\
+     Brake     {0 0 {red        Stop}} \\
+     Stop      {1 0 {red/yellow Attention}} \\
      Attention {0 0 {green      Drive}}}

    A possible one, because I did not care about creation order here

    faName deserialize serialization

    This is the complement to serialize. It replaces the @@ -367,24 +368,24 @@ least one start state. They operation will fail if the set contains an element which is not a known state. The result is a boolean value. It will be set to true if a start state is present in stateset, and false otherwise.

    faName finalstates
    -

    Returns the set of states which are marked as final states, +

    Returns the set of states which are marked as final states, also known as accepting states. See FINITE AUTOMATONS for explanations what this means.

    faName final add s1 ?s2 ...?

    Mark the states s1, s2, et cetera in the FA faName -as final (aka accepting).

    +as final (aka accepting).

    faName final remove s1 ?s2 ...?

    Mark the states s1, s2, et cetera in the FA faName as not final (aka not accepting).

    faName final? s

    A predicate. It tests if the state s in the FA faName is -final or not. +final or not. The result is a boolean value. It will be set to true if the -state s is final, and false otherwise.

    +state s is final, and false otherwise.

    faName final?set stateset

    A predicate. It tests if the set of states stateset contains at least one final state. They operation will fail if the set contains an element which is not a known state. The result is a boolean value. It will be set to true if a @@ -558,11 +559,11 @@

    • S is a set of states,

    • Sy a set of input symbols,

    • St is a subset of S, the set of start states, also known as initial states.

      • -

    • Fi is a subset of S, the set of final states, also known as +

    • Fi is a subset of S, the set of final states, also known as accepting.

    • T is a function from S x (Sy + epsilon) to {S}, the transition function. Here epsilon denotes the empty input symbol and is distinct from all symbols in Sy; and {S} is the set of subsets of S. In other words, T maps a combination of State and Input (which can be empty) to @@ -579,21 +580,21 @@ ... sy_n if there is a path in the graph of the FA beginning at a state in St and ending at a state in Fi whose edges have the labels sy_1, sy_2, etc. to sy_n. The set of all strings accepted by the FA is the language of the FA. One important equivalence is that the set of languages which -can be accepted by an FA is the set of regular languages.

      +can be accepted by an FA is the set of regular languages.

      Another important concept is that of deterministic FAs. A FA is said to be deterministic if for each string of input symbols there is exactly one path in the graph of the FA beginning at the start state and whose edges are labeled with the symbols in the string. While it might seem that non-deterministic FAs to have more power of recognition, this is not so. For each non-deterministic FA we can construct a deterministic FA which accepts the same language (--> Thompson's subset construction).

      -

      While one of the premier applications of FAs is in parsing, -especially in the lexer stage (where symbols == characters), +

      While one of the premier applications of FAs is in parsing, +especially in the lexer stage (where symbols == characters), this is not the only possibility by far.

      Quite a lot of processes can be modeled as a FA, albeit with a possibly large set of states. For these the notion of accepting states is often less or not relevant at all. What is needed instead is the ability to act to state changes in the FA, i.e. to generate some @@ -615,22 +616,16 @@ bugs and other problems. Please report such in the category grammar_fa of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_fa/faop.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_fa/faop.html +++ idoc/www/tcllib/files/modules/grammar_fa/faop.html @@ -1,6 +1,7 @@ - + + grammar::fa::op - Finite automaton operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::fa::op(n) 0.4 tcllib "Finite automaton operations and usage"

    Name

    grammar::fa::op - Operations on finite automatons

    @@ -194,11 +195,11 @@

    Any container class using this package for complex operations should set its own class command as the constructor. See package grammar::fa for an example.

    ::grammar::fa::op::reverse fa

    Reverses the fa. This is done by reversing the direction of all -transitions and swapping the sets of start and final +transitions and swapping the sets of start and final states. The language of fa changes unpredictably.

    ::grammar::fa::op::complete fa ?sink?

    Completes the fa complete, but nothing is done if the fa is already complete. This implies that only the first in a series of multiple consecutive complete operations on fa @@ -451,22 +452,16 @@ bugs and other problems. Please report such in the category grammar_fa of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/gasm.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/gasm.html +++ idoc/www/tcllib/files/modules/grammar_me/gasm.html @@ -1,6 +1,7 @@ - + + grammar::me::cpu::gasm - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me::cpu::gasm(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me::cpu::gasm - ME assembler

    @@ -432,22 +433,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_ast.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_ast.html +++ idoc/www/tcllib/files/modules/grammar_me/me_ast.html @@ -1,6 +1,7 @@ - + + grammar::me_ast - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me_ast(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me_ast - Various representations of ASTs

    @@ -124,11 +125,11 @@
  • Copyright

    • Description

    This document specifies various representations for the -abstract syntax trees (short AST) generated by +abstract syntax trees (short AST) generated by instances of ME virtual machines, independent of variant. Please go and read the document grammar::me_intro first if you do not know what a ME virtual machine is.

    ASTs and all the representations we specify distinguish between two types of nodes, namely:

    @@ -205,22 +206,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_cpu.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_cpu.html +++ idoc/www/tcllib/files/modules/grammar_me/me_cpu.html @@ -1,6 +1,7 @@ - + + grammar::me::cpu - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me::cpu(n) 0.2 tcllib "Grammar operations and usage"

    Name

    grammar::me::cpu - Virtual machine implementation II for parsing token streams

    @@ -344,22 +345,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_cpucore.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_cpucore.html +++ idoc/www/tcllib/files/modules/grammar_me/me_cpucore.html @@ -1,6 +1,7 @@ - + + grammar::me::cpu::core - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me::cpu::core(n) 0.2 tcllib "Grammar operations and usage"

    Name

    grammar::me::cpu::core - ME virtual machine state manipulation

    @@ -313,11 +314,11 @@ for.

    MATCH PROGRAM REPRESENTATION

    A match program is represented by nested Tcl list. The first element, asm, is a list of integer numbers, the instructions to execute, -and their arguments. The second element, pool, is a list of +and their arguments. The second element, pool, is a list of strings, referenced by the instructions, for error messages, token names, etc. The third element, tokmap, provides ordering information for the tokens, mapping their names to their numerical rank. This element can be empty, forcing lexicographic comparison when matching ranges.

    @@ -327,13 +328,13 @@ message explicitly instead of having it constructed from token names, etc. This allows the machine state to store only the message ids instead of the full strings.

    Jump destination arguments are absolute indices into the asm element, refering to the instruction to jump to. Any string arguments -are absolute indices into the pool element. Tokens, characters, +are absolute indices into the pool element. Tokens, characters, messages, and token (actually character) classes to match are coded as -references into the pool as well.

    +references into the pool as well.

    1. "ict_advance message"

    2. "ict_match_token tok message"

    3. "ict_match_tokrange tokbegin tokend message"

    4. "ict_match_tokclass code message"

      5. @@ -374,19 +375,19 @@

    5. pc: Program counter, int.

    6. halt: Halt flag, boolean.

    7. eof: Eof flag, boolean

    8. tc: Terminal cache, and input queue. Structure see below.

    9. cl: Current location, int.

      10. -

    10. ct: Current token, string.

      11. +

    11. ct: Current token, string.

    12. ok: Match status, boolean.

      13. -

    13. sv: Semantic value, list.

      14. -

    14. er: Error status, list.

      15. -

    15. ls: Location stack, list.

      16. -

    16. as: AST stack, list.

      17. -

    17. ms: AST marker stack, list.

      18. -

    18. es: Error stack, list.

      19. -

    19. rs: Return stack, list.

      20. +

    20. sv: Semantic value, list.

      21. +

    21. er: Error status, list.

      22. +

    22. ls: Location stack, list.

      23. +

    23. as: AST stack, list.

      24. +

    24. ms: AST marker stack, list.

      25. +

    25. es: Error stack, list.

      26. +

    26. rs: Return stack, list.

    27. nc: Nonterminal cache, dictionary.

    tc, the input queue of tokens waiting for processing and the terminal cache containing the tokens already processing are one unified data structure simply holding all tokens and their @@ -397,11 +398,11 @@

    All stacks have their top element aat the end, i.e. pushing an item is equivalent to appending to the list representing the stack, and popping it removes the last element.

    er, the error status is either empty or a list of two elements, a location in the input, and a list of messages, encoded as references -into the pool element of the code.

    +into the pool element of the code.

    nc, the nonterminal cache is keyed by nonterminal name and location, each value a four-element list containing current location, match status, semantic value, and error status, in this order.

    Bugs, Ideas, Feedback

    @@ -409,22 +410,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_intro.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_intro.html +++ idoc/www/tcllib/files/modules/grammar_me/me_intro.html @@ -1,6 +1,7 @@ - + + grammar::me_intro - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me_intro(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me_intro - Introduction to virtual machines for parsing token streams

    @@ -125,17 +126,17 @@

    This document is an introduction to and overview of the basic facilities for the parsing and/or matching of token streams. One possibility often used for the token domain are characters.

    The packages themselves all provide variants of one -virtual machine, called a match engine (short +virtual machine, called a match engine (short ME), which has all the facilities needed for the matching and parsing of a stream, and which are either controlled directly, or are customized with a match program. The virtual machine is basically a pushdown automaton, with additional elements for backtracking and/or handling of semantic data and construction of abstract syntax trees -(AST).

    +(AST).

    Because of the high degree of similarity in the actual implementations of the aforementioned virtual machine and the data structures they receive and generate these common parts are specified in a separate document which will be referenced by the documentation for packages actually implementing it.

    @@ -166,22 +167,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_tcl.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_tcl.html +++ idoc/www/tcllib/files/modules/grammar_me/me_tcl.html @@ -1,6 +1,7 @@ - + + grammar::me::tcl - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me::tcl(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me::tcl - Virtual machine implementation I for parsing token streams

    @@ -389,22 +390,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_util.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_util.html +++ idoc/www/tcllib/files/modules/grammar_me/me_util.html @@ -1,6 +1,7 @@ - + + grammar::me::util - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me::util(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me::util - AST utilities

    @@ -186,22 +187,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_me/me_vm.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_me/me_vm.html +++ idoc/www/tcllib/files/modules/grammar_me/me_vm.html @@ -1,6 +1,7 @@ - + + grammar::me_vm - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::me_vm(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::me_vm - Virtual machine for parsing token streams

    @@ -137,11 +138,11 @@

    Description

    Please go and read the document grammar::me_intro first for an overview of the various documents and their relations.

    This document specifies a virtual machine for the controlled matching and parsing of token streams, creating an -abstract syntax tree (short AST) reflecting the +abstract syntax tree (short AST) reflecting the structure of the input. Special machine features are the caching and reuse of partial results, caching of the encountered input, and the ability to backtrack in both input and AST creation.

    These features make the specified virtual machine especially useful to packrat parsers based on parsing expression grammars. It is however @@ -536,22 +537,16 @@ bugs and other problems. Please report such in the category grammar_me of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_peg/peg.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_peg/peg.html +++ idoc/www/tcllib/files/modules/grammar_peg/peg.html @@ -1,6 +1,7 @@ - + + grammar::peg - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::peg(n) 0.1 tcllib "Grammar operations and usage"

    Name

    grammar::peg - Create and manipulate parsing expression grammars

    @@ -186,11 +187,11 @@ often left out. The union of the sets of terminal and nonterminal symbols is called the set of symbols.

    Here the set of terminal symbols is not explicitly managed, but implicitly defined as the set of all characters. Note that this means that we inherit from Tcl the ability to handle all of Unicode.

    -

    A pair of nonterminal and parsing expression is also +

    A pair of nonterminal and parsing expression is also called a grammatical rule, or rule for short. In the context of a rule the nonterminal is often called the left-hand-side (LHS), and the parsing expression the right-hand-side (RHS).

    The start expression of a grammar is a parsing expression from which all the sentences contained in the language specified by @@ -348,24 +349,24 @@ AddOp <- '+'/'-' Term <- Number

    a possible serialization is

    -    grammar::peg \
-    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \
-     Factor     {x Term {* {x AddOp Term}}} \
-     Term       Number \
-     MulOp      {/ * /} \
-     AddOp      {/ + -} \
-     Number     {x {? Sign} {+ Digit}} \
-     Sign       {/ + -} \
-     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \
-    } \
-    {Expression value     Factor     value \
-     Term       value     MulOp      value \
-     AddOp      value     Number     value \
-     Sign       value     Digit      value \
+    grammar::peg \\
+    {Expression {/ {x ( Expression )} {x Factor {* {x MulOp Factor}}}} \\
+     Factor     {x Term {* {x AddOp Term}}} \\
+     Term       Number \\
+     MulOp      {/ * /} \\
+     AddOp      {/ + -} \\
+     Number     {x {? Sign} {+ Digit}} \\
+     Sign       {/ + -} \\
+     Digit      {/ 0 1 2 3 4 5 6 7 8 9} \\
+    } \\
+    {Expression value     Factor     value \\
+     Term       value     MulOp      value \\
+     AddOp      value     Number     value \\
+     Sign       value     Digit      value \\
     }
     Expression

    A possible one, because the order of the nonterminals in the dictionary is not relevant.

    @@ -521,11 +522,11 @@

    For the mathematically inclined, a PEG is a 4-tuple (VN,VT,R,eS) where

    • VN is a set of nonterminal symbols,

    • VT is a set of terminal symbols,

    • R is a finite set of rules, where each rule is a pair (A,e), A in VN, -and e a parsing expression.

      • +and e a parsing expression.

    • eS is a parsing expression, the start expression.

    Further constraints are

    • The intersection of VN and VT is empty.

      • @@ -539,19 +540,19 @@

    • A nonterminal symbol A is a parsing expression.

    • e1e2 is a parsing expression for parsing expressions e1 and 2. This is called sequence.

    • e1/e2 is a parsing expression for parsing expressions e1 and 2. This is called ordered choice.

      • -

    • e* is a parsing expression for parsing expression -e. This is called zero-or-more repetitions, also known +

    • e* is a parsing expression for parsing expression +e. This is called zero-or-more repetitions, also known as kleene closure.

      • -

    • e+ is a parsing expression for parsing expression -e. This is called one-or-more repetitions, also known +

    • e+ is a parsing expression for parsing expression +e. This is called one-or-more repetitions, also known as positive kleene closure.

      • -

    • !e is a parsing expression for parsing expression +

    • !e is a parsing expression for parsing expression e1. This is called a not lookahead predicate.

      • -

    • &e is a parsing expression for parsing expression +

    • &e is a parsing expression for parsing expression e1. This is called an and lookahead predicate.

    PEGs are used to define a grammatical structure for streams of symbols over VT. They are a modern phrasing of older formalisms invented by Alexander Birham. These formalisms were called TS (TMG recognition @@ -579,22 +580,16 @@ bugs and other problems. Please report such in the category grammar_peg of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/grammar_peg/peg_interp.html ================================================================== --- idoc/www/tcllib/files/modules/grammar_peg/peg_interp.html +++ idoc/www/tcllib/files/modules/grammar_peg/peg_interp.html @@ -1,6 +1,7 @@ - + + grammar::peg::interp - Grammar operations and usage - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    grammar::peg::interp(n) 0.1.1 tcllib "Grammar operations and usage"

    Name

    grammar::peg::interp - Interpreter for parsing expression grammars

    @@ -199,22 +200,16 @@ bugs and other problems. Please report such in the category grammar_peg of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Grammars and finite automata

    Index: idoc/www/tcllib/files/modules/hook/hook.html ================================================================== --- idoc/www/tcllib/files/modules/hook/hook.html +++ idoc/www/tcllib/files/modules/hook/hook.html @@ -1,6 +1,7 @@ - + + hook - Hooks - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    hook(n) 0.1 tcllib "Hooks"

    Name

    hook - Hooks

    @@ -178,28 +179,28 @@

    Bindings

    The hook command manages a collection of hook bindings. A hook binding has four elements:

      -

    1. A subject: the name of the entity that will be calling the +

    2. A subject: the name of the entity that will be calling the hook.

      3. -

    3. The hook itself. A hook usually reflects some occurrence in the -life of the subject that other entities might care to know -about. A hook has a name, and may also have arguments. Hook -names are arbitrary strings. Each subject must document the +

    4. The hook itself. A hook usually reflects some occurrence in the +life of the subject that other entities might care to know +about. A hook has a name, and may also have arguments. Hook +names are arbitrary strings. Each subject must document the names and arguments of the hooks it can call.

      5. -

    5. The name of the observer that wishes to receive the hook -from the subject.

      6. -

    6. A command prefix to which the hook arguments will be appended +

    7. The name of the observer that wishes to receive the hook +from the subject.

      8. +

    8. A command prefix to which the hook arguments will be appended when the binding is executed.

    Subjects and observers

    For convenience, this document collectively refers to subjects and observers as objects, while placing no requirements on how these objects are actually implemented. An object can be a -TclOO or Snit or XOTcl object, a Tcl +TclOO or Snit or XOTcl object, a Tcl command, a namespace, a module, a pseudo-object managed by some other object (as tags are managed by the Tk text widget) or simply a well-known name.

    Subject and observer names are arbitrary strings; however, as hook might be used at the package level, it's necessary to have @@ -321,12 +322,12 @@ value, its value will be invoked for all errors and other exceptional returns in observer bindings. See hook configure, below, for more information on configuration options.

    hook forget object

    This command deletes any existing bindings in which the named -object appears as either the subject or the -observer. +object appears as either the subject or the +observer. Bindings deleted by this method will never be called again. In particular,

    1. If an observer is forgotten during a call to hook call, any uncalled binding it might have had to the relevant subject and hook @@ -358,12 +359,12 @@ (thus preventing the error from arising a second time) and so forth.

    -tracecommand cmdPrefix

    The option's value should be a command prefix taking four arguments:

      -

    1. a subject,

      2. -

    2. a hook,

      3. +

    3. a subject,

      4. +

    4. a hook,

    5. a list of the hook's argument values, and

    6. a list of objects the hook was called for.

    The command will be called for each hook that is called. This allows the application to trace hook execution for debugging purposes.

    @@ -383,11 +384,11 @@ hook bind ::model <Update> .view [list .view ModelUpdate]

    When the ::model calls the hook, the .views ModelUpdate subcommand will be called.

    Later the .view megawidget is destroyed. In its destructor, -it tells the hook that it no longer exists:

    +it tells the hook that it no longer exists:

          hook forget .view

    All bindings involving .view are deleted.

    @@ -399,25 +400,19 @@ bugs and other problems. Please report such in the category hook of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/html/html.html ================================================================== --- idoc/www/tcllib/files/modules/html/html.html +++ idoc/www/tcllib/files/modules/html/html.html @@ -1,6 +1,7 @@ - + + html - HTML Generation - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    html(n) 1.5 tcllib "HTML Generation"

    +

    html(n) 1.4.4 tcllib "HTML Generation"

    Name

    html - Procedures to generate HTML structures

    Table Of Contents

      @@ -122,11 +123,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require html ?1.5?
      • +
    • package require html ?1.4.4?

    Description

    The package html provides commands that generate HTML. @@ -216,20 +213,20 @@ td (or th) tag. The tag parameters come from param or TD.* attributes defined with ::html::init. This uses ::html::font to insert a standard font tag into the table cell. The tag argument defaults to "td".

    ::html::checkbox name value
    -

    Generate a checkbox form element with the specified name and value. +

    Generate a checkbox form element with the specified name and value. This uses ::html::checkValue.

    ::html::checkSet key sep list
    -

    Generate a set of checkbox form elements and associated labels. The +

    Generate a set of checkbox form elements and associated labels. The list should contain an alternating list of labels and values. -This uses ::html::checkbox. All the checkbox buttons share the +This uses ::html::checkbox. All the checkbox buttons share the same key for their name. The sep is text used to separate the elements.

    ::html::checkValue name ?value?
    -

    Generate the "name=name value=value" for a checkbox form +

    Generate the "name=name value=value" for a checkbox form element. If the CGI variable name has the value value, then SELECTED is added to the return value. value defaults to "1".

    ::html::closeTag

    Pop a tag off the stack created by ::html::openTag and generate @@ -270,11 +267,11 @@

    This procedure is similar to the built-in Tcl for control structure. Rather than evaluating the body, it returns the subst'ed body. Each iteration of the loop causes another string to be concatenated to the result value.

    ::html::foreach varlist1 list1 ?varlist2 list2 ...? body
    -

    This procedure is similar to the built-in Tcl foreach control +

    This procedure is similar to the built-in Tcl foreach control structure. Rather than evaluating the body, it returns the subst'ed body. Each iteration of the loop causes another string to be concatenated to the result value.

    ::html::formValue name ?defvalue?

    Return a name and value pair, where the value is initialized from @@ -316,11 +313,11 @@ ::html::keywords, ::html::description, or ::html::meta then additional tags are inserted into the head section. -This leaves an open html tag pushed on the stack with +This leaves an open html tag pushed on the stack with ::html::openTag.

    ::html::headTag string

    Save a tag for inclusion in the head section generated by ::html::head. The string is everything in the tag except the enclosing angle brackets, < >.

    @@ -343,163 +340,141 @@ define a keyword meta tag for the page. The meta tag is included in the result of ::html::head.

    ::html::mailto email ?subject?

    Generate a hypertext link to a mailto: URL.

    ::html::meta args
    -

    Compatibility name for html::meta_name.

    -
    ::html::meta_name args
    -

    Side effect only. -Call this before ::html::head to define a meta tag for -the page. -The arguments (args) are a Tcl-style name, value list that is -used for the name= and content= attributes of the -meta tag. The meta tag is included in the result of -::html::head.

    -
    ::html::meta_equiv args
    -

    Side effect only. -Call this before ::html::head to define a meta tag for -the page. -The arguments (args) are a Tcl-style name, value list that is -used for the http-equiv= and content= attributes of -the meta tag. The meta tag is included in the result of -::html::head.

    -
    ::html::meta_charset charset
    -

    Side effect only. -Call this before ::html::head to -define a meta tag for the page. -The charset is used with the charset= attribute of the -meta tag. The meta tag is included in the result of -::html::head.

    -
    ::html::css href
    +

    Side effect only. Call this before ::html::head to +define a meta tag for the page. The args is a Tcl-style name, +value list that is used for the name= and value= parameters for the +meta tag. The meta tag is included in the result of +::html::head.

    +
    ::html::css href

    Side effect only. Call this before ::html::head to define a link tag for a linked CSS document. The href value is a HTTP URL to a CSS document. The link tag is included in the result of ::html::head.

    Multiple calls of this command are allowed, enabling the use of multiple CSS document references. In other words, the arguments of multiple calls are accumulated, and do not overwrite each other.

    -
    ::html::css-clear
    +
    ::html::css-clear

    Side effect only. Call this before ::html::head to clear all links to CSS documents.

    Multiple calls of this command are allowed, doing nothing after the first of a sequence with no intervening ::html::css.

    -
    ::html::js href
    +
    ::html::js href

    Side effect only. Call this before ::html::head to define a script tag for a linked JavaScript document. The href is a HTTP URL to a JavaScript document. The script tag is included in the result of ::html::head.

    Multiple calls of this command are allowed, enabling the use of multiple JavaScript document references. In other words, the arguments of multiple calls are accumulated, and do not overwrite each other.

    -
    ::html::js-clear
    +
    ::html::js-clear

    Side effect only. Call this before ::html::head to clear all links to JavaScript documents.

    Multiple calls of this command are allowed, doing nothing after the first of a sequence with no intervening ::html::js.

    -
    ::html::minorList list ?ordered?
    +
    ::html::minorList list ?ordered?

    Generate an ordered or unordered list of links. The list is a Tcl-style name, value list of labels and urls for the links. ordered is a boolean used to choose between an ordered or unordered list. It defaults to false.

    -
    ::html::minorMenu list ?sep?
    +
    ::html::minorMenu list ?sep?

    Generate a series of hypertext links. The list is a Tcl-style name, value list of labels and urls for the links. The sep is the text to put between each link. It defaults to " | ".

    -
    ::html::nl2br string
    +
    ::html::nl2br string

    This command replaces all line-endings in the string with a br tag and returns the modified text.

    -
    ::html::openTag tag ?param?
    +
    ::html::openTag tag ?param?

    Push tag onto a stack and generate the opening tag for tag. Use ::html::closeTag to pop the tag from the stack. The second argument provides any tag arguments, as a list whose elements are formatted to be in the form "key=value".

    -
    ::html::paramRow list ?rparam? ?cparam?
    +
    ::html::paramRow list ?rparam? ?cparam?

    Generate a table row, including tr and td tags. Each value in list is placed into its own table cell. This uses ::html::cell. The value of rparam is used as parameter for the tr tag. The value of cparam is passed to ::html::cell as parameter for the td tags.

    -
    ::html::passwordInput ?name?
    -

    Generate an input tag of type password. The name defaults to +

    ::html::passwordInput ?name?
    +

    Generate an input tag of type password. The name defaults to "password".

    -
    ::html::passwordInputRow label ?name?
    +
    ::html::passwordInputRow label ?name?

    Format a table row containing a label and an input tag of type -password. The name defaults to "password".

    -
    ::html::quoteFormValue value
    +password. The name defaults to "password".

    +
    ::html::quoteFormValue value

    Quote special characters in value by replacing them with HTML entities for quotes, ampersand, and angle brackets.

    -
    ::html::radioSet key sep list
    +
    ::html::radioSet key sep list

    Generate a set of input tags of type radio and an associated text label. All the radio buttons share the same key for their name. The sep is text used to separate the elements. The list is a Tcl-style label, value list.

    -
    ::html::radioValue name value
    +
    ::html::radioValue name value

    Generate the "name=name value=value" for a radio form element. If the CGI variable name has the value value, then SELECTED is added to the return value.

    -
    ::html::refresh seconds url
    +
    ::html::refresh seconds url

    Set up a refresh meta tag. Call this before ::html::head and the HEAD section will contain a meta tag that causes the document to refresh in seconds seconds. The url is optional. If specified, it specifies a new page to load after the refresh interval.

    -
    ::html::row args
    +
    ::html::row args

    Generate a table row, including tr and td tags. Each value in args is place into its own table cell. This uses ::html::cell. Ignores any default information set up via ::html::init.

    -
    ::html::select name param choices ?current?
    +
    ::html::select name param choices ?current?

    Generate a select form element and nested option tags. The name and param are used to generate the select tag. The choices list is a Tcl-style name, value list.

    -
    ::html::selectPlain name param choices ?current?
    +
    ::html::selectPlain name param choices ?current?

    Like ::html::select except that choices is a Tcl list of values used for the option tags. The label and the value for each option are the same.

    -
    ::html::set var val
    -

    This procedure is similar to the built-in Tcl set command. The +

    ::html::set var val
    +

    This procedure is similar to the built-in Tcl set command. The main difference is that it returns "" so it can be called from an HTML template file without appending unwanted results. The other difference is that it must take two arguments.

    -
    ::html::submit label ?name? ?title?
    -

    Generate an input tag of type submit. -The name defaults to "submit". -When a non-empty title string is specified the button gains a -title= attribute with that value.

    -
    ::html::tableFromArray arrname ?param? ?pat?
    -

    Generate a two-column table and nested rows to display a Tcl array. The +

    ::html::submit label ?name?
    +

    Generate an input tag of type submit. name defaults to "submit".

    +
    ::html::tableFromArray arrname ?param? ?pat?
    +

    Generate a two-column table and nested rows to display a Tcl array. The table gets a heading that matches the array name, and each generated row contains a name, value pair. The array names are sorted (lsort without -special options). The argument param is for the table tag and has +special options). The argument param is for the table tag and has to contain a pre-formatted string. The pat is a string match pattern used to select the array elements to show in the table. It defaults to *, i.e. the whole array is shown.

    -
    ::html::tableFromList querylist ?param?
    -

    Generate a two-column table and nested rows to display querylist, +

    ::html::tableFromList querylist ?param?
    +

    Generate a two-column table and nested rows to display querylist, which is a Tcl dictionary. Each generated row contains a name, value pair. The information is shown in the same order as specified in the dictionary. The -argument param is for the table tag and has to contain a +argument param is for the table tag and has to contain a pre-formatted string.

    -
    ::html::textarea name ?param? ?current?
    +
    ::html::textarea name ?param? ?current?

    Generate a textarea tag wrapped around its current values.

    -
    ::html::textInput name value args
    -

    Generate an input form tag with type text. This uses +

    ::html::textInput name value args
    +

    Generate an input form tag with type text. This uses ::html::formValue. The args is any additional tag attributes you want to put into the input tag.

    -
    ::html::textInputRow label name value args
    -

    Generate an input form tag with type text formatted into a table row +

    ::html::textInputRow label name value args
    +

    Generate an input form tag with type text formatted into a table row with an associated label. The args is any additional tag attributes you want to put into the input tag.

    -
    ::html::varEmpty name
    +
    ::html::varEmpty name

    This returns 1 if the named variable either does not exist or has the empty string for its value.

    -
    ::html::while test body
    +
    ::html::while test body

    This procedure is similar to the built-in Tcl while control structure. Rather than evaluating the body, it returns the subst'ed body. Each iteration of the loop causes another string to be concatenated to the result value.

    -
    ::html::doctype id
    +
    ::html::doctype id

    This procedure can be used to build the standard DOCTYPE declaration string. It will return the standard declaration string for the id, or throw an error if the id is not known. The following id's are defined:

      @@ -514,37 +489,25 @@

    1. XHTML10T

    2. XHTML10F

    3. XHTML11

    4. XHTMLB

    -
    ::html::wrapTag tag ?text? ?args?
    -

    A helper to wrap a text in a pair of open/close tags. -The arguments (args) are a Tcl-style name, value list that is -used to provide attributes and associated values to the opening tag. -The result is a string with the open tag along with the optional -attributes, the optional text, and the closed tag.

    Bugs, Ideas, Feedback

    This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category html of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    CGI programming

    Index: idoc/www/tcllib/files/modules/htmlparse/htmlparse.html ================================================================== --- idoc/www/tcllib/files/modules/htmlparse/htmlparse.html +++ idoc/www/tcllib/files/modules/htmlparse/htmlparse.html @@ -1,6 +1,7 @@ - + + htmlparse - HTML Parser - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    htmlparse(n) 1.2.2 tcllib "HTML Parser"

    Name

    htmlparse - Procedures to parse HTML strings

    @@ -305,22 +306,16 @@ bugs and other problems. Please report such in the category htmlparse of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Text processing

    Index: idoc/www/tcllib/files/modules/http/autoproxy.html ================================================================== --- idoc/www/tcllib/files/modules/http/autoproxy.html +++ idoc/www/tcllib/files/modules/http/autoproxy.html @@ -1,6 +1,6 @@ - + autoproxy - HTTP protocol helper modules - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    autoproxy(n) 1.7 tcllib "HTTP protocol helper modules"

    +

    autoproxy(n) 1.5.3 tcllib "HTTP protocol helper modules"

    Name

    autoproxy - Automatic HTTP proxy usage and authentication

    Table Of Contents

      @@ -129,13 +129,13 @@

    Synopsis

      -
    • package require Tcl 8.5
      • +
    • package require Tcl 8.2
    • package require http ?2.0?
      • -
    • package require autoproxy ?1.7?
      • +
    • package require autoproxy ?1.5.3?

    TLS Security Considerations

    -

    Note This section only applies if TLS support is provided -by the TLS package. -It does not apply when autoproxy was configured to use some -other package which can provide the same (i.e twapi), via -the -tls_package configuration option.

    -

    This package uses the TLS package to handle the -security for https urls and other socket connections.

    +

    This package uses the TLS package to handle the security +for https urls and other socket connections.

    Policy decisions like the set of protocols to support and what -ciphers to use are not the responsibility of TLS, nor of +ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and are likely influenced by the set of servers the application will talk to as well.

    For example, in light of the recent POODLE attack discovered by Google many servers will disable support for the SSLv3 protocol. -To handle this change the applications using TLS must be -patched, and not this package, nor TLS itself. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below.

         package require tls
     tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
@@ -208,19 +203,17 @@
 
    ::autoproxy::tls_connect args
    
 
    Connect to a secure socket through a proxy. HTTP proxy servers permit
 the use of the CONNECT HTTP command to open a link through the proxy
 to the target machine. This function hides the details. For use with
 the http package see tls_socket.
    
-
    The args list may contain any of the options
-supported by the specific TLS package that is in use but
+
    The args list may contain any of the tls package options but
 must end with the host and port as the last two items.
    
 
    ::autoproxy::tunnel_connect args
    
 
    Connect to a target host throught a proxy. This uses the same CONNECT
 HTTP command as the tls_connect but does not promote the link
 security once the connection is established.
    
-
    The args list may contain any of the options
-supported by the specific TLS package that is in use but
+
    The args list may contain any of the tls package options but
 must end with the host and port as the last two items.
    
 
    Note that many proxy servers will permit CONNECT calls to a limited
 set of ports - typically only port 443 (the secure HTTP port).
    
 
    ::autoproxy::tls_socket args
    
 
    This function is to be used to register a proxy-aware secure socket
@@ -254,18 +247,11 @@
 called when configure -basic is called with either no or
 insufficient authentication details. This can be used to present a
 dialog to the user to request the additional information.
    
 
    -basic
    
 
    Following options are for configuring the Basic authentication
-scheme parameters. See Basic Authentication.
-To unset the proxy authentication information retained from a previous
-call of this function either "--" or no additional parameters can be
-supplied. This will remove the existing authentication information.
    
-
    -tls_package packagename
    
-
    This option may be used to configure the Tcl package to use for
-TLS support. Valid package names are tls (default)
-and twapi.
    
+scheme parameters. See Basic Authentication.

    Basic Authentication

    Basic is the simplest and most commonly use HTTP proxy authentication scheme. It is described in (1 section 11) and also in (2). It offers @@ -279,15 +265,11 @@

    -username name

    The username required to authenticate with the configured proxy.

    -password password

    The password required for the username specified.

    -realm realm
    -

    This option is not used by this package but may be used in requesting -authentication details from the user.

    -
    --
    -

    The end-of-options indicator may be used alone to unset any -authentication details currently enabled.

    +

    This option is not used.

    EXAMPLES

     package require autoproxy
@@ -329,22 +311,16 @@
 bugs and other problems.
 Please report such in the category http :: autoproxy of the
 Tcllib Trackers.
 Please also report any ideas for enhancements you may have for either
 package and/or documentation.
    
-
    When proposing code changes, please provide unified diffs,
-i.e the output of diff -u.
    
-
    Note further that attachments are strongly preferred over
-inlined patches. Attachments can be made by going to the Edit
-form of the ticket immediately after its creation, and then using the
-left-most button in the secondary navigation bar.

    See Also

    http(n)

    Category

    Networking

    DELETED idoc/www/tcllib/files/modules/httpd/httpd.html Index: idoc/www/tcllib/files/modules/httpd/httpd.html ================================================================== --- idoc/www/tcllib/files/modules/httpd/httpd.html +++ idoc/www/tcllib/files/modules/httpd/httpd.html @@ -1,819 +0,0 @@ - -httpd - Tcl Web Server - - - - - -
    [ - Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications - ]
    -
    -

    httpd(n) 4.3.5 tcllib "Tcl Web Server"

    -

    Name

    -

    httpd - A TclOO and coroutine based web server

    -
    - -

    Synopsis

    -
    -
      -
    • package require Tcl 8.6
      • -
    • package require uuid
      • -
    • package require clay
      • -
    • package require coroutine
      • -
    • package require fileutil
      • -
    • package require fileutil::magic::filetype
      • -
    • package require websocket
      • -
    • package require mime
      • -
    • package require cron
      • -
    • package require uri
      • -
    • package require Markdown
      • -
    - -
    -
    -

    Description

    -

    This module implements a web server, suitable for embedding in an -application. The server is object oriented, and contains all of the -fundamentals needed for a full service website.

    -
    -

    Minimal Example

    -

    Starting a web service requires starting a class of type -httpd::server, and providing that server with one or more URIs -to service, and httpd::reply derived classes to generate them.

    -
    -oo::class create ::reply.hello {
-  method content {} {
-    my puts "<HTML><HEAD><TITLE>IRM Dispatch Server</TITLE></HEAD><BODY>"
-    my puts "<h1>Hello World!</h1>"
-    my puts </BODY></HTML>
-  }
-}
-::httpd::server create HTTPD port 8015 myaddr 127.0.0.1 doc_root ~/htdocs
-HTTPD plugin dispatch httpd::server::dispatch
-HTTPD uri add * /hello [list mixin reply.hello]
-
    -

    The bare module does have facilities to hose a files from a file system. Files that end in a .tml will be substituted in the style of Tclhttpd:

    -
    -<!-- hello.tml -->
-[my html_header {Hello World!}]
-Your Server is running.
-<p>
-The time is now [clock format [clock seconds]]
-[my html_footer]
-
    -

    A complete example of an httpd server is in the /examples directory of Tcllib. It also show how to dispatch URIs to other processes via SCGI and HTTP proxies.

    -
    -cd ~/tcl/sandbox/tcllib
-tclsh examples/httpd.tcl
-
    -
    -

    Classes

    -

    Class httpd::mime

    -

    A metaclass for MIME handling behavior across a live socket

    -

    Methods

    -
    -
    method ChannelCopy in out ?args?
    -
    -
    method html_header ?title ? ?args?
    -

    Returns a block of HTML

    -
    method html_footer ?args?
    -
    -
    method http_code_string code
    -
    -
    method HttpHeaders sock ?debug ?
    -
    -
    method HttpHeaders_Default
    -
    -
    method HttpServerHeaders
    -
    -
    method MimeParse mimetext
    -

    Converts a block of mime encoded text to a key/value list. If an exception is encountered, - the method will generate its own call to the error method, and immediately invoke - the output method to produce an error code and close the connection.

    -
    method Url_Decode data
    -

    De-httpizes a string.

    -
    method Url_PathCheck urlsuffix
    -
    -
    method wait mode sock
    -
    -
    -
    -

    Class httpd::reply

    -

    ancestors: httpd::mime

    -

    A class which shephards a request through the process of generating a - reply. - The socket associated with the reply is available at all times as the chan - variable. - The process of generating a reply begins with an httpd::server generating a - http::class object, mixing in a set of behaviors and then invoking the reply - object's dispatch method. - In normal operations the dispatch method:

    -
      - -

    1. Invokes the reset method for the object to populate default headers.

      2. -

    2. Invokes the HttpHeaders method to stream the MIME headers out of the socket

      3. -

    3. Invokes the request parse method to convert the stream of MIME headers into a - dict that can be read via the request method.

      4. -

    4. Stores the raw stream of MIME headers in the rawrequest variable of the object.

      5. -

    5. Invokes the content method for the object, generating an call to the error - method if an exception is raised.

      6. -

    6. Invokes the output method for the object

      7. -
    -

    Developers have the option of streaming output to a buffer via the puts method of the - reply, or simply populating the reply_body variable of the object. - The information returned by the content method is not interpreted in any way. - If an exception is thrown (via the error command in Tcl, for example) the caller will - auto-generate a 500 {Internal Error} message. - A typical implementation of content look like:

    -
    - clay::define ::test::content.file {
- 	superclass ::httpd::content.file
- 	# Return a file
- 	# Note: this is using the content.file mixin which looks for the reply_file variable
- 	# and will auto-compute the Content-Type
- 	method content {} {
- 	  my reset
-     set doc_root [my request get DOCUMENT_ROOT]
-     my variable reply_file
-     set reply_file [file join $doc_root index.html]
- 	}
- }
- clay::define ::test::content.time {
-   # return the current system time
- 	method content {} {
- 		my variable reply_body
-     my reply set Content-Type text/plain
- 		set reply_body [clock seconds]
- 	}
- }
- clay::define ::test::content.echo {
- 	method content {} {
- 		my variable reply_body
-     my reply set Content-Type [my request get CONTENT_TYPE]
- 		set reply_body [my PostData [my request get CONTENT_LENGTH]]
- 	}
- }
- clay::define ::test::content.form_handler {
- 	method content {} {
- 	  set form [my FormData]
- 	  my reply set Content-Type {text/html; charset=UTF-8}
-     my puts [my html_header {My Dynamic Page}]
-     my puts "<BODY>"
-     my puts "You Sent<p>"
-     my puts "<TABLE>"
-     foreach {f v} $form {
-       my puts "<TR><TH>$f</TH><TD><verbatim>$v</verbatim></TD>"
-     }
-     my puts "</TABLE><p>"
-     my puts "Send some info:<p>"
-     my puts "<FORM action=/[my request get REQUEST_PATH] method POST>"
-     my puts "<TABLE>"
-     foreach field {name rank serial_number} {
-       set line "<TR><TH>$field</TH><TD><input name=\"$field\" "
-       if {[dict exists $form $field]} {
-         append line " value=\"[dict get $form $field]\"""
-       }
-       append line " /></TD></TR>"
-       my puts $line
-     }
-     my puts "</TABLE>"
-     my puts [my html footer]
- 	}
- }
-
    -

    Variable

    -
    -
    variable ChannelRegister
    -
    -
    variable reply
    -

    A dictionary which will converted into the MIME headers of the reply

    -
    variable request
    -

    A dictionary containing the SCGI transformed HTTP headers for the request

    -
    -

    Delegate

    -
    -
    delegate <server>
    -

    The server object which spawned this reply

    -
    -

    Methods

    -
    -
    method constructor ServerObj ?args?
    -
    -
    method destructor ?dictargs?
    -

    clean up on exit

    -
    method ChannelRegister ?args?
    -

    Registers a channel to be closed by the close method

    -
    method close
    -

    Close channels opened by this object

    -
    method Log_Dispatched
    -

    Record a dispatch event

    -
    method dispatch newsock datastate
    -

    Accept the handoff from the server object of the socket - newsock and feed it the state datastate. - Fields the datastate are looking for in particular are:

    -

    * mixin - A key/value list of slots and classes to be mixed into the - object prior to invoking Dispatch.

    -

    * http - A key/value list of values to populate the object's request - ensemble

    -

    All other fields are passed along to the clay structure of the object.

    -
    method Dispatch
    -
    -
    method html_header title ?args?
    -
    -
    method html_footer ?args?
    -
    -
    method error code ?msg ? ?errorInfo ?
    -
    -
    method content
    -

    REPLACE ME: - This method is the "meat" of your application. - It writes to the result buffer via the "puts" method - and can tweak the headers via "clay put header_reply"

    -
    method EncodeStatus status
    -

    Formulate a standard HTTP status header from he string provided.

    -
    method log type ?info ?
    -
    -
    method CoroName
    -
    -
    method DoOutput
    -

    Generates the the HTTP reply, streams that reply back across chan, - and destroys the object.

    -
    method FormData
    -

    For GET requests, converts the QUERY_DATA header into a key/value list. - For POST requests, reads the Post data and converts that information to - a key/value list for application/x-www-form-urlencoded posts. For multipart - posts, it composites all of the MIME headers of the post to a singular key/value - list, and provides MIME_* information as computed by the mime package, including - the MIME_TOKEN, which can be fed back into the mime package to read out the contents.

    -
    method PostData length
    -

    Stream length bytes from the chan socket, but only of the request is a - POST or PUSH. Returns an empty string otherwise.

    -
    method Session_Load
    -

    Manage session data

    -
    method puts line
    -

    Appends the value of string to the end of reply_body, as well as a trailing newline - character.

    -
    method RequestFind field
    -
    -
    method request subcommand ?args?
    -
    -
    method reply subcommand ?args?
    -
    -
    method reset
    -

    Clear the contents of the reply_body variable, and reset all headers in the reply - structure back to the defaults for this object.

    -
    method timeOutCheck
    -

    Called from the http::server object which spawned this reply. Checks to see - if too much time has elapsed while waiting for data or generating a reply, and issues - a timeout error to the request if it has, as well as destroy the object and close the - chan socket.

    -
    method timestamp
    -

    Return the current system time in the format:

    -
    %a, %d %b %Y %T %Z
    -
    -
    -
    -

    Class httpd::server

    -

    ancestors: httpd::mime

    -

    Variable

    -
    -
    variable template
    -
    -
    variable url_patterns
    -
    -
    -

    Methods

    -
    -
    method constructor args ?port auto? ?myaddr 127.0.0.1? ?string auto? ?name auto? ?doc_root ? ?reverse_dns 0? ?configuration_file ? ?protocol HTTP/1.1?
    -
    -
    method destructor ?dictargs?
    -
    -
    method connect sock ip port
    -

    Reply to an open socket. This method builds a coroutine to manage the remainder - of the connection. The coroutine's operations are driven by the Connect method.

    -
    method ServerHeaders ip http_request mimetxt
    -
    -
    method Connect uuid sock ip
    -

    This method reads HTTP headers, and then consults the dispatch method to - determine if the request is valid, and/or what kind of reply to generate. Under - normal cases, an object of class ::http::reply is created, and that class's - dispatch method. - This action passes control of the socket to - the reply object. The reply object manages the rest of the transaction, including - closing the socket.

    -
    method counter which
    -

    Increment an internal counter.

    -
    method CheckTimeout
    -

    Check open connections for a time out event.

    -
    method debug ?args?
    -
    -
    method dispatch data
    -

    Given a key/value list of information, return a data structure describing how - the server should reply.

    -
    method Dispatch_Default reply
    -

    Method dispatch method of last resort before returning a 404 NOT FOUND error. - The default behavior is to look for a file in DOCUMENT_ROOT which - matches the query.

    -
    method Dispatch_Local data
    -

    Method dispatch method invoked prior to invoking methods implemented by plugins. - If this method returns a non-empty dictionary, that structure will be passed to - the reply. The default is an empty implementation.

    -
    method Headers_Local varname
    -

    Introspect and possibly modify a data structure destined for a reply. This - method is invoked before invoking Header methods implemented by plugins. - The default implementation is empty.

    -
    method Headers_Process varname
    -

    Introspect and possibly modify a data structure destined for a reply. This - method is built dynamically by the plugin method.

    -
    method HostName ipaddr
    -

    Convert an ip address to a host name. If the server/ reverse_dns flag - is false, this method simply returns the IP address back. - Internally, this method uses the dns module from tcllib.

    -
    method log ?args?
    -

    Log an event. The input for args is free form. This method is intended - to be replaced by the user, and is a noop for a stock http::server object.

    -
    method plugin slot ?class ?
    -

    Incorporate behaviors from a plugin. - This method dynamically rebuilds the Dispatch and Headers - method. For every plugin, the server looks for the following entries in - clay plugin/:

    -

    load - A script to invoke in the server's namespace during the plugin method invokation.

    -

    dispatch - A script to stitch into the server's Dispatch method.

    -

    headers - A script to stitch into the server's Headers method.

    -

    thread - A script to stitch into the server's Thread_start method.

    -
    method port_listening
    -

    Return the actual port that httpd is listening on.

    -
    method PrefixNormalize prefix
    -

    For the stock version, trim trailing /'s and *'s from a prefix. This - method can be replaced by the end user to perform any other transformations - needed for the application.

    -
    method source filename
    -
    -
    method start
    -

    Open the socket listener.

    -
    method stop
    -

    Shut off the socket listener, and destroy any pending replies.

    -
    method SubObject {} db
    -
    -
    method SubObject {} default
    -
    -
    method template page
    -

    Return a template for the string page

    -
    method TemplateSearch page
    -

    Perform a search for the template that best matches page. This - can include local file searches, in-memory structures, or even - database lookups. The stock implementation simply looks for files - with a .tml or .html extension in the ?doc_root? directory.

    -
    method Thread_start
    -

    Built by the plugin method. Called by the start method. Intended - to allow plugins to spawn worker threads.

    -
    method Uuid_Generate
    -

    Generate a GUUID. Used to ensure every request has a unique ID. - The default implementation is:

    -
    -   return [::clay::uuid generate]
-
    -
    -
    method Validate_Connection sock ip
    -

    Given a socket and an ip address, return true if this connection should - be terminated, or false if it should be allowed to continue. The stock - implementation always returns 0. This is intended for applications to - be able to implement black lists and/or provide security based on IP - address.

    -
    -
    -

    Class httpd::server::dispatch

    -

    ancestors: httpd::server

    -

    Provide a backward compadible alias

    -
    - - - -

    Class httpd::content.file

    -

    Class to deliver Static content - When utilized, this class is fed a local filename - by the dispatcher

    -

    Methods

    -
    -
    method FileName
    -
    -
    method DirectoryListing local_file
    -
    -
    method content
    -
    -
    method Dispatch
    -
    -
    -
    - -

    Class httpd::content.proxy

    -

    ancestors: httpd::content.exec

    -

    Return data from an proxy process

    -

    Methods

    -
    -
    method proxy_channel
    -
    -
    method proxy_path
    -
    -
    method ProxyRequest chana chanb
    -
    -
    method ProxyReply chana chanb ?args?
    -
    -
    method Dispatch
    -
    -
    -
    -

    Class httpd::content.cgi

    -

    ancestors: httpd::content.proxy

    -

    Methods

    -
    -
    method FileName
    -
    -
    method proxy_channel
    -
    -
    method ProxyRequest chana chanb
    -
    -
    method ProxyReply chana chanb ?args?
    -
    -
    method DirectoryListing local_file
    -

    For most CGI applications a directory list is vorboten

    -
    -
    -

    Class httpd::protocol.scgi

    -

    Return data from an SCGI process

    -

    Methods

    -
    -
    method EncodeStatus status
    -
    -
    -
    - -

    Class httpd::server.scgi

    -

    ancestors: httpd::server

    -

    Act as an SCGI Server

    -

    Methods

    -
    -
    method debug ?args?
    -
    -
    method Connect uuid sock ip
    -
    -
    -
    -

    Class httpd::content.websocket

    -

    Upgrade a connection to a websocket

    -
    -

    Class httpd::plugin

    -

    httpd plugin template

    -
    -

    Class httpd::plugin.dict_dispatch

    -

    A rudimentary plugin that dispatches URLs from a dict - data structure

    -

    Methods

    -
    -
    method Dispatch_Dict data
    -

    Implementation of the dispatcher

    -
    method uri {} add vhosts patterns info
    -
    -
    method uri {} direct vhosts patterns info body
    -
    -
    -
    -

    Class httpd::reply.memchan

    -

    ancestors: httpd::reply

    -

    Methods

    -
    -
    method output
    -
    -
    method DoOutput
    -
    -
    method close
    -
    -
    -
    -

    Class httpd::plugin.local_memchan

    -

    Methods

    -
    -
    method local_memchan command ?args?
    -
    -
    method Connect_Local uuid sock ?args?
    -

    A modified connection method that passes simple GET request to an object - and pulls data directly from the reply_body data variable in the object - Needed because memchan is bidirectional, and we can't seem to communicate that - the server is one side of the link and the reply is another

    -
    -
    -
    -

    AUTHORS

    -

    Sean Woods

    -
    -

    Bugs, Ideas, Feedback

    -

    This document, and the package it describes, will undoubtedly contain -bugs and other problems. -Please report such in the category network of the -Tcllib Trackers. -Please also report any ideas for enhancements you may have for either -package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    -
    - -

    Category

    -

    Networking

    -
    - -
    Index: idoc/www/tcllib/files/modules/ident/ident.html ================================================================== --- idoc/www/tcllib/files/modules/ident/ident.html +++ idoc/www/tcllib/files/modules/ident/ident.html @@ -1,6 +1,7 @@ - + + ident - Identification protocol client - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    ident(n) 0.42 tcllib "Identification protocol client"

    Name

    ident - Ident protocol client

    @@ -166,22 +167,16 @@ bugs and other problems. Please report such in the category ident of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/imap4/imap4.html ================================================================== --- idoc/www/tcllib/files/modules/imap4/imap4.html +++ idoc/www/tcllib/files/modules/imap4/imap4.html @@ -1,6 +1,6 @@ - + imap4 - imap client - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    imap4(n) 0.5.3 tcllib "imap client"

    Name

    imap4 - imap client-side tcl implementation of imap protocol

    @@ -119,18 +119,17 @@
  • TLS Security Considerations
  • REFERENCES
  • Bugs, Ideas, Feedback
  • See Also
  • Keywords
    • -
  • Category

    • Synopsis

    • package require Tcl 8.5
      • -
    • package require imap4 ?0.5.3?
      • +
    • package require imap4 ?0.5.2?

    TLS Security Considerations

    -

    This package uses the TLS package to handle the -security for https urls and other socket connections.

    +

    This package uses the TLS package to handle the security +for https urls and other socket connections.

    Policy decisions like the set of protocols to support and what -ciphers to use are not the responsibility of TLS, nor of +ciphers to use are not the responsibility of TLS, nor of this package itself however. Such decisions are the responsibility of whichever application is using the package, and are likely influenced by the set of servers the application will talk to as well.

    For example, in light of the recent POODLE attack discovered by Google many servers will disable support for the SSLv3 protocol. -To handle this change the applications using TLS must be -patched, and not this package, nor TLS itself. +To handle this change the applications using TLS must be +patched, and not this package, nor TLS itself. Such a patch may be as simple as generally activating tls1 support, as shown in the example below.

         package require tls
     tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
@@ -475,24 +474,15 @@
 
    This document, and the package it describes, will undoubtedly contain
 bugs and other problems.
 Please report such in the category imap4 of the
 Tcllib Trackers.
 Please also report any ideas for enhancements you may have for either
-package and/or documentation.
    
-
    When proposing code changes, please provide unified diffs,
-i.e the output of diff -u.
    
-
    Note further that attachments are strongly preferred over
-inlined patches. Attachments can be made by going to the Edit
-form of the ticket immediately after its creation, and then using the
-left-most button in the secondary navigation bar.
+package and/or documentation.
 Only a small part of rfc3501 implemented.
    -
    Index: idoc/www/tcllib/files/modules/inifile/ini.html ================================================================== --- idoc/www/tcllib/files/modules/inifile/ini.html +++ idoc/www/tcllib/files/modules/inifile/ini.html @@ -1,6 +1,7 @@ - + + inifile - Parsing of Windows INI files - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    inifile(n) 0.3.2 tcllib "Parsing of Windows INI files"

    +

    inifile(n) 0.3 tcllib "Parsing of Windows INI files"

    Name

    inifile - Parsing of Windows INI files

    Table Of Contents

      @@ -120,11 +121,11 @@

    Synopsis

    • package require Tcl 8.2
      • -
    • package require inifile ?0.3.2?
      • +
    • package require inifile ?0.3?
    • ::ini::open file ?-encoding encoding? ?access?
    • ::ini::close ini
    • ::ini::commit ini
      • @@ -201,16 +202,10 @@ bugs and other problems. Please report such in the category inifile of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Text processing

    Index: idoc/www/tcllib/files/modules/interp/deleg_method.html ================================================================== --- idoc/www/tcllib/files/modules/interp/deleg_method.html +++ idoc/www/tcllib/files/modules/interp/deleg_method.html @@ -1,6 +1,7 @@ - + + deleg_method - Interpreter utilities - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    deleg_method(n) 0.2 tcllib "Interpreter utilities"

    Name

    deleg_method - Creation of comm delegates (snit methods)

    @@ -161,22 +162,16 @@ bugs and other problems. Please report such in the category interp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/interp/deleg_proc.html ================================================================== --- idoc/www/tcllib/files/modules/interp/deleg_proc.html +++ idoc/www/tcllib/files/modules/interp/deleg_proc.html @@ -1,6 +1,7 @@ - + + deleg_proc - Interpreter utilities - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    deleg_proc(n) 0.2 tcllib "Interpreter utilities"

    Name

    deleg_proc - Creation of comm delegates (procedures)

    @@ -160,22 +161,16 @@ bugs and other problems. Please report such in the category interp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/interp/tcllib_interp.html ================================================================== --- idoc/www/tcllib/files/modules/interp/tcllib_interp.html +++ idoc/www/tcllib/files/modules/interp/tcllib_interp.html @@ -1,6 +1,7 @@ - + + interp - Interpreter utilities - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    interp(n) 0.1.2 tcllib "Interpreter utilities"

    Name

    interp - Interp creation and aliasing

    @@ -175,22 +176,16 @@ bugs and other problems. Please report such in the category interp of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    Programming tools

    Index: idoc/www/tcllib/files/modules/irc/irc.html ================================================================== --- idoc/www/tcllib/files/modules/irc/irc.html +++ idoc/www/tcllib/files/modules/irc/irc.html @@ -1,6 +1,7 @@ - + + irc - Low Level Tcl IRC Interface - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    irc(n) 0.7.0 tcllib "Low Level Tcl IRC Interface"

    +

    irc(n) 0.6.1 tcllib "Low Level Tcl IRC Interface"

    Name

    irc - Create IRC connection and interface.

    Table Of Contents

      @@ -123,12 +124,12 @@

    Synopsis

      -
    • package require Tcl 8.6
      • -
    • package require irc ?0.7.0?
      • +
    • package require Tcl
      • +
    • package require irc ?0.6.1?
    • ::irc::config ?key? ?value?
    • ::irc::connection
    • ::irc::connections
      • @@ -309,22 +310,16 @@ bugs and other problems. Please report such in the category irc of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

      -

      When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

      -

      Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    See Also

    rfc 1459

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/irc/picoirc.html ================================================================== --- idoc/www/tcllib/files/modules/irc/picoirc.html +++ idoc/www/tcllib/files/modules/irc/picoirc.html @@ -1,6 +1,7 @@ - + + picoirc - Simple embeddable IRC interface - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]
    -

    picoirc(n) 0.7.0 tcllib "Simple embeddable IRC interface"

    +

    picoirc(n) 0.5.2 tcllib "Simple embeddable IRC interface"

    Name

    picoirc - Small and simple embeddable IRC client.

    Table Of Contents

      @@ -122,15 +123,15 @@

    Synopsis

      -
    • package require Tcl 8.6
      • -
    • package require picoirc ?0.7.0?
      • +
    • package require Tcl
      • +
    • package require picoirc ?0.5.2?
    @@ -148,45 +149,24 @@

    This package is a fairly simple IRC client. If you need something with more capability investigate the irc package.

    COMMANDS

    -
    ::picoirc::connect callback nick ?password? url
    -

    Creates a new irc connection to the server specified by url and -login using the nick as the username and optionally password. -If the url starts with ircs:// then a TLS connection is -created. The callback must be as specified in CALLBACK. -Returns a package-specific variable that is used when calling other -commands in this package.

    -

    Note: -For connecting via TLS the Tcl module tls must be already -loaded, otherwise an error is raised.

    -
    -# must be loaded for TLS
-package require tls
-# default arguments
-tls::init -autoservername true -command workaround \
-    -require 1 -cadir /etc/ssl/certs -tls1 0 -tls1.1 0
-# avoid annoying bgerror, errors are already catched internally
-proc workaround {state args} {
-    if {$state == "verify"} {
-        return [lindex $args 3]
-    }
-}
-
    -
    +
    ::picoirc::connect callback nick url
    +

    Create a new irc connection to the server specified by url and +login using the nick as the username. The callback must be +as specified in CALLBACK. Returns a package-specific variable +that is used when calling other commands in this package.

    ::picoirc::post context channel message

    This should be called to process user input and send it to the server. A number of commands are recognised when prefixed with a forward-slash (/). Such commands are converted to IRC command sequences and then sent.

    ::picoirc::splituri uri

    Splits an IRC scheme uniform resource indicator into its component -parts. Returns a list of server, port, channel and secure where -secure is a boolean flag which is true if a TLS connection was -requested via the ircs:// schema. The default port is 6667 (or -6697 if secured) and there is no default channel.

    +parts. Returns a list of server, port and channel. The default port is +6667 and there is no default channel.

    ::picoirc::send context line

    This command is where all raw output to the server is handled. The default action is to write the line to the irc socket. However, before this happens the callback is called with "debug write". This permits the application author to inspect the raw IRC data and if @@ -260,11 +240,11 @@

    See Also

    rfc 1459

    Category

    Networking

    Index: idoc/www/tcllib/files/modules/javascript/javascript.html ================================================================== --- idoc/www/tcllib/files/modules/javascript/javascript.html +++ idoc/www/tcllib/files/modules/javascript/javascript.html @@ -1,6 +1,7 @@ - + + javascript - HTML and Java Script Generation - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    javascript(n) 1.0.2 tcllib "HTML and Java Script Generation"

    Name

    javascript - Procedures to generate HTML and Java Script structures.

    @@ -200,22 +201,16 @@ bugs and other problems. Please report such in the category javascript of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    CGI programming

    Index: idoc/www/tcllib/files/modules/jpeg/jpeg.html ================================================================== --- idoc/www/tcllib/files/modules/jpeg/jpeg.html +++ idoc/www/tcllib/files/modules/jpeg/jpeg.html @@ -1,6 +1,6 @@ - + jpeg - JPEG image manipulation - - -
    [ Tcllib Home -| Main Table Of Contents -| Table Of Contents -| Keyword Index -| Categories -| Modules -| Applications +| Main Table Of Contents +| Table Of Contents +| Keyword Index +| Categories +| Modules +| Applications ]

    jpeg(n) 0.5 tcllib "JPEG image manipulation"

    Name

    jpeg - JPEG querying and manipulation of meta data

    @@ -279,19 +279,13 @@ bugs and other problems. Please report such in the category jpeg of the Tcllib Trackers. Please also report any ideas for enhancements you may have for either package and/or documentation.

    -

    When proposing code changes, please provide unified diffs, -i.e the output of diff -u.

    -

    Note further that attachments are strongly preferred over -inlined patches. Attachments can be made by going to the Edit -form of the ticket immediately after its creation, and then using the -left-most button in the secondary navigation bar.

    Category

    File formats